@sandrinio/vdoc 3.0.1 → 3.4.0

package/skills/windsurf/resources/init-workflow.md

@@ -0,0 +1,123 @@
+# Init Workflow
+
+## Step 1 — Explore
+
+Follow the two-phase exploration strategy in `resources/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 `resources/exploration-strategies.md`.
+
+**Phase 2 — Targeted Exploration** (archetype-specific)
+Apply the matching archetype playbook from `resources/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 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 `vdocs/_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 `vdocs/_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. Follow the template in `resources/doc-template.md` 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 `resources/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

package/skills/windsurf/resources/manifest-schema.json

@@ -0,0 +1,16 @@
+{
+  "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 Feature Title",
+      "version": "1.0.0",
+      "description": "Rich semantic description with specific technology names, patterns, and concepts. Detailed enough that an AI can route any user question to this doc by matching against this field.",
+      "tags": ["keyword-1", "keyword-2"]
+    }
+  ]
+}

package/skills/windsurf/vdoc-workflow.md

@@ -1,6 +1,6 @@
 # /vdoc — Documentation Generator
 
-Run documentation workflows for this project. Full instructions are in `.windsurf/rules/vdoc.md`.
+Run documentation workflows for this project.
 
 ## Steps
 
@@ -14,18 +14,8 @@ The user may also specify: `/vdoc init` or `/vdoc audit`.
 
 ### Step 2a: Init Mode
 
-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 in `.windsurf/rules/vdoc.md`.
-4. **Manifest** — Create `vdocs/_manifest.json` with rich semantic descriptions.
-5. **Verify** — Every doc has mermaid diagrams, real paths, 2+ constraints, cross-references.
+Read and follow the workflow at `.windsurf/skills/vdoc/resources/init-workflow.md`. Use `.windsurf/skills/vdoc/resources/doc-template.md` as the doc template and `.windsurf/skills/vdoc/resources/manifest-schema.json` for the manifest format.
 
 ### Step 2b: Audit Mode
 
-1. Read `vdocs/_manifest.json`
-2. **Stale** — git diff since `last_updated`, cross-ref with each doc's "Key Files" section
-3. **Gaps** — undocumented features (new routes, services, models)
-4. **Dead** — docs referencing deleted files
-5. **Cross-refs** — verify Related Features links
-6. **Report** — present findings, wait for user direction
-7. **Patch** — update stale, generate gaps, fix cross-refs, update manifest
+Read and follow the workflow at `.windsurf/skills/vdoc/resources/audit-workflow.md`.

package/skills/cursor/vdoc.mdc

@@ -1,176 +0,0 @@
----
-description: "Generate and maintain feature-centric product documentation. Handles init (explore codebase, plan docs, generate), audit (detect stale/missing/dead docs, patch), and query (route questions via semantic manifest). Activates when user asks about documentation, says 'document this project', 'audit docs', or asks questions about codebase features."
-globs:
-alwaysApply: false
----
-
-# 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 into multiple diagrams.
-- **Data Model** must show real entities from the code, not placeholders.
-- **Constraints & Decisions** is the most valuable section. Dig for non-obvious choices. If the reason is unclear, write: `Reason: unknown — verify with team`.
-- **Related Features** must reference other doc filenames and explain the 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 enough 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 features 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 descriptions are accurate.
-6. **Report** — present stale docs, coverage gaps, dead docs, cross-ref issues, and current docs. Wait for user direction.
-7. **Patch** — update stale docs (re-read source, update affected sections). Generate new docs for gaps. Flag dead docs for removal. 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, say so and 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". It prevents breaking changes.
-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. Report before patching.

package/skills/windsurf/vdoc.md

@@ -1,94 +0,0 @@
----
-trigger: model_decision
-description: "Generate and maintain feature-centric product documentation. Modes: init (explore, plan, generate docs), audit (detect stale/missing/dead docs, patch), query (route questions via manifest). Activates on 'document this project', 'audit docs', or documentation questions."
----
-
-# vdoc — Documentation Generator
-
-Three modes: **init**, **audit**, **query**. All docs live in `vdocs/`. Manifest at `vdocs/_manifest.json` is the semantic index.
-
-## Init ("document this project")
-
-1. **Explore** — Read codebase: tech stack, features, architecture, integrations, entry points. Read actual files, don't skim.
-2. **Plan** — Create `vdocs/_DOCUMENTATION_PLAN.md` listing proposed docs. Present to user, suggest changes. Wait for approval.
-3. **Generate** — For each doc, read ALL relevant source files. Write `vdocs/FEATURE_NAME_DOC.md` using template below.
-4. **Manifest** — Create `vdocs/_manifest.json` (schema below).
-5. **Self-review** — Verify: mermaid diagrams present, real file paths, actual env vars, 2+ constraints per doc, cross-references exist.
-
-## Audit ("audit docs")
-
-1. Read `vdocs/_manifest.json`
-2. **Stale**: git diff since `last_updated`, cross-ref with each doc's "Key Files" section
-3. **Gaps**: find significant undocumented source files (routes, services, models)
-4. **Dead**: docs referencing deleted source files
-5. **Cross-refs**: verify Related Features links still valid
-6. **Report** to user, wait for direction, then patch/create/remove as approved
-7. Update manifest versions and timestamps
-
-## Query (any documentation question)
-
-Read manifest → match `description`/`tags` → read matching doc → answer. If no match, suggest audit.
-
-## Doc Template
-
-```markdown
-# {Feature Title}
-> {One-line description}
-
-## Overview
-{What it does, why it exists, system fit.}
-
-## How It Works
-{Core flow. Mermaid diagram(s) — max 7-9 nodes, split if larger.}
-
-## Data Model
-{Entities and relationships. Mermaid ER or table.}
-
-## Key Files
-| File | Purpose |
-|------|---------|
-
-## Dependencies & Integrations
-{External services, internal features, packages.}
-
-## Configuration
-| Variable | Purpose | Required |
-|----------|---------|----------|
-
-## Error Handling
-{Failure modes, user impact, retry logic. Mermaid if non-trivial.}
-
-## Constraints & Decisions
-{Why built this way. What CANNOT change without breaking things.}
-
-## Related Features
-{Cross-refs to other doc filenames. Blast radius.}
-```
-
-## Manifest Schema
-
-```json
-{
-  "project": "<name>",
-  "vdoc_version": "3.0.0",
-  "created_at": "<ISO-8601>",
-  "last_updated": "<ISO-8601>",
-  "last_commit": "<sha>",
-  "documentation": [{
-    "filepath": "FEATURE_NAME_DOC.md",
-    "title": "Title",
-    "version": "1.0.0",
-    "description": "Rich semantic description for AI routing.",
-    "tags": ["keyword-tag"]
-  }]
-}
-```
-
-## Rules
-
-- **Feature-centric**: one doc per feature, not per file
-- **Mermaid mandatory**: diagram flows, max 7-9 nodes
-- **Constraints are gold**: always fill, prevents breaking changes
-- **Rich descriptions**: manifest descriptions are semantic search indexes
-- **No hallucination**: only document what exists in code
-- **Plan first**: never generate without user approval