@sandrinio/vdoc 3.5.2 → 3.6.0

package/README.md

@@ -47,30 +47,48 @@ Then open Cursor and type: **`/vdoc init`**
 
 ## How It Works
 
+vdoc is **plan-first**. The AI proposes — you decide. Nothing gets generated until you approve.
+
 ### 1. Install (~5 seconds)
 
 ```bash
 npx @sandrinio/vdoc install claude
 ```
 
-Copies skill files to your AI platform's rules and commands locations. That's it.
+Copies skill files to your AI platform's config. No dependencies, no build step.
+
+### 2. Init — `/vdoc-init`
+
+This is the main workflow. Type `/vdoc-init` (or say "document this project") and the AI runs through four phases:
+
+**Phase 1: Explore** — The AI reads your project's config files and directory structure to identify the language, framework, and architecture. It uses archetype-based strategies (Web API, SPA, Full-Stack, CLI, Library, etc.) to know exactly which files to scan. The result is an exploration log documenting every file read and every feature signal detected.
+
+**Phase 2: Plan** — Based on what it found, the AI creates a documentation plan — a list of proposed docs, each covering one logical feature (not one file). The plan is saved as a file you can review.
+
+**Phase 3: You review** — The AI presents the plan and asks for your input:
+- *"Should I merge API routes and middleware into one doc?"*
+- *"I found a websocket system — want that documented separately?"*
+- *"Any legacy systems I should skip?"*
+
+You can add, remove, rename, or restructure docs before approving. **Nothing is generated until you say go.**
 
-### 2. Init
+**Phase 4: Generate** — For each approved doc, the AI reads all relevant source files, follows a consistent template, and writes feature-centric documentation with mermaid diagrams, real code references, and a semantic manifest for future AI queries.
 
-Type **`/vdoc-init`** in your AI tool (or say "document this project"). The skill tells the AI to:
+### 3. Update — `/vdoc-update`
 
-1. **Explore** — identify features, tech stack, architecture
-2. **Plan** — propose a documentation plan for your approval
-3. **Generate** — create feature-centric docs using a consistent template
-4. **Index** — build a semantic manifest for future queries
+Type `/vdoc-update` (or `/vdoc-audit`) when your code has changed. The AI:
 
-### 3. Update
+1. Checks git history to find which source files changed since docs were last updated
+2. Cross-references changes against each doc's "Key Files" to identify stale docs
+3. Scans for new features not covered by any doc
+4. Flags dead docs whose source files were deleted
+5. Verifies cross-references between docs
 
-Type **`/vdoc-update`** (or say "update docs"). The AI detects what changed via git, finds coverage gaps, flags dead docs, checks cross-references, reports everything, and patches only what you approve.
+It presents a report and waits for your direction before patching anything.
 
-### 4. Create
+### 4. Create — `/vdoc-create <feature>`
 
-Type **`/vdoc-create authentication system`** to document a single feature on demand. The AI locates the relevant source files, generates one doc, and updates the manifest.
+Type `/vdoc-create authentication system` to document a single feature on demand. The AI locates the relevant source files, generates one doc following the same template, and updates the manifest. Useful for adding docs incrementally without re-running the full init.
 
 ---
 
@@ -97,6 +115,38 @@ Docs are **feature-centric** — organized by what your system does, not by file
 
 ---
 
+## The Workflow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      /vdoc-init                         │
+│                                                         │
+│   Explore ──→ Plan ──→ You Review ──→ Generate          │
+│   (auto)      (auto)   (you decide)   (auto)            │
+│                             │                           │
+│                    add / remove / rename                 │
+│                    merge / split docs                    │
+│                    skip features                        │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│               /vdoc-update  or  /vdoc-audit             │
+│                                                         │
+│   Git Diff ──→ Detect Stale ──→ Report ──→ You Approve  │
+│                Detect Gaps       (auto)    ──→ Patch     │
+│                Detect Dead                              │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│              /vdoc-create <feature>                      │
+│                                                         │
+│   Locate Source ──→ Generate Doc ──→ Update Manifest    │
+│   (auto)            (auto)           (auto)             │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
 ## Documentation Template
 
 Every generated doc follows a consistent structure:
@@ -171,4 +221,4 @@ None. Your AI coding agent is the runtime.
 
 ---
 
-*vdoc v3.5.0 — Documentation skills for AI coding agents*
+*vdoc v3.5.2 — Documentation skills for AI coding agents*

package/bin/vdoc.mjs

@@ -232,6 +232,13 @@ function install(platform) {
 
   console.log(`\nvdoc → installing for ${platform}\n`);
 
+  // Create vdocs/ output directory
+  const vdocsDir = join(CWD, 'vdocs');
+  if (!existsSync(vdocsDir)) {
+    mkdirSync(vdocsDir, { recursive: true });
+    console.log(`  ✓ vdocs/`);
+  }
+
   for (const file of config.files) {
     if (file.inject) {
       injectFile(file.src, file.dest);
@@ -265,6 +272,7 @@ function uninstall() {
     join(CWD, '.claude', 'skills', 'vdoc-update'),
     join(CWD, '.claude', 'skills', 'vdoc-create'),
     join(CWD, '.claude', 'skills', 'vdoc-audit'),
+    join(CWD, '.claude', 'skills', 'vdoc'),
     join(CWD, '.cursor', 'rules', 'vdoc'),
     join(CWD, '.windsurf', 'skills', 'vdoc'),
     join(CWD, '.github', 'skills', 'vdoc'),

package/package.json

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

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `.agents/vdoc/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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 `.agents/vdoc/doc-template.md` exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

package/skills/claude/vdoc-init.md

@@ -58,7 +58,9 @@ This log is your working memory. It feeds directly into Step 2 (Plan).
 
 ## Step 2 — Plan
 
-Create `.claude/skills/vdoc-config/_DOCUMENTATION_PLAN.md` listing each proposed doc:
+Write `.claude/skills/vdoc-config/_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
@@ -75,7 +77,7 @@ Create `.claude/skills/vdoc-config/_DOCUMENTATION_PLAN.md` listing each proposed
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -84,11 +86,15 @@ Present the plan to the user. Actively suggest changes:
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `.claude/skills/vdoc-config/references/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-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`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 ### Writing Rules
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `references/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `references/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `references/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `.gemini/vdoc/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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 `.gemini/vdoc/doc-template.md` exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

package/skills/gemini/vdoc.toml

@@ -10,8 +10,8 @@ Run documentation workflows for this project. Full instructions are in GEMINI.md
 ## If "init" or no vdocs/ folder exists:
 
 1. **Explore** — Read the codebase: tech stack, features, architecture, integrations, entry points. 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 at @.gemini/vdoc/doc-template.md
+2. **Plan** — Write `vdocs/_DOCUMENTATION_PLAN.md` to disk listing proposed docs. Present to user. Wait for approval.
+3. **Generate** — Read template from @.gemini/vdoc/doc-template.md once. Then generate docs **one at a time**: read sources → write `vdocs/FEATURE_NAME_DOC.md` → confirm → next
 4. **Manifest** — Create `vdocs/_manifest.json` using schema at @.gemini/vdoc/manifest-schema.json
 5. **Verify** — Every doc has mermaid diagrams, real paths, 2+ constraints, cross-references.
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `.aiassistant/vdoc/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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 `.aiassistant/vdoc/doc-template.md` exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `.junie/vdoc/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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 `.junie/vdoc/doc-template.md` exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+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:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Follow the template in [doc-template.md](./doc-template.md) exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**
 

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

@@ -51,7 +51,9 @@ 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:
+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.
+
+Use this format:
 
 ```markdown
 # Documentation Plan
@@ -68,7 +70,7 @@ Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc:
 - Docs should be useful for onboarding AND as AI context for planning changes
 ```
 
-Present the plan to the user. Actively suggest changes:
+After writing the file, present the plan to the user. Actively suggest changes:
 - "Should I merge X and Y into one doc?"
 - "I found a websocket system — want that documented separately?"
 - "Any internal/legacy systems I should skip?"
@@ -77,11 +79,15 @@ Wait for user approval before proceeding.
 
 ## Step 3 — Generate
 
-For each approved doc:
+Read the template from `resources/doc-template.md` once before starting.
+
+Then generate docs **one at a time, sequentially**. 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 `resources/doc-template.md` exactly
-3. Write to `vdocs/FEATURE_NAME_DOC.md`
+2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+3. Confirm the file was written before moving to the next doc
+
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
 **Writing rules:**