@sandrinio/vdoc 3.7.1 → 3.9.0

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

package/skills/gemini/references/doc-template.md

@@ -1,92 +1,162 @@
+---
+title: "{Feature Title}"
+description: "{One-line description of what this covers}"
+tags: ["{domain}", "{capability}"]
+version: 1
+keyFiles: ["{src/path/main-file.ts}"]
+relatedDocs: []
+lastUpdated: "{YYYY-MM-DD}"
+---
+
 # {Feature Title}
 
-> {One-line description of what this covers}
+> {One-line description — same as frontmatter description}
+
+<!-- TEMPLATE GUIDANCE
+  Sections marked [CORE] — always include.
+  Sections marked [CONDITIONAL] — include only when relevant, omit entirely otherwise.
+  Do NOT leave empty sections or write "N/A".
+-->
 
 ---
 
 ## Overview
+<!-- [CORE] -->
+
+{What it does, why it exists, and who it's for. Lead with the user value — what problem does this solve? Then explain how it fits in the broader system. A PM should be able to read this section alone and understand the feature.}
+
+---
+
+## Business Rules
+<!-- [CORE] -->
+
+{Plain-language rules that govern this feature's behavior. No code, no implementation details — just the "what" and "why" a PM or stakeholder needs to know.}
+
+- {Rule}: {Description}
 
-{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+<!-- Examples:
+- **Trial limit**: Free users get 3 projects. Creating a 4th triggers the upgrade prompt.
+- **Auto-archive**: Inactive workspaces are archived after 90 days. Owners get email warnings at 60 and 80 days.
+- **Rate limiting**: API consumers are capped at 100 req/min per API key. Exceeding returns 429.
+-->
 
 ---
 
 ## User Workflows
+<!-- [CONDITIONAL: include for user-facing features] -->
 
-{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+{Step-by-step journeys for the 1-3 primary user actions.}
 
 1. **{Workflow Name}**
-   - **User action:** {What the user does}
-   - **System response:** {What the system does}
-   - **Result:** {What the user sees}
+   - **Trigger:** {What the user does}
+   - **Steps:** {What happens — keep it sequential}
+   - **Result:** {What the user sees or gets}
 
 ---
 
 ## How It Works
+<!-- [CORE] -->
 
-{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
+{Trace at least one complete request from trigger to final effect. Show the full path through every service, database call, and external system. Don't skip intermediaries.}
 
 {Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. Max 7-9 nodes per diagram, split into multiple if larger.}
 
 ---
 
-## Data Model
+## Key Files
 
-{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+<!-- [CORE] -->
 
-| Column | Type | Description |
-|--------|------|-------------|
-| `column_name` | `type` | What it stores |
+| File | Type | Purpose |
+|------|------|---------|
+| `src/path/file.ts` | Source | {What this file does} |
+| `src/path/file.test.ts` | Test | {What it validates} |
+| `.env` / `config.ts` | Config | {What it controls} |
 
-{Mermaid ER diagram for relationships between tables.}
+<!-- Type = Source, Test, Config, Migration, Script, Route, Hook, Store, Template, etc. -->
 
 ---
 
-## Key Files
+## Testing
+<!-- [CORE] -->
 
-| File | Purpose |
-|------|---------|
-| `src/path/file.ts` | What this file does |
+**Run:** `{test command — e.g. npm test -- --grep "feature-name"}`
 
----
+| What | Location | Notes |
+|------|----------|-------|
+| Unit tests | `{path}` | {What's covered} |
+| Integration tests | `{path}` | {What's covered} |
+| E2E tests | `{path}` | {What's covered} |
 
-## Dependencies & Integrations
+**Coverage gaps:** {What is NOT tested and why — honest assessment. "None" if fully covered.}
 
-{External services, internal features, packages this relies on.}
+**Manual testing:** {Steps for anything that requires manual verification, or "Fully automated" if none.}
 
 ---
 
-## Configuration
+## Common Tasks
+<!-- [CONDITIONAL: include when feature has recurring modification patterns] -->
 
-| Variable | Purpose | Required |
-|----------|---------|----------|
-| `ENV_VAR` | What it controls | Yes/No |
+{Cookbook-style recipes for the things developers actually do with this feature. Each recipe should be copy-paste actionable.}
+
+### {Task name — e.g. "Add a new payment method"}
+1. {Step}
+2. {Step}
+3. {Step}
+
+<!-- Keep recipes short (3-6 steps). If a task needs more, it's probably a workflow, not a recipe. -->
 
 ---
 
-## Error Handling & Edge Cases
+## Data Model
+<!-- [CONDITIONAL: include when feature owns database tables or persistent state] -->
 
-{Specific failure scenarios, not generic statements. For each:}
+{Primary tables/collections this feature owns.}
 
-- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
-## Security
+## Dependencies & Integrations
+<!-- [CONDITIONAL: include when feature depends on external services or other features] -->
 
-{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
+| Dependency | Type | What breaks if it's down |
+|------------|------|--------------------------|
+| `{service/package/feature}` | External / Internal | {Impact} |
+
+---
+
+## Error Handling & Edge Cases
+<!-- [CONDITIONAL: include when feature has non-obvious failure modes] -->
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
 
 ---
 
 ## Constraints & Decisions
+<!-- [CORE] -->
 
-{Why it's built this way. What you CANNOT change without breaking things.}
+{Why it's built this way. What you CANNOT change without breaking things. Include security considerations here — auth patterns, access control, secrets — when relevant.}
+
+- **{Decision}**: {What was decided and why. What alternative was rejected.}
 
 ---
 
 ## Related Features
+<!-- [CORE] -->
 
-{Cross-references to other docs by filename. Blast radius — what breaks if this changes.}
+| Doc | Relationship | Blast radius |
+|-----|-------------|--------------|
+| `{filename.md}` | {depends on / depended by / shares data with} | {What breaks if this feature changes} |
 
 ---
 
-*Generated by vdoc v3.0.0 • Last updated: {timestamp}*
+## Change Log
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Initial documentation | vdoc |

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,38 @@ 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.
+
+| Feature A | Feature B | Connection | Impact |
+|-----------|-----------|------------|--------|
+| Azure DevOps Integration | Google Sheets Export | Sheets exports work items fetched by Azure module | Azure doc must cover the export workflow |
+| Auth (NextAuth) | All API routes | Every route uses auth middleware | Auth doc must list all protected routes |
+| ... | ... | ... | ... |
+
 ## Ambiguities / Open Questions
 - Could not determine why Redis is in dependencies — no usage found. Ask user.
 - Payments folder exists but appears incomplete / WIP.
@@ -51,13 +92,19 @@ 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:
 
 ```markdown
 # Documentation Plan
 
+## Fingerprint
+- **Language(s):** e.g., TypeScript, Python
+- **Framework(s):** e.g., Next.js 14, FastAPI
+- **Archetype(s):** e.g., Full-stack Framework
+- **Scope:** e.g., ~85 files, medium
+
 ## Proposed Documents
 
 1. **PROJECT_OVERVIEW_DOC.md** — Tech stack, architecture, project structure, dev setup
@@ -79,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:
 
@@ -93,46 +140,107 @@ 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
 {
-  "filepath": "AUTHENTICATION_DOC.md",
-  "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"]
+  "project": "my-project",
+  "fingerprint": {
+    "languages": ["TypeScript"],
+    "frameworks": ["Next.js 14", "Prisma", "NextAuth"],
+    "archetypes": ["Full-stack Framework"],
+    "scope": "~85 files, medium"
+  },
+  "documentation": [
+    {
+      "filepath": "AUTHENTICATION_DOC.md",
+      "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"],
+      "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)