@sandrinio/vdoc 3.7.1 → 3.9.0

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

@@ -4,13 +4,20 @@
   "created_at": "<ISO-8601>",
   "last_updated": "<ISO-8601>",
   "last_commit": "<short-sha>",
+  "fingerprint": {
+    "languages": ["<language>"],
+    "frameworks": ["<framework>"],
+    "archetypes": ["<archetype>"],
+    "scope": "<file-count-and-size-category>"
+  },
   "documentation": [
     {
       "filepath": "FEATURE_NAME_DOC.md",
       "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/vscode/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/vscode/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/vscode/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/vscode/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 |