feat: package self-contained skill bundle

* feat: package self-contained skill bundle

* fix: bump cryptography security pin

Author: xiaojiou176

apps/orchestrator/requirements.txt

@@ -41,7 +41,7 @@ pre-commit==4.5.1
 vulture==2.14
 
 # Security-pinned transitive dependencies required by the mainline audit gate.
-cryptography==46.0.6
+cryptography==46.0.7
 pyasn1==0.6.3
 pyjwt==2.12.1
 pygments==2.20.0

apps/orchestrator/uv.lock

@@ -1,12 +1,17 @@
-This directory holds repo-tracked public skill artifacts for external skill registries.
+This directory holds CortexPilot public skill bundles for external skill
+registries.
 
-Each skill here must stay aligned with the current public CortexPilot boundary:
+Each bundle here must ship four things together:
 
-- public repo + Pages front door
-- read-only MCP only
-- local starter/bundle adoption
-- no hosted operator claim
-- no write-capable MCP claim
+- `SKILL.md`: the agent-facing instructions
+- `README.md`: the human-facing install and usage guide
+- `references/`: bundle-local install, tool-map, and lane notes
+- `manifest.yaml`: registry metadata for hosts such as ClawHub
 
-These skills may mirror repo-owned bundle surfaces, but they must not claim a live
-registry listing until the listing has been independently confirmed.
+The bundle is only valid if an agent can answer all four questions without
+leaving this directory:
+
+1. How do I install the published CortexPilot MCP package?
+2. Which read-only tools does the MCP expose?
+3. Which lane should I choose first?
+4. Which claims remain out of bounds?

public-skills/README.md

@@ -1,19 +1,37 @@
 # CortexPilot Adoption Router
 
-This public skill package exposes the current CortexPilot adoption router as a
-registry-friendly skill surface.
+This bundle teaches an agent how to connect the published CortexPilot read-only
+MCP package and choose the right public adoption lane.
 
-It is designed for host ecosystems that want a single skill folder with a
-`SKILL.md` contract and semver-friendly manifest.
+## What the agent learns here
 
-## What it does
+- how to install the published `cortexpilot-orchestrator==0.1.0a4` MCP package
+- which read-only CortexPilot tools exist and which are safe-first
+- how to choose between run/workflow inspection, queue/approval reads, and
+  proof/incident reads
+- which hosted or write-capable claims stay out of bounds
 
-- routes operators to the right CortexPilot adoption lane
-- keeps read-only MCP vs starter vs builder boundaries honest
-- points back to the current public repo and Pages front door
+## Included files
 
-## What it does not claim
+- `SKILL.md` — the progressive-disclosure prompt for the agent
+- `references/mcp-install.md` — exact install snippets for OpenHands/OpenClaw
+- `references/tool-map.md` — the stable read-only tool inventory
+- `references/example-tasks.md` — example asks and expected return shape
+- `manifest.yaml` — registry metadata used by hosts such as ClawHub
+
+## The shortest install path
+
+Use the published package, not a repo-local checkout:
+
+```bash
+uvx --from cortexpilot-orchestrator==0.1.0a4 cortexpilot-readonly-mcp
+```
+
+If the host needs a saved MCP config snippet, use the host-specific examples in
+`references/mcp-install.md`.
+
+## Hard boundaries
 
 - no hosted operator service
 - no write-capable public MCP
-- no live marketplace / registry listing unless independently confirmed
+- no first-party marketplace claim unless that host independently confirms it

public-skills/cortexpilot-adoption-router/README.md

@@ -1,46 +1,81 @@
 ---
 name: cortexpilot-adoption-router
-description: Route the current job to the right CortexPilot surface without overclaiming hosted, write-capable MCP, or published plugin support.
+description: Teach the agent how to connect the published CortexPilot read-only MCP package, choose the right public lane, and use the stable read-only tools without overclaiming hosted or write-capable support.
+triggers:
+  - cortexpilot
+  - cortexpilot setup
+  - cortexpilot mcp
+  - cortexpilot proof
+  - cortexpilot workflow
 ---
 
-# Purpose
+# CortexPilot Adoption Router
 
-Use this skill when a coding-agent workflow needs the shortest honest CortexPilot
-entrypoint.
+Use this skill when the user needs the shortest truthful path into CortexPilot.
 
-The job is to pick the right adoption lane first instead of treating every host
-tool as the same kind of plugin system.
+## What this skill teaches
 
-# Read Order
+- how to install the published CortexPilot MCP package
+- how to choose the right read-only tool for the current job
+- how to start with one public lane instead of mixing every surface together
+- how to keep the answer inside the current read-only public boundary
 
-1. `README.md`
-2. `docs/README.md`
-3. `docs/compatibility/index.html`
-4. `docs/integrations/index.html`
-5. One deeper lane only:
-   - `docs/mcp/index.html`
-   - `docs/skills/index.html`
-   - `docs/builders/index.html`
-   - `docs/use-cases/index.html`
+## When to use this skill
 
-# Use It To Choose A Lane
+Use this skill when the user asks to:
 
-- Start with **read-only MCP** when the first need is machine-readable
-  inspection.
-- Start with **skills** when the first need is repeatable repo-owned behavior.
-- Start with **builders** when the first need is package-level reuse.
-- Start with **use cases** when the first need is proof-first product
-  understanding.
+- connect CortexPilot to OpenHands or OpenClaw
+- inspect runs or workflows through the public read-only MCP
+- understand which public CortexPilot lane to choose first
+- inspect approvals, queue state, proof, compare, or incident summaries without
+  mutating anything
 
-# Guardrails
+## If the MCP is not connected yet
+
+Open `README.md` in this folder and follow `references/mcp-install.md`.
+Do not invent repo-local startup paths when the published package already
+exists.
+
+## Safe-first workflow
+
+1. `list_runs` or `list_workflows`
+   Use these first when the user needs the top-level ledger.
+2. `get_run` or `get_workflow`
+   Use these after the user already has the specific run or workflow to inspect.
+3. `list_queue`, `get_pending_approvals`, or `get_diff_gate_state`
+   Use these for queue, approval, or diff-gate posture.
+4. `get_run_reports`, `get_compare_summary`, `get_proof_summary`, or
+   `get_incident_summary`
+   Use these after the user is already inside one run and needs a specific
+   proof-oriented read model.
+
+## Tool-selection rule
+
+- Choose run/workflow reads for “what is happening now?”
+- Choose queue/approval reads for “what is blocked or pending?”
+- Choose compare/proof/incident reads for “what evidence exists for this run?”
+- Do not mix multiple lanes unless the user explicitly asks for a broader audit
+
+## What to return
+
+Return a short answer with:
+
+1. the chosen lane
+2. the next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet
+
+## Guardrails
 
 - Do not describe CortexPilot as a hosted operator product.
 - Do not describe the public MCP surface as write-capable.
-- Do not claim this bundle is a published Codex or OpenClaw listing.
-- Do not describe Claude Code as if it has a CortexPilot marketplace package.
-- Keep `task_contract` as the only execution authority.
+- Do not claim a first-party marketplace listing unless that host independently
+  confirms it.
+- Keep `task_contract` as the execution authority for real runs; this MCP is
+  read-only inspection only.
 
-# Done Signal
+## Read next
 
-The adoption path is correct only when the chosen lane matches the real job and
-the wording stays below official-listing or hosted-product claims.
+- `references/mcp-install.md`
+- `references/tool-map.md`
+- `references/example-tasks.md`

public-skills/cortexpilot-adoption-router/SKILL.md

@@ -1,11 +1,11 @@
 schema_version: 1
 name: cortexpilot-adoption-router
 display_name: CortexPilot Adoption Router
-version: 1.0.0
+version: 1.1.0
 summary: >
-  Public skill package that routes Codex, Claude Code, OpenHands, and OpenClaw
-  style workflows to the right CortexPilot adoption lane without overclaiming
-  hosted or write-capable support.
+  Public skill bundle for CortexPilot that packages MCP install guidance, a
+  read-only tool map, and a truthful lane-selection workflow for OpenHands and
+  OpenClaw style hosts.
 homepage: https://github.com/xiaojiou176-open/CortexPilot-public
 repository: https://github.com/xiaojiou176-open/CortexPilot-public
 license: MIT
@@ -15,23 +15,25 @@ entrypoints:
   skill_markdown: SKILL.md
 compatibility:
   openhands:
-    mode: skill directory
+    mode: skill directory plus published MCP config
     published_listing: false
   clawhub:
-    mode: skill publish
-    published_listing: false
+    mode: skill publish plus published MCP config
+    published_listing: true
 capabilities:
-  - route users to the truthful CortexPilot adoption lane
-  - preserve read-only MCP and starter-only boundaries
+  - install the published CortexPilot MCP package in host-specific config
+  - expose the stable read-only CortexPilot tool inventory
+  - route users to the truthful CortexPilot lane for runs, workflows, queue, and proof reads
   - keep hosted and write-capable claims gated
 boundaries:
   hosted_operator: false
   write_capable_mcp: false
   oauth_login: false
-  official_listing_live: false
+  official_listing_live: true
 distribution_notes:
-  current_claim: skill package is ready for registry submission, but no external registry listing should be claimed until it is confirmed live
+  current_claim: ClawHub listing is live; other hosts should only claim submission or live state when independently confirmed.
 verification:
   repo_commands:
     - npm run docs:check
     - bash scripts/check_repo_hygiene.sh
+    - printf '%s\n%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"bundle-audit","version":"0.0.0"}}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | uvx --from cortexpilot-orchestrator==0.1.0a4 cortexpilot-readonly-mcp

public-skills/cortexpilot-adoption-router/manifest.yaml

@@ -0,0 +1,15 @@
+# Example Tasks
+
+Use this bundle for tasks like:
+
+- “Connect CortexPilot to OpenHands and inspect the run ledger.”
+- “Which CortexPilot MCP tool should I call first for workflow truth?”
+- “Show me the safest read-only lane for approvals or queue state.”
+- “Inspect proof or incident summaries without mutating anything.”
+
+Return shapes should stay short and operational:
+
+1. chosen lane
+2. next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet

public-skills/cortexpilot-adoption-router/references/example-tasks.md

@@ -0,0 +1,42 @@
+# Install The Published CortexPilot MCP
+
+Use the published PyPI package, not a repo-local checkout.
+
+## Published package
+
+- package: `cortexpilot-orchestrator==0.1.0a4`
+- executable: `cortexpilot-readonly-mcp`
+- transport: `stdio`
+
+## OpenHands example
+
+Add the server to `~/.openhands/config.toml`:
+
+```toml
+[mcp]
+stdio_servers = [
+  { name = "cortexpilot-readonly", command = "uvx", args = ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"] }
+]
+```
+
+## OpenClaw example
+
+Add the server to your saved MCP server config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "cortexpilot-readonly": {
+        "command": "uvx",
+        "args": ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"]
+      }
+    }
+  }
+}
+```
+
+## Smoke check
+
+Use a minimal MCP handshake and `tools/list` request after the host attaches the
+server.

public-skills/cortexpilot-adoption-router/references/mcp-install.md

@@ -0,0 +1,33 @@
+# CortexPilot MCP Tool Map
+
+These are the stable read-only tools exposed by the published CortexPilot MCP.
+
+## Safe-first tools
+
+1. `list_runs`
+   Use first when the user needs the current run ledger.
+2. `get_run`
+   Use when the user already has one run identifier and needs the run snapshot.
+3. `list_workflows`
+   Use when the user needs the current Workflow Case ledger.
+4. `get_workflow`
+   Use when the user already has one workflow identifier.
+
+## Queue and approval tools
+
+- `list_queue`
+- `get_pending_approvals`
+- `get_diff_gate_state`
+
+Use these when the user is inspecting queue state, pending approvals, or diff
+gate posture.
+
+## Proof and incident tools
+
+- `get_run_reports`
+- `get_compare_summary`
+- `get_proof_summary`
+- `get_incident_summary`
+
+Use these after the user is already inside a specific run and wants the proof,
+compare, or incident read model.