mex-memory · theDakshJaitly · Sep 2, 2026 · Sep 2, 2026 · Sep 2, 2026
diff --git a/.mex/.tool-configs/CLAUDE.md b/.mex/.tool-configs/CLAUDE.md
@@ -59,6 +59,7 @@ For full project context, patterns, and task guidance — everything is there.
 
 <!-- mex-agent:skills:start -->
 ## MEX agent skills
+- At the start of every session, read `.mex/AGENTS.md` and `.mex/ROUTER.md` before project work; follow `ROUTER.md` to load only the relevant context.
 - Use `/mex-inbox` for durable governed Spec proposals and `/mex-relay` for durable team handoffs. Invoke them automatically when intent clearly matches; explicit invocation remains available.
 - 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.

diff --git a/.mex/ROUTER.md b/.mex/ROUTER.md
@@ -14,7 +14,7 @@ edges:
     condition: when setting up the dev environment or running the project for the first time
   - target: patterns/INDEX.md
     condition: when starting a task — check the pattern index for a matching pattern file
-last_updated: 2026-09-01
+last_updated: 2026-09-02
 ---
 
 # Session Bootstrap
@@ -26,6 +26,11 @@ Then read this file fully before doing anything else in this session.
 ## Current Project State
 
 **Working:**
+- Fresh-user setup is now a release-complete path: it preserves authored
+  scaffold files, protects disposable Graph/Wiki/local state from Git, launches
+  the first selected available Claude Code or Codex CLI from the repository
+  root, captures grounding, migrates and indexes Wiki content, validates the
+  result, and prints the required canonical commit checkpoint before Hub.
 - MEX v0.7.3 graph extraction and protocol-v3 JSONL behavior, including
   sequential TypeScript programs, compiler crash isolation, explicit WASM tree
   disposal, compact fingerprints/LSH, and bounded repair.

diff --git a/.mex/SETUP.md b/.mex/SETUP.md
@@ -10,11 +10,14 @@ This scaffold is currently empty. Follow the steps below to populate it for your
 mex setup
 ```
 
-The command handles everything automatically:
-1. Detects your project state (existing codebase, fresh project, or partial)
-2. Asks which AI tool you use and installs the right project instructions
-3. Pre-scans your codebase with `mex init` to build a structured brief (~5-8k tokens vs ~50k from AI exploration)
-4. Builds and runs the population prompt — or prints it for manual paste
+The command handles the setup workflow:
+1. Detects your project state without overwriting existing scaffold files
+2. Protects `.mex/graph.db*`, `.mex/wiki.db*`, and `.mex/local/` from Git
+3. Asks which AI tool you use and installs the right project instructions
+4. Scans the codebase and builds the local code graph
+5. Launches the first selected available Claude Code or Codex CLI, or prints the prompt for manual paste
+6. Captures grounding, migrates the populated Markdown, builds the Wiki index, and validates it
+7. Prints the canonical files to review and commit before running `mex hub`
 
 For Claude Code and Codex, setup also copies the packaged `mex-inbox` and
 `mex-relay` skills into the project. No plugin or separate skill installer is
@@ -222,6 +225,11 @@ Codex uses `$mex-inbox` and `$mex-relay`. Clear natural-language requests work
 too. Commit the project skill copies so teammates receive them; MEX never
 stages, commits, or pushes them automatically.
 
+Setup prints the scoped Git commands for the selected tools. Review those files
+and commit them before running `mex hub`; Hub requires `.mex/config.json` to
+match the version committed at the current Git `HEAD`. The local Graph/Wiki
+databases and `.mex/local/` remain ignored.
+
 **Verify** by starting a fresh session and asking your agent:
 "Read `.mex/ROUTER.md` and tell me what you now know about this project."
 
@@ -236,6 +244,6 @@ A well-populated scaffold should give the agent enough to:
 Once the scaffold is populated, use these to keep it aligned with your codebase:
 
 - **`mex check`** — detect drift (zero tokens, zero AI)
-- **`.mex/sync.sh`** — interactive drift check + targeted or full resync
+- **`mex sync`** — interactive drift check + targeted resync
 - **`mex skills sync`** — safely receive updated official agent skills after a package upgrade
 - **`mex watch`** — auto drift score after every commit
diff --git a/.mex/SYNC.md b/.mex/SYNC.md
@@ -1,12 +1,12 @@
 # Sync — Realign This Scaffold
 
-## Recommended: Use sync.sh
+## Recommended: Use `mex sync`
 
 ```bash
-.mex/sync.sh
+mex sync
 ```
 
-The script runs drift detection first, shows you exactly what's wrong, then offers:
+The command runs drift detection first, shows you exactly what's wrong, then offers:
 1. **Targeted sync** — AI fixes only the flagged files (fastest, cheapest)
 2. **Full resync** — AI re-reads everything and updates all scaffold files
 3. **Prompt export** — shows the prompts for manual paste

diff --git a/AGENTS.md b/AGENTS.md
@@ -1,5 +1,6 @@
 <!-- mex-agent:skills:start -->
 ## MEX agent skills
+- At the start of every session, read `.mex/AGENTS.md` and `.mex/ROUTER.md` before project work; follow `ROUTER.md` to load only the relevant context.
 - Use `$mex-inbox` for durable governed Spec proposals and `$mex-relay` for durable team handoffs. Invoke them automatically when intent clearly matches; explicit invocation remains available.
 - 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.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,6 +28,10 @@ All notable changes to this project will be documented in this file.
   overwriting user instructions, modified managed copies, or unrelated skills.
 
 ### Changed
+- `mex setup` now preserves existing scaffold files, launches the first selected
+  available Claude Code or Codex CLI from the project root, completes Wiki
+  migration/indexing after population, and stops at an explicit Git commit
+  checkpoint before Hub.
 - The integration graph uses schema v4: v0.7.3's compact BLOB fingerprints and
   integer-reference LSH storage combined with subject-generalized Wiki
   grounding. The v0.7.3 sequential compiler, crash isolation, fallback, and
@@ -38,6 +42,19 @@ All notable changes to this project will be documented in this file.
 - Inbox and Relay contracts now support bounded action-scoped discovery while
   preserving the existing complete contract catalogs for compatibility.
 
+### Fixed
+- Fresh setup now installs and verifies ignore protection for Graph/Wiki
+  databases and `.mex/local/`, refuses broad rules that hide canonical config,
+  and no longer overwrites authored files merely because they contain template
+  examples or date placeholders.
+- Setup now refuses malformed or redirected canonical config, publishes config
+  updates atomically, honors Wiki exclude/read-only scope, and blocks readiness
+  when authored grounding cannot be verified.
+- Claude Code and Codex population now uses an ignored prompt file with a short
+  launcher argument, avoiding Windows command-line length limits.
+- New Claude Code and Codex root instructions bootstrap `.mex/AGENTS.md` and
+  `.mex/ROUTER.md` on later sessions instead of installing only skill policy.
+
 ### Compatibility
 - Explicit graph maintenance recognizes v1, v2, released-main v3,
   integration-grounding v3, and complete hybrid v3 stores structurally. v2 and

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -1,5 +1,6 @@
 <!-- mex-agent:skills:start -->
 ## MEX agent skills
+- At the start of every session, read `.mex/AGENTS.md` and `.mex/ROUTER.md` before project work; follow `ROUTER.md` to load only the relevant context.
 - Use `/mex-inbox` for durable governed Spec proposals and `/mex-relay` for durable team handoffs. Invoke them automatically when intent clearly matches; explicit invocation remains available.
 - 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.

diff --git a/README.md b/README.md
@@ -222,7 +222,7 @@ mex requires Node.js 22.5 or newer. The npm package is named `mex-agent` because
 npx mex-agent setup
 ```
 
-Setup inspects the repository, builds the local code graph, creates the Markdown wiki, asks your coding agent to populate it from graph evidence, installs the right project anchor and official MEX skills, and validates the result.
+Setup protects checkout-local databases from Git, builds the code graph, asks your selected Claude Code or Codex CLI to populate the Markdown scaffold, migrates and indexes the Wiki, installs the project anchor and official MEX skills, and validates the result. It then prints the commit checkpoint required before Hub can start.
 
 ### Official Claude Code and Codex skills
 
@@ -231,7 +231,7 @@ The `mex-agent` npm package ships two official project skills from one canonical
 - `mex-inbox` prepares governed Spec, requirement, constraint, and acceptance-criterion proposals.
 - `mex-relay` prepares durable team handoffs.
 
-The normal `mex setup` flow installs copies for every selected supported agent; no separate plugin or skill installer is required. Claude Code receives `.claude/skills/mex-inbox` and `.claude/skills/mex-relay`, while Codex receives `.agents/skills/mex-inbox` and `.agents/skills/mex-relay`. Selecting both agents installs both sets and updates only the marker-delimited MEX block in `CLAUDE.md` and `AGENTS.md`.
+The normal `mex setup` flow installs copies for every selected supported agent; no separate plugin or skill installer is required. Claude Code receives `.claude/skills/mex-inbox` and `.claude/skills/mex-relay`, while Codex receives `.agents/skills/mex-inbox` and `.agents/skills/mex-relay`. Selecting both agents installs both sets and updates only the marker-delimited MEX block in `CLAUDE.md` and `AGENTS.md`. That managed block also directs every new agent session to read `.mex/AGENTS.md` and `.mex/ROUTER.md` before project work.
 
 Invoke the skills explicitly as `/mex-inbox` and `/mex-relay` in Claude Code, or `$mex-inbox` and `$mex-relay` in Codex. Clear natural-language requests for governed Spec proposals or durable handoffs invoke them automatically as well.
 
@@ -249,10 +249,13 @@ A standalone Codex plugin or marketplace package may be added later, but it is n
 After setup:
 
 ```bash
+git status --short            # Review the canonical MEX files
+git add .mex                  # Local Graph/Wiki databases stay ignored
+git commit -m "chore: initialize MEX"
 mex check                    # Check wiki health and code grounding
 mex sync                     # Repair drift with targeted agent prompts
 mex graph scope "<task>"     # Retrieve compact task context
-mex hub                      # Open the local Project Hub
+mex hub                      # Opens after .mex/config.json is committed at HEAD
 ```
 
 If you skipped global installation, use `npx mex-agent` in place of `mex`. Install globally at any time with: