@sandrinio/vdoc 3.3.1 → 3.5.0

package/bin/vdoc.mjs

@@ -13,10 +13,12 @@ const CWD = process.cwd();
 const PLATFORMS = {
   claude: {
     files: [
-      { src: 'claude/SKILL.md', dest: '.claude/skills/vdoc/SKILL.md' },
       { src: 'claude/vdoc-init.md', dest: '.claude/skills/vdoc-init/SKILL.md' },
-      { src: 'claude/vdoc-audit.md', dest: '.claude/skills/vdoc-audit/SKILL.md' },
+      { src: 'claude/vdoc-update.md', dest: '.claude/skills/vdoc-update/SKILL.md' },
+      { src: 'claude/vdoc-create.md', dest: '.claude/skills/vdoc-create/SKILL.md' },
       { src: 'claude/references/exploration-strategies.md', dest: '.claude/skills/vdoc-init/references/exploration-strategies.md' },
+      { src: 'claude/references/doc-template.md', dest: '.claude/skills/vdoc-config/references/doc-template.md' },
+      { src: 'claude/references/manifest-schema.json', dest: '.claude/skills/vdoc-config/references/manifest-schema.json' },
     ],
   },
   cursor: {
@@ -257,8 +259,10 @@ function uninstall() {
 
   // Clean skill directories that may have nested files
   const skillDirs = [
-    join(CWD, '.claude', 'skills', 'vdoc'),
+    join(CWD, '.claude', 'skills', 'vdoc-config'),
     join(CWD, '.claude', 'skills', 'vdoc-init'),
+    join(CWD, '.claude', 'skills', 'vdoc-update'),
+    join(CWD, '.claude', 'skills', 'vdoc-create'),
     join(CWD, '.claude', 'skills', 'vdoc-audit'),
     join(CWD, '.cursor', 'rules', 'vdoc'),
     join(CWD, '.windsurf', 'skills', 'vdoc'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vdoc",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "Documentation skills for AI coding agents",
   "type": "module",
   "bin": {

package/skills/agents/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/claude/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vdoc
+name: vdoc-config
 description: "Query existing project documentation. Use when user asks questions about the codebase and vdocs/ exists. For generating docs use /vdoc-init, for auditing use /vdoc-audit."
 ---
 

package/skills/claude/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,19 +5,19 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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 (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 `.claude/skills/vdoc-config/_exploration_log.md` documenting what you found:
 
 ```markdown
 # Exploration Log
@@ -51,7 +51,7 @@ This log is your working memory. It feeds directly into Step 2 (Plan).
 
 ## Step 2 — Plan
 
-Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
+Create `.claude/skills/vdoc-config/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 
 ```markdown
 # Documentation Plan
@@ -80,7 +80,7 @@ Wait for user approval before proceeding.
 For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Follow the template in `references/doc-template.md` exactly
+2. Read the template from `.claude/skills/vdoc-config/references/doc-template.md` and follow it exactly
 3. Write to `vdocs/FEATURE_NAME_DOC.md`
 
 **Writing rules:**
@@ -94,7 +94,7 @@ For each approved doc:
 
 ## Step 4 — Manifest
 
-Create `vdocs/_manifest.json` using the schema in `references/manifest-schema.json`.
+Create `vdocs/_manifest.json` using the schema in `.claude/skills/vdoc-config/references/manifest-schema.json`.
 
 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.
 

package/skills/claude/vdoc-create.md

@@ -0,0 +1,59 @@
+---
+name: vdoc-create
+description: "Create a single feature doc on demand. Use when user says 'document the auth system', 'create a doc for payments', or wants to add one specific doc to vdocs/."
+argument-hint: "<feature description>"
+---
+
+# vdoc create — Single Doc Generator
+
+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 `.claude/skills/vdoc-config/_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
+
+Do not skim. Understand how the feature actually works before writing.
+
+## Step 2 — Generate
+
+1. Read the template from `.claude/skills/vdoc-config/references/doc-template.md` and follow it exactly
+2. Write to `vdocs/FEATURE_NAME_DOC.md`
+
+### Writing Rules
+
+- **Mermaid diagrams are mandatory** in "How It Works". Show the actual flow — request lifecycle, state transitions, data pipeline. If a flow has more than 7-9 nodes, split into multiple diagrams.
+- **Data Model** must show real entities from the code, not generic placeholders. Use mermaid ER diagrams for relational data, tables for simpler models.
+- **Constraints & Decisions** is the most valuable section. Dig into the code for non-obvious choices. 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.
+- **Configuration** must list actual env vars/secrets from the code, not hypothetical ones.
+- **Error Handling** — trace what happens when things fail. What does the user see? What gets logged? Is there retry logic?
+
+## Step 3 — Update Manifest
+
+Read `vdocs/_manifest.json` and add the new doc entry using the schema in `.claude/skills/vdoc-config/references/manifest-schema.json`.
+
+If `vdocs/_manifest.json` doesn't exist, create it with the project name, version, and this doc as the first entry.
+
+## Step 4 — Self-Review
+
+Before finishing, verify:
+
+- [ ] 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 that exist in the codebase
+- [ ] "Configuration" lists actual env vars from the code
+- [ ] "Related Features" references other doc filenames (if other docs exist)
+- [ ] Manifest `description` is detailed enough for semantic routing
+- [ ] Doc explains WHY and HOW, not just WHAT
+
+## Rules
+
+1. **Feature-centric, not file-centric.** The doc covers one logical feature, not one source file.
+2. **No hallucination.** Only document what exists in code.
+3. **No scripts.** Do NOT create shell scripts, scanners, or build tools. Use Read/Glob/Grep.

package/skills/claude/vdoc-init.md

@@ -14,17 +14,17 @@ Generate feature-centric documentation from source code. All docs go in `vdocs/`
 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 using Read, Glob, and Grep to identify the project's language, framework, and archetype (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 
 **Phase 3 — Write Exploration Log**
-After exploring, write `vdocs/_exploration_log.md` documenting what you found:
+After exploring, write `.claude/skills/vdoc-config/_exploration_log.md` documenting what you found:
 
 ```markdown
 # Exploration Log
@@ -58,7 +58,7 @@ This log is your working memory. It feeds directly into Step 2 (Plan).
 
 ## Step 2 — Plan
 
-Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
+Create `.claude/skills/vdoc-config/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 
 ```markdown
 # Documentation Plan
@@ -87,81 +87,9 @@ Present the plan to the user. Actively suggest changes:
 For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Follow the template below exactly
+2. Read the template from `.claude/skills/vdoc-config/references/doc-template.md` and follow it exactly
 3. Write to `vdocs/FEATURE_NAME_DOC.md`
 
-### Doc Template
-
-```markdown
-# {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}*
-```
-
 ### Writing Rules
 
 - **Mermaid diagrams are mandatory** in "How It Works". Show the actual flow — request lifecycle, state transitions, data pipeline. If a flow has more than 7-9 nodes, split into multiple diagrams.
@@ -173,26 +101,7 @@ For each approved doc:
 
 ## Step 4 — Manifest
 
-Create `vdocs/_manifest.json`:
-
-```json
-{
-  "project": "<project-name>",
-  "vdoc_version": "3.0.0",
-  "created_at": "<ISO-8601>",
-  "last_updated": "<ISO-8601>",
-  "last_commit": "<short-sha>",
-  "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"]
-    }
-  ]
-}
-```
+Create `vdocs/_manifest.json` using the schema in `.claude/skills/vdoc-config/references/manifest-schema.json`.
 
 The `description` field is critical — write it rich enough that you can route any user question to the right doc by matching against descriptions.
 

package/skills/claude/vdoc-update.md

@@ -0,0 +1,80 @@
+---
+name: vdoc-update
+description: "Update existing vdocs to match current code. Use when user says 'update docs', 'sync docs', 'check docs', or documentation may be out of sync with code."
+---
+
+# vdoc update — Documentation Update
+
+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.
+
+---
+
+## 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:
+
+```
+Update Report:
+
+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 (use `/vdoc-create` for each)
+- Flag dead docs for user to confirm deletion
+- Fix cross-reference issues
+- Update manifest: bump versions, update `last_updated`, `last_commit`
+
+## Rules
+
+1. **No scripts.** Do NOT create shell scripts, scanners, or build tools. Use Read/Glob/Grep/Bash(git).
+2. **Report before patching.** Always present findings and wait for user direction.
+3. **No hallucination.** Only report what you verified in the code and filesystem.

package/skills/cline/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/continue/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/cursor/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/gemini/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/jetbrains-ai/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

package/skills/jetbrains-ai/references/init-workflow.md

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/junie/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

package/skills/vscode/references/exploration-strategies.md

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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`.
 
 **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.
+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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.
 

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

@@ -47,6 +47,22 @@ Match the detected archetype and follow its playbook. Each defines:
 - **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
@@ -287,3 +303,39 @@ If the project doesn't clearly match any archetype:
 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.

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

@@ -5,12 +5,12 @@
 Follow the two-phase exploration strategy in `resources/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 (Web API, Frontend SPA, Full-stack, CLI, Library, Mobile, Data Pipeline, Monorepo, Microservices, or Infrastructure).
+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 `resources/exploration-strategies.md`.
 
 **Phase 2 — Targeted Exploration** (archetype-specific)
-Apply the matching archetype playbook from `resources/exploration-strategies.md`. Read files in priority order using the glob patterns listed. Identify feature signals — each signal maps to a documentable feature.
+Apply the matching archetype playbook from `resources/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).
 
-If the project spans multiple archetypes (e.g., a monorepo with frontend + API), apply multiple playbooks. If no archetype matches, use the Fallback strategy and confirm with the user.
+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.