feat(docs): add docs skill with new/update/review/retcon + site wiring

- add skills/dev-docs/ (template library) and skills/docs/ (operational skill
  with new/update/review/retcon commands extracted from dev-docs)
- add monochrome docs icon, VitePress tile and sidebar entry in correct order
  (spec → dev → docs → flow → pr); update README workflow table
- parallelize docs new/retcon/review and usage report with background agents
- parallelize diff.md steps 3–4 (repo structure scan + category diffs)
- fix spec new: replace dead-end "Needs changes" button with Other free-text
- add xargs, sed, sort, pnpm run docs:build to allowed commands

Author: skapoor8

.claude/settings.json

@@ -51,6 +51,10 @@
       "Bash(npm run:*)",
       "Bash(npx:*)",
       "Bash(osascript:*)",
+      "Bash(pnpm run docs:build:*)",
+      "Bash(sed:*)",
+      "Bash(sort:*)",
+      "Bash(xargs:*)",
       "Bash(wc:*)",
       "Edit",
       "WebFetch",

README.md

@@ -33,6 +33,11 @@ Research requirements, generate proposals, create phase-by-phase implementation
 Architecture planning, technical exploration, and repo/branch comparison.</td>
 </tr>
 <tr>
+<td align="center"><img src="docs/public/icons/docs.svg" width="32"></td>
+<td><strong>docs</strong> — engineering documentation<br>
+Generate, update, review, and retroactively create docs from standard templates.</td>
+</tr>
+<tr>
 <td align="center"><img src="docs/public/icons/flow.svg" width="32"></td>
 <td><strong>flow</strong> — end-to-end pipeline orchestration<br>
 Chain skill workflows into end-to-end pipelines that run sequentially.</td>

docs/.vitepress/config.mjs

@@ -24,6 +24,7 @@ export default defineConfig({
     "skills/changelog/**",
     "skills/cz/**",
     "skills/dev/**",
+    "skills/docs/**",
     "skills/docker/**",
     "skills/em/**",
     "skills/flow/**",
@@ -106,6 +107,7 @@ export default defineConfig({
         items: [
           { text: "spec", link: "/skills/spec" },
           { text: "dev", link: "/skills/dev" },
+          { text: "docs", link: "/skills/docs" },
           { text: "flow", link: "/skills/flow" },
           { text: "pr", link: "/skills/pr" },
           { text: "qa", link: "/skills/qa" },

docs/index.md

@@ -28,6 +28,11 @@ features:
     title: dev
     details: Architecture planning, technical exploration, repo comparison, and docs generation.
     link: /skills/dev
+  - icon:
+      src: /icons/docs.svg
+    title: docs
+    details: Generate, update, review, and retroactively create engineering documentation.
+    link: /skills/docs
   - icon:
       src: /icons/flow.svg
     title: flow

docs/public/icons/docs.svg

@@ -40,12 +40,8 @@ Plan feature architecture or system design and write a draft to `.codevoyant/pla
 
 ### docs — generate architecture documentation
 
-Scan the codebase and produce component maps, data flow diagrams, API inventories, and dependency graphs in `docs/architecture/`.
-
-```bash
-/dev docs                                      # generate docs/architecture/ from codebase
-/dev docs --bg                                 # run in background, notify when done
-```
+> **Moved to `docs` skill.** Use `/docs new`, `/docs update`, `/docs review`, or `/docs retcon` instead.
+> See [`/skills/docs`](/skills/docs) for the full command reference.
 
 ### approve — promote plan to docs and Linear
 

docs/skills/dev.md

@@ -0,0 +1,72 @@
+# docs
+
+Generate, update, review, and retroactively create engineering documentation from standard templates.
+
+## Workflows
+
+### new -- create one or more doc files
+
+Generate a specific documentation file (or multiple files at once) using the appropriate component-type template.
+
+```bash
+/docs new auth --type library          # generate docs/architecture/auth.md
+/docs new auth storage payments        # batch: generate three files
+/docs readme                           # generate docs/README.md
+/docs architecture                     # generate docs/architecture/README.md
+```
+
+If `--type` is omitted, the type is auto-detected from the component's path in the codebase (`libs/` -> library, `apps/*/routes/api/` -> api, etc.).
+
+### update -- add to an existing doc from session context
+
+Update an existing documentation file with additions based on changes visible in the current session. Additive only -- existing content is preserved.
+
+```bash
+/docs update auth                      # update auth.md from session changes
+/docs update storage                   # update storage.md
+```
+
+Detects new env vars, new API endpoints, new design decisions, and new flow steps from the conversation, then adds them to the appropriate sections.
+
+### review -- audit docs/ for template adherence
+
+Evaluate Markdown files in `docs/` against the skill's template standards. Read-only -- nothing is modified. Emits a per-file gap report.
+
+```bash
+/docs review                           # audit all of docs/
+/docs review docs/architecture/        # audit one directory
+/docs review docs/architecture/auth.md # audit one file
+/docs review --json                    # machine-readable output
+```
+
+Checks for: required sections (Overview, Requirements, Design, Implementation, References), prescribed Mermaid diagram types, undefined acronyms, and second-person voice violations.
+
+### retcon -- generate full docs/ for a codebase with none
+
+Discover all major components in the codebase and generate a complete `docs/` structure from scratch. Useful when inheriting a project with no documentation.
+
+```bash
+/docs retcon                           # full codebase docs generation
+/docs retcon --dry-run                 # preview manifest before generating
+```
+
+## Templates
+
+All generated docs follow the section order: `Overview -> Requirements -> Design -> Implementation -> References`.
+
+Four component-type templates are available:
+
+| Type | Use for |
+|------|---------|
+| `api` | REST endpoint groups (`/api/`, route handlers) |
+| `library` | Monorepo packages (`libs/`, `packages/`) |
+| `frontend` | Svelte/React features, UI component libraries |
+| `infra` | Terraform modules (`infra/modules/`) |
+
+## Writing Standard
+
+Generated docs follow a junior-dev-friendly writing standard:
+- Define every acronym on first use
+- One idea per sentence
+- Explain "why" before "what" for non-obvious decisions
+- Mermaid diagrams replace prose for all multi-step flows

docs/skills/docs.md

@@ -0,0 +1,42 @@
+> **Superseded by `docs`** — this skill has been extracted into the standalone `docs` skill.
+> Use `/docs new`, `/docs update`, `/docs review`, or `/docs retcon` instead.
+> This file is kept for backwards compatibility only.
+
+# dev docs
+
+Generate and enforce documentation templates for engineering projects.
+
+Triggers: "dev docs", "generate docs", "create docs", "document {component}", "write docs for", "add docs for"
+
+## Critical Rules
+
+- **Never execute workflow logic here** — this file only parses args and dispatches
+- **Step 0 always runs first** — no exceptions
+- **Unknown verb → run `help.md`** — never error silently
+
+## Step 0: Parse Arguments
+
+```bash
+VERB="[first non-flag argument after 'docs', or empty]"
+REMAINING_ARGS="[everything after VERB, preserving order and flags]"
+
+# Normalise
+case "$VERB" in
+  "")             VERB="detect" ;;   # /dev docs → auto-detect missing docs
+  "arch")         VERB="architecture" ;;
+  "arch-readme")  VERB="architecture" ;;
+esac
+```
+
+## Step 1: Dispatch to Workflow
+
+Read and execute `references/workflows/{VERB}.md`, passing `$REMAINING_ARGS`.
+
+If `references/workflows/{VERB}.md` does not exist, fall back to `references/workflows/help.md`.
+
+## Workflow Index
+
+- **detect** (`references/workflows/docs.md`) — auto-detect missing docs and generate stubs
+- **readme** (`references/workflows/docs.md`) — generate/update `docs/README.md`
+- **architecture** (`references/workflows/docs.md`) — generate/update `docs/architecture/README.md` or a component file
+- **help** (`references/workflows/help.md`) — print command reference

skills/dev-docs/SKILL.md

@@ -0,0 +1,87 @@
+# Language Guide
+
+Rules for writing junior-dev-friendly engineering documentation.
+
+## Core Principle
+
+Documentation is for the person joining the team tomorrow with two years of experience.
+Not for the person who built the system. Not for a computer science professor.
+
+## Rules
+
+### 1. Define every acronym on first use
+
+Bad: "The app uses OIDC via an M2M flow with RS256 JWT validation."
+Good: "The app uses OpenID Connect (OIDC) — an identity layer on top of OAuth 2.0 — to verify who you are. It validates the JSON Web Token (JWT) using the RS256 algorithm (a public-key signature scheme)."
+
+Define once per document, in parentheses after the first use. Not in a glossary at the bottom — by the time the reader gets there, they're already confused.
+
+### 2. One idea per sentence
+
+Bad: "The session cookie, which is HttpOnly and therefore inaccessible to JavaScript running in the browser, contains a base64-encoded JSON object that includes the access token, refresh token, and expiry timestamp, and is validated on every request by re-verifying the JWT signature against Kinde's public JWKS endpoint."
+
+Good:
+"The session is stored in an HttpOnly cookie — JavaScript running in the browser cannot read it (this prevents XSS attacks from stealing sessions).
+The cookie contains a base64-encoded JSON object with the access token, refresh token, and expiry time.
+The server validates this cookie on every request by checking the JWT signature against Kinde's public key."
+
+### 3. Explain the "why" before the "what"
+
+Bad: "Post text is stored in GCS."
+Good: "Firestore documents have a 1 MB size limit, which long-form posts would easily exceed. Post text is therefore stored in GCS (Google Cloud Storage), with Firestore holding only a path reference."
+
+### 4. Use "you" (second person) consistently
+
+Bad: "The developer must add their email to `infra/shared/main.tf`."
+Good: "Add your email to `infra/shared/main.tf`."
+
+The reader is always "you". Never "the developer", "the user", "one", or passive voice.
+
+### 5. Keep `## Overview` to 3 sentences max
+
+The overview answers three questions:
+1. What is this? (one sentence)
+2. Where does it live in the codebase? (one sentence)
+3. Why does it exist / what problem does it solve? (one sentence)
+
+Everything else goes in Design or Implementation.
+
+### 6. Use tables for lists of 3+ related properties
+
+Bad:
+"The cookie is set with HttpOnly=true to prevent XSS. It uses Secure=true in production to require HTTPS. SameSite=Lax is set for CSRF protection."
+
+Good:
+| Property | Value | Purpose |
+|----------|-------|---------|
+| HttpOnly | true | Prevents JavaScript from reading the cookie (XSS protection) |
+| Secure | true in prod | Cookie only sent over HTTPS |
+| SameSite | Lax | Prevents CSRF attacks |
+
+### 7. Use diagrams to replace, not supplement, prose
+
+If you have a numbered list describing a multi-step flow, replace it with a `sequenceDiagram` or `flowchart`. Keep the numbered list only if the diagram would be harder to read (e.g. a list of 3 simple steps).
+
+The goal is: can a new team member understand the flow in 30 seconds from the diagram alone?
+
+### 8. Avoid impl-detail jargon in Overview and Requirements
+
+- No class names, function names, or file paths in `## Overview`
+- No TypeScript generics or internal abstractions in `## Requirements`
+- Save those for `## Design` and `## Implementation`
+
+### 9. Code blocks for everything executable
+
+Any command, path, variable value, or snippet that the reader might copy-paste: put it in a code block.
+
+Bad: "Run pnpm install then just dev."
+Good: Run `pnpm install` then `just dev`.
+Or:
+```bash
+pnpm install
+just dev
+```
+
+### 10. Link; don't duplicate
+
+If auth.md already explains the session format, link to it — don't repeat it. Use the `## References` section. Duplication creates maintenance debt.