Correct /han-update-documentation for five-plugin layout, and update all docs

.claude/skills/han-update-documentation/SKILL.md

@@ -20,9 +20,9 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(git *), Bash(find *)
 ## Pre-requisites
 
 - git: !`which git`
-- repo root marker: !`find . -maxdepth 2 -name "plugin.json" -path "*/.claude-plugin/*" -type f`
-- skills directory: !`find . -maxdepth 2 -type d -name "skills" -path "*/plugin/*"`
-- agents directory: !`find . -maxdepth 2 -type d -name "agents" -path "*/plugin/*"`
+- repo root marker: !`find . -maxdepth 3 -name "plugin.json" -path "*/.claude-plugin/*" -type f`
+- skills directories: !`find han.core han.github han.reporting han.feedback -maxdepth 1 -type d -name skills 2>/dev/null`
+- agents directory: !`find han.core -maxdepth 1 -type d -name agents 2>/dev/null`
 
 **If any of the above are empty:** 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.
 
@@ -39,7 +39,7 @@ Run `${CLAUDE_SKILL_DIR}/scripts/detect-doc-update-context.sh` and read its outp
 
 **`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 in the plugin.
+**`mode: sweep`** — full sweep. Set `MODE = sweep`. The skill audits every documentation entity across the plugin suite (`han.core`, `han.github`, `han.reporting`, `han.feedback`).
 
 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.
 
@@ -61,12 +61,22 @@ Deduplicate. Produce a single ordered inventory `INV`:
 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 four of them; agents live in only one. Long-form docs stay flat under `docs/skills/` and `docs/agents/` no matter which plugin owns the entity.
+
+- **Skill roots:** `han.core/skills`, `han.github/skills`, `han.reporting/skills`, `han.feedback/skills`.
+- **Agent root:** `han.core/agents` (the only plugin with agents).
+- **Plugin manifests:** `{plugin}/.claude-plugin/plugin.json` for each of `han`, `han.core`, `han.github`, `han.reporting`, `han.feedback`. Owned by `/han-release`; out of scope here.
+
+Throughout this skill, `{plugin}` means whichever of the four skill roots a given skill came from.
+
 ### When `MODE = sweep`
 
 Enumerate the full set:
 
-1. **Every skill.** `find plugin/skills -mindepth 1 -maxdepth 1 -type d` for the inventory; each entry pulls in `plugin/skills/{name}/SKILL.md` and `docs/skills/{name}.md`.
-2. **Every agent.** `find plugin/agents -mindepth 1 -maxdepth 1 -name "*.md" -type f` for the inventory; each entry pulls in `plugin/agents/{name}.md` and `docs/agents/{name}.md`.
+1. **Every skill.** `find han.core/skills han.github/skills han.reporting/skills han.feedback/skills -mindepth 1 -maxdepth 1 -type d` for the inventory; each entry pulls in `{plugin}/skills/{name}/SKILL.md` (the root the directory came from) and `docs/skills/{name}.md`.
+2. **Every agent.** `find han.core/agents -mindepth 1 -maxdepth 1 -name "*.md" -type f` for the inventory; each entry pulls in `han.core/agents/{name}.md` and `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 `docs/guidance/`.
@@ -89,7 +99,7 @@ Walk `INV` in order. For each entity, apply every rule in [references/audit-chec
   - Fix: {concrete edit}
 ```
 
-**Read the source of truth before checking the doc.** For a skill, read `plugin/skills/{name}/SKILL.md` first, then read `docs/skills/{name}.md` and check it against the source. For an agent, read `plugin/agents/{name}.md` first, then `docs/agents/{name}.md`. Doc-vs-source contradictions are functional bugs — treat them with the same severity as broken scripts (see `docs/guidance/skill-building-guidance/documentation-maintenance.md`).
+**Read the source of truth before checking the doc.** For a skill, read `{plugin}/skills/{name}/SKILL.md` first (the plugin root the skill came from), then read `docs/skills/{name}.md` and check it against the source. For an agent, read `han.core/agents/{name}.md` first, then `docs/agents/{name}.md`. Doc-vs-source contradictions are functional bugs — treat them with the same severity as broken scripts (see `docs/guidance/skill-building-guidance/documentation-maintenance.md`).
 
 **Batch agent audits when the inventory is large.** When `INV` has more than ten skills or ten agents to audit, dispatch a `content-auditor` agent per batch of five entities with the entity name, the source-of-truth file, and the long-form doc. Hand each agent the relevant section of [references/audit-checklist.md](references/audit-checklist.md) inline (do not tell it to read the file). The agent returns findings; merge them into the working list. Do not run more than four such agents in parallel.
 
@@ -101,7 +111,7 @@ After Step 3, look across entities, not just within them.
 
 1. **Bidirectional skill boundaries.** For every skill in `INV` whose frontmatter or long-form "Do not invoke for" section names a sibling, verify the sibling names this skill in the reverse direction. Asymmetric boundaries are findings.
 2. **Bidirectional pairings.** For every skill or agent in `INV` whose long-form Related documentation names another, verify the other side links back where the link adds value. One-direction pairings without a reason are findings.
-3. **Indexes are consistent with reality.** Use Grep to confirm every skill in `plugin/skills/` appears in `docs/skills/README.md` exactly once, and every agent in `plugin/agents/` appears in `docs/agents/README.md` exactly once. Stray entries pointing at non-existent files are findings.
+3. **Indexes are consistent with reality.** Use Grep to confirm every skill across the four skill roots (`han.core/skills`, `han.github/skills`, `han.reporting/skills`, `han.feedback/skills`) appears in `docs/skills/README.md` exactly once, and every agent in `han.core/agents/` appears in `docs/agents/README.md` exactly once. Stray entries pointing at non-existent files are findings.
 4. **CLAUDE.md catalog completeness.** Every entity in `INV` (skills and agents) has a one-line entry in the CLAUDE.md doc map. Missing entries are findings.
 5. **Count-free references.** Confirm `README.md`, `CLAUDE.md` (the "Indexes stay complete, not counted" line), and `docs/concepts.md` describe the skills and agents without a hardcoded total. A reintroduced count (for example "21 skills" or "23 agents") is a finding. Sweep mode always runs this check; branch mode runs it only if the branch added or removed skills or agents.
 6. **The `## How skills compose` block in `docs/skills/README.md`** references current skill names only. References to renamed or removed skills are findings.

.claude/skills/han-update-documentation/references/audit-checklist.md

@@ -2,11 +2,13 @@
 
 Verification rules applied to every entity in scope. The skill's mode (branch vs. sweep) determines *which* entities are in scope. This checklist determines *what* is checked for each one. Apply every rule that fits the entity's type. Record each finding with the file path and a concrete fix; do not paper over discrepancies.
 
-## Skills (`plugin/skills/{name}/SKILL.md` + `docs/skills/{name}.md`)
+`{plugin}` below means the skill root the skill came from: one of `han.core`, `han.github`, `han.reporting`, `han.feedback`. Agents live only under `han.core`.
 
-### Skill definition (`plugin/skills/{name}/SKILL.md`)
+## Skills (`{plugin}/skills/{name}/SKILL.md` + `docs/skills/{name}.md`)
 
-1. **Frontmatter `name` matches directory name.** `name: foo-bar` requires `plugin/skills/foo-bar/`.
+### Skill definition (`{plugin}/skills/{name}/SKILL.md`)
+
+1. **Frontmatter `name` matches directory name.** `name: foo-bar` requires `{plugin}/skills/foo-bar/`.
 2. **Frontmatter `description` is current.** Reflects what the steps actually do. If steps changed and the description still names a removed step or omits a new one, update the description.
 3. **`allowed-tools` matches actual usage.** Every tool the steps call is listed; tools no longer used are removed. Each Bash command prefix is a separate `Bash()` entry.
 4. **Referenced scripts exist.** Every `${CLAUDE_SKILL_DIR}/scripts/...` path resolves to a real file under the skill's `scripts/`.
@@ -15,8 +17,8 @@ Verification rules applied to every entity in scope. The skill's mode (branch vs
 
 ### Long-form doc (`docs/skills/{name}.md`)
 
-1. **Long-form doc exists.** Every skill in `plugin/skills/` has a matching long-form doc. Missing doc is a hard finding — create it from `docs/templates/skill-long-form-template.md` rather than leaving the gap.
-2. **Orientation frame intact.** First line is `# /{name}`; the second paragraph names the audience and links to `plugin/skills/{name}/SKILL.md`. The `> See also:` orientation line is present.
+1. **Long-form doc exists.** Every skill across the four skill roots has a matching long-form doc. Missing doc is a hard finding — create it from `docs/templates/skill-long-form-template.md` rather than leaving the gap.
+2. **Orientation frame intact.** First line is `# /{name}`; the second paragraph names the audience and links to `{plugin}/skills/{name}/SKILL.md`. The `> See also:` orientation line is present.
 3. **TL;DR present.** Three lines: what / when / what-you-get-back. Each one sentence.
 4. **Sections follow the template.** Key concepts, When to use it, How to invoke it, What you get back, How to get the most out of it, YAGNI (when applicable), Cost and latency, In more detail (optional), Sources, Related documentation.
 5. **TL;DR matches the skill's frontmatter description.** A reader who reads the SKILL.md frontmatter and the long-form TL;DR must come away with the same understanding. Mismatches are a finding.
@@ -37,9 +39,9 @@ Verification rules applied to every entity in scope. The skill's mode (branch vs
 6. **Bidirectional Related documentation links.** If `/foo` pairs with `/bar`, both long-form docs name the pairing.
 7. **README.md skill references stay count-free.** The Skills Index links resolve and the surrounding text names no hardcoded skill count.
 
-## Agents (`plugin/agents/{name}.md` + `docs/agents/{name}.md`)
+## Agents (`han.core/agents/{name}.md` + `docs/agents/{name}.md`)
 
-### Agent definition (`plugin/agents/{name}.md`)
+### Agent definition (`han.core/agents/{name}.md`)
 
 1. **Frontmatter `name` matches the file's basename.**
 2. **Frontmatter `description` is current.** Reflects what the agent does, when to dispatch it, and what it does not do. Boundary statements name the right sibling agents.
@@ -49,7 +51,7 @@ Verification rules applied to every entity in scope. The skill's mode (branch vs
 
 ### Long-form doc (`docs/agents/{name}.md`)
 
-1. **Long-form doc exists** for every agent in `plugin/agents/`. Missing doc is a hard finding — create it from `docs/templates/agent-long-form-template.md`.
+1. **Long-form doc exists** for every agent in `han.core/agents/`. Missing doc is a hard finding — create it from `docs/templates/agent-long-form-template.md`.
 2. **Orientation frame, TL;DR, and template sections present** per `docs/templates/agent-long-form-template.md`.
 3. **"Dispatched by" or equivalent section names every skill that uses this agent.** When a skill's dispatch list changed, this section updates.
 4. **TL;DR matches the agent's frontmatter description.**
@@ -74,7 +76,7 @@ Verification rules applied to every entity in scope. The skill's mode (branch vs
 
 ## Indexes (`docs/skills/README.md`, `docs/agents/README.md`)
 
-1. **Every skill / agent in `plugin/` appears in the index** under exactly one group.
+1. **Every skill (across the four skill roots) and every agent (in `han.core/agents`) appears in the index** under exactly one group.
 2. **No index entry points at a non-existent file.**
 3. **Group headings still describe their groups accurately.** When a category was renamed or merged, the heading updates.
 4. **Each entry's scent line is current.**

.claude/skills/han-update-documentation/references/scope-mapping.md

@@ -4,14 +4,16 @@ Maps a changed file path to the documentation entities that must be reviewed for
 
 A single changed file can pull multiple entities into scope. Always add every entity the path touches.
 
+`{plugin}` below means any of the four skill roots: `han.core`, `han.github`, `han.reporting`, `han.feedback`. Agents live only under `han.core`.
+
 ## Mapping table
 
 | Path pattern | Entities pulled into scope |
 |--------------|----------------------------|
-| `plugin/skills/{name}/SKILL.md` | skill `{name}` |
-| `plugin/skills/{name}/references/**` | skill `{name}` |
-| `plugin/skills/{name}/scripts/**` | skill `{name}` |
-| `plugin/agents/{name}.md` | agent `{name}` |
+| `{plugin}/skills/{name}/SKILL.md` | skill `{name}` |
+| `{plugin}/skills/{name}/references/**` | skill `{name}` |
+| `{plugin}/skills/{name}/scripts/**` | skill `{name}` |
+| `han.core/agents/{name}.md` | agent `{name}` |
 | `docs/skills/{name}.md` | skill `{name}` |
 | `docs/skills/README.md` | skills-index |
 | `docs/agents/{name}.md` | agent `{name}` |
@@ -27,7 +29,7 @@ A single changed file can pull multiple entities into scope. Always add every en
 | `CONTRIBUTING.md` | contributing |
 | `CLAUDE.md` | claude-md |
 | `CHANGELOG.md` | ignore (out of scope for this skill) |
-| `plugin/.claude-plugin/plugin.json` | ignore (versioning belongs to /han-release) |
+| `{plugin}/.claude-plugin/plugin.json` | ignore (versioning belongs to /han-release) |
 | `.claude-plugin/marketplace.json` | ignore (versioning belongs to /han-release) |
 | `.claude/skills/**` | ignore (repo-local maintenance skills, no plugin docs) |
 | anything else | ignore |
@@ -36,9 +38,9 @@ A single changed file can pull multiple entities into scope. Always add every en
 
 Some path changes drag additional entities into scope even when those entities' own files were not edited.
 
-- **A new skill added** under `plugin/skills/{name}/`: also audit `docs/skills/README.md` (must list it), `CLAUDE.md` (catalog entry), `README.md`, `docs/concepts.md` (all must reference it without a hardcoded count).
-- **A skill removed or renamed** under `plugin/skills/`: same as added, plus every other skill or agent doc whose Related Documentation section linked to the old name.
-- **A new agent added** under `plugin/agents/`: also audit `docs/agents/README.md`, `CLAUDE.md` (catalog entry), `README.md` (must reference it without a hardcoded count).
+- **A new skill added** under `{plugin}/skills/{name}/`: also audit `docs/skills/README.md` (must list it), `CLAUDE.md` (catalog entry), `README.md`, `docs/concepts.md` (all must reference it without a hardcoded count).
+- **A skill removed or renamed** under `{plugin}/skills/`: same as added, plus every other skill or agent doc whose Related Documentation section linked to the old name.
+- **A new agent added** under `han.core/agents/`: also audit `docs/agents/README.md`, `CLAUDE.md` (catalog entry), `README.md` (must reference it without a hardcoded count).
 - **An agent removed or renamed**: same as added, plus every skill doc that mentions dispatching the agent.
 - **A skill description (frontmatter) changed**: also audit `docs/skills/README.md` scent line, the skill's long-form `docs/skills/{name}.md` TL;DR, and the `CLAUDE.md` catalog entry. Sibling skills named in the boundary may need their reverse-boundary statement checked.
 - **An agent description (frontmatter) changed**: also audit `docs/agents/README.md` scent line, the agent's long-form `docs/agents/{name}.md` TL;DR.
@@ -49,7 +51,7 @@ Some path changes drag additional entities into scope even when those entities'
 These changes do not pull anything into the documentation update scope. They have their own owners.
 
 - `CHANGELOG.md` — owned by `/han-release`.
-- `plugin/.claude-plugin/plugin.json` `version` field — owned by `/han-release`.
+- `{plugin}/.claude-plugin/plugin.json` `version` field (any of the five plugins) — owned by `/han-release`.
 - `.claude-plugin/marketplace.json` `version` field — owned by `/han-release`.
 - `.claude/**` repo-local config and skills — not part of the plugin's user-facing surface.
 - `images/**`, binary assets.

docs/agents/structural-analyst.md

@@ -7,7 +7,7 @@ Operator documentation for the `structural-analyst` agent in the han plugin. Thi
 ## TL;DR
 
 - **What it does.** Analyzes the static structure of a specified codebase focus area: module boundaries, coupling, dependency direction, abstractions, and duplication. Produces numbered structural findings with file paths and verbatim code.
-- **When to dispatch it.** You want a principled static-structure pass on a module or focus area, independent of runtime behavior or risk assessment. Always dispatched by `/architectural-analysis`. Conditionally dispatched by `/code-review`.
+- **When to dispatch it.** You want a principled static-structure pass on a module or focus area, independent of runtime behavior or risk assessment. Always dispatched by `/architectural-analysis`. Conditionally dispatched by `/code-review`, and by `/iterative-plan-review` and `/plan-implementation` when the plan or review covers module boundaries, coupling, or dependency direction.
 - **What you get back.** Numbered `S#` findings, each tied to a structural dimension (Boundaries / Coupling / Dependency Direction / Abstraction / Duplication), file paths, verbatim code, and an impact statement.
 
 ## Key concepts