## What
Fix 44 broken intra-repo links across 7 files under `docs/`, surfaced by
a `docs/` markdown link audit. `mkdocs.yml` has `strict: false`, so the
broken links slipped past CI — but they break GitHub-raw viewing and
agent file-reading (the repo treats pointer rot in base docs as a
defect).
## Two pointer-rot classes
1. **41× `](skills/<name>.md)` → `](../skills/<name>/SKILL.md)`** —
skills live at `skills/<name>/SKILL.md`, never `skills/<name>.md`, and
`docs/` is one level deep so the target needs `../`. Several links
already had the **correct link text** (e.g.
`[skills/pre-mortem/SKILL.md](skills/pre-mortem.md)`) — only the href
was wrong, confirming intent. Special case: `skills/catalog.md` →
`SKILLS.md` (`docs/SKILLS.md` = the complete 82-skill reference).
2. **3× `](cli/commands.md)` → `](../cli/docs/COMMANDS.md)`** — the
generated CLI command doc.
Files: `GLOSSARY.md`, `index.md`, `context-lifecycle.md`,
`behavioral-discipline.md`, `create-your-first-skill.md`,
`context-packet.md`, `software-factory.md`.
**Not touched:** the intentional placeholder links in
`docs/standards/markdown-style-guide.md` (syntax demos: `url`,
`image.png`, `./other-doc.md`, etc.).
## Verification
- `docs/` broken-link scan: **44 → 0** outside the style-guide
placeholders.
- `markdownlint-cli2` on all 7 files: **0 errors**.
- Pure link-href changes (44 insertions / 44 deletions); no prose or
behavior change.
Closes-scenario: ag-28dp#docs-link-rot
Bounded-context: BC1-Corpus
Evidence: ag-28dp
## What
Gut **context poison** — agent-facing docs that route a working agent at
DEAD mechanisms. This poisoned a live fleet-operating session (the bo
driver building the go-dark supervisor) into proposing `ao rpi` as a
continuity-loop worker. Found via a 5-way parallel poison fan-out.
**Scope: operational-surgical** (Bo's explicit call). Gut the
agent-facing *operational* guidance + *factual* errors; **LEAVE** the
README/`docs/3.0.md` product narrative (Gas-City-as-reference-substrate
is coherent, ADR-backed product design — a different altitude from Bo's
live fleet).
## Changes (10 files, surgical)
**Tier A — operational guidance (the poison that bit me):**
- `CLAUDE.md` Session Constraints: "route multi-phase work through `ao
rpi`" → the live substrate (NTM + MCP Agent Mail + `continuity-loop`);
`gc` reframed as optional-out-of-session, **not** the live substrate.
Kept the accurate "bridge REMOVED" + "load-bearing legacy" lines.
- `AGENTS.md`: dropped the deleted "scheduling daemon" (ADR-0009).
- `AGENTS-RUNTIME.md`: `ao rpi serve --help` → the real `ao` command
surface.
**Tier B — hookless-factual** (3.0 installs no hooks by default):
hookless banners on `ARCHITECTURE.md` + `reference.md` (surgical vs.
rewriting diagram internals); corrected SessionStart-hook prose in
`context-packet.md` + `vs-claude-flow.md`.
**Tier C — retired `/dream` shown as live:** marked retired in
`evolve`/`harvest`/`using-agentops` (compounding moved to Gas City).
`curate` **intentionally left** — its `--mode=dream` is the forward
replacement, not poison.
## Guardrails
- Does **not** claim `ao rpi` was deleted — the command still compiles
(`loop`/`phased`/`serve` exist); only its role as the *live workflow* is
corrected.
- registry.json unaffected (skill **bodies** only; `generate-registry.sh
--check` = OK).
## Evidence
`bash scripts/generate-registry.sh --check` → OK. Diff is 20 insertions
/ 16 deletions across 10 files.
Bounded-context: BC1-Corpus (agent-facing context docs)
Evidence: this PR diff + the parallel fan-out inventory
Closes: ag-sjz8
🤖 Generated with [Claude Code](https://claude.com/claude-code)
## What
First slice of the hooks-runtime decoupling (ag-t1ca) — the
small/surgical files. Every claim verified against the repo (`hooks/`
absent, `ao hooks` / `ao init --hooks` absent, `make sync-hooks` now
embeds skills/lib not hooks).
- **agent-footguns.md:27** — `make sync-hooks` trigger list dropped dead
`hooks/` + `lib/hook-helpers.sh`; now lists what the target actually
copies into `cli/embedded/`.
- **context-packet.md:498** — `hooks/session-start.sh` → `ao session
bootstrap` (hookless).
- **seed-definition.md** — seed element #3 "Hook readiness" → "Lifecycle
stages (hookless)" (matched the doc's own §3); dropped non-existent `ao
init --hooks` flag; reframed two "hooks enforce/fire automatically"
lines to CI-gates + explicit lifecycle rules.
## Verify-first SAVES (left unchanged — consistent with executable
truth)
- **agents-operator-guide.md** — `check-agents-write-surfaces.sh` still
lists `hooks/` in its scan scope, so the doc matches the script (the
vestigial scan is a code-cleanup item, not doc drift).
- **SCHEMAS.md** — `hooks-manifest.v1.schema.json` already correctly
labeled "legacy / 3.0 hookless".
## Remaining in ag-t1ca (re-scoped, NOT in this PR)
The 6 large files need a dedicated careful pass: ARCHITECTURE.md,
agentops-system-map.md, context-lifecycle.md, leverage-points.md,
troubleshooting.md, INCIDENT-RUNBOOK.md.
Closes-scenario: ag-t1ca#small-files
Bounded-context: BC1-Corpus
Evidence: docs/context-packet.md
## Docs site — boshu2.github.io/agentops
- Replace Jekyll minima with MkDocs Material (slate dark palette default)
- Landing hero scoped to .landing-hero (no gradient bleed on inner pages)
- Section landings (getting-started, architecture, reference, contracts, levels) with narrative ledes
- Generate skill catalog + per-skill pages from skills/*/SKILL.md at build
- Generate CLI reference from cli/docs/ at build (fails build on missing source)
- Fix every internal link via one-shot migration (scripts/migrations/2026-04-19-fix-docs-links.py)
- Wire mkdocs build --strict into pre-push gate (Check 25a)
- Replace .github/workflows/pages.yml with .github/workflows/docs.yml (actions/deploy-pages)
- README + docs/CONTRIBUTING updated with docs-build toolchain on-ramp
- tests/docs/validate-links.sh patched to understand mkdocs-generated paths
## RPI orchestrator strict-delegation contract
- Strict sub-skill delegation is now the default for /rpi, /discovery, /validation. No --full flag — always on.
- Canonical contract in skills/shared/references/strict-delegation-contract.md (plus Codex mirror)
- Forged learning with detection phrases + corrective actions (ao-inject-ready)
- Rename --no-lifecycle -> --no-scaffold in /discovery (Claude + Codex) with deprecation alias through v2.40.0
- Harden inline-work hotspots with orchestrator-owned markers in /crank STEPS 3a.3, 6.5, 8.7 + Inline Work Policy footer
- Flag consistency: --auto and --interactive scopes documented; --complexity syntax formalized
- CHANGELOG [Unreleased] documents + scaffolds; runtime hook enforcement explicitly deferred
## fix(hooks): go-test-precommit skips when no Go files staged
- Previously ran go vet + go build unconditionally, blocking non-Go commits when Go toolchain was missing or at a different version
- Now checks staged diff and exits cleanly if no *.go or go.{mod,sum,work} files are staged
- Applied to both hooks/ (source) and cli/embedded/hooks/ (synced)
Provenance: full RPI lifecycle with strict delegation at every phase boundary (Phase 1 Skill(discovery) -> Phase 2 Skill(crank) -> Phase 3 Skill(validation) -> Skill(vibe), Skill(post-mortem), Skill(retro)).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fix right-side │ border alignment in box diagrams. Three fix types:
- Trailing space adjustment for border alignment
- Box border widening for content that exceeded width
- Bottom border dash count matching top border
Bo