@sandrinio/vdoc 3.7.1 → 3.9.0

package/skills/agents/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/agents/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 `.agents/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 `.agents/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)

package/skills/agents/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/claude/references/audit-workflow.md

@@ -1,6 +1,6 @@
 # Audit Workflow
 
-Detect stale, missing, and dead 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.
+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
 
@@ -10,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
 
@@ -24,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:
 
@@ -43,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
 
@@ -51,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)
+- 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