@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/skills/shared/core/multi-agent-sync/SKILL.md

@@ -9,197 +9,100 @@ metadata:
 
 # Multi-Agent Sync
 
-**Single command. Full ecosystem sync. No argument required.**
+**One command. Full ecosystem sync. No arguments needed.**
 
-When invoked, it synchronizes all targets in order. It detects what changed, updates only the stale ones, and reports the result.
+It syncs all targets in order, updating only the stale ones, and reports. macOS only (ADR-0012); credential access goes through `~/.claude/lib/credential-store.sh` so no call site names the keychain backend.
 
-**Input**: $ARGUMENTS (optional  -  `release` or a change description to apply to all targets)
+**Input**: $ARGUMENTS (optional)
+
+| Arg | Meaning |
+|---|---|
+| (none) | Full ecosystem sync, every target |
+| `release` | Full sync + version bump + tag + npm publish + website deploy (Release Flow) |
+| `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
+| `"change description"` | Apply the description to every target at once |
+
+## Gotchas
+
+- The pre-push gate is timing-sensitive: under heavy load a deadline test fails closed. Re-run it on a quiet machine; never push with `--no-verify`.
+- `npm publish` answering 202 means the registry is still processing. Verify with the registry's dist-tags before moving `required`, which is asked for every release.
+- The installed tree is localized (Turkish descriptions, `model: opus` while fable is off). Normalize to English and `model: fable` before copying into the repo.
+- Synced shell runs on BSD userland: BSD grep has no Perl-regex flag, and `sed` has no `\b` or `\|`. A pattern that silently matches nothing reads as "clean".
 
 ## Targets
 
-| # | Target | Path | Direction |
-|---|-------|-----|-----|
-| 1 | Claude Code (source of truth) | `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/scripts/` + `~/.claude/lib/` | source |
-| 2 | Copilot CLI | `~/.copilot/copilot-instructions.md` + `~/.copilot/skills/` | <- from Claude |
-| 2b | Codex CLI | `~/.codex/AGENTS.md` + `~/.codex/skills/multi-agent/` + `~/.codex/multi-agent-refs/` + `~/.codex/agents/*.toml` | <- from Claude (path-rewritten) |
-| 3 | multi-agent-pipeline repo | `~/multi-agent-pipeline/pipeline/` | <- from Claude (genericized) |
-| 4 | Website | `{owner}/{website-host}` | <- version + features |
-| 5 | multi-agent-toolkit MCP server | resolved from `prefs.global.devToolkit` or the `mcpServers` registration | own repo: gate, commit, publish |
+Claude Code (source of truth) -> Copilot CLI, Codex CLI (path-rewritten), the
+pipeline repo (genericized), the website (`{owner}/{website-host}`) and the
+multi-agent-toolkit MCP server (its own repo). Paths, directions, the shared
+Claude <-> Copilot sections and the token table: `$HOME/.claude/multi-agent-refs/sync/overview.md`; read it
+before Step 1.5.
 
-## Default Behavior (no argument)
+## Default Behavior (no arguments)
 
-Run all steps automatically:
+Run every step automatically:
 
 ```
-Step 0: DOCTOR      node $HOME/.claude/scripts/doctor.mjs  -  exit 2 or 4 STOPS the sync
-Step 1: DETECT      Compare timestamps, find stale targets
+Step 0: DOCTOR      doctor.mjs  -  exit 2 or 4 stops the sync
+Step 1.5: DETECT    Compare timestamps, find stale targets
 Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 70 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + sub-command specs as refs + agent TOML)
-Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub)
-Step 3d: DEV-TOOLKIT Companion MCP server -> detect movement, ship gates, commit + publish
+Step 2b: CODEX      Claude Code -> Codex CLI (router skill + specs as refs + agent TOML)
+Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
+Step 3c: PLUGINS    shared/external -> multi-agent-plugins marketplace (rebuild, bump, push)
+Step 3d: DEV-TOOLKIT companion MCP server -> detect movement, run the ship gates, commit + publish
+Step 3e: OFFICE      panel page is current, installed copies match it, toolkit version recorded
 Step 4: WEBSITE     Version + phase/model counts -> {website-host} (i18n + projects.ts)
 Step 5: Commit      Commit + push all changed repos
-Step 6: Report      Summary: synced targets, changed files, deploy status, multi-agent-toolkit version
+Step 6: Report      Synced targets, changed files, deploy status, multi-agent-toolkit version
 ```
 
-**Step 0 is a gate, not a report.** Syncing a blocked install copies one fault onto five surfaces, and the copies are what people then debug. Exit 4 stops too: the layout did not resolve, so nothing was checked, and syncing from an unknown state is worse than not syncing.
-
-If nothing is stale -> report "All targets up to date" and stop.
+If nothing is stale → report "All targets up to date" and stop.
 
-## Special inputs
-
-| Input | Behavior |
-|-------|----------|
-| (no argument) | Full ecosystem sync (default) |
-| `release` | Full sync + version bump + tag + npm publish + website deploy |
-| `multi-agent-toolkit` | Run Step 3d only: gate, commit and publish the companion MCP server |
-| `"change description"` | Apply the description to ALL targets at once |
+Step 0 gate rules and why: `features/doctor.md`.
 
+---
 
 ## Sync rules
 
-1. **Read first**  -  Understand the current state of all targets before making changes
-2. **Preserve file structure**  -  Each target has its own format:
-   - `commands/multi-agent/` SKILL tree + `multi-agent-refs/phases/`: detailed pipeline spec (frontmatter, phases, routing)
-   - `copilot-instructions.md`: general development instructions + pipeline summary section
-   - `multi-agent-pipeline/pipeline/`: generic open-source version (NO personal data)
-3. **Sync shared sections** (Claude <-> Copilot):
-   - Pipeline entries table (base / :autopilot)
-   - Project detection (URL-based + cwd-based)
-   - Figma pipeline flow
-   - Git conventions (author, branch, commit format)
-   - Keychain management (registry, naming convention, multi-agent pattern)
-4. **Do not duplicate**  -  Summary in Copilot, full spec in Claude. Preserve this distinction.
-5. **Report**  -  Show a short diff summary after the sync
-
-## Pipeline Repo Sync Rules (CRITICAL)
-
-1. **Source**: `~/.claude/commands/multi-agent/` + `~/.claude/multi-agent-refs/` + `~/.claude/agents/` + `~/.claude/lib/`
-2. **Target**: `~/multi-agent-pipeline/pipeline/`
-3. **Genericization** (must be applied BEFORE writing to the target):
-   - Jira project key (`prefs.global.defaultJiraKey`) -> `{JIRA_KEY}`, `PROJ` in examples
-   - Personal names/emails -> generic placeholder
-   - Branch names -> `develop`
-   - Project names -> `my-app`
-   - `{JIRA_HOST}`, `{BITBUCKET_HOST}`, `{CONFLUENCE_HOST}`, `{CORP_DOMAIN}` stay as-is
-   - **Verify**: scan for personal/corporate data inside pipeline/ with `grep` -> 0 results
-4. **File mapping**:
-   ```
-   ~/.claude/commands/multi-agent/        -> pipeline/commands/multi-agent/
-   ~/.claude/multi-agent-refs/            -> pipeline/multi-agent-refs/   (refs + pickers, non-command)
-   ~/.claude/commands/sim-test.md         -> pipeline/commands/sim-test.md
-   ~/.claude/agents/*.md                  -> pipeline/agents/
-   ```
-5. **Files NOT synced** (local-only, may contain personal data):
-   - `~/.claude/multi-agent-preferences.json`
-   - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
-   - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh` and `build-stack-plugins.mjs` (generic, synced)
-   - Step 3c (PLUGINS): rebuild the `{owner}/multi-agent-plugins` marketplace from `shared/external` via `build-stack-plugins.mjs` (bumps changed plugins' patch version), then commit + push the plugins repo. On any change also verify help + README freshness: every plugin registers `./skills/tools/help` in plugin.json, `tools/bump.py --check` shows no DRIFT, `tools/validate.py` clean (CHANGELOG entry per bumped version), and pipeline help/READMEs reflect any command-surface change from Step 3
-   - `~/.claude/settings.json`
-   - `~/.claude/multi-agent-refs/registries/`  -  the installer copies gate registries there from `pipeline/skills/shared/external`; the repo already holds the source
-
-
-## Codex Sync (Step 2b)
-
-This step does **not** hand-copy files. The Codex tree is a *transform* of the Claude
-tree, not a mirror: the sub-command specs become reference files (Codex silently
-truncates its skills block  -  see `cross-cli-contract.md` 2.6), every reference to a
-CLI-owned tree is retargeted (`agents/<persona>.md` becomes `.toml`, the dispatcher
-becomes the router skill), the personas under `agents/` are regenerated as TOML with a model +
-reasoning-effort map, and shared state (`logs/`, prefs, `knowledge/`) is deliberately
-left under `~/.claude`.
-
-That transform lives in `install/codex.mjs` and is gate-locked by
-`smoke-codex-install.sh`. Describing it again in prose would give the pipeline two
-definitions of the same thing, and the prose one would rot. So the step runs the
-installer:
-
-```bash
-cd "$HOME/multi-agent-pipeline" && node install.js --codex
-```
-
-Verify:
-
-```bash
-ls -1 "$HOME/.codex/skills" | grep -c '^multi-agent$'                  # want 1
-find "$HOME/.codex/multi-agent-refs/commands" -name SKILL.md | wc -l  # want the command count
-grep -rhoE '(\$HOME|~)/\.claude/(agents|scripts|lib|schemas|commands|multi-agent-refs|rules)' \
-  "$HOME/.codex/skills" "$HOME/.codex/multi-agent-refs" | sort -u     # want empty
-```
-
-MCP is registered by the installer via `codex mcp add multi-agent-toolkit` (idempotent,
-skipped with a warning when `codex` is absent). Never hand-edit
-`~/.codex/config.toml`  -  Codex owns it. Run this AFTER the REPO step, since the
-installer reads the repo tree.
+Read every target's current state before changing anything; keep each target's
+own format; summary in Copilot, full spec in Claude, never duplicated; finish
+with a short diff summary.
 
 ---
 
-## Dev-Toolkit Sync (Step 3d)
-
-The companion MCP server (`multi-agent-toolkit-mcp`) is its own repo with its own registry. Pipeline skills call its tools and several declare a minimum version, so when it moves it has to ship.
-
-**Resolution**: identical to `multi-agent-refactor` Step 0c  -  `prefs.global.devToolkit` first, then the `mcpServers` registration, then skip.
-
-**Detect movement**: dirty working tree, unpushed commits, or no `v<version>` tag for the version in `package.json`. Nothing moved -> report "up to date" and continue.
-
-**Ship gates** (a failure aborts this step only, with file + line; the rest of the sync continues).
-When the toolkit ships its own gate script (`npm run gates` / `scripts/gates.sh`), run that instead of the list below - the repo owns the definition, this skill owns the requirement. The list is the fallback, and the coverage the script must have:
+## Step procedures (read each file before its step)
 
-1. `node --check index.js` plus every `tools/**/*.js`.
-2. stdio handshake (`initialize` -> `notifications/initialized` -> `tools/list`) must answer with a non-zero tool count.
-3. That count must match every advertised count (`package.json` description, README header and per-family rows). Fix the docs, never the gate.
-4. `npm pack --dry-run` must list every `tools/*/` directory the server loads  -  a missing `files[]` entry publishes a broken package.
-5. `grep -rn "console\.log(" index.js tools/` must be empty: stdout carries the JSON-RPC frames, diagnostics go to `console.error`.
-6. Personal-data scan: no absolute `/Users/<name>` paths, no tokens, no corporate hostnames.
-7. Version contract: every pipeline-side minimum version must be satisfied by what is about to ship; a new tool a pipeline skill now needs -> bump that minimum in the same sync.
+| Step | Procedure |
+|---|---|
+| 2b CODEX (runs after Step 3) | `$HOME/.claude/multi-agent-refs/sync/codex.md` |
+| 3 REPO | `$HOME/.claude/multi-agent-refs/sync/repo.md` |
+| 3c PLUGINS | `$HOME/.claude/multi-agent-refs/sync/stack-plugins.md` |
+| 3d DEV-TOOLKIT (and `multi-agent-toolkit` arg) | `$HOME/.claude/multi-agent-refs/sync/dev-toolkit.md` |
+| 3e OFFICE (also release step 9c) | `$HOME/.claude/multi-agent-refs/sync/office.md` |
 
-**Version bump**: patch for fixes and docs, minor for a new tool, major for a removed or renamed tool.
-
-**Ship**: commit with that repo's own convention, tag `v<version>`, push with `--tags`, then publish to the registry from `publishConfig` using a throwaway userconfig  -  never edit `~/.npmrc`, never a bare `npm publish`. The token depends on the registry AND on the package scope: the registry picks the credential type, the scope picks the account. `npm.pkg.github.com` needs a **Classic** GitHub PAT with `write:packages`; `registry.npmjs.org` needs the `npm` key. Resolving on host alone misroutes on any machine with a work and a personal GitHub identity  -  prefer a scope-specific mapping (`github_<scope>`) and fall back to the generic `github` key only when there is one identity.
-
-```bash
-NPMRC=$(mktemp); trap 'rm -f "$NPMRC"' EXIT
-REG=$(node -p "require('./package.json').publishConfig?.registry || 'https://registry.npmjs.org'")
-HOST=${REG#https://}; HOST=${HOST%/}
-SCOPE=$(node -p "(require('./package.json').name.match(/^@([^/]+)/)||[])[1] || ''")
-case "$HOST" in
-  npm.pkg.github.com*) KEY=github; [ -n "$SCOPE" ] && KEY="github_$SCOPE" ;;
-  *) KEY=npm ;;
-esac
-# Fall back to the generic key when no scope-specific mapping exists.
-bash "$HOME/.copilot/lib/credential-store.sh" get "$KEY" >/dev/null 2>&1 || KEY=github
-TOKEN=$(bash "$HOME/.claude/lib/credential-store.sh" get "$KEY")
-[ -n "$TOKEN" ] || echo "ABORT: no '$KEY' token - onboard it via /multi-agent:setup before publishing"
-printf '%s\n' "registry=$REG" "//$HOST/:_authToken=$TOKEN" > "$NPMRC"
-npm publish --userconfig "$NPMRC"
-```
-
-**Approval**: outside autopilot and outside `release`, ask first: commit + push / commit + push + publish / skip. Never ship unapproved band-E work from `multi-agent-refactor` silently.
+Hard rules for Step 3, whatever `repo.md` adds:
 
+- Genericize BEFORE writing to `~/multi-agent-pipeline/pipeline/`; the personal/corporate data scan must return 0 results.
+- Never sync a `local-only: true` SKILL.md, local config, or `~/.claude/office/`. A leaked wrapper, sidecar or localized description aborts the sync.
+- Synced shell follows the BSD / bash 3.2 contract in `repo.md` (`grep -P` banned, keychain I/O only via `credential-store.sh`). A failed smoke gate aborts the push; fix the `~/.claude/` source, re-sync.
 
 ## Website Sync (Step 4)
 
-Propagate version, phase and model counts and feature descriptions to the website.
-
 ```bash
 gh auth switch --user {owner}
 WEBSITE_DIR="$HOME/{website-host}"
-[ ! -d "$WEBSITE_DIR" ] && gh repo clone {owner}/website "$WEBSITE_DIR"
+[ ! -d "$WEBSITE_DIR" ] && gh repo clone {owner}/{website-host} "$WEBSITE_DIR"
 cd "$WEBSITE_DIR" && git pull origin main
 ```
 
-| File | To sync |
-|-------|--------------|
-| `src/lib/i18n.tsx` | Phase count, model count, feature descriptions (EN + TR) |
-| `src/data/projects.ts` | Version number, tagline, description, feature list |
+Files: `src/lib/i18n.tsx` (counts, feature copy EN + TR) and `src/data/projects.ts` (version, features); detail in `overview.md`.
 
 ```bash
-# A commit the platform does not recognise is pushed fine and never built, so the site
-# keeps the old version. {identity} is the one routed to {owner}, not the run's own.
+# {identity} is the one routed to {owner}, not the run's own.
 # Why, signature, recovery: `$HOME/.claude/multi-agent-refs/website-deploy.md`.
 bash "$HOME/.claude/scripts/website-deploy-commit.sh" "{identity.name}" "{identity.email}" "{VERSION}" "$WEBSITE_DIR"
 ```
 
+---
 
 ## Release Flow
 
@@ -207,9 +110,8 @@ When invoked with the `release` argument:
 
 ```
 1. REPO          Claude Code -> pipeline repo (genericized)
-2. VERIFY        Personal data scan -> 0 results
-3. LINT + TEST   ESLint + smoke tests (stale .skill-manifest.json fails here; re-sign
-                 it with sign-skills.sh whenever a SKILL.md moved)
+2. VERIFY        Personal data scan -> 0 results; config-hygiene scan (scan-agent-config.sh) -> 0 HIGH
+3. LINT + TEST   ESLint + smoke tests (re-sign .skill-manifest.json with sign-skills.sh when a SKILL.md moved)
 4. VERSION       package.json version bump (patch/minor/major)
 5. Commit + TAG  git commit + git tag v{VERSION}
 6. PUSH          git push --tags; publish is local (release.yml off)
@@ -217,84 +119,38 @@ When invoked with the `release` argument:
 8. WEBSITE       Version + features -> {website-host} (maintainer identity, build verified Ready)
 9. COPILOT       Copilot CLI instructions + skills sync
 9b. CODEX        Codex CLI router skill + refs + agent TOML (node install.js --codex)
+9c. OFFICE       Step 3e: the installed panel matches the release
 10. Report       Summary: version, touched repos, deploy status
 ```
 
+---
 
 ## Sub-Command Sync (Claude Code <-> Copilot CLI Skills)
 
-> Codex takes the Step 2b path instead; see that section.
+Claude <-> Copilot axis only; Codex takes Step 2b (`cross-cli-contract.md` 2.6).
 
-| Claude Code | Copilot CLI |
-|-------------|-------------|
-| `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
+`~/.claude/commands/multi-agent/{cmd}/SKILL.md` <-> `~/.copilot/skills/multi-agent-{cmd}/SKILL.md`.
 
 **70 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off,
-autopilot-on, autopilot-status, bug-bash, build-optimize, channels, complaint-analysis,
-create-jira, design-check, diff-explain, doctor, estimate, feedback, forget,
-garbage-collect, graph, help, ios-coding-standard, issue, jira, kill,
-language, log, manual-test, model, office-off, office-on, office-pair, office-status, postmortem, prune-logs,
-prune-prompts, purge, refactor, research, resume, review,
-review-analysis, review-issue, review-jira, route-off, route-on,
-route-status, routines, save, scaffold, scan, scenario-audit, search,
-security-review, serve, setup, stack, status, steer, store-ready, sync, test, test-accessibility,
-test-dark-mode, test-dynamic-type, test-gen, test-screenshots, testflight-validation,
-uninstall, update
+analysis, analysis-jira, analysis-resolve, autopilot, autopilot-off, autopilot-on,
+autopilot-status, bug-bash, build-optimize, channels, complaint-analysis, create-jira,
+design-check, diff-explain, doctor, estimate, feedback, forget, garbage-collect, graph, help,
+ios-coding-standard, issue, jira, kill, language, log,
+manual-test, model, office-off, office-on, office-pair, office-status, postmortem, prune-logs, prune-prompts, purge, refactor, research, resume, review, review-analysis, review-issue, review-jira, route-off, route-on, route-status,
+routines, save, scaffold, scan, scenario-audit, search, security-review, serve, setup, stack, status, steer, store-ready, sync, test,
+test-accessibility, test-dark-mode, test-dynamic-type, test-gen, test-screenshots,
+testflight-validation, uninstall, update
 ```
 
-**NOT synced**: `refs/*`  -  Lazy-load references, Claude Code specific
+**NOT synced**: `$HOME/.claude/multi-agent-refs/*`  -  lazy-load references, Claude Code specific
 
-**Claude -> Copilot**: Add SKILL.md frontmatter (`name`, `description`, `user-invocable: true`, `argument-hint`)
-**Copilot -> Claude**: Simplify the frontmatter (`description` + `allowed-tools`), add `$ARGUMENTS`
+Frontmatter conversion between the two forms: `overview.md`, "Sub-command paths".
 
+---
 
 ## Keychain Token Access
 
-| Operation | Token Source |
-|-------|---------------|
-| `gh` CLI (personal) | `{owner}` gh auth (Keychain) |
-| `gh` CLI (work) | `${USER}_{work-gh-alias}` gh auth (Keychain) |
-| npm publish | `NODE_AUTH_TOKEN`  -  `GITHUB_TOKEN` in CI, Keychain PAT locally |
-| multi-agent-toolkit publish (Step 3d) | scope-resolved key (`github_<scope>`, else `github`, else `npm`) -> throwaway `--userconfig`, registry from that repo's `publishConfig` |
-
-```bash
-gh auth switch --user {owner}  # for personal repos
-```
-
-
-## Pre-flight the token scope
-
-GitHub reports a token's scopes on any authenticated request, so check before
-uploading instead of reading it out of a 403:
-
-```bash
-curl -sI -H "Authorization: token $TOKEN" https://api.github.com/user \
-  | grep -i '^x-oauth-scopes:' | grep -q 'write:packages'
-```
-
-Candidate order for `npm.pkg.github.com`, because storage location and scope are
-not correlated: `github_<scope>` from the mapping, then `gh auth token -u <scope>`
-(gh's own OAuth token often carries `write:packages` when a hand-made PAT does
-not), then the generic `github` key only on a single-identity machine. Take the
-first candidate whose scopes include `write:packages` AND whose login matches the
-package scope. If none qualifies, stop before publishing and report each candidate
-with the login it resolved to and the scope it was missing  -  that is the
-actionable output, not a 403 body.
-
-## Publish 403s: two causes, two fixes
-
-Neither message says "wrong token" plainly, and they need opposite responses:
-
-- `Unauthorized: As an Enterprise Managed User, you cannot access this content`  -
-  the resolved token belongs to a corporate EMU account, which cannot publish to a
-  personal scope at all. No scope grant fixes this; map the personal account's PAT
-  under `github_<scope>`.
-- `The token provided does not match expected scopes`  -  right account, missing
-  permission. Regenerate as a **Classic** PAT with `write:packages`
-  (plus `repo` for a private package) and re-onboard through setup.
-
-Always report which of the two occurred. "Permission denied" alone sends the user
-to regenerate a token that was never the problem.
+Token sources per operation: `overview.md`. Personal repos run under
+`gh auth switch --user {owner}`; tokens are read only through `credential-store.sh`.

package/pipeline/skills/shared/external/alarmkit/SKILL.md

@@ -58,39 +58,12 @@ The user must grant access. The app may ask up front, or AlarmKit will prompt
 the first time something is scheduled. If neither prompt ends in approval, no
 alarm is scheduled and nothing will ring.
 
-```swift
-import AlarmKit
-
-func ensureAlarmAccess() async -> Bool {
-    let center = AlarmManager.shared
-    switch center.authorizationState {
-    case .authorized:
-        return true
-    case .denied:
-        return false
-    case .notDetermined:
-        let answer = try? await center.requestAuthorization()
-        return answer == .authorized
-    @unknown default:
-        return false
-    }
-}
-
-func watchAlarmAccess(onChange: @escaping (Bool) -> Void) async {
-    for await state in AlarmManager.shared.authorizationUpdates {
-        switch state {
-        case .authorized: onChange(true)
-        case .denied, .notDetermined: onChange(false)
-        @unknown default: onChange(false)
-        }
-    }
-}
-```
-
 `AlarmManager.AuthorizationState` has three cases: `.notDetermined`,
 `.denied` and `.authorized`. `authorizationState` is a synchronous read;
 `authorizationUpdates` is an async sequence of changes.
 
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
+
 ## Alarm or timer?
 
 | | `.alarm` | `.timer` |
@@ -126,38 +99,6 @@ let schoolRun = Alarm.Schedule.relative(.init(time: sixAM, repeats: .weekly(clas
 
 ### Configuring and scheduling
 
-```swift
-import AlarmKit
-import SwiftUI
-
-struct ShiftInfo: AlarmMetadata {
-    var shiftName: String
-}
-
-@available(iOS 26.1, *)
-func scheduleShiftAlarm() async throws -> Alarm {
-    let dawn = Alarm.Schedule.Relative.Time(hour: 5, minute: 30)
-    let alert = AlarmPresentation.Alert(
-        title: "Early shift",
-        secondaryButton: AlarmButton(text: "Later", textColor: .white, systemImageName: "zzz"),
-        secondaryButtonBehavior: .countdown
-    )
-    let attributes = AlarmAttributes(
-        presentation: AlarmPresentation(alert: alert),
-        metadata: ShiftInfo(shiftName: "Warehouse A"),
-        tintColor: .teal
-    )
-    let config = AlarmManager.AlarmConfiguration(
-        countdownDuration: Alarm.CountdownDuration(preAlert: nil, postAlert: 9 * 60),
-        schedule: .relative(.init(time: dawn, repeats: .never)),
-        attributes: attributes,
-        sound: .default
-    )
-    let center = AlarmManager.shared
-    return try await center.schedule(id: UUID(), configuration: config)
-}
-```
-
 Here `postAlert` is what makes the secondary button a snooze: pressing it
 starts a nine-minute countdown and then rings again.
 
@@ -170,6 +111,8 @@ right:
   `secondaryButtonBehavior: .countdown` plus `CountdownDuration.postAlert`.
   Pass one only with `.custom` behavior or when the app must do its own work.
 
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
+
 ### Lifecycle and transitions
 
 The normal path is scheduled, then countdown, then alerting. From countdown
@@ -189,30 +132,7 @@ anywhere.
 
 A timer rings once a duration has passed and always shows its countdown.
 
-```swift
-import AlarmKit
-import SwiftUI
-
-struct BrewInfo: AlarmMetadata {
-    var blend: String
-}
-
-@available(iOS 26.1, *)
-func startSteepTimer() async throws {
-    let presentation = AlarmPresentation(
-        alert: .init(title: "Tea is ready"),
-        countdown: .init(title: "Steeping"),
-        paused: .init(title: "Steeping paused",
-                      resumeButton: AlarmButton(text: "Resume", textColor: .white, systemImageName: "play.fill"))
-    )
-    let attributes = AlarmAttributes(presentation: presentation,
-                                     metadata: BrewInfo(blend: "Sencha"),
-                                     tintColor: .green)
-    let threeMinutes = AlarmManager.AlarmConfiguration.timer(duration: 180, attributes: attributes, sound: .default)
-    let center = AlarmManager.shared
-    _ = try await center.schedule(id: UUID(), configuration: threeMinutes)
-}
-```
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
 
 ### CountdownDuration
 
@@ -292,46 +212,17 @@ the alerting UI from it; the widget extension may draw countdown and paused.
 | `AlarmPresentation.Countdown(title:pauseButton:)` | counting down | no |
 | `AlarmPresentation.Paused(title:resumeButton:)` | paused | no |
 
-Combine them with `AlarmPresentation(alert:countdown:paused:)`:
+Combine them with `AlarmPresentation(alert:countdown:paused:)`.
 
-```swift
-import AlarmKit
-import SwiftUI
-
-@available(iOS 26.1, *)
-func workoutPresentation() -> AlarmPresentation {
-    let again = AlarmButton(text: "Again", textColor: .white, systemImageName: "repeat")
-    let hold = AlarmButton(text: "Hold", textColor: .orange, systemImageName: "pause.fill")
-    let go = AlarmButton(text: "Go", textColor: .orange, systemImageName: "play.fill")
-    return AlarmPresentation(
-        alert: .init(title: "Rest over", secondaryButton: again, secondaryButtonBehavior: .countdown),
-        countdown: .init(title: "Resting", pauseButton: hold),
-        paused: .init(title: "Rest on hold", resumeButton: go)
-    )
-}
-```
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
 
 ### Metadata
 
-```swift
-import AlarmKit
-import SwiftUI
-
-struct PlantInfo: AlarmMetadata { var plantName: String; var litres: Double }
-struct NoAlarmData: AlarmMetadata {}
-
-@available(iOS 26.1, *)
-func plantAttributes() -> (AlarmAttributes<PlantInfo>, AlarmAttributes<NoAlarmData>) {
-    let look = AlarmPresentation(alert: .init(title: "Water the fern"))
-    let withData = AlarmAttributes(presentation: look, metadata: PlantInfo(plantName: "Fern", litres: 0.5), tintColor: .mint)
-    let plain = AlarmAttributes<NoAlarmData>(presentation: look, metadata: nil, tintColor: .mint)
-    return (withData, plain)
-}
-```
-
 When there is nothing to carry, declare an empty type that conforms to
 `AlarmMetadata` and pass `metadata: nil`.
 
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
+
 ### AlarmPresentationState
 
 `AlarmPresentationState` is the alarm Live Activity's `ContentState`, owned and
@@ -398,50 +289,7 @@ Setup stays with what Apple documents: `NSAlarmKitUsageDescription` and
 `AlarmManager` authorization. Do not require extra keys or a
 `com.apple.developer.alarmkit` entitlement unless a current Apple source says so.
 
-```swift
-import ActivityKit
-import AlarmKit
-import SwiftUI
-import WidgetKit
-
-struct CoachInfo: AlarmMetadata {
-    var drill: String
-}
-
-struct CoachAlarmWidget: Widget {
-    var body: some WidgetConfiguration {
-        ActivityConfiguration(for: AlarmAttributes<CoachInfo>.self) { context in
-            Text(context.attributes.metadata?.drill ?? "Timer")
-                .padding()
-        } dynamicIsland: { context in
-            DynamicIsland {
-                DynamicIslandExpandedRegion(.center) {
-                    let heading = context.attributes.presentation.alert.title
-                    Text(heading)
-                }
-                DynamicIslandExpandedRegion(.bottom) {
-                    if case .countdown(let run) = context.state.mode {
-                        Text(timerInterval: Date.now...run.fireDate, countsDown: true)
-                    }
-                }
-            } compactLeading: {
-                Image(systemName: "alarm.fill")
-            } compactTrailing: {
-                Image(systemName: "alarm.fill")
-            } minimal: {
-                Image(systemName: "alarm.fill")
-            }
-        }
-    }
-}
-
-@main
-struct CoachWidgets: WidgetBundle {
-    var body: some Widget {
-        CoachAlarmWidget()
-    }
-}
-```
+Code for this section: [AlarmKit code](references/alarmkit-code.md).
 
 ## Common mistakes
 
@@ -485,6 +333,7 @@ struct CoachWidgets: WidgetBundle {
 
 ## References
 
+- [AlarmKit code](references/alarmkit-code.md): open for the code behind authorization, scheduling, countdown timers, presentation, metadata and the Live Activity widget.
 - [AlarmKit patterns](references/alarmkit-patterns.md) - complete alarm and timer flows, authorization manager, state store, widget extension, recurrence, snooze and custom actions, Info.plist, errors
 - [AlarmKit](https://developer.apple.com/documentation/alarmkit)
 - [AlarmManager](https://developer.apple.com/documentation/alarmkit/alarmmanager)