git:20260805.d641f6f to git:20260820.48da30c

5 added, 5 removed. Audit A to A.

---

name: agents

description: Always-loaded project anchor. Read this first. Contains project identity, non-negotiables, commands, and pointer to ROUTER.md for full context.

last_updated: [YYYY-MM-DD]

---

# [Project Name]

## What This Is

<!-- One sentence. What does this project do?

Length: 1 sentence maximum.

Not a tagline — a factual description of what the software does.

Example: "A REST API for managing inventory across multiple warehouse locations." -->

## Non-Negotiables

<!-- Hard rules the agent must never violate. Not preferences — rules.

These are the things that, if broken, cause real damage to the codebase.

Length: 3-5 items. More than 5 means the list has not been prioritised.

Example:

- Never write database queries outside of the repository layer

- Never commit secrets or API keys

- Always handle errors explicitly — no silent failures -->

## Commands

<!-- The exact commands needed to work on this project.

Include: run dev server, run tests, run linter, build.

Use the actual commands from this codebase — not placeholders.

For monorepos or projects with separate frontend/backend, group by area.

Target: keep this entire file under 150 tokens. For full-stack projects

with separate command sets, up to 200 tokens is acceptable.

Example:

- Dev: `npm run dev`

- Test: `npm test`

- Lint: `npm run lint`

- Build: `npm run build` -->

## Code Graph

The repo is indexed into `.mex/graph.db`. Use it to avoid re-reading code you already have — it is one tool alongside Grep/Glob, not a replacement for them.

- If you know the symbol name, go straight to it: `mex graph query <who-calls|what-calls|where-defined> <symbol>` and `mex graph get <id>` are exact and cheap. This is the strongest part of the graph. Give it exact names — an approximate name can return a confident wrong match.

- - Exploring an unfamiliar task? `mex graph scope "<task>"` returns a compact JSONL manifest (`meta`, `fact`s, `summary`). Scope matches on words, not meaning: if your phrasing does not share vocabulary with the code, results will be weak. Treat it as a starting point, never as a complete answer.

- - If the manifest does not clearly contain what you need, use Grep/Glob instead. Do not expand node ids that look irrelevant, and do not re-run `scope` with reworded phrasing more than once — that costs more than searching directly.

- - Treat any source the graph DOES return as ALREADY READ; do not re-open those files.

- - Pick 1-3 relevant node ids from the manifest and expand only those with `mex graph get <id> --detail source`.

+ - Exploring an unfamiliar task? `mex graph scope "<task>"` returns bounded, source-backed JSONL context plus trustworthy execution flows. Scope matches on words, not meaning, so treat it as starting evidence rather than a complete answer.

+ - Treat source returned by the graph as ALREADY READ; do not re-open those files.

+ - Read the summary status and evidence. `status: "ok"` remains usable when `truncated: true`; only optional evidence was omitted. For `partial` or `degraded`, narrow the task or follow `suggestedNextCommands`.

+ - Use `mex graph get <id> --detail source` only when source is missing, you need exact expansion, or a partial/degraded summary suggests it. Do not expand nodes by quota.

+ - If the evidence is insufficient or the task wording does not match the code, use Grep/Glob instead. Do not re-run `scope` with reworded phrasing more than once.

- Before editing a symbol, run `mex impact <symbol|file>` to see affected callers and scaffold memory.

- - If a result is `truncated`, do NOT repeat the broad query — narrow the task or use the summary's `suggestedNextCommands`. Scale through a few focused calls, never one giant response.

- During `mex sync`, adjudicate any AMBIGUOUS grounding; after repairs, ensure the refreshed grounding is re-emitted.

## Scaffold Growth

After meaningful work, run GROW:

- Ground: what changed in reality?

- Record: update `ROUTER.md` and relevant `context/` files

- Orient: create or update a `patterns/` runbook if this can recur

- Write: bump `last_updated` on changed scaffold files and run `mex log` when rationale matters

The scaffold grows from real work, not just setup. See the GROW step in `ROUTER.md` for details.

## Navigation

At the start of every session, read `ROUTER.md` before doing anything else.

For full project context, patterns, and task guidance — everything is there.