@sandrinio/vdoc 3.5.0 → 3.5.2

package/README.md

@@ -11,9 +11,9 @@ One install command. Your AI handles the rest.
 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 init     →  AI explores codebase → proposes plan → you approve → generates docs
-/vdoc audit    →  AI detects stale, missing, dead docs → reports → patches
-"how does auth work?"  →  AI reads manifest → routes to right doc → answers
+/vdoc-init              →  AI explores codebase → proposes plan → you approve → generates docs
+/vdoc-update            →  AI detects stale, missing, dead docs → reports → patches
+/vdoc-create <feature>  →  AI documents one specific feature on demand
 ```
 
 ---
@@ -32,9 +32,9 @@ Then open Cursor and type: **`/vdoc init`**
 
 | Platform | Install Command | `/vdoc` Command | Invocation |
 |----------|----------------|----------------|------------|
-| **Claude Code** | `npx @sandrinio/vdoc install claude` | `/vdoc init` `/vdoc audit` | Skill (SKILL.md) |
+| **Claude Code** | `npx @sandrinio/vdoc install claude` | `/vdoc-init` `/vdoc-update` `/vdoc-create` | Skills |
 | **Cursor** | `npx @sandrinio/vdoc install cursor` | `/vdoc init` `/vdoc audit` | Command + Rule |
-| **Windsurf** | `npx @sandrinio/vdoc install windsurf` | `/vdoc` | Workflow + Rule |
+| **Windsurf** | `npx @sandrinio/vdoc install windsurf` | `/vdoc` | Workflow + Skill |
 | **VS Code (Copilot)** | `npx @sandrinio/vdoc install vscode` | `/vdoc` | Prompt + Instructions |
 | **Continue** | `npx @sandrinio/vdoc install continue` | `/vdoc init` `/vdoc audit` | Invokable Prompt + Rule |
 | **Cline** | `npx @sandrinio/vdoc install cline` | `/vdoc` | Workflow + Rule |
@@ -57,20 +57,20 @@ Copies skill files to your AI platform's rules and commands locations. That's it
 
 ### 2. Init
 
-Type **`/vdoc init`** in your AI tool (or say "document this project"). The skill tells the AI to:
+Type **`/vdoc-init`** in your AI tool (or say "document this project"). The skill tells the AI to:
 
 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
 
-### 3. Audit
+### 3. Update
 
-Type **`/vdoc audit`** (or say "audit 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.
+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.
 
-### 4. Query
+### 4. Create
 
-Ask any question. The AI reads the manifest, routes to the right doc, and answers from documented knowledge.
+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.
 
 ---
 
@@ -78,14 +78,19 @@ Ask any question. The AI reads the manifest, routes to the right doc, and answer
 
 ```
 your-project/
-└── vdocs/
-    ├── _manifest.json                ← Semantic index (AI reads first)
-    ├── _DOCUMENTATION_PLAN.md        ← Approved plan (kept for reference)
-    ├── PROJECT_OVERVIEW_DOC.md
-    ├── AUTHENTICATION_DOC.md
-    ├── API_REFERENCE_DOC.md
-    ├── DATABASE_SCHEMA_DOC.md
-    └── ...
+├── vdocs/
+│   ├── _manifest.json                ← Semantic index (AI reads first)
+│   ├── PROJECT_OVERVIEW_DOC.md
+│   ├── AUTHENTICATION_DOC.md
+│   ├── API_REFERENCE_DOC.md
+│   ├── DATABASE_SCHEMA_DOC.md
+│   └── ...
+└── .claude/skills/vdoc-config/       ← Planning artifacts (Claude example)
+    ├── _exploration_log.md           ← What was scanned and why
+    ├── _DOCUMENTATION_PLAN.md        ← Approved plan
+    └── references/
+        ├── doc-template.md           ← Shared doc template
+        └── manifest-schema.json      ← Shared manifest schema
 ```
 
 Docs are **feature-centric** — organized by what your system does, not by file paths.
@@ -138,7 +143,7 @@ Removes all vdoc skill and rule files from **every** supported platform in one c
 
 | Platform | Files Removed |
 |----------|--------------|
-| Claude Code | `.claude/skills/vdoc/` |
+| Claude Code | `.claude/skills/vdoc-init/`, `vdoc-update/`, `vdoc-create/`, `vdoc-config/` |
 | Cursor | `.cursor/rules/vdoc.mdc`, `.cursor/commands/vdoc.md` |
 | Windsurf | `.windsurf/rules/vdoc.md`, `.windsurf/workflows/vdoc.md` |
 | VS Code (Copilot) | `.github/instructions/vdoc.instructions.md`, `.github/prompts/vdoc.prompt.md` |
@@ -166,4 +171,4 @@ None. Your AI coding agent is the runtime.
 
 ---
 
-*vdoc v3.0.0 — Documentation skills for AI coding agents*
+*vdoc v3.5.0 — Documentation skills for AI coding agents*

package/bin/vdoc.mjs

@@ -15,6 +15,7 @@ const PLATFORMS = {
     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' },

package/package.json

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

package/skills/claude/vdoc-audit.md

@@ -44,7 +44,7 @@ Read each doc's "Related Features" section. Verify that:
 Present a clear report:
 
 ```
-Audit Results:
+Audit Report:
 
 STALE (source files changed):
   - AUTHENTICATION_DOC.md — src/lib/auth.ts changed (added GitHub provider)
@@ -68,7 +68,7 @@ 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-init` workflow for each)
+- 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`

package/skills/claude/SKILL.md

@@ -1,28 +0,0 @@
----
-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."
----
-
-# vdoc — Documentation Query
-
-Answer questions about the codebase using existing documentation in `vdocs/`.
-
-## Other Commands
-
-- **`/vdoc-init`** — Generate documentation from source code (explore → plan → generate)
-- **`/vdoc-audit`** — Audit docs for stale, missing, or dead entries
-
-## How to Answer Questions
-
-1. Read `vdocs/_manifest.json`
-2. Match the question against `description` and `tags` fields
-3. Read matching doc(s) from `vdocs/`
-4. Answer from documented knowledge
-5. If no match or no `vdocs/` folder, suggest running `/vdoc-init`
-6. If docs seem outdated, suggest running `/vdoc-audit`
-
-## Rules
-
-- Only answer from what's documented — do not hallucinate
-- Reference specific doc filenames in your answers
-- If the question spans multiple docs, read all relevant ones

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

@@ -1,65 +0,0 @@
-# Audit Workflow
-
-## Step 1 — Read Current State
-
-Read `vdocs/_manifest.json`. Load the list of documented features and their metadata.
-
-## Step 2 — Detect Stale Docs
-
-Run `git log --name-only --since="<last_updated>" --pretty=format:""` or use `git diff` to find all source files that changed since the last audit.
-
-Cross-reference changed files against each doc's "Key Files" section to identify which docs are stale.
-
-## Step 3 — Detect Coverage Gaps
-
-Scan the codebase for significant features not covered by any doc. Look for:
-- New route files / API endpoints
-- New service classes or modules
-- New database models / schema changes
-- New configuration or infrastructure files
-
-If you find undocumented features, propose new docs.
-
-## Step 4 — Detect Dead Docs
-
-Check each doc's "Key Files" section against the actual filesystem. If key files no longer exist, the doc may be dead. Flag it: "PAYMENT_PROCESSING_DOC.md references 3 files that no longer exist — remove or archive?"
-
-## Step 5 — Check Cross-References
-
-Read each doc's "Related Features" section. Verify that:
-- Referenced doc filenames still exist
-- The described coupling is still accurate (skim the relevant code)
-
-## Step 6 — Report
-
-Present a clear report:
-
-```
-Audit Results:
-
-STALE (source files changed):
-  - AUTHENTICATION_DOC.md — src/lib/auth.ts changed (added GitHub provider)
-  - API_REFERENCE_DOC.md — 2 new endpoints added
-
-COVERAGE GAPS (undocumented features):
-  - src/services/notification.ts — no doc covers notifications
-
-DEAD DOCS (source files removed):
-  - LEGACY_ADMIN_DOC.md — all 4 source files deleted
-
-CROSS-REF ISSUES:
-  - AUTHENTICATION_DOC.md references BILLING_DOC.md which no longer exists
-
-CURRENT (no changes needed):
-  - DATABASE_SCHEMA_DOC.md
-  - PROJECT_OVERVIEW_DOC.md
-
-Proceed with fixes?
-```
-
-Wait for user direction, then:
-- Patch stale docs (re-read source files, update affected sections only)
-- Generate new docs for coverage gaps (follow init workflow for each)
-- Flag dead docs for user to confirm deletion
-- Fix cross-reference issues
-- Update manifest: bump versions, update `last_updated`, `last_commit`

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

@@ -1,123 +0,0 @@
-# Init Workflow
-
-## Step 1 — Explore
-
-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. 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. Combine multiple playbooks when the project doesn't fit a single archetype (see "Composing Archetypes" in the strategies file).
-
-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 `.claude/skills/vdoc-config/_exploration_log.md` documenting what you found:
-
-```markdown
-# Exploration Log
-
-## Fingerprint
-- **Language(s):** e.g., TypeScript, Python
-- **Framework(s):** e.g., Next.js 14, FastAPI
-- **Archetype(s):** e.g., Full-stack Framework
-- **Scope:** e.g., ~85 files, medium
-
-## Files Read
-| # | File | Why | What I Found |
-|---|------|-----|--------------|
-| 1 | package.json | Fingerprint | Next.js 14, Prisma, NextAuth |
-| 2 | src/app/ (listing) | Page tree | 12 routes, 3 API routes |
-| ... | ... | ... | ... |
-
-## Feature Signals Detected
-| Signal | Source File(s) | Proposed Doc |
-|--------|---------------|--------------|
-| Auth middleware + login page | middleware.ts, app/login/page.tsx | AUTHENTICATION_DOC.md |
-| Prisma schema with 8 models | prisma/schema.prisma | DATA_MODEL_DOC.md |
-| ... | ... | ... |
-
-## Ambiguities / Open Questions
-- Could not determine why Redis is in dependencies — no usage found. Ask user.
-- Payments folder exists but appears incomplete / WIP.
-```
-
-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:
-
-```markdown
-# Documentation Plan
-
-## Proposed Documents
-
-1. **PROJECT_OVERVIEW_DOC.md** — Tech stack, architecture, project structure, dev setup
-2. **AUTHENTICATION_DOC.md** — OAuth2 flow, JWT lifecycle, session management, RBAC
-3. **API_REFERENCE_DOC.md** — All endpoints, request/response shapes, error codes
-...
-
-## Notes
-- Each doc covers one logical feature, not one file
-- Docs should be useful for onboarding AND as AI context for planning changes
-```
-
-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.
-
-## Step 3 — Generate
-
-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`
-
-**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: "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`.
-
-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:
-
-```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
-
-Before finishing, verify:
-
-- [ ] Every doc has at least one mermaid diagram in "How It Works"
-- [ ] Every doc has at least 2 entries in "Constraints & Decisions"
-- [ ] Every doc's "Key Files" lists real paths that exist in the codebase
-- [ ] Every doc's "Configuration" lists actual env vars from the code
-- [ ] 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