docs(release): prepare v0.1.0-alpha.2 truth sync (#49)

Author: xiaojiou176

DISTRIBUTION.md

@@ -60,16 +60,13 @@ MCP / npm package release.
 
 ## Version And Release Truth
 
-- The only live GitHub release today is `v0.1.0-alpha.1`.
-- That release is the first public storefront baseline and should be read as
-  the first public release snapshot, not as a claim that every post-release
-  hardening commit is already re-tagged.
-- Current `main` is ahead of tag commit `7fbc491`, so repo-side distribution
-  hardening after that baseline lives on `main` until a later tag/release is
-  cut.
-- Until the next release is created, README, Pages, and docs must describe the
-  current release truth as "first public baseline release + current main is
-  ahead", not "release fully matches current main".
+- The latest live GitHub release is `v0.1.0-alpha.2`.
+- `v0.1.0-alpha.2` is the current published prerelease baseline and is meant to
+  match the current released `main` snapshot.
+- `v0.1.0-alpha.1` remains the historical first public baseline, not the latest
+  release truth.
+- If `main` moves again after this release, README, Pages, and docs must return
+  to explicit lag wording until the next tag is cut.
 
 ## Canonical MCP Truth
 

README.md

@@ -691,19 +691,22 @@ gates can trace the maintenance decision end to end.
 The public release surface now has a live baseline. Use these entrypoints:
 
 - [GitHub Releases page](https://github.com/xiaojiou176-open/CortexPilot-public/releases)
-- [Live GitHub Release `v0.1.0-alpha.1`](https://github.com/xiaojiou176-open/CortexPilot-public/releases/tag/v0.1.0-alpha.1)
+- [Live GitHub Release `v0.1.0-alpha.2`](https://github.com/xiaojiou176-open/CortexPilot-public/releases/tag/v0.1.0-alpha.2)
 - [Live GitHub Pages site](https://xiaojiou176-open.github.io/CortexPilot-public/)
 - [Changelog](CHANGELOG.md)
 - [Public release checklist](docs/runbooks/public-release-checklist.md)
+- [Current release notes source](docs/releases/v0.1.0-alpha.2.md)
 - [First public release draft](docs/releases/first-public-release-draft.md)
 - [Tracked healthy `news_digest` proof summary](docs/releases/assets/news-digest-healthy-proof-2026-03-27.md)
 - [Tracked `news_digest` baseline summary](docs/releases/assets/news-digest-benchmark-summary-2026-03-27.md)
 - [Tracked `news_digest` Workflow Case recap](docs/releases/assets/news-digest-workflow-case-recap-2026-03-27.md)
 
-Release truth note: `v0.1.0-alpha.1` is the current public storefront baseline,
-but current `main` is ahead with post-release repo-side follow-through. Treat
-[DISTRIBUTION.md](DISTRIBUTION.md) as the live repo-side distribution contract
-until the next tag is cut.
+Release truth note: `v0.1.0-alpha.2` is the current published prerelease
+baseline and is intended to match the current released `main` snapshot. The
+historical first-baseline draft remains
+[docs/releases/first-public-release-draft.md](docs/releases/first-public-release-draft.md),
+while the current release note source is
+[docs/releases/v0.1.0-alpha.2.md](docs/releases/v0.1.0-alpha.2.md).
 
 Public repo hygiene stays fail-closed as well: token-like fixture coverage must
 use synthetic string assembly, and public path fixtures must use generic

configs/docs_nav_registry.json

@@ -92,6 +92,15 @@
       "owner_surface": "docs",
       "listed_in_primary_navigation": false
     },
+    {
+      "path": "docs/releases/v0.1.0-alpha.2.md",
+      "kind": "reference",
+      "status": "active",
+      "canonical": true,
+      "generated": false,
+      "owner_surface": "docs",
+      "listed_in_primary_navigation": false
+    },
     {
       "path": "docs/assets/storefront/demo-status.md",
       "kind": "reference",

configs/mcp_public_manifest.json

@@ -3,9 +3,9 @@
   "name": "cortexpilot-readonly",
   "display_name": "CortexPilot Read-only MCP",
   "status": "shipped",
-  "version": "0.1.0-alpha.1",
-  "version_truth": "This is the latest published GitHub release version. Verify parity with current main before making broader release or registry claims.",
-  "release_represents_current_main": false,
+  "version": "0.1.0-alpha.2",
+  "version_truth": "This is the latest published GitHub release version and is intended to match the current released main snapshot. Re-check parity after later mainline commits before making broader release or registry claims.",
+  "release_represents_current_main": true,
   "description": "Repo-owned read-only MCP server for CortexPilot runs, workflows, approvals, compare, proof, and incident summaries.",
   "homepage": "https://xiaojiou176-open.github.io/CortexPilot-public/mcp/",
   "distribution_page": "https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/DISTRIBUTION.md",

docs/README.md

@@ -66,14 +66,15 @@ navigation set.
 1. [runbooks/public-release-checklist.md](runbooks/public-release-checklist.md)
 2. [runbooks/storefront-share-kit.md](runbooks/storefront-share-kit.md)
 3. [runbooks/github-storefront-manual-steps.md](runbooks/github-storefront-manual-steps.md)
-4. [releases/first-public-release-draft.md](releases/first-public-release-draft.md)
-5. [assets/storefront/demo-status.md](assets/storefront/demo-status.md)
-6. [assets/storefront/benchmark-methodology.md](assets/storefront/benchmark-methodology.md)
-7. [architecture/ecosystem-and-builder-surfaces-v1.md](architecture/ecosystem-and-builder-surfaces-v1.md)
-8. [runbooks/render-hosted-operator-pilot.md](runbooks/render-hosted-operator-pilot.md)
-9. [runbooks/write-mcp-queue-pilot.md](runbooks/write-mcp-queue-pilot.md)
-10. [robots.txt](robots.txt)
-11. [sitemap.xml](sitemap.xml)
+4. [releases/v0.1.0-alpha.2.md](releases/v0.1.0-alpha.2.md)
+5. [releases/first-public-release-draft.md](releases/first-public-release-draft.md)
+6. [assets/storefront/demo-status.md](assets/storefront/demo-status.md)
+7. [assets/storefront/benchmark-methodology.md](assets/storefront/benchmark-methodology.md)
+8. [architecture/ecosystem-and-builder-surfaces-v1.md](architecture/ecosystem-and-builder-surfaces-v1.md)
+9. [runbooks/render-hosted-operator-pilot.md](runbooks/render-hosted-operator-pilot.md)
+10. [runbooks/write-mcp-queue-pilot.md](runbooks/write-mcp-queue-pilot.md)
+11. [robots.txt](robots.txt)
+12. [sitemap.xml](sitemap.xml)
 
 ## What Each File Is For
 
@@ -87,6 +88,7 @@ navigation set.
 - `docs/runbooks/public-release-checklist.md`: user-facing GitHub release preparation checklist
 - `docs/runbooks/storefront-share-kit.md`: tracked punchline and sharing kit for storefront work
 - `docs/runbooks/github-storefront-manual-steps.md`: exact GitHub UI values and manual storefront steps
+- `docs/releases/v0.1.0-alpha.2.md`: repo-side draft source for the current published prerelease notes
 - `docs/releases/first-public-release-draft.md`: repo-side draft source for the first public GitHub Release
 - `docs/assets/storefront/demo-status.md`: status ledger for tracked public demo and proof assets
 - `docs/assets/storefront/proof-pack-index.json`: machine-readable public proof bundle index for proven and showcase storefront slices

docs/assets/storefront/demo-status.md

@@ -34,7 +34,7 @@ ones that still need a real capture pass.
 | Healthy backend-backed `news_digest` public proof set | present | tracked proof summary: `docs/releases/assets/news-digest-healthy-proof-2026-03-27.md` |
 | Public benchmark artifact from a real tracked run | present | first tracked single-run baseline: `docs/releases/assets/news-digest-benchmark-summary-2026-03-27.md` |
 | Share-ready Workflow Case recap asset | present | tracked recap asset: `docs/releases/assets/news-digest-workflow-case-recap-2026-03-27.md` |
-| Published GitHub Release page/card | present | live release exists, but it is still the latest published prerelease baseline rather than a guaranteed snapshot of current `main` |
+| Published GitHub Release page/card | present | live release `v0.1.0-alpha.2` is the latest published prerelease baseline and current released `main` snapshot |
 
 ## Still Missing
 
@@ -63,8 +63,8 @@ The public storytelling shorthand is now:
 - `social-preview-1280x640.png` is a repo-tracked upload candidate for the GitHub social preview setting, not proof that the live GitHub setting has already been applied.
 - `docs/releases/first-public-release-draft.md` remains the repo-side draft source that fed the published release notes.
 - the live GitHub Release page currently represents the latest published public
-  baseline, not an automatic claim that every later repo-side hardening commit
-  is already included in the tag.
+  baseline and current released `main` snapshot; if later commits land, repo
+  docs must restore explicit lag wording until the next tag is cut.
 - `docs/releases/assets/news-digest-healthy-proof-2026-03-27.md` and the two
   copied screenshots are repo-tracked evidence from a successful local run,
   not proof that the live GitHub Release page has already been published.

docs/distribution/index.html

@@ -255,17 +255,17 @@ <h2>Release truth</h2>
           <article class="card">
             <span class="badge shipped">Published today</span>
             <h3>Latest GitHub release</h3>
-            <p><code>v0.1.0-alpha.1</code> is the latest published GitHub Release and the latest public semver tag.</p>
+            <p><code>v0.1.0-alpha.2</code> is the latest published GitHub Release and the latest public semver tag.</p>
           </article>
           <article class="card">
             <span class="badge deferred">Important boundary</span>
-            <h3>Release is not the same thing as moving main</h3>
-            <p>Before any registry, marketplace, Docker, or broader distribution claim, cut a fresh release that matches the current <code>main</code> state instead of assuming parity from repo docs alone.</p>
+            <h3>Current release and main are aligned</h3>
+            <p>The current prerelease is meant to match the current released <code>main</code> snapshot. If later commits land, restore explicit lag wording until the next tag is cut.</p>
           </article>
           <article class="card">
             <span class="badge shipped">Repo-side draft</span>
             <h3>Current release notes source</h3>
-            <p>Use <a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/docs/releases/first-public-release-draft.md"><code>docs/releases/first-public-release-draft.md</code></a> as the tracked repo-side release draft, then verify parity against the live GitHub release page.</p>
+            <p>Use <a href="https://github.com/xiaojiou176-open/CortexPilot-public/blob/main/docs/releases/v0.1.0-alpha.2.md"><code>docs/releases/v0.1.0-alpha.2.md</code></a> as the tracked repo-side release draft. Keep <code>first-public-release-draft.md</code> as the historical alpha.1 baseline.</p>
           </article>
         </div>
       </section>

docs/releases/first-public-release-draft.md

@@ -7,6 +7,9 @@ This release is the first public storefront baseline for CortexPilot.
 Treat it as the first published baseline, not as a claim that current `main`
 and the latest public release are always the same snapshot.
 
+Historical note: the newer current release note source lives at
+`docs/releases/v0.1.0-alpha.2.md`.
+
 ## Why this release matters
 
 CortexPilot is not just an agent demo repository. It is a command tower for

docs/releases/v0.1.0-alpha.2.md

@@ -0,0 +1,61 @@
+# CortexPilot v0.1.0-alpha.2 - distribution readiness baseline
+
+This file is the tracked source for the current published GitHub Release notes.
+
+This release aligns the latest published prerelease with the current released
+`main` snapshot after the distribution-readiness closeout landed.
+
+## Why this release matters
+
+CortexPilot is no longer only a truthful-ready public repo. With this release,
+the public release/tag now catches up to the current distribution contract,
+starter boundaries, package stance, and read-only MCP artifact story.
+
+## What changed
+
+- added a canonical repo-side distribution contract in `DISTRIBUTION.md`
+- added a public Pages mirror at `docs/distribution/index.html`
+- artifactized the shipped read-only MCP surface through
+  `configs/mcp_public_manifest.json`
+- standardized the official MCP startup story around
+  `scripts/run_readonly_mcp.sh`
+- tightened Codex / Claude Code / OpenClaw starter and bundle wording so local
+  adoption materials are not misread as published listings
+- promoted `@cortexpilot/frontend-api-client` and
+  `@cortexpilot/frontend-api-contract` to publish-ready-but-deferred package
+  posture, while keeping `@cortexpilot/frontend-shared` workspace-only
+- synced README, Pages, release-truth wording, and storefront docs around the
+  new latest published prerelease baseline
+
+## What to open first
+
+1. `README.md`
+2. `DISTRIBUTION.md`
+3. `docs/distribution/index.html`
+4. `docs/mcp/index.html`
+5. `docs/builders/index.html`
+
+## Current truthful boundary
+
+- the public repo and GitHub Pages site are official front doors
+- the shipped MCP surface is still read-only, stdio, and repo-local
+- starter kits and the coding-agent bundle remain local-adoption material, not
+  published marketplace listings
+- hosted operator service, write-capable MCP, Docker distribution, and
+  registry submissions remain deferred
+
+## Historical note
+
+- `v0.1.0-alpha.1` remains the first public prerelease baseline
+- this file supersedes `docs/releases/first-public-release-draft.md` as the
+  source for the latest published release notes
+
+## Verification
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 bash scripts/run_readonly_mcp.sh </dev/null
+npm run docs:check
+bash scripts/check_repo_hygiene.sh
+npm pack --json --dry-run ./packages/frontend-api-client
+npm pack --json --dry-run ./packages/frontend-api-contract
+```

docs/runbooks/github-storefront-manual-steps.md

@@ -55,25 +55,26 @@ If Discussions are disabled again in the future:
 
 - reflect that choice in `README.md` or `SUPPORT.md`
 
-## 5. First GitHub Release
+## 5. Latest GitHub Release
 
 Recommended release title:
 
-> CortexPilot v0.1.0-alpha.1 - first public prerelease baseline
+> CortexPilot v0.1.0-alpha.2 - distribution readiness baseline
 
 Draft notes source:
 
-- `docs/releases/first-public-release-draft.md`
+- `docs/releases/v0.1.0-alpha.2.md`
 
 Live release:
 
-- `https://github.com/xiaojiou176-open/CortexPilot-public/releases/tag/v0.1.0-alpha.1`
+- `https://github.com/xiaojiou176-open/CortexPilot-public/releases/tag/v0.1.0-alpha.2`
 
 Truth note:
 
-- treat `v0.1.0-alpha.1` as the latest published public baseline, not as an
-  automatic claim that current `main` is already re-tagged
-- if current `main` has moved ahead, keep `README.md` and `DISTRIBUTION.md`
+- treat `v0.1.0-alpha.2` as the latest published public baseline and current
+  released `main` snapshot
+- keep `v0.1.0-alpha.1` as the historical first public baseline
+- if current `main` moves ahead again, keep `README.md` and `DISTRIBUTION.md`
   explicit about that lag until the next release is cut
 
 ## 6. Pages / Landing