# v1.0 Launch Runbook

Operational playbook for the v1.0 stability release (GL #396). One owner per
section; nothing on this page is aspirational — every step has a command or a
checklist. Goal: v1.0 is an orchestrated market event, not a changelog entry.

## Phase 0 — Entry criteria (before an RC exists)

All of these are CI-enforced and must be green on `main`:

- [ ] Contract freeze active: `rust/tests/contracts_frozen.rs` + `frozen-hashes.json` (GL #394)
- [ ] OpenAPI surface gate: `rust/tests/openapi_stability.rs` (additive-only)
- [ ] SDK conformance matrix 3/3 SDKs, 14/14 checks PASS (`docs/reference/sdk-conformance-matrix.md`, GL #395)
- [ ] SDK release gate green: `python3 scripts/check-sdk-versions.py`
- [ ] `lean-ctx doctor --migrate-check` exits 0 on a fresh install **and** on a long-lived dev machine
- [ ] Zero clippy warnings, full test suite green, coverage job green

## Phase 1 — RC cut + feature freeze (T-14 days)

1. Branch: `git checkout -b release/v1.0 && git push origin release/v1.0`.
2. Tag the first RC: `git tag v1.0.0-rc.1 && git push origin v1.0.0-rc.1`
   (release.yml builds all 8 targets; `sdk-gate` job blocks on SDK coupling).
3. Freeze window: only `fix:`/`docs:` commits may land on `release/v1.0`.
   `main` stays open for post-1.0 work; cherry-pick fixes back.
4. Baseline snapshot (paste into the appendix below):
   - GitHub stars, npm weekly DLs (`lean-ctx-bin`), PyPI DLs (`lean-ctx-client`), crates.io DLs
   - Discord member count, website weekly uniques

## Phase 2 — Bug bash (T-14 → T-7)

Checklist per platform (macOS arm64, Linux x86_64+musl, Windows x86_64):

- [ ] `curl -fsSL https://leanctx.com/install.sh | sh` installs the RC
- [ ] `lean-ctx setup` on a clean machine: Cursor, Claude Code, Codex CLI detected
- [ ] `lean-ctx doctor` all green; `lean-ctx doctor --migrate-check` exits 0
- [ ] Upgrade path: install latest 0.x/3.x stable → upgrade to RC → `doctor --migrate-check` → data intact (sessions, knowledge, indexes)
- [ ] `ctx_read`/`ctx_search`/`ctx_semantic_search` round trip in a real repo
- [ ] Dashboard + `lean-ctx serve` + one SDK quickstart per language
- [ ] Custom embedding model loads via `hf:` scheme (GL #397 path)

File everything as `bug-bash::v1.0` labels; release-blockers get `severity::blocker`.

## Phase 3 — Rollback plan (decided BEFORE launch day)

Trigger: a `severity::blocker` found after `v1.0.0` is public.

1. GitHub release: mark `v1.0.0` as pre-release (hides "Latest" pointer), restore previous stable as Latest.
2. npm: `npm dist-tag add lean-ctx-bin@<prev> latest` (never unpublish).
3. Homebrew: revert the formula bump commit in `homebrew-lean-ctx`.
4. AUR: push previous `pkgver` in `aur/`.
5. install.sh resolves "latest" from the GitHub API — re-pointing Latest fixes it with zero changes.
6. Post a pinned status to Discord + the HN/PH threads (honesty beats silence).

Rehearse steps 1–5 once with a throwaway tag during Phase 2.

## Phase 4 — Launch day (T-0, all times CET)

| Time | Action | Owner |
|---|---|---|
| 07:00 | Final gate: CI green on tag, `doctor --migrate-check` on 3 platforms, scorecard signed | eng |
| 08:00 | `git tag v1.0.0 && git push origin v1.0.0` — release.yml ships binaries + npm + brew + AUR | eng |
| 09:00 | Verify every channel serves 1.0: install.sh, npm, brew, AUR, cargo | eng |
| 09:30 | Blog post live (`blog/`), comparisons refreshed, /press page live | content |
| 10:00 | Discord `@everyone` + supporter mail (founding-user thanks) | community |
| 15:00 | **Show HN** posted (US morning; text from `marketing/launch-v1/show-hn.md`) | founder |
| 15:00–23:00 | HN Q&A window — founder answers everything personally; no marketing voice | founder |
| 23:00 | Day-1 metrics snapshot into the appendix | eng |
| T+1 09:00 | **Product Hunt** launch (assets from `marketing/launch-v1/product-hunt.md`; deliberately offset from HN) | content |

## Phase 5 — Measurement

- UTM convention: `?utm_source={hn,ph,press,discord,mail}&utm_campaign=v1-launch` on every shared leanctx.com link. HN tolerates no UTM on the main link — use it in comment links only.
- Compare against the Phase-1 baseline after 7 days: stars Δ, npm/PyPI/crates DL Δ, team-trial signups, press pickups.
- Retro doc within 14 days; learnings feed GTM P2 (#379).

## Hard-earned rules (tokbench thread, GL #308/#361)

1. Publish the **savings-faithful configuration** prominently (env vars, bridge mode) — external benchmarkers WILL test the wrong mode and publish numbers.
2. Every benchmark claim links a reproducible script + the signed scorecard (`core/scorecard`).
3. Answer benchmark critique within hours, with configs and commits — never adjectives.

## Appendix — baselines

| Date | Stars | npm/wk | PyPI/wk | crates total | Discord |
|---|---|---|---|---|---|
| (RC day) | | | | | |
| (T-0) | | | | | |
| (T+7) | | | | | |
