# M6 Plan — stage-setting: `spt-releases`, dev docs, v0.1 release

> **Status: ✅ COMPLETE (2026-06-05).** D1–D7 all delivered same-day; the
> acceptance below ran green against the LIVE published release (one-liner
> install → `spt 0.1.0` → quickstarts as written → llms/schema fetch from the
> canonical URL → both SignedRelease assets + a v0.1.1-shaped test release +
> a recovery-key-signed metadata all verified against the embedded two-key
> anchor with the real ceremony keys). spt-releases is public; Pages live;
> release runbook: `docs/RELEASE-RUNBOOK.md`.
> Authored from the grill session of 2026-06-05 (decisions committed `1922fa4`).

> **Just-in-time, lightweight** — same pattern as `M0…M5-PLAN.md`.
> Branch: `dev-freeform`. Authoritative architecture: **ADR-0014** (publish-target
> repo + lapse-proof canonical URL), **ADR-0015** (two-key release signing),
> **CONTEXT §Installation** (v0.1 phasing), **CONTEXT §Project infrastructure**
> (`spt-releases`, licensing split), **`docs/DOCS-STRATEGY.md` §v0.1 deployment
> scope** (Tier 1/Tier 2).

> **Upstream is done:** M0–M5 ✅ (all v1 core milestones; final proof
> `[twohost]` run `26998500755` on `5bc996c`). M6 is the **preliminary phase
> before the v1 acceptance proof** — it sets the stage for third-party adapter
> development so the `spt-claude-code` downstream project (and any third party)
> can build against a published, documented, installable spt-core.

## Scope decisions (user, 2026-06-05 grill — all locked)

1. **Repo topology:** source stays private long-term; `SaberMage/spt-releases`
   (created private, flips public anytime) is the pure publish target — README,
   GitHub Releases, rendered docs. Doc truth + CI generation stay here (ADR-0014).
2. **Canonical URL:** `https://sabermage.github.io/spt-releases` permanent, baked
   everywhere; **no custom domain on Pages** (lapse-proof). `spt-core.decidel.com`
   = optional human-facing redirect only (ADR-0014).
3. **Installer (minimal, option b):** scripts download latest release →
   **sha256-check** → place binary → register *user* PATH. **Non-interactive
   contract** (the same script *is* every adapter's pack-in on-demand install — no
   second mechanism; any future interactive element requires a flagged
   non-interactive mode). OS-service registration **deferred** (daemon auto-start
   covers dev-stage use). Full ed25519 verification is `spt update`'s job after
   first install; first-fetch trust = HTTPS + GitHub.
4. **Third-party surface = the binary** (manifest + `spt api`). SDK crates are
   first-party-only while source is private; crates.io publish of the 3 SDK crates
   is the explicit later path. rustdoc still ships → Pages (no docs.rs).
5. **Docs scope = Tier 1** (DOCS-STRATEGY §v0.1): mental model · human quickstart ·
   adapter quickstart (via `mock-adapter`) · **complete harness-contract vertical**
   (public manifest reference + full `spt api` reference + install-on-demand
   bootstrap pattern) · shell getting-started (`spt-shell-notify` live example) ·
   generated CLI reference · **manifest JSON Schema (new code: schemars)** · root
   `llms.txt` + `llms-full.txt` · rustdoc→Pages. **Tier 2 deferred:** MCP doc
   server, `--help --json`, capstone, per-vertical llms.txt fan-out, remaining
   verticals' tutorials (overview + reference stubs only).
6. **Site:** mdBook + custom theme CSS (styling north star: Astro Starlight — its
   look, not its toolchain). Raw `.md` published alongside HTML. Authored in a new
   top-level **`docs-site/`** (never from internal `docs/` — that corpus is
   private and sister-project-laden).
7. **README:** `README.md`, `# SPT` brand; "What is SPT?" tagline verbatim; honest
   ABC paragraph (**Pi = the pi coding agent, disambiguated**; harness adapters
   phrased as in-development); **Status table** (works-today vs next); two install
   one-liners; two dev getting-started sections; docs + `llms.txt` pointers.
8. **Install-on-demand docs:** generic contract + per-OS check-and-install snippet
   (real Pages URL, no placeholders); Windows PATH-refresh gotcha (absolute path
   for first invocation) documented. The real `/spt-install` skill is an
   `spt-claude-code` deliverable, linked later.
9. **Release:** workspace → **0.1.0** (single shared version), tag `v0.1.0` in
   source repo, GitHub Release on `spt-releases`. Assets: windows + linux binaries,
   `SHA256SUMS`, **`SignedRelease` metadata in the exact format `spt update`
   consumes**, `manifest.schema.json`, `mock-adapter` source zip.
10. **Signing (ADR-0015):** two Ed25519 keypairs — active primary + never-used
    offline recovery; **both pubkeys embedded** in the binary's trusted set; seeds
    backed up off-machine; **manual local signing** (no CI secrets).
11. **License split:** MIT for install scripts / `mock-adapter` / docs-site
    content; binary under a short proprietary freeware license with an explicit
    **royalty-free adapter/shell development clause**.
12. **Wire-proto version** stays its own counter (R-ARCH-3) — never conflated with
    the 0.1.0 release version.

## Goal

A third-party developer (human or dev-agent) lands on `spt-releases`, runs one
non-interactive install line on Windows or Linux, has two agents exchanging a
message in under 10 minutes, and can build a working harness or shell adapter
from the published docs alone — against a signed v0.1.0 release whose future
self-updates verify against the two-key trust anchor.

## Scope

### In

- `SaberMage/spt-releases` repo (private) + README + LICENSE pair + Pages config.
- `install.sh` / `install.ps1` (non-interactive, sha256, user PATH) served at the
  canonical Pages URL.
- Manifest JSON Schema generation (schemars on the `spt-runtime` manifest types) +
  CI drift gate.
- `docs-site/` mdBook corpus, Tier 1 content + theme; llms.txt/llms-full + raw-`.md`
  publish; rustdoc→Pages; generated CLI reference; publish pipeline (source-repo CI
  → releases-repo Pages branch).
- Release pipeline (tag-triggered, both self-hosted runners, cross-repo
  `gh release create`), key minting + embedded trusted set, signed v0.1.0 release,
  flip repo public.

### Out (explicitly deferred, tracked)

- OS-service registration (REQ-INSTALL-1 completes later); legacy migration at
  install (REQ-MIGRATE-1 — needs `spt-claude-code` parity era); marketplace
  repackaging (REQ-INSTALL-2 — doc-stage only here); Tier 2 docs (MCP server,
  `--help --json`, capstone); crates.io / docs.rs; `spt-claude-code` itself
  (separate downstream project + its own grill).

## Tasks

- **D1 — repo + public face.** Create `spt-releases` (private) via `gh`; author
  `README.md` per decision 7; `LICENSE-MIT` (scripts/examples/docs) +
  `LICENSE-BINARY` (freeware + royalty-free-adapter clause); Pages enabled
  (live at flip). *Everything authored public-safe from day one.*
- **D2 — installer scripts.** `install.sh` + `install.ps1`: latest-release
  lookup → platform asset fetch → sha256 verify → place under the per-OS install
  root → user-PATH registration → print absolute path (the PATH-refresh gotcha).
  Non-interactive by construction; idempotent re-run. CI rung: run each script
  against a staged release artifact on the matching runner, then `spt --version`.
- **D3 — manifest JSON Schema.** schemars derives on the manifest types;
  `manifest.schema.json` emitted at a stable site-root path + included in release
  assets; CI drift gate (regenerate + diff).
- **D4 — docs-site Tier 1 content.** mdBook skeleton + Starlight-inspired theme;
  mental model/overview (diagrams); human quickstart (install → two agents
  message, real values); adapter quickstart (walked via `mock-adapter`);
  harness-contract vertical complete (public manifest reference rewritten from
  `docs/MANIFEST.md` — public-safe, no sister-project references; full `spt api`
  reference; install-on-demand bootstrap pattern + per-OS snippet); shell
  getting-started (`spt-shell-notify` as the live example); overview + reference
  stubs for the remaining verticals.
- **D5 — agent-export + generation plumbing.** Root `llms.txt` (curated index) +
  `llms-full.txt` (CI-concatenated); raw-`.md` published alongside HTML; CLI
  reference generated from clap help output; rustdoc for the SDK crates → Pages;
  the source-repo CI publish job (build `docs-site/` → push to `spt-releases`
  Pages branch) + drift gates (CLI ref, schema, llms exports).
- **D6 — release pipeline + signing.** Workspace version → 0.1.0; tag-triggered
  workflow (build matrix on both runners → assemble assets → cross-repo release
  via fine-grained token); **key ceremony per ADR-0015** (mint primary +
  recovery, embed both pubkeys in the binary's default `VerifyPolicy` trusted
  set, back up seeds off-machine); local metadata-signing step (manual) producing
  the `SignedRelease` asset.
- **D7 — v0.1.0 ship + flip.** Tag `v0.1.0`; run the ceremony; publish the
  release; flip `spt-releases` public; Pages goes live; **acceptance run** (below).

## Acceptance (the D7 proof)

On a machine (or clean CI job) that has never had spt-core: README one-liner →
`spt --version` reports 0.1.0 → human quickstart completes < 10 min → adapter
quickstart yields a working mock-derived adapter from docs alone → `llms.txt` +
`manifest.schema.json` fetch from the canonical URL → a staged v0.1.1-shaped
test release **verifies** against the embedded trusted set (`spt update` dry
path), and a recovery-key-signed metadata file also verifies.

## Requirement activation (at M6 start, per rule 5 — NOT yet applied)

| REQ | Stages at activation | Task |
|---|---|---|
| REQ-DOCS-1 | doc, impl | D4/D5 |
| REQ-DOCS-2 | doc, int (quickstart CI-run) | D4 |
| REQ-DOCS-3 | doc | D4 |
| REQ-DOCS-4 | doc, impl, unit (schema + llms + CLI ref; MCP/`--json` excluded → DEFERRED.md) | D3/D5 |
| REQ-DOCS-5 | impl, int (drift gates in CI) | D3/D5 |
| REQ-INSTALL-1 | doc, impl, int (script halves; OS-service excluded → DEFERRED.md) | D2 |
| REQ-INSTALL-2 | doc (relocatable-binary + minimal-logic stance documented) | D2 |
| REQ-INSTALL-3 | impl, int (idempotent re-run rung) | D2 |
| REQ-INSTALL-5 *(new)* | impl, int | D2 |
| REQ-REL-1 *(new)* | doc, impl | D1/D5 |
| REQ-REL-2 *(new)* | impl, int | D6/D7 |
| REQ-REL-3 *(new)* | impl, unit | D6 |