@sandrinio/vdoc 3.0.1 → 3.4.0

package/skills/vscode/vdoc.prompt.md

@@ -1,31 +1,21 @@
 ---
 agent: 'agent'
-description: 'Generate and maintain feature-centric product documentation'
+description: 'Use when user says /vdoc, document this project, audit docs, or asks about existing project documentation'
 name: 'vdoc'
 argument-hint: '[init|audit]'
-tools: ['changes', 'codebase', 'githubRepo', 'problems']
+tools: ['search/changes', 'search/codebase', 'web/githubRepo', 'read/problems']
 ---
 
 # vdoc — Documentation Generator
 
-Run documentation workflows for this project. Full instructions are in `.github/instructions/vdoc.instructions.md`.
+Run documentation workflows for this project.
 
 **Mode: ${input:mode:init}**
 
 ## If mode is `init` (or no `vdocs/` folder exists):
 
-1. **Explore** — Read the codebase: tech stack, features, architecture, integrations, entry points. Use #tool:codebase to search broadly. Read actual files.
-2. **Plan** — Create `vdocs/_DOCUMENTATION_PLAN.md` listing proposed docs. Present to user. Wait for approval.
-3. **Generate** — For each doc, read ALL relevant source files. Write `vdocs/FEATURE_NAME_DOC.md` following the template in `.github/instructions/vdoc.instructions.md`.
-4. **Manifest** — Create `vdocs/_manifest.json` with rich semantic descriptions.
-5. **Verify** — Every doc has mermaid diagrams, real paths, 2+ constraints, cross-references.
+Read and follow the workflow at `.github/skills/vdoc/references/init-workflow.md`. Use `.github/skills/vdoc/references/doc-template.md` as the doc template and `.github/skills/vdoc/references/manifest-schema.json` for the manifest format.
 
 ## If mode is `audit` (or `vdocs/` already exists):
 
-1. Read `vdocs/_manifest.json`
-2. **Stale** — Use #tool:changes to find modified source files. Cross-ref with each doc's "Key Files" section.
-3. **Gaps** — Find undocumented features (new routes, services, models)
-4. **Dead** — Docs referencing deleted files
-5. **Cross-refs** — Verify Related Features links still valid
-6. **Report** — Present findings, wait for user direction
-7. **Patch** — Update stale docs, generate gaps, fix cross-refs, update manifest
+Read and follow the workflow at `.github/skills/vdoc/references/audit-workflow.md`.

package/skills/windsurf/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: vdoc
+description: "Use when user says /vdoc, 'document this project', 'audit docs', or asks questions about existing project documentation, stale docs, undocumented features, or documentation coverage gaps"
+---
+
+# vdoc — Documentation Generator
+
+## Overview
+
+Documentation must be feature-centric, plan-approved, and grounded in source code. Never generate docs from assumptions.
+
+## When to Use
+- User says `/vdoc`, "document this project", "audit docs", or asks about documentation
+- Docs are stale, missing, or out of sync with code (documentation drift, undocumented features, coverage gaps)
+- After significant feature work that changed codebase behavior
+
+## When NOT to Use
+- API reference docs (use JSDoc/TSDoc)
+- README files or contribution guides
+- Inline code comments
+
+---
+
+Three modes: **init**, **audit**, **query**. All docs live in `vdocs/`. Manifest at `vdocs/_manifest.json` is the semantic index.
+
+## Init (`/vdoc init`)
+
+Read the detailed workflow at `resources/init-workflow.md`.
+
+Summary: Explore codebase → Plan docs → User approves → Generate using template → Build manifest → Self-review.
+
+## Audit (`/vdoc audit`)
+
+Read the detailed workflow at `resources/audit-workflow.md`.
+
+Summary: Read manifest → Detect stale/gaps/dead docs → Check cross-refs → Report → Patch with approval.
+
+## Query (any documentation question)
+
+1. Read `vdocs/_manifest.json`
+2. Match question against `description` and `tags` fields
+3. Read matching doc(s)
+4. Answer from documented knowledge
+5. If no match, suggest running an audit
+
+## Rules
+
+1. **Feature-centric, not file-centric.** One doc per logical feature, not per source file.
+2. **Mermaid over prose.** Diagram flows. Max 7-9 nodes per diagram.
+3. **Constraints are gold.** Always fill "Constraints & Decisions".
+4. **Rich manifest descriptions.** Pack with specific terms for semantic routing.
+5. **No hallucination.** Only document what exists in code.
+6. **Plan first, always.** Never generate without user-approved plan.
+
+## Common Mistakes
+- **File-centric instead of feature-centric** — Don't create one doc per source file. Group by logical feature.
+- **Documenting aspirations** — Only document what the code actually does today, not planned work.
+- **Skipping the plan** — Generating without user approval leads to rework and coverage gaps.
+- **Oversized diagrams** — Keep Mermaid to 7-9 nodes; split if larger.
+- **Shallow constraints** — "Constraints & Decisions" is the most valuable section. Dig for non-obvious choices.
+
+## Red Flags — STOP
+- Generating docs without an approved plan
+- Documenting something you haven't verified in source code
+- Creating one doc per file instead of per feature
+- Skipping Mermaid diagrams in "How It Works"
+- Writing manifest descriptions too vague for semantic routing

package/skills/windsurf/resources/audit-workflow.md

@@ -0,0 +1,65 @@
+# Audit Workflow
+
+## Step 1 — Read Current State
+
+Read `vdocs/_manifest.json`. Load the list of documented features and their metadata.
+
+## Step 2 — Detect Stale Docs
+
+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.
+
+## Step 3 — Detect Coverage Gaps
+
+Scan the codebase for significant features not covered by any doc. Look for:
+- New route files / API endpoints
+- New service classes or modules
+- New database models / schema changes
+- New configuration or infrastructure files
+
+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?"
+
+## Step 5 — Check Cross-References
+
+Read each doc's "Related Features" section. Verify that:
+- Referenced doc filenames still exist
+- The described coupling is still accurate (skim the relevant code)
+
+## Step 6 — Report
+
+Present a clear report:
+
+```
+Audit Results:
+
+STALE (source files changed):
+  - AUTHENTICATION_DOC.md — src/lib/auth.ts changed (added GitHub provider)
+  - API_REFERENCE_DOC.md — 2 new endpoints added
+
+COVERAGE GAPS (undocumented features):
+  - src/services/notification.ts — no doc covers notifications
+
+DEAD DOCS (source files removed):
+  - LEGACY_ADMIN_DOC.md — all 4 source files deleted
+
+CROSS-REF ISSUES:
+  - AUTHENTICATION_DOC.md references BILLING_DOC.md which no longer exists
+
+CURRENT (no changes needed):
+  - DATABASE_SCHEMA_DOC.md
+  - PROJECT_OVERVIEW_DOC.md
+
+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)
+- Flag dead docs for user to confirm deletion
+- Fix cross-reference issues
+- Update manifest: bump versions, update `last_updated`, `last_commit`

package/skills/windsurf/resources/doc-template.md

@@ -0,0 +1,67 @@
+# {Feature Title}
+
+> {One-line description of what this covers}
+
+---
+
+## Overview
+
+{What it does, why it exists, how it fits in the system.}
+
+---
+
+## How It Works
+
+{Core logic and flow.}
+
+{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+
+---
+
+## Data Model
+
+{Entities this feature owns and their relationships. Mermaid ER diagram or table.}
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/path/file.ts` | What this file does |
+
+---
+
+## Dependencies & Integrations
+
+{External services, internal features, packages this relies on.}
+
+---
+
+## Configuration
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `ENV_VAR` | What it controls | Yes/No |
+
+---
+
+## Error Handling
+
+{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+
+---
+
+## Constraints & Decisions
+
+{Why it's built this way. What you CANNOT change without breaking things.}
+
+---
+
+## Related Features
+
+{Cross-references to other docs by filename. Blast radius — what breaks if this changes.}
+
+---
+
+*Generated by vdoc v3.0.0 • Last updated: {timestamp}*

package/skills/windsurf/resources/exploration-strategies.md

@@ -0,0 +1,341 @@
+# Exploration Strategies
+
+Smart, targeted codebase exploration. Two phases: fingerprint the project, then follow the right archetype playbook.
+
+## Phase 1 — Fingerprint
+
+Read these high-signal files first (whichever exist) to classify the project. **3-5 reads max.**
+
+### Package / Config Files (read 1-2)
+
+| File | Ecosystem |
+|------|-----------|
+| `package.json` | Node.js / JavaScript / TypeScript |
+| `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `Gemfile` | Ruby |
+| `pom.xml` / `build.gradle` | Java / Kotlin |
+| `composer.json` | PHP |
+| `*.csproj` / `*.sln` | .NET |
+| `pubspec.yaml` | Dart / Flutter |
+
+### Structure Scan
+
+- List root directory
+- List `src/` or `app/` or `lib/` (whichever exists)
+
+### Entry Points (read 1-2)
+
+- README.md (first 50 lines)
+- Main entry file (e.g., `src/index.ts`, `main.py`, `cmd/main.go`)
+
+### Determine
+
+1. **Primary language(s)** and framework(s)
+2. **Project archetype** — match to a playbook below
+3. **Rough scope** — small (< 20 files), medium (20-100), large (100+)
+
+If the project spans multiple archetypes (e.g., monorepo with frontend + API), apply multiple playbooks.
+
+---
+
+## Phase 2 — Archetype Playbooks
+
+Match the detected archetype and follow its playbook. Each defines:
+- **Glob patterns** — files to read, in priority order
+- **What to extract** — what each file category reveals
+- **Feature signals** — patterns that indicate documentable features
+
+### Composing Archetypes
+
+Most real projects don't fit a single archetype. **Combine playbooks** when needed:
+
+- A FastAPI app with AI agent workflows → **Web API** playbook for routes/middleware/auth + read `**/workflows/**`, `**/agents/**`, `**/chains/**`, `**/prompts/**` for the agent layer
+- A Next.js app with a Python microservice → **Full-Stack Framework** + **Web API** playbooks
+- A CLI that wraps an SDK → **CLI Tool** + **Library/SDK** playbooks
+
+**How to compose:**
+1. Pick the **primary archetype** (what the project fundamentally is)
+2. Follow its playbook fully
+3. When you encounter directories/patterns that belong to another archetype, pull in that playbook's glob patterns and feature signals
+4. In the exploration log, note which archetypes you composed and why
+
+Do not force a project into one archetype. The playbooks are building blocks — use what fits.
+
+---
+
+### Web API
+
+**Signals:** Express, FastAPI, Django REST, Rails, Spring Boot, Gin, Actix, Phoenix, Hono, NestJS
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/routes/**`, `**/router.*`, `**/urls.py` | Endpoints, HTTP methods, URL structure |
+| 2 | `**/middleware/**`, `**/middleware.*` | Auth, CORS, rate limiting, logging, error handling |
+| 3 | `**/models/**`, `**/schema*`, `**/migrations/**` | Data model, entities, relationships |
+| 4 | `**/controllers/**`, `**/handlers/**`, `**/views/**` | Business logic per endpoint |
+| 5 | `**/services/**`, `**/lib/**` | Shared logic, external integrations |
+| 6 | `**/config/**`, `.env*`, `**/settings*` | Environment config, feature flags |
+| 7 | `**/tests/**` (skim 2-3) | What's tested reveals what matters |
+
+**Feature signals:**
+- Auth routes/middleware → Authentication doc
+- Payment/billing routes → Payments doc
+- File upload handlers → File Management doc
+- WebSocket/SSE handlers → Real-time doc
+- Background jobs/queues → Background Processing doc
+- Email/notification services → Notifications doc
+- Search endpoints → Search doc
+- Admin routes → Admin Panel doc
+
+---
+
+### Frontend SPA
+
+**Signals:** React (CRA/Vite), Vue, Svelte, Angular, Solid
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/pages/**`, `**/views/**`, `**/routes*` | Page tree, routing structure |
+| 2 | `**/store/**`, `**/context/**`, `**/state/**`, `**/*slice*` | State shape, data flow |
+| 3 | `**/api/**`, `**/services/**`, `**/hooks/use*` | API integration, data fetching |
+| 4 | `**/components/**` (skim top-level) | Component architecture, shared vs feature |
+| 5 | `**/types/**`, `**/interfaces/**`, `**/*.d.ts` | Data contracts, shared types |
+| 6 | `**/utils/**`, `**/helpers/**` | Shared utilities |
+| 7 | `**/config/**`, `.env*` | Feature flags, API URLs, build config |
+
+**Feature signals:**
+- Auth context/store + login pages → Authentication doc
+- Form components + validation → Forms doc
+- Data tables with pagination → Data Display doc
+- Charts/dashboards → Analytics doc
+- Theming/i18n files → Theming / Internationalization doc
+- File upload components → Media Management doc
+
+---
+
+### Full-Stack Framework
+
+**Signals:** Next.js, Nuxt, SvelteKit, Remix, RedwoodJS, Blitz, Astro (SSR)
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/app/**/page.*`, `**/pages/**`, `**/routes/**` | UI pages AND API routes — the router is the architecture |
+| 2 | `**/api/**`, `**/server/**`, `**/actions/**` | Server-side logic, server actions |
+| 3 | `**/models/**`, `**/schema*`, `**/prisma/**`, `**/drizzle/**` | Data layer, ORM config |
+| 4 | `**/middleware.*`, `**/middleware/**` | Request pipeline, auth, redirects |
+| 5 | `**/components/**` (skim top-level) | Shared UI components |
+| 6 | `**/lib/**`, `**/utils/**`, `**/services/**` | Shared server + client utilities |
+| 7 | `**/config/**`, `.env*`, `next.config.*`, `nuxt.config.*` | Framework and environment config |
+
+**Feature signals:**
+- All Web API signals + all Frontend SPA signals
+- Server actions / mutations → Data Mutation doc
+- ISR/SSG configuration → Rendering Strategy doc
+- Edge functions / middleware → Edge Computing doc
+
+---
+
+### CLI Tool
+
+**Signals:** Commander, Yargs, Click, Typer, Cobra, Clap, oclif, Argparse
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/commands/**`, `**/cmd/**`, `**/cli.*` | Command tree, subcommands |
+| 2 | Main entry (`bin/*`, `src/index.*`, `src/main.*`) | Argument parsing, top-level flow |
+| 3 | `**/config*`, `**/*rc*`, `**/settings*` | Config file formats, defaults |
+| 4 | `**/utils/**`, `**/lib/**`, `**/core/**` | Core logic behind commands |
+| 5 | `**/output*`, `**/format*`, `**/display*` | Output formatting (JSON, table, etc.) |
+| 6 | `**/templates/**`, `**/scaffolds/**` | Code generation templates |
+
+**Feature signals:**
+- Multiple subcommands → one doc per command group
+- Config file handling → Configuration doc
+- Plugin/extension system → Plugin Architecture doc
+- Interactive prompts → User Interaction doc
+- File I/O operations → File Processing doc
+
+---
+
+### Library / SDK
+
+**Signals:** Published package with `main`/`exports` in package.json, `lib/` with clear public API, type declarations
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | Main export (`src/index.*`, `lib/index.*`, `__init__.py`) | Public API surface |
+| 2 | `**/*.d.ts`, `**/types.*`, `**/interfaces.*` | Type contracts, input/output shapes |
+| 3 | `**/core/**`, `**/lib/**` | Internal implementation |
+| 4 | `**/utils/**`, `**/helpers/**` | Supporting utilities |
+| 5 | `**/examples/**`, `**/demo/**` | Usage patterns |
+| 6 | `**/plugins/**`, `**/adapters/**`, `**/providers/**` | Extension points |
+| 7 | `**/tests/**` (skim 2-3) | Edge cases, expected behavior |
+
+**Feature signals:**
+- Multiple exported classes/functions → Core API doc
+- Plugin/adapter pattern → Extension Architecture doc
+- Multiple output formats → Serialization doc
+- Caching layer → Performance doc
+
+---
+
+### Mobile App
+
+**Signals:** React Native, Flutter, SwiftUI, Jetpack Compose, Expo, Ionic, Capacitor
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/screens/**`, `**/pages/**`, `**/views/**` | Screen tree, navigation structure |
+| 2 | `**/navigation/**`, `**/router*` | Navigation graph, deep linking |
+| 3 | `**/store/**`, `**/state/**`, `**/providers/**` | State management, data flow |
+| 4 | `**/api/**`, `**/services/**`, `**/network/**` | Backend communication, offline sync |
+| 5 | `**/components/**` (skim) | Shared UI components |
+| 6 | `**/native/**`, `**/platform/**`, `**/ios/**`, `**/android/**` | Platform-specific code, native modules |
+| 7 | `**/assets/**` (list only) | Bundled resources |
+
+**Feature signals:**
+- Push notification setup → Notifications doc
+- Camera/media access → Media Capture doc
+- Offline storage (SQLite, Realm, AsyncStorage) → Data Persistence doc
+- Deep linking / universal links → Navigation doc
+- Platform-specific native modules → Platform Integration doc
+
+---
+
+### Data Pipeline / ML
+
+**Signals:** Airflow, dbt, Prefect, Dagster, Luigi, Pandas, Spark, TensorFlow, PyTorch, scikit-learn, Jupyter notebooks
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/dags/**`, `**/pipelines/**`, `**/flows/**`, `**/workflows/**` | Pipeline definitions, DAGs, task graph |
+| 2 | `**/models/**` (ML or dbt) | Model definitions, training logic or SQL transforms |
+| 3 | `**/sources/**`, `**/extractors/**`, `**/connectors/**` | Data sources, ingestion logic |
+| 4 | `**/transforms/**`, `**/processors/**` | Data transformation logic |
+| 5 | `**/schemas/**`, `**/contracts/**` | Data contracts, validation |
+| 6 | `**/notebooks/**`, `*.ipynb` | Exploratory analysis, experiments |
+| 7 | `**/config/**`, `**/profiles*` | Connection strings, environment config |
+
+**Feature signals:**
+- Multiple DAGs/pipelines → one doc per pipeline
+- ML model training → Model Training doc
+- Feature engineering → Feature Store doc
+- Data validation (Great Expectations, Pandera) → Data Quality doc
+- Scheduled runs → Orchestration doc
+
+---
+
+### Monorepo
+
+**Signals:** Turborepo, Nx, Lerna, Rush, Bazel, pnpm workspaces — has `packages/`, `apps/`, or `workspace` config
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | Root config (`turbo.json`, `nx.json`, `lerna.json`, `pnpm-workspace.yaml`) | Workspace structure, build pipeline |
+| 2 | `packages/*/package.json` or `apps/*/package.json` | All packages/apps and their dependencies |
+| 3 | `**/shared/**`, `**/common/**`, `**/core/**` | Shared packages that others depend on |
+| 4 | Each app/package entry point (skim) | Purpose of each workspace member |
+
+**Then apply the matching sub-archetype playbook** to each significant package/app (e.g., Web API for the backend, Frontend SPA for the frontend, Library for shared packages).
+
+**Feature signals:**
+- Shared packages → Shared Infrastructure doc
+- Build/deploy pipeline → Build System doc
+- Inter-package dependencies → Architecture Overview doc (dependency graph)
+
+---
+
+### Microservices
+
+**Signals:** Docker Compose, Kubernetes manifests, multiple services with separate entry points, API gateway, service mesh
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `docker-compose*`, `**/k8s/**`, `**/helm/**`, `**/terraform/**` | Service topology, infrastructure |
+| 2 | API gateway config, `**/gateway/**` | Routing, load balancing, auth gateway |
+| 3 | Each service's entry point and routes (skim) | Service responsibilities, API surface |
+| 4 | `**/proto/**`, `**/graphql/**`, `**/schemas/**` | Inter-service contracts (gRPC, GraphQL) |
+| 5 | `**/queues/**`, `**/events/**`, `**/messaging/**` | Async communication, event bus |
+| 6 | `**/shared/**`, `**/common/**` | Shared libraries across services |
+
+**Then apply the Web API playbook** to each significant service.
+
+**Feature signals:**
+- Service discovery → Service Mesh doc
+- Event-driven communication → Event Architecture doc
+- Shared vs per-service database → Data Architecture doc
+- Health checks / circuit breakers → Resilience doc
+
+---
+
+### Infrastructure / IaC
+
+**Signals:** Terraform, Pulumi, CloudFormation, Ansible, CDK, Serverless Framework
+
+| Priority | Glob Pattern | What to Extract |
+|----------|-------------|-----------------|
+| 1 | `**/main.tf`, `**/stacks/**`, `**/lib/**` (CDK) | Resource definitions, stack structure |
+| 2 | `**/variables*`, `**/inputs*`, `**/config*` | Parameterization, environment configs |
+| 3 | `**/modules/**`, `**/constructs/**` | Reusable infrastructure modules |
+| 4 | `**/environments/**`, `**/stages/**` | Environment-specific overrides |
+| 5 | `**/outputs*`, `**/exports*` | Cross-stack references |
+| 6 | CI/CD config (`.github/workflows/`, `Jenkinsfile`) | Deployment pipeline |
+
+**Feature signals:**
+- Networking (VPC, subnets, security groups) → Networking doc
+- Compute (ECS, Lambda, EC2) → Compute Architecture doc
+- Data stores (RDS, DynamoDB, S3) → Data Infrastructure doc
+- CI/CD pipeline → Deployment Pipeline doc
+- Monitoring (CloudWatch, Datadog) → Observability doc
+
+---
+
+## Fallback — Unknown Archetype
+
+If the project doesn't clearly match any archetype:
+
+1. List the root directory and `src/` (or equivalent)
+2. Read the top 5 largest files by line count
+3. Read any files with "main", "app", "server", "index", or "core" in the name
+4. Check test files — they reveal what developers think is important
+5. Check CI/CD config (`.github/workflows/`, `Jenkinsfile`) — pipeline steps reveal build/deploy architecture
+
+Then propose an archetype to the user: *"This looks like a [X] project. I'll explore it using the [X] playbook. Sound right?"*
+
+---
+
+## Existing Documentation
+
+During fingerprinting, check if the project already has documentation:
+
+- `vdocs/_manifest.json` — previous vdoc output
+- `docs/`, `documentation/`, `product_documentation/` — existing docs folder
+- `README.md` (if substantial, beyond basic setup)
+- `*.md` files in the project root
+
+**If existing docs are found:**
+
+1. **Read the existing docs first** — they are a head start, not waste
+2. **Cross-reference with the actual codebase** — verify claims in the docs against real code. Flag anything that's:
+   - **Stale** — docs describe behavior that no longer matches the code
+   - **Missing** — code has features not covered in docs
+   - **Accurate** — docs match the code (reuse this content, don't rewrite it)
+3. **In the exploration log**, add a section:
+
+```markdown
+## Existing Documentation
+| Source | Status | Notes |
+|--------|--------|-------|
+| product_documentation/AUTH_DOC.md | Accurate | Matches current auth flow |
+| product_documentation/API_DOC.md | Stale | 3 new endpoints not documented |
+| (no existing doc) | Gap | RAG retrieval pipeline undocumented |
+```
+
+4. **In the Plan (Step 2)**, propose:
+   - **Update** for stale docs (specify what changed)
+   - **New** for gaps
+   - **Keep** for accurate docs (copy/adapt into vdocs/ format)
+
+This avoids regenerating documentation that already exists and is correct.