docs: align documentation with the create-snapshots + bootstrap pipeline

.specify/memory/constitution.md

@@ -31,13 +31,13 @@ Every step of the bootstrap pipeline must use either:
 Examples currently in use:
 
 - `db-synthesizer` (upstream `ouroboros-consensus`, mode (a)) — fixture chain DB synthesis
+- `db-analyser` (upstream `ouroboros-consensus`, mode (a)) — bundled in the runtime image as the engine `amaru create-snapshots` drives
 - `header-extractor` (in-repo, mode (b), consumes `ouroboros-consensus` as a library) — chain DB queries
-- `ledger-state-emitter` (in-repo, mode (b), consumes `ouroboros-consensus` and `cardano-ledger` as libraries) — Amaru-compatible ledger-state emission for the pinned node release
-- `amaru` ([`pragma-org/amaru`](https://github.com/pragma-org/amaru), mode (a)) — convert / import / run
+- `ledger-state-emitter` (in-repo, mode (b), consumes `ouroboros-consensus` and `cardano-ledger` as libraries) — standalone Amaru-compatible ledger-state emission for the pinned node release; no longer in the producer pipeline
+- `amaru` ([`pragma-org/amaru`](https://github.com/pragma-org/amaru), mode (a), currently consumed via the `lambdasistemi/amaru` `feat/testnet-bootstrap` branch — upstream main plus a minimal upstreamable delta — SHA-pinned in `flake.lock`) — create-snapshots / bootstrap / run
 
-`db-analyser` and `snapshot-converter` remain available for historical
-Phase 0 checks, but they are not in the bootstrap-producer runtime
-image after the R-011 pivot.
+`snapshot-converter` remains available for historical Phase 0 checks,
+but it is not in the bootstrap-producer runtime image.
 
 What is **not** permitted:
 
@@ -118,10 +118,18 @@ Amendments require a PR, a rationale in the PR description, and the
 All PRs must verify compliance with these principles. When the
 constitution and a convenience are in conflict, the constitution wins.
 
-**Version**: 1.2.0 | **Ratified**: 2026-04-27 | **Last Amended**: 2026-04-29
+**Version**: 1.3.0 | **Ratified**: 2026-04-27 | **Last Amended**: 2026-06-12
 
 ### Amendment log
 
+- **1.3.0 (2026-06-12)**: Principle II examples updated after the
+  producer migrated to upstream `amaru create-snapshots` +
+  `amaru bootstrap`. `db-analyser` returned to the runtime image as the
+  engine that `create-snapshots` drives; `ledger-state-emitter` is
+  retained as a standalone tool but is no longer the runtime
+  ledger-state producer; the Amaru example commands are now
+  create-snapshots / bootstrap / run, consumed via the SHA-pinned
+  `lambdasistemi/amaru` `feat/testnet-bootstrap` branch.
 - **1.2.0 (2026-04-29)**: Principle II examples updated after the
   Phase 2 R-011 pivot. `ledger-state-emitter` is now the runtime
   ledger-state producer, consuming `ouroboros-consensus` and

AGENTS.md

@@ -0,0 +1,54 @@
+# Repository Agent Guide
+
+## What this repo is
+
+`amaru-bootstrap` builds the
+`ghcr.io/lambdasistemi/amaru-bootstrap-producer` Docker image and the
+tools inside it, used to start relay-only
+[Amaru](https://github.com/pragma-org/amaru) nodes on custom Cardano
+testnets (primarily the Antithesis testnets in
+`cardano-foundation/cardano-node-antithesis`). Amaru cannot sync such
+testnets from genesis, so the `bootstrap-producer` orchestrator reads a
+cardano-node ChainDB, drives `amaru create-snapshots` and
+`amaru bootstrap`, and commits a bundle of ledger/chain stores that
+`amaru run` opens. Everything is pinned to one cardano-node release at a
+time (currently 10.7.1) because ledger-state CBOR drifts between
+releases.
+
+Read [`.specify/memory/constitution.md`](.specify/memory/constitution.md)
+before making design decisions — it gates them (no forks of upstream
+Cardano code, stock tools + custom orchestration, SHA pinning, Nix-first).
+
+## How to work here
+
+- Build/test everything CI builds: `just build-gate`
+- Full local CI mirror (Build Gate + Phase 0 smoke verdict + Docker live
+  verifier): `just ci`
+- Phase 0 smoke test against the vendored fixture: `just smoke`
+- One flake check: `nix build .#checks.x86_64-linux.<name>` (never
+  `nix develop -c cabal test` in CI)
+- Run a tool: `nix run .#bootstrap-producer`, `.#smoke-test`,
+  `.#header-extractor`, `.#ledger-state-emitter`, `.#amaru`,
+  `.#db-synthesizer`, `.#db-analyser`, `.#snapshot-converter`
+- Shell lint: `just shellcheck`; scripts are bash with
+  `set -euo pipefail`, shellcheck-clean
+- Haskell: GHC 9.6, fourmolu (70-char limit, leading commas/arrows),
+  Haddock on all exports, Hackage-ready (`cabal check` clean)
+- Pinning discipline: cabal `source-repository-package` entries carry
+  nix32 `--sha256` (not SRI); Docker images are tagged by commit SHA,
+  never `:main`/`:latest`
+- Workflow: every ticket runs through speckit
+  (`specify` → `plan` → `tasks` → `implement`); specs live under
+  `specs/`; linear history on `main` (rebase merge only); `Build Gate`
+  is the required CI check
+- CI runs on self-hosted `nixos` runners; the docs site deploys via
+  `mkdocs gh-deploy` from `.github/workflows/deploy-docs.yml`
+
+## Skills
+
+Activatable procedures live under `skills/`. Load the one whose
+description matches your task:
+
+- [`skills/amaru-bootstrap-guide/`](skills/amaru-bootstrap-guide/SKILL.md)
+  — repository map, build/test/run commands, code navigation, and how to
+  use the bootstrap-producer image and its tools.

CLAUDE.md

@@ -1,42 +1,17 @@
 # amaru-bootstrap
 
-Project-specific guidance for AI agents. **Read [`.specify/memory/constitution.md`](./.specify/memory/constitution.md) first** — it gates all design decisions.
-
-## Workflow
-
-- Every ticket runs through speckit: `speckit-specify` -> `speckit-plan` -> `speckit-tasks` -> `speckit-implement`. No implementation without a spec on disk.
-- One worktree per branch. Main repo (`/code/amaru-bootstrap`) stays on `main`; feature work happens in `/code/amaru-bootstrap-<short>`.
-- Linear history on `main` (rebase merge only).
-- Branch protection: `Build Gate` required, admin bypass.
-
-## Tooling
-
-- **Nix-first**: every binary built and run via the flake. Never `pip install`, `cargo install`, `cabal install`, `curl | sh`.
-- **Haskell tools** (`db-synthesizer`, `db-analyser`): haskell.nix + CHaP, declared in `cabal.project`, exposed via `nix/iog-tools.nix`.
-- **Rust tool** (`amaru`): crane wrapping `pragma-org/amaru` flake input, exposed via `nix/amaru.nix`.
-- **Orchestrator** (`scripts/smoke-test.sh`): bash, shellcheck-clean, `set -euo pipefail`.
-- **CI**: `runs-on: nixos`. Build Gate first; downstream jobs gated. Never `nix develop -c cabal test` in CI — always `nix build .#checks.<system>.<name>`.
-
-## Pinning discipline (constitution Principle III)
-
-- All Haskell SRPs in `cabal.project` carry `--sha256:` in **nix32** format (NOT SRI). Use `nix flake prefetch` then `nix hash convert --to nix32`.
-- All Docker images in any production-facing context tagged by commit SHA. `:main` is a bug.
-
-## Speckit phase budgets
-
-- `plan.md` <= 200 lines. Push detail into `research.md`, `data-model.md`, `contracts/`, `quickstart.md`.
-- After each `speckit-implement` phase, compact a Status block back into `plan.md`.
-
-## Active feature
-
-- `001-snapshot-format-smoke` — Phase 0 hypothesis-validation smoke test. See [`specs/001-snapshot-format-smoke/`](./specs/001-snapshot-format-smoke/).
-
-<!-- MANUAL ADDITIONS START -->
-<!-- MANUAL ADDITIONS END -->
-
-## Active Technologies
-- Bash 5.x (orchestrator script); Haskell GHC 9.6.x (existing tools, plus the small header-extractor tool from R-001) (003-amaru-bootstrap-producer)
-- filesystem only — read cluster's chain DB, write the bundle to a docker volume. No database, no state. (003-amaru-bootstrap-producer)
-
-## Recent Changes
-- 003-amaru-bootstrap-producer: Added Bash 5.x (orchestrator script); Haskell GHC 9.6.x (existing tools, plus the small header-extractor tool from R-001)
+Agent guidance for this repository lives in [AGENTS.md](AGENTS.md).
+Start there; it covers what the repo is, the working commands, the
+constitution gate, and the skills under `skills/`.
+
+Claude-specific notes only below this line.
+
+- Read [`.specify/memory/constitution.md`](.specify/memory/constitution.md)
+  before design decisions — it gates them.
+- Every ticket runs through speckit: `speckit-specify` ->
+  `speckit-plan` -> `speckit-tasks` -> `speckit-implement`. No
+  implementation without a spec on disk. `plan.md` <= 200 lines; push
+  detail into `research.md`, `data-model.md`, `contracts/`,
+  `quickstart.md`, and compact a Status block back into `plan.md`
+  after each implement phase.
+- One worktree per branch; the main checkout stays on `main`.