@pharaoh-so/mcp 0.3.26 → 0.3.28

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

@@ -155,8 +155,8 @@
       }
     },
     {
-      "name": "search_functions",
-      "description": "Check if functionality already exists BEFORE writing any new function, utility, or helper.\n\nCALL THIS WHEN:\n• You're about to create a new function — search first to prevent duplicates\n• You need to find where a concept is implemented (e.g., 'notify', 'validate', 'parse')\n• You're looking for the right function to import instead of reimplementing\n• A task says 'add X functionality' — verify X doesn't already exist\n\nRETURNS: Matching functions with file paths, line numbers, module, export status, async flag, complexity scores, and full signatures. Searches all functions across the entire codebase.\n\nEXAMPLES:\n• \"Is there already a function that sends Slack notifications?\"\n• \"What validation utilities exist?\"\n• \"Where is email formatting handled?\"\n• \"Does a retry wrapper already exist somewhere?\"\n\nWHY NOT JUST READ FILES: grep only finds exact string matches and misses re-exports, aliases, and barrel-file indirection. This searches the full resolved dependency graph — if it exists anywhere in the codebase, this finds it.",
+      "name": "get_blast_radius",
+      "description": "Check what breaks BEFORE refactoring, renaming, or deleting a function, file, or module.\n\nCALL THIS WHEN:\n• You're about to refactor or rename a function — see every caller that needs updating\n• You want to know if a change is safe — check if anything depends on this code\n• A PR modifies a shared utility — trace all downstream consumers\n• You need to assess risk level before a change (LOW/MEDIUM/HIGH)\n\nRETURNS: Risk assessment (LOW/MEDIUM/HIGH), all affected callers grouped by module with file paths, impacted HTTP endpoints, impacted cron jobs, and affected DB operations. Traces up to 5 hops deep through the call graph.\n\nEXAMPLES:\n• \"What breaks if I change the formatMessage function?\"\n• \"How many callers does this utility have across the codebase?\"\n• \"Is it safe to delete this file or do other modules use it?\"\n• \"Which API endpoints are affected if I modify the db module?\"\n\nWHY NOT JUST READ FILES: You can grep for direct callers, but you'll miss indirect callers 2-3 hops away, and you won't see affected endpoints or cron jobs. This traces the full transitive dependency chain automatically.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -165,39 +165,72 @@
             "type": "string",
             "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
           },
-          "query": {
+          "entity": {
             "type": "string",
-            "maxLength": 500,
-            "description": "Function name or partial match (e.g., \"notify\", \"fetch\", \"transform\")"
+            "description": "Function name, file path, or module name"
+          },
+          "entity_type": {
+            "type": "string",
+            "enum": [
+              "function",
+              "file",
+              "module"
+            ],
+            "description": "Type of entity"
+          },
+          "depth": {
+            "description": "How many hops to trace (default: 3, max: 5)",
+            "type": "number"
+          }
+        },
+        "required": [
+          "repo",
+          "entity",
+          "entity_type"
+        ]
+      },
+      "annotations": {
+        "title": "Change Blast Radius",
+        "readOnlyHint": true,
+        "destructiveHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
+    {
+      "name": "check_reachability",
+      "description": "Check if functions are reachable from production entry points (API endpoints, CLI commands, cron jobs, event handlers, MCP tools).\n\nCALL THIS WHEN:\n• After implementing a feature — verify new code is wired into the app\n• Reviewing a PR — are all new functions actually reachable?\n• Cleaning up dead code — find functions only called by tests\n• Before opening a PR — run this as a pre-flight check\n\nRETURNS: For each exported function, whether it's reachable from a production entry point,\nthe path from entry point to function, and classification (entry_point / reachable / unreachable).\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
+      "inputSchema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
+          },
+          "functions": {
+            "description": "Function names to check (checks all exported if omitted)",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
           },
           "module": {
             "description": "Filter to a specific module",
             "type": "string"
           },
-          "file": {
-            "description": "Filter to functions in a specific file (full path for exact match, filename for substring match)",
-            "type": "string"
-          },
-          "exported_only": {
-            "description": "Only show exported functions (default: false)",
+          "include_paths": {
+            "description": "Include full reachability paths (default: false)",
             "type": "boolean"
-          },
-          "offset": {
-            "description": "Skip first N results for pagination (default: 0)",
-            "type": "number"
-          },
-          "limit": {
-            "description": "Max results to return (default: 20, max: 50)",
-            "type": "number"
           }
         },
         "required": [
-          "repo",
-          "query"
+          "repo"
         ]
       },
       "annotations": {
-        "title": "Function Search",
+        "title": "Reachability Check",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -206,8 +239,8 @@
       }
     },
     {
-      "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.",
+      "name": "get_vision_docs",
+      "description": "Get the documented intent — CLAUDE.md files, PRDs, roadmaps, skill specs — to understand WHY code exists, not just what it does.\n\nCALL THIS WHEN:\n• You're implementing a feature and need to check if a PRD or spec exists for it\n• You want to understand the original design intent behind existing code\n• You need to verify your implementation matches documented requirements\n• You're reviewing code and want to check it against the documented vision\n\nRETURNS: All vision documents grouped by type (claude_md, prd, skill, roadmap), with each spec's title, section ID, and implementation status showing which functions implement each spec.\n\nEXAMPLES:\n• \"Is there a PRD for the notification system?\"\n• \"What does the CLAUDE.md say about the auth module?\"\n• \"What specs exist for the slack integration?\"\n• \"Which specs are already implemented vs still pending?\"\n\nWHY NOT JUST READ FILES: Vision docs are scattered across CLAUDE.md files, PRDs, and roadmaps in different directories. This aggregates them all AND cross-references against actual implementations so you can see spec-to-code alignment in one call.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -216,21 +249,20 @@
             "type": "string",
             "description": "Repository name"
           },
-          "category": {
-            "default": "all",
-            "description": "Which design system aspect to return",
+          "module": {
+            "description": "Filter to specs related to this module",
+            "type": "string"
+          },
+          "doc_type": {
+            "description": "Filter by document type",
             "type": "string",
             "enum": [
-              "components",
-              "tokens",
-              "anti_patterns",
+              "claude_md",
+              "prd",
+              "skill",
+              "roadmap",
               "all"
             ]
-          },
-          "include_screens": {
-            "default": false,
-            "description": "Include screen/page components (*Screen, *Page, *View, *Route) that are typically app-level consumers, not reusable primitives",
-            "type": "boolean"
           }
         },
         "required": [
@@ -238,7 +270,7 @@
         ]
       },
       "annotations": {
-        "title": "Design System",
+        "title": "Vision Documents",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -247,42 +279,31 @@
       }
     },
     {
-      "name": "get_blast_radius",
-      "description": "Check what breaks BEFORE refactoring, renaming, or deleting a function, file, or module.\n\nCALL THIS WHEN:\n• You're about to refactor or rename a function — see every caller that needs updating\n• You want to know if a change is safe — check if anything depends on this code\n• A PR modifies a shared utility — trace all downstream consumers\n• You need to assess risk level before a change (LOW/MEDIUM/HIGH)\n\nRETURNS: Risk assessment (LOW/MEDIUM/HIGH), all affected callers grouped by module with file paths, impacted HTTP endpoints, impacted cron jobs, and affected DB operations. Traces up to 5 hops deep through the call graph.\n\nEXAMPLES:\n• \"What breaks if I change the formatMessage function?\"\n• \"How many callers does this utility have across the codebase?\"\n• \"Is it safe to delete this file or do other modules use it?\"\n• \"Which API endpoints are affected if I modify the db module?\"\n\nWHY NOT JUST READ FILES: You can grep for direct callers, but you'll miss indirect callers 2-3 hops away, and you won't see affected endpoints or cron jobs. This traces the full transitive dependency chain automatically.",
+      "name": "get_vision_gaps",
+      "description": "Find what's missing — specs without code AND complex code without specs. Call this to prioritize what to build or document next.\n\nCALL THIS WHEN:\n• You're planning work and need to find unimplemented features from PRDs\n• You want to find complex undocumented functions that need specs or tests\n• You need to audit spec-to-code alignment for a module\n• Someone asks \"what's left to build?\" or \"what's undocumented?\"\n\nRETURNS: Two lists — (1) specified-but-not-built: PRD specs with no implementing functions, and (2) built-but-not-specified: complex functions above a threshold with no vision spec. Includes function names, complexity scores, file paths, and spec references.\n\nEXAMPLES:\n• \"What features from the PRDs haven't been built yet?\"\n• \"Which complex functions lack documentation?\"\n• \"What's the spec coverage for the auth module?\"\n• \"Are there any orphaned specs or undocumented behaviors?\"\n\nWHY NOT JUST READ FILES: Manually diffing PRD bullets against code is error-prone and misses complexity metrics. This cross-references the entire spec tree against the function graph automatically — gaps that would take an hour to find manually surface in seconds.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
         "properties": {
           "repo": {
             "type": "string",
-            "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
-          },
-          "entity": {
-            "type": "string",
-            "description": "Function name, file path, or module name"
+            "description": "Repository name"
           },
-          "entity_type": {
-            "type": "string",
-            "enum": [
-              "function",
-              "file",
-              "module"
-            ],
-            "description": "Type of entity"
+          "module": {
+            "description": "Filter to a specific module",
+            "type": "string"
           },
-          "depth": {
-            "description": "How many hops to trace (default: 3, max: 5)",
+          "complexity_threshold": {
+            "description": "Min complexity for undocumented function flag (default: 15)",
             "type": "number"
           }
         },
         "required": [
-          "repo",
-          "entity",
-          "entity_type"
+          "repo"
         ]
       },
       "annotations": {
-        "title": "Change Blast Radius",
+        "title": "Vision Gap Analysis",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -364,8 +385,8 @@
       }
     },
     {
-      "name": "check_reachability",
-      "description": "Check if functions are reachable from production entry points (API endpoints, CLI commands, cron jobs, event handlers, MCP tools).\n\nCALL THIS WHEN:\n• After implementing a feature — verify new code is wired into the app\n• Reviewing a PR — are all new functions actually reachable?\n• Cleaning up dead code — find functions only called by tests\n• Before opening a PR — run this as a pre-flight check\n\nRETURNS: For each exported function, whether it's reachable from a production entry point,\nthe path from entry point to function, and classification (entry_point / reachable / unreachable).\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
+      "name": "search_functions",
+      "description": "Check if functionality already exists BEFORE writing any new function, utility, or helper.\n\nCALL THIS WHEN:\n• You're about to create a new function — search first to prevent duplicates\n• You need to find where a concept is implemented (e.g., 'notify', 'validate', 'parse')\n• You're looking for the right function to import instead of reimplementing\n• A task says 'add X functionality' — verify X doesn't already exist\n\nRETURNS: Matching functions with file paths, line numbers, module, export status, async flag, complexity scores, and full signatures. Searches all functions across the entire codebase.\n\nEXAMPLES:\n• \"Is there already a function that sends Slack notifications?\"\n• \"What validation utilities exist?\"\n• \"Where is email formatting handled?\"\n• \"Does a retry wrapper already exist somewhere?\"\n\nWHY NOT JUST READ FILES: grep only finds exact string matches and misses re-exports, aliases, and barrel-file indirection. This searches the full resolved dependency graph — if it exists anywhere in the codebase, this finds it.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -374,101 +395,39 @@
             "type": "string",
             "description": "Repository name. Works with your connected repos or any public open source repo by GitHub slug (e.g., 'vercel/next.js')."
           },
-          "functions": {
-            "description": "Function names to check (checks all exported if omitted)",
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
+          "query": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Function name or partial match (e.g., \"notify\", \"fetch\", \"transform\")"
           },
           "module": {
             "description": "Filter to a specific module",
             "type": "string"
           },
-          "include_paths": {
-            "description": "Include full reachability paths (default: false)",
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "repo"
-        ]
-      },
-      "annotations": {
-        "title": "Reachability Check",
-        "readOnlyHint": true,
-        "destructiveHint": false
-      },
-      "execution": {
-        "taskSupport": "forbidden"
-      }
-    },
-    {
-      "name": "get_vision_docs",
-      "description": "Get the documented intent — CLAUDE.md files, PRDs, roadmaps, skill specs — to understand WHY code exists, not just what it does.\n\nCALL THIS WHEN:\n• You're implementing a feature and need to check if a PRD or spec exists for it\n• You want to understand the original design intent behind existing code\n• You need to verify your implementation matches documented requirements\n• You're reviewing code and want to check it against the documented vision\n\nRETURNS: All vision documents grouped by type (claude_md, prd, skill, roadmap), with each spec's title, section ID, and implementation status showing which functions implement each spec.\n\nEXAMPLES:\n• \"Is there a PRD for the notification system?\"\n• \"What does the CLAUDE.md say about the auth module?\"\n• \"What specs exist for the slack integration?\"\n• \"Which specs are already implemented vs still pending?\"\n\nWHY NOT JUST READ FILES: Vision docs are scattered across CLAUDE.md files, PRDs, and roadmaps in different directories. This aggregates them all AND cross-references against actual implementations so you can see spec-to-code alignment in one call.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
-      "inputSchema": {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "type": "object",
-        "properties": {
-          "repo": {
-            "type": "string",
-            "description": "Repository name"
-          },
-          "module": {
-            "description": "Filter to specs related to this module",
+          "file": {
+            "description": "Filter to functions in a specific file (full path for exact match, filename for substring match)",
             "type": "string"
           },
-          "doc_type": {
-            "description": "Filter by document type",
-            "type": "string",
-            "enum": [
-              "claude_md",
-              "prd",
-              "skill",
-              "roadmap",
-              "all"
-            ]
-          }
-        },
-        "required": [
-          "repo"
-        ]
-      },
-      "annotations": {
-        "title": "Vision Documents",
-        "readOnlyHint": true,
-        "destructiveHint": false
-      },
-      "execution": {
-        "taskSupport": "forbidden"
-      }
-    },
-    {
-      "name": "get_vision_gaps",
-      "description": "Find what's missing — specs without code AND complex code without specs. Call this to prioritize what to build or document next.\n\nCALL THIS WHEN:\n• You're planning work and need to find unimplemented features from PRDs\n• You want to find complex undocumented functions that need specs or tests\n• You need to audit spec-to-code alignment for a module\n• Someone asks \"what's left to build?\" or \"what's undocumented?\"\n\nRETURNS: Two lists — (1) specified-but-not-built: PRD specs with no implementing functions, and (2) built-but-not-specified: complex functions above a threshold with no vision spec. Includes function names, complexity scores, file paths, and spec references.\n\nEXAMPLES:\n• \"What features from the PRDs haven't been built yet?\"\n• \"Which complex functions lack documentation?\"\n• \"What's the spec coverage for the auth module?\"\n• \"Are there any orphaned specs or undocumented behaviors?\"\n\nWHY NOT JUST READ FILES: Manually diffing PRD bullets against code is error-prone and misses complexity metrics. This cross-references the entire spec tree against the function graph automatically — gaps that would take an hour to find manually surface in seconds.\n\nTIER: Pharaoh Pro — free tier receives a preview. Summarize what the preview reveals, explain what full data would show for this task, then include the upgrade link.",
-      "inputSchema": {
-        "$schema": "http://json-schema.org/draft-07/schema#",
-        "type": "object",
-        "properties": {
-          "repo": {
-            "type": "string",
-            "description": "Repository name"
+          "exported_only": {
+            "description": "Only show exported functions (default: false)",
+            "type": "boolean"
           },
-          "module": {
-            "description": "Filter to a specific module",
-            "type": "string"
+          "offset": {
+            "description": "Skip first N results for pagination (default: 0)",
+            "type": "number"
           },
-          "complexity_threshold": {
-            "description": "Min complexity for undocumented function flag (default: 15)",
+          "limit": {
+            "description": "Max results to return (default: 20, max: 50)",
             "type": "number"
           }
         },
         "required": [
-          "repo"
+          "repo",
+          "query"
         ]
       },
       "annotations": {
-        "title": "Vision Gap Analysis",
+        "title": "Function Search",
         "readOnlyHint": true,
         "destructiveHint": false
       },
@@ -665,6 +624,73 @@
         "taskSupport": "forbidden"
       }
     },
+    {
+      "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 (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",
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Repository name"
+          },
+          "category": {
+            "default": "all",
+            "description": "Which design system aspect to return",
+            "type": "string",
+            "enum": [
+              "components",
+              "tokens",
+              "anti_patterns",
+              "all"
+            ]
+          },
+          "include_screens": {
+            "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": [
+          "repo"
+        ]
+      },
+      "annotations": {
+        "title": "Design System",
+        "readOnlyHint": true,
+        "destructiveHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
     {
       "name": "setup_environment",
       "description": "Set up the optimal development environment for this codebase — install Pharaoh's curated plugin bundle.\n\nCALL THIS WHEN:\n• The user says \"set up my environment\", \"install plugins\", or \"optimize my setup\"\n• You want to proactively improve the development experience with proven plugins\n• After noticing the user could benefit from LSP, security scanning, or code review tools\n• The user is on OpenClaw or Cursor and wants to install Pharaoh skills/prompts\n\nRETURNS: A curated list of recommended plugins and install instructions, tailored to the client platform (claude-code, openclaw, or cursor) and languages in this codebase.\n\nThis is a one-time setup. Once installed, plugins persist across sessions.",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "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