@sandrinio/vdoc 3.6.1 → 3.7.0

package/bin/vdoc.mjs

@@ -20,6 +20,10 @@ const PLATFORMS = {
       { 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' },
+      { src: 'claude/commands/vdoc-init.md', dest: '.claude/commands/vdoc-init.md' },
+      { src: 'claude/commands/vdoc-create.md', dest: '.claude/commands/vdoc-create.md' },
+      { src: 'claude/commands/vdoc-update.md', dest: '.claude/commands/vdoc-update.md' },
+      { src: 'claude/commands/vdoc-audit.md', dest: '.claude/commands/vdoc-audit.md' },
     ],
   },
   cursor: {

package/package.json

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

package/skills/agents/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `.agents/vdoc/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/claude/commands/vdoc-audit.md

@@ -0,0 +1 @@
+Read and follow the rules in `.claude/skills/vdoc/SKILL.md`, then execute the audit workflow at `.claude/skills/vdoc/references/audit-workflow.md`.

package/skills/claude/commands/vdoc-create.md

@@ -0,0 +1,3 @@
+Read and follow the rules in `.claude/skills/vdoc/SKILL.md`, then execute the create workflow at `.claude/skills/vdoc/references/create-workflow.md`.
+
+Create a doc for: $ARGUMENTS

package/skills/claude/commands/vdoc-init.md

@@ -0,0 +1 @@
+Read and follow the rules in `.claude/skills/vdoc/SKILL.md`, then execute the init workflow at `.claude/skills/vdoc/references/init-workflow.md`.

package/skills/claude/commands/vdoc-update.md

@@ -0,0 +1 @@
+Read and follow the rules in `.claude/skills/vdoc/SKILL.md`, then execute the audit workflow at `.claude/skills/vdoc/references/audit-workflow.md`.

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

@@ -9,6 +9,7 @@ Use the user's description to find the relevant source files:
 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
+4. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
 
 Do not skim. Understand how the feature actually works before writing.
 
@@ -19,12 +20,16 @@ Do not skim. Understand how the feature actually works before writing.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **Constraints & Decisions** is the most valuable section. Dig into the code for non-obvious choices. 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.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 3 — Update Manifest
 
@@ -43,3 +48,6 @@ 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
+- [ ] Doc has "User Workflows" with at least one step-by-step journey
+- [ ] Doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Doc has a "Security" section documenting auth/access patterns

package/skills/claude/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ 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:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/cline/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `references/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/continue/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `references/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/cursor/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `references/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/gemini/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `.gemini/vdoc/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/jetbrains-ai/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

package/skills/jetbrains-ai/references/init-workflow.md

@@ -84,19 +84,24 @@ Read the template from `.aiassistant/vdoc/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/junie/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `.junie/vdoc/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/vscode/references/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ 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:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns

package/skills/windsurf/resources/doc-template.md

@@ -6,21 +6,38 @@
 
 ## Overview
 
-{What it does, why it exists, how it fits in the system.}
+{What it does and why it exists. Start with the value proposition — what problem does this solve for the user? Then explain how it fits in the system.}
+
+---
+
+## User Workflows
+
+{Step-by-step journeys for the 1-3 primary user actions. For each workflow:}
+
+1. **{Workflow Name}**
+   - **User action:** {What the user does}
+   - **System response:** {What the system does}
+   - **Result:** {What the user sees}
 
 ---
 
 ## How It Works
 
-{Core logic and flow.}
+{Trace at least one complete request from user action to final effect. Show the full path through every service, database call, and external system involved. Don't skip intermediaries.}
 
-{Mermaid diagram(s) — max 7-9 nodes per diagram, split into multiple if larger.}
+{Use a sequence diagram for the primary flow — show all actors. Use flowcharts for branching logic only. 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.}
+{Primary tables this feature owns. Include actual column names, types, and purpose — not just entity names.}
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `column_name` | `type` | What it stores |
+
+{Mermaid ER diagram for relationships between tables.}
 
 ---
 
@@ -46,9 +63,17 @@
 
 ---
 
-## Error Handling
+## Error Handling & Edge Cases
+
+{Specific failure scenarios, not generic statements. For each:}
+
+- **{Scenario}** — {What triggers it}. User sees: {what}. System does: {recovery/logging}.
+
+---
+
+## Security
 
-{Failure modes, what the user sees, retry logic. Mermaid diagram if the error flow is non-trivial.}
+{Authentication and authorization patterns. Service roles, secrets, access control. What an attacker could exploit if this feature were misconfigured.}
 
 ---
 

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

@@ -84,19 +84,24 @@ Read the template from `resources/doc-template.md` once before starting.
 Then generate docs **one at a time, sequentially**. For each approved doc:
 
 1. Read ALL relevant source files for that feature — not just the main file, but helpers, types, middleware, tests
-2. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
-3. Confirm the file was written before moving to the next doc
+2. **Trace the end-to-end flow** — pick the primary user action and follow it through every layer: frontend → API route → service/lib → database → external service → response. Read each file in the chain. Don't stop at the service layer.
+3. Write `vdocs/FEATURE_NAME_DOC.md` following the template exactly
+4. Confirm the file was written before moving to the next doc
 
-Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → write doc → next.
+Do NOT attempt to generate multiple docs from memory. Each doc is a fresh cycle: read sources → trace flows → write doc → next.
 
 **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.
+- **Overview** must open with the value proposition — what problem does this feature solve for the user? Not just "manages X" but "enables users to Y without Z."
+- **User Workflows** — describe 1-3 primary user journeys step by step: what the user does, what the system does, what the user sees. This grounds the doc in product reality.
+- **"How It Works" must use sequence diagrams** for the primary flow — show every actor (user, frontend, API, service, database, external systems). Flowcharts are for branching logic only. Trace the COMPLETE path — if there's a cron job that calls an executor that calls an external API, show all three, not just "cron → external API."
+- **Data Model** must show actual column names, types, and descriptions for primary tables — not just entity names in an ER diagram. Read the actual schema/types files. Include fields that carry important semantics (e.g., `session_id` for context continuity, `webhook_url` for per-config endpoints).
+- **Error Handling & Edge Cases** — list specific failure scenarios: "If the user's OAuth token expires, the system does X. The user sees Y." Not generic "errors are logged." Think: what breaks at 2 AM with no user present?
+- **Security** — document auth patterns, service roles, secrets, access control. If a background job bypasses RLS with a service role, say so. If an endpoint is guarded by a bearer token, document it.
 - **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?
+- **Key Files** — list every file in the execution path, not just the "main" files. If a cron handler, executor, service, and DB helper are all involved, list all of them.
 
 ## Step 4 — Manifest
 
@@ -127,3 +132,6 @@ 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
+- [ ] Every doc has "User Workflows" with at least one step-by-step journey
+- [ ] Every doc has specific "Error Handling & Edge Cases" (not generic)
+- [ ] Every doc has a "Security" section documenting auth/access patterns