" append an item to the workspace queue eeco adaptations <name> on|off toggle an AI-adaptation fact on or off eeco workflows [<name> on|off] list scaffolded workflows or toggle one on/off eeco show notes list the workspace notes, newest first eeco show adaptations list AI-adaptation facts with their on/off state eeco show prompt [name] list the prompt library or print one prompt body eeco refresh-manifest [<dir>] rebuild the .ai.json manifests in the knowledge dirs eeco version print the version eeco help command reference Exit codes (also the workflow contract): 0 clean · 1 finding/failure · 2 blocked (a required tool is missing) · 3 AI pass deferred (no --ai). 4a. Configuration — eeco config ─────────────────────────────── Configuration resolves in three layers, each overriding the one before it: built-in defaults → user-global ~/.config/eeco/config.local (shared by every project) → workspace <repo>/<user>/.eeco/config.local (this project only) Inspect and edit the two file layers with eeco config: eeco config list # every key, effective value, and origin eeco config get automation # one effective value, bare (for scripts) eeco config set automation=manual # write the workspace layer (this project) eeco config set --global automation=auto # write the cross-project layer set accepts key=value or key value. A value is validated against the same rules config.local uses, so a typo'd key or a malformed number is rejected before anything is written. (Floor-invariant keys such as automation tolerate any value and normalize at load, exactly as they do in a hand-edited config.local.) Sharing settings across projects — the global layer Set a key once with --global and every project inherits it, unless that project overrides it in its own workspace config.local. This is the git --global model: machine-wide defaults with per-repo overrides. The global file lives at ~/.config/eeco/config.local — or $XDG_CONFIG_HOME/eeco/config.local, or wherever EECO_CONFIG_HOME points (the override also makes the layer hermetic under tests). eeco config set --global … is the one eeco command that writes outside a repository, by design; everything else stays inside the project. It does not need an initialised workspace, or even to be inside a repo. Cockpit targets share the same model: eeco cockpit target --global add cursor # new projects inherit this target set eeco cockpit target list # falls back to the global set when this # project has no cockpit.json of its own Copying settings from one specific project — --from / import Where the global layer is a *live* shared default, --from is a *one-shot copy* from one named project into another. It carries three things — config.local, the cockpit selection (cockpit.json), and the scaffolded workflows/ — and nothing else (project-specific knowledge, state, and bug reports never travel). eeco init --from ~/other-project # bootstrap a new repo, then copy from another eeco config import ~/other-project # copy into an already-initialised project eeco config import --force ~/other-project # let the source win over existing files/keys The source path may be the other repo's root or any directory inside it. Into a fresh workspace the config.local is copied verbatim (full fidelity); into an existing one it is key-merged. Without --force, files and keys the destination already has are preserved; --force lets the source win. Importing from a project of a different type may pull in type-specific keys (profile, gate) — eeco config set fixes any you don't want. 5. Builtin workflows ──────────────────── ┌──────────────────┬──────────────────────────────────────┬─────────────────┬─────┐ │ Workflow │ Inspects │ Writes │ AI │ ├──────────────────┼──────────────────────────────────────┼─────────────────┼─────┤ │ comment-hygiene │ source/docs for tooling fingerprints │ nothing │ no │ │ leak-guard │ staged + tracked tree, commit msg │ nothing │ no │ │ version-sync │ declared version_locations │ nothing │ no │ │ gate │ the declared gate command chain │ nothing │ no │ │ bug-sweep │ code, statically │ a triage ledger │ opt │ │ handover-refresh │ code/docs/git history │ queue proposal │ opt │ │ evolve │ run history + repeated actions │ queue │ opt │ │ memory-drift │ memory facts with a ref │ queue │ no │ │ doc-drift │ CHANGELOG.md vs git tags │ queue │ no │ │ manifest-refresh │ knowledge dirs (paths + kinds) │ .ai.json │ no │ └──────────────────┴──────────────────────────────────────┴─────────────────┴─────┘ • comment-hygiene fails if any shippable file carries an AI-attribution / tooling string. • leak-guard blocks a commit that would leak an attribution string, a Co-Authored-By trailer, or a private-workspace path into tracked files. • version-sync reports drift between the version strings declared in <workspace>/config.local's version_locations list. Each entry is a path:regex pair (split on the first colon); the path is repo-relative and the regex must declare at least one capture group (group 1 captures the version string). With no version_locations entries the workflow exits 0 (the gate is opt-in per project). Use the multiline flag (?m) when the regex anchors on the start of a line further down a file — Go's ^ is start-of-string by default. Set version_locations=auto instead of an explicit list to let version-sync discover the version locations itself. In auto mode it scans a fixed, high-precision set of common version files — VERSION, CHANGELOG.md (the first ## [vX.Y.Z] heading), package.json, pyproject.toml, and Cargo.toml — and reports drift across whichever of them the project actually has. A file that is absent, or present but carrying no version-shaped string, is skipped. auto cannot be mixed with explicit path:regex entries — it is the whole list or none of it — and composes with version_anchor the same way an explicit list does. The version_anchor config key selects the source of truth declared locations are checked against. Three modes: • Unset (default) — consistency-only. The first declared location is the anchor; the rest must match it. Exits 0 when every declared location agrees, 1 when any drifts, and 2 when a declared path is missing on disk. The slice-1 behaviour, preserved for backward compatibility. • version_anchor=tag — tag-anchor. The latest semver-shaped (vX.Y.Z) tag reachable from HEAD is the source of truth. Declared locations must be semver->= the tag, so a release commit can bump declared locations ahead of the not-yet-pushed tag (the tag is pushed after the commit). Backward-drift still fails. If no semver-shaped tag is reachable yet, falls back to the consistency-only behaviour with a note in the summary. • version_anchor=<path>:<regex> — designated-file mode. Same shape as a version_locations entry; the captured version is the source of truth and every declared location must strict-equal it. A missing path exits 2 (blocked) so a typo surfaces rather than silently falling through to consistency-only. Worked example. Declare two entries that both must carry the latest released tag — the CHANGELOG.md heading and the matching footer compare-link, which often drift when a release bumps one but forgets the other — and enable tag-anchor so a release commit's bump catches a forgotten location: version_locations=CHANGELOG.md:(?m)^## \[v(\d+\.\d+\.\d+)\] version_locations=CHANGELOG.md:(?m)^\[v(\d+\.\d+\.\d+)\]: https://github version_anchor=tag Once version_locations is declared, wire the gate into the pre-commit hook so drift is caught before the commit lands rather than only under make gates: eeco hooks pre-commit on installs a .git/hooks/pre-commit that runs the default workflow chain (leak-guard + version-sync) and blocks the commit on a non-zero exit. See §9 for the override knob and the byte-identical reversal contract. • gate runs the project's declared parse/build gate — the ordered command chain in <workspace>/config.local's gate key — step by step, with the repository root as the working directory, stopping at the first failure. The gate key is repeatable: each occurrence adds one step (a whitespace-split command), and the first occurrence resets the profile default so the operator-declared chain fully replaces it. A bare single-command gate is a one-step chain; a project with no gate (the generic profile, or a lone gate=) is a clean no-op, so the gate is opt-in per project. Every step's command is checked on PATH before the first step runs, so a chain that cannot complete exits 2 (blocked); a step that exits non-zero exits 1 and stops the chain. Run it with eeco run gate, or add gate to pre_commit_workflows (§9) to run the whole validation chain before each commit. Worked example. A Go project that wants vet, a static linter, and the unit tests as one gate, run in order and stopping at the first to fail: gate=go vet ./... gate=staticcheck ./... gate=go test ./... • bug-sweep does a static read and maintains an append-only triage ledger (open findings → resolved log); with --ai it performs the reasoning pass, otherwise it reports and parks the prompt. • handover-refresh drafts a dated handover plus a "what's now dead" diff and queues it for your approval — it never overwrites a note directly. • evolve watches for repetition and *proposes* new workflows into the queue. It never activates one on its own. The proposal pass is two-stage: a deterministic signal extraction scans the most recent 40 commit subjects for repeated conventional-commit types (<type>(<scope>)?!?: …) and surfaces one workflow candidate per type that appears at least three times (cap five candidates per run, sorted count-desc then key-asc). Each candidate becomes its own evolve queue item — the operator resolves or dismisses one at a time. The gated AI pass becomes optional enrichment layered on top: --ai (or automation=auto) opts into it; on no consent or any provider skip eeco still exits 0 when the deterministic pass found at least one candidate, and only preserves the exit-3 (AI deferred) contract when there is genuinely nothing to report — no consent and no deterministic candidates. It also maintains a repetition ledger at <workspace>/state/evolve-history.json. Each surfaced candidate writes one record (signal kind + key, count at proposal, the queue row's kind + title, the proposal timestamp); a re-run suppresses any candidate whose (signal_kind, signal_key) is already in the ledger, so a recurring signal is proposed exactly once in its lifetime even after the queue item is ticked. Each run also reconciles unresolved records against the queue: a record whose queue row is now checked flips to resolved: true with a resolved_at timestamp. Reconciliation runs once per evolve invocation — the queue is not watched live, so an operator who ticks a row between runs sees the ledger update on the next eeco run evolve. The re-propose-on-signal-recurrence knob is a follow-on slice; today a resolved record still suppresses. A future slice may add a file-touch signal alongside the commit-type one (deferred because it needs a new gitx helper). • memory-drift flags a memory fact whose ref: file has been committed on a later calendar day than the fact's own created: date — a sign the fact may now describe code that has moved on. eeco gc already catches a ref: that no longer exists on disk; memory-drift catches the complementary case where the file is still there but has changed since the fact was written. One review item per stale fact is routed to the queue — eeco flags the drift, you reconcile the fact. It needs git on PATH (it exits 2, blocked, without it) and exits 0 when every ref-carrying fact is still current. Run it with `eeco run memory-drift`, or wire it to run automatically after a merge with the post-merge hook (§9), where it is in the default workflow list. • doc-drift flags drift between the release sections in CHANGELOG.md and the project's git tags. Two cases: a vX.Y.Z git tag with no ## [vX.Y.Z] CHANGELOG section (a release that was never documented), and a ## [vX.Y.Z] section with no matching tag (a release documented but never tagged). The newest section is exempt: a release commit adds the ## [vX.Y.Z] heading before the vX.Y.Z tag is pushed, so a section strictly ahead of the latest tag is the expected release-in-progress state, not drift. One review item per drift is routed to the queue — eeco flags it, you reconcile the CHANGELOG.md or the tag. It needs git on PATH (it exits 2, blocked, without it) and exits 0 when CHANGELOG.md is absent, no tags exist yet, or every tag and section agree. Run it with `eeco run doc-drift, or let the post-merge` hook (§9) run it automatically — it is in that hook's default workflow list alongside memory-drift and manifest-refresh. • manifest-refresh rebuilds the per-directory .ai.json manifests across the knowledge dirs — the project-type directories scaffolded under <repo>/<owner>/ as siblings of the engine workspace. Each manifest is a deterministic skeleton — a JSON document `{"dir", "purpose"?, "items":[{"path","kind"}…]} with kind either "file"` or "dir", sorted by path; the optional desc/find_when fields are reserved for a future enrichment pass and stay empty in the deterministic walk. The .ai.json file is skipped in its own walk, so a re-run over unchanged dirs reproduces byte-identical output. Writes land in the gitignored per-user area, never the tracked tree; it needs no AI and never blocks. Run it on demand with `eeco refresh-manifest [<dir>]` (the same deterministic rebuild, optionally scoped to one knowledge dir), or let the post-merge hook (§9) run it. Run any of them from the TUI or eeco run <name>. These ten are the complete builtin set. Additional builtin workflows are tracked as a post-v0.1.0 item. Scaffolding a workflow with eeco new eeco new <name> scaffolds a user workflow under <workspace>/workflows/<name>/ from a per-profile template. The scaffold layout is picked from the project's detected profile: • go profile — run PATH-checks go and runs go vet ./... as the inert default. • python profile — run PATH-checks python3 and runs python3 -m compileall -q . as the inert default. • generic profile (and any profile without a dedicated template: zig, rust, node) — run is a bare sh stub that prints a placeholder line and exits 0. In every case the scaffolded run is a starting point — replace the default body with the real check this workflow is meant to perform. The chosen template is internal to eeco; the verb shape `eeco new <name>` is unchanged. Toggling a scaffolded workflow on or off Once scaffolded, a workflow is on by default; eeco runs it whenever it is asked to (a manual eeco run <name>, a hook chain that names it, the TUI). To pause a workflow without deleting it: eeco workflows <name> off # mark <name> as disabled eeco workflows <name> on # bring <name> back online eeco workflows # list every scaffolded workflow + state off plants an empty sentinel marker file at <workspace>/workflows/<name>/disabled; the loader sees it and reports the workflow as blocked (exit 2) without running it. on removes the marker. Repeating the same action is a clean no-op. Builtin workflows are unaffected by this toggle — their contract is part of the frozen public surface. To remove a scaffolded workflow for good, delete its directory. 6. Memory and garbage collection ──────────────────────────────── The store holds one fact per file (flat frontmatter: name, description, type, dates, optional ref:/expires:, pin:), with a regenerated MEMORY.md index and [[links]] between facts. Types: user, feedback, project, reference, finding. eeco gc (or the Memory screen) keeps the store honest: • a memory whose ref: path is gone, that has expired, a resolved finding, or an unused reference past the stale window is archived to the recoverable attic; • anything load-bearing (project/feedback/user) is **queued for your decision**, never silently deleted; • pin: true exempts a fact permanently. This is automated and conservative — the algorithm never loses a fact that still matters; it asks you instead. Re-running eeco gc (for example through the post-merge hook chain) no longer files duplicate gc-review items for an unresolved finding: an open queue row for the same fact + reason is recognised and the second filing is skipped. Resolving the row (checking its box) lets a future trigger file again, so the queue is never wedged on a stale recommendation. eeco add fact records a fact without hand-authoring the frontmatter: eeco add fact --description "<summary>" [--type <type>] [--name <slug>] [--ref <path>] [--pin] [--provenance <text>] [--agent <name>] "<body>" It writes one frontmatter file under <workspace>/memory/ and regenerates MEMORY.md. --description is the one-line summary that drives relevance matching and is required. --type is one of user, feedback, project, reference, finding and defaults to project — the safe default, since project/user/feedback facts are queued for review rather than archived. --name is the lower-kebab-case filename stem; when omitted it is derived from --description. --ref records a repo-relative path the fact documents (garbage collection validates it); --pin exempts the fact from collection. --provenance "<text>" records the snippet that triggered the fact (source: in frontmatter, capped at 120 characters); --agent <name> records which assistant filed it (agent:). Both are **required for --type feedback and --type user** — those types are durable adaptations to the operator, and an unauthored adaptation is the silent drift eeco show adaptations exists to surface. Hand-authored facts remain permissive: an older fact file without the new fields still loads. eeco refuses to overwrite an existing fact — pass a different --name, or edit the file directly. The command needs an initialised workspace; it writes only inside it (Constraint 1) and never stages or commits (Constraint 6). Editing a fact later is `$EDITOR <workspace>/memory/<name>.md; removing one is rm`. Auditing AI adaptations A feedback- or user-typed memory fact is a durable adaptation to the operator — every future assistant briefed by eeco go honours it. eeco show adaptations lists every adaptation newest-first with its provenance and on/off state, so the operator can audit *what the AI is doing automatically now* without grepping the memory directory: eeco show adaptations eeco adaptations <name> on|off flips a disabled: flag on one fact in place and regenerates the MEMORY.md index so the change shows at once. A disabled fact is preserved on disk but hidden from eeco go briefs and eeco ask rankings, so re-enabling is one CLI flip: eeco adaptations terse-feedback off # mute it without deleting eeco adaptations terse-feedback on # restore it eeco gc skips disabled facts so a deliberately muted adaptation never gets routed for staleness review. A disabled fact is hidden from the AI-facing surfaces (eeco go, eeco ask, the TUI relevance ranker) but stays **visible — marked — on the human audit surfaces**: the regenerated MEMORY.md index lists it under a ## disabled heading, and the TUI /memory screen tags its line [off]. This holds for a fact of any type, so a disabled project or reference fact is never silently lost from view. eeco show adaptations is the audit surface; the fact file under <workspace>/memory/<name>.md is the source of truth. Constraints 1 + 6 hold (writes inside the workspace; nothing staged or committed). 7. The queue — the only thing that interrupts you ───────────────────────────────────────────────── Workflows and GC never act unilaterally on a meaningful change. They append an item to the queue. View it with eeco queue (or /queue in the TUI); the status digest shows the open count. The queue file is yours — you resolve an item by ticking its checkbox ([ ] → [x]) or deleting the row in <workspace>/state/queue.md. Nothing else nags you; nothing runs unless you invoke it. You can also file a queue item yourself — or have an assistant file one for you — with eeco add task: eeco add task "wire the man page into brew/scoop" eeco add task --kind review --detail "check the brew formula" "audit packaging" The title is the checklist row; --kind is the short queue tag (default task); --detail is an optional elaboration printed beneath the row. The item is appended to <workspace>/state/queue.md and shows up alongside workflow- and GC-filed items in eeco queue (or /queue) and the status digest's queue count. eeco add task writes only inside the workspace (Constraint 1) and never stages or commits (Constraint 6); it requires an initialised workspace. Like eeco add fact, it closes the read/write loop — an assistant briefed by eeco go can route a decision back into eeco's one decision channel instead of letting it evaporate. 8. AI configuration ─────────────────── AI is opt-in (--ai, or an automation level that grants standing consent) and budget-capped. eeco no longer runs an in-binary model client — it configures the harness that runs the AI. The one inference path it keeps for its own chores is a CLI provider that shells any program of your choice (prompt on stdin, reply on stdout); with none configured, every AI pass is parked, never failed. Configure in <workspace>/config.local, or set the common keys from the control center with /settings: automation = propose # manual | propose | scaffold | auto ai_budget = 1 # gated passes per invocation; 0 disables AI # CLI provider — any program, prompt on stdin, reply on stdout: ai_command = yourcli --print ai_provider = cli # cli | none; empty/unknown auto-selects • Auto-select (default). With ai_provider empty or unset — or an unknown/legacy value such as anthropic — a configured ai_command picks the CLI provider; otherwise every AI pass is **parked and queued**, never failed — the deterministic, non-AI result still stands. ai_provider = none is also accepted; nothing here is ever a config error. • ai_model and ai_api_key_env are inert legacy keys: read and passed through, but ignored by the CLI provider (there is no native API path). They stay only so an old config.local loads unchanged. • Only automation=auto is itself standing AI consent; every other level needs an explicit --ai on the run. • The same gating — consent, budget cap, and prompt-parking — wraps every provider call, so a run is always safe and never an uncontrolled spend. Every attempt is recorded to the AI-call ledger (state/ai-calls.json): label, provider, resolved model, prompt and response hashes, and token usage. /settings (no arguments) shows the current values; `/settings <key> <value> writes one to config.local`. A change applies the next time eeco starts; a long-lived session keeps the budget cap it began with. Cumulative AI usage — eeco stats eeco stats aggregates that ledger (state/ai-calls.json) into a one-glance readout of how much AI eeco has actually used on this project: eeco stats eeco stats: 12 AI calls (9 ran, 3 parked) from 2026-05-21 to 2026-05-30 tokens: 18432 input · 4096 cached · 6210 output (28738 total) by provider: cli 9 · none 3 It reports the total number of gated AI calls, how many actually ran versus were parked, the cumulative token counts, the per-provider call breakdown, and the recorded date range. Unlike eeco go --metrics, whose token figures are bytes/4 estimates marked with ≈, these token totals are the real provider counts the ledger stored, so they carry no ≈. The command is read-only and makes no AI call; an uninitialised workspace or an empty ledger reports `no AI calls recorded yet` and still exits 0. The exact wording and the displayed figures are a human-readable readout and are not part of the frozen surface. 9. Hooks (opt-in, reversible) ───────────────────────────── Off by default. Inspect with eeco hooks (or /hooks); toggle with eeco hooks <name> on|off (or /hooks <name> on|off). Names: pre-commit, post-merge, session-start, commit-msg, commit-guard. • pre-commit — a local .git/hooks/pre-commit (untracked, repo-scoped) that runs the configured builtin workflows in declared order and stops at the first non-zero exit, blocking the commit when any step fails. Defaults to leak-guard (blocks a leaking commit) followed by version-sync (silent on projects that have not declared version_locations, so opt-in per project). Override the list with one or more pre_commit_workflows keys in config.local; the first occurrence resets the binary default, subsequent occurrences append. An empty pre_commit_workflows= value clears the list and `eeco hooks pre-commit on` refuses to install. The hook is installed only if no pre-commit hook already exists, and removed only when the on-disk script is byte-identical to what eeco wrote; a foreign or hand-edited hook is always left untouched. After upgrading the eeco binary (for example a brew upgrade that moves the binary) or editing pre_commit_workflows, run eeco hooks pre-commit refresh to rewrite the installed script with the current binary path and workflow set. • post-merge — a local .git/hooks/post-merge (untracked, repo-scoped) that runs the configured drift-detection workflows after a git merge / git pull — the moment another author's changes land, the natural time to re-check whether eeco's recorded state has drifted from the code. Defaults to memory-drift followed by doc-drift (both silent no-ops on a project with no memory ref: facts and no CHANGELOG/tags). Unlike pre-commit it does not block: the merge has already completed, so a finding or a missing tool surfaces as a queue item, never as a hook failure (each step's exit is swallowed and the hook does not use set -e). The drift workflows file at most one open queue item per finding — a repeated run does not pile up duplicates of a finding still awaiting a decision. Override the list with one or more post_merge_workflows keys in config.local (same reset-then-append semantics as pre_commit_workflows; an empty post_merge_workflows= clears the list and eeco hooks post-merge on refuses to install). Install / removal / refresh behave exactly as for pre-commit: a foreign or hand-edited hook is always left untouched. • session-start — composes up to three blocks at session start and stays silent when every block is empty: 1. A reading routine — repo-relative paths to read before substantive work. Auto-detected from a built-in list (docs/PUBLIC_API.md, docs/ARCHITECTURE.md, CHANGELOG.md, ARCHITECTURE.md, docs/USAGE.md, README.md); existing entries surface, missing ones are skipped. The most-recently-modified match of roadmap*.md is appended as the live planning surface. Override the doc list with one or more session_start_docs keys in config.local; change the roadmap pattern with session_start_roadmap_glob (empty disables discovery). 2. A mailbox warning — surfaces when Ideas.md at the repo root has content beyond its empty template (the parser skips the file header and any HTML comment blocks). Change the filename with session_start_mailbox in config.local; an empty value disables the block. The hook does not create the file — it surfaces only when the operator opted in by creating it. 3. A one-line queue reminder — eeco: N items awaiting a decision when the queue is non-empty. 4. (opt-in) Pinned memory bodies — the full body of every pin: true memory fact under <workspace>/memory/, separated by Markdown dividers. Off by default, so the hook output is byte-identical until enabled. Opt in via session_start_pinned_bodies=true in config.local (workspace default) or the --with-pinned-bodies flag on eeco hooks session-emit (one invocation only). Useful when an AI assistant treats the hook output as a system-reminder so a pinned policy memory (for example a no-AI-attribution rule) lands in the model's context at session start. The session-start hook ships with two brand-free delivery channels; use either alone or compose both: • JSON settings file — an exact-match-removable entry in an AI CLI's user-global JSON settings file (the Claude Code shape). Set the file location with session_settings_path in config.local or the EECO_SESSION_SETTINGS environment variable. The file is backed up (inside the workspace) before the edit and re-validated after; an invalid result is rolled back. • Marker block in a text/markdown file — eeco maintains a delimited block of the same content the JSON channel renders, in one or more files the assistant already reads at session start (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, AGENTS.md for OpenAI Codex, .cursorrules for Cursor, ~/.config/<tool>/..., etc.). Declare one path per session_files= line in config.local; each value is either repo-relative (held inside the repo) or absolute. The block is fenced by HTML comments —  /  — and replaces in place on re-on or refresh. The block content is whatever eeco hooks session-emit prints. eeco never edits bytes outside the marker pair, and a block whose contents have been hand-edited since install is left untouched on off. Files eeco itself created are removed when off would leave them empty; files that already existed are restored byte-identical to their pre-on state when the block is at end-of-file. Neither channel is configured by default: `eeco hooks session-start on` reports "not configured" until at least one of the two is set. When the file channel is wired, run eeco hooks session-start refresh to re-render the block — the JSON channel does not need it (it carries a command eeco runs at session start, so it is always fresh). • commit-msg — a local .git/hooks/commit-msg (untracked, repo-scoped) that rejects commit messages carrying an AI-attribution trailer. The policy is universal and lives inside the eeco binary: the on-disk script is a one-line wrapper that execs eeco hooks commit-msg-check "$1", so the pattern set refreshes with every brew upgrade eeco. Matches the trailer-anchored forms (Co-Authored-By: lines naming claude, anthropic, or noreply@anthropic) plus the Claude Code robot-emoji (U+1F916) "Generated-with" signature; deliberately stricter than the broad repo-tree scan so a docs commit that *discusses* the policy ("remove Co-Authored-By trailer") still passes. Exit code 1 prints the matched line and names --no-verify explicitly as the bypass; conscious overrides remain available without surprise. Install / removal behave exactly as for pre-commit and post-merge: foreign hooks are never modified. After a brew upgrade eeco rewires the eeco binary path, run `eeco hooks commit-msg refresh` to rewrite the on-disk wrapper without an off-then-on toggle. • commit-guard — the harness-layer companion to commit-msg. Where the git commit-msg hook guards eeco's own repository, the commit-guard installs a Claude Code PreToolUse hook that denies any pending git commit carrying AI attribution — in any repository the assistant drives, and not bypassable by git commit --no-verify (the hook sits above git). It runs the same attribution detector leak-guard uses, so the patterns stay one source of truth (the foreign repo's own attribution_pattern entries are honoured when its config loads). Default off; enable with eeco hooks commit-guard on, which installs a PreToolUse group into the JSON settings file named by session_settings_path (or EECO_SESSION_SETTINGS) — the same file the session-start JSON channel uses, backed up and re-validated the same way; it reports "not configured" when neither is set. The runner detects a real git commit token-by-token (so git status and echo "git commit" never fire), scans the assembled message (-m/-F/COMMIT_EDITMSG), the staged diff, and the raw command, and **denies only on a positive finding — any parse or infrastructure uncertainty degrades open** (the commit proceeds), so a session is never wedged; the git pre-commit / commit-msg hooks and CI remain the hard gates. off removes only eeco's group (foreign PreToolUse groups are preserved); after a brew upgrade eeco run eeco hooks commit-guard refresh to rewrite the binary path. Every action is recorded in <workspace>/state/hooks.json so it can be cleanly undone. The git-hook scripts and the JSON-settings writes — the session-start and commit-guard entries plus any session_files blocks — are the only touches eeco ever makes outside the gitignored workspace. 9a. Gates — composed read-only policy checks ──────────────────────────────────────────── eeco gates check-attribution is a CI-facing companion to the commit-msg hook (§9). The hook blocks at the source on a developer machine; the gate is the CI backstop that catches a leak when a developer bypassed the hook (--no-verify) or never installed it. Both share the same trailer-anchored pattern set so prose discussing the policy never false-fires. Scope: • Tracked-file scan — broad: delegates to the same detector comment-hygiene uses (line-anchored Co-Authored-By:, the Generated with/by <ai-ish> co-marketing line, and the robot-emoji Generated signature). Enumerates the file list from git ls-files and filters to a built-in text-extension allowlist (.md, .sh, .go, .zig, .S, .inc, .zon, .yml, .yaml, .txt, .ld, .json, .toml). Hits print as path:line: excerpt. • Commit-body scan — strict trailer-anchored: Co-Authored-By: lines naming claude, anthropic, or noreply@anthropic, plus the robot-emoji "Generated" signature. Default range is origin/main..HEAD; falls back to HEAD~10..HEAD with a stderr notice when origin/main is unresolvable (fresh clone, detached HEAD, initial commit). Hits print as `commit <short-sha>: line N: excerpt`. Flags (all optional): ┌───────────────────┬───────────────────────────────────────────────────────────────────────────┐ │ Flag │ Effect │ ├───────────────────┼───────────────────────────────────────────────────────────────────────────┤ │ --paths "<a b c>" │ override the tracked-files filter; pass an explicit space-separated list. │ │ --commits N │ force HEAD~N..HEAD instead of the default range. │ │ --no-commits │ skip the commit-body scan (file-only). │ │ --no-files │ skip the file scan (commits-only). │ │ --exclude <path> │ repeatable; repo-relative path to skip during the file scan. │ └───────────────────┴───────────────────────────────────────────────────────────────────────────┘ Exit codes: 0 clean, 1 on any hit (sets stderr with one line per finding plus a N finding(s) summary), 2 on usage error. The CI invocation pattern is one step before git push-eligible builds: - name: ai-attribution gate run: eeco gates check-attribution Use actions/checkout@v5 with fetch-depth: 0 so the commit-body range resolves; default 1 makes origin/main..HEAD empty and the fallback notice triggers. 10. Safety guarantees ───────────────────── • eeco writes only inside the repo's gitignored workspace; a path guard enforces this and refuses .. traversal. • It never commits or pushes your project's tracked tree. The optional private workspace-history repo (see §11a) commits only inside the gitignored workspace, locally, and is never pushed. • No AI-attribution string is ever written to a tracked file. • Everything it does is invoked by you or queued for you. 11. Removing eeco from a project ──────────────────────────────── eeco uninstall writes a single eeco-handoff.md at the repository root summarising what eeco knew about the project, then prints the git command to remove the workspace by hand. It never deletes anything itself, so nothing is lost if you change your mind. eeco uninstall # bare handoff (just paths + removal command) eeco uninstall --scope facts # + memory facts eeco uninstall --scope queue # + open queue items eeco uninstall --scope everything # + facts + queue + scaffolded workflows + hooks The handoff file is written at the repository root, alongside your tracked tree; the file itself is not gitignored, so you choose whether to keep, commit, or delete it. The workspace is gitignored, so a single git rm -rf .eeco (substitute your workspace name) is the only on-disk removal needed once the handoff has been reviewed. Turn opt-in hooks off first (eeco hooks pre-commit off, eeco hooks session-start off) so the reversibility ledger can do its work before the workspace goes. If the private workspace-history repo exists (§11a), eeco uninstall offers to de-init it — removing only its .git, never your data — after a confirmation prompt. Pass --yes to skip the prompt, or decline to keep the history and remove it yourself later. Your workspace data files are never deleted by eeco uninstall. 11a. Workspace history (the private logbook) ──────────────────────────────────────────── At eeco init, eeco stands up a **private, local git repository inside its own gitignored workspace directory** (<username>/) to version its knowledge layer — memory facts, the queue, decisions, manifests — over time. This repository has no remote and is never pushed, and it never touches your project's tracked tree: it records only what eeco already writes inside its own gitignored workspace, so it is invisible to your project's git. The workspace_history config key controls it: • manual (default) — the repo exists; eeco commits only when you run eeco history snapshot. • auto — as manual, plus eeco commits automatically after each mutating verb (add fact/note/task, gc, go --write, run, new, …); still local-only, no remote. • off — no private repo at all. eeco init # creates the private repo (manual) eeco init --no-track # skip it for this run eeco history # show the recent commit log eeco add note "decided X" # mutate the workspace eeco history snapshot # commit the current state eeco history snapshot -m "milestone" # …with a message eeco history compact --dry-run # preview: how many commits would collapse eeco history compact # squash the whole log into one (confirms first) eeco history compact --yes # …without the prompt Under auto the log grows a commit per mutating verb, so it can get long. eeco history compact squashes the entire history into a single commit whose contents are the current workspace state — the git pendant to the docs-compaction protocol. Your workspace files are never touched (only the commit log is collapsed), and the old commits stay reachable through the git reflog, so the squash is recoverable; eeco runs no git gc. It is manual only — there is no auto-trigger — and it confirms before rewriting unless you pass --yes; --dry-run reports the count and changes nothing. The repo is created opt-out (--no-track for one run, or workspace_history=off durably) and removed at eeco uninstall (§11). Inside it eeco has a free hand — commit, and later squash — because nothing there is shared or tracked by the host repo. 12. Filing bug reports ────────────────────── eeco report-bug captures friction with eeco itself into a structured Markdown record and prints a pre-filled GitHub Issues URL so the report can reach the project in one click. The command works for everyone: anyone who installed eeco can file, with or without an initialised workspace. eeco report-bug --note "leak-guard tripped on a doc-only commit" \ --cmd "eeco run leak-guard" Both flags are optional. The record contains the eeco version, a whitelisted environment snapshot (OS, arch, Go version, SHELL, TERM, and any EECO_* variables — never the full env), the note, and the invoking command. Where the record lands: • Inside an initialised workspace. Records go to <workspace>/bug-reports/; override the directory with the bug_report_dir key in <workspace>/config.local (workspace- relative — absolute paths and .. traversal are rejected at parse time). • Anywhere else (no eeco init yet, or not inside a git repo at all). Records go to ~/.eeco/bug-reports/ so a fresh-install user can file a report against eeco itself without having to set anything up first. The repo's tracked tree is never touched. Sharing the record: eeco report-bug prints a pre-filled URL like https://github.com/ajhahnde/eeco/issues/new?title=...&body=.... Opening it in a browser fills the issue form with the record body already pasted — clicking Submit files it to the project. The local file is your durable copy; you can refine it before clicking, or attach it by hand if the URL ends up too long for the browser. Nothing is sent automatically — the upstream side of the loop is always a human click. Pass --submit to have eeco open that URL for you (the $BROWSER command if set, otherwise the platform default opener). It is opt-in and changes nothing else: the form opens pre-filled, you still review and click Submit, and the command still reports that nothing was sent automatically — opening a pre-filled form is not the same as sending. If no browser can be opened, the command prints a short note alongside the URL and still exits 0; --submit is a convenience, never a failure point. 13. Briefing an AI assistant ──────────────────────────── eeco go prints a compact, deterministic project brief written for an AI assistant. It is the fast, cheap way to bring any assistant — not only the strongest — up to speed on a project: one command returns a map of the project instead of a scan across many files. eeco go The brief has six sections: • Working with eeco — what eeco is, the read-only commands an assistant can run, and the rule that decisions go to eeco's queue rather than silent edits. • Project — the detected profile, the parse/build gate, and the top-level layout (taken from the tracked set, so build artifacts and the workspace stay out). • Where to look — every memory fact that records a file pointer, as a topic → file map. This is the assistant's shortcut to the right file. • What eeco knows — the load-bearing memory facts (project, feedback, user). • Open decisions — the items waiting in eeco's queue. • Recording back — how the assistant keeps the brief useful: record durable facts and route decisions through the queue. eeco go calls no AI provider — the brief is assembled entirely from what eeco already tracks, so it costs no provider budget and is safe to run any number of times. The output is deterministic: the same workspace state produces the same brief. The brief is Markdown by default — written for an assistant to read. The --json flag emits the same project state as a JSON object instead, the machine-readable form for a downstream agent or script that parses the brief rather than reading it: eeco go --json The JSON object has nine top-level keys — project, profile, gate (an argv array), top_level, initialized, workflows, where_to_look (description/ref objects), knowledge (name/description/type objects), and open_decisions. Every array is always present, an empty list rather than null, so a consumer can iterate without a nil check. These top-level keys are part of eeco's frozen public surface. --json prints to stdout and cannot be combined with --write. By default the brief is printed to stdout and nothing is written. The --write flag saves it instead to a stable file inside the workspace — .eeco/context.md by default — so an assistant's instructions file can point at a fixed path rather than re-running the command each session: eeco go --write # writes .eeco/context.md The destination is workspace-relative; override it with the context_path key in <workspace>/config.local (absolute paths and .. traversal are rejected). --write requires an initialised workspace, and the file it writes is byte-identical to the stdout brief. The file lives in the gitignored workspace, so it is never committed; re-run eeco go --write whenever you want it refreshed. For an assistant on a tight context budget the --brief flag reshapes the output: the "Working with eeco" preamble and "Recording back" outro drop out, and the per-section lists (Where to look, What eeco knows, Open decisions) are capped at five entries each. --brief composes with --json and --write, so every delivery axis gets the size knob: eeco go --brief # smaller Markdown brief eeco go --brief --json # smaller JSON brief eeco go --brief --write # writes the smaller variant In --brief --json the nine frozen top-level keys are preserved — arrays may simply be shorter, never absent or null — so a consumer that parses the JSON brief sees the same shape, never an unexpected key disappearance. To keep the persisted .eeco/context.md under a known size, set the context_budget key in <workspace>/config.local to a maximum byte count (roughly four bytes per token is a useful rule of thumb): context_budget=4000 # cap the --write brief at 4000 bytes When context_budget is set, eeco go --write trims the saved brief down a deterministic ladder until it fits: it tries the full brief first, then the smaller --brief form, then that form with the per-section lists capped progressively shorter (5, 4, 3, 2, 1, 0). It writes the largest tier that fits and reports which one — for example wrote .eeco/context.md (brief, 1840/4000 bytes). A context_budget of 0 (the default) means no cap. The budget applies only to --write; bare eeco go and eeco go --brief printed to stdout are unchanged. If the budget is so small that even the smallest tier overruns it, eeco still writes that smallest brief and prints a note — a brief slightly over budget beats no brief at all. To surface the recent free-form notes from eeco add note (§17) inside the brief, set the brief_include_notes key in <workspace>/config.local: brief_include_notes=true When enabled, eeco go adds a Recent notes section between What eeco knows and Open decisions, listing the five newest notes from <workspace>/notes/ with their UTC timestamp and first line. The section appears in Markdown output only — eeco go --json still emits exactly the nine frozen top-level keys (PUBLIC_API.md (PUBLIC_API.md) §"CLI commands and flags"), since notes belong to the assistant-prose channel rather than a parsed brief. The key accepts the standard strconv.ParseBool set — true/false, 1/0, t/f (in either case); a typo like yes/no is rejected at parse time so the operator notices. The default is false, so bare eeco go omits the section; the key composes with --brief, --write, and --copy exactly like the other sections. To wire the brief into a session, either point your assistant's instructions file at .eeco/context.md, or — if you use the bundled session-start hook (§9) — add session_start_docs=.eeco/context.md to config.local so the hook lists it in the reading routine automatically. Any assistant that can read a file or run a shell command can consume the brief; eeco assumes no particular tool. For a chat-only assistant — Gemini web, a Gem, AI Studio, ChatGPT, or any LLM behind a chat box — the --copy flag writes the brief to the host operating system's clipboard so you can paste it in one shot: eeco go --copy # full Markdown brief on the clipboard eeco go --copy --brief # smaller brief for a tight context window eeco go --copy --json # structured payload for a chat that parses JSON --copy works on macOS (pbcopy), Windows (clip.exe), and Linux (wl-copy on Wayland, xclip or xsel on X11). When none of those tools is on PATH eeco exits 2 with an install hint — the same "blocked: required tool missing" contract every other workflow follows. --copy does not compose with --write (one delivery axis per invocation); it does compose with --brief and --json. Re-run eeco go --copy whenever the project state has moved on. Measuring the brief — --metrics The --metrics flag adds a one-line readout to stderr after the brief, so you can see what the brief actually saved: eeco go --metrics eeco go: assembled in 412µs · brief 1840 bytes (≈460 tokens) · distilled ≈980 tokens of project knowledge into ≈460 (≈53% smaller) It reports three things: how long the brief took to assemble (real wall-clock), the brief's own size, and how much of the project's knowledge layer — the on-disk memory facts, the queue, and any notes — the brief distils. Byte counts are real measurements; token figures are estimates via the ~4-bytes-per-token heuristic and are marked with a leading ≈, never presented as exact counts (eeco ships no tokenizer, by design). The compression percentage is grounded in real on-disk bytes and is never reported below 0%. The readout goes to stderr, so it never mixes into the brief itself: eeco go --metrics > brief.md writes a clean brief to the file and prints the readout to the terminal. It always describes the **canonical Markdown brief** — even alongside --json or --copy, where it measures the Markdown brief the assistant would read — and it never appears in --json stdout, so the nine frozen top-level keys (PUBLIC_API.md (PUBLIC_API.md) §"CLI commands and flags") are untouched. With --write under a context_budget the readout still describes that canonical brief, not the budget-trimmed file that was persisted — the metric measures how much eeco's brief compresses the knowledge layer, a stable property, rather than one write's fitted size. --metrics is off by default and composes with every other flag. Briefing assistants other than Claude Code eeco's delivery channels are brand-free — point them at whichever assistant you use: • Gemini CLI (Google's terminal-native assistant) reads GEMINI.md at session start. Set session_files=GEMINI.md in <workspace>/config.local, then eeco hooks session-start on. Same recipe as Claude Code with CLAUDE.md. • OpenAI Codex reads AGENTS.md. Set session_files=AGENTS.md. • Cursor reads .cursorrules. Set session_files=.cursorrules. • Any other assistant whose instructions file lives at a known path: add that path as a session_files= line and eeco will keep a marker block in it (§9). For an assistant with no terminal and no filesystem access (Gemini web, Gems, AI Studio, ChatGPT, any chat box), eeco go --copy is the one-shot bridge — render the brief into the clipboard and paste it into the chat. Re-run when the project state moves on. Asking a targeted question Where eeco go is a one-shot overview, eeco ask answers a *specific* question with a ranked set of pointers — the interactive counterpart to the static brief: eeco ask "where is the project brief rendered" The answer has two sections: Memory — the memory facts whose name, description, or body overlaps the question, shown as a topic → file map when the fact carries a ref; and Code — the best-matching lines in the repository's tracked files, each as a path:line reference with the matching line. Results are ranked by how many distinct question words they match, with stable tie-breaks, so the same question over the same tree always gives the same answer. eeco ask --limit 3 "how does version-sync detect drift" # cap code hits eeco ask --json "queue" # machine-readable --limit N caps the number of code locations (default 10); every matching memory fact is always shown. --json emits an object with three frozen top-level keys — question, memory, code — both arrays always present, never null. Like eeco go, eeco ask calls no AI provider (relevance is a word-overlap score over what eeco already tracks), reads anywhere in the repo but writes nothing, and works in any git repository — the memory section is simply empty when the workspace is not initialised. Binary and very large files are skipped. 14. Applying an update ────────────────────── eeco update checks for a newer release and prints the gap, but does not download anything. The opt-in --apply flag turns it into a verified self-replace: download the platform release archive, verify its sha256 against the published SHA256SUMS, verify the cosign signature on SHA256SUMS, verify the GitHub build-provenance attestation on the archive, then atomically swap the running binary. eeco update --apply Verification gates. All three must pass before any swap. Any one failure leaves the running binary untouched and leaves the downloaded files in <workspace>/state/update-<tag>/ for inspection. • cosign verify-blob against the keyless certificate identity baked into the release workflow (refs/tags/v… on this repo). • sha256 of the downloaded archive equal to its line in SHA256SUMS. • gh attestation verify <archive> --repo ajhahnde/eeco. Requirements. cosign and gh must be on PATH. The command must run inside an initialised eeco workspace — <workspace>/state/ holds the staging directory, the backup, and the swap ledger (<workspace>/state/binary.json). The running binary must be on a released tag (v…); an unpinned 0.0.0-dev build refuses with a reinstall hint. Package-manager handoff. If the resolved running-binary path lives under a known package-manager root (Homebrew, Scoop, Linuxbrew), --apply refuses and points at the package manager's upgrade verb (brew upgrade eeco or scoop update eeco). Self-replace would fight the package manager on its next sync; the manager owns its prefix. Rollback. The previous binary is preserved at <workspace>/state/update-<tag>/eeco.bak (or eeco.exe.bak on Windows). To revert by hand: mv <workspace>/state/update-<tag>/eeco.bak <running-path> The exact <running-path> is recorded in <workspace>/state/binary.json under running_path. What stays the same. Bare eeco update (no flag) is unchanged: it still lists the gap and exits cleanly, without touching any binary. Constraint 6 holds — eeco only swaps when the operator passed --apply. 15. Reading the in-binary guide ─────────────────────────────── eeco guide pages the user manual built into the binary — a verbatim mirror of this file (docs/USAGE.md) at the tag the binary was built from. Every install route ships the manual offline; no network access needed, no doc directory to clone. eeco guide The pager selection is $PAGER first (split on whitespace; the first token must be on PATH), then less -R if less is available, then a plain stdout dump as the final fallback. When stdout is not a terminal (piped or redirected) the command always dumps the manual plainly and exits 0 — the same one-screen path the TUI uses for eeco with no arguments. At a terminal the manual is prettified for reading: Markdown tables become box-drawing grids, headings are styled with a rule, and inline code / bold / links are rendered rather than shown as raw markup. NO_COLOR drops the colour but keeps the layout. Piped or redirected output stays raw Markdown, byte-identical to docs/USAGE.md, so a script that captures the guide (eeco guide > usage.md) gets the source unchanged. Quick recipes. eeco guide # page interactively eeco guide | less # explicit pager pipeline eeco guide > usage.md # capture the embedded snapshot PAGER='less +/^## 4' eeco guide # jump straight to the commands table The embedded snapshot is locked to the binary version. Pair it with eeco update --apply to keep the manual in sync with the running release. The tracked-tree docs/USAGE.md and the in-binary guide stay byte-identical in CI — a release commit that forgets to re-sync the mirror fails the build. 16. Authoring tracked docs ────────────────────────── eeco docs new <target> seeds a tracked-tree documentation file at the repository root. Two targets ship today: ┌────────┬──────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Target │ File written │ Purpose │ ├────────┼──────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ vision │ VISION.md │ seed a short manifesto: what this project is for, what it gives you, what it deliberately is not, and where the roadmap lives │ │ readme │ README.md │ seed a new-reader-friendly README: tagline, what the project does, a quick-start recipe, and a short "how it works" │ └────────┴──────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ The scaffolder is deterministic — no AI call, no provider spend — and project-shape-aware: the rendered "See also" only links to companion docs that already exist (README.md, docs/USAGE.md, docs/ARCHITECTURE.md). The readme target's "See also" never self-links, so the link set narrows to docs/USAGE.md and docs/ARCHITECTURE.md. eeco docs new vision # write VISION.md (refuse if it exists) eeco docs new --overwrite vision # replace an existing VISION.md eeco docs new readme # write README.md (refuse if it exists) eeco docs new --overwrite readme # replace an existing README.md Refuse-on-existing is the default. Pass --overwrite to replace a prior scaffold or hand-edited file. **--overwrite discards the existing body** — use it deliberately, especially on a populated README.md. eeco writes the file but never stages or commits it (Constraint 6); review the result and run `git add <file> && git commit` yourself. The seed file carries a one-line HTML comment at the top marking it as a scaffold and naming the eeco version it was generated against. The comment is invisible in any rendered Markdown view and can be deleted in the same edit you fill the body in. eeco docs refresh <target> re-renders the project-state-derived region of a previously-scaffolded doc — the same project-shape-aware "See also" block eeco docs new rendered — leaving operator prose outside the marker pair untouched. The region is delimited by a pair of HTML-comment markers:  … rendered content …  Markers inside fenced code blocks are ignored, mirroring `eeco docs compact`. Unmatched, nested, or out-of-order markers exit 1 with a parse error naming the offending line; the file is not touched. A scaffold with no markers is auto-initialised: the freshly rendered block is appended at EOF, marker-wrapped, with a blank-line separator. The operator removes the prior in-place block manually. Where --overwrite on eeco docs new discards the entire body, refresh is the non-destructive complement. eeco docs refresh vision # re-render VISION.md's marker block eeco docs refresh readme # re-render README.md's marker block eeco docs compact <path> moves resolved regions of a long doc into a sibling archive file so the working copy stays short, then leaves a single-line pointer stub in place at each cut. A region is anything between a pair of HTML-comment markers:  … content to archive …  Markers inside fenced code blocks are ignored, so a doc explaining the markers (this very paragraph in the original docs/USAGE.md) does not trigger a self-archive. eeco docs compact roadmap_v1.x.md eeco docs compact --dry-run roadmap_v1.x.md eeco docs compact --archive history.md roadmap_v1.x.md The default archive destination is <basename>.archive<ext> next to the source — e.g. roadmap_v1.x.md → roadmap_v1.x.archive.md. Override the destination with --archive; pass a --dry-run to preview which line ranges would move without writing. Re-running after a successful compact is an idempotent no-op (`no archive markers found`); the archive is appended to on subsequent runs so a long-lived doc can be compacted in waves. Unmatched, nested, or out-of-order markers exit 1 with a parse error naming the offending line; the archive is not touched. Both paths must resolve inside the repository (absolute paths and .. traversal are rejected). eeco writes the source and the archive but never stages or commits either (Constraint 6); review both files and `git add` / commit when ready. For a log that grows by prepending a new section each time — a session journal, a changelog, a steering file — placing markers by hand every round is fiddly. --keep-last N discovers the archivable regions by heading instead. Pair it with --heading <prefix>, the heading-line prefix that opens an archivable section: eeco docs compact --keep-last 4 --heading "## Snapshot" RESUME.md This keeps the N most-recent matching sections — newest meaning topmost in the file — and archives everything older. The # run in --heading fixes the section level: a section runs from its heading to the next heading of the same or a higher level, so a live tail such as a trailing ## Next session or ## Pointers block is never swallowed. A deeper sub-heading inside a section does not split it, and (as in marker mode) any heading inside a fenced code block is ignored. Adjacent archived sections collapse into one pointer stub. --keep-last and explicit markers are mutually exclusive: running heading mode on a source that still carries a paired marker region exits 1 rather than mixing the two schemes. --keep-last requires --heading and vice versa. --dry-run and --archive work the same in both modes; re-running once only the kept window remains is an idempotent no-op. 17. Keeping notes ───────────────── A note is a place to scribble — a half-formed idea, a reminder, a thread to pick up later. It is deliberately neither a memory fact (frontmatter-strict, matched to AI relevance) nor a queue item (the append-only decision channel): routing scratch text into either of those pollutes their contract. Notes get their own surface. eeco add note "check round-robin fairness in queue promotion" eeco show notes eeco add note "<text>" saves the text verbatim to one plain Markdown file under <workspace>/notes/, named YYYY-MM-DD-HHMMSS-<slug>.md (the timestamp is UTC; the slug is derived from the text). The directory is created on first use, so a fresh eeco init is not required — being inside a git repository is enough. eeco writes only inside the workspace (Constraint 1) and never stages or commits (Constraint 6). eeco show notes lists every note newest-first, one row per note: the local date and time followed by the note's first line. An empty or absent notes directory prints a friendly hint and exits 0. This first slice is append + list only. To edit a note, open it in your editor ($EDITOR <workspace>/notes/<file>); to remove one, delete the file (rm <workspace>/notes/<file>).

Everything eeco can do. The runtime story, directory layout, trust boundaries, and frozen public surface are documented in ARCHITECTURE.md (ARCHITECTURE.md). 1. Install ────────── Single static binary, zero runtime dependencies. Four install routes: pre-built binary, Homebrew, Scoop, from source. 1.1 Pre-built binary (recommended) Download the archive for your platform from the releases page (https://github.com/ajhahnde/eeco/releases), verify it against SHA256SUMS, extract the eeco binary, and put it on your PATH. ┌─────────┬───────┬────────────────────────────────────┐ │ OS │ Arch │ Archive │ ├─────────┼───────┼────────────────────────────────────┤ │ darwin │ amd64 │ eeco__darwin_amd64.tar.gz │ │ darwin │ arm64 │ eeco__darwin_arm64.tar.gz │ │ linux │ amd64 │ eeco__linux_amd64.tar.gz │ │ linux │ arm64 │ eeco__linux_arm64.tar.gz │ │ windows │ amd64 │ eeco__windows_amd64.zip │ │ windows │ arm64 │ eeco__windows_arm64.zip │ └─────────┴───────┴────────────────────────────────────┘ Checksum verification: shasum -a 256 -c SHA256SUMS Signature and provenance (recommended). SHA256SUMS is signed keylessly with cosign — no key to fetch or trust on file; the signing identity is the release workflow itself. Verify it: cosign verify-blob \ --certificate SHA256SUMS.pem \ --certificate-identity-regexp \ '^https://github.com/ajhahnde/eeco/\.github/workflows/release\.yml@refs/tags/v' \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --signature SHA256SUMS.sig \ SHA256SUMS Each archive also carries GitHub build provenance. Verify a downloaded archive came from this repository's release workflow: gh attestation verify eeco___. --repo ajhahnde/eeco macOS Gatekeeper. The darwin binaries are distributed unsigned by design; their integrity is established by the SHA256SUMS signature and provenance above rather than Apple's notary service. After extracting, clear the quarantine attribute the browser sets on the download: xattr -d com.apple.quarantine ./eeco The cosign + provenance route above is the supported integrity check on macOS; the darwin binaries are intentionally distributed without an Apple Developer ID signature. 1.2 From source Requires Go 1.24+. Released archives are produced by GitHub Actions on every v* tag and uploaded to the releases page (https://github.com/ajhahnde/eeco/releases). Running make release locally is an alternate path — useful for offline rebuilds and for verifying that a published release is byte-identical to a fresh build from the tag. Reproducing the released binaries byte-for-byte requires the same Go toolchain CI used. go.mod pins it; when your installed Go differs, set GOTOOLCHAIN=go1.24.2 so the build fetches and uses the pinned version. git clone https://github.com/ajhahnde/eeco cd eeco make build # ./eeco with injected version make release VERSION=vX.Y.Z # cross-build the published matrix into dist/ make verify # go build ./... && go vet ./... && go test ./... make build produces ./eeco with version, commit, and buildDate injected via -ldflags so eeco version reports the real build identity. make release writes archives plus SHA256SUMS into dist/; make packaging writes eeco.rb and eeco.json from the checksums. 1.3 Homebrew (macOS, Linux) brew install ajhahnde/eeco/eeco Installs the binary from the latest tagged release via the ajhahnde/eeco tap. brew upgrade eeco follows new tags. The formula is generated per release and published with the release assets as eeco.rb. 1.4 Scoop (Windows) scoop bucket add eeco https://github.com/ajhahnde/scoop-eeco scoop install eeco scoop update eeco follows new tags. The manifest is published with the release assets as eeco.json. 2. First use in a project — eeco init ───────────────────────────────────── cd /path/to/your/repo eeco init eeco init: • creates a private, per-user workspace at //.eeco/ and adds // to .gitignore if it is not already ignored, so nothing eeco does can leak into your tracked history. is your git user.name; override it with --username NAME or the EECO_USERNAME environment variable (resolution order: flag, env, git user.name, then a prompt). --workspace NAME renames the inner .eeco engine directory; • scaffolds the engine, memory store, builtin workflows, and state inside that directory; • detects the project profile (zig, python, node, go, generic) and the matching parse/build gate, and classifies the project type to choose the knowledge directories it scaffolds. Detection is a deterministic marker scan; init_detection_threshold (a value in [0,1] in config.local) is the confidence at or above which init accepts the scan without prompting (0, the default, uses the detector's own default). --type CATEGORY forces a type and skips detection; --ai opts into a single gated AI pass for an ambiguous tree. The one commit eeco makes. When init adds the .gitignore line it stages *only that file*, commits it as eeco init, and pushes — the single sanctioned write to your git history (everything else eeco writes stays in the gitignored workspace). --no-commit skips the commit and push; --no-push commits locally without pushing. On a non-git or not-yet-real repo the step is skipped with a manual hint, and any git failure is a warning — init never fails because of it. Migrating an older workspace. If a legacy /.eeco workspace from before the per-user layout is found, init reports it and offers to run eeco migrate v1 (§4) before continuing; declining makes no changes. This is also the "new project, professional setup" path: one command gives a repo its private workspace plus the whole ecosystem. 3. The control center (TUI) — eeco ────────────────────────────────── Run eeco with no arguments to open the control center. Not a terminal (piped/CI)? It prints a one-screen status digest and exits 0 instead. The control center opens on a home screen: a centred eeco logo at the top, the version and one rotating usage tip below it, a hint above the input, and a thin dim status footer (repo, profile, gate, automation, memory and queue counts, hook state, last run) below the input. Every command is discoverable by typing / (the slash-command palette) or pressing ? (the shortcut overlay), so the home screen stays uncluttered. Typing or running a command collapses the home view to input + footer so streamed output reads cleanly above; clearing the input recovers the home view. Output stays in the normal terminal scrollback after you quit — no full-screen takeover. Typing / opens a slash-command palette: a live dropdown of every command with its one-line purpose, between the input and the footer. Filter it by typing (/h narrows to /help and /hooks), move the highlight with Up/Down, and accept the selection with Tab or Enter; the palette closes on a space, a newline, or when the input clears. The input is a multi-line composer: type or paste a request that spans several lines. Enter submits; Alt+Enter or Ctrl+J inserts a newline (Ctrl+J is the fallback where a terminal swallows Alt+Enter). The box grows with the draft up to eight rows and then scrolls internally, shrinking back when you submit or clear. Free text (no leading slash) no longer opens an in-binary chat. eeco configures the harness that runs the AI (see eeco cockpit), so the control center stays a deterministic command surface rather than a second-rate agent: a free-text line prints a dim one-line reminder to use a slash command (/run, /memory, …) or ? for help, and spends nothing. The in-binary chat turn, its read-only tool loop, and /clear were retired in the move to the cockpit model. Input accepts: ┌─────────────────────┬─────────────────────────────────────────────────────────┐ │ Input │ What it does │ ├─────────────────────┼─────────────────────────────────────────────────────────┤ │ /run [--ai] │ run a workflow (--ai opts into one gated pass) │ │ /queue │ show items awaiting a decision │ │ /memory │ list stored facts │ │ /gc │ run memory garbage collection │ │ /new │ scaffold a new workflow │ │ /hooks [ on|off] │ show or toggle the opt-in reversible hooks │ │ /settings [ ] │ view or set the AI config (persists to config.local) │ │ /help │ command and key reference │ │ /quit │ leave the control center │ │ plain text │ a dim reminder to use a slash command (chat is retired) │ └─────────────────────┴─────────────────────────────────────────────────────────┘ Keys: Up/Down browse command history at the top and bottom of the composer (and move the cursor within a multi-line draft otherwise, or move the palette highlight when it is open), Tab completes a command or workflow name, Alt+Enter / Ctrl+J insert a newline, ? toggles a shortcut overlay, Esc interrupts a running task — an animated spinner in the footer marks one in flight. q (on an empty line), /quit, and Ctrl-C always leave the terminal in a sane state. NO_COLOR is honoured. Plain text never spends silently: each conversation turn is consented and budget-capped, and parked-and-queued when it cannot run (the conversation does not advance on a parked turn). Commands never require AI. 4. Commands ─────────── eeco open the control center (digest if non-TTY) eeco init [--no-track] [--from ] bootstrap the ecosystem in this repo (--from imports settings from another eeco project; --no-track skips the private workspace-history repo) eeco migrate v1 [--yes] move a legacy /.eeco workspace under / eeco run run one workflow (read-only / safe by default) eeco run --ai allow this run's gated, budget-capped AI pass eeco new scaffold a new workflow from the template eeco gc run memory garbage collection eeco queue print the workspace queue (resolve by editing queue.md) eeco stats print cumulative AI usage from the call ledger (real token counts) eeco hooks on|off toggle an opt-in hook (reversible; names: pre-commit, post-merge, session-start, commit-msg, commit-guard) eeco hooks session-start refresh re-render every session_files block from current project state eeco hooks refresh rewrite an installed hook (pre-commit, post-merge, commit-msg, commit-guard) with the current eeco binary path eeco config list show every config key, its effective value, and origin (default | global | local) eeco config get print the effective value of one config key eeco config set [--global] set a key in this workspace, or (--global) in the cross-project layer eeco config import [--force] copy config.local, cockpit.json, and workflows from another eeco project eeco cockpit target [--global] list|add |rm manage the active (or cross-project) harness target set eeco gates check-attribution [flags] scan tracked files + commit bodies for AI-attribution fingerprints eeco update [--apply] check for a newer release; --apply verifies + swaps eeco doctor run workspace and config diagnostics eeco go [--brief] [--metrics] [--write|--json|--copy] print an AI-ready brief; --brief trims it; --metrics adds a stderr readout; --json emits JSON, --write saves, --copy clipboards eeco ask [--limit N] [--json] "" answer a question with ranked file:line pointers (no AI) eeco docs new [--overwrite] scaffold a tracked-tree doc (targets: vision, readme) eeco docs refresh re-render a scaffolded doc's marker-wrapped block (targets: vision, readme) eeco docs compact [--keep-last N --heading ] [--archive ] [--dry-run] archive old regions of (markers, or heading-discovered with --keep-last) into a sibling eeco history show the private workspace-history log (recent commits) eeco history snapshot [-m ] commit the current workspace state into the private history repo eeco history compact [--dry-run] [--yes] squash the private history log into one commit (reflog-recoverable) eeco guide page the in-binary user manual through the host pager eeco uninstall [--yes] write a handoff summary, print the removal command, and de-init the private history repo (--yes skips the confirm) eeco report-bug [--submit] file a structured bug report (--submit opens the pre-filled issue URL in your browser) eeco add note "" append a free-form note to the workspace eeco add fact --description "" [flags] "" record a durable memory fact eeco add task "" append an item to the workspace queue eeco adaptations <name> on|off toggle an AI-adaptation fact on or off eeco workflows [<name> on|off] list scaffolded workflows or toggle one on/off eeco show notes list the workspace notes, newest first eeco show adaptations list AI-adaptation facts with their on/off state eeco show prompt [name] list the prompt library or print one prompt body eeco refresh-manifest [<dir>] rebuild the .ai.json manifests in the knowledge dirs eeco version print the version eeco help command reference Exit codes (also the workflow contract): 0 clean · 1 finding/failure · 2 blocked (a required tool is missing) · 3 AI pass deferred (no --ai). 4a. Configuration — eeco config ─────────────────────────────── Configuration resolves in three layers, each overriding the one before it: built-in defaults → user-global ~/.config/eeco/config.local (shared by every project) → workspace <repo>/<user>/.eeco/config.local (this project only) Inspect and edit the two file layers with eeco config: eeco config list # every key, effective value, and origin eeco config get automation # one effective value, bare (for scripts) eeco config set automation=manual # write the workspace layer (this project) eeco config set --global automation=auto # write the cross-project layer set accepts key=value or key value. A value is validated against the same rules config.local uses, so a typo'd key or a malformed number is rejected before anything is written. (Floor-invariant keys such as automation tolerate any value and normalize at load, exactly as they do in a hand-edited config.local.) Sharing settings across projects — the global layer Set a key once with --global and every project inherits it, unless that project overrides it in its own workspace config.local. This is the git --global model: machine-wide defaults with per-repo overrides. The global file lives at ~/.config/eeco/config.local — or $XDG_CONFIG_HOME/eeco/config.local, or wherever EECO_CONFIG_HOME points (the override also makes the layer hermetic under tests). eeco config set --global … is the one eeco command that writes outside a repository, by design; everything else stays inside the project. It does not need an initialised workspace, or even to be inside a repo. Cockpit targets share the same model: eeco cockpit target --global add cursor # new projects inherit this target set eeco cockpit target list # falls back to the global set when this # project has no cockpit.json of its own Copying settings from one specific project — --from / import Where the global layer is a *live* shared default, --from is a *one-shot copy* from one named project into another. It carries three things — config.local, the cockpit selection (cockpit.json), and the scaffolded workflows/ — and nothing else (project-specific knowledge, state, and bug reports never travel). eeco init --from ~/other-project # bootstrap a new repo, then copy from another eeco config import ~/other-project # copy into an already-initialised project eeco config import --force ~/other-project # let the source win over existing files/keys The source path may be the other repo's root or any directory inside it. Into a fresh workspace the config.local is copied verbatim (full fidelity); into an existing one it is key-merged. Without --force, files and keys the destination already has are preserved; --force lets the source win. Importing from a project of a different type may pull in type-specific keys (profile, gate) — eeco config set fixes any you don't want. 5. Builtin workflows ──────────────────── ┌──────────────────┬──────────────────────────────────────┬─────────────────┬─────┐ │ Workflow │ Inspects │ Writes │ AI │ ├──────────────────┼──────────────────────────────────────┼─────────────────┼─────┤ │ comment-hygiene │ source/docs for tooling fingerprints │ nothing │ no │ │ leak-guard │ staged + tracked tree, commit msg │ nothing │ no │ │ version-sync │ declared version_locations │ nothing │ no │ │ gate │ the declared gate command chain │ nothing │ no │ │ bug-sweep │ code, statically │ a triage ledger │ opt │ │ handover-refresh │ code/docs/git history │ queue proposal │ opt │ │ evolve │ run history + repeated actions │ queue │ opt │ │ memory-drift │ memory facts with a ref │ queue │ no │ │ doc-drift │ CHANGELOG.md vs git tags │ queue │ no │ │ manifest-refresh │ knowledge dirs (paths + kinds) │ .ai.json │ no │ └──────────────────┴──────────────────────────────────────┴─────────────────┴─────┘ • comment-hygiene fails if any shippable file carries an AI-attribution / tooling string. • leak-guard blocks a commit that would leak an attribution string, a Co-Authored-By trailer, or a private-workspace path into tracked files. • version-sync reports drift between the version strings declared in <workspace>/config.local's version_locations list. Each entry is a path:regex pair (split on the first colon); the path is repo-relative and the regex must declare at least one capture group (group 1 captures the version string). With no version_locations entries the workflow exits 0 (the gate is opt-in per project). Use the multiline flag (?m) when the regex anchors on the start of a line further down a file — Go's ^ is start-of-string by default. Set version_locations=auto instead of an explicit list to let version-sync discover the version locations itself. In auto mode it scans a fixed, high-precision set of common version files — VERSION, CHANGELOG.md (the first ## [vX.Y.Z] heading), package.json, pyproject.toml, and Cargo.toml — and reports drift across whichever of them the project actually has. A file that is absent, or present but carrying no version-shaped string, is skipped. auto cannot be mixed with explicit path:regex entries — it is the whole list or none of it — and composes with version_anchor the same way an explicit list does. The version_anchor config key selects the source of truth declared locations are checked against. Three modes: • Unset (default) — consistency-only. The first declared location is the anchor; the rest must match it. Exits 0 when every declared location agrees, 1 when any drifts, and 2 when a declared path is missing on disk. The slice-1 behaviour, preserved for backward compatibility. • version_anchor=tag — tag-anchor. The latest semver-shaped (vX.Y.Z) tag reachable from HEAD is the source of truth. Declared locations must be semver->= the tag, so a release commit can bump declared locations ahead of the not-yet-pushed tag (the tag is pushed after the commit). Backward-drift still fails. If no semver-shaped tag is reachable yet, falls back to the consistency-only behaviour with a note in the summary. • version_anchor=<path>:<regex> — designated-file mode. Same shape as a version_locations entry; the captured version is the source of truth and every declared location must strict-equal it. A missing path exits 2 (blocked) so a typo surfaces rather than silently falling through to consistency-only. Worked example. Declare two entries that both must carry the latest released tag — the CHANGELOG.md heading and the matching footer compare-link, which often drift when a release bumps one but forgets the other — and enable tag-anchor so a release commit's bump catches a forgotten location: version_locations=CHANGELOG.md:(?m)^## \[v(\d+\.\d+\.\d+)\] version_locations=CHANGELOG.md:(?m)^\[v(\d+\.\d+\.\d+)\]: https://github version_anchor=tag Once version_locations is declared, wire the gate into the pre-commit hook so drift is caught before the commit lands rather than only under make gates: eeco hooks pre-commit on installs a .git/hooks/pre-commit that runs the default workflow chain (leak-guard + version-sync) and blocks the commit on a non-zero exit. See §9 for the override knob and the byte-identical reversal contract. • gate runs the project's declared parse/build gate — the ordered command chain in <workspace>/config.local's gate key — step by step, with the repository root as the working directory, stopping at the first failure. The gate key is repeatable: each occurrence adds one step (a whitespace-split command), and the first occurrence resets the profile default so the operator-declared chain fully replaces it. A bare single-command gate is a one-step chain; a project with no gate (the generic profile, or a lone gate=) is a clean no-op, so the gate is opt-in per project. Every step's command is checked on PATH before the first step runs, so a chain that cannot complete exits 2 (blocked); a step that exits non-zero exits 1 and stops the chain. Run it with eeco run gate, or add gate to pre_commit_workflows (§9) to run the whole validation chain before each commit. Worked example. A Go project that wants vet, a static linter, and the unit tests as one gate, run in order and stopping at the first to fail: gate=go vet ./... gate=staticcheck ./... gate=go test ./... • bug-sweep does a static read and maintains an append-only triage ledger (open findings → resolved log); with --ai it performs the reasoning pass, otherwise it reports and parks the prompt. • handover-refresh drafts a dated handover plus a "what's now dead" diff and queues it for your approval — it never overwrites a note directly. • evolve watches for repetition and *proposes* new workflows into the queue. It never activates one on its own. The proposal pass is two-stage: a deterministic signal extraction scans the most recent 40 commit subjects for repeated conventional-commit types (<type>(<scope>)?!?: …) and surfaces one workflow candidate per type that appears at least three times (cap five candidates per run, sorted count-desc then key-asc). Each candidate becomes its own evolve queue item — the operator resolves or dismisses one at a time. The gated AI pass becomes optional enrichment layered on top: --ai (or automation=auto) opts into it; on no consent or any provider skip eeco still exits 0 when the deterministic pass found at least one candidate, and only preserves the exit-3 (AI deferred) contract when there is genuinely nothing to report — no consent and no deterministic candidates. It also maintains a repetition ledger at <workspace>/state/evolve-history.json. Each surfaced candidate writes one record (signal kind + key, count at proposal, the queue row's kind + title, the proposal timestamp); a re-run suppresses any candidate whose (signal_kind, signal_key) is already in the ledger, so a recurring signal is proposed exactly once in its lifetime even after the queue item is ticked. Each run also reconciles unresolved records against the queue: a record whose queue row is now checked flips to resolved: true with a resolved_at timestamp. Reconciliation runs once per evolve invocation — the queue is not watched live, so an operator who ticks a row between runs sees the ledger update on the next eeco run evolve. The re-propose-on-signal-recurrence knob is a follow-on slice; today a resolved record still suppresses. A future slice may add a file-touch signal alongside the commit-type one (deferred because it needs a new gitx helper). • memory-drift flags a memory fact whose ref: file has been committed on a later calendar day than the fact's own created: date — a sign the fact may now describe code that has moved on. eeco gc already catches a ref: that no longer exists on disk; memory-drift catches the complementary case where the file is still there but has changed since the fact was written. One review item per stale fact is routed to the queue — eeco flags the drift, you reconcile the fact. It needs git on PATH (it exits 2, blocked, without it) and exits 0 when every ref-carrying fact is still current. Run it with `eeco run memory-drift`, or wire it to run automatically after a merge with the post-merge hook (§9), where it is in the default workflow list. • doc-drift flags drift between the release sections in CHANGELOG.md and the project's git tags. Two cases: a vX.Y.Z git tag with no ## [vX.Y.Z] CHANGELOG section (a release that was never documented), and a ## [vX.Y.Z] section with no matching tag (a release documented but never tagged). The newest section is exempt: a release commit adds the ## [vX.Y.Z] heading before the vX.Y.Z tag is pushed, so a section strictly ahead of the latest tag is the expected release-in-progress state, not drift. One review item per drift is routed to the queue — eeco flags it, you reconcile the CHANGELOG.md or the tag. It needs git on PATH (it exits 2, blocked, without it) and exits 0 when CHANGELOG.md is absent, no tags exist yet, or every tag and section agree. Run it with `eeco run doc-drift, or let the post-merge` hook (§9) run it automatically — it is in that hook's default workflow list alongside memory-drift and manifest-refresh. • manifest-refresh rebuilds the per-directory .ai.json manifests across the knowledge dirs — the project-type directories scaffolded under <repo>/<owner>/ as siblings of the engine workspace. Each manifest is a deterministic skeleton — a JSON document `{"dir", "purpose"?, "items":[{"path","kind"}…]} with kind either "file"` or "dir", sorted by path; the optional desc/find_when fields are reserved for a future enrichment pass and stay empty in the deterministic walk. The .ai.json file is skipped in its own walk, so a re-run over unchanged dirs reproduces byte-identical output. Writes land in the gitignored per-user area, never the tracked tree; it needs no AI and never blocks. Run it on demand with `eeco refresh-manifest [<dir>]` (the same deterministic rebuild, optionally scoped to one knowledge dir), or let the post-merge hook (§9) run it. Run any of them from the TUI or eeco run <name>. These ten are the complete builtin set. Additional builtin workflows are tracked as a post-v0.1.0 item. Scaffolding a workflow with eeco new eeco new <name> scaffolds a user workflow under <workspace>/workflows/<name>/ from a per-profile template. The scaffold layout is picked from the project's detected profile: • go profile — run PATH-checks go and runs go vet ./... as the inert default. • python profile — run PATH-checks python3 and runs python3 -m compileall -q . as the inert default. • generic profile (and any profile without a dedicated template: zig, rust, node) — run is a bare sh stub that prints a placeholder line and exits 0. In every case the scaffolded run is a starting point — replace the default body with the real check this workflow is meant to perform. The chosen template is internal to eeco; the verb shape `eeco new <name>` is unchanged. Toggling a scaffolded workflow on or off Once scaffolded, a workflow is on by default; eeco runs it whenever it is asked to (a manual eeco run <name>, a hook chain that names it, the TUI). To pause a workflow without deleting it: eeco workflows <name> off # mark <name> as disabled eeco workflows <name> on # bring <name> back online eeco workflows # list every scaffolded workflow + state off plants an empty sentinel marker file at <workspace>/workflows/<name>/disabled; the loader sees it and reports the workflow as blocked (exit 2) without running it. on removes the marker. Repeating the same action is a clean no-op. Builtin workflows are unaffected by this toggle — their contract is part of the frozen public surface. To remove a scaffolded workflow for good, delete its directory. 6. Memory and garbage collection ──────────────────────────────── The store holds one fact per file (flat frontmatter: name, description, type, dates, optional ref:/expires:, pin:), with a regenerated MEMORY.md index and [[links]] between facts. Types: user, feedback, project, reference, finding. eeco gc (or the Memory screen) keeps the store honest: • a memory whose ref: path is gone, that has expired, a resolved finding, or an unused reference past the stale window is archived to the recoverable attic; • anything load-bearing (project/feedback/user) is **queued for your decision**, never silently deleted; • pin: true exempts a fact permanently. This is automated and conservative — the algorithm never loses a fact that still matters; it asks you instead. Re-running eeco gc (for example through the post-merge hook chain) no longer files duplicate gc-review items for an unresolved finding: an open queue row for the same fact + reason is recognised and the second filing is skipped. Resolving the row (checking its box) lets a future trigger file again, so the queue is never wedged on a stale recommendation. eeco add fact records a fact without hand-authoring the frontmatter: eeco add fact --description "<summary>" [--type <type>] [--name <slug>] [--ref <path>] [--pin] [--provenance <text>] [--agent <name>] "<body>" It writes one frontmatter file under <workspace>/memory/ and regenerates MEMORY.md. --description is the one-line summary that drives relevance matching and is required. --type is one of user, feedback, project, reference, finding and defaults to project — the safe default, since project/user/feedback facts are queued for review rather than archived. --name is the lower-kebab-case filename stem; when omitted it is derived from --description. --ref records a repo-relative path the fact documents (garbage collection validates it); --pin exempts the fact from collection. --provenance "<text>" records the snippet that triggered the fact (source: in frontmatter, capped at 120 characters); --agent <name> records which assistant filed it (agent:). Both are **required for --type feedback and --type user** — those types are durable adaptations to the operator, and an unauthored adaptation is the silent drift eeco show adaptations exists to surface. Hand-authored facts remain permissive: an older fact file without the new fields still loads. eeco refuses to overwrite an existing fact — pass a different --name, or edit the file directly. The command needs an initialised workspace; it writes only inside it (Constraint 1) and never stages or commits (Constraint 6). Editing a fact later is `$EDITOR <workspace>/memory/<name>.md; removing one is rm`. Auditing AI adaptations A feedback- or user-typed memory fact is a durable adaptation to the operator — every future assistant briefed by eeco go honours it. eeco show adaptations lists every adaptation newest-first with its provenance and on/off state, so the operator can audit *what the AI is doing automatically now* without grepping the memory directory: eeco show adaptations eeco adaptations <name> on|off flips a disabled: flag on one fact in place and regenerates the MEMORY.md index so the change shows at once. A disabled fact is preserved on disk but hidden from eeco go briefs and eeco ask rankings, so re-enabling is one CLI flip: eeco adaptations terse-feedback off # mute it without deleting eeco adaptations terse-feedback on # restore it eeco gc skips disabled facts so a deliberately muted adaptation never gets routed for staleness review. A disabled fact is hidden from the AI-facing surfaces (eeco go, eeco ask, the TUI relevance ranker) but stays **visible — marked — on the human audit surfaces**: the regenerated MEMORY.md index lists it under a ## disabled heading, and the TUI /memory screen tags its line [off]. This holds for a fact of any type, so a disabled project or reference fact is never silently lost from view. eeco show adaptations is the audit surface; the fact file under <workspace>/memory/<name>.md is the source of truth. Constraints 1 + 6 hold (writes inside the workspace; nothing staged or committed). 7. The queue — the only thing that interrupts you ───────────────────────────────────────────────── Workflows and GC never act unilaterally on a meaningful change. They append an item to the queue. View it with eeco queue (or /queue in the TUI); the status digest shows the open count. The queue file is yours — you resolve an item by ticking its checkbox ([ ] → [x]) or deleting the row in <workspace>/state/queue.md. Nothing else nags you; nothing runs unless you invoke it. You can also file a queue item yourself — or have an assistant file one for you — with eeco add task: eeco add task "wire the man page into brew/scoop" eeco add task --kind review --detail "check the brew formula" "audit packaging" The title is the checklist row; --kind is the short queue tag (default task); --detail is an optional elaboration printed beneath the row. The item is appended to <workspace>/state/queue.md and shows up alongside workflow- and GC-filed items in eeco queue (or /queue) and the status digest's queue count. eeco add task writes only inside the workspace (Constraint 1) and never stages or commits (Constraint 6); it requires an initialised workspace. Like eeco add fact, it closes the read/write loop — an assistant briefed by eeco go can route a decision back into eeco's one decision channel instead of letting it evaporate. 8. AI configuration ─────────────────── AI is opt-in (--ai, or an automation level that grants standing consent) and budget-capped. eeco no longer runs an in-binary model client — it configures the harness that runs the AI. The one inference path it keeps for its own chores is a CLI provider that shells any program of your choice (prompt on stdin, reply on stdout); with none configured, every AI pass is parked, never failed. Configure in <workspace>/config.local, or set the common keys from the control center with /settings: automation = propose # manual | propose | scaffold | auto ai_budget = 1 # gated passes per invocation; 0 disables AI # CLI provider — any program, prompt on stdin, reply on stdout: ai_command = yourcli --print ai_provider = cli # cli | none; empty/unknown auto-selects • Auto-select (default). With ai_provider empty or unset — or an unknown/legacy value such as anthropic — a configured ai_command picks the CLI provider; otherwise every AI pass is **parked and queued**, never failed — the deterministic, non-AI result still stands. ai_provider = none is also accepted; nothing here is ever a config error. • ai_model and ai_api_key_env are inert legacy keys: read and passed through, but ignored by the CLI provider (there is no native API path). They stay only so an old config.local loads unchanged. • Only automation=auto is itself standing AI consent; every other level needs an explicit --ai on the run. • The same gating — consent, budget cap, and prompt-parking — wraps every provider call, so a run is always safe and never an uncontrolled spend. Every attempt is recorded to the AI-call ledger (state/ai-calls.json): label, provider, resolved model, prompt and response hashes, and token usage. /settings (no arguments) shows the current values; `/settings <key> <value> writes one to config.local`. A change applies the next time eeco starts; a long-lived session keeps the budget cap it began with. Cumulative AI usage — eeco stats eeco stats aggregates that ledger (state/ai-calls.json) into a one-glance readout of how much AI eeco has actually used on this project: eeco stats eeco stats: 12 AI calls (9 ran, 3 parked) from 2026-05-21 to 2026-05-30 tokens: 18432 input · 4096 cached · 6210 output (28738 total) by provider: cli 9 · none 3 It reports the total number of gated AI calls, how many actually ran versus were parked, the cumulative token counts, the per-provider call breakdown, and the recorded date range. Unlike eeco go --metrics, whose token figures are bytes/4 estimates marked with ≈, these token totals are the real provider counts the ledger stored, so they carry no ≈. The command is read-only and makes no AI call; an uninitialised workspace or an empty ledger reports `no AI calls recorded yet` and still exits 0. The exact wording and the displayed figures are a human-readable readout and are not part of the frozen surface. 9. Hooks (opt-in, reversible) ───────────────────────────── Off by default. Inspect with eeco hooks (or /hooks); toggle with eeco hooks <name> on|off (or /hooks <name> on|off). Names: pre-commit, post-merge, session-start, commit-msg, commit-guard. • pre-commit — a local .git/hooks/pre-commit (untracked, repo-scoped) that runs the configured builtin workflows in declared order and stops at the first non-zero exit, blocking the commit when any step fails. Defaults to leak-guard (blocks a leaking commit) followed by version-sync (silent on projects that have not declared version_locations, so opt-in per project). Override the list with one or more pre_commit_workflows keys in config.local; the first occurrence resets the binary default, subsequent occurrences append. An empty pre_commit_workflows= value clears the list and `eeco hooks pre-commit on` refuses to install. The hook is installed only if no pre-commit hook already exists, and removed only when the on-disk script is byte-identical to what eeco wrote; a foreign or hand-edited hook is always left untouched. After upgrading the eeco binary (for example a brew upgrade that moves the binary) or editing pre_commit_workflows, run eeco hooks pre-commit refresh to rewrite the installed script with the current binary path and workflow set. • post-merge — a local .git/hooks/post-merge (untracked, repo-scoped) that runs the configured drift-detection workflows after a git merge / git pull — the moment another author's changes land, the natural time to re-check whether eeco's recorded state has drifted from the code. Defaults to memory-drift followed by doc-drift (both silent no-ops on a project with no memory ref: facts and no CHANGELOG/tags). Unlike pre-commit it does not block: the merge has already completed, so a finding or a missing tool surfaces as a queue item, never as a hook failure (each step's exit is swallowed and the hook does not use set -e). The drift workflows file at most one open queue item per finding — a repeated run does not pile up duplicates of a finding still awaiting a decision. Override the list with one or more post_merge_workflows keys in config.local (same reset-then-append semantics as pre_commit_workflows; an empty post_merge_workflows= clears the list and eeco hooks post-merge on refuses to install). Install / removal / refresh behave exactly as for pre-commit: a foreign or hand-edited hook is always left untouched. • session-start — composes up to three blocks at session start and stays silent when every block is empty: 1. A reading routine — repo-relative paths to read before substantive work. Auto-detected from a built-in list (docs/PUBLIC_API.md, docs/ARCHITECTURE.md, CHANGELOG.md, ARCHITECTURE.md, docs/USAGE.md, README.md); existing entries surface, missing ones are skipped. The most-recently-modified match of roadmap*.md is appended as the live planning surface. Override the doc list with one or more session_start_docs keys in config.local; change the roadmap pattern with session_start_roadmap_glob (empty disables discovery). 2. A mailbox warning — surfaces when Ideas.md at the repo root has content beyond its empty template (the parser skips the file header and any HTML comment blocks). Change the filename with session_start_mailbox in config.local; an empty value disables the block. The hook does not create the file — it surfaces only when the operator opted in by creating it. 3. A one-line queue reminder — eeco: N items awaiting a decision when the queue is non-empty. 4. (opt-in) Pinned memory bodies — the full body of every pin: true memory fact under <workspace>/memory/, separated by Markdown dividers. Off by default, so the hook output is byte-identical until enabled. Opt in via session_start_pinned_bodies=true in config.local (workspace default) or the --with-pinned-bodies flag on eeco hooks session-emit (one invocation only). Useful when an AI assistant treats the hook output as a system-reminder so a pinned policy memory (for example a no-AI-attribution rule) lands in the model's context at session start. The session-start hook ships with two brand-free delivery channels; use either alone or compose both: • JSON settings file — an exact-match-removable entry in an AI CLI's user-global JSON settings file (the Claude Code shape). Set the file location with session_settings_path in config.local or the EECO_SESSION_SETTINGS environment variable. The file is backed up (inside the workspace) before the edit and re-validated after; an invalid result is rolled back. • Marker block in a text/markdown file — eeco maintains a delimited block of the same content the JSON channel renders, in one or more files the assistant already reads at session start (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, AGENTS.md for OpenAI Codex, .cursorrules for Cursor, ~/.config/<tool>/..., etc.). Declare one path per session_files= line in config.local; each value is either repo-relative (held inside the repo) or absolute. The block is fenced by HTML comments —  /  — and replaces in place on re-on or refresh. The block content is whatever eeco hooks session-emit prints. eeco never edits bytes outside the marker pair, and a block whose contents have been hand-edited since install is left untouched on off. Files eeco itself created are removed when off would leave them empty; files that already existed are restored byte-identical to their pre-on state when the block is at end-of-file. Neither channel is configured by default: `eeco hooks session-start on` reports "not configured" until at least one of the two is set. When the file channel is wired, run eeco hooks session-start refresh to re-render the block — the JSON channel does not need it (it carries a command eeco runs at session start, so it is always fresh). • commit-msg — a local .git/hooks/commit-msg (untracked, repo-scoped) that rejects commit messages carrying an AI-attribution trailer. The policy is universal and lives inside the eeco binary: the on-disk script is a one-line wrapper that execs eeco hooks commit-msg-check "$1", so the pattern set refreshes with every brew upgrade eeco. Matches the trailer-anchored forms (Co-Authored-By: lines naming claude, anthropic, or noreply@anthropic) plus the Claude Code robot-emoji (U+1F916) "Generated-with" signature; deliberately stricter than the broad repo-tree scan so a docs commit that *discusses* the policy ("remove Co-Authored-By trailer") still passes. Exit code 1 prints the matched line and names --no-verify explicitly as the bypass; conscious overrides remain available without surprise. Install / removal behave exactly as for pre-commit and post-merge: foreign hooks are never modified. After a brew upgrade eeco rewires the eeco binary path, run `eeco hooks commit-msg refresh` to rewrite the on-disk wrapper without an off-then-on toggle. • commit-guard — the harness-layer companion to commit-msg. Where the git commit-msg hook guards eeco's own repository, the commit-guard installs a Claude Code PreToolUse hook that denies any pending git commit carrying AI attribution — in any repository the assistant drives, and not bypassable by git commit --no-verify (the hook sits above git). It runs the same attribution detector leak-guard uses, so the patterns stay one source of truth (the foreign repo's own attribution_pattern entries are honoured when its config loads). Default off; enable with eeco hooks commit-guard on, which installs a PreToolUse group into the JSON settings file named by session_settings_path (or EECO_SESSION_SETTINGS) — the same file the session-start JSON channel uses, backed up and re-validated the same way; it reports "not configured" when neither is set. The runner detects a real git commit token-by-token (so git status and echo "git commit" never fire), scans the assembled message (-m/-F/COMMIT_EDITMSG), the staged diff, and the raw command, and **denies only on a positive finding — any parse or infrastructure uncertainty degrades open** (the commit proceeds), so a session is never wedged; the git pre-commit / commit-msg hooks and CI remain the hard gates. off removes only eeco's group (foreign PreToolUse groups are preserved); after a brew upgrade eeco run eeco hooks commit-guard refresh to rewrite the binary path. Every action is recorded in <workspace>/state/hooks.json so it can be cleanly undone. The git-hook scripts and the JSON-settings writes — the session-start and commit-guard entries plus any session_files blocks — are the only touches eeco ever makes outside the gitignored workspace. 9a. Gates — composed read-only policy checks ──────────────────────────────────────────── eeco gates check-attribution is a CI-facing companion to the commit-msg hook (§9). The hook blocks at the source on a developer machine; the gate is the CI backstop that catches a leak when a developer bypassed the hook (--no-verify) or never installed it. Both share the same trailer-anchored pattern set so prose discussing the policy never false-fires. Scope: • Tracked-file scan — broad: delegates to the same detector comment-hygiene uses (line-anchored Co-Authored-By:, the Generated with/by <ai-ish> co-marketing line, and the robot-emoji Generated signature). Enumerates the file list from git ls-files and filters to a built-in text-extension allowlist (.md, .sh, .go, .zig, .S, .inc, .zon, .yml, .yaml, .txt, .ld, .json, .toml). Hits print as path:line: excerpt. • Commit-body scan — strict trailer-anchored: Co-Authored-By: lines naming claude, anthropic, or noreply@anthropic, plus the robot-emoji "Generated" signature. Default range is origin/main..HEAD; falls back to HEAD~10..HEAD with a stderr notice when origin/main is unresolvable (fresh clone, detached HEAD, initial commit). Hits print as `commit <short-sha>: line N: excerpt`. Flags (all optional): ┌───────────────────┬───────────────────────────────────────────────────────────────────────────┐ │ Flag │ Effect │ ├───────────────────┼───────────────────────────────────────────────────────────────────────────┤ │ --paths "<a b c>" │ override the tracked-files filter; pass an explicit space-separated list. │ │ --commits N │ force HEAD~N..HEAD instead of the default range. │ │ --no-commits │ skip the commit-body scan (file-only). │ │ --no-files │ skip the file scan (commits-only). │ │ --exclude <path> │ repeatable; repo-relative path to skip during the file scan. │ └───────────────────┴───────────────────────────────────────────────────────────────────────────┘ Exit codes: 0 clean, 1 on any hit (sets stderr with one line per finding plus a N finding(s) summary), 2 on usage error. The CI invocation pattern is one step before git push-eligible builds: - name: ai-attribution gate run: eeco gates check-attribution Use actions/checkout@v5 with fetch-depth: 0 so the commit-body range resolves; default 1 makes origin/main..HEAD empty and the fallback notice triggers. 10. Safety guarantees ───────────────────── • eeco writes only inside the repo's gitignored workspace; a path guard enforces this and refuses .. traversal. • It never commits or pushes your project's tracked tree. The optional private workspace-history repo (see §11a) commits only inside the gitignored workspace, locally, and is never pushed. • No AI-attribution string is ever written to a tracked file. • Everything it does is invoked by you or queued for you. 11. Removing eeco from a project ──────────────────────────────── eeco uninstall writes a single eeco-handoff.md at the repository root summarising what eeco knew about the project, then prints the git command to remove the workspace by hand. It never deletes anything itself, so nothing is lost if you change your mind. eeco uninstall # bare handoff (just paths + removal command) eeco uninstall --scope facts # + memory facts eeco uninstall --scope queue # + open queue items eeco uninstall --scope everything # + facts + queue + scaffolded workflows + hooks The handoff file is written at the repository root, alongside your tracked tree; the file itself is not gitignored, so you choose whether to keep, commit, or delete it. The workspace is gitignored, so a single git rm -rf .eeco (substitute your workspace name) is the only on-disk removal needed once the handoff has been reviewed. Turn opt-in hooks off first (eeco hooks pre-commit off, eeco hooks session-start off) so the reversibility ledger can do its work before the workspace goes. If the private workspace-history repo exists (§11a), eeco uninstall offers to de-init it — removing only its .git, never your data — after a confirmation prompt. Pass --yes to skip the prompt, or decline to keep the history and remove it yourself later. Your workspace data files are never deleted by eeco uninstall. 11a. Workspace history (the private logbook) ──────────────────────────────────────────── At eeco init, eeco stands up a **private, local git repository inside its own gitignored workspace directory** (<username>/) to version its knowledge layer — memory facts, the queue, decisions, manifests — over time. This repository has no remote and is never pushed, and it never touches your project's tracked tree: it records only what eeco already writes inside its own gitignored workspace, so it is invisible to your project's git. The workspace_history config key controls it: • manual (default) — the repo exists; eeco commits only when you run eeco history snapshot. • auto — as manual, plus eeco commits automatically after each mutating verb (add fact/note/task, gc, go --write, run, new, …); still local-only, no remote. • off — no private repo at all. eeco init # creates the private repo (manual) eeco init --no-track # skip it for this run eeco history # show the recent commit log eeco add note "decided X" # mutate the workspace eeco history snapshot # commit the current state eeco history snapshot -m "milestone" # …with a message eeco history compact --dry-run # preview: how many commits would collapse eeco history compact # squash the whole log into one (confirms first) eeco history compact --yes # …without the prompt Under auto the log grows a commit per mutating verb, so it can get long. eeco history compact squashes the entire history into a single commit whose contents are the current workspace state — the git pendant to the docs-compaction protocol. Your workspace files are never touched (only the commit log is collapsed), and the old commits stay reachable through the git reflog, so the squash is recoverable; eeco runs no git gc. It is manual only — there is no auto-trigger — and it confirms before rewriting unless you pass --yes; --dry-run reports the count and changes nothing. The repo is created opt-out (--no-track for one run, or workspace_history=off durably) and removed at eeco uninstall (§11). Inside it eeco has a free hand — commit, and later squash — because nothing there is shared or tracked by the host repo. 12. Filing bug reports ────────────────────── eeco report-bug captures friction with eeco itself into a structured Markdown record and prints a pre-filled GitHub Issues URL so the report can reach the project in one click. The command works for everyone: anyone who installed eeco can file, with or without an initialised workspace. eeco report-bug --note "leak-guard tripped on a doc-only commit" \ --cmd "eeco run leak-guard" Both flags are optional. The record contains the eeco version, a whitelisted environment snapshot (OS, arch, Go version, SHELL, TERM, and any EECO_* variables — never the full env), the note, and the invoking command. Where the record lands: • Inside an initialised workspace. Records go to <workspace>/bug-reports/; override the directory with the bug_report_dir key in <workspace>/config.local (workspace- relative — absolute paths and .. traversal are rejected at parse time). • Anywhere else (no eeco init yet, or not inside a git repo at all). Records go to ~/.eeco/bug-reports/ so a fresh-install user can file a report against eeco itself without having to set anything up first. The repo's tracked tree is never touched. Sharing the record: eeco report-bug prints a pre-filled URL like https://github.com/ajhahnde/eeco/issues/new?title=...&body=.... Opening it in a browser fills the issue form with the record body already pasted — clicking Submit files it to the project. The local file is your durable copy; you can refine it before clicking, or attach it by hand if the URL ends up too long for the browser. Nothing is sent automatically — the upstream side of the loop is always a human click. Pass --submit to have eeco open that URL for you (the $BROWSER command if set, otherwise the platform default opener). It is opt-in and changes nothing else: the form opens pre-filled, you still review and click Submit, and the command still reports that nothing was sent automatically — opening a pre-filled form is not the same as sending. If no browser can be opened, the command prints a short note alongside the URL and still exits 0; --submit is a convenience, never a failure point. 13. Briefing an AI assistant ──────────────────────────── eeco go prints a compact, deterministic project brief written for an AI assistant. It is the fast, cheap way to bring any assistant — not only the strongest — up to speed on a project: one command returns a map of the project instead of a scan across many files. eeco go The brief has six sections: • Working with eeco — what eeco is, the read-only commands an assistant can run, and the rule that decisions go to eeco's queue rather than silent edits. • Project — the detected profile, the parse/build gate, and the top-level layout (taken from the tracked set, so build artifacts and the workspace stay out). • Where to look — every memory fact that records a file pointer, as a topic → file map. This is the assistant's shortcut to the right file. • What eeco knows — the load-bearing memory facts (project, feedback, user). • Open decisions — the items waiting in eeco's queue. • Recording back — how the assistant keeps the brief useful: record durable facts and route decisions through the queue. eeco go calls no AI provider — the brief is assembled entirely from what eeco already tracks, so it costs no provider budget and is safe to run any number of times. The output is deterministic: the same workspace state produces the same brief. The brief is Markdown by default — written for an assistant to read. The --json flag emits the same project state as a JSON object instead, the machine-readable form for a downstream agent or script that parses the brief rather than reading it: eeco go --json The JSON object has nine top-level keys — project, profile, gate (an argv array), top_level, initialized, workflows, where_to_look (description/ref objects), knowledge (name/description/type objects), and open_decisions. Every array is always present, an empty list rather than null, so a consumer can iterate without a nil check. These top-level keys are part of eeco's frozen public surface. --json prints to stdout and cannot be combined with --write. By default the brief is printed to stdout and nothing is written. The --write flag saves it instead to a stable file inside the workspace — .eeco/context.md by default — so an assistant's instructions file can point at a fixed path rather than re-running the command each session: eeco go --write # writes .eeco/context.md The destination is workspace-relative; override it with the context_path key in <workspace>/config.local (absolute paths and .. traversal are rejected). --write requires an initialised workspace, and the file it writes is byte-identical to the stdout brief. The file lives in the gitignored workspace, so it is never committed; re-run eeco go --write whenever you want it refreshed. For an assistant on a tight context budget the --brief flag reshapes the output: the "Working with eeco" preamble and "Recording back" outro drop out, and the per-section lists (Where to look, What eeco knows, Open decisions) are capped at five entries each. --brief composes with --json and --write, so every delivery axis gets the size knob: eeco go --brief # smaller Markdown brief eeco go --brief --json # smaller JSON brief eeco go --brief --write # writes the smaller variant In --brief --json the nine frozen top-level keys are preserved — arrays may simply be shorter, never absent or null — so a consumer that parses the JSON brief sees the same shape, never an unexpected key disappearance. To keep the persisted .eeco/context.md under a known size, set the context_budget key in <workspace>/config.local to a maximum byte count (roughly four bytes per token is a useful rule of thumb): context_budget=4000 # cap the --write brief at 4000 bytes When context_budget is set, eeco go --write trims the saved brief down a deterministic ladder until it fits: it tries the full brief first, then the smaller --brief form, then that form with the per-section lists capped progressively shorter (5, 4, 3, 2, 1, 0). It writes the largest tier that fits and reports which one — for example wrote .eeco/context.md (brief, 1840/4000 bytes). A context_budget of 0 (the default) means no cap. The budget applies only to --write; bare eeco go and eeco go --brief printed to stdout are unchanged. If the budget is so small that even the smallest tier overruns it, eeco still writes that smallest brief and prints a note — a brief slightly over budget beats no brief at all. To surface the recent free-form notes from eeco add note (§17) inside the brief, set the brief_include_notes key in <workspace>/config.local: brief_include_notes=true When enabled, eeco go adds a Recent notes section between What eeco knows and Open decisions, listing the five newest notes from <workspace>/notes/ with their UTC timestamp and first line. The section appears in Markdown output only — eeco go --json still emits exactly the nine frozen top-level keys (PUBLIC_API.md (PUBLIC_API.md) §"CLI commands and flags"), since notes belong to the assistant-prose channel rather than a parsed brief. The key accepts the standard strconv.ParseBool set — true/false, 1/0, t/f (in either case); a typo like yes/no is rejected at parse time so the operator notices. The default is false, so bare eeco go omits the section; the key composes with --brief, --write, and --copy exactly like the other sections. To wire the brief into a session, either point your assistant's instructions file at .eeco/context.md, or — if you use the bundled session-start hook (§9) — add session_start_docs=.eeco/context.md to config.local so the hook lists it in the reading routine automatically. Any assistant that can read a file or run a shell command can consume the brief; eeco assumes no particular tool. For a chat-only assistant — Gemini web, a Gem, AI Studio, ChatGPT, or any LLM behind a chat box — the --copy flag writes the brief to the host operating system's clipboard so you can paste it in one shot: eeco go --copy # full Markdown brief on the clipboard eeco go --copy --brief # smaller brief for a tight context window eeco go --copy --json # structured payload for a chat that parses JSON --copy works on macOS (pbcopy), Windows (clip.exe), and Linux (wl-copy on Wayland, xclip or xsel on X11). When none of those tools is on PATH eeco exits 2 with an install hint — the same "blocked: required tool missing" contract every other workflow follows. --copy does not compose with --write (one delivery axis per invocation); it does compose with --brief and --json. Re-run eeco go --copy whenever the project state has moved on. Measuring the brief — --metrics The --metrics flag adds a one-line readout to stderr after the brief, so you can see what the brief actually saved: eeco go --metrics eeco go: assembled in 412µs · brief 1840 bytes (≈460 tokens) · distilled ≈980 tokens of project knowledge into ≈460 (≈53% smaller) It reports three things: how long the brief took to assemble (real wall-clock), the brief's own size, and how much of the project's knowledge layer — the on-disk memory facts, the queue, and any notes — the brief distils. Byte counts are real measurements; token figures are estimates via the ~4-bytes-per-token heuristic and are marked with a leading ≈, never presented as exact counts (eeco ships no tokenizer, by design). The compression percentage is grounded in real on-disk bytes and is never reported below 0%. The readout goes to stderr, so it never mixes into the brief itself: eeco go --metrics > brief.md writes a clean brief to the file and prints the readout to the terminal. It always describes the **canonical Markdown brief** — even alongside --json or --copy, where it measures the Markdown brief the assistant would read — and it never appears in --json stdout, so the nine frozen top-level keys (PUBLIC_API.md (PUBLIC_API.md) §"CLI commands and flags") are untouched. With --write under a context_budget the readout still describes that canonical brief, not the budget-trimmed file that was persisted — the metric measures how much eeco's brief compresses the knowledge layer, a stable property, rather than one write's fitted size. --metrics is off by default and composes with every other flag. Briefing assistants other than Claude Code eeco's delivery channels are brand-free — point them at whichever assistant you use: • Gemini CLI (Google's terminal-native assistant) reads GEMINI.md at session start. Set session_files=GEMINI.md in <workspace>/config.local, then eeco hooks session-start on. Same recipe as Claude Code with CLAUDE.md. • OpenAI Codex reads AGENTS.md. Set session_files=AGENTS.md. • Cursor reads .cursorrules. Set session_files=.cursorrules. • Any other assistant whose instructions file lives at a known path: add that path as a session_files= line and eeco will keep a marker block in it (§9). For an assistant with no terminal and no filesystem access (Gemini web, Gems, AI Studio, ChatGPT, any chat box), eeco go --copy is the one-shot bridge — render the brief into the clipboard and paste it into the chat. Re-run when the project state moves on. Asking a targeted question Where eeco go is a one-shot overview, eeco ask answers a *specific* question with a ranked set of pointers — the interactive counterpart to the static brief: eeco ask "where is the project brief rendered" The answer has two sections: Memory — the memory facts whose name, description, or body overlaps the question, shown as a topic → file map when the fact carries a ref; and Code — the best-matching lines in the repository's tracked files, each as a path:line reference with the matching line. Results are ranked by how many distinct question words they match, with stable tie-breaks, so the same question over the same tree always gives the same answer. eeco ask --limit 3 "how does version-sync detect drift" # cap code hits eeco ask --json "queue" # machine-readable --limit N caps the number of code locations (default 10); every matching memory fact is always shown. --json emits an object with three frozen top-level keys — question, memory, code — both arrays always present, never null. Like eeco go, eeco ask calls no AI provider (relevance is a word-overlap score over what eeco already tracks), reads anywhere in the repo but writes nothing, and works in any git repository — the memory section is simply empty when the workspace is not initialised. Binary and very large files are skipped. 14. Applying an update ────────────────────── eeco update checks for a newer release and prints the gap, but does not download anything. The opt-in --apply flag turns it into a verified self-replace: download the platform release archive, verify its sha256 against the published SHA256SUMS, verify the cosign signature on SHA256SUMS, verify the GitHub build-provenance attestation on the archive, then atomically swap the running binary. eeco update --apply Verification gates. All three must pass before any swap. Any one failure leaves the running binary untouched and leaves the downloaded files in <workspace>/state/update-<tag>/ for inspection. • cosign verify-blob against the keyless certificate identity baked into the release workflow (refs/tags/v… on this repo). • sha256 of the downloaded archive equal to its line in SHA256SUMS. • gh attestation verify <archive> --repo ajhahnde/eeco. Requirements. cosign and gh must be on PATH. The command must run inside an initialised eeco workspace — <workspace>/state/ holds the staging directory, the backup, and the swap ledger (<workspace>/state/binary.json). The running binary must be on a released tag (v…); an unpinned 0.0.0-dev build refuses with a reinstall hint. Package-manager handoff. If the resolved running-binary path lives under a known package-manager root (Homebrew, Scoop, Linuxbrew), --apply refuses and points at the package manager's upgrade verb (brew upgrade eeco or scoop update eeco). Self-replace would fight the package manager on its next sync; the manager owns its prefix. Rollback. The previous binary is preserved at <workspace>/state/update-<tag>/eeco.bak (or eeco.exe.bak on Windows). To revert by hand: mv <workspace>/state/update-<tag>/eeco.bak <running-path> The exact <running-path> is recorded in <workspace>/state/binary.json under running_path. What stays the same. Bare eeco update (no flag) is unchanged: it still lists the gap and exits cleanly, without touching any binary. Constraint 6 holds — eeco only swaps when the operator passed --apply. 15. Reading the in-binary guide ─────────────────────────────── eeco guide pages the user manual built into the binary — a verbatim mirror of this file (docs/USAGE.md) at the tag the binary was built from. Every install route ships the manual offline; no network access needed, no doc directory to clone. eeco guide The pager selection is $PAGER first (split on whitespace; the first token must be on PATH), then less -R if less is available, then a plain stdout dump as the final fallback. When stdout is not a terminal (piped or redirected) the command always dumps the manual plainly and exits 0 — the same one-screen path the TUI uses for eeco with no arguments. At a terminal the manual is prettified for reading: Markdown tables become box-drawing grids, headings are styled with a rule, and inline code / bold / links are rendered rather than shown as raw markup. NO_COLOR drops the colour but keeps the layout. Piped or redirected output stays raw Markdown, byte-identical to docs/USAGE.md, so a script that captures the guide (eeco guide > usage.md) gets the source unchanged. Quick recipes. eeco guide # page interactively eeco guide | less # explicit pager pipeline eeco guide > usage.md # capture the embedded snapshot PAGER='less +/^## 4' eeco guide # jump straight to the commands table The embedded snapshot is locked to the binary version. Pair it with eeco update --apply to keep the manual in sync with the running release. The tracked-tree docs/USAGE.md and the in-binary guide stay byte-identical in CI — a release commit that forgets to re-sync the mirror fails the build. 16. Authoring tracked docs ────────────────────────── eeco docs new <target> seeds a tracked-tree documentation file at the repository root. Two targets ship today: ┌────────┬──────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ │ Target │ File written │ Purpose │ ├────────┼──────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤ │ vision │ VISION.md │ seed a short manifesto: what this project is for, what it gives you, what it deliberately is not, and where the roadmap lives │ │ readme │ README.md │ seed a new-reader-friendly README: tagline, what the project does, a quick-start recipe, and a short "how it works" │ └────────┴──────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ The scaffolder is deterministic — no AI call, no provider spend — and project-shape-aware: the rendered "See also" only links to companion docs that already exist (README.md, docs/USAGE.md, docs/ARCHITECTURE.md). The readme target's "See also" never self-links, so the link set narrows to docs/USAGE.md and docs/ARCHITECTURE.md. eeco docs new vision # write VISION.md (refuse if it exists) eeco docs new --overwrite vision # replace an existing VISION.md eeco docs new readme # write README.md (refuse if it exists) eeco docs new --overwrite readme # replace an existing README.md Refuse-on-existing is the default. Pass --overwrite to replace a prior scaffold or hand-edited file. **--overwrite discards the existing body** — use it deliberately, especially on a populated README.md. eeco writes the file but never stages or commits it (Constraint 6); review the result and run `git add <file> && git commit` yourself. The seed file carries a one-line HTML comment at the top marking it as a scaffold and naming the eeco version it was generated against. The comment is invisible in any rendered Markdown view and can be deleted in the same edit you fill the body in. eeco docs refresh <target> re-renders the project-state-derived region of a previously-scaffolded doc — the same project-shape-aware "See also" block eeco docs new rendered — leaving operator prose outside the marker pair untouched. The region is delimited by a pair of HTML-comment markers:  … rendered content …  Markers inside fenced code blocks are ignored, mirroring `eeco docs compact`. Unmatched, nested, or out-of-order markers exit 1 with a parse error naming the offending line; the file is not touched. A scaffold with no markers is auto-initialised: the freshly rendered block is appended at EOF, marker-wrapped, with a blank-line separator. The operator removes the prior in-place block manually. Where --overwrite on eeco docs new discards the entire body, refresh is the non-destructive complement. eeco docs refresh vision # re-render VISION.md's marker block eeco docs refresh readme # re-render README.md's marker block eeco docs compact <path> moves resolved regions of a long doc into a sibling archive file so the working copy stays short, then leaves a single-line pointer stub in place at each cut. A region is anything between a pair of HTML-comment markers:  … content to archive …  Markers inside fenced code blocks are ignored, so a doc explaining the markers (this very paragraph in the original docs/USAGE.md) does not trigger a self-archive. eeco docs compact roadmap_v1.x.md eeco docs compact --dry-run roadmap_v1.x.md eeco docs compact --archive history.md roadmap_v1.x.md The default archive destination is <basename>.archive<ext> next to the source — e.g. roadmap_v1.x.md → roadmap_v1.x.archive.md. Override the destination with --archive; pass a --dry-run to preview which line ranges would move without writing. Re-running after a successful compact is an idempotent no-op (`no archive markers found`); the archive is appended to on subsequent runs so a long-lived doc can be compacted in waves. Unmatched, nested, or out-of-order markers exit 1 with a parse error naming the offending line; the archive is not touched. Both paths must resolve inside the repository (absolute paths and .. traversal are rejected). eeco writes the source and the archive but never stages or commits either (Constraint 6); review both files and `git add` / commit when ready. For a log that grows by prepending a new section each time — a session journal, a changelog, a steering file — placing markers by hand every round is fiddly. --keep-last N discovers the archivable regions by heading instead. Pair it with --heading <prefix>, the heading-line prefix that opens an archivable section: eeco docs compact --keep-last 4 --heading "## Snapshot" RESUME.md This keeps the N most-recent matching sections — newest meaning topmost in the file — and archives everything older. The # run in --heading fixes the section level: a section runs from its heading to the next heading of the same or a higher level, so a live tail such as a trailing ## Next session or ## Pointers block is never swallowed. A deeper sub-heading inside a section does not split it, and (as in marker mode) any heading inside a fenced code block is ignored. Adjacent archived sections collapse into one pointer stub. --keep-last and explicit markers are mutually exclusive: running heading mode on a source that still carries a paired marker region exits 1 rather than mixing the two schemes. --keep-last requires --heading and vice versa. --dry-run and --archive work the same in both modes; re-running once only the kept window remains is an idempotent no-op. 17. Keeping notes ───────────────── A note is a place to scribble — a half-formed idea, a reminder, a thread to pick up later. It is deliberately neither a memory fact (frontmatter-strict, matched to AI relevance) nor a queue item (the append-only decision channel): routing scratch text into either of those pollutes their contract. Notes get their own surface. eeco add note "check round-robin fairness in queue promotion" eeco show notes eeco add note "<text>" saves the text verbatim to one plain Markdown file under <workspace>/notes/, named YYYY-MM-DD-HHMMSS-<slug>.md (the timestamp is UTC; the slug is derived from the text). The directory is created on first use, so a fresh eeco init is not required — being inside a git repository is enough. eeco writes only inside the workspace (Constraint 1) and never stages or commits (Constraint 6). eeco show notes lists every note newest-first, one row per note: the local date and time followed by the note's first line. An empty or absent notes directory prints a friendly hint and exits 0. This first slice is append + list only. To edit a note, open it in your editor ($EDITOR <workspace>/notes/<file>); to remove one, delete the file (rm <workspace>/notes/<file>).