@sandrinio/vdoc 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandro Sulaberidze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# vdoc
+
+**Documentation skills for AI coding agents.**
+
+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 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
+```
+
+---
+
+## Quick Start
+
+```bash
+npx vdoc install cursor
+```
+
+Then open Cursor and type: **`/vdoc init`**
+
+---
+
+## Supported Platforms
+
+| 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 |
+
+---
+
+## How It Works
+
+### 1. Install (~5 seconds)
+
+```bash
+npx vdoc install claude
+```
+
+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:
+
+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
+
+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.
+
+### 4. Query
+
+Ask any question. The AI reads the manifest, routes to the right doc, and answers from documented knowledge.
+
+---
+
+## What Gets Created
+
+```
+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
+    └── ...
+```
+
+Docs are **feature-centric** — organized by what your system does, not by file paths.
+
+---
+
+## Documentation Template
+
+Every generated doc follows a consistent structure:
+
+- **Overview** — what it does, why it exists
+- **How It Works** — core logic with mermaid diagrams (max 7-9 nodes per diagram)
+- **Data Model** — entities and relationships
+- **Key Files** — source files that implement this feature
+- **Dependencies & Integrations** — external services, internal features
+- **Configuration** — env vars, feature flags, secrets
+- **Error Handling** — failure modes and user-facing behavior
+- **Constraints & Decisions** — why it's built this way, what you can't change
+- **Related Features** — cross-references and blast radius
+
+---
+
+## 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:
+
+```json
+{
+  "documentation": [
+    {
+      "filepath": "AUTHENTICATION_DOC.md",
+      "title": "Authentication - OAuth2 & JWT",
+      "version": "1.0.0",
+      "description": "OAuth2 flow with Google/GitHub providers, JWT lifecycle, session management via NextAuth.js, route protection middleware, and role-based access control.",
+      "tags": ["oauth2", "jwt", "session-management", "rbac"]
+    }
+  ]
+}
+```
+
+---
+
+## Uninstall
+
+```bash
+npx 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:
+
+| Platform | Files Removed |
+|----------|--------------|
+| Claude Code | `.claude/skills/vdoc/` |
+| 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` |
+| Continue | `.continue/rules/vdoc.md`, `.continue/prompts/vdoc-command.md` |
+| Cline | `.clinerules/vdoc.md`, `.clinerules/workflows/vdoc.md` |
+| Gemini CLI | `.gemini/commands/vdoc.toml` |
+| JetBrains AI | `.aiassistant/rules/vdoc.md` |
+| Universal | `AGENTS.md` (vdoc section only) |
+
+For files shared with other tools (`GEMINI.md`, `.junie/guidelines.md`, `.github/copilot-instructions.md`), only the vdoc-injected section is removed.
+
+Your `vdocs/` documentation folder is **always kept intact**.
+
+---
+
+## Requirements
+
+None. Your AI coding agent is the runtime.
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+*vdoc v3.0.0 — Documentation skills for AI coding agents*

package/bin/vdoc.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, rmSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS = resolve(__dirname, '..', 'skills');
+const CWD = process.cwd();
+
+// ── Platform mappings ──────────────────────────────────────────────
+
+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' },
+    ],
+  },
+  cursor: {
+    files: [
+      { src: 'cursor/vdoc.mdc', dest: '.cursor/rules/vdoc.mdc' },
+      { src: 'cursor/vdoc-command.md', dest: '.cursor/commands/vdoc.md' },
+    ],
+  },
+  windsurf: {
+    files: [
+      { src: 'windsurf/vdoc.md', dest: '.windsurf/rules/vdoc.md' },
+      { src: 'windsurf/vdoc-workflow.md', dest: '.windsurf/workflows/vdoc.md' },
+    ],
+  },
+  vscode: {
+    files: [
+      { 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 },
+    ],
+  },
+  continue: {
+    files: [
+      { src: 'continue/vdoc.md', dest: '.continue/rules/vdoc.md' },
+      { src: 'continue/vdoc-command.md', dest: '.continue/prompts/vdoc-command.md' },
+    ],
+  },
+  cline: {
+    files: [
+      { src: 'cline/vdoc.md', dest: '.clinerules/vdoc.md' },
+      { src: 'cline/vdoc-workflow.md', dest: '.clinerules/workflows/vdoc.md' },
+    ],
+  },
+  gemini: {
+    files: [
+      { src: 'gemini/vdoc.toml', dest: '.gemini/commands/vdoc.toml' },
+      { src: 'gemini/GEMINI.md', dest: 'GEMINI.md', inject: true },
+    ],
+  },
+  jetbrains: {
+    files: [
+      { src: 'jetbrains-ai/vdoc.md', dest: '.aiassistant/rules/vdoc.md' },
+    ],
+  },
+  junie: {
+    files: [
+      { src: 'junie/guidelines.md', dest: '.junie/guidelines.md', inject: true },
+    ],
+  },
+  agents: {
+    files: [
+      { src: 'agents/AGENTS.md', dest: 'AGENTS.md', inject: true },
+    ],
+  },
+};
+
+const MARKER_START = '<!-- vdoc:start -->';
+const MARKER_END = '<!-- vdoc:end -->';
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function copyFile(src, dest) {
+  const srcPath = join(SKILLS, src);
+  const destPath = join(CWD, dest);
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, readFileSync(srcPath));
+  console.log(`  ✓ ${dest}`);
+}
+
+function injectFile(src, dest) {
+  const srcPath = join(SKILLS, src);
+  const destPath = join(CWD, dest);
+  const content = readFileSync(srcPath, 'utf8');
+
+  // Ensure content has markers
+  const injection = content.includes(MARKER_START)
+    ? content
+    : `${MARKER_START}\n${content}\n${MARKER_END}`;
+
+  if (existsSync(destPath)) {
+    const existing = readFileSync(destPath, 'utf8');
+    const startIdx = existing.indexOf(MARKER_START);
+    const endIdx = existing.indexOf(MARKER_END);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      // Replace between markers
+      const before = existing.slice(0, startIdx);
+      const after = existing.slice(endIdx + MARKER_END.length);
+      writeFileSync(destPath, before + injection + after);
+    } else {
+      // Append
+      writeFileSync(destPath, existing.trimEnd() + '\n\n' + injection + '\n');
+    }
+  } else {
+    mkdirSync(dirname(destPath), { recursive: true });
+    writeFileSync(destPath, injection.endsWith('\n') ? injection : injection + '\n');
+  }
+  console.log(`  ✓ ${dest} (injected)`);
+}
+
+function removeFile(dest) {
+  const destPath = join(CWD, dest);
+  if (existsSync(destPath)) {
+    unlinkSync(destPath);
+    console.log(`  ✓ removed ${dest}`);
+    cleanEmptyDirs(dirname(destPath));
+    return true;
+  }
+  return false;
+}
+
+function uninjectFile(dest) {
+  const destPath = join(CWD, dest);
+  if (!existsSync(destPath)) return false;
+
+  const content = readFileSync(destPath, 'utf8');
+  const startIdx = content.indexOf(MARKER_START);
+  const endIdx = content.indexOf(MARKER_END);
+
+  if (startIdx === -1 || endIdx === -1) return false;
+
+  const before = content.slice(0, startIdx);
+  const after = content.slice(endIdx + MARKER_END.length);
+  const remaining = (before + after).trim();
+
+  if (remaining.length === 0) {
+    unlinkSync(destPath);
+    console.log(`  ✓ removed ${dest}`);
+    cleanEmptyDirs(dirname(destPath));
+  } else {
+    writeFileSync(destPath, remaining + '\n');
+    console.log(`  ✓ cleaned vdoc section from ${dest}`);
+  }
+  return true;
+}
+
+function cleanEmptyDirs(dir) {
+  // Don't clean above CWD
+  if (!dir.startsWith(CWD) || dir === CWD) return;
+  try {
+    const entries = readdirSync(dir);
+    if (entries.length === 0) {
+      rmSync(dir);
+      cleanEmptyDirs(dirname(dir));
+    }
+  } catch { /* ignore */ }
+}
+
+function isDirEmpty(dir) {
+  try {
+    return readdirSync(dir).length === 0;
+  } catch { return true; }
+}
+
+// ── Commands ───────────────────────────────────────────────────────
+
+function install(platform) {
+  const config = PLATFORMS[platform];
+  if (!config) {
+    console.error(`Unknown platform: ${platform}`);
+    console.error(`Supported: ${Object.keys(PLATFORMS).join(', ')}`);
+    process.exit(1);
+  }
+
+  console.log(`\nvdoc → installing for ${platform}\n`);
+
+  for (const file of config.files) {
+    if (file.inject) {
+      injectFile(file.src, file.dest);
+    } else {
+      copyFile(file.src, file.dest);
+    }
+  }
+
+  console.log(`\nDone. Open your AI tool and type: /vdoc init\n`);
+}
+
+function uninstall() {
+  console.log(`\nvdoc → removing all skill files\n`);
+
+  let removed = 0;
+
+  for (const [, config] of Object.entries(PLATFORMS)) {
+    for (const file of config.files) {
+      if (file.inject) {
+        if (uninjectFile(file.dest)) removed++;
+      } else {
+        if (removeFile(file.dest)) removed++;
+      }
+    }
+  }
+
+  // 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));
+  }
+
+  if (removed === 0) {
+    console.log('  No vdoc files found.');
+  }
+
+  console.log(`\nDone. Your vdocs/ documentation folder was kept intact.\n`);
+}
+
+// ── Main ───────────────────────────────────────────────────────────
+
+const [,, command, platform] = process.argv;
+
+if (command === 'install' && platform) {
+  install(platform);
+} else if (command === 'uninstall') {
+  uninstall();
+} else {
+  console.log(`
+vdoc v3.0.0 — Documentation skills for AI coding agents
+
+Usage:
+  npx vdoc install <platform>   Install skill files for a platform
+  npx vdoc uninstall             Remove all vdoc skill files (keeps vdocs/)
+
+Platforms:
+  ${Object.keys(PLATFORMS).join(', ')}
+`);
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@sandrinio/vdoc",
+  "version": "3.0.0",
+  "description": "Documentation skills for AI coding agents",
+  "type": "module",
+  "bin": {
+    "vdoc": "bin/vdoc.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "keywords": [
+    "documentation",
+    "ai",
+    "coding-agent",
+    "cursor",
+    "claude",
+    "copilot",
+    "windsurf",
+    "cline",
+    "continue",
+    "gemini"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sandrinio/vdoc.git"
+  }
+}

package/skills/agents/AGENTS.md

@@ -0,0 +1,170 @@
+# vdoc — Documentation Generator
+
+You generate and maintain feature-centric documentation for codebases. You have three modes: **init**, **audit**, and **query**.
+
+All documentation lives in `vdocs/` at the project root. The manifest at `vdocs/_manifest.json` is the semantic index you read first.
+
+---
+
+## 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.}
+
+---
+
+## Data Model
+{Entities this feature owns. 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 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.
+
+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.
+
+---
+
+## 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.