|
| 1 | +# CortexPilot Distribution Contract |
| 2 | + |
| 3 | +This file is the canonical human-readable source for CortexPilot's current |
| 4 | +official distribution story. |
| 5 | + |
| 6 | +The public GitHub Pages mirror for this contract lives at |
| 7 | +`docs/distribution/index.html`. |
| 8 | + |
| 9 | +If README, Pages, examples, package metadata, or release notes ever appear to |
| 10 | +say different things, this file wins and the drift should be fixed in the next |
| 11 | +change set. |
| 12 | + |
| 13 | +## One-sentence story |
| 14 | + |
| 15 | +Today CortexPilot officially ships a public repo front door, a GitHub Pages |
| 16 | +product front door, one proof-first public workflow baseline, a repo-local |
| 17 | +read-only MCP server, local coding-agent starter/bundle materials, and |
| 18 | +repo-owned skills for local adoption. |
| 19 | + |
| 20 | +It does not yet officially ship a hosted operator service, a public write-capable |
| 21 | +MCP, a Docker distribution path, or any registry-published plugin / skills / |
| 22 | +MCP / npm package release. |
| 23 | + |
| 24 | +## Status labels |
| 25 | + |
| 26 | +- `shipped`: part of the official public distribution today |
| 27 | +- `starter-only`: intentionally copy-paste or local-install material, not a |
| 28 | + registry item |
| 29 | +- `bundle-compatible`: installable from a local path or local marketplace-like |
| 30 | + surface, but still not a published listing |
| 31 | +- `publish-ready but deferred`: metadata and package contract are ready for a |
| 32 | + future public package release, but no registry release is live yet |
| 33 | +- `not standalone distribution unit`: useful repo-owned surface, but not meant |
| 34 | + to be marketed or released on its own today |
| 35 | +- `deferred`: real later-phase direction, but not part of current official |
| 36 | + distribution |
| 37 | +- `not part of current official distribution`: out of scope for the current |
| 38 | + public story |
| 39 | + |
| 40 | +## Current Distribution Matrix |
| 41 | + |
| 42 | +| Surface | Current status | Official claim | Install path | Protocol / Auth | Next action | |
| 43 | +| --- | --- | --- | --- | --- | --- | |
| 44 | +| GitHub repo | `shipped` | Canonical public source, docs, code, and release front door | `https://github.com/xiaojiou176-open/CortexPilot-public` | none | keep sharp and truthful | |
| 45 | +| GitHub Pages | `shipped` | Canonical public product front door | `https://xiaojiou176-open.github.io/CortexPilot-public/` | none | keep first screen compressed | |
| 46 | +| 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 | |
| 47 | +| 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` | |
| 48 | +| 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 | |
| 49 | +| 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 | |
| 50 | +| 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 | |
| 51 | +| 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 | |
| 52 | +| 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 | |
| 53 | +| `@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 | |
| 54 | +| `@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 | |
| 55 | +| `@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 | |
| 56 | +| 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 | |
| 57 | +| 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 | |
| 58 | +| 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 | |
| 59 | +| 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 | |
| 60 | + |
| 61 | +## Version And Release Truth |
| 62 | + |
| 63 | +- The only live GitHub release today is `v0.1.0-alpha.1`. |
| 64 | +- That release is the first public storefront baseline and should be read as |
| 65 | + the first public release snapshot, not as a claim that every post-release |
| 66 | + hardening commit is already re-tagged. |
| 67 | +- Current `main` is ahead of tag commit `7fbc491`, so repo-side distribution |
| 68 | + hardening after that baseline lives on `main` until a later tag/release is |
| 69 | + cut. |
| 70 | +- Until the next release is created, README, Pages, and docs must describe the |
| 71 | + current release truth as "first public baseline release + current main is |
| 72 | + ahead", not "release fully matches current main". |
| 73 | + |
| 74 | +## Canonical MCP Truth |
| 75 | + |
| 76 | +- Human-readable MCP quickstart: `docs/mcp/index.html` |
| 77 | +- Machine-readable MCP distribution manifest: `configs/mcp_public_manifest.json` |
| 78 | +- Public mirror of this contract: `docs/distribution/index.html` |
| 79 | +- Implementation: `apps/orchestrator/src/cortexpilot_orch/mcp_readonly_server.py` |
| 80 | +- Canonical startup wrapper: `scripts/run_readonly_mcp.sh` |
| 81 | +- Canonical starter template: `examples/coding-agents/mcp/readonly.mcp.json.example` |
| 82 | +- Root `DISTRIBUTION.md` stays authoritative; the public mirror at |
| 83 | + `docs/distribution/index.html` must match it and route readers back here |
| 84 | + |
| 85 | +## External / Owner-only Actions Left Out On Purpose |
| 86 | + |
| 87 | +These are intentionally outside repo-side completion: |
| 88 | + |
| 89 | +- publish npm packages |
| 90 | +- publish a PyPI package |
| 91 | +- submit an MCP registry entry |
| 92 | +- submit Codex / Claude Code / OpenClaw marketplace or registry items |
| 93 | +- publish a Docker image |
| 94 | +- deploy a live hosted operator service |
| 95 | +- promote a public write-capable MCP |
| 96 | + |
| 97 | +Those actions require external platform writes or owner decisions and are not |
| 98 | +part of the current official shipped contract. |
0 commit comments