feat: finish distribution market readiness

* docs: align storefront and alpha.3 release truth

* chore: allow root nvmrc in hygiene policy

* feat: finish distribution market readiness

* fix: run cli tests with orchestrator deps

* fix: allow new public distribution surfaces in ci

Author: xiaojiou176

DISTRIBUTION.md

@@ -14,12 +14,13 @@ change set.
 
 Today CortexPilot officially ships a public repo front door, a GitHub Pages
 product front door, one proof-first public workflow baseline, a repo-local
-read-only MCP server, local coding-agent starter/bundle materials, and
-repo-owned skills for local adoption.
+read-only MCP server, a published PyPI package, a live Official MCP Registry
+entry, local coding-agent starter/bundle materials, and a live ClawHub skill.
 
 It does not yet officially ship a hosted operator service, a public write-capable
-MCP, a Docker distribution path, or any registry-published plugin / skills /
-MCP / npm package release.
+MCP, a Docker distribution path, or standalone npm releases. OpenHands/extensions
+and MCP.so submissions are filed, but they still depend on external review or
+intake handling rather than repo-only publication.
 
 ## Status labels
 
@@ -28,6 +29,8 @@ MCP / npm package release.
   registry item
 - `bundle-compatible`: installable from a local path or local marketplace-like
   surface, but still not a published listing
+- `submitted-externally`: the repo has filed the platform submission and holds a
+  public receipt, but the host has not finished acceptance yet
 - `publish-ready but deferred`: metadata and package contract are ready for a
   future public package release, but no registry release is live yet
 - `not standalone distribution unit`: useful repo-owned surface, but not meant
@@ -45,24 +48,32 @@ MCP / npm package release.
 | GitHub Pages | `shipped` | Canonical public product front door | `https://xiaojiou176-open.github.io/CortexPilot-public/` | none | keep first screen compressed |
 | First proven workflow (`news_digest`) | `shipped` | Official public proof-first baseline | `docs/use-cases/index.html` and tracked proof assets | read-only proof / replay story | keep as the only release-proven public workflow |
 | Read-only MCP | `shipped` | Repo-owned stdio JSON-RPC MCP for machine-readable inspection only | bootstrapped repo checkout + `bash __CORTEXPILOT_REPO_ROOT__/scripts/run_readonly_mcp.sh` or the tracked starter templates | `stdio`, JSON-RPC 2.0, read-only, repo-local, no hosted auth, no OAuth | keep artifactized through `configs/mcp_public_manifest.json` |
+| PyPI package (`cortexpilot-orchestrator`) | `shipped` | Published package for the public read-only MCP runtime | `https://pypi.org/project/cortexpilot-orchestrator/0.1.0a4/` | package install only | keep package README, entrypoints, and version markers aligned with registry truth |
+| Official MCP Registry entry | `shipped` | Public MCP discovery entry for the read-only CortexPilot server | `https://registry.modelcontextprotocol.io/v0/servers?search=io.github.xiaojiou176-open/cortexpilot-readonly` | registry discovery only, stdio package install | keep `server.json` aligned with PyPI and the public MCP docs |
 | Codex starter | `starter-only` | Local marketplace seed plus shared read-only MCP template | `examples/coding-agents/codex/` | local path wiring only | keep truthful; do not relabel as official directory listing |
 | 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 | `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 |
+| Repo-owned adoption-router skill | `shipped` | Cross-tool routing skill with `SKILL.md` + `manifest.yaml`, shared between the repo bundle and external skill distribution | `examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/` | repo-owned skill contract, local bundle plus external skill publication | keep the repo bundle and published skill receipts aligned |
+| ClawHub skill (`cortexpilot-adoption-router`) | `shipped` | Published OpenClaw skill for honest CortexPilot adoption routing | `https://www.clawhub.ai/skills/cortexpilot-adoption-router` | skill registry, no hosted CortexPilot account, no write-capable MCP | keep the skill copy aligned with the repo bundle and public boundary |
+| OpenHands/extensions submission | `submitted-externally` | Public skill submission for the same adoption-router artifact | `https://github.com/OpenHands/extensions/pull/152` | host review flow, not live until merged | track review without overclaiming a merged listing |
+| MCP.so submission | `submitted-externally` | Directory submission for the public read-only MCP server | `https://github.com/chatmcp/mcpso/issues/1559` | directory intake flow, not live until accepted | keep the issue body aligned with current package + registry truth |
 | `@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 |
 | Docker image / Dockerfile | `deferred` | No official container distribution today; existing Dockerfiles are CI-only infrastructure | none | n/a | add only when a real container story exists |
 | Hosted Render pilot | `deferred` | Repo-side pilot blueprint exists, but no live hosted operator claim | `render.yaml` + runbook only | hosted HTTP / token boundary remains later | keep truthful; no live hosted claim |
 | Write-capable MCP | `not part of current official distribution` | Public MCP is still read-only | none | owner-only preview groundwork exists separately | keep gated and out of public claim |
-| Registry-published plugins / skills / MCP | `not part of current official distribution` | No official Codex / Claude Code / OpenClaw / MCP registry listing is live today | none | external platform submission required | external-only later action |
 
 ## Version And Release Truth
 
 - The latest live GitHub release is `v0.1.0-alpha.3`.
 - `v0.1.0-alpha.3` is the current published prerelease baseline and is meant to
   match the current released `main` snapshot.
+- The latest published public package for the read-only MCP is
+  `cortexpilot-orchestrator==0.1.0a4`.
+- The latest Official MCP Registry entry points to
+  `io.github.xiaojiou176-open/cortexpilot-readonly@0.1.0a4`.
 - `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
@@ -84,9 +95,8 @@ MCP / npm package release.
 These are intentionally outside repo-side completion:
 
 - publish npm packages
-- publish a PyPI package
-- submit an MCP registry entry
-- submit Codex / Claude Code / OpenClaw marketplace or registry items
+- wait for OpenHands/extensions review on PR `#152`
+- wait for MCP.so intake handling on issue `#1559`
 - publish a Docker image
 - deploy a live hosted operator service
 - promote a public write-capable MCP

README.md

@@ -26,18 +26,19 @@ not a hosted product, and the shipped MCP surface remains **read-only**.
 
 The shortest truthful answer today is:
 
-> CortexPilot officially ships a public repo, a public Pages front door, a repo-local read-only MCP surface, and proof-first starter materials. Hosted service, write-capable MCP, Docker distribution, registry submissions, and standalone package publication are still explicitly deferred.
+> CortexPilot officially ships a public repo, a public Pages front door, a repo-local read-only MCP surface, a published PyPI package, a live Official MCP Registry entry, and a live ClawHub skill. OpenHands/extensions and MCP.so submissions are filed with public receipts, while hosted service, write-capable MCP, Docker distribution, and standalone npm releases remain deferred.
 
 Use these buckets:
 
-- **Shipped now**: repo, Pages, proof-first docs, read-only MCP
+- **Shipped now**: repo, Pages, proof-first docs, read-only MCP, PyPI package, Official MCP Registry entry, ClawHub skill
 - **Starter-only**: Codex / Claude Code / OpenClaw local starter kits and bundle examples
+- **Submitted externally**: `OpenHands/extensions#152` and `chatmcp/mcpso#1559` are filed and await host review
 - **Publish-ready but deferred**:
   `@cortexpilot/frontend-api-client`,
   `@cortexpilot/frontend-api-contract`
 - **Workspace-only**: `@cortexpilot/frontend-shared` stays repo-owned and is
   not marketed as a standalone package
-- **Deferred**: hosted operator, write-capable MCP, Docker image, npm/PyPI, and marketplace/registry submissions
+- **Deferred**: hosted operator, write-capable MCP, Docker image, and standalone npm releases
 
 If you need the exact matrix instead of a one-line summary, open
 [DISTRIBUTION.md](DISTRIBUTION.md) or the public

apps/orchestrator/README.md

@@ -1,4 +1,5 @@
 # Orchestrator Module
+<!-- mcp-name: io.github.xiaojiou176-open/cortexpilot-readonly -->
 
 `apps/orchestrator/` is the backend core of CortexPilot.
 

apps/orchestrator/setup.cfg

@@ -1,11 +1,47 @@
 [metadata]
 name = cortexpilot-orchestrator
-version = 0.1.0
+version = 0.1.0a4
+description = CortexPilot orchestrator and read-only MCP runtime
+long_description = file: README.md
+long_description_content_type = text/markdown
+license = MIT
+url = https://github.com/xiaojiou176-open/CortexPilot-public
+project_urls =
+    Homepage = https://xiaojiou176-open.github.io/CortexPilot-public/
+    Repository = https://github.com/xiaojiou176-open/CortexPilot-public
+    Documentation = https://xiaojiou176-open.github.io/CortexPilot-public/mcp/
+    Issues = https://github.com/xiaojiou176-open/CortexPilot-public/issues
+    Discussions = https://github.com/xiaojiou176-open/CortexPilot-public/discussions
+    Changelog = https://github.com/xiaojiou176-open/CortexPilot-public/releases
 
 [options]
 package_dir =
     = src
 packages = find:
+install_requires =
+    pydantic==2.12.5
+    jsonschema==4.26.0
+    typer==0.21.1
+    rich==14.3.3
+    fastapi==0.128.1
+    uvicorn==0.42.0
+    python-dotenv==1.2.1
+    opentelemetry-api==1.40.0
+    opentelemetry-sdk==1.40.0
+    opentelemetry-exporter-otlp-proto-grpc==1.40.0
+    opentelemetry-exporter-otlp-proto-http==1.40.0
+    playwright==1.58.0
+    google-genai==1.68.0
+    openai-agents==0.7.0
+    temporalio==1.22.0
+    duckduckgo-search==8.1.1
+    httpx==0.28.1
+    mcp>=1.9.4,<2.0.0
 
 [options.packages.find]
 where = src
+
+[options.entry_points]
+console_scripts =
+    cortexpilot = cortexpilot_orch.cli:main
+    cortexpilot-readonly-mcp = cortexpilot_orch.mcp_entrypoints:readonly_mcp_main

apps/orchestrator/src/cortexpilot_orch/cli.py

@@ -513,5 +513,13 @@ def mcp_queue_pilot_server() -> None:
     serve_queue_pilot_mcp()
 
 
-if __name__ == "__main__":
+def main() -> None:
     app()
+
+
+def mcp_readonly_main() -> None:
+    serve_readonly_mcp()
+
+
+if __name__ == "__main__":
+    main()

apps/orchestrator/src/cortexpilot_orch/mcp_entrypoints.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from cortexpilot_orch.mcp_readonly_server import serve_readonly_mcp
+
+
+def readonly_mcp_main() -> None:
+    serve_readonly_mcp()

apps/orchestrator/src/cortexpilot_orch/mcp_readonly_server.py

@@ -17,7 +17,7 @@
 SERVER_INFO = {
     "name": "cortexpilot-readonly",
     "title": "CortexPilot Read-only MCP",
-    "version": "0.1.0",
+    "version": "0.1.0a4",
 }
 
 
@@ -329,7 +329,7 @@ def build_readonly_tools(read_service: ControlPlaneReadService) -> list[Readonly
 
 class CortexPilotReadonlyMcpServer:
     def __init__(self, read_service: ControlPlaneReadService | None = None) -> None:
-        self._read_service = read_service or ControlPlaneReadService.from_api_main()
+        self._read_service = read_service or ControlPlaneReadService.from_runtime()
         self._tools = build_readonly_tools(self._read_service)
         self._tool_map = {tool.name: tool for tool in self._tools}
 

apps/orchestrator/src/cortexpilot_orch/services/__init__.py

@@ -1,5 +1,12 @@
-from cortexpilot_orch.services.orchestration_service import OrchestrationService
-from cortexpilot_orch.services.rollback_service import RollbackService
-from cortexpilot_orch.services.session_index_service import SessionIndexService
+"""Service package exports for CortexPilot.
 
-__all__ = ["RollbackService", "OrchestrationService", "SessionIndexService"]
+Keep this module import-light so read-only surfaces can import targeted service
+modules without pulling the full orchestration runtime into package import side
+effects.
+"""
+
+__all__ = [
+    "OrchestrationService",
+    "RollbackService",
+    "SessionIndexService",
+]