commands.md

SourceCompass commands and config

Every command is run as node eb.mjs <command> from the toolkit folder. Every command after init takes --in <name> and --repo <checkout>. Without --in, the tool uses your only instance, or the demo, but never inside a different repository: there it refuses and asks you to choose. The demo instance is named demo.

Command	What it does
demo	Build the made-up demo instance
init --repo <path> [--name n] [--build]	Draft a config for your repo (read-only); optionally build
build --in <name>	Rebuild the map (no model calls)
open --in <name>	Rebuild if stale, then open the viewer. From another checkout, a map that is stale for it is refused (use brief or q there)
context --in <name>	Which repo am I in; is the map fresh?
map --in <name>	Short overview for agents
q "<words>" --in <name>	Short cited answer
show <ID> / impact <path>	A full record / what depends on a file
brief <topic words>	Planning capsule: status, plan-file status, what to re-verify, files to read
place <feature words>	Where a new feature belongs: its module (built or still missing), app and menu, layers and links
arch [<module>] [--section dw|eval|gaps|…|all] [--full]	The target module map; a module card lists every requirement id and status, 40 requirement lines per page with each text shortened, unless you ask for a section. Paging limits the requirement lines, not the size: a long single field, such as the goal, is printed in full
req <id>	One requirement in full: status, approval, history, the planned evaluations that name it (plans, not proof), recorded evidence and the review findings mapped to it
propose --id <id> --expect-rev <n> --file <text> --why <reason> / proposals	A revision-checked change proposal (refused when the revision moved on, or while the design files changed since the last build; competing and stale proposals are flagged); it never edits the design
proposals resolve --file <name> --as accepted|rejected|superseded --by <who> [--why …] / proposals --all	Record how a proposal ended (accepted only once the design holds its exact text); the record is kept. proposals lists pending ones only
evidence add --req <id> --expect-rev <n> --status … --layer … --env … --source-sha … --receipt … / evidence list	Record a check against one requirement revision; it shows only its layer and does not transfer to another revision. Never edits the design and never makes the map stale
findings [<finding id>] [--source id] [--disposition d]	Review findings: coverage per source and the unresolved ones, or one finding traced to its source, requirement revision, evaluations, evidence and owner
example [<id>]	A worked example as text
module <id> / workflow [id] / lifecycle	Module, workflow (or the catalog list) or lifecycle view as text
status / which-build <sha>	Freshness / is the map about that build?
agent-snippet --for claude|codex|any	Instructions to paste for your agent
agent-setup --for … --file <path> [--dry-run] [--remove]	Install or remove those instructions as one managed block
export-obsidian, export-ua	Linked notes and canvas maps for Obsidian; a projection for the Understand-Anything viewer, with a report of what the projection loses. Exports of a stale map are refused unless you pass --allow-stale

The routine an agent follows is in AGENT-CONTRACT.md.

Adapting the config

init writes instances/<name>/brain.config.json. The main fields:

• policy: which files may be read.
• surfaces: each app. A router surface is a React Router app. A reducer surface is a phone app that switches screens in a reducer; see demo/sample-files.mjs → DEMO_CONFIG for a complete example.
• dataRoots, consumerRoots, migrations, syncRules: where data code, tests, migrations and sync rules live.
• globalFiles: files whose change makes the whole map stale. To limit one to a single app, write { "glob": "apps/mobile/src/Shell.tsx", "surfaces": ["field"] }, and only when that app truly cannot affect the others. Folder position alone proves nothing.
• ledger: optional { "file": "docs/PLAN.md" }, a markdown checklist in your repo (- [x] ID: text). brief reads it at HEAD and reports each linked id as OPEN, DONE or NOT IN PLAN FILE. It never edits it.
• vocabulary: your team's words for things, e.g. "daily log": ["log entry"].

Then run node eb.mjs build --in <name>.

What init detects

• React Router route files (JSX <Route> trees);
• navigation config files;
• data folders;
• tests and migrations.

It prints everything it guessed, so check instances/<name>/brain.config.json once. Two things it cannot detect yet: phone apps that switch screens with a reducer (write the reducer surface by hand, see above), and routes written as objects with createBrowserRouter.

What the viewer and the design inputs hold

Most of these need a file you write in instances/<name>/intent/. None is discovered from code.

• What people do: jobs such as "Plan tomorrow's crews" → the screens involved.
• Start to finish: every stage of the work, each item marked built, partial or missing, plus the chains that must connect. Either write a simple board (intent/lifecycle.json) or a workflow catalog (intent/workflows.json). A catalog says, for each workflow, who does it and who approves it, every allowed state change and whether the server must enforce it, timers, exceptions, offline behaviour, what AI may draft and must never decide, and a pass/fail acceptance test. When a catalog exists, the board is built from it, so the two never disagree.
• App modules: the app as its team knows it, taken from its own navigation. Each module shows written intent next to what the code does, and flows marked found, gap, partial or undocumented. Add a target architecture (intent/architecture.json) and the same tab gains a Target: start to finish map: every module the work needs, built or still missing, placed by stage and by app, with the ways work and data move between modules. A table shows whether each layer is built (field app, office app, shared logic, backend, sync), and you can follow an end-to-end path to its first break. The build checks the file: every workflow must have exactly one home module, and every module that exists today must be placed.
  • Optionally, each module can carry a contract: its goal, what "done" looks like, how each item is proven, what exists, and each gap with how it closes and who owns it. Contracts are all or nothing: once one module has one, every module needs one. Shared rules (contractRules) show up on the card of every module they bind.
  • A field-app charter says who uses the phone app, where they work, and what each module puts on the phone (PHONE, PHONE-LITE or OFFICE ONLY). The build flags a charter that disagrees with a module's placement or goes over its tab limit.
• Platform: optional (intent/platform.json). The internal contracts the product relies on (models, storage, queues, sync, notifications, connectors and so on): what exists today, which adapter serves the pilot, how you would leave that vendor, and when it is needed. A roadmap shows growth stages, each with the measurable trigger that starts the next. The build flags a contract with no owner, exit plan or proof, and a coverage gap with no owner.
• How work moves: role swimlanes for workflows you describe, with exception paths. Intended, implemented and observed stay separate.
• Worked example: optional (intent/examples.json). One job walked step by step: who acts where, what record and state change, what travels in sync, what the other side sees, and how built it is today (built, partly built, not built, built unsafely, or off the app), with evidence, the requirements that govern it, and the dead ends. The demo has one.
• Findings, requirements, Trace and Maps: see traceability.md.
• Screens: area → screen → button → handler → data → table, with file:line at every hop.
• Technical: file → affected screens, tables and tests; dead links; sync buckets.