feat(doc-syncer): stack-aware audit with deploy-doc gating

Auto-discover what the project actually has instead of a fixed doc list:
root files (incl. DEPLOY.md, SECURITY.md, ARCHITECTURE.md, ROADMAP.md),
docs/**, and .claude/{tasks,audits,memory}/.

Detect stack (Node/Python/Rust/Go/Ruby/PHP/Dart/.NET) and deploy
complexity (NONE/TRIVIAL/NON_TRIVIAL) to drive doc-needs:
- Propose DEPLOY.md only when non-trivial (Docker, fly.toml, k8s,
  multi-stage CI).
- Propose inlining/removing DEPLOY.md when deploy is trivial.
- Enforce README presence with typical GitHub layout.

Add CREATE/REMOVE proposal categories to the validation gate. Update
auto-mode to map deploy artifacts to DEPLOY.md and decisions.md
architectural changes back to CLAUDE.md/README.

Sync skills/doc/SKILL.md description + triggers to match.

Co-Authored-By: Claude <noreply@anthropic.com>

agents/doc-syncer.md

@@ -1,6 +1,6 @@
 ---
 name: doc-syncer
-description: Detect stale documentation by cross-referencing git history against doc files. Audit, report, and patch. Supports full audit and automatic (silent) mode.
+description: Detect stale documentation by cross-referencing git history against the project's actual doc layout. Auto-discovers root docs, docs/**, and .claude/{tasks,audits,memory}/. Stack-aware deploy-doc gating (DEPLOY.md only when non-trivial). Enforces README presence. Audit, report, patch. Supports full audit and automatic (silent) mode.
 tools: Read, Write, Edit, Bash, Grep, Glob
 model: sonnet
 ---
@@ -9,8 +9,10 @@ model: sonnet
 
 ## GOAL
 Keep documentation in sync with code. Detect drift, report it,
-and patch what can be patched automatically. Never invent content
--- only reflect what actually changed in code.
+patch what can be patched automatically. Auto-discover what doc
+the project has and what it actually needs based on stack and
+deploy complexity. Never invent content -- only reflect what
+changed in code.
 
 ## REQUEST
 $ARGUMENTS
@@ -19,135 +21,265 @@ $ARGUMENTS
 
 ## MODE DETECTION
 
-Parse `$ARGUMENTS` to determine mode:
+Parse `$ARGUMENTS`:
 
 - **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:`
-  Jump directly to AUTO MODE section below.
+  Jump to AUTO MODE section.
 - **FULL AUDIT** — anything else (empty, file list, description)
-  Run the full audit workflow below.
+  Run the full audit workflow.
 
 ---
 
 ## FULL AUDIT
 
-### STEP 1 — DISCOVER DOCS
+### STEP 1 — DISCOVER PROJECT DOC LAYOUT
 
-Find all documentation files in the project:
+Auto-detect what doc files actually exist. No fixed list.
 
 ```bash
-# Standard doc files at root
-ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
-   CONTRIBUTING.md CHANGELOG.md 2>/dev/null
-
-# Docs directory
-find docs -name '*.md' 2>/dev/null | head -50
+# Standard root doc files (only those that exist)
+for f in README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
+         DEPLOY.md CONTRIBUTING.md CHANGELOG.md SECURITY.md \
+         CODE_OF_CONDUCT.md ARCHITECTURE.md ROADMAP.md LICENSE; do
+  [ -f "$f" ] && echo "$f"
+done
+
+# docs/ tree
+find docs -name '*.md' 2>/dev/null
+
+# .claude/ project-state docs
+find .claude/tasks .claude/audits .claude/memory \
+  -name '*.md' 2>/dev/null
 ```
 
-Store the list as `DOC_FILES`.
-If no docs found at all, report and stop.
+Store as `DOC_FILES` (existing) and `DOC_MISSING` (canonical names
+absent — at minimum: README.md).
+
+### STEP 2 — STACK & DEPLOY ANALYSIS
+
+Detect project stack and deploy complexity. Drives later decisions
+about which docs are needed.
+
+**Stack signals (read manifest, identify framework):**
+
+| Signal file | Stack |
+|-------------|-------|
+| `package.json` — read `dependencies` | Node/JS — React, Next.js, Astro, Vue, Svelte, Express, NestJS, etc. |
+| `requirements.txt` / `pyproject.toml` / `Pipfile` | Python — Django, FastAPI, Flask, Streamlit |
+| `Cargo.toml` | Rust — Axum, Actix, Tauri |
+| `go.mod` | Go |
+| `Gemfile` | Ruby/Rails |
+| `composer.json` | PHP — Symfony, Laravel |
+| `pubspec.yaml` | Dart/Flutter |
+| `*.csproj` / `*.sln` | .NET |
 
-### STEP 2 — DETECT DRIFT PER DOC
+**Deploy signals — classify trivial vs non-trivial:**
+
+| Signal | Complexity |
+|--------|-----------|
+| `Dockerfile`, `docker-compose.yml`, `compose.yaml` | NON_TRIVIAL |
+| `fly.toml`, `render.yaml`, `railway.toml`, `vercel.json`, `netlify.toml` | NON_TRIVIAL |
+| `.github/workflows/deploy*.yml`, `.gitlab-ci.yml` w/ deploy stage | NON_TRIVIAL |
+| `kubernetes/`, `helm/`, `k8s/`, manifests w/ `kind: Deployment` | NON_TRIVIAL |
+| `terraform/`, `pulumi/`, `serverless.yml`, SAM `template.yaml` | NON_TRIVIAL |
+| `Makefile` w/ multi-step deploy target | NON_TRIVIAL |
+| Multiple env-specific configs (`.env.production`, `.env.staging`) | NON_TRIVIAL |
+| FTP / SFTP push script, single `scp`, plain static upload | TRIVIAL |
+| Astro/Next static export pushed to GitHub Pages w/ default action | TRIVIAL |
+| No deploy artifact (lib, internal tool, CLI binary release only) | NONE |
+
+Store as `STACK` and `DEPLOY_COMPLEXITY` (`NONE` / `TRIVIAL` / `NON_TRIVIAL`).
+Record evidence (which file triggered classification) for the report.
+
+### STEP 3 — DETECT DRIFT PER DOC
 
 For each file in `DOC_FILES`:
 
-1. Get its last modification date:
+1. Get last modification date:
    ```bash
    git log -1 --format=%aI -- <file>
    ```
 
-2. Get all commits touching the codebase since that date:
+2. Get commits touching the codebase since that date. Adapt globs
+   to detected `STACK`:
    ```bash
    git log --oneline --since="<date>" \
-     --diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \
-     '*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \
-     '*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \
+     --diff-filter=AMRD -- <stack-specific source globs> \
      'Dockerfile' 'docker-compose.yml' 'Makefile' \
-     'package.json' 'Cargo.toml' 'pyproject.toml'
+     '*.toml' '*.json' '*.yaml' '*.yml' '*.env.example'
    ```
-   Adapt glob list to the project's actual stack.
 
-3. For each commit, extract what changed:
+3. For each commit, extract changes:
    ```bash
    git show --stat --name-only <hash>
    git diff <hash>~1..<hash> --unified=3
    ```
    Look for: new/renamed/deleted functions, new config keys,
    new CLI flags, changed endpoints, breaking changes,
-   dependency adds/removes/upgrades,
-   **new features added**, **features removed or deprecated**.
-
-4. Cross-reference each change against the doc's content.
-   Read the doc file and check if the change is reflected.
-
-5. **Feature delta detection** — compare what the code provides
-   vs what the docs describe:
-   - Scan for new entry points, routes, commands, skills, or
-     modules that have no corresponding doc section → ADDED.
-   - Scan docs for references to functions, files, endpoints,
-     or features that no longer exist in the codebase → REMOVED.
-   - Use `git diff --stat` between last doc edit and HEAD to
-     identify files added (`A`) or deleted (`D`).
+   dep adds/removes/upgrades, new features, removed features.
 
-### STEP 3 — ANALYSIS PER DOC TYPE
+4. Cross-reference each change against doc content.
 
-Apply doc-specific checks:
-
-**README.md**
-- Install steps: do commands still match package manifest and CLAUDE.md?
-- Feature list: does it cover current functionality?
-  - **Added features:** new skills, commands, endpoints, or modules
-    present in code but missing from the feature list → tag AUTO
-    if name/description is obvious, HUMAN if wording needs judgment.
-  - **Removed features:** entries in the feature list that reference
-    code, files, or endpoints that no longer exist → tag AUTO for
-    removal, HUMAN if the feature was deprecated (needs migration note).
-- Examples: do code snippets match current API/signatures?
-- Prerequisites: are versions and tools still accurate?
-- Docker section: present if Docker is used, absent if not?
+5. **Feature delta detection:**
+   - New entry points / routes / commands / skills / modules in
+     code, no doc section → `[ADDED]`.
+   - Doc references functions / files / endpoints / features
+     absent from code → `[REMOVED]`.
+   - Use `git diff --stat` between last doc edit and HEAD to
+     identify added (`A`) / deleted (`D`) files.
+
+### STEP 4 — ANALYSIS PER DOC TYPE
+
+Apply doc-specific checks. Skip docs not in `DOC_FILES` (handled
+by STEP 5/6 if creation needed).
+
+**README.md** — *must exist; see STEP 5 if absent*
+- Title + one-line description present?
+- Quick-start commands match package manifest?
+- Feature list covers current functionality?
+  - **Added:** new skills/commands/endpoints/modules in code,
+    missing from feature list → AUTO if name obvious, HUMAN if
+    wording needs judgment.
+  - **Removed:** entries referencing code/files/endpoints absent
+    → AUTO for removal, HUMAN if deprecated.
+- Examples match current API/signatures?
+- Prerequisites: versions/tools accurate?
+- Cross-links present and pointing to existing files
+  (`INSTALL.md`, `CONFIGURE.md`, `USAGE.md`, `DEPLOY.md`,
+  `CONTRIBUTING.md`, `CHANGELOG.md`)? Dead link → AUTO removal.
+  Missing link to existing doc → AUTO addition.
 
 **CLAUDE.md**
-- Norms: do coding conventions match current project patterns?
-- Stack description: still accurate?
-- Commands (build/test/lint): still runnable?
-- Folder tree: matches actual structure?
-- New patterns worth documenting?
-
-**INSTALL.md / CONFIGURE.md**
-- Environment variables: do all referenced vars exist in .env.example?
-- Install steps: match current dependency manager and versions?
-- Configuration steps: reference current config file format?
+- Norms match current project patterns?
+- Stack description matches detected `STACK`?
+- Build/test/lint commands runnable?
+- Folder tree matches actual structure?
+- Decisions in `.claude/memory/decisions.md` reflected when
+  architectural (framework choice, security stance, API versioning)?
+
+**INSTALL.md**
+- Env vars referenced exist in `.env.example`?
+- Install steps match current dep manager + versions?
+- OS/runtime prerequisites accurate?
+
+**CONFIGURE.md**
+- Config-file format matches current code?
+- Each documented option still present in code?
+- New options added to code reflected here?
 
 **USAGE.md**
-- CLI flags and commands: match current implementation?
-- API endpoints: match current routes?
-- Code examples: match current signatures?
+- CLI flags / commands match current implementation?
+- API endpoints match current routes (versioned per
+  `/api/v1/...` rule)?
+- Code examples match current signatures?
+
+**DEPLOY.md**
+- Steps match detected deploy artifacts (Dockerfile, fly.toml,
+  workflows, etc.)?
+- Production env vars listed and match `.env.example`?
+- Rollback procedure present (non-trivial deploy)?
+- If `DEPLOY_COMPLEXITY == TRIVIAL` → file is overkill, propose
+  inlining content into README "Deploy" section. HUMAN.
 
 **CONTRIBUTING.md**
-- Branch workflow: still accurate?
-- Test commands: still correct?
-- Code style rules: still enforced?
+- Branch workflow accurate?
+- Test commands correct?
+- Code style rules still enforced (lint config, formatter)?
 
 **CHANGELOG.md**
-- Latest code changes: do they have corresponding entries?
-- Entry format: consistent with existing style?
+- Latest code changes have entries? Always HUMAN.
+- Entry format consistent with existing style?
 
 **docs/**/*.md**
-- Technical accuracy: do references to code match reality?
-- Links: do internal links point to existing files/sections?
+- Technical accuracy: code references match reality?
+- Internal links point to existing files/sections?
+
+**.claude/tasks/TODO.md**
+- Tasks still relevant given current code state?
+- Completed subtasks ticked?
+- Tasks for code that no longer exists → flag for cleanup. HUMAN.
+
+**.claude/audits/*.md**
+- Audit reports (SEO, harden, validate, BUGS-FOUND, etc.)
+  reference paths/files that still exist?
+- Findings still applicable, or already resolved by later commits?
+  Flag resolved findings → HUMAN (user decides whether to archive).
+
+**.claude/memory/decisions.md / learnings.md / blockers.md**
+- Decisions referencing files/modules → those still exist?
+- Resolved blockers marked `resolved`?
+- Decisions contradicting current code → surface for user
+  reconciliation. HUMAN.
+
+**.claude/memory/journal.md / evals.md**
+- Append-only logs — never edit. Skip drift checks.
 
 **Inline comments (JSDoc, docstrings, rustdoc, godoc)**
-- Only check files that changed since last doc update.
-- `@param` / `@return` types: match actual function signatures?
-- Description: still accurate after the change?
+- Only check files changed since last doc update.
+- `@param` / `@return` types match actual function signatures?
+- Description still accurate after the change?
+
+### STEP 5 — README BOOTSTRAP CHECK
 
-### STEP 4 — REPORT
+If `README.md ∉ DOC_FILES`:
 
-Present a structured report:
+README is mandatory. Propose creation using typical GitHub layout —
+include only sections relevant to detected `STACK` and
+`DEPLOY_COMPLEXITY`. Use real project data (manifest name,
+description, install/run commands). No placeholders.
+
+Proposed template (HUMAN approval required):
+
+```markdown
+# <project-name>
+
+<one-line description from manifest or git remote>
+
+## Features
+- <bullet from detected entry points / commands>
+- <bullet>
+
+## Quick Start
+\`\`\`bash
+<install command from detected stack>
+<run command from detected stack>
+\`\`\`
+
+## Documentation
+- [Install](INSTALL.md)            <!-- only if exists or proposed -->
+- [Configure](CONFIGURE.md)        <!-- only if exists or proposed -->
+- [Usage](USAGE.md)                <!-- only if exists or proposed -->
+- [Deploy](DEPLOY.md)              <!-- only if DEPLOY_COMPLEXITY == NON_TRIVIAL -->
+- [Contributing](CONTRIBUTING.md)  <!-- only if exists -->
+- [Changelog](CHANGELOG.md)        <!-- only if exists -->
+
+## License
+<from LICENSE file or manifest, else HUMAN>
+```
+
+Tag overall as HUMAN — user validates before write.
+
+### STEP 6 — DEPLOY.md GATE
+
+| State | Action |
+|-------|--------|
+| `DEPLOY_COMPLEXITY == NONE` | Skip. Don't propose DEPLOY.md. |
+| `DEPLOY_COMPLEXITY == TRIVIAL` AND no DEPLOY.md | Skip. Suggest one-paragraph "Deploy" section in README. HUMAN. |
+| `DEPLOY_COMPLEXITY == TRIVIAL` AND DEPLOY.md exists | Suggest deletion or inlining into README. HUMAN. |
+| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND no DEPLOY.md | Propose creation. HUMAN. Template based on detected artifacts (Docker → image build + run + env; fly.toml → `fly deploy` + secrets; workflows → branch trigger + manual approval; k8s → kubectl apply + namespace + rollout). |
+| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND DEPLOY.md exists | Apply standard drift detection (STEP 3-4). |
+
+### STEP 7 — REPORT
 
 ```
 DOC SYNC REPORT
 ===============
 
+PROJECT STACK   : <detected stack>
+DEPLOY          : <NONE | TRIVIAL | NON_TRIVIAL — evidence>
+DOCS PRESENT    : <count> — <list>
+DOCS MISSING    : <list of canonical names not present>
+
 ## <filename>
 Last updated: <date> (<N commits since>)
 
@@ -161,53 +293,64 @@ Last updated: <date> (<N commits since>)
 
 ---
 (repeat for each doc with drift)
+
+## CREATE PROPOSALS
+- [HUMAN] README.md — bootstrap (template above)
+- [HUMAN] DEPLOY.md — non-trivial deploy (Docker + fly.toml)
+- ...
+
+## REMOVE / INLINE PROPOSALS
+- [HUMAN] DEPLOY.md — trivial deploy, inline into README instead
+- ...
 ```
 
-Tagging rules:
+**Tagging rules:**
 - **AUTO** — factual update Claude can write: command changed,
-  var renamed, param added, version bumped, file moved,
-  dead reference removed, new entry point added to a list.
-- **HUMAN** — needs business context or judgment: feature
-  description wording, architecture rationale, changelog entry
-  content, new section creation, deprecation notices.
-
-Feature delta tags:
-- **[ADDED]** — feature exists in code but not in docs.
-  AUTO if it's a list entry (add name + one-line description).
-  HUMAN if it needs a new section or paragraph.
-- **[REMOVED]** — feature documented but no longer in code.
-  AUTO if it's a list entry to delete.
-  HUMAN if it needs a deprecation note or migration guidance.
-
-CHANGELOG entries are always tagged HUMAN — version bump and
-release notes are human decisions.
-
-If no drift detected in any doc: print
+  var renamed, param added, version bumped, file moved, dead
+  reference removed, new entry point added to a list, new link
+  added to existing doc.
+- **HUMAN** — needs business context: feature wording,
+  architecture rationale, changelog entry content, new section
+  creation, deprecation notes, README/DEPLOY bootstrap content,
+  decisions.md ↔ code reconciliation.
+
+**Feature delta tags:**
+- `[ADDED]` — feature in code, not in docs. AUTO for list entry
+  with obvious wording, HUMAN if needs new section.
+- `[REMOVED]` — feature in docs, not in code. AUTO for list entry
+  to delete, HUMAN if needs deprecation note.
+
+CHANGELOG entries always HUMAN. README/DEPLOY creation always
+HUMAN.
+
+If no drift in any doc and no missing required doc:
 `DOC SYNC: all docs current` and stop.
 
-### STEP 5 — VALIDATION GATE (mandatory stop)
+### STEP 8 — VALIDATION GATE (mandatory stop)
 
 ```
 DOC SYNC — VALIDATION GATE
-AUTO items : <count> (Claude will patch these)
-HUMAN items: <count> (listed above for your review)
+AUTO items   : <count> (Claude will patch these)
+HUMAN items  : <count> (listed above for review)
+CREATE items : <count> (README/DEPLOY proposals)
+REMOVE items : <count>
 
-Apply AUTO patches? (yes / select items / cancel)
+Apply AUTO patches?      (yes / select items / cancel)
+Apply HUMAN/CREATE items? (per-item: yes / no / edit)
 ```
 
 Wait for explicit approval. Do not proceed without it.
 
-### STEP 6 — PATCH
-
-Apply only approved AUTO items:
-- Surgical edits only. Preserve existing structure and tone.
-- For each edit, use the Edit tool with minimal old_string/new_string.
-- Do not rewrite surrounding prose. Do not reformat.
-- If a doc section doesn't exist yet for a change, propose creating
-  it but do NOT auto-write. Tag as HUMAN and surface to user.
+### STEP 9 — PATCH
 
-After patching, re-read each modified file to verify no broken
-markdown, no orphaned references.
+Apply only approved items:
+- Surgical Edit for AUTO items. Preserve structure and tone.
+- Write for approved CREATE items (README, DEPLOY). Use real
+  project data only — no `<TODO>` placeholders, no fabricated
+  feature descriptions.
+- For removals, prefer Edit (delete dead lines) over Write.
+- Re-read each modified file post-edit to verify no broken
+  markdown, no orphaned references.
 
 ### OUTPUT
 
@@ -215,6 +358,8 @@ markdown, no orphaned references.
 DOC SYNC COMPLETE
 DOCS CHECKED : <count>
 AUTO PATCHED : <count> items across <count> files
+CREATED      : <count> files
+REMOVED      : <count> files
 HUMAN PENDING: <count> items (see report above)
 SKIPPED      : <count> (user declined)
 ```
@@ -228,43 +373,48 @@ Input format: `auto-mode scope: <file1> <file2> ...`
 
 ### STEP A1 — PARSE SCOPE
 
-Extract the file list from `$ARGUMENTS`.
-These are files modified during the current session.
+Extract file list from `$ARGUMENTS`. These are files modified
+during the current session.
 
 ### STEP A2 — IDENTIFY RELEVANT DOCS
 
-For each modified file, determine which docs might reference it:
+Map modified files to relevant docs:
 - Code files → README (examples, feature list), USAGE, docs/
-- Config files → INSTALL, CONFIGURE, README (setup section)
-- Package manifest → README (prerequisites, install), INSTALL
-- Dockerfile/compose → README (Docker section), INSTALL
-- CLAUDE.md changes → skip (CLAUDE.md is self-documenting)
+- Config files → INSTALL, CONFIGURE, README setup section
+- Package manifest → README (prereqs, install), INSTALL
+- Dockerfile/compose → README Docker section, INSTALL, DEPLOY
+- Deploy artifacts (fly.toml, workflows, k8s manifests, etc.)
+  → DEPLOY (or trigger STEP 6 gate if no DEPLOY.md), README
+- CLAUDE.md change → skip (self-documenting)
+- `.claude/memory/decisions.md` change with architectural impact
+  → CLAUDE.md, README
 
-If no relevant docs exist for the changed files → exit silently.
+If no relevant docs exist for changed files → exit silently.
 
 ### STEP A3 — QUICK DRIFT CHECK
 
-For each relevant doc, read it and check only the sections that
-could be affected by the scoped changes. No full git scan —
-compare the doc content directly against the current state of
-the modified files.
+For each relevant doc, read it and check only sections affected
+by scoped changes. No full git scan — compare doc content directly
+against current state of modified files.
 
-Also check for feature deltas in the scoped files:
-- New files added → is the feature/module documented?
-- Files deleted → are there doc references to remove?
-- New exports, routes, commands → listed in relevant docs?
+Feature deltas in scoped files:
+- New files added → feature/module documented?
+- Files deleted → doc references to remove?
+- New exports/routes/commands → listed in relevant docs?
 
-Categorize findings:
-- **NONE** — no drift detected
+Categorize:
+- **NONE** — no drift detected.
 - **MINOR** — factual correction (command, param, path, version),
-  dead reference to remove, new list entry to add
+  dead reference removal, new list entry add.
 - **SIGNIFICANT** — new feature undocumented, section outdated,
-  breaking change not reflected, feature removed without doc update
+  breaking change not reflected, feature removed without doc
+  update, new deploy artifact (Dockerfile, fly.toml, workflow)
+  without DEPLOY.md update or creation.
 
 ### STEP A4 — ACT
 
-- **NONE** → exit completely silent. No output at all.
-- **MINOR** → patch silently. Print one-line confirmation:
+- **NONE** → exit completely silent. No output.
+- **MINOR** → patch silently. One-line confirmation:
   `doc-sync: patched <file> (<what changed>)`
 - **SIGNIFICANT** → surface to user before patching:
   ```
@@ -278,11 +428,20 @@ Categorize findings:
 
 ## RULES
 - Never invent content. Only sync what changed in code.
-- Never fabricate examples, feature descriptions, or explanations.
-- If a doc section doesn't exist yet, propose creating it but
-  don't auto-write (tag HUMAN).
+- Never fabricate examples, feature descriptions, explanations.
+- Doc creation (README, DEPLOY) requires HUMAN approval and uses
+  real project data only.
+- Doc list is dynamic — auto-detect, never assume fixed set.
+- DEPLOY.md only when `DEPLOY_COMPLEXITY == NON_TRIVIAL`. Trivial
+  deploy belongs in README.
+- README always required. Bootstrap if missing.
 - CHANGELOG entries: always propose, never auto-write.
 - Inline comment updates: only for files in scope, only when
   signature actually changed.
-- Preserve existing doc structure, formatting, and tone.
-- Keep patches minimal — change what's wrong, nothing else.
+- `.claude/memory/journal.md` and `evals.md` are append-only
+  logs — never edit.
+- `.claude/memory/decisions.md` / `learnings.md` / `blockers.md`
+  are user-curated registries — surface drift, don't auto-edit
+  (HUMAN only).
+- Preserve existing structure, formatting, tone.
+- Patches minimal — change what's wrong, nothing else.

skills/doc/SKILL.md

@@ -1,15 +1,21 @@
 ---
 name: doc
 description: |
-  Full documentation audit and sync. Detects stale docs by cross-referencing
-  git history against README, CLAUDE.md, INSTALL.md, CONFIGURE.md, USAGE.md,
-  CONTRIBUTING.md, CHANGELOG.md, docs/**/*.md, and inline comments (JSDoc,
-  docstrings, rustdoc, godoc). Reports drift with commit refs, proposes fixes,
-  patches approved items. Detects added features missing from docs and removed
-  features still documented (feature delta detection).
+  Full documentation audit and sync. Auto-detects what doc files the project
+  actually has — root docs (README, CLAUDE.md, INSTALL.md, CONFIGURE.md,
+  USAGE.md, DEPLOY.md, CONTRIBUTING.md, CHANGELOG.md), docs/**/*.md, project-state
+  files in .claude/{tasks,audits,memory}/, and inline comments (JSDoc, docstrings,
+  rustdoc, godoc). Stack-aware: detects framework + deploy complexity, proposes
+  DEPLOY.md only when non-trivial (Docker, fly.toml, k8s, multi-stage CI), skips
+  for trivial deploys (FTP push, single scp, plain static). Enforces README
+  presence with typical GitHub layout (title, quick start, links to existing
+  sub-docs). Cross-references git history for drift; detects added features
+  missing from docs and removed features still documented (feature delta
+  detection). Reports drift with commit refs, proposes fixes, patches approved
+  items.
   Trigger: "doc", "sync docs", "audit docs", "update readme", "check documentation",
   "are docs up to date", "documentation drift", "stale docs", "new feature not documented",
-  "removed feature still in docs".
+  "removed feature still in docs", "create README", "should I have a DEPLOY doc".
   Replaces the old /readme skill with broader scope.
 argument-hint: [leave empty for full audit, or list specific files/docs to check]
 disable-model-invocation: false