@sandrinio/vdoc 3.8.0 → 3.9.0

package/skills/gemini/references/init-workflow.md

@@ -5,7 +5,7 @@
 Follow the two-phase exploration strategy in `references/exploration-strategies.md`:
 
 **Phase 1 — Fingerprint** (3-5 file reads max)
-Read package/config files and directory structure to identify the project's language, framework, and archetype. Also check for existing documentation (`vdocs/`, `docs/`, `product_documentation/`, substantial `*.md` files). If found, read them first — they're a head start. See the "Existing Documentation" section in `references/exploration-strategies.md`.
+Read package/config files and directory structure using Read, Glob, and Grep to identify the project's language, framework, and archetype. Also check for existing documentation (`vdocs/`, `docs/`, `product_documentation/`, substantial `*.md` files). If found, read them first — they're a head start. See the "Existing Documentation" section in `references/exploration-strategies.md`.
 
 **Phase 2 — Targeted Exploration** (archetype-specific)
 Apply the matching archetype playbook from `references/exploration-strategies.md`. Read files in priority order using the glob patterns listed. Identify feature signals — each signal maps to a documentable feature. Combine multiple playbooks when the project doesn't fit a single archetype (see "Composing Archetypes" in the strategies file).
@@ -14,10 +14,19 @@ If no archetype matches, use the Fallback strategy and confirm with the user.
 
 Do not skim. Understand how the system actually works before proposing docs.
 
-**Important:** Use your built-in file-reading tools to explore. Do NOT create scanner scripts, shell scripts, or any tooling. vdoc is purely AI-driven — no scripts, no build steps, no infrastructure.
+**Phase 2b — Behavior Discovery** (universal — runs after archetype playbook)
+Apply the 4-layer discovery protocol from `references/discovery-protocol.md`:
+1. **Capability Surface** — Map every entry point (routes, endpoints, commands, exports)
+2. **Data Flows** — For each capability, trace data from source to screen to mutation
+3. **Shared Behaviors** — Find cross-cutting concerns (auth, error handling, notifications, feature flags)
+4. **Integration Boundary** — Map every external touchpoint (outgoing API calls, incoming webhooks, background jobs, env vars)
+
+This catches behaviors that file-structure exploration misses: background jobs, event-driven workflows, hidden integrations, cross-feature dependencies.
+
+**Important:** Use your built-in tools (Read, Glob, Grep) to explore. Do NOT create scanner scripts, shell scripts, or any tooling. vdoc is purely AI-driven — no scripts, no build steps, no infrastructure.
 
 **Phase 3 — Write Exploration Log**
-After exploring, write `vdocs/_exploration_log.md` documenting what you found:
+After exploring, write `vdocs/_planning/_exploration_log.md` documenting what you found:
 
 ```markdown
 # Exploration Log
@@ -42,6 +51,29 @@ After exploring, write `vdocs/_exploration_log.md` documenting what you found:
 | Prisma schema with 8 models | prisma/schema.prisma | DATA_MODEL_DOC.md |
 | ... | ... | ... |
 
+## 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 | None (read-only) |
+
+## Shared Behaviors
+| Behavior | Scope | Implementation |
+|----------|-------|----------------|
+| Auth | All /app/* routes | NextAuth middleware + useSession hook |
+
+## Integration Boundary
+| Direction | System | Purpose | Env Var |
+|-----------|--------|---------|--------|
+| Outgoing | Stripe API | Payments | STRIPE_SECRET_KEY |
+| Incoming | Stripe webhooks | Payment events | /api/webhooks/stripe |
+| Background | Cron: cleanup-sessions | Expire old sessions | Vercel Cron |
+
 ## Cross-Feature Dependencies
 After identifying all feature signals, grep for imports/references between features to map which features consume each other's data, types, or APIs. This prevents missing secondary workflows during doc generation.
 
@@ -60,7 +92,7 @@ This log is your working memory. It feeds directly into Step 2 (Plan).
 
 ## Step 2 — Plan
 
-Write `vdocs/_DOCUMENTATION_PLAN.md` to disk AND present it to the user in the same step. The file must be persisted — do not just show it in chat.
+Write `vdocs/_planning/_DOCUMENTATION_PLAN.md` to disk AND present it to the user in the same step. The file must be persisted — do not just show it in chat.
 
 Use this format:
 
@@ -94,7 +126,7 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-Read the template from `.gemini/vdoc/doc-template.md` once before starting.
+Read the template from [doc-template.md](./doc-template.md) once before starting.
 
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
@@ -108,25 +140,31 @@ Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle:
 
 **Writing rules:**
 
-- **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."
-- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **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. "Free users get 3 projects", "Sessions expire after 30 min of inactivity", "Rate limit: 100 req/min per API key." 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 step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality. [CONDITIONAL: omit for non-user-facing features like background jobs]
 - **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
-- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
-- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
-- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
-- **Constraints & Decisions** is the most valuable section. Dig into the code for non-obvious choices: "Uses polling instead of websockets because...", "Auth tokens expire in 15min because...". If you can't find the reason, state the constraint and mark it: `Reason: unknown — verify with team`.
-- **Related Features** must reference other docs by filename and explain the coupling: "Changes to the JWT schema will require updates to API_REFERENCE_DOC.md (auth middleware affects all endpoints)."
-- **Configuration** must list actual env vars/secrets from the code, not hypothetical ones.
-- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
+- **Key Files** — list every file in the execution path with a Type column (Source, Test, Config, Migration, Script, Route, Hook, Store). Include test files and config files, not just source. If a cron handler, executor, service, and DB helper are all involved, list all of them.
+- **Testing** — include the test run command, test file locations, what's covered, coverage gaps (honest assessment), and manual testing steps. This is critical for AI coders and onboarding developers.
+- **Common Tasks** — cookbook-style recipes for recurring modifications: "To add a new payment method, do X, Y, Z." [CONDITIONAL: omit for features with no recurring modification patterns]
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. [CONDITIONAL: omit for features without persistent state]
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present? [CONDITIONAL: omit for features with no non-obvious failure modes]
+- **Constraints & Decisions** is the most valuable section. Dig into the code for non-obvious choices: "Uses polling instead of websockets because...", "Auth tokens expire in 15min because...". Include security considerations here — auth patterns, access control, secrets. If you can't find the reason, state the constraint and mark it: `Reason: unknown — verify with team`.
+- **Related Features** — structured table with Doc, Relationship (depends on / depended by / shares data with), and Blast radius columns. Reference other docs by filename. Also populate the `relatedDocs` frontmatter array with the same filenames.
+- **Change Log** — add initial entry with today's date and "Initial documentation".
 
 ## Step 4 — Manifest
 
-Create `vdocs/_manifest.json` using the schema in `.gemini/vdoc/manifest-schema.json`.
+Create `vdocs/_manifest.json` using the schema in [manifest-schema.json](./manifest-schema.json).
 
 **Transfer the Fingerprint** from the exploration log into the manifest's top-level `fingerprint` object. This preserves the project identity metadata alongside the documentation inventory.
 
 The `description` field is critical — write it rich enough that you can route any user question to the right doc by matching against descriptions. Include specific technology names, patterns, and concepts.
 
+The `deps` field lists feature names (matching other entries' titles) that would break or behave differently if this feature changes. Populate from the Related Features table's "depends on" and "depended by" relationships. This enables blast radius analysis by downstream consumers.
+
 Example:
 
 ```json
@@ -144,23 +182,65 @@ Example:
       "title": "Authentication - OAuth2 & JWT",
       "version": "1.0.0",
       "description": "OAuth2 flow with Google/GitHub providers, JWT token lifecycle, session management via NextAuth.js, route protection middleware, and role-based access control.",
-      "tags": ["oauth2", "jwt", "session-management", "rbac"]
+      "tags": ["oauth2", "jwt", "session-management", "rbac"],
+      "deps": ["user-profile", "billing", "api-reference"]
     }
   ]
 }
 ```
 
-## Step 5 — Self-Review
+## Step 5 — Generate Context Slices
+
+For each generated doc, create a token-optimized context slice at `vdocs/_slices/{FEATURE_NAME}_SLICE.md`.
+
+A context slice contains ONLY these sections extracted 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)
+
+Format:
+
+```markdown
+<!-- Context slice for {Feature Title} — auto-generated, do not edit manually -->
+<!-- Full doc: vdocs/{FEATURE_NAME_DOC}.md -->
+
+# {Feature Title}
+
+{First paragraph of Overview}
+
+## Business Rules
+{Full Business Rules section}
+
+## Key Files
+{Full Key Files table}
+
+## Constraints & Decisions
+{Full Constraints & Decisions section}
+
+## Related Features
+{Full Related Features table}
+```
+
+These slices are designed for AI agent consumption — compact enough to include in context packs without exceeding token budgets. They auto-regenerate whenever the parent doc is created or updated.
+
+## Step 6 — Self-Review
 
 Before finishing, verify:
 
+- [ ] Every doc has valid YAML frontmatter (title, description, tags, version, keyFiles, relatedDocs, lastUpdated)
+- [ ] Frontmatter `keyFiles` matches the Key Files table entries
+- [ ] Frontmatter `relatedDocs` matches the Related Features table doc filenames
 - [ ] Every doc has at least one mermaid diagram in "How It Works"
 - [ ] Every doc has at least 2 entries in "Constraints & Decisions"
-- [ ] Every doc's "Key Files" lists real paths that exist in the codebase
-- [ ] Every doc's "Configuration" lists actual env vars from the code
-- [ ] Every doc's "Related Features" references other doc filenames
+- [ ] Every doc's Key Files lists real paths that exist in the codebase (include Type column)
+- [ ] Every doc has a Testing section with run command and coverage info
+- [ ] Every doc's Related Features uses the structured table format (Doc, Relationship, Blast radius)
+- [ ] Manifest entries include `deps` arrays populated from Related Features
 - [ ] Manifest `description` is detailed enough for semantic routing
 - [ ] No doc is just a shallow restatement of file names — each explains WHY and HOW
-- [ ] Every doc has "User Workflows" with at least one step-by-step journey
-- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
-- [ ] Every doc has a "Security" section documenting auth/access patterns
+- [ ] Every doc has "Business Rules" with at least one plain-language rule
+- [ ] CONDITIONAL sections are omitted (not left empty) when not relevant
+- [ ] Context slices exist in `vdocs/_slices/` for every generated doc
+- [ ] Planning artifacts are in `vdocs/_planning/` (exploration log, doc plan)

package/skills/gemini/references/manifest-schema.json

@@ -16,7 +16,8 @@
       "title": "Human-Readable Feature Title",
       "version": "1.0.0",
       "description": "Rich semantic description with specific technology names, patterns, and concepts. Detailed enough that an AI can route any user question to this doc by matching against this field.",
-      "tags": ["keyword-1", "keyword-2"]
+      "tags": ["keyword-1", "keyword-2"],
+      "deps": ["<feature-name-that-breaks-if-this-changes>"]
     }
   ]
 }

package/skills/jetbrains-ai/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/jetbrains-ai/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/jetbrains-ai/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 |
+```