han-update-documentation

## Pre-requisites

- git: !`which git 2>/dev/null || echo "not installed"`
- repo root marker: !`find . -maxdepth 3 -name "plugin.json" -path "*/.claude-plugin/*" -type f`
- skill roots:
  !`find . -maxdepth 2 -type d -name skills -path './han-*/skills' ! -path './han-plugin-builder/skills' 2>/dev/null | sed 's|^\./||' | sort`
- agents directory:
  !`find . -maxdepth 2 -type d -name agents -path './han-*/agents' 2>/dev/null | sed 's|^\./||' | sort`

**If any of the above are empty or read `not installed`:** this skill is intended to run inside the Han plugin
repository. Tell the operator which marker is missing and stop. Do not attempt to operate on a different repo.

## Project Context

- current branch: !`git branch --show-current 2>/dev/null || echo unknown`
- default branch: !`git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo unknown`

## Step 1: Detect mode and scope

Run `${CLAUDE_SKILL_DIR}/scripts/detect-doc-update-context.sh` and read its output. Branch on the `mode:` line.

The script also emits the **skill roots** (between `skill-roots-start` and `skill-roots-end`) and the **agent root**
(the `agent-root:` line), both discovered dynamically from disk. These are the authoritative roots for the rest of this
skill — use them wherever the steps below say "the skill roots" or "the agent root," rather than any hardcoded plugin
list. A skill root is every `han-*/skills` directory except `han-plugin-builder/skills`, whose `guidance` skill is
authoring guidance audited under guidance docs (Step 2, sweep), not a documented product skill. Adding a new product
plugin needs no edit to this skill; it shows up in the discovered roots automatically.

**`mode: error`** — stop. Surface the `reason:` line to the operator. Do not proceed.

**`mode: branch`** — branch scope. Set `MODE = branch`. Read the file list between `changed-files-start` and
`changed-files-end` (or note that the file list is empty if `changed-files: none` appears instead). If the file list is
empty, inform the operator that the branch has no changes against the default branch and stop.

**`mode: sweep`** — full sweep. Set `MODE = sweep`. The skill audits every documentation entity across the plugin suite
(every skill root the detect script reported, plus the agent root).

Echo back the mode and the count of in-scope files (branch mode) or "full plugin sweep" (sweep mode) so the operator
knows what is about to happen.

## Step 2: Build the entity inventory

The mode determines _which_ entities to audit. Always build a deduplicated list of entities before reading anything
else, so Step 3 has a fixed plan.

### When `MODE = branch`

Map each changed file to its entities using [references/scope-mapping.md](./references/scope-mapping.md). A single file
can pull multiple entities into scope (a changed skill SKILL.md pulls the skill plus, if the description changed, the
index and CLAUDE.md catalog). Then apply the **implicit dependencies** section of the mapping reference: skill or agent
additions and removals pull the indexes, CLAUDE.md, README, and `docs/concepts.md` into scope; sibling-boundary changes
pull the named sibling into scope.

Deduplicate. Produce a single ordered inventory `INV`:

1. Skills, alphabetical.
2. Agents, alphabetical.
3. Indexes (`docs/skills/README.md`, `docs/agents/README.md`).
4. Top-level concept docs (`docs/concepts.md`, `docs/quickstart.md`, `docs/sizing.md`, `docs/yagni.md`).
5. Guidance docs (specific files only).
6. Templates (specific files only).
7. Root files (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`).

### Plugin roots

Han ships as several plugins. Skills are spread across several of them; agents live in `han-core` and, for the
readability-editor, `han-communication`. Long-form docs now live inside the plugin they describe, at
`{plugin}/docs/skills/{name}.md` and `{plugin}/docs/agents/{name}.md`, beside that plugin's `README.md`.

- **Skill roots:** the list the detect script reported between `skill-roots-start` and `skill-roots-end`. Every
  `han-*/skills` directory except `han-plugin-builder/skills` (its `guidance` skill is authoring guidance, audited under
  guidance docs below). Do not hardcode the plugins here; read them from the script so a newly added plugin is covered
  automatically.
- **Agent root:** the script's `agent-root:` line (`han-core/agents`). The readability-editor agent also lives in
  `han-communication/agents`; include it when auditing agents.
- **Plugin manifests:** `{plugin}/.claude-plugin/plugin.json` for every plugin. Owned by `/han-release`; out of scope
  here.

Throughout this skill, `{plugin}` means whichever discovered skill root a given skill came from.

### When `MODE = sweep`

Enumerate the full set:

1. **Every skill.** Run `find <skill roots> -mindepth 1 -maxdepth 1 -type d`, passing the skill roots the detect script
   reported, for the inventory; each entry pulls in `{plugin}/skills/{name}/SKILL.md` (the root the directory came from)
   and `{plugin}/docs/skills/{name}.md`.
2. **Every agent.** Run `find <agent root> -mindepth 1 -maxdepth 1 -name "*.md" -type f`, passing the script's
   `agent-root` (plus `han-communication/agents` for the readability-editor), for the inventory; each entry pulls in
   `{agent-root}/{name}.md` and `{plugin}/docs/agents/{name}.md`.
3. **Both indexes** (`docs/skills/README.md`, `docs/agents/README.md`).
4. **All top-level concept docs** in `docs/`.
5. **All guidance docs** under `han-plugin-builder/skills/guidance/references/`.
6. **All templates** under `docs/templates/`.
7. **Root files** (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`).

Sweep mode always audits that `README.md`, `CLAUDE.md`, and `docs/concepts.md` reference the skills and agents without a
hardcoded count, and that every entity found in this step appears in the indexes and the CLAUDE.md catalog.

### Out-of-scope files (both modes)

Treat as ignored: `CHANGELOG.md`, plugin and marketplace `version` fields, `.claude/**`, `LICENSE`, `i