docs: restructure into docs/<skill-family>/, slim README to install + overview

.claude/skills/setup-isolated-setup-install/SKILL.md

@@ -36,7 +36,7 @@ when_to_use: |
 This skill is the **on-ramp** for adopters who do not yet have the
 secure setup running. It is a thin walkthrough wrapper around the
 canonical install path documented in
-[`secure-agent-setup.md`](../../../secure-agent-setup.md). The
+[`docs/setup/secure-agent-setup.md`](../../../docs/setup/secure-agent-setup.md). The
 authoritative content lives there; this skill exists so an adopter
 can say *"set up the secure agent setup"* in a fresh session and
 land in the right step-by-step flow without first reading the
@@ -86,7 +86,7 @@ Before walking any install step, confirm with the user:
    preserved vs replaced.
 4. **Sync repo (optional).** Whether the user maintains a
    private dotfile-style `~/.claude-config` repo per
-   [Syncing user-scope config across machines](../../../secure-agent-setup.md#syncing-user-scope-config-across-machines).
+   [Syncing user-scope config across machines](../../../docs/setup/secure-agent-setup.md#syncing-user-scope-config-across-machines).
    If yes, the skill installs user-scope scripts as **symlinks**
    into `~/.claude-config/scripts/` rather than `cp`-ing into
    `~/.claude/scripts/` — the symlink approach is what makes
@@ -95,7 +95,7 @@ Before walking any install step, confirm with the user:
 ## Walk-through
 
 Follow the canonical step list at
-[secure-agent-setup.md → Adopter setup → Via a Claude Code prompt](../../../secure-agent-setup.md#via-a-claude-code-prompt).
+[docs/setup/secure-agent-setup.md → Adopter setup → Via a Claude Code prompt](../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt).
 Each step in that list maps 1:1 to a step in this skill. Do not
 re-write the list here — read the doc, follow it, and surface each
 sub-step with the user. The doc names are the source of truth; the

.claude/skills/setup-isolated-setup-update/SKILL.md

@@ -28,7 +28,7 @@ when_to_use: |
 
 This skill is the **drift report** for an already-installed secure
 setup. It walks the canonical update-check at
-[`secure-agent-setup.md` → Keeping the setup updated → Via a Claude Code prompt](../../../secure-agent-setup.md#via-a-claude-code-prompt-2)
+[`docs/setup/secure-agent-setup.md` → Keeping the setup updated → Via a Claude Code prompt](../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt-2)
 and surfaces what is older / newer / has drifted, without applying
 any change.
 
@@ -65,13 +65,13 @@ any change.
 ## What to check
 
 The canonical step list is in
-[secure-agent-setup.md → Keeping the setup updated → Via a Claude Code prompt](../../../secure-agent-setup.md#via-a-claude-code-prompt-2).
+[docs/setup/secure-agent-setup.md → Keeping the setup updated → Via a Claude Code prompt](../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt-2).
 Walk each:
 
 1. **Framework checkout.** `cd` into the user's `airflow-steward`
    clone, `git fetch origin main`, report what changed under
    `tools/agent-isolation/`, `.claude/settings.json`, and
-   `secure-agent-setup.md` since the local checkout was last
+   `docs/setup/secure-agent-setup.md` since the local checkout was last
    updated. Print the `git pull --ff-only` command for the user
    to run; do not run it.
 2. **Pinned upstream tools.** Run
@@ -80,7 +80,7 @@ Walk each:
    has aged past the framework's 7-day cooldown. Include the
    upstream changelog link for each. Do not bump the manifest;
    that is a separate
-   [Bumping a pinned version](../../../secure-agent-setup.md#bumping-a-pinned-version)
+   [Bumping a pinned version](../../../docs/setup/secure-agent-setup.md#bumping-a-pinned-version)
    PR by hand.
 3. **User-scope script-copy drift.** For every user-scope file
    the doc tells the adopter to install
@@ -119,15 +119,15 @@ follow-up:
   arrived, and reminds the user to handle the parent-tracker
   submodule pointer if applicable.
 - Pinned-tool upgrade candidate worth adopting → manifest bump PR
-  per [Bumping a pinned version](../../../secure-agent-setup.md#bumping-a-pinned-version).
+  per [Bumping a pinned version](../../../docs/setup/secure-agent-setup.md#bumping-a-pinned-version).
 - User-scope script drift → re-`cp` from the framework checkout,
   or — if the script lives in `~/.claude-config/` and the user
   wants the change propagated to other machines — invoke
   `setup-shared-config-sync` to commit + push.
 - Settings.json shape drift → the user merges the new
   framework block into their tracker's `.claude/settings.json`
   by hand (the section to copy from is documented in
-  [The framework's own `.claude/settings.json`](../../../secure-agent-setup.md#the-frameworks-own-claudesettingsjson)).
+  [The framework's own `.claude/settings.json`](../../../docs/setup/secure-agent-setup.md#the-frameworks-own-claudesettingsjson)).
 - A previously-blocked denial command now succeeds → stop and
   surface as a regression, not a routine update; the user
   should investigate before bumping anything.

.claude/skills/setup-isolated-setup-verify/SKILL.md

@@ -2,7 +2,7 @@
 name: setup-isolated-setup-verify
 description: |
   Walk the verification checklist documented in
-  `secure-agent-setup.md` and report ✓ done / ✗ missing / ⚠ partial
+  `docs/setup/secure-agent-setup.md` and report ✓ done / ✗ missing / ⚠ partial
   for each piece of the secure agent setup — project + user-scope
   `settings.json` wiring, hook scripts present + executable,
   `claude-iso` sourced, pinned tool versions installed at the
@@ -28,7 +28,7 @@ when_to_use: |
 
 This skill is the **assertion** layer over the secure setup. It
 runs the checklist documented in
-[`secure-agent-setup.md` → Verification → Via a Claude Code prompt](../../../secure-agent-setup.md#via-a-claude-code-prompt-1)
+[`docs/setup/secure-agent-setup.md` → Verification → Via a Claude Code prompt](../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt-1)
 and reports each check's status to the user with concrete evidence
 (file paths, command output, version strings).
 
@@ -57,7 +57,7 @@ and reports each check's status to the user with concrete evidence
 ## The 7 checks
 
 The canonical list lives in
-[secure-agent-setup.md → Verification → Via a Claude Code prompt](../../../secure-agent-setup.md#via-a-claude-code-prompt-1).
+[docs/setup/secure-agent-setup.md → Verification → Via a Claude Code prompt](../../../docs/setup/secure-agent-setup.md#via-a-claude-code-prompt-1).
 Walk each in order:
 
 1. Project `.claude/settings.json` shape — `sandbox.enabled: true`,

.claude/skills/setup-shared-config-sync/SKILL.md

@@ -3,7 +3,7 @@ name: setup-shared-config-sync
 description: |
   Commit + push the user's shared Claude config to the
   `~/.claude-config` private dotfile-style sync repo (per
-  `secure-agent-setup.md` → Syncing user-scope config across
+  `docs/setup/secure-agent-setup.md` → Syncing user-scope config across
   machines). Inspects `~/.claude-config` for uncommitted local
   edits and unpushed commits, drafts a commit message for any
   unstaged changes, asks for explicit approval, then commits and
@@ -40,7 +40,7 @@ modifications upstream.
 
 The sync repo lives at `~/.claude-config/`. This is the convention
 documented in
-[`secure-agent-setup.md` → Syncing user-scope config across machines](../../../secure-agent-setup.md#syncing-user-scope-config-across-machines).
+[`docs/setup/secure-agent-setup.md` → Syncing user-scope config across machines](../../../docs/setup/secure-agent-setup.md#syncing-user-scope-config-across-machines).
 Adopters who maintain a sync repo at a different path will need to
 fork this skill — the path is intentionally not parameterised
 because the doc specifies one canonical location and forking the
@@ -89,7 +89,7 @@ skill is cleaner than per-invocation path-passing.
    or is not a git repo, surface that and stop — the user has
    not yet set up a sync repo per the doc, and the right next
    action is for them to follow
-   [Setting up a fresh host](../../../secure-agent-setup.md#setting-up-a-fresh-host).
+   [Setting up a fresh host](../../../docs/setup/secure-agent-setup.md#setting-up-a-fresh-host).
 
 2. **`git fetch origin`** to learn the remote's current state.
    Report:

.claude/skills/setup-steward-upgrade/SKILL.md

@@ -5,7 +5,7 @@ description: |
   latest `origin/main` and surface what changed — the commits
   pulled, the files touched (with focus on the secure-setup blast
   radius: `.claude/settings.json`, `tools/agent-isolation/`,
-  `secure-agent-setup.md`, `secure-agent-internals.md`,
+  `docs/setup/secure-agent-setup.md`, `docs/setup/secure-agent-internals.md`,
   `pinned-versions.toml`), and the next-step recommendation. Never
   applies user-side propagation itself — that is the job of
   `setup-isolated-setup-update` (drift report) and the framework
@@ -19,7 +19,7 @@ when_to_use: |
   date", or after Claude Code surfaces something new from the
   framework's release notes. Also appropriate as the entry point
   to a periodic update routine — recommended cadence per
-  secure-agent-setup.md is once per Claude Code upgrade or once
+  docs/setup/secure-agent-setup.md is once per Claude Code upgrade or once
   a month, whichever comes first; this skill is the *first* step
   of that routine, with `setup-isolated-setup-update` (read-only drift
   report) and any subsequent re-`cp` / `/setup-shared-config-sync` runs
@@ -67,8 +67,8 @@ which is read-only and runs naturally as the next step.
 - **Show what arrived.** After a successful pull, surface the
   commit list and a per-file change summary, with explicit focus
   on the secure-setup blast radius (`.claude/settings.json`,
-  `tools/agent-isolation/`, `secure-agent-setup.md`,
-  `secure-agent-internals.md`,
+  `tools/agent-isolation/`, `docs/setup/secure-agent-setup.md`,
+  `docs/setup/secure-agent-internals.md`,
   `tools/agent-isolation/pinned-versions.toml`). The user should
   walk away knowing whether this upgrade has user-side
   follow-through to do.
@@ -107,8 +107,8 @@ which is read-only and runs naturally as the next step.
    - List per-file changes with secure-setup focus:
      `git -C <path> diff --name-status HEAD..@{u}` — call out
      entries under `.claude/settings.json`,
-     `tools/agent-isolation/**`, `secure-agent-setup.md`,
-     `secure-agent-internals.md`, `pinned-versions.toml` if they
+     `tools/agent-isolation/**`, `docs/setup/secure-agent-setup.md`,
+     `docs/setup/secure-agent-internals.md`, `pinned-versions.toml` if they
      appear.
 
 4. **Confirm with the user before pulling.** Show the commits
@@ -171,7 +171,7 @@ which is read-only and runs naturally as the next step.
 
    - **If `pinned-versions.toml` changed**, name the specific
      tool(s) bumped and remind the user that the host install
-     commands in `secure-agent-setup.md → Required tools` may
+     commands in `docs/setup/secure-agent-setup.md → Required tools` may
      now reference newer versions; the user runs the `apt-get`
      / `dnf` / `npm install` themselves (the skill does not
      touch system tools).
@@ -192,7 +192,7 @@ which is read-only and runs naturally as the next step.
   `claude-code`). Those bumps happen on the host via the
   package manager, surfaced by `check-tool-updates.sh` and
   approved per the
-  [Bumping a pinned version](../../../secure-agent-setup.md#bumping-a-pinned-version)
+  [Bumping a pinned version](../../../docs/setup/secure-agent-setup.md#bumping-a-pinned-version)
   flow.
 - Not for syncing user-scope edits to `~/.claude-config`. That
   is `setup-shared-config-sync`'s job.

AGENTS.md

@@ -79,8 +79,8 @@ The framework has two layers:
 Repo-root files:
 
 - [`README.md`](README.md) — the end-to-end process for handling security issues (generic lifecycle).
-- [`how-to-fix-a-security-issue.md`](how-to-fix-a-security-issue.md) — high-level description of the fix workflow.
-- [`new-members-onboarding.md`](new-members-onboarding.md) — onboarding guide for new security team members.
+- [`docs/security/how-to-fix-a-security-issue.md`](docs/security/how-to-fix-a-security-issue.md) — high-level description of the fix workflow.
+- [`docs/security/new-members-onboarding.md`](docs/security/new-members-onboarding.md) — onboarding guide for new security team members.
 - [`projects/_template/`](projects/_template/) — bootstrap scaffold for a new adopter's `<project-config>/`.
 - [`tools/<name>/`](tools/) — tool adapters (GitHub operations, issue-template schema, project-board GraphQL, …) for the external tools the skills invoke.
 - [`.claude/skills/<name>/SKILL.md`](.claude/skills/) — the agentic workflows.
@@ -330,7 +330,7 @@ the user to follow up with submodule update on the parent.
 operate against pre-disclosure CVE content; running Claude Code (or
 another `SKILL.md`-aware agent) with default-permissive access to
 `~/`, env vars, and arbitrary network egress is a real exfiltration
-risk. See [`secure-agent-setup.md`](secure-agent-setup.md) for the
+risk. See [`docs/setup/secure-agent-setup.md`](docs/setup/secure-agent-setup.md) for the
 layered defence the framework dogfoods (`.claude/settings.json`
 sandbox + tool permissions + clean-env wrapper, with system tools
 pinned per-tool with a 7-day default upstream cooldown).

CONTRIBUTING.md

@@ -44,8 +44,8 @@ four — no hard-coded project assumptions anywhere.
   brevity, confidentiality, linking conventions, the placeholder
   substitution rule (`<PROJECT>`, `<tracker>`, `<upstream>`), and the
   informational-only treatment of reporter-supplied CVSS scores.
-  [`how-to-fix-a-security-issue.md`](how-to-fix-a-security-issue.md) and
-  [`new-members-onboarding.md`](new-members-onboarding.md) are
+  [`docs/security/how-to-fix-a-security-issue.md`](docs/security/how-to-fix-a-security-issue.md) and
+  [`docs/security/new-members-onboarding.md`](docs/security/new-members-onboarding.md) are
   human-facing guides that sit alongside those.
 - **Skills** live under
   [`.claude/skills/`](.claude/skills/). Each is a `SKILL.md` that
@@ -85,8 +85,8 @@ four — no hard-coded project assumptions anywhere.
 ├── AGENTS.md                      # Editorial rules: tone, brevity, confidentiality,
 │                                  # placeholder substitution, reporter-CVSS policy
 ├── CONTRIBUTING.md                # This file
-├── how-to-fix-a-security-issue.md # Human-facing fix guide
-├── new-members-onboarding.md      # Human-facing onboarding guide
+├── docs/security/how-to-fix-a-security-issue.md # Human-facing fix guide
+├── docs/security/new-members-onboarding.md      # Human-facing onboarding guide
 │
 ├── .claude/
 │   └── skills/                    # Agent workflows (invoked via the Skill tool)