diff --git a/.claude/skills/han-release/SKILL.md b/.claude/skills/han-release/SKILL.md
index 31763735..17cdb9c2 100644
--- a/.claude/skills/han-release/SKILL.md
+++ b/.claude/skills/han-release/SKILL.md
@@ -1,19 +1,13 @@
 ---
 name: han-release
 description: >
-  Cut a Han release: update CHANGELOG.md with the changes since the last release, bump every plugin that changed, tag
-  every plugin as {plugin-name}--v{version} so a version-constrained dependency can resolve, and publish a GitHub
-  release whose notes attribute every merged pull request to its author, credit every closed issue to the person who
-  opened it, the people who contributed to it, and the people who worked on the fix, and link back to the full changelog
-  for that version. Han ships as a parent meta-plugin (`han`) plus child plugins (`han-core`, `han-github`,
-  `han-reporting`, and any future `han-*` extension); the skill versions each plugin independently and tags each one
-  independently, with the release attaching to the parent's tag. Use when releasing, cutting a release, shipping a new
-  Han version, publishing release notes, or tagging a version. Reads each plugin's target version from its plugin.json;
-  when a plugin has not been bumped past the latest tag yet, it proposes a semantic-versioning bump and confirms the
-  whole plan before continuing. Always stops for approval before creating any tag, because a pushed tag is never moved.
-  Requires the gh CLI, jq, the claude CLI, and a clean git checkout. This is a repository-maintenance skill for the Han
-  repo itself, not a general review or PR skill — use code-review for local review, post-code-review-to-pr to post a PR
-  review, and update-pr-description for PR bodies.
+  Cut a Han release: update CHANGELOG.md with the changes since the last release, bump and tag every plugin that changed
+  as {plugin-name}--v{version} so a version-constrained dependency can resolve, and publish a GitHub release crediting
+  every merged pull request and closed issue to the people behind it. Use when releasing, cutting a release, shipping a
+  new Han version, publishing release notes, or tagging a version. Always stops for approval before creating any tag,
+  because a pushed tag is never moved. Requires the gh CLI, jq, the claude CLI, and a clean git checkout. This is a
+  repository-maintenance skill for the Han repo itself, not a general review or PR skill — use code-review for local
+  review, post-code-review-to-pr to post a PR review, and update-pr-description for PR bodies.
 argument-hint: "[pause before publishing] [draft] [optional release context]"
 allowed-tools:
   Read, Edit, Write, Glob, Grep, Agent, Bash(git *), Bash(gh *), Bash(jq *), Bash(which *), Bash(grep *), Bash(sed *),
@@ -92,7 +86,7 @@ first release and silently expand the changelog to the whole repository history.
   ```
 
   Do not read `prev#` as "the number without the leading `v`". That older rule returns the whole tag string for a
-  per-plugin tag, and `prev#` is the parent's baseline (see Step 3a), so a wrong value here silently corrupts the entire
+  per-plugin tag, and `prev#` is the parent's baseline (see 3a in `references/version-plan-rules.md`), so a wrong value here silently corrupts the entire
   version plan rather than failing.
 
 - Each plugin's source directory comes from the `source` field in `marketplace.json` (for example `./han-core`), so its
@@ -131,7 +125,7 @@ first release and silently expand the changelog to the whole repository history.
    yourself before applying the precedence above:
    `git tag -l '{parent plugin name}--v*' --sort=-v:refname | head -n1`.
 
-   `prev` feeds two different things: the commit range below, **and** the parent's baseline version in Step 3a via
+   `prev` feeds two different things: the commit range below, **and** the parent's baseline version at 3a in `references/version-plan-rules.md` via
    `prev#`. Parse `prev#` with the after-the-last-`v` rule in the vocabulary block, not by stripping a leading `v`.
 
 2. **Commit range.** With a previous tag: `${prev}..HEAD`. First release: the full history (`HEAD` with no range base).
@@ -154,42 +148,11 @@ first release and silently expand the changelog to the whole repository history.
 5. **No-PR fallback.** If `$pr_list` is empty (local-only or squash history with no PR refs), record the notable commit
    subjects from `git log {range} --oneline` instead, and use the commits form documented in both reference files.
 
-6. **Collect closed issues and their attribution.** For each merged PR `N` in `$pr_list`, find the issues that PR closed
-   and credit everyone involved. This relates each closed issue to the fix that resolved it.
-
-   - **Find the closed issues for the PR.** Take the issue numbers from
-     `gh pr view N --json closingIssuesReferences --jq '[.closingIssuesReferences[]?.number]'` (the GitHub-tracked
-     closing links). As a fallback for older PRs that linked via text, also scan the PR body and commit messages for
-     GitHub closing keywords: `gh pr view N --json body,commits --jq '[.body, (.commits[].messageBody)] | join("\n")'`
-     and extract `#<num>` that follow `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, or
-     `resolved` (case-insensitive). Union the two sets, dedupe.
-
-   - **Confirm each is a closed issue.** For each candidate number `I`, run
-     `gh issue view I --json number,title,author,state,comments` (suppress stderr; redirect `2>/dev/null`). Skip the
-     number if the command fails (it is a PR number, not an issue, or does not exist).
-
-   - **Gather attribution per issue.** Record:
-     - **opener** — `.author.login`, unless `.author.is_bot` is true.
-     - **issue contributors** (people who contributed meaningfully) — the people who left a **substantive** comment on
-       the issue. A reaction is not a comment (a 👍 or other emoji reaction never appears in `.comments[]`), so
-       reaction-only participants are already excluded. Drive-by comments do not count either. Pull each comment with
-       its author and body
-       (`gh issue view I --json comments --jq '.comments[] | select(.author.is_bot|not) | {login: .author.login, body: .body}'`,
-       stderr suppressed), and treat a comment as a drive-by when its trimmed body is emoji-only, or is a brief
-       acknowledgment or status ping (for example `+1`, `same`, `me too`, `bump`, `following`, `thanks`,
-       `any update(s)?`), or is shorter than roughly 15 words and adds no detail. A person qualifies only when at least
-       one of their comments is substantive (not a drive-by). Remove the opener and the PR workers so each person is
-       credited once. May be empty.
-     - **PR workers** — for the closing PR `N`, the union of the PR author, the review authors, and the commit authors:
-       `gh pr view N --json author,reviews,commits --jq '[.author.login] + [.reviews[]?.author.login] + [.commits[].authors[].login] | unique'`.
-       Drop bot accounts (`is_bot` where available, plus the `web-flow`, `github-actions`, and `dependabot` logins).
-
-   - **Build `$issue_list`.** One entry per closed issue: its number, title, opener, contributors, the closing PR
-     number(s), and the merged PR workers. If the same issue is closed by more than one PR in the range, record every
-     closing PR and merge their worker sets. Build the changelog bullets and release-body lines per
-     [references/changelog-rules.md](./references/changelog-rules.md) and
-     [references/release-notes-format.md](./references/release-notes-format.md). If no closed issues are found,
-     `$issue_list` is empty and the issues subsection/section is omitted everywhere.
+6. **Collect closed issues and their attribution.** For each merged PR `N` in `$pr_list`, find the issues that PR
+   closed and credit everyone involved, following [references/attribution-rules.md](./references/attribution-rules.md).
+   That file holds the closing-issue lookup, the substantive-comment test that decides who counts as a contributor, the
+   bot-account exclusions, and the shape of each `$issue_list` entry. If no closed issues are found, `$issue_list` is
+   empty and the issues subsection/section is omitted everywhere.
 
 ## Step 3: Build the per-plugin version plan
 
@@ -204,64 +167,11 @@ Enumerate the plugins from `plugins` in Project Context (one parent, plus each c
   baseline. Record the introduction in the changelog, but do not increment. This is the general rule for every future
   `han-*` extension, not a one-time exception for the current children.
 
-### 3a. Classify each plugin
-
-For each plugin, read `current` from `{source}/.claude-plugin/plugin.json` and compute `baseline`:
-
-- **Child, did not exist at `prev`** (`git cat-file -e {prev}:{source}/.claude-plugin/plugin.json` fails, or this is the
-  first release): **new plugin**. `baseline = current`, `target = current`, **no bump**, mark it `new`. Skip the rest of
-  the classification for this plugin.
-- **Child, existed at `prev`**: `baseline = git show {prev}:{source}/.claude-plugin/plugin.json | jq -r .version`.
-- **Parent**: `baseline = prev#` (the parent's version is what the tag tracks, regardless of any directory move). On the
-  first release `baseline` is empty and the parent is treated like a new plugin set to its `current` value.
-
-Determine whether the plugin **changed** in `{range}`:
-
-- **Child**: changed when `git diff --name-only {prev}..HEAD -- {source}/` is non-empty.
-- **Parent**: always treated as changed (it always bumps). Its change _level_ is computed in 3b from the whole release,
-  not just `{parent source}/`.
-
-### 3b. Compute each changed plugin's bump level and target
-
-For a **changed child**, classify the highest-priority change inside `{source}/`:
-
-- **major** — a skill directory under `{source}/skills/` was removed or renamed (renaming breaks `/skill-name`), an
-  agent under `{source}/agents/` was removed or renamed, or a commit indicates a breaking behavior change (`!` in the
-  type, `BREAKING CHANGE`, a review skill that now auto-posts, and so on). Inspect
-  `git diff --name-status {range} -- {source}/` for `D`/`R` on `SKILL.md` or agent paths, and scan commit subjects
-  scoped to that plugin.
-- **minor** — a new skill, a new agent, a new `references/` file, or a new optional capability was added inside
-  `{source}/`, with no major change present. Inspect the same diff for added `SKILL.md` / agent files.
-- **patch** — only typo, permission, edge-case, or context-injection fixes inside `{source}/`.
-
-For the **parent**, the bump level is the maximum across the whole release:
-
-- a child was **removed** from the suite → **major** (breaking for anyone who installed the meta-plugin).
-- any changed child's level is **major** → **major**.
-- a **new** child plugin was introduced, or any changed child's level is **minor** → at least **minor** (a new or
-  expanded capability reaches suite installers).
-- otherwise (only child patches, or only repo-level/`{parent source}/` doc and config fixes) → **patch**.
-
-Take the highest of those. Repo-root changes that do not live inside any plugin directory (for example `docs/`,
-`README.md`, `CONTRIBUTING.md`) are suite-level: they count toward the parent's level (normally patch) and never bump a
-child.
-
-Compute `proposed` from each plugin's `baseline`: major → `(x+1).0.0`, minor → `x.(y+1).0`, patch → `x.y.(z+1)`.
-
-### 3c. Decide each plugin's target (ahead path vs. compute path)
-
-For each changed plugin, compare `current` to `baseline`:
-
-```
-highest=$(printf '%s\n%s\n' "{baseline}" "{current}" | sort -V | tail -n1)
-```
-
-- **`current` strictly ahead of `baseline`** (`highest` == `current` and `current` != `baseline`): the version was
-  already bumped during development. **`target = current`. No confirmation for this plugin.** Still compute the expected
-  `proposed`, and if `current` is a _lower_ level of bump than the changes warrant, add one non-blocking advisory line
-  to the Step 7 summary.
-- **`current` equal to or behind `baseline`**: the one-bump-per-branch bump has not been applied for this plugin.
-  `target = proposed`; this plugin **needs confirmation**.
+Classify each plugin, compute its bump level, and decide its target by following
+[references/version-plan-rules.md](./references/version-plan-rules.md). That file holds the baseline lookup for a
+parent, an existing child, and a new child (3a); the major, minor, and patch classification for a changed child and for
+the parent (3b); and the ahead-path versus compute-path decision that determines which plugins need confirmation below
+(3c).
 
 ### 3d. Confirm the plan (conditional gate)
 
@@ -310,7 +220,7 @@ two reads above answer the same question and work in either state.
 
 ## Step 4: Apply the versions
 
-For **every** plugin whose `target` differs from its `current` (the compute-path plugins from Step 3c, and any plugin
+For **every** plugin whose `target` differs from its `current` (the compute-path plugins from 3c in `references/version-plan-rules.md`, and any plugin
 the operator edited at 3d), set both files so they read `target`:
 
 1. Set `{source}/.claude-plugin/plugin.json` `version` to that plugin's `target` (Edit).
@@ -327,7 +237,8 @@ recovery is discarding the working-tree edits.
 
 ## Step 5: Update CHANGELOG.md
 
-Follow [references/changelog-rules.md](./references/changelog-rules.md) exactly. From `v3.0.0` onward, each release
+Follow [references/changelog-rules.md](./references/changelog-rules.md) exactly, writing the narrative in the voice at
+[writing-voice.md](../../../han-communication/references/writing-voice.md). From `v3.0.0` onward, each release
 section is a parent `## v{parent target}` heading with one `### {plugin} v{version}` sub-heading per plugin that changed
 (the parent always appears; new and changed children appear; unchanged children are omitted), plus the release-level
 bookkeeping subsections. Every `@mention` in the changelog (narrative, PR bullets, issue bullets) is a markdown link to
@@ -437,7 +348,7 @@ The commit is on GitHub and no tag exists yet. Everything past this point is irr
 1. **Compute each plugin's `tag name`** as `{name}--v{target}`, for every plugin in `plugins`, then split them into two
    sets using the Step 3 version plan:
    - **Being tagged this release** — every plugin whose `target` differs from its `baseline` (the parent always, plus
-     each bumped child), and every **new** plugin from Step 3a, whose tag has never existed.
+     each bumped child), and every **new** plugin classified at 3a, whose tag has never existed.
    - **Carried forward** — every unchanged child, whose `target` equals its `baseline`. Its tag was created by the
      release that shipped that version and points at that older release commit. This run does not re-tag it.
 
diff --git a/.claude/skills/han-release/references/attribution-rules.md b/.claude/skills/han-release/references/attribution-rules.md
new file mode 100644
index 00000000..439f9837
--- /dev/null
+++ b/.claude/skills/han-release/references/attribution-rules.md
@@ -0,0 +1,49 @@
+# Release Attribution Rules
+
+This file defines how a release run credits the people behind every closed issue in the range. It is loaded by
+`SKILL.md` Step 2.6, which finds the issues each merged PR closed and builds `$issue_list` from them.
+
+Work one merged PR at a time and relate each closed issue to the fix that resolved it.
+
+## Find the closed issues for the PR
+
+Take the issue numbers from
+`gh pr view N --json closingIssuesReferences --jq '[.closingIssuesReferences[]?.number]'` (the GitHub-tracked
+closing links). As a fallback for older PRs that linked via text, also scan the PR body and commit messages for
+GitHub closing keywords: `gh pr view N --json body,commits --jq '[.body, (.commits[].messageBody)] | join("\n")'`
+and extract `#<num>` that follow `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, or
+`resolved` (case-insensitive). Union the two sets, dedupe.
+
+## Confirm each is a closed issue
+
+For each candidate number `I`, run
+`gh issue view I --json number,title,author,state,comments` (suppress stderr; redirect `2>/dev/null`). Skip the
+number if the command fails (it is a PR number, not an issue, or does not exist).
+
+## Gather attribution per issue
+
+Record:
+
+- **opener** — `.author.login`, unless `.author.is_bot` is true.
+- **issue contributors** (people who contributed meaningfully) — the people who left a **substantive** comment on
+  the issue. A reaction is not a comment (a 👍 or other emoji reaction never appears in `.comments[]`), so
+  reaction-only participants are already excluded. Drive-by comments do not count either. Pull each comment with
+  its author and body
+  (`gh issue view I --json comments --jq '.comments[] | select(.author.is_bot|not) | {login: .author.login, body: .body}'`,
+  stderr suppressed), and treat a comment as a drive-by when its trimmed body is emoji-only, or is a brief
+  acknowledgment or status ping (for example `+1`, `same`, `me too`, `bump`, `following`, `thanks`,
+  `any update(s)?`), or is shorter than roughly 15 words and adds no detail. A person qualifies only when at least
+  one of their comments is substantive (not a drive-by). Remove the opener and the PR workers so each person is
+  credited once. May be empty.
+- **PR workers** — for the closing PR `N`, the union of the PR author, the review authors, and the commit authors:
+  `gh pr view N --json author,reviews,commits --jq '[.author.login] + [.reviews[]?.author.login] + [.commits[].authors[].login] | unique'`.
+  Drop bot accounts (`is_bot` where available, plus the `web-flow`, `github-actions`, and `dependabot` logins).
+
+## Build `$issue_list`
+
+One entry per closed issue: its number, title, opener, contributors, the closing PR
+number(s), and the merged PR workers. If the same issue is closed by more than one PR in the range, record every
+closing PR and merge their worker sets. Build the changelog bullets and release-body lines per
+[changelog-rules.md](./changelog-rules.md) and
+[release-notes-format.md](./release-notes-format.md). If no closed issues are found,
+`$issue_list` is empty and the issues subsection/section is omitted everywhere.
diff --git a/.claude/skills/han-release/references/changelog-rules.md b/.claude/skills/han-release/references/changelog-rules.md
index 47f8b8f1..e12f1de3 100644
--- a/.claude/skills/han-release/references/changelog-rules.md
+++ b/.claude/skills/han-release/references/changelog-rules.md
@@ -1,5 +1,13 @@
 # CHANGELOG.md rules
 
+## Contents
+
+- Per-plugin structure (from v3.0.0 onward)
+- Augment vs. generate
+- Linked mentions
+- Generated bookkeeping subsections
+- Register and voice for a generated narrative section
+
 `CHANGELOG.md` lives at the repository root. The title line is `# Han Release Notes`. Each version is a top-level
 section that starts with `## v{parent target}` (newest first, directly under the title), where `parent target` is the
 version of the parent `han` plugin.
diff --git a/.claude/skills/han-release/references/release-notes-format.md b/.claude/skills/han-release/references/release-notes-format.md
index 41b8a3a5..d32ca48f 100644
--- a/.claude/skills/han-release/references/release-notes-format.md
+++ b/.claude/skills/han-release/references/release-notes-format.md
@@ -1,5 +1,13 @@
 # GitHub release notes format
 
+## Contents
+
+- Body template
+- PR line format
+- Issues closed section
+- Full-changelog links
+- Publish vs. draft, and idempotency
+
 The release notes body is assembled deterministically: the release's summary paragraph leads (no heading), followed by a
 `## What's Changed` PR list, an `## Issues closed` section, the per-plugin `### {plugin} v{version}` narrative
 sub-headings, then the full-changelog links. The release is named for the parent `han` plugin's version, so the body
diff --git a/.claude/skills/han-release/references/version-plan-rules.md b/.claude/skills/han-release/references/version-plan-rules.md
new file mode 100644
index 00000000..85cd01f0
--- /dev/null
+++ b/.claude/skills/han-release/references/version-plan-rules.md
@@ -0,0 +1,64 @@
+# Per-Plugin Version Plan Rules
+
+This file defines how a release run establishes each plugin's baseline version, classifies the size of its change, and
+decides its target version. It is loaded by `SKILL.md` Step 3, which applies the governing rules there and then confirms
+the resulting plan at 3d.
+
+## 3a. Classify each plugin
+
+For each plugin, read `current` from `{source}/.claude-plugin/plugin.json` and compute `baseline`:
+
+- **Child, did not exist at `prev`** (`git cat-file -e {prev}:{source}/.claude-plugin/plugin.json` fails, or this is the
+  first release): **new plugin**. `baseline = current`, `target = current`, **no bump**, mark it `new`. Skip the rest of
+  the classification for this plugin.
+- **Child, existed at `prev`**: `baseline = git show {prev}:{source}/.claude-plugin/plugin.json | jq -r .version`.
+- **Parent**: `baseline = prev#` (the parent's version is what the tag tracks, regardless of any directory move). On the
+  first release `baseline` is empty and the parent is treated like a new plugin set to its `current` value.
+
+Determine whether the plugin **changed** in `{range}`:
+
+- **Child**: changed when `git diff --name-only {prev}..HEAD -- {source}/` is non-empty.
+- **Parent**: always treated as changed (it always bumps). Its change _level_ is computed in 3b from the whole release,
+  not just `{parent source}/`.
+
+## 3b. Compute each changed plugin's bump level and target
+
+For a **changed child**, classify the highest-priority change inside `{source}/`:
+
+- **major** — a skill directory under `{source}/skills/` was removed or renamed (renaming breaks `/skill-name`), an
+  agent under `{source}/agents/` was removed or renamed, or a commit indicates a breaking behavior change (`!` in the
+  type, `BREAKING CHANGE`, a review skill that now auto-posts, and so on). Inspect
+  `git diff --name-status {range} -- {source}/` for `D`/`R` on `SKILL.md` or agent paths, and scan commit subjects
+  scoped to that plugin.
+- **minor** — a new skill, a new agent, a new `references/` file, or a new optional capability was added inside
+  `{source}/`, with no major change present. Inspect the same diff for added `SKILL.md` / agent files.
+- **patch** — only typo, permission, edge-case, or context-injection fixes inside `{source}/`.
+
+For the **parent**, the bump level is the maximum across the whole release:
+
+- a child was **removed** from the suite → **major** (breaking for anyone who installed the meta-plugin).
+- any changed child's level is **major** → **major**.
+- a **new** child plugin was introduced, or any changed child's level is **minor** → at least **minor** (a new or
+  expanded capability reaches suite installers).
+- otherwise (only child patches, or only repo-level/`{parent source}/` doc and config fixes) → **patch**.
+
+Take the highest of those. Repo-root changes that do not live inside any plugin directory (for example `docs/`,
+`README.md`, `CONTRIBUTING.md`) are suite-level: they count toward the parent's level (normally patch) and never bump a
+child.
+
+Compute `proposed` from each plugin's `baseline`: major → `(x+1).0.0`, minor → `x.(y+1).0`, patch → `x.y.(z+1)`.
+
+## 3c. Decide each plugin's target (ahead path vs. compute path)
+
+For each changed plugin, compare `current` to `baseline`:
+
+```
+highest=$(printf '%s\n%s\n' "{baseline}" "{current}" | sort -V | tail -n1)
+```
+
+- **`current` strictly ahead of `baseline`** (`highest` == `current` and `current` != `baseline`): the version was
+  already bumped during development. **`target = current`. No confirmation for this plugin.** Still compute the expected
+  `proposed`, and if `current` is a _lower_ level of bump than the changes warrant, add one non-blocking advisory line
+  to the Step 7 summary.
+- **`current` equal to or behind `baseline`**: the one-bump-per-branch bump has not been applied for this plugin.
+  `target = proposed`; this plugin **needs confirmation**.
diff --git a/.claude/skills/han-update-documentation/references/audit-checklist.md b/.claude/skills/han-update-documentation/references/audit-checklist.md
index cc8038c7..79d15dd1 100644
--- a/.claude/skills/han-update-documentation/references/audit-checklist.md
+++ b/.claude/skills/han-update-documentation/references/audit-checklist.md
@@ -1,5 +1,16 @@
 # Per-Entity Audit Checklist
 
+## Contents
+
+- Skills (`{plugin}/skills/{name}/SKILL.md` + `{plugin}/docs/skills/{name}.md`)
+- Agents (`{plugin}/agents/{name}.md` + `{plugin}/docs/agents/{name}.md`)
+- Top-level concept docs (`docs/concepts.md`, `docs/quickstart.md`, `docs/sizing.md`, `docs/yagni.md`)
+- Indexes (`docs/skills/README.md`, `docs/agents/README.md`)
+- Guidance docs (`han-plugin-builder/skills/guidance/references/**`)
+- Templates (`docs/templates/**`)
+- Root files (`README.md`, `CONTRIBUTING.md`, `CLAUDE.md`)
+- Reporting findings
+
 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.
diff --git a/han-atlassian/references/config-rule.md b/han-atlassian/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-atlassian/references/config-rule.md
+++ b/han-atlassian/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-coding/references/collaborative-stop-rule.md b/han-coding/references/collaborative-stop-rule.md
index d9cbc7a7..61f91898 100644
--- a/han-coding/references/collaborative-stop-rule.md
+++ b/han-coding/references/collaborative-stop-rule.md
@@ -1,5 +1,15 @@
 # Collaborative Stop Rule (Handing Control Back Mid-Run)
 
+## Contents
+
+- Who reads this
+- Detecting the flag
+- What a stop presents
+- Asking before building, and when
+- Recording what the person says
+- Acting on the answer
+- Pace
+
 This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what
 it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill
 performed it.
diff --git a/han-coding/references/config-rule.md b/han-coding/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-coding/references/config-rule.md
+++ b/han-coding/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-coding/references/evidence-rule.md b/han-coding/references/evidence-rule.md
index 8534703a..c38432db 100644
--- a/han-coding/references/evidence-rule.md
+++ b/han-coding/references/evidence-rule.md
@@ -1,7 +1,15 @@
 # Evidence Rule (Evidence-Based)
 
+## Contents
+
+- Trust classes
+- The three principles
+- How to apply the rule
+- Escalation
+- What this rule is not
+
 This rule defines what evidence means in Han, how to characterize how strong it is, and what to do when no evidence
-exists at all. The rule supplements [`yagni-rule.md`](./yagni-rule.md). YAGNI's categories answer _is there any evidence
+exists at all. The rule supplements the companion `yagni-rule.md`, which a skill needing both loads directly. YAGNI's categories answer _is there any evidence
 to include this item?_ This rule answers _once an item passes that test, how confident should you be in the evidence,
 and what is the response when no evidence is available?_
 
@@ -32,8 +40,8 @@ The principle inverts in three contexts: formal-methods or specification-complia
 authoritative artifact); regulatory or contractual contexts (the regulation wins); and pre-incident observation of
 intended behavior (a passing test proves only that tested inputs behaved correctly for tested code paths; passing and
 failing tests are not symmetric evidence). See
-[`docs/evidence.md#principle-1-proximity-to-origin`](../../docs/evidence.md#principle-1-proximity-to-origin) for the
-inversion conditions.
+[`docs/evidence.md`](https://github.com/testdouble/han/blob/main/docs/evidence.md#principle-1-proximity-to-origin) in
+the Han repository for the inversion conditions in full.
 
 ### Principle 2: Independent corroboration (web-source scope)
 
@@ -57,7 +65,7 @@ When a claim has no evidence at any tier, label it. Defer the dependent decision
 justify revisiting.
 
 Do not collapse "no evidence" into "very weak evidence." They are different states. The response pattern is the same one
-[YAGNI](./yagni-rule.md) uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
+`yagni-rule.md` uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
 incident class, a customer commitment, a regulation taking effect, a dependency landing). Aspirational triggers do not
 qualify.
 
diff --git a/han-coding/references/yagni-rule.md b/han-coding/references/yagni-rule.md
index c2b57c27..9fc46d0b 100644
--- a/han-coding/references/yagni-rule.md
+++ b/han-coding/references/yagni-rule.md
@@ -1,5 +1,13 @@
 # YAGNI Rule (Evidence-Based)
 
+## Contents
+
+- The two gates
+- Named anti-patterns (auto-flag as YAGNI candidates)
+- How to apply YAGNI in skills and agents
+- Deferred (YAGNI) section format
+- What YAGNI is not
+
 YAGNI — "You Aren't Gonna Need It" — is the rule this project uses to keep specs, plans, code, and operational machinery
 from accreting work that isn't needed yet. The rule is evidence-based, not absolute. Items survive when evidence
 justifies them. Items without evidence get deferred — recorded for later, not silently dropped.
@@ -10,8 +18,8 @@ copy. The bar for inclusion is "we need this now and have evidence to prove it,"
 
 The categories below answer whether evidence exists at all (the inclusion gate). For how strong the evidence is once it
 exists — trust classes, the corroboration gate for web sources, the no-evidence label — see the companion
-[`evidence-rule.md`](./evidence-rule.md). The two rules work together; this one gates inclusion, that one characterizes
-quality.
+`evidence-rule.md`, which a skill needing both loads directly. The two rules work together; this one gates inclusion,
+that one characterizes quality.
 
 ## The two gates
 
diff --git a/han-coding/skills/code-review/SKILL.md b/han-coding/skills/code-review/SKILL.md
index 02ab813a..78ce4787 100644
--- a/han-coding/skills/code-review/SKILL.md
+++ b/han-coding/skills/code-review/SKILL.md
@@ -250,7 +250,9 @@ Review each file from the Step 1 file list **in alphabetical order**. For each f
 4. **Examine the diff** to understand what changed. If no diff is available (Mode B uncommitted review or Mode C non-git
    review from Step 1), skip this sub-step — the full file read from sub-step 3 provides all necessary context. Apply
    the review checklist to the entire file content.
-5. **Apply the review checklist** at [review-checklist.md](./references/review-checklist.md)
+5. **Apply the review checklist** at [review-checklist.md](./references/review-checklist.md). Its YAGNI pass and its
+   Gate 1 evidence test are defined in [../../references/yagni-rule.md](../../references/yagni-rule.md); read that
+   file from here rather than following the checklist's own link to it.
 
 If the user provided focus areas in their arguments (the `$focus_areas` binding from Step 1), apply extra scrutiny to
 those areas and include additional detail in findings for matching categories.
diff --git a/han-coding/skills/code-review/references/agent-dispatch.md b/han-coding/skills/code-review/references/agent-dispatch.md
index a18cb948..00e684f8 100644
--- a/han-coding/skills/code-review/references/agent-dispatch.md
+++ b/han-coding/skills/code-review/references/agent-dispatch.md
@@ -1,5 +1,11 @@
 # Agent Selection and Dispatch
 
+## Contents
+
+- Step 3.2: Select agents
+- Step 3.3: Scope every agent brief to the change
+- Step 3.4: Domain-scoped file lists
+
 The review roster, the signals that select each agent, the brief-scoping rules, the domain-scoped file
 lists, and the exact per-agent dispatch prompts. Step 3 selects and dispatches using this file. The sub-step numbering below is the skill's own; other sites cite
 these sections as Step 3.2 through Step 3.5.
diff --git a/han-coding/skills/code-review/references/agent-finding-classification.md b/han-coding/skills/code-review/references/agent-finding-classification.md
index b6e7ec93..52373145 100644
--- a/han-coding/skills/code-review/references/agent-finding-classification.md
+++ b/han-coding/skills/code-review/references/agent-finding-classification.md
@@ -1,3 +1,16 @@
+## Contents
+
+- Processing test-engineer results
+- Processing edge-case-explorer results
+- Processing adversarial-security-analyst results
+- Processing structural-analyst results
+- Processing behavioral-analyst results
+- Processing concurrency-analyst results (only if dispatched)
+- Processing data-engineer results (only if dispatched)
+- Processing devops-engineer results (only if dispatched)
+- Processing on-call-engineer results (only if dispatched)
+- Processing junior-developer results
+
 **Size-based demotion (applies to every category below).** Size-based demotion is governed by [SKILL.md](../SKILL.md)
 Step 3.3, the authoritative home for size-based severity rules. The bands in each category define what each severity
 means; Step 3.3 governs which findings escalate to those bands at the change's size (read from Step 3.1). When
diff --git a/han-coding/skills/code-review/references/finding-content.md b/han-coding/skills/code-review/references/finding-content.md
index 2f4f2800..a4570cad 100644
--- a/han-coding/skills/code-review/references/finding-content.md
+++ b/han-coding/skills/code-review/references/finding-content.md
@@ -1,5 +1,14 @@
 # Finding Content: the plain-language explanation
 
+## Contents
+
+- Which findings carry it
+- What the explanation answers
+- Where the answers come from
+- The fix route
+- Both cues reach the summary table
+- Security findings
+
 Every finding a reader is expected to act on opens with a plain-language explanation written for someone who will not
 open the file. This file says which findings carry it, what it answers, and where the answers come from. The block
 format it renders into is in [template.md](./template.md).
diff --git a/han-coding/skills/code-review/references/review-checklist.md b/han-coding/skills/code-review/references/review-checklist.md
index aa99bd05..3d2641ea 100644
--- a/han-coding/skills/code-review/references/review-checklist.md
+++ b/han-coding/skills/code-review/references/review-checklist.md
@@ -1,5 +1,21 @@
 ### Review Checklist
 
+## Contents
+
+- YAGNI
+- Correctness
+- Data Isolation (when applicable)
+- Performance
+- Error Handling
+- Testing
+- API Design
+- Code Maintainability
+- Code Organization
+- Documentation
+- Code Style & Patterns
+- Database (when applicable)
+- Architecture Decision Records (when applicable)
+
 **YAGNI** (apply [../../../references/yagni-rule.md](../../../references/yagni-rule.md); these become `YAGNI-###` items
 in the separate YAGNI section, never CRIT/WARN/SUGG)
 
diff --git a/han-coding/skills/coding-standard/references/durable-references.md b/han-coding/skills/coding-standard/references/durable-references.md
index 736f4787..235ab319 100644
--- a/han-coding/skills/coding-standard/references/durable-references.md
+++ b/han-coding/skills/coding-standard/references/durable-references.md
@@ -1,5 +1,12 @@
 # The durable-reference rule
 
+## Contents
+
+- Rule 1: The committed document cites a durable anchor, never a bare line number
+- Rule 2: Choose the anchor's scope
+- Rule 3: State applicability as a membership criterion, not a roster
+- Rule 4: Remove temporal phrasing or references to "current state"
+
 A committed document that cites code — a coding standard, a piece of project documentation — must stay accurate as the
 code it cites evolves. Two failure modes break that. A bare `file:line` citation in the document goes stale the moment a
 line is inserted above it. A snapshot roster of "current consumers" goes stale as consumers change. This rule prevents
diff --git a/han-coding/skills/tdd/references/failure-modes.md b/han-coding/skills/tdd/references/failure-modes.md
index cfcb7ce8..990ade9b 100644
--- a/han-coding/skills/tdd/references/failure-modes.md
+++ b/han-coding/skills/tdd/references/failure-modes.md
@@ -1,5 +1,19 @@
 # How an Agent Fakes TDD, and the Discipline That Catches It
 
+## Contents
+
+- 1. Writing the test and the production code together
+- 2. Never seeing red
+- 3. Whole-feature steps
+- 4. Skipping the refactor
+- 5. Asserting on implementation detail
+- 6. Applying standards while going green
+- 7. Keeping no test list
+- 8. Refactoring into speculative abstraction
+- 9. Asserting the bug instead of the fix
+- 10. Making a test pass by changing code the ticket does not own
+- The one check that catches most of these
+
 An unguided coding agent reliably fakes TDD. The failure is rarely malice — it is the model optimizing for "tests are
 green at the end" instead of "the tests drove the code". Each failure mode below has a symptom you can observe and a
 gate in the SKILL body that catches it. When you feel the pull toward any of these, that pull is the signal the
diff --git a/han-coding/skills/tdd/references/test-selection.md b/han-coding/skills/tdd/references/test-selection.md
index 11a495cf..280e252c 100644
--- a/han-coding/skills/tdd/references/test-selection.md
+++ b/han-coding/skills/tdd/references/test-selection.md
@@ -1,5 +1,15 @@
 # Choosing the Next Test: TPP and ZOMBIES
 
+## Contents
+
+- The Transformation Priority Premise (TPP)
+- Using the ranking to pick the next test
+- The decision-point rule
+- ZOMBIES: the same idea as a concrete ordering
+- How this composes with the rest of the loop
+- Worked example: `sum(numbers)`
+- Sources
+
 This is the canonical reference for the test-selection heuristics the `/tdd` skill uses when it orders the test list
 (Step 2) and picks the next item (Step 3). The loop tells you to write a failing test and make it pass. It does not tell
 you which test to write next. The Transformation Priority Premise and ZOMBIES both answer exactly that question, and
diff --git a/han-communication/references/config-rule.md b/han-communication/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-communication/references/config-rule.md
+++ b/han-communication/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-communication/references/readability-rule.md b/han-communication/references/readability-rule.md
index 14cb6f42..0df11aaa 100644
--- a/han-communication/references/readability-rule.md
+++ b/han-communication/references/readability-rule.md
@@ -1,5 +1,18 @@
 # Readability Rule (Human-Readable Output Standard)
 
+## Contents
+
+- Who reads reader-facing output
+- The audience frame
+- What the standard requires
+- Length guidance
+- The vocabulary blocklist
+- Prose only
+- Fidelity wins
+- Break a rule before writing something clumsy
+- The standardized self-check
+- How to apply this rule in a skill
+
 This is the shared readability standard that every reader-facing Han skill applies while it writes. Its one aim: when a
 user runs a reader-facing skill, the human-facing deliverable it produces can be found, understood, and used by a reader
 who did not do the work and lacks the author's context.
diff --git a/han-communication/references/writing-voice.md b/han-communication/references/writing-voice.md
index 5ff37893..2eb5b427 100644
--- a/han-communication/references/writing-voice.md
+++ b/han-communication/references/writing-voice.md
@@ -1,5 +1,15 @@
 # Han Writing Voice Profile
 
+## Contents
+
+- Formatting standards
+- Voice profile
+- Vocabulary and phrasing
+- Structural tendencies
+- Content type variations
+- AI slop to avoid
+- Sample passages
+
 ## Formatting standards
 
 This profile governs voice and tone — not formatting mechanics. For formatting rules (paragraph length limits, header
diff --git a/han-core/references/collaborative-stop-rule.md b/han-core/references/collaborative-stop-rule.md
index d9cbc7a7..61f91898 100644
--- a/han-core/references/collaborative-stop-rule.md
+++ b/han-core/references/collaborative-stop-rule.md
@@ -1,5 +1,15 @@
 # Collaborative Stop Rule (Handing Control Back Mid-Run)
 
+## Contents
+
+- Who reads this
+- Detecting the flag
+- What a stop presents
+- Asking before building, and when
+- Recording what the person says
+- Acting on the answer
+- Pace
+
 This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what
 it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill
 performed it.
diff --git a/han-core/references/config-rule.md b/han-core/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-core/references/config-rule.md
+++ b/han-core/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-core/references/evidence-rule.md b/han-core/references/evidence-rule.md
index 8534703a..c38432db 100644
--- a/han-core/references/evidence-rule.md
+++ b/han-core/references/evidence-rule.md
@@ -1,7 +1,15 @@
 # Evidence Rule (Evidence-Based)
 
+## Contents
+
+- Trust classes
+- The three principles
+- How to apply the rule
+- Escalation
+- What this rule is not
+
 This rule defines what evidence means in Han, how to characterize how strong it is, and what to do when no evidence
-exists at all. The rule supplements [`yagni-rule.md`](./yagni-rule.md). YAGNI's categories answer _is there any evidence
+exists at all. The rule supplements the companion `yagni-rule.md`, which a skill needing both loads directly. YAGNI's categories answer _is there any evidence
 to include this item?_ This rule answers _once an item passes that test, how confident should you be in the evidence,
 and what is the response when no evidence is available?_
 
@@ -32,8 +40,8 @@ The principle inverts in three contexts: formal-methods or specification-complia
 authoritative artifact); regulatory or contractual contexts (the regulation wins); and pre-incident observation of
 intended behavior (a passing test proves only that tested inputs behaved correctly for tested code paths; passing and
 failing tests are not symmetric evidence). See
-[`docs/evidence.md#principle-1-proximity-to-origin`](../../docs/evidence.md#principle-1-proximity-to-origin) for the
-inversion conditions.
+[`docs/evidence.md`](https://github.com/testdouble/han/blob/main/docs/evidence.md#principle-1-proximity-to-origin) in
+the Han repository for the inversion conditions in full.
 
 ### Principle 2: Independent corroboration (web-source scope)
 
@@ -57,7 +65,7 @@ When a claim has no evidence at any tier, label it. Defer the dependent decision
 justify revisiting.
 
 Do not collapse "no evidence" into "very weak evidence." They are different states. The response pattern is the same one
-[YAGNI](./yagni-rule.md) uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
+`yagni-rule.md` uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
 incident class, a customer commitment, a regulation taking effect, a dependency landing). Aspirational triggers do not
 qualify.
 
diff --git a/han-core/references/yagni-rule.md b/han-core/references/yagni-rule.md
index c2b57c27..9fc46d0b 100644
--- a/han-core/references/yagni-rule.md
+++ b/han-core/references/yagni-rule.md
@@ -1,5 +1,13 @@
 # YAGNI Rule (Evidence-Based)
 
+## Contents
+
+- The two gates
+- Named anti-patterns (auto-flag as YAGNI candidates)
+- How to apply YAGNI in skills and agents
+- Deferred (YAGNI) section format
+- What YAGNI is not
+
 YAGNI — "You Aren't Gonna Need It" — is the rule this project uses to keep specs, plans, code, and operational machinery
 from accreting work that isn't needed yet. The rule is evidence-based, not absolute. Items survive when evidence
 justifies them. Items without evidence get deferred — recorded for later, not silently dropped.
@@ -10,8 +18,8 @@ copy. The bar for inclusion is "we need this now and have evidence to prove it,"
 
 The categories below answer whether evidence exists at all (the inclusion gate). For how strong the evidence is once it
 exists — trust classes, the corroboration gate for web sources, the no-evidence label — see the companion
-[`evidence-rule.md`](./evidence-rule.md). The two rules work together; this one gates inclusion, that one characterizes
-quality.
+`evidence-rule.md`, which a skill needing both loads directly. The two rules work together; this one gates inclusion,
+that one characterizes quality.
 
 ## The two gates
 
diff --git a/han-documentation/references/config-rule.md b/han-documentation/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-documentation/references/config-rule.md
+++ b/han-documentation/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-documentation/references/evidence-rule.md b/han-documentation/references/evidence-rule.md
index 8534703a..c38432db 100644
--- a/han-documentation/references/evidence-rule.md
+++ b/han-documentation/references/evidence-rule.md
@@ -1,7 +1,15 @@
 # Evidence Rule (Evidence-Based)
 
+## Contents
+
+- Trust classes
+- The three principles
+- How to apply the rule
+- Escalation
+- What this rule is not
+
 This rule defines what evidence means in Han, how to characterize how strong it is, and what to do when no evidence
-exists at all. The rule supplements [`yagni-rule.md`](./yagni-rule.md). YAGNI's categories answer _is there any evidence
+exists at all. The rule supplements the companion `yagni-rule.md`, which a skill needing both loads directly. YAGNI's categories answer _is there any evidence
 to include this item?_ This rule answers _once an item passes that test, how confident should you be in the evidence,
 and what is the response when no evidence is available?_
 
@@ -32,8 +40,8 @@ The principle inverts in three contexts: formal-methods or specification-complia
 authoritative artifact); regulatory or contractual contexts (the regulation wins); and pre-incident observation of
 intended behavior (a passing test proves only that tested inputs behaved correctly for tested code paths; passing and
 failing tests are not symmetric evidence). See
-[`docs/evidence.md#principle-1-proximity-to-origin`](../../docs/evidence.md#principle-1-proximity-to-origin) for the
-inversion conditions.
+[`docs/evidence.md`](https://github.com/testdouble/han/blob/main/docs/evidence.md#principle-1-proximity-to-origin) in
+the Han repository for the inversion conditions in full.
 
 ### Principle 2: Independent corroboration (web-source scope)
 
@@ -57,7 +65,7 @@ When a claim has no evidence at any tier, label it. Defer the dependent decision
 justify revisiting.
 
 Do not collapse "no evidence" into "very weak evidence." They are different states. The response pattern is the same one
-[YAGNI](./yagni-rule.md) uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
+`yagni-rule.md` uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
 incident class, a customer commitment, a regulation taking effect, a dependency landing). Aspirational triggers do not
 qualify.
 
diff --git a/han-documentation/references/yagni-rule.md b/han-documentation/references/yagni-rule.md
index c2b57c27..9fc46d0b 100644
--- a/han-documentation/references/yagni-rule.md
+++ b/han-documentation/references/yagni-rule.md
@@ -1,5 +1,13 @@
 # YAGNI Rule (Evidence-Based)
 
+## Contents
+
+- The two gates
+- Named anti-patterns (auto-flag as YAGNI candidates)
+- How to apply YAGNI in skills and agents
+- Deferred (YAGNI) section format
+- What YAGNI is not
+
 YAGNI — "You Aren't Gonna Need It" — is the rule this project uses to keep specs, plans, code, and operational machinery
 from accreting work that isn't needed yet. The rule is evidence-based, not absolute. Items survive when evidence
 justifies them. Items without evidence get deferred — recorded for later, not silently dropped.
@@ -10,8 +18,8 @@ copy. The bar for inclusion is "we need this now and have evidence to prove it,"
 
 The categories below answer whether evidence exists at all (the inclusion gate). For how strong the evidence is once it
 exists — trust classes, the corroboration gate for web sources, the no-evidence label — see the companion
-[`evidence-rule.md`](./evidence-rule.md). The two rules work together; this one gates inclusion, that one characterizes
-quality.
+`evidence-rule.md`, which a skill needing both loads directly. The two rules work together; this one gates inclusion,
+that one characterizes quality.
 
 ## The two gates
 
diff --git a/han-feedback/references/config-rule.md b/han-feedback/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-feedback/references/config-rule.md
+++ b/han-feedback/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-github/references/config-rule.md b/han-github/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-github/references/config-rule.md
+++ b/han-github/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-github/skills/work-items-to-issues/references/screenshot-embed-rules.md b/han-github/skills/work-items-to-issues/references/screenshot-embed-rules.md
index 6f20a01a..597c850d 100644
--- a/han-github/skills/work-items-to-issues/references/screenshot-embed-rules.md
+++ b/han-github/skills/work-items-to-issues/references/screenshot-embed-rules.md
@@ -1,5 +1,17 @@
 # Screenshot embed rules
 
+## Contents
+
+- The accepted file types
+- Why cross-repo URLs are forbidden
+- Required URL form
+- Why the path is feature-scoped
+- How assets reach the default branch
+- Embed format inside the issue body
+- Mapping visual material to slices
+- Duplication over sharing
+- What never to do
+
 When the plan folder contains a `ui-designs/` subfolder with visual material, every UI-bearing slice MUST embed the
 relevant material **inline in the issue body** — not as plain links.
 
diff --git a/han-linear/references/config-rule.md b/han-linear/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-linear/references/config-rule.md
+++ b/han-linear/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-planning/references/collaborative-stop-rule.md b/han-planning/references/collaborative-stop-rule.md
index d9cbc7a7..61f91898 100644
--- a/han-planning/references/collaborative-stop-rule.md
+++ b/han-planning/references/collaborative-stop-rule.md
@@ -1,5 +1,15 @@
 # Collaborative Stop Rule (Handing Control Back Mid-Run)
 
+## Contents
+
+- Who reads this
+- Detecting the flag
+- What a stop presents
+- Asking before building, and when
+- Recording what the person says
+- Acting on the answer
+- Pace
+
 This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what
 it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill
 performed it.
diff --git a/han-planning/references/config-rule.md b/han-planning/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-planning/references/config-rule.md
+++ b/han-planning/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-planning/references/evidence-rule.md b/han-planning/references/evidence-rule.md
index 8534703a..c38432db 100644
--- a/han-planning/references/evidence-rule.md
+++ b/han-planning/references/evidence-rule.md
@@ -1,7 +1,15 @@
 # Evidence Rule (Evidence-Based)
 
+## Contents
+
+- Trust classes
+- The three principles
+- How to apply the rule
+- Escalation
+- What this rule is not
+
 This rule defines what evidence means in Han, how to characterize how strong it is, and what to do when no evidence
-exists at all. The rule supplements [`yagni-rule.md`](./yagni-rule.md). YAGNI's categories answer _is there any evidence
+exists at all. The rule supplements the companion `yagni-rule.md`, which a skill needing both loads directly. YAGNI's categories answer _is there any evidence
 to include this item?_ This rule answers _once an item passes that test, how confident should you be in the evidence,
 and what is the response when no evidence is available?_
 
@@ -32,8 +40,8 @@ The principle inverts in three contexts: formal-methods or specification-complia
 authoritative artifact); regulatory or contractual contexts (the regulation wins); and pre-incident observation of
 intended behavior (a passing test proves only that tested inputs behaved correctly for tested code paths; passing and
 failing tests are not symmetric evidence). See
-[`docs/evidence.md#principle-1-proximity-to-origin`](../../docs/evidence.md#principle-1-proximity-to-origin) for the
-inversion conditions.
+[`docs/evidence.md`](https://github.com/testdouble/han/blob/main/docs/evidence.md#principle-1-proximity-to-origin) in
+the Han repository for the inversion conditions in full.
 
 ### Principle 2: Independent corroboration (web-source scope)
 
@@ -57,7 +65,7 @@ When a claim has no evidence at any tier, label it. Defer the dependent decision
 justify revisiting.
 
 Do not collapse "no evidence" into "very weak evidence." They are different states. The response pattern is the same one
-[YAGNI](./yagni-rule.md) uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
+`yagni-rule.md` uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
 incident class, a customer commitment, a regulation taking effect, a dependency landing). Aspirational triggers do not
 qualify.
 
diff --git a/han-planning/references/operator-escalation-rule.md b/han-planning/references/operator-escalation-rule.md
index d3a7d3ee..cfdee7d5 100644
--- a/han-planning/references/operator-escalation-rule.md
+++ b/han-planning/references/operator-escalation-rule.md
@@ -1,5 +1,14 @@
 # Operator Escalation Rule (One Question at a Time)
 
+## Contents
+
+- One question per turn
+- Lead with the consequence, in plain language
+- The opening confirmation turn is not an escalation
+- The single stop
+- The escalation register
+- Related rules
+
 **Owned by `han-planning`.** This file is authored here and is not a vendored copy of a shared rule. Do not overwrite it
 from another plugin's `references/` folder during a re-sync sweep, and do not treat a difference between it and any
 similarly-named file elsewhere as drift to correct.
diff --git a/han-planning/references/planning-boundary-rule.md b/han-planning/references/planning-boundary-rule.md
index 38aa6fc5..0c62443a 100644
--- a/han-planning/references/planning-boundary-rule.md
+++ b/han-planning/references/planning-boundary-rule.md
@@ -1,5 +1,11 @@
 # Planning Boundary Rule (Scope Boundary and Visual Material)
 
+## Contents
+
+- The boundary record
+- Visual material
+- Related rules
+
 **Owned by `han-planning`.** This file is authored here and is not a vendored copy of a shared rule. Do not overwrite it
 from another plugin's `references/` folder during a re-sync sweep, and do not treat a difference between it and any
 similarly-named file elsewhere as drift to correct.
diff --git a/han-planning/references/scope-justification-rule.md b/han-planning/references/scope-justification-rule.md
index 8fd61970..5a3ce20e 100644
--- a/han-planning/references/scope-justification-rule.md
+++ b/han-planning/references/scope-justification-rule.md
@@ -1,5 +1,12 @@
 # Scope Justification Rule (Justification, Cut List, and the Scope Gate)
 
+## Contents
+
+- The justification field
+- The cut list
+- The scope gate
+- Related rules
+
 **Owned by `han-planning`.** This file is authored here and is not a vendored copy of a shared rule. Do not overwrite it
 from another plugin's `references/` folder during a re-sync sweep, and do not treat a difference between it and any
 similarly-named file elsewhere as drift to correct.
@@ -123,4 +130,5 @@ the operator spends a turn re-deciding something their own ticket already said.
 - [`planning-boundary-rule.md`](./planning-boundary-rule.md), for the boundary record this gate reads and the visual
   material a justification can cite.
 - [`operator-escalation-rule.md`](./operator-escalation-rule.md), for the plain language a cut-list entry borrows.
-- [`yagni-rule.md`](./yagni-rule.md), for the evidence and simpler-version gates the scope gate sits beside.
+- `yagni-rule.md`, for the evidence and simpler-version gates the scope gate sits beside. A skill applying both loads
+  each of them directly from its `SKILL.md`.
diff --git a/han-planning/references/yagni-rule.md b/han-planning/references/yagni-rule.md
index c2b57c27..9fc46d0b 100644
--- a/han-planning/references/yagni-rule.md
+++ b/han-planning/references/yagni-rule.md
@@ -1,5 +1,13 @@
 # YAGNI Rule (Evidence-Based)
 
+## Contents
+
+- The two gates
+- Named anti-patterns (auto-flag as YAGNI candidates)
+- How to apply YAGNI in skills and agents
+- Deferred (YAGNI) section format
+- What YAGNI is not
+
 YAGNI — "You Aren't Gonna Need It" — is the rule this project uses to keep specs, plans, code, and operational machinery
 from accreting work that isn't needed yet. The rule is evidence-based, not absolute. Items survive when evidence
 justifies them. Items without evidence get deferred — recorded for later, not silently dropped.
@@ -10,8 +18,8 @@ copy. The bar for inclusion is "we need this now and have evidence to prove it,"
 
 The categories below answer whether evidence exists at all (the inclusion gate). For how strong the evidence is once it
 exists — trust classes, the corroboration gate for web sources, the no-evidence label — see the companion
-[`evidence-rule.md`](./evidence-rule.md). The two rules work together; this one gates inclusion, that one characterizes
-quality.
+`evidence-rule.md`, which a skill needing both loads directly. The two rules work together; this one gates inclusion,
+that one characterizes quality.
 
 ## The two gates
 
diff --git a/han-planning/skills/plan-a-feature/references/review-team-briefs.md b/han-planning/skills/plan-a-feature/references/review-team-briefs.md
index dd71c69e..38a37e9e 100644
--- a/han-planning/skills/plan-a-feature/references/review-team-briefs.md
+++ b/han-planning/skills/plan-a-feature/references/review-team-briefs.md
@@ -1,5 +1,12 @@
 # Review Team Roster and Briefs
 
+## Contents
+
+- The roster
+- Specialists deliberately excluded from the default roster
+- Domain-scoped briefs
+- The shared brief every specialist receives
+
 The specialist roster for the spec-stage review round, the domain-scoped brief each specialist receives, and the shared
 brief text every one of them gets. Step 6 of the skill selects from this file; it does not restate it.
 
diff --git a/han-planning/skills/plan-implementation/SKILL.md b/han-planning/skills/plan-implementation/SKILL.md
index 456cf701..e0f251f8 100644
--- a/han-planning/skills/plan-implementation/SKILL.md
+++ b/han-planning/skills/plan-implementation/SKILL.md
@@ -119,6 +119,12 @@ artifacts live in `{same-folder-as-source}/artifacts/` (which may already exist
 - `{same-folder-as-source}/artifacts/implementation-iteration-history.md` — round-by-round record of specialists
   engaged, questions raised, and how each was resolved.
 
+Each file follows its own template, copied whole:
+[feature-implementation-plan-template.md](./references/feature-implementation-plan-template.md),
+[implementation-decision-log-template.md](./references/implementation-decision-log-template.md), and
+[implementation-iteration-history-template.md](./references/implementation-iteration-history-template.md). Read a
+template in full from here rather than through the synthesis directives in Step 8.
+
 Two more artifacts are written by Step 1.5 rather than by this step:
 
 - `{same-folder-as-source}/artifacts/scope-boundary.md` — the boundary record. Always present, whether this run wrote it
diff --git a/han-planning/skills/plan-implementation/references/team-selection.md b/han-planning/skills/plan-implementation/references/team-selection.md
index bbd9d441..235df8a6 100644
--- a/han-planning/skills/plan-implementation/references/team-selection.md
+++ b/han-planning/skills/plan-implementation/references/team-selection.md
@@ -1,8 +1,16 @@
 # Team Selection
 
+## Contents
+
+- Size bands and the specialist cap
+- The roster
+- Domain-scoped briefs
+
 The size bands, the specialist cap, the round cap, and the roster Step 3 draws from.
 Step 3 selects using this file; it does not restate it.
 
+## Size bands and the specialist cap
+
 **Default to small.** Start the classification at **small** and only escalate to medium or large when the signals below
 clearly require it. When a signal is borderline, stay at the smaller band. Use the spec's coordinations, T# count,
 security/PII surface, integration boundaries, and the user's framing:
@@ -28,6 +36,8 @@ subsystems, small auth surface", "Medium: passed via `$size`", or "Medium: from
 `default-swarm-size`", naming whichever of the two files supplied it). If
 the user disagrees, accept the override (size, specific specialists, or both) and proceed.
 
+## The roster
+
 The team **always includes**:
 
 - `han-core:plan-synthesizer` — final synthesizer, dispatched once in Step 8 rather than per round.
diff --git a/han-plugin-builder/references/config-rule.md b/han-plugin-builder/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-plugin-builder/references/config-rule.md
+++ b/han-plugin-builder/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-description-length.md b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-description-length.md
index a6ca6a92..8072f3b1 100644
--- a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-description-length.md
+++ b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-description-length.md
@@ -5,6 +5,17 @@ paths:
 
 # Agent Description Length
 
+## Contents
+
+- The target: keep every agent description under 1024 characters
+- Why agents drifted long, and why it matters
+- What belongs in the description, and what moves to the body
+- The priority cutting ladder
+- How to measure a description
+- Common Pitfalls
+- Summary Checklist
+- Cross-References
+
 Every installed agent's frontmatter `description` is loaded into context in every conversation, the same way skill
 descriptions are. Claude reads the whole roster of agent descriptions to decide which agent to dispatch, so each one is
 paid for in every session whether or not the agent runs. Run `/context` in a session with agents installed and you will
diff --git a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-domain-focus.md b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-domain-focus.md
index 0739cae0..ec3dd33d 100644
--- a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-domain-focus.md
+++ b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-domain-focus.md
@@ -5,6 +5,13 @@ paths:
 
 # Domain Focus in Agent Definitions
 
+## Contents
+
+- Why Domain Focus Matters
+- Implementation
+- Summary Checklist
+- Cross-References
+
 Agents perform better when they target a narrow domain with precise vocabulary. A focused agent activates deep expertise
 in the model. A broad generalist activates shallow, averaged knowledge across competing domains.
 
diff --git a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-external-files.md b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-external-files.md
index 0df3a2df..8fb36ab1 100644
--- a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-external-files.md
+++ b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-external-files.md
@@ -5,6 +5,17 @@ paths:
 
 # External File References in Agent Definitions
 
+## Contents
+
+- The Rule
+- Why: Structural Evidence
+- Comparison: Skills vs. Agents
+- Agent Frontmatter Fields
+- The Pattern in Practice
+- What to Do Instead
+- Summary Checklist
+- Cross-References
+
 Agent definitions are self-contained markdown files. Unlike skills, agents do not support external file references. No
 `references/` folders, no `scripts/` folders, and no context injection commands. All content must be inlined directly in
 the agent `.md` file.
diff --git a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-model-selection.md b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-model-selection.md
index 5c004d72..e7f984af 100644
--- a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-model-selection.md
+++ b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/agent-model-selection.md
@@ -5,6 +5,17 @@ paths:
 
 # Choosing the Right Model for Agent Definitions
 
+## Contents
+
+- The `model` Field
+- Model Characteristics
+- Decision Criteria
+- A Note on Cost
+- Evidence from Agent Archetypes
+- Summary Checklist
+- Cross-References
+- Sources
+
 Agents support a `model` frontmatter field that skills do not. Choosing the right model is about matching capability and
 speed to the task the agent performs. **Cost is not a factor in model selection.** Choose based on what the task
 demands, not price.
diff --git a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/multi-agent-economics.md b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/multi-agent-economics.md
index 6b0b0e91..a972b6d8 100644
--- a/han-plugin-builder/skills/guidance/references/agent-building-guidelines/multi-agent-economics.md
+++ b/han-plugin-builder/skills/guidance/references/agent-building-guidelines/multi-agent-economics.md
@@ -5,6 +5,16 @@ paths:
 
 # Multi-Agent Economics
 
+## Contents
+
+- Say what warrants delegation, because the model's default is eager
+- The Escalation Cascade
+- The 45% Threshold
+- Scaling Reality
+- Practical Implications for Skills
+- Summary Checklist
+- Sources
+
 When a skill dispatches agents via the `Agent` tool, each agent adds latency and token cost. This doc provides the
 decision framework for when adding agents is justified and when it's wasteful.
 
diff --git a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/marketplace-json-options.md b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/marketplace-json-options.md
index 2571d315..6a2afa69 100644
--- a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/marketplace-json-options.md
+++ b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/marketplace-json-options.md
@@ -1,5 +1,16 @@
 # marketplace.json Schema Reference
 
+## Contents
+
+- Root Object
+- Plugin Entry Object
+- Source Variants
+- Strict Mode
+- Version Resolution
+- Reserved Marketplace Names
+- Official Reference
+- JSON example
+
 The `.claude-plugin/marketplace.json` file is the registry that Claude Code reads to discover and install plugins from a
 marketplace.
 
diff --git a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/plugin-json-options.md b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/plugin-json-options.md
index 64d78794..50c58be2 100644
--- a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/plugin-json-options.md
+++ b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/plugin-json-options.md
@@ -1,5 +1,18 @@
 # plugin.json Schema Reference
 
+## Contents
+
+- Required Fields
+- Metadata Fields (Optional)
+- Component Path Fields (Optional)
+- userConfig
+- channels
+- dependencies
+- Environment Variables
+- Complete Example
+- Official Reference
+- JSON example
+
 The `.claude-plugin/plugin.json` manifest file defines a Claude Code plugin's metadata and component paths.
 
 ## Required Fields
diff --git a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/themes-json-options.md b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/themes-json-options.md
index 985766d2..ecb6720b 100644
--- a/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/themes-json-options.md
+++ b/han-plugin-builder/skills/guidance/references/claude-marketplace-and-plugin-configuration/themes-json-options.md
@@ -1,5 +1,15 @@
 # Theme File Schema Reference
 
+## Contents
+
+- Fields
+- `base` Valid Values
+- Color Value Formats
+- Color Tokens
+- Behavior
+- Official Reference
+- JSON example
+
 Plugin theme files are JSON files placed in the `themes/` directory (or a custom path set via the `themes` field in
 `plugin.json`). The filename without `.json` becomes the theme's slug.
 
diff --git a/han-plugin-builder/skills/guidance/references/iterative-plugin-development.md b/han-plugin-builder/skills/guidance/references/iterative-plugin-development.md
index 3c7b197f..7a0906f2 100644
--- a/han-plugin-builder/skills/guidance/references/iterative-plugin-development.md
+++ b/han-plugin-builder/skills/guidance/references/iterative-plugin-development.md
@@ -1,5 +1,12 @@
 # Iterative Plugin Development
 
+## Contents
+
+- The Rules
+- Testing Methodology
+- When to Stop Iterating
+- Summary Checklist
+
 Plugin development (skills, agents, and hooks) almost never produces solid, consistently working entities on the first
 try. LLM-driven plugins interact with model behavior unpredictably: assumptions encoded in a first draft only surface as
 problems on re-examination. This guide codifies an iterative development process that challenges assumptions, eliminates
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/allowed-tools-bash-permissions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/allowed-tools-bash-permissions.md
index 34fdd0cf..752dbdfb 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/allowed-tools-bash-permissions.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/allowed-tools-bash-permissions.md
@@ -5,6 +5,13 @@ paths:
 
 # Bash Permission Patterns in `allowed-tools`
 
+## Contents
+
+- Syntax Rules
+- Granularity Rules
+- Common Patterns
+- Summary Checklist
+
 The `allowed-tools` frontmatter in a SKILL.md file declares which Bash commands are auto-approved without user
 permission prompts. Bash permissions use a glob pattern syntax: `Bash(command prefix *)`. Getting the syntax or
 granularity wrong causes skills to either stall on permission prompts or silently auto-approve unintended commands.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-hygiene.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-hygiene.md
index 240f887d..a4fda46d 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-hygiene.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-hygiene.md
@@ -5,6 +5,12 @@ paths:
 
 # Context Hygiene
 
+## Contents
+
+- The Rules
+- Anti-Patterns
+- Summary Checklist
+
 Context hygiene is the discipline of keeping a skill's context footprint minimal, well-positioned, and free of stale or
 irrelevant tokens. Several other guidance docs contain rules that serve this goal — progressive disclosure, frontmatter
 conciseness, extracting to references/, position-aware ordering, stale-doc audits. This doc explains the mechanisms
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md
index bfdb2db5..60fd9d41 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/context-injection-commands.md
@@ -5,6 +5,18 @@ paths:
 
 # Context Injection Commands in Skill Files
 
+## Contents
+
+- Syntax
+- When to Use
+- Section Placement
+- Command Guidelines
+- What NOT to Use in Context Injection
+- Referencing Injected Context in Steps
+- Relationship to `allowed-tools`
+- Command Categories Quick Reference
+- Summary Checklist
+
 Context injection commands use the `` !`command` `` syntax to execute a shell command at skill load time and inject its
 stdout into the skill as runtime context. The command runs **once when the skill loads**, not during each step. This
 gives skill steps access to dynamic information about the current environment without hardcoding values.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/cowork-specific-skill-instructions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/cowork-specific-skill-instructions.md
index c1cce669..3fa26beb 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/cowork-specific-skill-instructions.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/cowork-specific-skill-instructions.md
@@ -5,6 +5,20 @@ paths:
 
 # Claude Cowork — Complete Reference
 
+## Contents
+
+- What is Cowork?
+- What Cowork Can Do
+- Cowork vs. Claude Code: Extension Model
+- Skills in Cowork
+- Skill File Format
+- Skill Directory Structure
+- How Skills Load (Progressive Disclosure)
+- Cowork Runtime Environment
+- Authoring Best Practices
+- Checklist Before Uploading a Skill
+- Resources
+
 ## What is Cowork?
 
 Claude Cowork is Anthropic's agentic AI system for knowledge workers (not developers), available as a research preview
@@ -194,8 +208,9 @@ bigquery-skill/
 For tracked changes: See [REDLINING.md](REDLINING.md) For OOXML details: See [OOXML.md](OOXML.md)
 ```
 
-Keep all references **one level deep** from SKILL.md. Avoid nested references (SKILL.md → A.md → B.md) — Claude may only
-partially read nested files.
+Keep all references **one level deep** from SKILL.md, and open any reference file over roughly 100 lines with a contents
+list. Neither rule is specific to cowork; both are in
+[Skill Reference Files](./skill-reference-files.md#keep-reference-links-one-level-deep-from-skillmd).
 
 ### Degrees of freedom
 
@@ -250,6 +265,7 @@ gerund rule plus directory-name, dependency-prefix, and case-sensitivity rules.
 - [ ] No time-sensitive information
 - [ ] Consistent terminology throughout
 - [ ] File references are one level deep from SKILL.md
+- [ ] Reference files over roughly 100 lines open with a contents list
 - [ ] Workflows have clear numbered steps
 
 **Code and scripts**
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/documentation-maintenance.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/documentation-maintenance.md
index c2387166..5fd1601c 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/documentation-maintenance.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/documentation-maintenance.md
@@ -5,6 +5,15 @@ paths:
 
 # Documentation Maintenance
 
+## Contents
+
+- The Rules
+- Rule: Treat doc-code contradictions as functional bugs
+- Rule: Audit SKILL.md when its dependencies change
+- Rule: Audit references/ against source truth
+- Rule: Version documentation with the code it describes
+- Summary Checklist
+
 A skill that worked last month can silently degrade if its SKILL.md or references describe things that have changed. The
 model follows stale instructions faithfully — stale documentation is active poison, not passive neglect.
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/dynamic-project-discovery.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/dynamic-project-discovery.md
index 165c1671..9b1f5704 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/dynamic-project-discovery.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/dynamic-project-discovery.md
@@ -5,6 +5,15 @@ paths:
 
 # Dynamic Project Discovery
 
+## Contents
+
+- The Rules
+- Rule: Never hardcode branch names
+- Rule: Use `which` (guarded) for tool availability, not `--version`
+- Rule: Discover project structure dynamically
+- Rule: Handle missing tools gracefully in Pre-requisites
+- Summary Checklist
+
 Skills run in whatever repository the user invokes them from. They must discover the project's structure, branch names,
 and tool availability dynamically rather than hardcoding assumptions.
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/graceful-degradation.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/graceful-degradation.md
index bd006151..28d9529e 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/graceful-degradation.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/graceful-degradation.md
@@ -6,6 +6,13 @@ paths:
 
 # Graceful Degradation
 
+## Contents
+
+- The Rules
+- Rule: Detect environment state with a script, then branch to a named mode
+- Rule: Apply conventional defaults for directory keys when config is absent
+- Summary Checklist
+
 **Differentiation from `dynamic-project-discovery.md`:** That doc covers hard prerequisites — tools or capabilities the
 skill cannot function without at all; when they're missing, the skill stops with a message to the user. This doc covers
 _partial context_ — situations where the environment is usable but some data (a git history, project config, docs
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/naming-conventions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/naming-conventions.md
index f607022e..d8b336bb 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/naming-conventions.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/naming-conventions.md
@@ -5,6 +5,18 @@ paths:
 
 # Naming Conventions
 
+## Contents
+
+- The Rules
+- Rule: Plugin directory name must match the `name` field in `plugin.json`
+- Rule: Never put a `.` in a plugin name
+- Rule: Skill directory names should indicate external dependencies
+- Rule: Avoid skill names that imply the wrong artifact type
+- Rule: Skill `name` in frontmatter matches the directory name
+- Rule: No README.md inside skill folders
+- Rule: SKILL.md is case-sensitive
+- Summary Checklist
+
 Consistent naming across plugins, skills, and directories helps users discover and understand what a skill does from its
 name alone.
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/progressive-disclosure.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/progressive-disclosure.md
index 91310a1c..9973dcf1 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/progressive-disclosure.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/progressive-disclosure.md
@@ -5,6 +5,15 @@ paths:
 
 # Progressive Disclosure
 
+## Contents
+
+- The Rules
+- Rule: Skills use three levels of information loading
+- Rule: Keep SKILL.md body focused on process steps — extract domain knowledge to references/
+- Rule: Frontmatter descriptions must earn every word
+- Rule: Use scripts/ for deterministic operations
+- Summary Checklist
+
 Skills use a three-level information architecture that balances context availability with token efficiency. Each level
 loads only when needed, keeping Claude's context window focused on what matters for the current task.
 
@@ -56,7 +65,10 @@ Read the diff between the current branch and the default branch...
 ```
 
 **Level 3 — Linked files (loaded on demand):** Files in `references/` and `scripts/` that Claude loads only when a step
-explicitly references them. Templates, checklists, style guides, and shell scripts live here.
+explicitly references them. Templates, checklists, style guides, and shell scripts live here. Level 3 is one level, not
+a chain: link every reference file directly from SKILL.md, and open any reference file over roughly 100 lines with a
+contents list, so a partial read still shows what the file holds. Both rules are in
+[Skill Reference Files](./skill-reference-files.md).
 
 ```
 skills/
@@ -248,6 +260,7 @@ flexibility.
 5. Keep step-by-step process instructions, context injection, and conditional logic in SKILL.md
 6. Use `scripts/` for deterministic operations where correctness matters more than flexibility
 7. Every token in frontmatter costs context in every conversation — make it count
+8. Level 3 files link directly from SKILL.md, and the ones over roughly 100 lines open with a contents list
 
 Cross-references:
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/security-restrictions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/security-restrictions.md
index e3c5af13..93ba4117 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/security-restrictions.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/security-restrictions.md
@@ -5,6 +5,15 @@ paths:
 
 # Security Restrictions
 
+## Contents
+
+- The Rules
+- Rule: No XML angle brackets in frontmatter
+- Rule: No "claude" or "anthropic" in skill names
+- Rule: Description field max 1024 characters
+- Rule: Safe YAML parsing only
+- Summary Checklist
+
 Skill frontmatter appears in Claude's system prompt. This privileged position means malicious or malformed frontmatter
 could inject instructions into the system prompt, bypass skill boundaries, or cause silent failures. These restrictions
 prevent those risks.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-composition.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-composition.md
index 1a8c12f5..79e47816 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-composition.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-composition.md
@@ -5,6 +5,13 @@ paths:
 
 # Skill Composition
 
+## Contents
+
+- Orchestration composition (supported, with care)
+- Data-fetch composition (avoid)
+- The `context: fork` field
+- Deciding which way to go
+
 Skills can call other skills through the Skill tool. This is a real, supported capability, and Han uses it in
 production. It also has sharp edges. Treat it as a power tool: reach for it deliberately, with the safeguards below, and
 only when the alternative is duplicating a whole skill's worth of work.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-decomposition.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-decomposition.md
index 4f9329b5..c1852cb5 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-decomposition.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-decomposition.md
@@ -5,6 +5,12 @@ paths:
 
 # Skill Decomposition
 
+## Contents
+
+- The Rules
+- Composition Patterns
+- Summary Checklist
+
 A skill should do one thing well. When a skill handles too many responsibilities, it becomes fragile, hard to debug, and
 difficult for the LLM to follow consistently. Split monolithic skills into focused units and extract reusable agent
 definitions.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md
index 2214c61c..19b73120 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-frontmatter.md
@@ -5,6 +5,13 @@ paths:
 
 # Skill Description Frontmatter
 
+## Contents
+
+- How Description Matching Works
+- The Rules
+- Common Pitfalls
+- Summary Checklist
+
 The `description` field in SKILL.md frontmatter is the primary mechanism Claude uses to decide when to invoke a skill.
 Every installed skill's description is always loaded into Claude's context, where descriptions compete against each
 other for selection. A thin description means missed triggers — users ask for something the skill handles, but Claude
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-length.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-length.md
index a2906259..02227c6a 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-length.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-description-length.md
@@ -5,6 +5,16 @@ paths:
 
 # Skill Description Length
 
+## Contents
+
+- The target: keep every description under 1024 characters
+- Why 1024, when there are two different limits
+- How to measure a description
+- What gets cut first: the priority order
+- What to do when a description is over the limit
+- Common Pitfalls
+- Summary Checklist
+
 Every installed skill's `description` is loaded into context in every conversation, and the harness budgets how much of
 it Claude actually gets to see. A description that runs too long does not fail loudly — it gets silently truncated or
 dropped from the listing, and the skill quietly stops triggering as well as it should. This doc sets the length target
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-reference-files.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-reference-files.md
index d87ad3c6..367fb19f 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-reference-files.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/skill-reference-files.md
@@ -5,6 +5,17 @@ paths:
 
 # Skill Reference Files
 
+## Contents
+
+- Why References Exist: Progressive Disclosure
+- The Rule
+- Keep Reference Links One Level Deep from SKILL.md
+- Give a Reference File Over 100 Lines a Table of Contents
+- Directory Structure
+- The `assets/` Directory
+- Skills vs. Agents
+- Summary Checklist
+
 Skills can include reference documents — templates, checklists, examples, and other supporting content — in a
 `references/` subdirectory within the skill folder. These files are loaded into the skill's context on demand when a
 step explicitly references them.
@@ -63,6 +74,73 @@ skills/
 
 Moved into `references/` where the plugin system expects them.
 
+## Keep Reference Links One Level Deep from SKILL.md
+
+Every reference file a run needs must be linked directly from SKILL.md. When Claude reaches a file through another
+reference file — SKILL.md, then `evidence-rule.md`, then `yagni-rule.md` — it may preview that third file with a partial
+read such as `head -100` rather than reading it whole, and the run proceeds on part of the content.
+
+**Before (two hops to the content):**
+
+```markdown
+<!-- SKILL.md -->
+
+Apply the evidence standard in [references/evidence-rule.md](./references/evidence-rule.md).
+
+<!-- references/evidence-rule.md -->
+
+This rule supplements [yagni-rule.md](./yagni-rule.md).
+```
+
+`yagni-rule.md` is reachable only through `evidence-rule.md`, so the run may get part of it.
+
+**After (both files linked from SKILL.md):**
+
+```markdown
+<!-- SKILL.md -->
+
+Apply the inclusion gate in [references/yagni-rule.md](./references/yagni-rule.md) and the evidence standard in
+[references/evidence-rule.md](./references/evidence-rule.md).
+```
+
+The rule is about reachability, not about forbidding links between reference files. Once both files are linked from
+SKILL.md, a cross-link from one to the other is a navigation aid rather than the only path. What the rule forbids is a
+file reachable **only** through another reference file.
+
+A reference file must also stay inside its own plugin. A link that climbs out of the plugin directory (`../../docs/`)
+resolves in the source repository and breaks for everyone who installs the plugin, because only the plugin directory
+ships. Name the external document in prose, or link it by its public URL.
+
+## Give a Reference File Over 100 Lines a Table of Contents
+
+A reference file longer than roughly 100 lines opens with a `## Contents` list of its own section headings. Claude often
+previews a long file with a partial read, and a contents list at the top means even a partial read shows the full scope
+of what the file holds, so nothing further down goes unnoticed.
+
+```markdown
+# API Reference
+
+## Contents
+
+- Authentication and setup
+- Core methods
+- Error handling patterns
+
+## Authentication and setup
+
+...
+```
+
+List the headings that name the file's real sections, and stop there. Usually those are the `##` headings. When a file
+puts its sections one level down under a single `##` wrapper — a `## The Rules` holding ten `### Rule: ...` headings —
+list the inner ones instead, because a two-entry contents list tells a reader nothing. A list that mirrors every
+sub-heading of an already well-sectioned file costs more than the partial read it protects against.
+
+**The exception: output templates.** A reference file that is a skeleton copied whole into a produced document — an ADR
+template, a report template, a specification template — gets no contents list, because the list would be copied into
+every document the template produces. Keep those files free of a table of contents no matter how long they run, and
+have the SKILL.md step that loads one say it is copied whole so the run reads all of it.
+
 ## Directory Structure
 
 The full skill directory layout:
@@ -125,7 +203,10 @@ If an agent needs substantial reference content, inline it directly in the agent
 4. Use `assets/` for output files (templates, fonts, icons) not intended as context
 5. Extract domain knowledge (templates, checklists, rate tables, decision matrices) to `references/`
 6. Keep process steps and execution logic in SKILL.md
-7. Agents are self-contained — no `references/` or `scripts/` support
+7. Link every reference file a run needs directly from SKILL.md, so no file is reachable only through another one
+8. Keep every reference link inside the plugin directory — a link that climbs out of it breaks once the plugin is installed
+9. Open a reference file over roughly 100 lines with a `## Contents` list of its `##` headings, unless it is a template copied whole into output
+10. Agents are self-contained — no `references/` or `scripts/` support
 
 Cross-references:
 
@@ -133,3 +214,4 @@ Cross-references:
   don't support references
 - [Context Injection Commands](./context-injection-commands.md) — How injected context relates to reference files
 - [Progressive Disclosure](./progressive-disclosure.md) — The three-level architecture that references are part of
+- [Skill Decomposition](./skill-decomposition.md) — What to do when a reference file grows past what one file should hold
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/success-criteria-and-testing.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/success-criteria-and-testing.md
index 2686be37..650889d5 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/success-criteria-and-testing.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/success-criteria-and-testing.md
@@ -5,6 +5,13 @@ paths:
 
 # Success Criteria and Testing
 
+## Contents
+
+- Triggering Tests
+- Functional Tests
+- Performance Comparison
+- Summary Checklist
+
 How do you know a skill is working? Without defined success criteria, "it seems fine" becomes the bar — and that bar
 shifts with each conversation. This guide defines three test types that cover whether a skill triggers correctly,
 executes its workflow, and actually improves outcomes compared to working without it.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md
index 047c6405..26212113 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/troubleshooting.md
@@ -5,6 +5,20 @@ paths:
 
 # Troubleshooting
 
+## Contents
+
+- Skill Won't Upload
+- Skill Doesn't Trigger
+- Skill Triggers Too Often
+- Instructions Not Followed
+- Allowed-Tools Issues
+- A Probe Reading Outside the Project Is Refused by the Classifier
+- A Probe Naming an Environment Variable Is Refused
+- A Script Probe Aborts the Skill
+- Context Injection Syntax in Prose Triggers Execution
+- Sub-Skill Output Lost
+- Summary Checklist
+
 This guide covers common problems encountered when building and using skills, organized by symptom. Each section
 describes the symptom, explains the likely cause, and provides a concrete fix.
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/use-case-planning.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/use-case-planning.md
index 5a45c969..69263f84 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/use-case-planning.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/use-case-planning.md
@@ -5,6 +5,12 @@ paths:
 
 # Use Case Planning
 
+## Contents
+
+- The Rules
+- Use Case Template
+- Summary Checklist
+
 Before writing a SKILL.md, define 2-3 concrete use cases the skill should handle. Use cases ground the skill in real
 user workflows rather than abstract capabilities, and they become the test cases you run after building.
 
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/workflow-patterns.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/workflow-patterns.md
index b3bf9970..5bd6a7c9 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/workflow-patterns.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/workflow-patterns.md
@@ -5,6 +5,18 @@ paths:
 
 # Workflow Patterns
 
+## Contents
+
+- Choosing Your Approach: Problem-First vs. Tool-First
+- Sequential Workflow Orchestration
+- Iterative Refinement
+- Context-Aware Tool Selection
+- Domain-Specific Intelligence
+- Combining Patterns
+- Human Gates in Workflow Steps
+- Ordering Within Steps: Recency Bias
+- Summary Checklist
+
 Skills encode workflows — multi-step processes that Claude executes in a specific order with specific tools. This guide
 documents four structural patterns that appear across well-built skills. Each pattern solves a different workflow shape,
 and most real skills combine two or more.
diff --git a/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md b/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md
index 3da77349..7145e060 100644
--- a/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md
+++ b/han-plugin-builder/skills/guidance/references/skill-building-guidance/writing-effective-instructions.md
@@ -5,6 +5,22 @@ paths:
 
 # Writing Effective Instructions
 
+## Contents
+
+- The Rules
+- Rule: Be specific and actionable
+- Rule: Write constraints with embedded reasoning
+- Rule: Include error handling in instructions
+- Rule: Prefer inline discovery over forked data-fetch sub-skills
+- Rule: Reference bundled resources clearly
+- Rule: Use progressive disclosure for instruction length
+- Rule: Avoid verbose, buried, or ambiguous instructions
+- Rule: Structure conventions as heading + one-line rule + example
+- Rule: Resolve variation at the point of use
+- Rule: Include canonical examples for conventions the skill enforces
+- Rule: Use scripts for deterministic validation
+- Summary Checklist
+
 The SKILL.md body — everything below the YAML frontmatter — is where you tell Claude _how_ to execute the skill. These
 instructions load when the skill triggers (Level 2 in the progressive disclosure model) and guide Claude through the
 workflow step by step.
diff --git a/han-plugin-builder/skills/skill-builder/SKILL.md b/han-plugin-builder/skills/skill-builder/SKILL.md
index cc7dcd42..74ddc190 100644
--- a/han-plugin-builder/skills/skill-builder/SKILL.md
+++ b/han-plugin-builder/skills/skill-builder/SKILL.md
@@ -174,7 +174,9 @@ Cover at minimum:
    `SKILL.md` cased exactly.
 4. **Progressive disclosure** (`progressive-disclosure.md`, `skill-reference-files.md`) — body is process only and under
    500 lines; domain knowledge is in `references/`; scripts hold deterministic work; nothing the toolchain already
-   enforces is restated.
+   enforces is restated; every reference file is linked directly from SKILL.md rather than only through another
+   reference file, every reference link stays inside the plugin directory, and any reference file over roughly 100 lines
+   opens with a `## Contents` list unless it is a template copied whole into output.
 5. **Instruction quality** (`writing-effective-instructions.md`, `workflow-patterns.md`) — steps are specific and
    actionable; constraints embed reasoning; error handling is present; human gates sit only at irreversible actions; the
    most critical item in each list is placed last.
diff --git a/han-reporting/references/config-rule.md b/han-reporting/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-reporting/references/config-rule.md
+++ b/han-reporting/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-reporting/skills/html-summary/references/layout-principles.md b/han-reporting/skills/html-summary/references/layout-principles.md
index 93ebc984..7de49ba3 100644
--- a/han-reporting/skills/html-summary/references/layout-principles.md
+++ b/han-reporting/skills/html-summary/references/layout-principles.md
@@ -1,5 +1,18 @@
 # Executive Layout Principles for HTML Summaries
 
+## Contents
+
+- Reading order — required
+- What hoists to the top
+- What stays in supporting detail
+- Diagram rendering rules
+- Mermaid containers — required
+- Data-flow section layout
+- Section omission
+- Length discipline
+- Voice and framing
+- What to never do
+
 These principles override the order of the source markdown. The HTML report is for executive readers — they read
 top-down and stop early. The most decision-relevant content must appear first, every time.
 
diff --git a/han-reporting/skills/html-summary/references/report-style.md b/han-reporting/skills/html-summary/references/report-style.md
index 2c45ca81..0da5c6cb 100644
--- a/han-reporting/skills/html-summary/references/report-style.md
+++ b/han-reporting/skills/html-summary/references/report-style.md
@@ -1,5 +1,16 @@
 # Style Reference for HTML Summaries
 
+## Contents
+
+- CSS variables — paste verbatim into `:root`
+- Color role mapping
+- Typography
+- Shape and spacing
+- Mermaid theming
+- Component patterns
+- Accessibility
+- What not to do
+
 The default palette, typography, and component patterns for executive HTML reports. The colors derive from the Test
 Double brand palette (testdouble.com): a white page, deep purple as the primary accent, signature green for positive
 outcomes, and action orange for the stakeholder asks. Use these values verbatim. Do not introduce new accent colors or
diff --git a/han-research/references/config-rule.md b/han-research/references/config-rule.md
index f14eafe7..bcb53cb2 100644
--- a/han-research/references/config-rule.md
+++ b/han-research/references/config-rule.md
@@ -1,5 +1,14 @@
 # Config Rule (`.han/config.md`)
 
+## Contents
+
+- The two files, the two probes, and the personal read
+- Schema
+- How a configured path resolves
+- Precedence
+- Extra agents joining the pool
+- Degradation and the one-line note
+
 Han reads two optional configuration files, and either one may be absent. A person may carry a personal
 `.han/config.md` inside their Claude Code configuration directory, and a consuming project may carry its own
 `.han/config.md`. The personal file supplies defaults that follow the person into every project; the project file
diff --git a/han-research/references/evidence-rule.md b/han-research/references/evidence-rule.md
index 8534703a..c38432db 100644
--- a/han-research/references/evidence-rule.md
+++ b/han-research/references/evidence-rule.md
@@ -1,7 +1,15 @@
 # Evidence Rule (Evidence-Based)
 
+## Contents
+
+- Trust classes
+- The three principles
+- How to apply the rule
+- Escalation
+- What this rule is not
+
 This rule defines what evidence means in Han, how to characterize how strong it is, and what to do when no evidence
-exists at all. The rule supplements [`yagni-rule.md`](./yagni-rule.md). YAGNI's categories answer _is there any evidence
+exists at all. The rule supplements the companion `yagni-rule.md`, which a skill needing both loads directly. YAGNI's categories answer _is there any evidence
 to include this item?_ This rule answers _once an item passes that test, how confident should you be in the evidence,
 and what is the response when no evidence is available?_
 
@@ -32,8 +40,8 @@ The principle inverts in three contexts: formal-methods or specification-complia
 authoritative artifact); regulatory or contractual contexts (the regulation wins); and pre-incident observation of
 intended behavior (a passing test proves only that tested inputs behaved correctly for tested code paths; passing and
 failing tests are not symmetric evidence). See
-[`docs/evidence.md#principle-1-proximity-to-origin`](../../docs/evidence.md#principle-1-proximity-to-origin) for the
-inversion conditions.
+[`docs/evidence.md`](https://github.com/testdouble/han/blob/main/docs/evidence.md#principle-1-proximity-to-origin) in
+the Han repository for the inversion conditions in full.
 
 ### Principle 2: Independent corroboration (web-source scope)
 
@@ -57,7 +65,7 @@ When a claim has no evidence at any tier, label it. Defer the dependent decision
 justify revisiting.
 
 Do not collapse "no evidence" into "very weak evidence." They are different states. The response pattern is the same one
-[YAGNI](./yagni-rule.md) uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
+`yagni-rule.md` uses for deferred items: a labeled defer with a concrete reopen trigger (a measured metric, an
 incident class, a customer commitment, a regulation taking effect, a dependency landing). Aspirational triggers do not
 qualify.
 
diff --git a/han-research/references/yagni-rule.md b/han-research/references/yagni-rule.md
index c2b57c27..9fc46d0b 100644
--- a/han-research/references/yagni-rule.md
+++ b/han-research/references/yagni-rule.md
@@ -1,5 +1,13 @@
 # YAGNI Rule (Evidence-Based)
 
+## Contents
+
+- The two gates
+- Named anti-patterns (auto-flag as YAGNI candidates)
+- How to apply YAGNI in skills and agents
+- Deferred (YAGNI) section format
+- What YAGNI is not
+
 YAGNI — "You Aren't Gonna Need It" — is the rule this project uses to keep specs, plans, code, and operational machinery
 from accreting work that isn't needed yet. The rule is evidence-based, not absolute. Items survive when evidence
 justifies them. Items without evidence get deferred — recorded for later, not silently dropped.
@@ -10,8 +18,8 @@ copy. The bar for inclusion is "we need this now and have evidence to prove it,"
 
 The categories below answer whether evidence exists at all (the inclusion gate). For how strong the evidence is once it
 exists — trust classes, the corroboration gate for web sources, the no-evidence label — see the companion
-[`evidence-rule.md`](./evidence-rule.md). The two rules work together; this one gates inclusion, that one characterizes
-quality.
+`evidence-rule.md`, which a skill needing both loads directly. The two rules work together; this one gates inclusion,
+that one characterizes quality.
 
 ## The two gates