yvgude--lean-ctx/docs/releases/v1.0-runbook.md

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)