refactor!: converge every package on the tutorial contract; numbered tutorial replaces the doc set

.changeset/simplification-major.md

@@ -0,0 +1,52 @@
+---
+'@looprun-ai/core': major
+'@looprun-ai/mastra': major
+'@looprun-ai/models': major
+'@looprun-ai/eval': major
+'@looprun-ai/server': major
+'@looprun-ai/vercel': major
+'looprun': major
+---
+
+**Breaking: the public API is now exactly what the tutorial teaches.**
+
+Every package barrel was converged onto a single contract — the symbols taught by
+`docs/tutorial/01`–`06`. Names that no package documented and no consumer imported were deleted;
+names that only the runtime needs moved behind `@looprun-ai/core/internal`. Each barrel is now
+pinned by a surface-lock test, so it cannot drift back — with one gap: the published `./testing`
+subpaths of `@looprun-ai/core` and `@looprun-ai/mastra` re-export by wildcard (~27 symbols) and
+carry no lock yet, so those two are the one surface that can still drift. Locking them is a
+follow-up.
+
+| package | public exports | before |
+|---|---|---|
+| `@looprun-ai/core` | 51 taught (+11 type-closure riders) | 107 named + 2 wildcard re-exports |
+| `@looprun-ai/mastra` | 7 + core flow-through | 25 named + 1 wildcard |
+| `@looprun-ai/models` | 8 (+2 riders) | 24 |
+| `@looprun-ai/eval` | 19 (+9 riders) | 52 |
+| `@looprun-ai/server` | 4 (+3 riders) | 13 |
+
+**Why `looprun` and `@looprun-ai/vercel` are also major.** The `looprun` umbrella re-exports core, so
+its root and `./core` barrels narrow exactly as core does — the break reaches consumers through the
+facade, not only through the scoped package. `@looprun-ai/vercel` has no API change at all (its
+factory still throws); it is major because the changeset config links `looprun` and `@looprun-ai/*`
+into one version group, so the whole set moves together.
+
+**What moved rather than vanished.** `@looprun-ai/core/internal` is a new, explicitly unstable
+subpath carrying the runtime primitives (ledger, turn machine, trunk internals, `GUARD_CATALOG`,
+`GuardExecutionError`). It exists so in-repo tooling and forks keep working; it carries no
+compatibility promise across releases.
+
+**What was cut outright.** The `coherence` guard family and its trunk section were removed
+(-396 LOC); the trunk fold was proven byte-identical across the change. Runtime helpers that had
+been exported from `@looprun-ai/core` without ever being documented or imported — including
+`uploadDisplayLabels` and `isReplyOnly` — are now module-local to `renderTurnPrompt`. Package
+`CHANGELOG.md` entries that announced them stay unedited: they are an accurate record of what those
+versions shipped.
+
+**Also in this release.** `packages/core/src/guards.ts` was split into `guards/` (30 catalogued
+factories, all files ≤500 lines); `@looprun-ai/mastra`'s `agent.ts` was split; and the nine
+superseded documents under `docs/` were replaced by the six-chapter tutorial, every code block of
+which is compiled in CI against the published packages.
+
+Migration table for external consumers: `docs/superpowers/specs/2026-07-28-migration-notes.md`.

.github/pull_request_template.md

@@ -20,7 +20,7 @@
 - [ ] The coverage ratchet was **not lowered** (`proof completeness · <kind>` still complete)
 - [ ] Proof record committed via `pnpm proofs:record` (`governance/proofs/*.md`, `verdict: PASS`)
 - [ ] `governance/MATRIX.md` regenerated (`pnpm proofs:matrix`) and committed
-- [ ] If a guard kind changed: `packages/core/GUARDS.md` **and** `skills/agentspec/references/guard-catalog.md` updated (the parity test enforces it)
+- [ ] If a guard kind changed: its `GUARD_CATALOG` entry in `packages/core/src/guards/catalog.ts` added/updated and `pnpm docs:guards` re-run (the parity test enforces the entry; the drift gate enforces the regeneration)
 - [ ] Drift lint clean (`node tests/no-bench-drift.test.mjs`)
 - [ ] Docs-tooling-only change — no proof record needed
 

.github/workflows/ci.yml

@@ -27,6 +27,9 @@ jobs:
       # no-bench-drift) are ordinary vitest files — they RUN on every push/PR, not just exist.
       - run: pnpm -r --if-present test
       - run: node tests/no-bench-drift.test.mjs
+      # Tutorial chapter 04 is GENERATED from GUARD_CATALOG (needs the build above): a kind whose
+      # catalog entry changed without the chapter being re-rendered fails here.
+      - run: node scripts/gen-guards-chapter.mjs --check
       # Governance: the deterministic guard-proof suite + the generated matrix must be in sync.
       - run: pnpm test:proofs
       - run: node scripts/proofs/gen-matrix.mjs --check

CONTRIBUTING.md

@@ -40,8 +40,11 @@ Author the proof **before** the implementation — the proof cases are the spec.
    new kind with **positive / negative / neutral** L1 cases plus at least one **L3 loop** case (and the
    collective non-interference expectation). See
    [`skills/looprun-governance/references/proof-case-authoring.md`](skills/looprun-governance/references/proof-case-authoring.md).
-2. **Implement** the guard in `packages/core/src/guards.ts` until the cases pass.
-3. **Update the catalog doc**: `packages/core/GUARDS.md`.
+2. **Implement** the guard in the matching `packages/core/src/guards/<category>.ts` until the cases pass.
+3. **Add the catalog entry**: a `GUARD_CATALOG` row in `packages/core/src/guards/catalog.ts` (name,
+   category, hook, summary, when-to-use, a compilable example), then `pnpm docs:guards` to regenerate
+   the tutorial's guard chapter and its compiled examples. The catalog is the vocabulary of record;
+   `packages/core/GUARDS.md` is maintainer internals and carries no kind list.
 4. **Run the suite**: `pnpm test:proofs` (green, ratchet not lowered).
 5. **Generate the record**:
    ```bash