---
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: "2026-09-06"
---

# mex

## What This Is
A local-first TypeScript CLI and browser Hub that turns repository code and agent knowledge into a tracked Wiki backed by disposable Graph and Wiki indexes.

## Non-Negotiables
- Tracked Markdown is canonical; never commit `.mex/graph.db*`, `.mex/wiki.db*`, or `.mex/local/`.
- Ordinary reads never repair, migrate, or initialize state; mutations and maintenance must be explicit.
- Keep the package-root API limited to intentional exports from `src/index.ts`.
- Never weaken containment, freshness, privacy, or bounded-work checks to make a test pass.
- MEX never stages, commits, pushes, or pulls on a user's behalf.

## Commands
- Dev: `npm run dev`
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

Use the smallest relevant structured resolver. For Inbox or Relay mutations, resolve only the intended action with `mex inbox contract --action <command-id> --json` or `mex relay contract --action <command-id> --json`; use `mex capabilities --json` only for broader capability discovery. If the user explicitly asks to create, save, or draft a checkout-local Inbox or Relay draft, preview and apply that exact draft without asking for redundant confirmation. Deleting a local draft, or publishing, approving, rejecting, withdrawing, marking stale, repairing, taking or acknowledging, or closing, requires fresh explicit confirmation after semantic preview. Treat Git commit, push, and pull as separate actions requiring their own authorization.

## Code Graph
The repo is indexed into `.mex/graph.db`. Use it as a bounded discovery tool alongside Grep/Glob.
- For an exact symbol, use `mex graph query <who-calls|what-calls|where-defined> <symbol>` and `mex graph get <id>`.
- For an unfamiliar task, start with `mex graph scope "<task>"`; treat its source as already read and inspect its evidence/status before relying on it.
- Scope matches words rather than meaning. If evidence is insufficient, use Grep/Glob instead of repeatedly rephrasing the same scope.
- Before editing a symbol, use `mex impact <symbol|file>` to inspect callers and grounded knowledge.
- Read broad, ground tight: only behavioral claims get exact node fingerprints and useful `mex://<nodeId>` anchors.
- During `mex sync`, adjudicate ambiguous grounding and verify refreshed grounding is emitted.

## Scaffold Growth
After meaningful work, run GROW: ground what changed, record state/context updates, orient with a reusable pattern when warranted, and write updated timestamps/rationale. See `ROUTER.md`.

Keep MEX-context acknowledgements concise and natural; name the specific file,
event log, entity, or Code Graph evidence used.

## 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.

<!-- mex-agent:skills:start -->
## MEX context policy
- When MEX context materially influences an answer or implementation, include one concise acknowledgement: `MEX context used: <specific records/files/entities consulted>.`
- Do not claim an author, date, or historical event unless the retrieved data actually provides it.
- After a MEX write, say exactly what changed and its sharing boundary: a local draft is checkout-only and nothing is shared; a canonical artifact is written to the working tree and requires commit/push to share.
- Skill activation is not approval for canonical actions.
<!-- mex-agent:skills:end -->