@pharaoh-so/mcp 0.3.26 → 0.3.27

package/commands/plan.md

@@ -39,11 +39,12 @@ Do NOT review from memory or assumptions. Query the actual codebase first.
 ### If Pharaoh MCP tools are available:
 
 1. `get_codebase_map` — current modules, hot files, dependency graph
-2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
-3. `get_module_context` on affected modules — entry points, patterns, conventions
-4. `query_dependencies` between affected modules — coupling, circular deps
-5. `get_blast_radius` on the primary target of the change — know what breaks
-6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
+2. `get_vision_docs` — read the repo's architectural contract. If the plan touches a domain with a MUST-bullet, the assertion is a hard constraint on the plan. Raise it explicitly in Section 1. If `get_vision_docs` returns an empty-state scaffold, flag that the repo needs `/pharaoh:vision` before planning anything architectural.
+3. `search_functions` for keywords related to the plan — find existing code to reuse/extend
+4. `get_module_context` on affected modules — entry points, patterns, conventions
+5. `query_dependencies` between affected modules — coupling, circular deps
+6. `get_blast_radius` on the primary target of the change — know what breaks
+7. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
 
 ### Without Pharaoh (graceful fallback):
 
@@ -71,10 +72,17 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
+- **Vision alignment (check FIRST).** Does this plan touch a domain
+  governed by a MUST-bullet in `docs/VISION.md`? If yes, quote the
+  assertion and verify the plan doesn't violate it. If the plan would
+  violate a MUST, STOP and raise with the user — either the plan changes
+  or VISION.md needs an update first (with user approval).
 - Component boundaries and coupling concerns
 - Dependency graph: does this change shrink or expand surface area?
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
+- **If this plan introduces a new invariant**, call it out and include a
+  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 

package/commands/review.md

@@ -65,7 +65,8 @@ Then call these additional tools for data recon doesn't cover:
 - `get_regression_risk` — overall change risk score for the repo
 - `get_consolidation_opportunities` — duplicate logic the PR may introduce
 - `check_reachability` — are new exports wired to entry points?
-- `get_vision_gaps` — do changes align with or drift from specs?
+- `get_vision_docs` — read the repo's architectural contract. For every touched module, pull its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
+- `get_vision_gaps` — do changes align with or drift from specs? New complex functions without a matching assertion are flagged; retired specs with implementing code are flagged.
 
 **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, regression risk level, duplication findings, reachability status, and spec alignment.
 
@@ -249,7 +250,8 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 - Unreachable exports (new public code with zero callers)
 - New circular dependencies between modules
 - HIGH regression risk without corresponding test coverage
-- Vision spec violations (building against spec intent)
+- **A MUST-bullet in `docs/VISION.md` is violated by this change** (without VISION.md being updated in the same PR with user approval)
+- Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
 - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
 - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
 - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)

package/commands/vision.md

@@ -0,0 +1,184 @@
+---
+description: Draft a VISION.md for this repo by filling a graph-derived scaffold
+---
+
+# Vision Drafting
+
+Author a VISION.md that captures this repo's invariants — what must always be
+true about its behavior. The file becomes a machine-readable contract that
+Pharaoh's linter, PR Guard, and MCP tools reason against on every change.
+
+## Why this matters (explain this to the user before drafting)
+
+A VISION.md is leverage, not paperwork. Once the repo has one:
+
+- **PR Guard** checks every pull request against its assertions. Changes that
+  contradict a MUST-bullet surface as a Check on the PR — the team sees drift
+  from intent at the exact moment it happens, not months later.
+- **`get_vision_gaps`** becomes useful. Pharaoh cross-references every spec
+  against the function graph and surfaces both sides of the drift: specs
+  without implementing code (dead intent) and complex functions with no spec
+  (invisible invariants).
+- **`get_vision_docs`** returns spec-to-code traceability. Each assertion
+  shows the functions that implement it — a direct map from intent → code.
+- **CI enforces it.** Every MUST bullet pairs with a TEST reference. The
+  linter fails when an assertion has no enforcing test. No more wishlist
+  specs that drift over time.
+
+Without a VISION.md, the tools above return empty. The graph sees code; it
+doesn't see intent. The file is the bridge.
+
+## When to Use
+
+- The repo has no `docs/VISION.md` yet and the user wants Pharaoh's full
+  value — PR Guard, vision-gaps, spec traceability all depend on the file.
+- `get_vision_docs` returned the "No VISION.md yet" onboarding response.
+- The user said "draft a vision doc", "add a VISION.md", or "scaffold vision".
+- A user is new to Pharaoh and asking what they should do next.
+
+## The flow — collaborative, not solo
+
+This is a short working session with the user. Do not solo-fill the scaffold
+— the graph can tell you the shape of the code, but only the user knows what
+must not break. Ask questions, propose, let them steer.
+
+1. **Get the scaffold.** Call `get_vision_docs` with the repo name. When no
+   vision doc exists, the tool returns a deterministic scaffold plus the
+   agent directive. Use that as your starting structure. Never invent a
+   scaffold from scratch; the archetypes encode Pharaoh's framework shape
+   and drift is surfaced by the framework-linter.
+
+2. **Interview the user.** Before filling anything, ask: *"What are the 3-5
+   things about this repo that must not break, no matter what?"* Their
+   answer drives the assertions. If they can't articulate it, probe with
+   follow-ups — "what would a P0 incident look like here?", "what would
+   wake you up on a weekend?". The goal is to extract real invariants, not
+   to generate plausible-sounding ones from graph evidence.
+
+3. **Ground each domain in real code.** For every `## Domain` the scaffold
+   rendered, call `get_module_context` for the module(s) that back that
+   domain. For example, an "Authentication and Authorization" domain →
+   `get_module_context` on the auth module + any session/token modules.
+   Read the exported functions, endpoints, env vars, and DB access.
+
+4. **Replace TODOs with WHAT statements.**
+   - Every `### TODO:` heading becomes a real assertion title. Describe the
+     invariant in plain language — "Sessions expire after 30 minutes of
+     inactivity", not "checkSession() returns null after timeout".
+   - Every `- MUST: TODO —` bullet becomes a WHAT statement. Banned
+     content: function names, file paths, class names, identifiers.
+   - Add a `- TEST: path/to/test.ts` line for every assertion. If the test
+     doesn't exist yet, write it before committing. A MUST without a TEST
+     is not an invariant, it's a wish.
+
+5. **Trim irrelevant domains.** If a rendered `## Domain` doesn't match
+   anything real in this repo, delete that whole section. The scaffold is a
+   starting point, not a contract to honor exhaustively.
+
+6. **Write the file.** Save to `docs/VISION.md` in the repo. Remove the
+   `<!-- scaffold-generated -->` marker and the `<!-- AGENT DIRECTIVE -->`
+   block once every TODO is resolved.
+
+7. **Wire it into CLAUDE.md.** This is non-negotiable — it's what turns the
+   vision doc from a file on disk into a contract future sessions respect.
+   If `CLAUDE.md` exists at the repo root, append (or edit) a section:
+
+   ```markdown
+   ## Vision docs
+
+   `docs/VISION.md` is this repo's architectural contract. Before any
+   non-trivial change, call `get_vision_docs` to read the relevant
+   assertions. After any large refactor, run `get_vision_gaps` to surface
+   drift between intent and implementation. When adding a new invariant,
+   open `docs/VISION.md`, add a `### assertion` under the right `##` domain,
+   and pair every `- MUST:` with a `- TEST:` referencing the enforcing test.
+
+   Never introduce code that would violate a MUST-bullet without first
+   updating `docs/VISION.md` (with the user's approval).
+   ```
+
+   If no `CLAUDE.md` exists, create a minimal one with the section above
+   plus any project-specific instructions you already have context for.
+
+8. **Verify.** Run `pharaoh vision lint --framework` (or instruct the user
+   to). Zero errors. Zero TODO warnings. Zero unresolved placeholders.
+
+## Hard rules
+
+- **No HOW in MUST bullets.** Banned: function names, file paths, camelCase
+  identifiers, backtick-wrapped code. The linter enforces this as a warning;
+  treat it as a hard rule.
+- **Every MUST needs a TEST.** The format-linter errors if a MUST bullet
+  has no matching TEST reference to an existing file.
+- **One MUST per line.** Don't pack multiple invariants into a single bullet.
+- **Max 10 prose lines per assertion.** Keep each `###` section tight.
+- **Mirror Pharaoh's canonical domains when they fit.** Rename only when the
+  user's project truly has a different shape. The framework-linter warns on
+  unrecognized domains so drift is visible.
+
+## What to avoid
+
+- **Do NOT** write VISION.md from scratch without calling `get_vision_docs`
+  first — you'll miss domains the graph detected and duplicate ones it
+  already included.
+- **Do NOT** carry forward the AGENT DIRECTIVE or scaffold-generated marker
+  into the committed file. Those are drafting aids, not document content.
+- **Do NOT** write speculative assertions ("sessions will expire someday").
+  Only assert what the code enforces today or what you'll commit a test for.
+- **Do NOT** use `pharaoh vision init` — that only drops the format guide,
+  not a graph-grounded scaffold. Always go through `get_vision_docs`.
+
+## Completion checklist
+
+- [ ] User was interviewed for their real invariants (not graph-guessed)
+- [ ] Every rendered `## Domain` either has ≥1 real assertion or was deleted
+- [ ] Every `### TODO:` heading replaced with a real title
+- [ ] Every `- MUST: TODO —` replaced with a WHAT statement
+- [ ] Every assertion has a `- TEST:` line pointing at an existing test file
+- [ ] Scaffold marker + AGENT DIRECTIVE block removed
+- [ ] `CLAUDE.md` updated (or created) with the Vision docs section
+- [ ] `pharaoh vision lint --framework` exits clean
+
+## After it ships — tell the user what they unlocked
+
+Once `docs/VISION.md` is committed, call out the new capabilities concretely:
+
+1. **Every future AI session reads it.** Because CLAUDE.md now references
+   `docs/VISION.md`, any agent working in this repo (Claude Code, Cursor,
+   anyone else connecting Pharaoh) will consult the file before touching
+   architecture. Continuity across sessions, across people, across tools.
+2. **`get_vision_docs`** now returns spec-to-code traceability per
+   assertion. The user can see which functions implement each invariant.
+3. **`get_vision_gaps`** surfaces drift. Unspecified complex functions
+   get flagged; specs with no implementing code get flagged for review
+   (either write the code or retire the spec).
+4. **Their next PR is checked.** PR Guard now evaluates touched code
+   against relevant assertions. First-time use often catches real drift.
+5. **`/pharaoh:plan`** will surface relevant assertions during reconnaissance.
+6. **`/pharaoh:review`** will flag PRs that touch code governed by a MUST.
+
+The bigger payoff: architectural invariants are now enforced in CI the same
+way unit tests enforce behavior. Intent and implementation stop drifting.
+
+## Ongoing maintenance — it's a living file
+
+VISION.md rots if it's not maintained. Part of your job in future sessions
+(even ones that aren't about vision directly) is to keep it current:
+
+- **When a MUST changes**, update VISION.md in the same PR as the code
+  change. Don't let the file lag — stale assertions are worse than none.
+- **When a new architectural decision lands**, add a new `###` assertion
+  under the right `##` domain with a pairing TEST. One assertion per
+  decision, not batches.
+- **When an assertion stops being load-bearing**, delete it. Retirement is
+  as important as addition.
+- **When `get_vision_gaps` shows >5 unimplemented specs**, the doc has
+  drifted into wishlist territory. Prune.
+- **Quarterly**: run `pharaoh vision lint --framework` and address warnings.
+
+Format reference: https://pharaoh.so/vision-format.md
+---
+
+Here is any additional context for the vision draft:
+
+$ARGUMENTS

package/inspect-tools.json

@@ -207,7 +207,7 @@
     },
     {
       "name": "get_design_system",
-      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count, design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Where are raw HTML elements used instead of components?\"\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
+      "description": "Discover the design system BEFORE creating any UI component.\n\nCALL THIS WHEN:\n• You're about to create a React/Vue/Svelte component — check what already exists\n• You need to know the canonical component for a UI pattern (button, input, modal)\n• You want to find design tokens (colors, spacing, typography) to use\n• You suspect raw HTML elements are used instead of existing components\n\nRETURNS: Components with props and usage count (paginated), design tokens with values, and anti-patterns where raw HTML is used instead of existing components. Pass `path_pattern`, `name_prefix`, `offset`, or `limit` to narrow or page through results. Screen/page components are excluded by default.\n\nEXAMPLES:\n• \"What components does this design system have?\"\n• \"Is there already a Button component I should use?\"\n• \"What color tokens are available?\"\n• \"Show me all components in /atoms/\" → use path_pattern=\"/atoms/\"\n• \"Show me the next page\" → use offset=50\n\nWHY NOT JUST READ FILES: Design systems span dozens of files across multiple directories. This returns the complete inventory with usage frequency — the most-used components are the most canonical.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -231,6 +231,32 @@
             "default": false,
             "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
             "type": "boolean"
+          },
+          "path_pattern": {
+            "description": "Substring match against File.path (e.g. '/atoms/', '/ui/Button'). Narrows to components whose file path contains this exact substring.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "name_prefix": {
+            "description": "Exact prefix match against component name (e.g. 'Button' matches Button, ButtonGroup, ButtonIcon). Case-sensitive.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "offset": {
+            "default": 0,
+            "description": "Pagination offset (0-based). Capped at 10000.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10000
+          },
+          "limit": {
+            "default": 50,
+            "description": "Page size. Default 50, max 200.",
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 200
           }
         },
         "required": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",

package/skills/pharaoh/SKILL.md

@@ -27,14 +27,23 @@ For unmapped private repos, direct the user to install the Pharaoh GitHub App
 
 | Trigger | Call |
 |---------|------|
+| Before ANY architectural change | `get_vision_docs` — read the relevant MUST-bullets first |
 | Before modifying code | `get_module_context` + `get_blast_radius` |
 | Before writing new code | `search_functions` |
 | Before creating UI components | `get_design_system` |
 | Before tracing module connections | `query_dependencies` |
 | Before implementing a spec | `get_vision_docs` |
+| After a large refactor | `get_vision_gaps` — surface intent/implementation drift |
 | Before deleting code | `check_reachability` |
 | Initial orientation | `pharaoh_recon` (batches the above) |
 
+**Vision docs are first-class.** If the repo has a `docs/VISION.md`, it's
+the contract for what must always be true. Read it before touching
+architecture. If a change would violate a MUST-bullet, stop and raise it
+with the user before coding. If the repo has no VISION.md, offer to run
+`/pharaoh:vision` at the next natural break — it's the highest-leverage
+setup step for any team using Pharaoh.
+
 ## Anti-patterns
 
 - Do NOT read files one-by-one to understand architecture — call `get_codebase_map`.
@@ -45,10 +54,12 @@ For unmapped private repos, direct the user to install the Pharaoh GitHub App
 
 ## Automatic workflows
 
-**PR review:** `pharaoh_recon` (map + touched modules + blast radius) → `get_regression_risk` → `get_consolidation_opportunities`. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK.
+**PR review:** `pharaoh_recon` (map + touched modules + blast radius) → `get_vision_docs` (relevant assertions) → `get_regression_risk` → `get_consolidation_opportunities`. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK. Any PR touching code governed by a MUST-bullet should reference the assertion in the review.
 
 **Health audit:** `get_unused_code` → `get_test_coverage` → `get_regression_risk` → `get_vision_gaps` → `get_cross_repo_audit`. Grade A–F.
 
+**Vision maintenance:** When an architectural decision lands in a PR, update `docs/VISION.md` in the same commit — add an assertion if one is new, retire one if it no longer applies. Stale vision docs are worse than none.
+
 ## Using results
 
 - Lead with what the data reveals about this codebase — not a raw dump. Highlight surprises.

package/skills/plan/SKILL.md

@@ -45,11 +45,12 @@ Do NOT review from memory or assumptions. Query the actual codebase first.
 ### If Pharaoh MCP tools are available:
 
 1. `get_codebase_map` — current modules, hot files, dependency graph
-2. `search_functions` for keywords related to the plan — find existing code to reuse/extend
-3. `get_module_context` on affected modules — entry points, patterns, conventions
-4. `query_dependencies` between affected modules — coupling, circular deps
-5. `get_blast_radius` on the primary target of the change — know what breaks
-6. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
+2. `get_vision_docs` — read the repo's architectural contract. If the plan touches a domain with a MUST-bullet, the assertion is a hard constraint on the plan. Raise it explicitly in Section 1. If `get_vision_docs` returns an empty-state scaffold, flag that the repo needs `/pharaoh:vision` before planning anything architectural.
+3. `search_functions` for keywords related to the plan — find existing code to reuse/extend
+4. `get_module_context` on affected modules — entry points, patterns, conventions
+5. `query_dependencies` between affected modules — coupling, circular deps
+6. `get_blast_radius` on the primary target of the change — know what breaks
+7. `check_reachability` on the primary target — verify it's actually reachable from entry points before worrying about it
 
 ### Without Pharaoh (graceful fallback):
 
@@ -77,10 +78,17 @@ Adapt depth to change size. Skip sections that don't apply. **After each section
 
 ### Section 1 — Architecture (skip for small/single-file changes)
 
+- **Vision alignment (check FIRST).** Does this plan touch a domain
+  governed by a MUST-bullet in `docs/VISION.md`? If yes, quote the
+  assertion and verify the plan doesn't violate it. If the plan would
+  violate a MUST, STOP and raise with the user — either the plan changes
+  or VISION.md needs an update first (with user approval).
 - Component boundaries and coupling concerns
 - Dependency graph: does this change shrink or expand surface area?
 - Data flow bottlenecks and single points of failure
 - Does this need new code at all, or can a human process / existing pattern solve it?
+- **If this plan introduces a new invariant**, call it out and include a
+  step in Section 6 to add a `### assertion` to VISION.md with a pairing TEST.
 
 ### Section 2 — Code Quality (always)
 

package/skills/review/SKILL.md

@@ -71,7 +71,8 @@ Then call these additional tools for data recon doesn't cover:
 - `get_regression_risk` — overall change risk score for the repo
 - `get_consolidation_opportunities` — duplicate logic the PR may introduce
 - `check_reachability` — are new exports wired to entry points?
-- `get_vision_gaps` — do changes align with or drift from specs?
+- `get_vision_docs` — read the repo's architectural contract. For every touched module, pull its relevant assertions. Any change touching code governed by a MUST-bullet must be checked against that assertion — if the change would violate the MUST, the verdict tips toward BLOCK unless VISION.md is updated in the same PR with user approval.
+- `get_vision_gaps` — do changes align with or drift from specs? New complex functions without a matching assertion are flagged; retired specs with implementing code are flagged.
 
 **Output of Phase 1:** Architecture map, module profiles for every touched module, blast radius for high-risk changes, dependency paths between coupled modules, regression risk level, duplication findings, reachability status, and spec alignment.
 
@@ -255,7 +256,8 @@ If none of these triggers are met, **skip Phase 3** and proceed to Phase 4.
 - Unreachable exports (new public code with zero callers)
 - New circular dependencies between modules
 - HIGH regression risk without corresponding test coverage
-- Vision spec violations (building against spec intent)
+- **A MUST-bullet in `docs/VISION.md` is violated by this change** (without VISION.md being updated in the same PR with user approval)
+- Vision spec drift: new complex function has no matching assertion AND the domain it lives in has existing assertions (implies invariants are expected here)
 - Any CRITICAL finding from Phase 2 or Phase 3 that is confirmed and unfixed
 - DISAGREE verdict from adversarial review on security-sensitive code, confirmed after verification
 - Unanchored Cypher query (MATCH without traversing through `Repo {name: $repo}`)

package/skills/vision/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: vision
+prompt-name: vision-with-pharaoh
+description: Draft a VISION.md for this repo by filling a graph-derived scaffold. Pharaoh generates the structure and domain archetypes from the repo's knowledge graph; you fill in the assertions using ground-truth module context. Output is a committed docs/VISION.md that the format-linter and framework-linter both accept.
+version: 0.1.0
+homepage: https://pharaoh.so
+user-invocable: true
+metadata: {"emoji": "☥", "tags": ["vision", "architecture", "specs", "invariants", "pharaoh"]}
+---
+
+# Vision Drafting
+
+Author a VISION.md that captures this repo's invariants — what must always be
+true about its behavior. The file becomes a machine-readable contract that
+Pharaoh's linter, PR Guard, and MCP tools reason against on every change.
+
+## Why this matters (explain this to the user before drafting)
+
+A VISION.md is leverage, not paperwork. Once the repo has one:
+
+- **PR Guard** checks every pull request against its assertions. Changes that
+  contradict a MUST-bullet surface as a Check on the PR — the team sees drift
+  from intent at the exact moment it happens, not months later.
+- **`get_vision_gaps`** becomes useful. Pharaoh cross-references every spec
+  against the function graph and surfaces both sides of the drift: specs
+  without implementing code (dead intent) and complex functions with no spec
+  (invisible invariants).
+- **`get_vision_docs`** returns spec-to-code traceability. Each assertion
+  shows the functions that implement it — a direct map from intent → code.
+- **CI enforces it.** Every MUST bullet pairs with a TEST reference. The
+  linter fails when an assertion has no enforcing test. No more wishlist
+  specs that drift over time.
+
+Without a VISION.md, the tools above return empty. The graph sees code; it
+doesn't see intent. The file is the bridge.
+
+## When to Use
+
+- The repo has no `docs/VISION.md` yet and the user wants Pharaoh's full
+  value — PR Guard, vision-gaps, spec traceability all depend on the file.
+- `get_vision_docs` returned the "No VISION.md yet" onboarding response.
+- The user said "draft a vision doc", "add a VISION.md", or "scaffold vision".
+- A user is new to Pharaoh and asking what they should do next.
+
+## The flow — collaborative, not solo
+
+This is a short working session with the user. Do not solo-fill the scaffold
+— the graph can tell you the shape of the code, but only the user knows what
+must not break. Ask questions, propose, let them steer.
+
+1. **Get the scaffold.** Call `get_vision_docs` with the repo name. When no
+   vision doc exists, the tool returns a deterministic scaffold plus the
+   agent directive. Use that as your starting structure. Never invent a
+   scaffold from scratch; the archetypes encode Pharaoh's framework shape
+   and drift is surfaced by the framework-linter.
+
+2. **Interview the user.** Before filling anything, ask: *"What are the 3-5
+   things about this repo that must not break, no matter what?"* Their
+   answer drives the assertions. If they can't articulate it, probe with
+   follow-ups — "what would a P0 incident look like here?", "what would
+   wake you up on a weekend?". The goal is to extract real invariants, not
+   to generate plausible-sounding ones from graph evidence.
+
+3. **Ground each domain in real code.** For every `## Domain` the scaffold
+   rendered, call `get_module_context` for the module(s) that back that
+   domain. For example, an "Authentication and Authorization" domain →
+   `get_module_context` on the auth module + any session/token modules.
+   Read the exported functions, endpoints, env vars, and DB access.
+
+4. **Replace TODOs with WHAT statements.**
+   - Every `### TODO:` heading becomes a real assertion title. Describe the
+     invariant in plain language — "Sessions expire after 30 minutes of
+     inactivity", not "checkSession() returns null after timeout".
+   - Every `- MUST: TODO —` bullet becomes a WHAT statement. Banned
+     content: function names, file paths, class names, identifiers.
+   - Add a `- TEST: path/to/test.ts` line for every assertion. If the test
+     doesn't exist yet, write it before committing. A MUST without a TEST
+     is not an invariant, it's a wish.
+
+5. **Trim irrelevant domains.** If a rendered `## Domain` doesn't match
+   anything real in this repo, delete that whole section. The scaffold is a
+   starting point, not a contract to honor exhaustively.
+
+6. **Write the file.** Save to `docs/VISION.md` in the repo. Remove the
+   `<!-- scaffold-generated -->` marker and the `<!-- AGENT DIRECTIVE -->`
+   block once every TODO is resolved.
+
+7. **Wire it into CLAUDE.md.** This is non-negotiable — it's what turns the
+   vision doc from a file on disk into a contract future sessions respect.
+   If `CLAUDE.md` exists at the repo root, append (or edit) a section:
+
+   ```markdown
+   ## Vision docs
+
+   `docs/VISION.md` is this repo's architectural contract. Before any
+   non-trivial change, call `get_vision_docs` to read the relevant
+   assertions. After any large refactor, run `get_vision_gaps` to surface
+   drift between intent and implementation. When adding a new invariant,
+   open `docs/VISION.md`, add a `### assertion` under the right `##` domain,
+   and pair every `- MUST:` with a `- TEST:` referencing the enforcing test.
+
+   Never introduce code that would violate a MUST-bullet without first
+   updating `docs/VISION.md` (with the user's approval).
+   ```
+
+   If no `CLAUDE.md` exists, create a minimal one with the section above
+   plus any project-specific instructions you already have context for.
+
+8. **Verify.** Run `pharaoh vision lint --framework` (or instruct the user
+   to). Zero errors. Zero TODO warnings. Zero unresolved placeholders.
+
+## Hard rules
+
+- **No HOW in MUST bullets.** Banned: function names, file paths, camelCase
+  identifiers, backtick-wrapped code. The linter enforces this as a warning;
+  treat it as a hard rule.
+- **Every MUST needs a TEST.** The format-linter errors if a MUST bullet
+  has no matching TEST reference to an existing file.
+- **One MUST per line.** Don't pack multiple invariants into a single bullet.
+- **Max 10 prose lines per assertion.** Keep each `###` section tight.
+- **Mirror Pharaoh's canonical domains when they fit.** Rename only when the
+  user's project truly has a different shape. The framework-linter warns on
+  unrecognized domains so drift is visible.
+
+## What to avoid
+
+- **Do NOT** write VISION.md from scratch without calling `get_vision_docs`
+  first — you'll miss domains the graph detected and duplicate ones it
+  already included.
+- **Do NOT** carry forward the AGENT DIRECTIVE or scaffold-generated marker
+  into the committed file. Those are drafting aids, not document content.
+- **Do NOT** write speculative assertions ("sessions will expire someday").
+  Only assert what the code enforces today or what you'll commit a test for.
+- **Do NOT** use `pharaoh vision init` — that only drops the format guide,
+  not a graph-grounded scaffold. Always go through `get_vision_docs`.
+
+## Completion checklist
+
+- [ ] User was interviewed for their real invariants (not graph-guessed)
+- [ ] Every rendered `## Domain` either has ≥1 real assertion or was deleted
+- [ ] Every `### TODO:` heading replaced with a real title
+- [ ] Every `- MUST: TODO —` replaced with a WHAT statement
+- [ ] Every assertion has a `- TEST:` line pointing at an existing test file
+- [ ] Scaffold marker + AGENT DIRECTIVE block removed
+- [ ] `CLAUDE.md` updated (or created) with the Vision docs section
+- [ ] `pharaoh vision lint --framework` exits clean
+
+## After it ships — tell the user what they unlocked
+
+Once `docs/VISION.md` is committed, call out the new capabilities concretely:
+
+1. **Every future AI session reads it.** Because CLAUDE.md now references
+   `docs/VISION.md`, any agent working in this repo (Claude Code, Cursor,
+   anyone else connecting Pharaoh) will consult the file before touching
+   architecture. Continuity across sessions, across people, across tools.
+2. **`get_vision_docs`** now returns spec-to-code traceability per
+   assertion. The user can see which functions implement each invariant.
+3. **`get_vision_gaps`** surfaces drift. Unspecified complex functions
+   get flagged; specs with no implementing code get flagged for review
+   (either write the code or retire the spec).
+4. **Their next PR is checked.** PR Guard now evaluates touched code
+   against relevant assertions. First-time use often catches real drift.
+5. **`/pharaoh:plan`** will surface relevant assertions during reconnaissance.
+6. **`/pharaoh:review`** will flag PRs that touch code governed by a MUST.
+
+The bigger payoff: architectural invariants are now enforced in CI the same
+way unit tests enforce behavior. Intent and implementation stop drifting.
+
+## Ongoing maintenance — it's a living file
+
+VISION.md rots if it's not maintained. Part of your job in future sessions
+(even ones that aren't about vision directly) is to keep it current:
+
+- **When a MUST changes**, update VISION.md in the same PR as the code
+  change. Don't let the file lag — stale assertions are worse than none.
+- **When a new architectural decision lands**, add a new `###` assertion
+  under the right `##` domain with a pairing TEST. One assertion per
+  decision, not batches.
+- **When an assertion stops being load-bearing**, delete it. Retirement is
+  as important as addition.
+- **When `get_vision_gaps` shows >5 unimplemented specs**, the doc has
+  drifted into wishlist territory. Prune.
+- **Quarterly**: run `pharaoh vision lint --framework` and address warnings.
+
+Format reference: https://pharaoh.so/vision-format.md