Merge remote-tracking branch 'origin/main' into pr-43-merge-refresh

Author: xiaojiou176

CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this repository will be documented in this file.
 
 ### Changed
 
+- added a registry-shaped `manifest.yaml` for the repo-owned
+  `cortexpilot-adoption-router` skill inside the coding-agent bundle, then
+  synced the distribution contract, skills quickstart, and Codex / Claude Code /
+  OpenClaw starter docs so CortexPilot can truthfully describe one cross-tool
+  skill artifact as `publish-ready but deferred` without claiming any live
+  marketplace or registry listing
 - added a repo-owned workflow/dependency/security closeout lane by bootstrapping
   pinned `actionlint`, `zizmor`, `trivy`, `gitleaks`, and `trufflehog`
   binaries through `scripts/lib/release_tool_helpers.sh`; the same slice adds

DISTRIBUTION.md

@@ -49,7 +49,7 @@ MCP / npm package release.
 | Claude Code starter | `starter-only` | Project-local `.claude` and `.mcp.json` starter | `examples/coding-agents/claude-code/` | local project wiring only | keep truthful; do not relabel as marketplace package |
 | OpenClaw starter | `starter-only` | Local config seed for the same read-only MCP and compatible bundle | `examples/coding-agents/openclaw/` | local config + local plugin path | keep truthful; do not relabel as ClawHub publication |
 | Cross-tool coding-agent bundle | `bundle-compatible` | Local bundle compatible with Codex local marketplace installs, Claude plugin-dir development, and OpenClaw local plugin loading | `examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/` | local bundle metadata + repo-aware MCP wrapper | keep local-install contract; no published listing claim |
-| Repo-owned skill in the bundle | `starter-only` | Routing skill for honest adoption path selection | shipped inside the local bundle | repo-owned skill only | keep repo-owned; not a marketplace item |
+| Repo-owned skill in the bundle | `publish-ready but deferred` | Cross-tool routing skill with `SKILL.md` + `manifest.yaml` for honest adoption path selection across Codex / Claude Code / OpenClaw style installs | `examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/` | repo-owned skill contract, bundle-scoped today, no live registry listing | keep truthful: package-ready metadata exists, but official marketplace / registry submissions are still later actions |
 | `@cortexpilot/frontend-api-client` | `publish-ready but deferred` | Thin JS/TS client for control-plane reads and guarded operator add-ons | package metadata + README are publish-ready, but the official install story is still clone / vendor reuse until the first npm release exists | HTTP API with token / mutation-role expectations | publish later only after the first public package release is intentionally cut |
 | `@cortexpilot/frontend-api-contract` | `publish-ready but deferred` | Generated route / query / type boundary for frontend consumers | package metadata + README are publish-ready, but the official install story is still clone / vendor reuse until the first npm release exists | typed contract layer only | publish later only after the first public package release is intentionally cut |
 | `@cortexpilot/frontend-shared` | `not standalone distribution unit` | Repo-owned presentation substrate for dashboard / desktop / future web surfaces | repo-local package only | frontend presentation helpers only | keep repo-owned for now |
@@ -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>
@@ -363,6 +363,14 @@ <h2>Current distribution matrix</h2>
                 <td>Local bundle metadata + plugin-scoped read-only MCP</td>
                 <td>Keep local-first; do not call it a published listing.</td>
               </tr>
+              <tr>
+                <td><strong>Repo-owned adoption-router skill</strong></td>
+                <td><span class="badge starter">publish-ready but deferred</span></td>
+                <td>Cross-tool skill artifact with <code>SKILL.md</code> plus <code>manifest.yaml</code> for Codex / Claude Code / OpenClaw-compatible installs.</td>
+                <td><code>examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/</code></td>
+                <td>Repo-owned skill contract, bundle-scoped today, no live registry listing</td>
+                <td>Keep the artifact honest: metadata and semver are present, but any official registry submission is still a later external action.</td>
+              </tr>
               <tr>
                 <td><strong>@cortexpilot/frontend-api-client</strong></td>
                 <td><span class="badge starter">publish-ready but deferred</span></td>

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
+```