@sandrinio/vdoc 3.6.0 → 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`**
 
 ---
 
@@ -165,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
 {

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

package/package.json

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

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,7 @@ This log is your working memory. It feeds directly into Step 2 (Plan).
 
 ## Step 2 — Plan
 
-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.
+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:
 
@@ -82,11 +75,11 @@ After writing the file, present the plan to the user. Actively suggest changes:
 - "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
 
-Read the template from `.claude/skills/vdoc-config/references/doc-template.md` once before starting.
+Read the template from [doc-template.md](./doc-template.md) once before starting.
 
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
@@ -96,20 +89,32 @@ Then generate docs **one at a time, sequentially**. For each approved doc:
 
 Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
 
-### 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.
 - **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.
 
-The `description` field is critical — write it rich enough that you can route any user question to the right doc by matching against descriptions.
+Example:
+
+```json
+{
+  "filepath": "AUTHENTICATION_DOC.md",
+  "title": "Authentication - OAuth2 & JWT",
+  "version": "1.0.0",
+  "description": "OAuth2 flow with Google/GitHub providers, JWT token lifecycle, session management via NextAuth.js, route protection middleware, and role-based access control.",
+  "tags": ["oauth2", "jwt", "session-management", "rbac"]
+}
+```
 
 ## Step 5 — Self-Review
 
@@ -122,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/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.