@sandrinio/vdoc 3.0.0 → 3.3.1

package/README.md

@@ -21,7 +21,7 @@ vdoc teaches your AI coding agent how to create and maintain feature-centric doc
 ## Quick Start
 
 ```bash
-npx vdoc install cursor
+npx @sandrinio/vdoc install cursor
 ```
 
 Then open Cursor and type: **`/vdoc init`**
@@ -32,16 +32,16 @@ Then open Cursor and type: **`/vdoc init`**
 
 | Platform | Install Command | `/vdoc` Command | Invocation |
 |----------|----------------|----------------|------------|
-| **Claude Code** | `npx vdoc install claude` | `/vdoc init` `/vdoc audit` | Skill (SKILL.md) |
-| **Cursor** | `npx vdoc install cursor` | `/vdoc init` `/vdoc audit` | Command + Rule |
-| **Windsurf** | `npx vdoc install windsurf` | `/vdoc` | Workflow + Rule |
-| **VS Code (Copilot)** | `npx vdoc install vscode` | `/vdoc` | Prompt + Instructions |
-| **Continue** | `npx vdoc install continue` | `/vdoc init` `/vdoc audit` | Invokable Prompt + Rule |
-| **Cline** | `npx vdoc install cline` | `/vdoc` | Workflow + Rule |
-| **Gemini CLI** | `npx vdoc install gemini` | `/vdoc init` `/vdoc audit` | TOML Command + GEMINI.md |
-| **JetBrains AI** | `npx vdoc install jetbrains` | Natural language | Rule only |
-| **JetBrains Junie** | `npx vdoc install junie` | Natural language | Guidelines only |
-| **Universal** | `npx vdoc install agents` | Natural language | AGENTS.md |
+| **Claude Code** | `npx @sandrinio/vdoc install claude` | `/vdoc init` `/vdoc audit` | Skill (SKILL.md) |
+| **Cursor** | `npx @sandrinio/vdoc install cursor` | `/vdoc init` `/vdoc audit` | Command + Rule |
+| **Windsurf** | `npx @sandrinio/vdoc install windsurf` | `/vdoc` | Workflow + Rule |
+| **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 |
+| **Gemini CLI** | `npx @sandrinio/vdoc install gemini` | `/vdoc init` `/vdoc audit` | TOML Command + GEMINI.md |
+| **JetBrains AI** | `npx @sandrinio/vdoc install jetbrains` | Natural language | Rule only |
+| **JetBrains Junie** | `npx @sandrinio/vdoc install junie` | Natural language | Guidelines only |
+| **Universal** | `npx @sandrinio/vdoc install agents` | Natural language | AGENTS.md |
 
 ---
 
@@ -50,7 +50,7 @@ Then open Cursor and type: **`/vdoc init`**
 ### 1. Install (~5 seconds)
 
 ```bash
-npx vdoc install claude
+npx @sandrinio/vdoc install claude
 ```
 
 Copies skill files to your AI platform's rules and commands locations. That's it.
@@ -131,7 +131,7 @@ The `_manifest.json` acts as a semantic index. Each entry has a rich `descriptio
 ## Uninstall
 
 ```bash
-npx vdoc uninstall
+npx @sandrinio/vdoc uninstall
 ```
 
 Removes all vdoc skill and rule files from **every** supported platform in one command. No platform argument needed — it scans for and deletes everything vdoc may have created:

package/bin/vdoc.mjs

@@ -14,24 +14,41 @@ const PLATFORMS = {
   claude: {
     files: [
       { src: 'claude/SKILL.md', dest: '.claude/skills/vdoc/SKILL.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' },
+      { src: 'claude/vdoc-init.md', dest: '.claude/skills/vdoc-init/SKILL.md' },
+      { src: 'claude/vdoc-audit.md', dest: '.claude/skills/vdoc-audit/SKILL.md' },
+      { src: 'claude/references/exploration-strategies.md', dest: '.claude/skills/vdoc-init/references/exploration-strategies.md' },
     ],
   },
   cursor: {
     files: [
-      { src: 'cursor/vdoc.mdc', dest: '.cursor/rules/vdoc.mdc' },
+      { src: 'cursor/RULE.md', dest: '.cursor/rules/vdoc/RULE.md' },
+      { src: 'cursor/references/init-workflow.md', dest: '.cursor/rules/vdoc/references/init-workflow.md' },
+      { src: 'cursor/references/audit-workflow.md', dest: '.cursor/rules/vdoc/references/audit-workflow.md' },
+      { src: 'cursor/references/doc-template.md', dest: '.cursor/rules/vdoc/references/doc-template.md' },
+      { src: 'cursor/references/manifest-schema.json', dest: '.cursor/rules/vdoc/references/manifest-schema.json' },
+      { src: 'cursor/references/exploration-strategies.md', dest: '.cursor/rules/vdoc/references/exploration-strategies.md' },
       { src: 'cursor/vdoc-command.md', dest: '.cursor/commands/vdoc.md' },
     ],
   },
   windsurf: {
     files: [
-      { src: 'windsurf/vdoc.md', dest: '.windsurf/rules/vdoc.md' },
+      { src: 'windsurf/SKILL.md', dest: '.windsurf/skills/vdoc/SKILL.md' },
+      { src: 'windsurf/resources/init-workflow.md', dest: '.windsurf/skills/vdoc/resources/init-workflow.md' },
+      { src: 'windsurf/resources/audit-workflow.md', dest: '.windsurf/skills/vdoc/resources/audit-workflow.md' },
+      { src: 'windsurf/resources/doc-template.md', dest: '.windsurf/skills/vdoc/resources/doc-template.md' },
+      { src: 'windsurf/resources/manifest-schema.json', dest: '.windsurf/skills/vdoc/resources/manifest-schema.json' },
+      { src: 'windsurf/resources/exploration-strategies.md', dest: '.windsurf/skills/vdoc/resources/exploration-strategies.md' },
       { src: 'windsurf/vdoc-workflow.md', dest: '.windsurf/workflows/vdoc.md' },
     ],
   },
   vscode: {
     files: [
+      { src: 'vscode/SKILL.md', dest: '.github/skills/vdoc/SKILL.md' },
+      { src: 'vscode/references/init-workflow.md', dest: '.github/skills/vdoc/references/init-workflow.md' },
+      { src: 'vscode/references/audit-workflow.md', dest: '.github/skills/vdoc/references/audit-workflow.md' },
+      { src: 'vscode/references/doc-template.md', dest: '.github/skills/vdoc/references/doc-template.md' },
+      { src: 'vscode/references/manifest-schema.json', dest: '.github/skills/vdoc/references/manifest-schema.json' },
+      { src: 'vscode/references/exploration-strategies.md', dest: '.github/skills/vdoc/references/exploration-strategies.md' },
       { src: 'vscode/vdoc.instructions.md', dest: '.github/instructions/vdoc.instructions.md' },
       { src: 'vscode/vdoc.prompt.md', dest: '.github/prompts/vdoc.prompt.md' },
       { src: 'vscode/copilot-instructions.md', dest: '.github/copilot-instructions.md', inject: true },
@@ -41,33 +58,63 @@ const PLATFORMS = {
     files: [
       { src: 'continue/vdoc.md', dest: '.continue/rules/vdoc.md' },
       { src: 'continue/vdoc-command.md', dest: '.continue/prompts/vdoc-command.md' },
+      { src: 'continue/references/init-workflow.md', dest: '.continue/references/vdoc/init-workflow.md' },
+      { src: 'continue/references/audit-workflow.md', dest: '.continue/references/vdoc/audit-workflow.md' },
+      { src: 'continue/references/doc-template.md', dest: '.continue/references/vdoc/doc-template.md' },
+      { src: 'continue/references/manifest-schema.json', dest: '.continue/references/vdoc/manifest-schema.json' },
+      { src: 'continue/references/exploration-strategies.md', dest: '.continue/references/vdoc/exploration-strategies.md' },
     ],
   },
   cline: {
     files: [
       { src: 'cline/vdoc.md', dest: '.clinerules/vdoc.md' },
       { src: 'cline/vdoc-workflow.md', dest: '.clinerules/workflows/vdoc.md' },
+      { src: 'cline/references/init-workflow.md', dest: '.clinerules/vdoc/init-workflow.md' },
+      { src: 'cline/references/audit-workflow.md', dest: '.clinerules/vdoc/audit-workflow.md' },
+      { src: 'cline/references/doc-template.md', dest: '.clinerules/vdoc/doc-template.md' },
+      { src: 'cline/references/manifest-schema.json', dest: '.clinerules/vdoc/manifest-schema.json' },
+      { src: 'cline/references/exploration-strategies.md', dest: '.clinerules/vdoc/exploration-strategies.md' },
     ],
   },
   gemini: {
     files: [
       { src: 'gemini/vdoc.toml', dest: '.gemini/commands/vdoc.toml' },
       { src: 'gemini/GEMINI.md', dest: 'GEMINI.md', inject: true },
+      { src: 'gemini/references/init-workflow.md', dest: '.gemini/vdoc/init-workflow.md' },
+      { src: 'gemini/references/audit-workflow.md', dest: '.gemini/vdoc/audit-workflow.md' },
+      { src: 'gemini/references/doc-template.md', dest: '.gemini/vdoc/doc-template.md' },
+      { src: 'gemini/references/manifest-schema.json', dest: '.gemini/vdoc/manifest-schema.json' },
+      { src: 'gemini/references/exploration-strategies.md', dest: '.gemini/vdoc/exploration-strategies.md' },
     ],
   },
   jetbrains: {
     files: [
       { src: 'jetbrains-ai/vdoc.md', dest: '.aiassistant/rules/vdoc.md' },
+      { src: 'jetbrains-ai/references/init-workflow.md', dest: '.aiassistant/vdoc/init-workflow.md' },
+      { src: 'jetbrains-ai/references/audit-workflow.md', dest: '.aiassistant/vdoc/audit-workflow.md' },
+      { src: 'jetbrains-ai/references/doc-template.md', dest: '.aiassistant/vdoc/doc-template.md' },
+      { src: 'jetbrains-ai/references/manifest-schema.json', dest: '.aiassistant/vdoc/manifest-schema.json' },
+      { src: 'jetbrains-ai/references/exploration-strategies.md', dest: '.aiassistant/vdoc/exploration-strategies.md' },
     ],
   },
   junie: {
     files: [
       { src: 'junie/guidelines.md', dest: '.junie/guidelines.md', inject: true },
+      { src: 'junie/references/init-workflow.md', dest: '.junie/vdoc/init-workflow.md' },
+      { src: 'junie/references/audit-workflow.md', dest: '.junie/vdoc/audit-workflow.md' },
+      { src: 'junie/references/doc-template.md', dest: '.junie/vdoc/doc-template.md' },
+      { src: 'junie/references/manifest-schema.json', dest: '.junie/vdoc/manifest-schema.json' },
+      { src: 'junie/references/exploration-strategies.md', dest: '.junie/vdoc/exploration-strategies.md' },
     ],
   },
   agents: {
     files: [
       { src: 'agents/AGENTS.md', dest: 'AGENTS.md', inject: true },
+      { src: 'agents/references/init-workflow.md', dest: '.agents/vdoc/init-workflow.md' },
+      { src: 'agents/references/audit-workflow.md', dest: '.agents/vdoc/audit-workflow.md' },
+      { src: 'agents/references/doc-template.md', dest: '.agents/vdoc/doc-template.md' },
+      { src: 'agents/references/manifest-schema.json', dest: '.agents/vdoc/manifest-schema.json' },
+      { src: 'agents/references/exploration-strategies.md', dest: '.agents/vdoc/exploration-strategies.md' },
     ],
   },
 };
@@ -208,11 +255,33 @@ function uninstall() {
     }
   }
 
-  // Also clean .claude/skills/vdoc/ directory if it exists
-  const claudeSkillDir = join(CWD, '.claude', 'skills', 'vdoc');
-  if (existsSync(claudeSkillDir)) {
-    rmSync(claudeSkillDir, { recursive: true });
-    cleanEmptyDirs(dirname(claudeSkillDir));
+  // Clean skill directories that may have nested files
+  const skillDirs = [
+    join(CWD, '.claude', 'skills', 'vdoc'),
+    join(CWD, '.claude', 'skills', 'vdoc-init'),
+    join(CWD, '.claude', 'skills', 'vdoc-audit'),
+    join(CWD, '.cursor', 'rules', 'vdoc'),
+    join(CWD, '.windsurf', 'skills', 'vdoc'),
+    join(CWD, '.github', 'skills', 'vdoc'),
+    join(CWD, '.continue', 'references', 'vdoc'),
+    join(CWD, '.clinerules', 'vdoc'),
+    join(CWD, '.gemini', 'vdoc'),
+    join(CWD, '.aiassistant', 'vdoc'),
+    join(CWD, '.junie', 'vdoc'),
+    join(CWD, '.agents', 'vdoc'),
+  ];
+  for (const dir of skillDirs) {
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true });
+      console.log(`  ✓ removed ${dir.slice(CWD.length + 1)}/`);
+      cleanEmptyDirs(dirname(dir));
+    }
+  }
+
+  // Clean legacy files from previous versions
+  const legacyFiles = ['.cursor/rules/vdoc.mdc', '.windsurf/rules/vdoc.md'];
+  for (const f of legacyFiles) {
+    if (removeFile(f)) removed++;
   }
 
   if (removed === 0) {

package/package.json

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

package/skills/agents/AGENTS.md

@@ -1,164 +1,38 @@
 # vdoc — Documentation Generator
 
-You generate and maintain feature-centric documentation for codebases. You have three modes: **init**, **audit**, and **query**.
+Documentation must be feature-centric, plan-approved, and grounded in source code. Never generate docs from assumptions.
 
-All documentation lives in `vdocs/` at the project root. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
+## When to Use
+- User says `/vdoc`, "document this project", "audit docs", or asks about documentation
+- Docs are stale, missing, or out of sync with code
 
----
-
-## Mode 1: Init
-
-**Trigger:** User says "document this project" or similar.
-
-### Step 1 — Explore
-
-Read the codebase thoroughly. Identify:
-
-- **Tech stack**: languages, frameworks, databases, ORMs
-- **Features**: authentication, API, payments, notifications, search, etc.
-- **Architecture**: monolith vs microservices, frontend/backend split, key patterns
-- **Integrations**: third-party services (Stripe, AWS, Redis, etc.)
-- **Entry points**: where requests come in, how they flow through the system
-
-Do not skim. Read key files — entry points, config, routes, schemas, middleware.
-
-### Step 2 — Plan
-
-Create `vdocs/_DOCUMENTATION_PLAN.md` listing each proposed doc with a one-line description. Present to user. Suggest merges, additions, or removals. Wait for approval.
-
-### Step 3 — Generate
-
-For each approved doc, read ALL relevant source files and generate using this template:
-
-```markdown
-# {Feature Title}
-
-> {One-line description}
-
----
-
-## Overview
-{What it does, why it exists, how it fits in the system.}
-
----
-
-## How It Works
-{Core logic and flow.}
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split if larger.}
+## When NOT to Use
+- API reference docs (use JSDoc/TSDoc), README files, inline code comments
 
 ---
 
-## Data Model
-{Entities this feature owns. Mermaid ER diagram or table.}
+You generate and maintain feature-centric documentation. Three modes: **init**, **audit**, **query**.
 
----
+All docs live in `vdocs/`. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
 
-## Key Files
-| File | Purpose |
-|------|---------|
-| `src/path/file.ts` | What this file does |
+## Init (`/vdoc init`)
 
----
+Read the detailed workflow at `.agents/vdoc/init-workflow.md`.
 
-## Dependencies & Integrations
-{External services, internal features, packages this relies on.}
+Use the doc template at `.agents/vdoc/doc-template.md`.
 
----
+Use the manifest schema at `.agents/vdoc/manifest-schema.json`.
 
-## Configuration
-| Variable | Purpose | Required |
-|----------|---------|----------|
-| `ENV_VAR` | What it controls | Yes/No |
+## Audit (`/vdoc audit`)
 
----
+Read the detailed workflow at `.agents/vdoc/audit-workflow.md`.
 
-## Error Handling
-{Failure modes, what the user sees, retry logic. Mermaid diagram if non-trivial.}
-
----
-
-## Constraints & Decisions
-{Why it's built this way. What you CANNOT change without breaking things.}
-
----
-
-## Related Features
-{Cross-references to other docs by filename. Blast radius notes.}
-
----
-
-*Generated by vdoc v3.0.0 • Last updated: {timestamp}*
-```
-
-**Writing rules:**
-
-- **Mermaid diagrams are mandatory** in "How It Works". Max 7-9 nodes — split larger flows.
-- **Data Model** must show real entities from the code, not placeholders.
-- **Constraints & Decisions** is the most valuable section. Dig for non-obvious choices. If unclear, write: `Reason: unknown — verify with team`.
-- **Related Features** must reference other doc filenames and explain coupling.
-- **Configuration** must list actual env vars from the code.
-- **Error Handling** — trace what happens when things fail.
-
-### Step 4 — Manifest
-
-Create `vdocs/_manifest.json`:
-
-```json
-{
-  "project": "<project-name>",
-  "vdoc_version": "3.0.0",
-  "created_at": "<ISO-8601>",
-  "last_updated": "<ISO-8601>",
-  "last_commit": "<short-sha>",
-  "documentation": [
-    {
-      "filepath": "FEATURE_NAME_DOC.md",
-      "title": "Human-Readable Title",
-      "version": "1.0.0",
-      "description": "Rich semantic description with technology names, patterns, concepts. Detailed enough for AI to route questions to this doc.",
-      "tags": ["keyword-tag"]
-    }
-  ]
-}
-```
-
-### Step 5 — Self-Review
-
-Verify: every doc has mermaid diagrams, at least 2 constraints, real file paths, actual env vars, cross-references. Manifest descriptions are detailed for semantic routing. No hallucinated content.
-
----
-
-## Mode 2: Audit
-
-**Trigger:** User says "audit docs" or similar.
-
-1. **Read manifest** — load `vdocs/_manifest.json`
-2. **Detect stale** — `git diff` or `git log --name-only --since="<last_updated>"` to find changed source files. Cross-reference with each doc's "Key Files" section.
-3. **Detect gaps** — scan codebase for significant source files not covered by any doc (new routes, services, models, config).
-4. **Detect dead docs** — check each doc's "Key Files" against filesystem. Flag docs referencing deleted files.
-5. **Check cross-refs** — verify "Related Features" links still exist and coupling is accurate.
-6. **Report** — present stale, gaps, dead, cross-ref issues, and current docs. Wait for user direction.
-7. **Patch** — update stale docs, generate new docs for gaps, flag dead docs, fix cross-refs. Update manifest.
-
----
-
-## Mode 3: Query
-
-**Trigger:** User asks any question about the codebase or documentation.
+## 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
-
----
-
-## Naming Convention
-
-Files: `FEATURE_NAME_DOC.md` — uppercase, feature-named, `_DOC` suffix.
-
----
+3. Read matching doc(s) and answer from documented knowledge
+4. If no match, suggest running an audit
 
 ## Rules
 

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

@@ -0,0 +1,65 @@
+# 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/agents/references/doc-template.md

@@ -0,0 +1,67 @@
+# {Feature Title}
+
+> {One-line description of what this covers}
+
+---
+
+## Overview
+
+{What it does, why it exists, how it fits in the system.}
+
+---
+
+## How It Works
+
+{Core logic and flow.}
+
+{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+
+---
+
+## Data Model
+
+{Entities this feature owns and their relationships. Mermaid ER diagram or table.}
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/path/file.ts` | What this file does |
+
+---
+
+## Dependencies & Integrations
+
+{External services, internal features, packages this relies on.}
+
+---
+
+## Configuration
+
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| `ENV_VAR` | What it controls | Yes/No |
+
+---
+
+## Error Handling
+
+{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+
+---
+
+## Constraints & Decisions
+
+{Why it's built this way. What you CANNOT change without breaking things.}
+
+---
+
+## Related Features
+
+{Cross-references to other docs by filename. Blast radius — what breaks if this changes.}
+
+---
+
+*Generated by vdoc v3.0.0 • Last updated: {timestamp}*