Add /update-docs skill for keeping docs in sync with code

Watermark-based skill that detects code changes since the last run,
maps them to affected doc pages via a code-to-doc mapping table, and
makes surgical edits. Watermark file created on first run.

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

.claude/skills/docs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: update-docs
+description: Update documentation in docs/ based on recent code changes. Reads git history since a watermark commit, maps changed files to doc pages, and makes surgical edits to keep docs in sync with code.
+---
+
+# Update Docs
+
+Detect code changes since the last run and update affected documentation pages.
+
+- [references/mapping.md](references/mapping.md) — code-to-doc page mapping
+- Follow `docs/CONTRIBUTING.md` and `docs/AGENTS.md` for writing style
+
+## Workflow
+
+### 1. Read watermark
+
+Read `.claude/skills/docs/watermark` for the last processed commit SHA. If the file is missing (first run), use the commit from 30 days ago as the starting point: `git log --before="30 days ago" --format=%H -1 main`.
+
+### 2. Gather changes
+
+Run `git log --oneline --no-merges --name-only <watermark>..HEAD` to get changed files and commit messages since the watermark.
+
+### 3. Map changes to doc pages
+
+Cross-reference changed files against the code-to-doc mapping in `references/mapping.md`. Also use judgment for unmapped files (e.g., new crates or modules that clearly affect user-facing behavior).
+
+Filter to user-facing behavioral changes only:
+- New features, flags, commands, config options, node types
+- Changed behavior, renamed APIs, new integrations
+- Bug fixes that affect documented behavior
+
+Skip:
+- Internal refactors with no behavior change
+- Test-only changes
+- CI/CD pipeline changes
+- Dependency bumps
+- Code style or linting changes
+
+If nothing affects docs, tell the user and stop.
+
+### 4. Read code and docs
+
+For each affected doc page: read the current MDX file and the relevant source files. Identify sections that are outdated, missing, or incorrect.
+
+### 5. Update doc pages
+
+Surgical edits only — change only affected sections. Preserve existing voice, structure, heading hierarchy, and Mintlify component usage.
+
+- Add code examples for new features (CLI commands, config snippets, DOT syntax)
+- Insert rows into reference tables in logical position
+- Add new sections for entirely new capabilities
+- Update existing descriptions when behavior changes
+- Never edit `docs/api-reference/arc-api.yaml` — that is the API workflow's source of truth
+
+### 6. Validate DOT examples
+
+If any updated page contains ` ```dot ` code blocks with `digraph` definitions, run `./test/docs/run_tests.sh validate`. Fix any failures before proceeding.
+
+### 7. Write watermark
+
+Write the output of `git rev-parse HEAD` to `.claude/skills/docs/watermark`.
+
+### 8. Summarize
+
+List updated doc pages and what changed in each.

.claude/skills/docs/references/mapping.md

@@ -0,0 +1,38 @@
+# Code-to-Doc Mapping
+
+Which source files affect which doc pages. Use this as guidance — also apply judgment for unmapped files that clearly affect user-facing behavior.
+
+| Source | Docs |
+|--------|------|
+| `crates/arc-cli/src/main.rs`, `crates/arc-workflows/src/cli/mod.rs`, `crates/arc-workflows/src/cli/run.rs` | `docs/reference/cli.mdx` |
+| `crates/arc-cli/src/cli_config.rs` | `docs/reference/cli-configuration.mdx` |
+| `crates/arc-llm/src/cli.rs` | `docs/reference/cli.mdx` |
+| `crates/arc-api/src/serve.rs` | `docs/reference/cli.mdx` |
+| `crates/arc-workflows/src/parser/*.rs` | `docs/reference/dot-language.mdx` |
+| `crates/arc-workflows/src/condition.rs` | `docs/reference/dot-language.mdx` |
+| `crates/arc-workflows/src/cli/validate.rs` | `docs/reference/dot-language.mdx` |
+| `crates/arc-workflows/src/stylesheet.rs` | `docs/workflows/stylesheets.mdx` |
+| `crates/arc-workflows/src/transform.rs` | `docs/workflows/variables.mdx` |
+| `crates/arc-workflows/src/handler/*.rs` | `docs/workflows/stages-and-nodes.mdx`, `docs/reference/dot-language.mdx` |
+| `crates/arc-workflows/src/handler/human.rs` | `docs/workflows/human-in-the-loop.mdx` |
+| `crates/arc-workflows/src/cli/run_config.rs` | `docs/execution/run-configuration.mdx` |
+| `crates/arc-workflows/src/engine.rs` | `docs/core-concepts/how-arc-works.mdx` |
+| `crates/arc-workflows/src/context/*.rs` | `docs/execution/context.mdx` |
+| `crates/arc-workflows/src/checkpoint.rs` | `docs/execution/checkpoints.mdx` |
+| `crates/arc-workflows/src/retro.rs`, `crates/arc-workflows/src/retro_agent.rs` | `docs/execution/retros.mdx` |
+| `crates/arc-workflows/src/interviewer/*.rs` | `docs/execution/interviews.mdx` |
+| `crates/arc-workflows/src/hook/*.rs` | `docs/agents/hooks.mdx` |
+| `crates/arc-workflows/src/daytona_sandbox.rs` | `docs/integrations/daytona.mdx`, `docs/execution/environments.mdx` |
+| `crates/arc-agent/src/tools.rs`, `crates/arc-agent/src/tool_registry.rs`, `crates/arc-agent/src/tool_execution.rs` | `docs/agents/tools.mdx` |
+| `crates/arc-agent/src/v4a_patch.rs` | `docs/agents/tools.mdx` |
+| `crates/arc-agent/src/cli.rs` | `docs/agents/permissions.mdx` |
+| `crates/arc-agent/src/subagent.rs` | `docs/agents/subagents.mdx` |
+| `crates/arc-agent/src/mcp_integration.rs` | `docs/agents/mcp.mdx` |
+| `crates/arc-llm/src/catalog.rs`, `crates/arc-llm/src/providers/*.rs` | `docs/core-concepts/models.mdx` |
+| `crates/arc-exe/src/*.rs` | `docs/integrations/exe-dev.mdx`, `docs/execution/environments.mdx` |
+| `crates/arc-devcontainer/src/*.rs` | `docs/execution/devcontainers.mdx` |
+| `crates/arc-slack/src/*.rs` | `docs/integrations/slack.mdx` |
+| `crates/arc-sprites/src/*.rs` | `docs/integrations/sprites.mdx` |
+| `crates/arc-mcp/src/*.rs` | `docs/agents/mcp.mdx` |
+| `crates/arc-api/src/*.rs` | `docs/api-reference/overview.mdx`, `docs/api-reference/demo-mode.mdx` |
+| `crates/arc-api/src/server_config.rs` | `docs/administration/server-configuration.mdx` |