@sandrinio/vdoc 3.5.2 → 3.6.1

package/README.md

@@ -8,7 +8,7 @@ One install command. Your AI handles the rest.
 
 ## What is vdoc?
 
-vdoc teaches your AI coding agent how to create and maintain feature-centric documentation for your codebase. It's not a CLI you run — it's a skill file that gets installed into your AI platform. After install, you just talk to your AI.
+vdoc gives your AI coding agent the ability to create and maintain feature-centric documentation for your codebase. It's not a CLI you run — it's a skill file that gets installed into your AI platform. After install, you just talk to your AI.
 
 ```
 /vdoc-init              →  AI explores codebase → proposes plan → you approve → generates docs
@@ -21,10 +21,10 @@ vdoc teaches your AI coding agent how to create and maintain feature-centric doc
 ## Quick Start
 
 ```bash
-npx @sandrinio/vdoc install cursor
+npx @sandrinio/vdoc install claude
 ```
 
-Then open Cursor and type: **`/vdoc init`**
+Then type: **`/vdoc-init`**
 
 ---
 
@@ -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:
@@ -115,7 +165,9 @@ Every generated doc follows a consistent structure:
 
 ## Manifest
 
-The `_manifest.json` acts as a semantic index. Each entry has a rich `description` field that AI uses to route queries to the right doc:
+The `_manifest.json` is a map for your AI. Instead of reading every doc to find the right one, the AI reads the manifest first and picks the relevant doc based on rich descriptions and tags.
+
+When you ask "how does authentication work?", the AI matches your question against manifest descriptions and goes straight to `AUTHENTICATION_DOC.md` — no scanning, no guessing.
 
 ```json
 {
@@ -171,4 +223,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

@@ -13,13 +13,13 @@ const CWD = process.cwd();
 const PLATFORMS = {
   claude: {
     files: [
-      { src: 'claude/vdoc-init.md', dest: '.claude/skills/vdoc-init/SKILL.md' },
-      { src: 'claude/vdoc-update.md', dest: '.claude/skills/vdoc-update/SKILL.md' },
-      { src: 'claude/vdoc-audit.md', dest: '.claude/skills/vdoc-audit/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' },
+      { src: 'claude/SKILL.md', dest: '.claude/skills/vdoc/SKILL.md' },
+      { src: 'claude/references/init-workflow.md', dest: '.claude/skills/vdoc/references/init-workflow.md' },
+      { src: 'claude/references/create-workflow.md', dest: '.claude/skills/vdoc/references/create-workflow.md' },
+      { src: 'claude/references/audit-workflow.md', dest: '.claude/skills/vdoc/references/audit-workflow.md' },
+      { src: 'claude/references/exploration-strategies.md', dest: '.claude/skills/vdoc/references/exploration-strategies.md' },
+      { src: 'claude/references/doc-template.md', dest: '.claude/skills/vdoc/references/doc-template.md' },
+      { src: 'claude/references/manifest-schema.json', dest: '.claude/skills/vdoc/references/manifest-schema.json' },
     ],
   },
   cursor: {
@@ -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.1",
   "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/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: vdoc
+description: "Generate and maintain feature-centric documentation from source code. Use when user says 'document this project', 'generate docs', 'create a doc for [feature]', 'update docs', 'audit docs', 'sync docs', or asks about documentation coverage and freshness."
+---
+
+# vdoc — Documentation Generator
+
+Four modes: **init**, **create**, **update**, **audit**, plus **query** for any documentation question. All docs live in `vdocs/`. Manifest at `vdocs/_manifest.json` is the semantic index.
+
+Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep) for everything.
+
+## Init
+
+Read the detailed workflow at [init-workflow.md](./references/init-workflow.md).
+
+Summary: Explore codebase → Write exploration log → Plan docs → User approves → Generate one-at-a-time using [doc template](./references/doc-template.md) → Build manifest per [schema](./references/manifest-schema.json) → Self-review.
+
+## Create
+
+Read the detailed workflow at [create-workflow.md](./references/create-workflow.md).
+
+Summary: Locate feature in codebase → Generate one doc using [doc template](./references/doc-template.md) → Update manifest per [schema](./references/manifest-schema.json) → Self-review.
+
+## Update / Audit
+
+Read the detailed workflow at [audit-workflow.md](./references/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.
+7. **No scripts.** Do NOT create shell scripts, scanners, or build tools.

package/skills/claude/{vdoc-update.md → references/audit-workflow.md}

@@ -1,14 +1,7 @@
----
-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
+# Audit Workflow
 
 Detect stale, missing, and dead documentation. Report and patch. Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep, Bash for git commands) for everything.
 
----
-
 ## Step 1 — Read Current State
 
 Read `vdocs/_manifest.json`. Load the list of documented features and their metadata.
@@ -44,7 +37,7 @@ Read each doc's "Related Features" section. Verify that:
 Present a clear report:
 
 ```
-Update Report:
+Audit Results:
 
 STALE (source files changed):
   - AUTHENTICATION_DOC.md — src/lib/auth.ts changed (added GitHub provider)
@@ -66,15 +59,9 @@ CURRENT (no changes needed):
 Proceed with fixes?
 ```
 
-**Wait for user direction**, then:
+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)
+- Generate new docs for coverage gaps (follow create workflow for each)
 - Flag dead docs for user to confirm deletion
 - Fix cross-reference issues
 - Update manifest: bump versions, update `last_updated`, `last_commit`
-
-## 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/claude/{vdoc-create.md → references/create-workflow.md}

@@ -1,20 +1,12 @@
----
-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 Workflow
 
 Create one feature doc based on the user's description. Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep) for everything.
 
----
-
 ## Step 1 — Locate
 
 Use the user's description to find the relevant source files:
 
-1. If `.claude/skills/vdoc-config/_exploration_log.md` exists, read it first — it maps the codebase and may already have the feature signal you need
+1. If `vdocs/_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
 
@@ -22,10 +14,10 @@ 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
+1. Read the template from [doc-template.md](./doc-template.md) and follow it exactly
 2. Write to `vdocs/FEATURE_NAME_DOC.md`
 
-### Writing Rules
+**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.
@@ -36,7 +28,7 @@ Do not skim. Understand how the feature actually works before writing.
 
 ## 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`.
+Read `vdocs/_manifest.json` and add the new doc entry using the schema in [manifest-schema.json](./manifest-schema.json).
 
 If `vdocs/_manifest.json` doesn't exist, create it with the project name, version, and this doc as the first entry.
 
@@ -51,9 +43,3 @@ Before finishing, verify:
 - [ ] "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 → references/init-workflow.md}

@@ -1,13 +1,4 @@
----
-name: vdoc-init
-description: "Generate feature-centric documentation from source code. Use when user says 'document this project', 'generate docs', or wants to create vdocs from scratch."
----
-
-# vdoc init — Generate Documentation
-
-Generate feature-centric documentation from source code. All docs go in `vdocs/`. Do NOT create scripts, shell files, scanners, or any tooling — use your built-in tools (Read, Glob, Grep) for everything.
-
----
+# Init Workflow
 
 ## Step 1 — Explore
 
@@ -23,8 +14,10 @@ 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 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 `.claude/skills/vdoc-config/_exploration_log.md` documenting what you found:
+After exploring, write `vdocs/_exploration_log.md` documenting what you found:
 
 ```markdown
 # Exploration Log
@@ -58,7 +51,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 `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
@@ -75,35 +70,51 @@ 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?"
 
-**Wait for user approval before proceeding.**
+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. 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
 
-### Writing Rules
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+
+**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: "Uses polling instead of websockets because...", "Auth tokens expire in 15min because...". If you can't find the reason, state the constraint and mark it: `Reason: unknown — verify with team`.
-- **Related Features** must reference other docs by filename and explain the coupling.
+- **Related Features** must reference other docs by filename and explain the coupling: "Changes to the JWT schema will require updates to API_REFERENCE_DOC.md (auth middleware affects all endpoints)."
 - **Configuration** must list actual env vars/secrets from the code, not hypothetical ones.
 - **Error Handling** — trace what happens when things fail. What does the user see? What gets logged? Is there retry logic?
 
 ## Step 4 — Manifest
 
-Create `vdocs/_manifest.json` using the schema in `.claude/skills/vdoc-config/references/manifest-schema.json`.
+Create `vdocs/_manifest.json` using the schema in [manifest-schema.json](./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.
+
+Example:
 
-The `description` field is critical — write it rich enough that you can route any user question to the right doc by matching against descriptions.
+```json
+{
+  "filepath": "AUTHENTICATION_DOC.md",
+  "title": "Authentication - OAuth2 & JWT",
+  "version": "1.0.0",
+  "description": "OAuth2 flow with Google/GitHub providers, JWT token lifecycle, session management via NextAuth.js, route protection middleware, and role-based access control.",
+  "tags": ["oauth2", "jwt", "session-management", "rbac"]
+}
+```
 
 ## Step 5 — Self-Review
 
@@ -116,10 +127,3 @@ Before finishing, verify:
 - [ ] Every doc's "Related Features" references other doc filenames
 - [ ] Manifest `description` is detailed enough for semantic routing
 - [ ] No doc is just a shallow restatement of file names — each explains WHY and HOW
-
-## Rules
-
-1. **Feature-centric, not file-centric.** One doc per logical feature, not per 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.
-4. **Plan first.** Never generate without user-approved plan.

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:**
 

package/skills/claude/vdoc-audit.md

@@ -1,80 +0,0 @@
----
-name: vdoc-audit
-description: "Audit existing vdocs for stale, missing, or dead documentation. Use when user says 'audit docs', 'check docs', or documentation may be out of sync with code."
----
-
-# vdoc audit — Documentation Audit
-
-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:
-
-```
-Audit 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.