@sandrinio/vdoc 3.8.0 → 3.9.0

package/README.md

@@ -6,6 +6,22 @@ One install command. Your AI handles the rest.
 
 ---
 
+## Why vdoc?
+
+### 1. Better AI context
+
+Your AI reads code, but code doesn't tell it *why* auth tokens expire in 15 minutes, *what happens* when a webhook fails at 2 AM, or *which features depend on each other*. Without that context, the AI guesses — and gets things wrong. vdoc generates feature-centric docs that give it real system knowledge, plus a `_manifest.json` that acts as a routing table — one read and the AI knows exactly which doc to open for any question.
+
+### 2. Developer onboarding
+
+New developer joins the team. Instead of spending days reading code and asking questions, they point their AI at the `vdocs/` folder and get up to speed immediately. Every feature is documented with end-to-end flows, data models, error scenarios, security patterns, and architectural decisions — the stuff that normally lives only in senior devs' heads.
+
+### 3. No data leaves your machine
+
+vdoc is not a service, not a CLI that phones home, not a SaaS product. It's a set of skill/rule files that get copied into your AI platform's config folder. Your code is read by the same AI agent you're already using. Nothing is sent anywhere, no accounts, no API keys, no telemetry.
+
+---
+
 ## What is vdoc?
 
 vdoc gives your AI coding agent the ability to create and maintain feature-centric documentation for your codebase. It's not a CLI you run — it's a skill file that gets installed into your AI platform. After install, you just talk to your AI.
@@ -169,26 +185,46 @@ Docs are **feature-centric** — organized by what your system does, not by file
 
 Every generated doc follows a consistent structure:
 
-- **Overview** — what it does, why it exists
-- **How It Works** — core logic with mermaid diagrams (max 7-9 nodes per diagram)
-- **Data Model** — entities and relationships
-- **Key Files** — source files that implement this feature
+- **Overview** — value proposition: what problem this solves for the user
+- **User Workflows** — step-by-step journeys: what the user does, what the system does, what the user sees
+- **How It Works** — end-to-end flows with mermaid sequence diagrams (every actor shown)
+- **Data Model** — actual column names, types, and descriptions from schema files
+- **Key Files** — every file in the execution path, not just the "main" files
 - **Dependencies & Integrations** — external services, internal features
-- **Configuration** — env vars, feature flags, secrets
-- **Error Handling** — failure modes and user-facing behavior
-- **Constraints & Decisions** — why it's built this way, what you can't change
-- **Related Features** — cross-references and blast radius
+- **Configuration** — actual env vars and secrets from the code
+- **Error Handling & Edge Cases** — specific failure scenarios with system behavior and user impact
+- **Security** — auth patterns, service roles, access control, secrets handling
+- **Constraints & Decisions** — non-obvious architectural choices with reasoning
+- **Related Features** — cross-references by doc filename with coupling explanation
 
 ---
 
-## Manifest
+## Manifest — The AI's Entry Point
+
+The `_manifest.json` is the first file any AI agent should read when it encounters your project. It solves a fundamental problem: **how does an AI know what your project does without reading everything?**
+
+### How it works
 
-The `_manifest.json` is a map for your AI. Instead of reading every doc to find the right one, the AI reads the manifest first and picks the relevant doc based on rich descriptions and tags.
+1. AI opens `vdocs/_manifest.json` — one read
+2. Sees the project fingerprint (language, framework, architecture)
+3. Matches the user's question against rich doc descriptions
+4. Reads only the relevant doc — not the entire codebase
 
-When you ask "how does authentication work?", the AI matches your question against manifest descriptions and goes straight to `AUTHENTICATION_DOC.md` — no scanning, no guessing.
+**Without manifest:** "How does auth work?" → AI scans dozens of files, misses context, hallucinates details
+
+**With manifest:** "How does auth work?" → AI reads manifest → routes to `AUTHENTICATION_DOC.md` → gets the complete OAuth2 flow, JWT lifecycle, error scenarios, and security patterns
+
+### Example
 
 ```json
 {
+  "project": "my-saas-app",
+  "fingerprint": {
+    "languages": ["TypeScript"],
+    "frameworks": ["Next.js 14", "Prisma", "NextAuth"],
+    "archetypes": ["Full-stack Framework"],
+    "scope": "~85 files, medium"
+  },
   "documentation": [
     {
       "filepath": "AUTHENTICATION_DOC.md",
@@ -201,6 +237,8 @@ When you ask "how does authentication work?", the AI matches your question again
 }
 ```
 
+The `description` field is intentionally rich — it's written for semantic matching, not for humans to skim. The more specific the description, the better the AI routes questions to the right doc.
+
 ---
 
 ## Uninstall
@@ -241,4 +279,4 @@ None. Your AI coding agent is the runtime.
 
 ---
 
-*vdoc v3.5.2 — Documentation skills for AI coding agents*
+*vdoc v3.8.0 — Documentation skills for AI coding agents*

package/bin/vdoc.mjs

@@ -18,6 +18,7 @@ const PLATFORMS = {
       { src: 'claude/references/create-workflow.md', dest: '.claude/skills/vdoc/references/create-workflow.md' },
       { src: 'claude/references/audit-workflow.md', dest: '.claude/skills/vdoc/references/audit-workflow.md' },
       { src: 'claude/references/exploration-strategies.md', dest: '.claude/skills/vdoc/references/exploration-strategies.md' },
+      { src: 'claude/references/discovery-protocol.md', dest: '.claude/skills/vdoc/references/discovery-protocol.md' },
       { src: 'claude/references/doc-template.md', dest: '.claude/skills/vdoc/references/doc-template.md' },
       { src: 'claude/references/manifest-schema.json', dest: '.claude/skills/vdoc/references/manifest-schema.json' },
       { src: 'claude/commands/vdoc-init.md', dest: '.claude/commands/vdoc-init.md' },
@@ -34,6 +35,7 @@ const PLATFORMS = {
       { src: 'cursor/references/doc-template.md', dest: '.cursor/rules/vdoc/references/doc-template.md' },
       { src: 'cursor/references/manifest-schema.json', dest: '.cursor/rules/vdoc/references/manifest-schema.json' },
       { src: 'cursor/references/exploration-strategies.md', dest: '.cursor/rules/vdoc/references/exploration-strategies.md' },
+      { src: 'cursor/references/discovery-protocol.md', dest: '.cursor/rules/vdoc/references/discovery-protocol.md' },
       { src: 'cursor/vdoc-command.md', dest: '.cursor/commands/vdoc.md' },
     ],
   },
@@ -45,6 +47,7 @@ const PLATFORMS = {
       { src: 'windsurf/resources/doc-template.md', dest: '.windsurf/skills/vdoc/resources/doc-template.md' },
       { src: 'windsurf/resources/manifest-schema.json', dest: '.windsurf/skills/vdoc/resources/manifest-schema.json' },
       { src: 'windsurf/resources/exploration-strategies.md', dest: '.windsurf/skills/vdoc/resources/exploration-strategies.md' },
+      { src: 'windsurf/resources/discovery-protocol.md', dest: '.windsurf/skills/vdoc/resources/discovery-protocol.md' },
       { src: 'windsurf/vdoc-workflow.md', dest: '.windsurf/workflows/vdoc.md' },
     ],
   },
@@ -56,6 +59,7 @@ const PLATFORMS = {
       { src: 'vscode/references/doc-template.md', dest: '.github/skills/vdoc/references/doc-template.md' },
       { src: 'vscode/references/manifest-schema.json', dest: '.github/skills/vdoc/references/manifest-schema.json' },
       { src: 'vscode/references/exploration-strategies.md', dest: '.github/skills/vdoc/references/exploration-strategies.md' },
+      { src: 'vscode/references/discovery-protocol.md', dest: '.github/skills/vdoc/references/discovery-protocol.md' },
       { src: 'vscode/vdoc.instructions.md', dest: '.github/instructions/vdoc.instructions.md' },
       { src: 'vscode/vdoc.prompt.md', dest: '.github/prompts/vdoc.prompt.md' },
       { src: 'vscode/copilot-instructions.md', dest: '.github/copilot-instructions.md', inject: true },
@@ -70,6 +74,7 @@ const PLATFORMS = {
       { src: 'continue/references/doc-template.md', dest: '.continue/references/vdoc/doc-template.md' },
       { src: 'continue/references/manifest-schema.json', dest: '.continue/references/vdoc/manifest-schema.json' },
       { src: 'continue/references/exploration-strategies.md', dest: '.continue/references/vdoc/exploration-strategies.md' },
+      { src: 'continue/references/discovery-protocol.md', dest: '.continue/references/vdoc/discovery-protocol.md' },
     ],
   },
   cline: {
@@ -81,6 +86,7 @@ const PLATFORMS = {
       { src: 'cline/references/doc-template.md', dest: '.clinerules/vdoc/doc-template.md' },
       { src: 'cline/references/manifest-schema.json', dest: '.clinerules/vdoc/manifest-schema.json' },
       { src: 'cline/references/exploration-strategies.md', dest: '.clinerules/vdoc/exploration-strategies.md' },
+      { src: 'cline/references/discovery-protocol.md', dest: '.clinerules/vdoc/discovery-protocol.md' },
     ],
   },
   gemini: {
@@ -92,6 +98,7 @@ const PLATFORMS = {
       { src: 'gemini/references/doc-template.md', dest: '.gemini/vdoc/doc-template.md' },
       { src: 'gemini/references/manifest-schema.json', dest: '.gemini/vdoc/manifest-schema.json' },
       { src: 'gemini/references/exploration-strategies.md', dest: '.gemini/vdoc/exploration-strategies.md' },
+      { src: 'gemini/references/discovery-protocol.md', dest: '.gemini/vdoc/discovery-protocol.md' },
     ],
   },
   jetbrains: {
@@ -102,6 +109,7 @@ const PLATFORMS = {
       { src: 'jetbrains-ai/references/doc-template.md', dest: '.aiassistant/vdoc/doc-template.md' },
       { src: 'jetbrains-ai/references/manifest-schema.json', dest: '.aiassistant/vdoc/manifest-schema.json' },
       { src: 'jetbrains-ai/references/exploration-strategies.md', dest: '.aiassistant/vdoc/exploration-strategies.md' },
+      { src: 'jetbrains-ai/references/discovery-protocol.md', dest: '.aiassistant/vdoc/discovery-protocol.md' },
     ],
   },
   junie: {
@@ -112,6 +120,7 @@ const PLATFORMS = {
       { src: 'junie/references/doc-template.md', dest: '.junie/vdoc/doc-template.md' },
       { src: 'junie/references/manifest-schema.json', dest: '.junie/vdoc/manifest-schema.json' },
       { src: 'junie/references/exploration-strategies.md', dest: '.junie/vdoc/exploration-strategies.md' },
+      { src: 'junie/references/discovery-protocol.md', dest: '.junie/vdoc/discovery-protocol.md' },
     ],
   },
   agents: {
@@ -122,6 +131,7 @@ const PLATFORMS = {
       { src: 'agents/references/doc-template.md', dest: '.agents/vdoc/doc-template.md' },
       { src: 'agents/references/manifest-schema.json', dest: '.agents/vdoc/manifest-schema.json' },
       { src: 'agents/references/exploration-strategies.md', dest: '.agents/vdoc/exploration-strategies.md' },
+      { src: 'agents/references/discovery-protocol.md', dest: '.agents/vdoc/discovery-protocol.md' },
     ],
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vdoc",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Documentation skills for AI coding agents",
   "type": "module",
   "bin": {

package/skills/agents/references/audit-workflow.md

@@ -1,5 +1,7 @@
 # Audit Workflow
 
+Detect stale, missing, dead, and low-quality documentation. Report and patch. Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep, Bash for git commands) for everything.
+
 ## Step 1 — Read Current State
 
 Read `vdocs/_manifest.json`. Load the list of documented features and their metadata.
@@ -8,7 +10,7 @@ Read `vdocs/_manifest.json`. Load the list of documented features and their meta
 
 Run `git log --name-only --since="<last_updated>" --pretty=format:""` or use `git diff` to find all source files that changed since the last audit.
 
-Cross-reference changed files against each doc's "Key Files" section to identify which docs are stale.
+Cross-reference changed files against each doc's `keyFiles` frontmatter (or Key Files section) to identify which docs are stale.
 
 ## Step 3 — Detect Coverage Gaps
 
@@ -22,15 +24,36 @@ If you find undocumented features, propose new docs.
 
 ## Step 4 — Detect Dead Docs
 
-Check each doc's "Key Files" section against the actual filesystem. If key files no longer exist, the doc may be dead. Flag it: "PAYMENT_PROCESSING_DOC.md references 3 files that no longer exist — remove or archive?"
+Check each doc's Key Files (from frontmatter `keyFiles` and the Key Files table) against the actual filesystem. If key files no longer exist, the doc may be dead. Flag it: "PAYMENT_PROCESSING_DOC.md references 3 files that no longer exist — remove or archive?"
 
 ## Step 5 — Check Cross-References
 
-Read each doc's "Related Features" section. Verify that:
-- Referenced doc filenames still exist
+Read each doc's Related Features table and `relatedDocs` frontmatter. Verify that:
+- Referenced doc filenames still exist in `vdocs/` and in `_manifest.json`
+- The `deps` array in the manifest matches the Related Features table
 - The described coupling is still accurate (skim the relevant code)
 
-## Step 6 — Report
+## Step 6 — Quality Score
+
+Run mechanical quality checks on each doc. Score = percentage of checks passing.
+
+| # | Check | How to verify |
+|---|-------|---------------|
+| 1 | Valid YAML frontmatter | Has all required fields: title, description, tags, version, keyFiles, relatedDocs, lastUpdated |
+| 2 | CORE sections present and non-empty | Overview, Business Rules, How It Works, Key Files, Testing, Constraints & Decisions, Related Features all exist with content |
+| 3 | Key File paths exist | Every path in frontmatter `keyFiles` and Key Files table resolves to a real file |
+| 4 | How It Works has a diagram | Contains at least one `mermaid` code block |
+| 5 | Business Rules has ≥1 rule | At least one bullet point in the section |
+| 6 | relatedDocs resolve | Every filename in frontmatter `relatedDocs` exists in `vdocs/` |
+| 7 | lastUpdated freshness | Delta between `lastUpdated` and latest git blame on key files is within acceptable range |
+| 8 | Testing section has run command | Contains a code-formatted command string |
+
+**Score thresholds:**
+- **80-100%** — Good quality
+- **60-79%** — Acceptable, minor improvements suggested
+- **Below 60%** — Low quality — generate a "quality fix" task
+
+## Step 7 — Report
 
 Present a clear report:
 
@@ -41,6 +64,11 @@ STALE (source files changed):
   - AUTHENTICATION_DOC.md — src/lib/auth.ts changed (added GitHub provider)
   - API_REFERENCE_DOC.md — 2 new endpoints added
 
+QUALITY SCORES:
+  - AUTHENTICATION_DOC.md — 88% (Good) ✓
+  - API_REFERENCE_DOC.md — 50% (Low) ✗ Missing: Business Rules, Testing section, mermaid diagram
+  - DATABASE_SCHEMA_DOC.md — 75% (Acceptable) ~ Missing: Testing section
+
 COVERAGE GAPS (undocumented features):
   - src/services/notification.ts — no doc covers notifications
 
@@ -49,17 +77,20 @@ DEAD DOCS (source files removed):
 
 CROSS-REF ISSUES:
   - AUTHENTICATION_DOC.md references BILLING_DOC.md which no longer exists
+  - Manifest deps for PAYMENTS_DOC.md lists "invoicing" but no invoicing doc exists
 
 CURRENT (no changes needed):
-  - DATABASE_SCHEMA_DOC.md
-  - PROJECT_OVERVIEW_DOC.md
+  - PROJECT_OVERVIEW_DOC.md — 100% quality
 
 Proceed with fixes?
 ```
 
 Wait for user direction, then:
 - Patch stale docs (re-read source files, update affected sections only)
-- Generate new docs for coverage gaps (follow init workflow for each)
+- Fix low-quality docs (add missing CORE sections, fix broken key file paths)
+- Generate new docs for coverage gaps (follow create workflow for each)
 - Flag dead docs for user to confirm deletion
-- Fix cross-reference issues
-- Update manifest: bump versions, update `last_updated`, `last_commit`
+- Fix cross-reference issues (update relatedDocs frontmatter + manifest deps)
+- Regenerate context slices for any patched/updated docs in `vdocs/_slices/`
+- Update manifest: bump `version`, update `last_updated`, `last_commit`, fix `deps` arrays
+- Bump frontmatter `version` (increment by 1) and `lastUpdated` on every patched doc

package/skills/agents/references/create-workflow.md

@@ -0,0 +1,77 @@
+# Create Workflow
+
+Create one feature doc based on the user's description. Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep) for everything.
+
+## Step 1 — Locate
+
+Use the user's description to find the relevant source files:
+
+1. If `vdocs/_planning/_exploration_log.md` exists, read it first — it maps the codebase and may already have the feature signal you need
+2. Otherwise, search the codebase with Glob and Grep to find files matching the user's description
+3. Read ALL relevant source files — not just the main file, but helpers, types, middleware, tests, API routes, components
+4. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+5. **Search for consumers** — grep for the feature's key types, table names, API endpoints, and module imports across the entire codebase. This catches secondary workflows (exports, scheduled jobs, webhooks, notifications, external automation) that live in different directories but depend on this feature. If you find consumers, read them and include those workflows in the doc.
+
+Do not skim. Understand how the feature actually works before writing.
+
+## Step 2 — Generate
+
+1. Read the template from [doc-template.md](./doc-template.md) and follow it exactly
+2. Write to `vdocs/FEATURE_NAME_DOC.md`
+
+**Writing rules:**
+
+- **YAML frontmatter** — every doc MUST start with frontmatter: `title`, `description`, `tags`, `version` (start at 1), `keyFiles` (array of primary source file paths), `relatedDocs` (array of other doc filenames), `lastUpdated` (YYYY-MM-DD). This metadata is the machine-readable contract — keep it in sync with the doc body.
+- **CORE vs CONDITIONAL sections** — follow the `[CORE]` and `[CONDITIONAL]` markers in the template. Omit conditional sections entirely when not relevant. Do NOT leave empty sections or write "N/A".
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z." A PM should understand the feature from this section alone.
+- **Business Rules** — plain-language rules that govern behavior. No code. If you can't find explicit rules, derive them from the code and mark with `Inferred from code — verify with team`.
+- **User Workflows** — describe 1-3 primary user journeys. [CONDITIONAL: omit for non-user-facing features]
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor. Trace the COMPLETE path.
+- **Key Files** — list every file in the execution path with a Type column (Source, Test, Config, Migration, etc.). Include test files and config files.
+- **Testing** — include the test run command, test file locations, coverage gaps, and manual testing steps.
+- **Common Tasks** — cookbook recipes for recurring modifications. [CONDITIONAL: omit when not applicable]
+- **Data Model** — actual column names, types, descriptions. [CONDITIONAL: omit for features without persistent state]
+- **Error Handling & Edge Cases** — specific failure scenarios, not generic. [CONDITIONAL: omit for features with no non-obvious failure modes]
+- **Constraints & Decisions** — non-obvious choices + security considerations (auth, access control, secrets).
+- **Related Features** — structured table: Doc, Relationship, Blast radius. Also populate `relatedDocs` frontmatter.
+- **Change Log** — add initial entry with today's date.
+
+## Step 3 — Update Manifest
+
+Read `vdocs/_manifest.json` and add the new doc entry using the schema in [manifest-schema.json](./manifest-schema.json).
+
+Include the `deps` array — list feature names (matching other manifest entries' titles) that would break if this feature changes. Populate from the Related Features table.
+
+If `vdocs/_manifest.json` doesn't exist, create it with the project name, version, and this doc as the first entry.
+
+## Step 4 — Generate Context Slice
+
+Create a token-optimized context slice at `vdocs/_slices/{FEATURE_NAME}_SLICE.md`.
+
+Extract ONLY these sections from the full doc:
+- **Overview** (first paragraph only)
+- **Business Rules** (full section)
+- **Key Files** table (full table)
+- **Constraints & Decisions** (full section)
+- **Related Features** table (full table)
+
+Add a header comment: `<!-- Context slice for {Feature Title} — auto-generated, do not edit manually -->` and a link back to the full doc.
+
+## Step 5 — Self-Review
+
+Before finishing, verify:
+
+- [ ] Doc has valid YAML frontmatter (title, description, tags, version, keyFiles, relatedDocs, lastUpdated)
+- [ ] Frontmatter `keyFiles` matches Key Files table entries
+- [ ] Frontmatter `relatedDocs` matches Related Features table doc filenames
+- [ ] Doc has at least one mermaid diagram in "How It Works"
+- [ ] Doc has at least 2 entries in "Constraints & Decisions"
+- [ ] Key Files lists real paths with Type column
+- [ ] Doc has a Testing section with run command and coverage info
+- [ ] Doc has Business Rules with at least one plain-language rule
+- [ ] CONDITIONAL sections are omitted (not left empty) when not relevant
+- [ ] Related Features uses structured table format (Doc, Relationship, Blast radius)
+- [ ] Manifest entry includes `deps` array populated from Related Features
+- [ ] Manifest `description` is detailed enough for semantic routing
+- [ ] Context slice exists in `vdocs/_slices/`
+- [ ] Doc explains WHY and HOW, not just WHAT

package/skills/agents/references/discovery-protocol.md

@@ -0,0 +1,211 @@
+# Universal Discovery Protocol
+
+After running the archetype playbook from `exploration-strategies.md`, apply these four discovery layers to find **behaviors** — not just files. The archetype playbook tells you WHERE to look. This protocol tells you WHAT to look for.
+
+Run all four layers regardless of archetype. Each layer produces signals that feed the documentation plan.
+
+---
+
+## Layer 1 — Capability Surface
+
+**Goal:** Map everything a user/consumer can DO.
+
+The capability surface is the complete set of entry points into your system. Every entry point = a potential doc.
+
+| Project Type | Capability Source | How to Find |
+|-------------|------------------|-------------|
+| SPA / Mobile | Route definitions | Glob: `**/routes*`, `**/router*`, `**/app/**/page.*`, `**/screens/**` |
+| Web API | Endpoint definitions | Glob: `**/routes/**`, `**/controllers/**`; Grep: `@Get\|@Post\|app.get\|router.` |
+| CLI | Command definitions | Glob: `**/commands/**`, `**/cmd/**`; Grep: `.command(\|.subcommand\|Subcommand` |
+| Library/SDK | Public exports | Read main entry point (`index.*`), check `exports` in package config |
+| Pipeline | DAG/flow definitions | Glob: `**/dags/**`, `**/pipelines/**`, `**/flows/**`, `**/workflows/**` |
+| Event-driven | Event handlers | Grep: `on\(\|addEventListener\|@EventHandler\|subscribe\|consumer` |
+
+### SPA-Specific: Route Tree = Feature Map
+
+For SPAs (React, Angular, Vue, Svelte), the route tree IS the documentation outline:
+
+1. **Extract the full route tree** — read router config, `app/` directory structure, or navigation definitions
+2. **Classify each route:**
+   - **Core domain** — the primary value (e.g., `/projects/:id`, `/dashboard`)
+   - **Auth** — login, register, forgot password, OAuth callbacks
+   - **Settings/Admin** — configuration, user management
+   - **Utility** — 404, error pages, maintenance
+3. **For each core domain route, identify:**
+   - What data it displays (state selectors, API calls, props)
+   - What actions the user can take (buttons, forms, modals)
+   - What happens after each action (navigation, API mutation, toast)
+
+**Framework-specific best signals:**
+
+| Framework | Best Feature Signal | Pattern to Grep |
+|-----------|-------------------|-----------------|
+| React | Custom hooks | `export function use[A-Z]` or `export const use[A-Z]` |
+| Angular | Feature modules + services | `@NgModule\|@Injectable` |
+| Vue 3 | Composables | `export function use[A-Z]` in `composables/` |
+| Svelte | Stores + loaders | `writable\|readable\|derived` or `+page.ts` `load` functions |
+| Solid | Signals + resources | `createSignal\|createResource` |
+
+Each custom hook/composable/service that encapsulates a reusable behavior = one documentable feature.
+
+### API-Specific: Endpoint Map
+
+1. **Check for API specs first** — OpenAPI/Swagger (`swagger.json`, `openapi.yaml`), GraphQL schemas (`schema.graphql`, `*.gql`), protobuf definitions (`*.proto`), tRPC routers. These are free structured input — parse them instead of re-discovering.
+2. **Group endpoints by resource** — `/users/*`, `/projects/*`, `/billing/*` — each group is a feature.
+3. **Trace middleware chains** — what runs before each endpoint? (auth, validation, rate limiting, logging)
+
+---
+
+## Layer 2 — Data Flows
+
+**Goal:** For each capability, trace how data moves from source to screen (or from input to storage).
+
+### Discovery questions per feature:
+1. **Where does the data come from?** (API call, local state, URL params, localStorage, real-time subscription)
+2. **How is it transformed?** (selectors, computed values, mappers, formatters)
+3. **Where is it displayed?** (which components/views consume it)
+4. **How does the user modify it?** (forms, inline edits, drag-drop, toggles)
+5. **Where does the mutation go?** (API endpoint, store dispatch, optimistic update)
+6. **What's the loading/error/empty state?** (skeleton, spinner, error boundary, empty state message)
+
+### Patterns to discover:
+
+| Pattern | Grep Signal | What It Reveals |
+|---------|------------|-----------------|
+| API client calls | `fetch\|axios\|httpClient\|trpc\|useSWR\|useQuery\|graphql` | Backend dependencies per feature |
+| State management | `useSelector\|useStore\|mapState\|inject\|useContext\|getState` | Shared state between features |
+| Form handling | `useForm\|FormGroup\|Formik\|react-hook-form\|zod\|yup\|validate` | User input flows + validation rules |
+| Caching | `cache\|staleTime\|revalidate\|TTL\|memo\|persist` | Data freshness strategy |
+| Optimistic updates | `optimistic\|rollback\|onMutate\|pending` | UX patterns for mutations |
+
+### SPA data flow trace template:
+```
+Feature: [name]
+  User action → Component → Hook/Service → API call → Backend endpoint
+  Response → Transform → State update → Re-render → User sees [result]
+  Error → Error handler → User sees [error state]
+```
+
+---
+
+## Layer 3 — Shared Behaviors
+
+**Goal:** Find cross-cutting concerns that affect multiple features.
+
+These don't belong to any single feature — they're system-wide patterns that deserve their own docs or dedicated sections.
+
+### Must-find behaviors:
+
+| Behavior | Where to Look | Grep Patterns |
+|----------|--------------|---------------|
+| **Authentication** | Middleware, guards, interceptors, context providers | `auth\|token\|session\|jwt\|oauth\|login\|guard\|protect\|interceptor` |
+| **Authorization** | Route guards, role checks, permission gates | `role\|permission\|can\|ability\|policy\|rbac\|acl\|isAdmin\|gate` |
+| **Error handling** | Error boundaries, global handlers, interceptors | `ErrorBoundary\|catch\|onError\|handleError\|errorHandler\|fallback\|retry` |
+| **Notifications** | Toast systems, push notifications, in-app alerts | `toast\|notify\|alert\|snackbar\|notification\|push\|banner` |
+| **Real-time** | WebSocket, SSE, polling, subscriptions | `WebSocket\|socket\|SSE\|EventSource\|subscribe\|polling\|realtime\|live` |
+| **Theming/i18n** | Theme providers, translation files, locale configs | `theme\|dark\|light\|i18n\|locale\|translate\|intl\|t\(` |
+| **Analytics** | Tracking calls, event logging | `track\|analytics\|gtag\|mixpanel\|segment\|posthog\|amplitude` |
+| **Feature flags** | Flag checks, A/B tests, experimental UI | `feature.*flag\|experiment\|variant\|canary\|flipper\|unleash\|launchDarkly` |
+
+### Discovery process:
+1. Grep for each behavior's patterns across the codebase
+2. If found, read the implementation to understand scope
+3. In the exploration log, note which features are affected
+4. In the plan, decide: standalone doc vs dedicated section in each affected feature doc
+
+---
+
+## Layer 4 — Integration Boundary
+
+**Goal:** Find every point where the system touches the outside world.
+
+### Outgoing integrations (your app calls external services):
+
+| Pattern | How to Find |
+|---------|------------|
+| HTTP clients | Grep: `fetch\|axios\|got\|httpClient\|request\|urllib` — read the base URL and endpoint |
+| SDK imports | Grep: `import.*from ['"]@?(?:aws-sdk\|stripe\|twilio\|sendgrid\|firebase\|supabase)` |
+| Database connections | Grep: `createClient\|createPool\|mongoose.connect\|PrismaClient\|createConnection` |
+| Cache connections | Grep: `redis\|memcache\|createClient.*cache` |
+| Queue producers | Grep: `publish\|sendMessage\|enqueue\|dispatch.*queue\|produce` |
+
+### Incoming integrations (external services call your app):
+
+| Pattern | How to Find |
+|---------|------------|
+| Webhook handlers | Grep: `webhook\|/hook\|/callback` in route definitions |
+| OAuth callbacks | Grep: `callback\|/auth/.*callback\|redirect_uri` |
+| Queue consumers | Grep: `consume\|subscribe\|onMessage\|process.*queue\|worker` |
+| Cron / scheduled tasks | Grep: `cron\|schedule\|@Cron\|setInterval.*60\|recurring`; Glob: `**/cron/**`, `**/jobs/**`, `**/tasks/**`, `**/workers/**` |
+
+### Hidden work (no user present):
+
+This is the most underdocumented layer in any project. Actively hunt for:
+
+1. **Background jobs** — Glob: `**/jobs/**`, `**/workers/**`, `**/queues/**`, `**/tasks/**`
+2. **Scheduled tasks** — Grep: `cron\|schedule\|@Scheduled\|setInterval`; check CI/CD configs for scheduled workflows
+3. **Event handlers** — Grep: `on\(\|emit\(\|EventEmitter\|addEventListener\|subscribe`; check for pub/sub patterns
+4. **Database triggers** — Read migration files for trigger definitions
+5. **Cleanup / maintenance** — Grep: `cleanup\|purge\|archive\|expire\|gc\|garbage`
+
+### Environment as documentation:
+
+Read `.env.example`, `.env.sample`, or environment config files. Each env var is a configuration surface:
+- `DATABASE_URL` → database dependency
+- `STRIPE_SECRET_KEY` → payment integration
+- `REDIS_URL` → caching layer
+- `WEBHOOK_SECRET` → incoming integration
+
+Group env vars by feature — they reveal the integration map without reading any code.
+
+---
+
+## How to Use This Protocol
+
+### During Init (Step 1 — Explore):
+
+After the archetype playbook:
+1. Run Layer 1 to build the capability map
+2. For each capability, run Layer 2 to trace data flows
+3. Run Layer 3 once for the whole project to find shared behaviors
+4. Run Layer 4 once to map the integration boundary
+
+### During Audit:
+
+Layers 1 and 4 are the best sources for coverage gaps:
+- New routes/endpoints = new capabilities not yet documented
+- New env vars with external URLs = new integrations not yet documented
+- New cron/job files = new background work not yet documented
+
+### In the Exploration Log:
+
+Add a section per layer:
+
+```markdown
+## Capability Surface
+| Entry Point | Type | Proposed Doc |
+|-------------|------|-------------|
+| /api/auth/* | Auth routes (5 endpoints) | AUTHENTICATION_DOC.md |
+| /dashboard | Page + 3 sub-routes | DASHBOARD_DOC.md |
+
+## Data Flows
+| Feature | State Source | API Calls | Mutations |
+|---------|-------------|-----------|-----------|
+| Dashboard | useDashboardStore | GET /api/stats, GET /api/projects | None (read-only) |
+| Project Editor | useProjectStore | GET /api/projects/:id | PUT /api/projects/:id, POST /api/tasks |
+
+## Shared Behaviors
+| Behavior | Scope | Implementation |
+|----------|-------|----------------|
+| Auth | All /app/* routes | NextAuth middleware + useSession hook |
+| Error handling | Global | ErrorBoundary + toast on API errors |
+| Feature flags | 3 features | LaunchDarkly SDK, checked in useFeatureFlag hook |
+
+## Integration Boundary
+| Direction | System | Purpose | Env Var |
+|-----------|--------|---------|---------|
+| Outgoing | Stripe API | Payments | STRIPE_SECRET_KEY |
+| Outgoing | SendGrid | Emails | SENDGRID_API_KEY |
+| Incoming | Stripe webhooks | Payment events | /api/webhooks/stripe |
+| Background | Cron: cleanup-sessions | Expire old sessions | runs daily via Vercel Cron |
+```