coding-os 0.3.8__tar.gz → 0.3.10__tar.gz

coding_os-0.3.10/PKG-INFO

@@ -0,0 +1,605 @@
+Metadata-Version: 2.4
+Name: coding-os
+Version: 0.3.10
+Summary: The cognitive operating system that gives AI agents memory, structure, and discipline
+Author-email: Kourosh Ebrahimzadeh <info@coding-os.dev>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/kouroshez/coding-os
+Project-URL: Repository, https://github.com/kouroshez/coding-os
+Project-URL: Issues, https://github.com/kouroshez/coding-os/issues
+Keywords: ai,coding-agent,mcp,llm,cli,hexagonal,claude,codex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: click>=8.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: jsonschema>=4.17.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: sse-starlette>=2.1.0
+Requires-Dist: claude-agent-sdk<0.3.0,>=0.2.110
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: rag
+Requires-Dist: sentence-transformers>=2.2.0; extra == "rag"
+Requires-Dist: numpy>=1.24.0; extra == "rag"
+Provides-Extra: graph-os
+Requires-Dist: sentence-transformers>=2.7.0; extra == "graph-os"
+Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "graph-os"
+Requires-Dist: usearch>=2.16; extra == "graph-os"
+Requires-Dist: sqlite-vec>=0.1.9; extra == "graph-os"
+Requires-Dist: tree-sitter<0.26.0,>=0.25.0; extra == "graph-os"
+Requires-Dist: tree-sitter-python<0.26.0,>=0.25.0; extra == "graph-os"
+Requires-Dist: tree-sitter-typescript<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-bash<0.26.0,>=0.25.0; extra == "graph-os"
+Requires-Dist: tree-sitter-yaml<0.8.0,>=0.6.1; extra == "graph-os"
+Requires-Dist: tree-sitter-go<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-php<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: pathspec>=0.12.1; extra == "graph-os"
+Requires-Dist: tree-sitter-rust<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-ruby<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-java<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-c<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-cpp<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-c-sharp<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-scala<0.26.0,>=0.23.0; extra == "graph-os"
+Requires-Dist: tree-sitter-kotlin>=1.0.0; extra == "graph-os"
+Requires-Dist: tree-sitter-lua>=0.4.0; extra == "graph-os"
+Provides-Extra: board-os
+Requires-Dist: aiohttp>=3.9.0; extra == "board-os"
+Requires-Dist: watchdog>=4.0.0; extra == "board-os"
+Provides-Extra: web
+Provides-Extra: claude-sdk
+Provides-Extra: codex-sdk
+Requires-Dist: openai-codex<0.145.0,>=0.144.4; extra == "codex-sdk"
+Dynamic: license-file
+
+# coding-os
+
+[![PyPI](https://img.shields.io/pypi/v/coding-os?color=blue&label=pypi)](https://pypi.org/project/coding-os/)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)
+[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](./pyproject.toml)
+[![CI](https://github.com/kouroshez/coding-os/actions/workflows/ci.yml/badge.svg)](https://github.com/kouroshez/coding-os/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kouroshez/coding-os/badge)](https://scorecard.dev/viewer/?uri=github.com/kouroshez/coding-os)
+[![cli](https://img.shields.io/badge/cli-cos-informational)](./docs/architecture/meta-project.md)
+
+> **Coding OS — the cognitive operating system that gives AI agents memory, structure, and discipline.**
+> Teaches AI agents *how to think* (thinking_os) and *how to code*
+> (workflow, hooks, skills, rules) — agent-agnostic so the same kernel
+> serves Claude Code and OpenAI Codex without rewriting. **Modular by
+> design**: take only what you need — even just the knowledge graph
+> (`--profile lite --enable-module graph`).
+>
+> Website: <https://coding-os.dev> · Community: <https://community.coding-os.dev>
+
+<table>
+<tr>
+<td align="center" width="34%">
+<h3>💛 Sponsor</h3>
+<a href="https://github.com/sponsors/kouroshez"><b>GitHub Sponsors</b></a><br/>
+<a href="https://coding-os.dev/donate">One-off donation</a>
+<br/><sub>Keeps a single maintainer shipping</sub>
+</td>
+<td align="center" width="33%">
+<h3>💬 Community</h3>
+<a href="https://community.coding-os.dev"><b>Forum</b></a><br/>
+<a href="https://github.com/kouroshez/coding-os/discussions">Discussions</a>
+<br/><sub>Questions, setups, rough edges</sub>
+</td>
+<td align="center" width="33%">
+<h3>⭐ Star</h3>
+<a href="https://github.com/kouroshez/coding-os"><b>Follow the repo</b></a><br/>
+<a href="./CHANGELOG.md">Read the changelog</a>
+<br/><sub>The cheapest way to help</sub>
+</td>
+</tr>
+</table>
+
+**Free, and staying that way.** Apache-2.0, no paid tier, no telemetry, no
+gated features — the kernel you run is the whole thing. Sponsorship buys
+maintenance time, not access.
+
+### Right-sized by construction
+
+Loading a whole skill catalogue into every prompt is how agents run out of
+context before they run out of task. coding-os narrows it twice.
+
+**At `cos init`** — a project installs only the stacks it declares. A
+WordPress project gets the `wordpress` skill and never sees `go-patterns`,
+`rails` or `spring-boot`. Alongside them sit the stack-agnostic ones —
+`clean-code`, `testing-strategy`, `api-design`, `a11y`, `security-web` —
+which apply to any codebase.
+
+**On every turn** — what is on disk is not what is in context. A generated
+rules table maps file globs to skills, and the matching skill loads only
+when you are about to write a file it governs. Editing a React component
+loads `nextjs-react`; nothing else comes with it.
+
+What you pay per session is `AGENTS.md` plus the rules of the modules you
+enabled. Disable a module and its rules, tools and slash commands leave with
+it — see [Modular by design](#modular-by-design--take-only-what-you-need).
+
+---
+
+## Prerequisites
+
+| Tool | Min version | Why | macOS install |
+|---|---|---|---|
+| Python | 3.10 | CLI, MCP server, extractors | `brew install python@3.12` |
+| [uv](https://docs.astral.sh/uv/) | 0.5 | Fast Python installer + tool runner | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Bash | 4 | Hook scripts use 4.x features (macOS ships 3.2) | `brew install bash` |
+| Node.js | 20 | **Only** if rebuilding the Hub UI under `src/core/web/ui/` | `brew install node@20` |
+| Docker | 24 | **Only** for the Docker quickstart below | `brew install --cask docker` |
+
+Linux: replace `brew install …` with your distro's package manager
+(`apt`, `dnf`, `pacman`). Windows: WSL 2 + the same Linux steps.
+
+## Quickstart — panel first (one command)
+
+If you would rather click than type, this is the whole install. It preflights
+prerequisites, installs the `cos` CLI, and boots the Hub:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kouroshez/coding-os/main/install.sh | bash
+# …or, from a checkout:  bash install.sh
+```
+
+Open the Hub at `http://127.0.0.1:9188` and press **New project**. The Composer picks a
+preset (or your own stack mix), asks one sentence about the project, and
+scaffolds it — docs, board, knowledge graph, and agent setup included. There is
+no CLI step in between; everything below is the same flow with flags instead of
+clicks. ([ADR-0007](docs/architecture/adr/0007-gui-first-install-path.md))
+
+## 60-second quickstart (native `uv`)
+
+```bash
+# 1. Install the cos CLI globally
+git clone https://github.com/kouroshez/coding-os.git
+cd coding-os
+uv tool install --editable .
+
+# 2. Verify
+cos --version                          # → coding-os, version X.Y.Z
+cos doctor --bootstrap                 # preflight: python/bash/git/uv/sed prerequisites
+cos doctor                             # full health sweep (must be all-green)
+
+# 3. Spawn a new project, scaffolded with an agent + a stack
+#    --agent takes several at once: --agent claude,codex
+cos init --agent claude --template django --name my-shop --yes
+cd my-shop                             # adapter installer ran for you and wrote
+                                       # .claude/, .mcp.json, .coding-os/
+
+# 4. Boot the multi-project Web Hub: graph + board + cognition + search
+cos hub start                          # → http://127.0.0.1:9188
+```
+
+Open `http://127.0.0.1:9188` in your browser. You will see the
+knowledge graph of `my-shop`, the Scrumban board, the cognition
+trace timeline, and unified search across all retrieval layers.
+
+**The Hub is optional.** The CLI-only loop is complete on its own: `cd
+my-shop`, open your agent (e.g. `claude` — MCP + hooks are already
+wired), then `cos daily` / `cos task-create` / `cos task-start` — `cos init`
+prints the exact first commands for your project. Every project ships its own
+guide at `docs/workflow/workflow-guide.md`. For an existing repo, use
+`cos adopt` instead of `init`.
+
+For Codex, swap `--agent claude` for `--agent codex` (or pass
+both — `--agent claude,codex`) — everything else is identical. Each agent's
+installer is `src/adapters/<agent>/install.sh`; `cos init` runs it
+for you and re-runs it on `cos update`.
+
+### Modular by design — take only what you need
+
+coding-os is not all-or-nothing. The **kernel** (session lifecycle + safety) is
+always on; everything else is a **subsystem module** you switch on or off:
+`docs` · `tasks` (Scrumban) · `graph` · `memory` · `cognition` ·
+`observability` · `hub-extras` · `cicd`. Named **profiles** curate the set, so
+the agent's MCP tool surface stays as small as you want it.
+
+Wanted just the knowledge graph? That is the entire install:
+
+```bash
+cos init --agent claude --name my-app --profile lite --enable-module graph --yes
+```
+
+`lite` is kernel-only; `core` adds docs, tasks, graph and the Hub hooks;
+`standard` *(the recommended default)* adds memory + observability; `full` is
+everything. Start lean and change your mind later — from the project root,
+`cos module enable memory`. `--profile` and `--disable-module` are **unioned**:
+they can only remove. `--enable-module` is the escape that keeps one on and
+pulls its dependencies with it — passing the same id to both flags is an error,
+not an override. `cos init --help` lists the live ids straight from
+`src/core/subsystems.yaml`, `cos module list` shows what you ended up with, and
+Hub **Config → Modules** — or the Composer's *Advanced* section at create
+time — flips any of it later. Full model:
+[meta-project.md § subsystem modules](docs/architecture/meta-project.md#the-fourth-axis--subsystem-modules-which-kernel-surfaces-ship).
+
+## Run with Docker (Hub layer; native for projects)
+
+**Architecture split** — adopted because each layer wants a different
+deploy shape:
+
+| Layer | Runs where | Why |
+|---|---|---|
+| **Hub** (web panel: graph · board · cognition · search) | **Docker** (production-shaped) | Reproducible build · isolated runtime · same image dev → CI → prod |
+| **Consumer projects** (each project's `.coding-os/`, MCP server, skills, adapters) | **Host (native)** | Agent runtimes (Claude Code / Codex CLI) live on the host filesystem · `cos init` factory writes alongside your source · IDE/editor needs direct paths |
+
+The Hub container **reads** the host's projects via a read-only bind
+mount and the host's registry file, so every absolute path stays
+valid inside the container — no path translation.
+
+### Quickstart
+
+```bash
+docker compose up
+# → http://127.0.0.1:9188
+```
+
+By default, `docker-compose.yml` bind-mounts `$HOME` read-only at
+the same path inside the container so `cos registry scan ~` finds
+every `.coding-os/` directory below it. Hub state (SQLite, traces)
+lives in the `cos-state` named volume and survives `down` / `up`.
+
+Project auto-discovery, narrowing the mount for production, and manual
+`docker run` (no compose): [docs/engineering/hub-architecture.md § Docker
+deployment](./docs/engineering/hub-architecture.md#docker-deployment-hub-layer).
+
+## MCP server wire-up (Claude / Codex)
+
+`cos init` writes `.mcp.json` at the project root automatically. If
+you ever need to register the MCP server manually (e.g. another tool
+that reads MCP configs), this is the shape every adapter installs:
+
+```json
+{
+  "mcpServers": {
+    "coding-os": { "command": "cos", "args": ["server-start"] }
+  }
+}
+```
+
+Verify the wire is live in your agent runtime:
+
+- **Claude Code:** `cos doctor` shows `mcp.coding-os = ok`; the CLI
+  exposes `cos_*` tools via `ToolSearch("select:<tool>")`.
+- **Codex CLI:** `codex --mcp-list` lists `coding-os`.
+
+If the server isn't found, re-run `bash src/adapters/<agent>/install.sh`
+from the project root, then restart the agent.
+
+---
+
+## What it is
+
+`coding-os` is a three-layer composition (DNA → mRNA → phenotype):
+
+```
+src/core/  ──►  src/adapters/<agent>/  ──►  src/templates/<stack>/  ──►  consumer project
+(DNA)         (mRNA)                       (phenotype)                 (organism)
+```
+
+| Layer            | What it owns                                                       |
+| ---------------- | ------------------------------------------------------------------ |
+| `src/core/`      | MCP server, hooks, rules, skills — **agent-agnostic, stack-agnostic** |
+| `src/adapters/`  | Per-agent translation: `.claude/`, `.codex/` rendering             |
+| `src/templates/` | Per-stack overlays: 27 stacks — Django, Next.js, FastAPI, Laravel, Rails, Flutter, Go, Rust, … (`cos list-stacks`) |
+| `src/cli/`       | The `cos` factory CLI that composes the three layers               |
+
+Adding a new stack or a new agent is a pure YAML + Markdown change.
+No Python edits required.
+
+## What it does
+
+1. **Complexity Gate** — classifies problems before acting (Cynefin:
+   CLEAR / COMPLICATED / COMPLEX / CHAOTIC / CONFUSION).
+2. **Cognitive Cycle** — CLASSIFY → ORIENT → PLAN → EXECUTE → VERIFY.
+   The kernel rule (`src/core/rules/thinking_os.md`) is always
+   active; the deep skill loads only when the gate returns COMPLICATED
+   or COMPLEX.
+3. **Self-learning memory** — SQLite-backed observations, metrics,
+   and learned patterns across sessions (`cos_search`, `cos_learn_*`).
+4. **Hook enforcement** — hooks gate writes, edits, prompts,
+   sessions, and stops (exact count in `src/core/hooks/registry.yaml`).
+   Adapter parity matrix in `docs/engineering/`.
+5. **Four-layer retrieval** — agent memory (`cos_search`) · doc RAG
+   (`cos_doc_search`) · task graph (`cos_task_*`) · knowledge graph
+   (`cos_graph_*`).
+6. **Intent enforcement** — when the user uses exhaustive vocabulary
+   ("all" / "every" / "completely" / "until done", matched in English
+   and one additional language), the Stop hook refuses premature "done"
+   until an evidence bundle is recorded.
+7. **Upgrade path** — `cos update` keeps every consumer project in
+   sync with `coding-os` without touching user content.
+
+## Web Hub (`http://127.0.0.1:9188`)
+
+A singleton FastAPI + Vite/React SPA that serves every registered
+project via `/api/p/<slug>/*`:
+
+- **Workspace** — project overview, Scrumban board (kind × swimlane ×
+  epic, WIP enforcement), memory, cognition traces, unified search.
+- **Graph** — Sigma.js canvas with deliberate view modes + smart
+  export + dagre layout.
+- **Config** — modules, git settings, hub settings, per-project chips.
+- **Marketplace** — community skills/stacks (rolling out).
+- **Diagnostics** — health, hooks log, token-burn audit.
+
+`cos hub start` boots the hub. `cos hub status` reports health.
+Source: `src/core/web/`. UI: `src/core/web/ui/` (`npm run dev`).
+
+## Architecture
+
+```
+coding-os/
+├── src/                # All importable code (Python src-layout)
+│   ├── cli/              # Factory entrypoint (`cos` command)
+│   ├── core/             # Agent-agnostic brain (DNA)
+│   │   ├── thinking_os/    # MCP server: memory, learning, metrics, cognition
+│   │   ├── graph_os/       # Polyglot knowledge graph (SQLite backend)
+│   │   ├── board_os/       # Scrumban task system
+│   │   ├── web/            # Hub UI + FastAPI backbone
+│   │   ├── hooks/          # Hook scripts (SSOT: registry.yaml)
+│   │   ├── rules/          # Always-active rules + auto-generated artifacts
+│   │   ├── skills/         # Universal skills
+│   │   └── scripts/        # Kernel-internal regen tooling
+│   ├── adapters/         # Per-agent translation (mRNA, adapter.yaml manifests)
+│   │   ├── claude/         # Claude Code adapter
+│   │   └── codex/          # OpenAI Codex CLI/Desktop adapter
+│   ├── templates/        # Per-stack scaffolds (phenotype, stack.yaml-driven)
+│   │   ├── _base/          # Generic base + fragments/
+│   │   ├── django/         # Django + DRF + PostgreSQL
+│   │   ├── nextjs/         # Next.js + React + TypeScript + Tailwind
+│   │   ├── fastapi/        # FastAPI + Pydantic + SQLAlchemy
+│   │   ├── go/             # Go stdlib + chi router
+│   │   ├── go-fiber/       # Go + Fiber v3
+│   │   ├── react-native/   # React Native + Expo
+│   │   ├── python/         # Python library / CLI / MCP server
+│   │   ├── meta/           # Meta-stack (for coding-os contributors)
+│   │   └── …               # 27 stacks total — `cos list-stacks`
+│   └── scripts/          # Maintenance + regen tooling
+├── tests/              # cross-cutting tests
+├── docs/               # Governance, engineering, playbooks, architecture
+└── .coding-os/         # Per-project runtime state (gitignored)
+```
+
+## Command index (highlights · 99 `cos` subcommands total)
+
+```
+Project lifecycle    init · adopt · setup · add-adapter · add-stack · update · materialize · eject
+Modules              module list · module enable · module disable   (per-project surface control)
+Diagnostics          doctor · health · list-stacks · list-adapters · hooks-dir · hooks-log
+Hub                  hub start · hub status · hub stop
+Board                board · task-create · task-start · task-move · task-done · daily · retro · wip
+Cognition            cognition trace · trace-replay · trace-summary
+Supervision          supervision show · enable · disable · set   (per-role adapter/model/effort)
+Graph                29 graph-* subcommands (build · find · deps · analysis · review);
+                     22 mirror a cos_graph_* MCP tool one-for-one, enforced by a parity test
+```
+
+Full catalogue with flows: [docs/architecture/meta-project.md](./docs/architecture/meta-project.md).
+
+## Slash commands (25 commands)
+
+The `cos` CLI above is the *factory*. Inside an agent session you also get
+**slash commands** — packaged workflows invoked by typing `/`: 11 workflow
+commands (`/board`, `/daily`, `/retro`, `/task`, `/classify`, `/compose`,
+`/memory-search`, `/verify`, `/review`, `/diagnose`, `/new-project`) and 14
+`/role-*` commands (the semantic roles of the cognition chain). They ship in
+`.claude/commands/` (and `.codex/commands/`) and are version-controlled, so
+every teammate gets them on clone. Day-to-day usage:
+[docs/workflow/workflow-guide.md](./docs/workflow/workflow-guide.md).
+
+## MCP tools (`cos_*` family, all `ok / fail` envelope)
+
+One MCP server (launched by `.mcp.json` → `cos server-start`) exposes every
+`cos_*` tool across ten families: health, memory (`cos_search`), learning,
+metrics, routing, docs (`cos_doc_search`), tasks (`cos_task_*`), graph
+(`cos_graph_*`, 22 tools), cognition (`cos_compose_chain`), and retrieval.
+Per-tool docs + envelope spec:
+[docs/governance/mcp-tool-inventory.md](./docs/governance/mcp-tool-inventory.md).
+
+## The knowledge graph — why it changes the economics
+
+Most "AI coding" tools answer structural questions ("who calls this?",
+"what breaks if I rename it?", "where does this data flow?") by *reading
+files* until the agent guesses an answer. That burns tokens, slows the
+loop, and produces hallucinations the moment a caller lives in a file
+the agent didn't open.
+
+coding-os ships a precomputed knowledge graph as the **third retrieval
+layer** alongside memory and docs. Every commit refreshes 23 node kinds
+(functions, methods, classes, modules, routes, MCP tools, docs,
+headings, frontmatter, hooks, rules, skills, tasks, …) and 18 edge
+types (`contains`, `calls`, `imports`, `inherits_from`,
+`handles_route`, `has_param_type`, `references_doc`, `is_decorated_by`,
+`links_to`, …). The agent then asks the graph — `cos_graph_references`,
+`cos_graph_impact`, `cos_graph_rename_plan` — and gets a small,
+high-confidence JSON envelope back.
+
+### Benchmark — graph vs read-the-file (live repo · 33,548 nodes · 72,797 edges)
+
+"What breaks if I change X?" answered two ways — read **every caller
+file** to be *sure* you caught them all (the safe manual path), vs one
+`cos_graph_*` envelope. Token counts are **measured** on this codebase
+(file bytes ÷ 4; tool `tokens_estimated` from the live envelope):
+
+| Question | Graph tool (result) | Manual: read all callers | Graph envelope | **Savings** |
+|---|---|---:|---:|---:|
+| What breaks if `init_db` changes? | `cos_graph_impact` — 508 impacted | 100 files ≈ 456,000 tok | **7,962 tok** | **98.3%** |
+| Who must a `GraphNode` rename touch? | `cos_graph_rename_plan` — 118 sites, risk=high | 26 files ≈ 170,000 tok | **7,519 tok** | **95.6%** |
+| Who sources `cos-env.sh`? | `cos_graph_references` — 79 refs | grep + open each hook | **579 tok** | ~99% |
+
+The exact numbers shift per machine and per tokenizer — the **ratio**
+(roughly 20–100× less context) is what holds. The leanest queries
+(`cos_graph_references(limit=20)`) answer in 140–600 tokens vs 2K–24K
+for even a *single* file Read. Every envelope carries `total_count` +
+`truncated`, so the agent knows when it has the whole answer — no silent
+truncation.
+
+The savings compound: an agent asking 50 structural questions over a
+feature spends ~50–400 KB of context, not the multiple MB an exhaustive
+file sweep would cost — leaving the budget for actual reasoning.
+
+### Coverage, budgets, health — the anti-hallucination contract
+
+Every coverage-sensitive tool reports its own incompleteness
+(`total_count` · `result_truncated` · `walk_truncated` — never silent),
+all 23 node kinds answer end-to-end in 0–23 ms, `cos_graph_doctor`
+sweeps stale nodes, and every Write/Edit re-indexes just the touched
+file. The full contract — budget knobs, per-kind latency, Hub view
+modes, and the probe-then-widen workflow — lives in
+[graph_os-queries.md § Coverage, budgets, and benchmarks](./docs/engineering/graph_os-queries.md#coverage-budgets-and-benchmarks-readme-deep-dive).
+
+Deep dive: [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-queries.md)
+· [docs/engineering/graph-hallucination-cures.md](./docs/engineering/graph-hallucination-cures.md)
+· [docs/governance/mcp-tool-inventory.md](./docs/governance/mcp-tool-inventory.md).
+
+## Supported agents
+
+| Agent | Hook coverage | Skills | MCP server | Notes |
+| --- | --- | --- | --- | --- |
+| Claude Code | Full for its native events ✅ | Native skills | ✅ | No native `SessionEnd`. |
+| Codex CLI | Full for supported Codex events ✅ | Native agent skills | ✅ | Includes Bash, Read, `apply_patch`, MCP, prompt, compact, subagent, permission, Stop, and SessionEnd hooks. |
+| Codex Desktop | Same project hook/config contract as Codex CLI ✅ | Native agent skills | ✅ | Project hooks require trust/review; Hub observability is native, while Hub interactive chat is still Claude-only. |
+
+Parity matrix + reasoning: [docs/engineering/adapter-parity.md](./docs/engineering/adapter-parity.md)
+(the 2026-04-25 workflow audit is a historical snapshot predating Codex parity).
+
+## Agent supervision — pick the model per role (opt-in)
+
+Off by default. Turn it on and each of the 11 semantic roles can run on its own
+adapter, model, and reasoning effort — a cheap model reviewing, an expensive one
+architecting. It works with a **single** adapter too: routing across Claude's own
+model tiers is the common case, not a fallback.
+
+```bash
+cos supervision enable
+cos supervision set --orchestrator-model claude-sonnet-5     # project default
+cos supervision set --role reviewer  --role-model claude-haiku-4-5 --role-effort low
+cos supervision set --role architect --role-model claude-opus-4-8  --role-effort xhigh
+cos supervision show
+```
+
+Adapters and their model catalogs are discovered from `adapter.yaml`, so a new
+runtime is configurable the day it is installed.
+
+When a provider reports a rate limit, only the **model pool** that hit it goes
+into a persistent cooldown — providers meter each pool separately, so an
+exhausted Opus pool must not stop a reviewer running on Haiku. Recovery is one
+half-open probe, not a retry storm against a limit that cannot succeed.
+
+Same policy from the Hub (**Config → Settings**), the CLI, or MCP — no Hub
+required. Disabled means disabled: no probe, no state write, no tokens.
+
+Full contract: [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)
+· operator guide: [docs/playbooks/agent-supervision-setup.md](./docs/playbooks/agent-supervision-setup.md)
+
+## Configuration
+
+`.coding-os.yaml` at every project root:
+
+```yaml
+version: "1.0"
+agents: [claude, codex]
+templates: [django, nextjs]
+state_dir: .coding-os
+code_extensions: [py, ts, tsx]
+verify:
+  backend: "make lint-backend && make test-backend"
+  frontend: "cd src/frontend && npm run lint && npm test"
+protected_files:
+  - "*/migrations/*.py"
+```
+
+## Adding a new stack (zero Python changes)
+
+Create `src/templates/<id>/stack.yaml` plus skills, rules, and scaffold
+docs — the CLI auto-discovers it (`cos list-stacks`), then
+`make manifest-regen && make regen-rules` refreshes the derived
+artifacts. The same pattern works for new **adapters**
+(`src/adapters/<id>/adapter.yaml` + `install.sh`). Step-by-step:
+[docs/playbooks/template-authoring.md](./docs/playbooks/template-authoring.md)
+· [docs/playbooks/adapter-authoring.md](./docs/playbooks/adapter-authoring.md).
+
+## Project structure (for contributors)
+
+```bash
+make verify-hooks         # shellcheck + bash -n on every hook
+make verify               # matrix-targeted tests for what changed
+make test-mcp             # MCP self-test (cold start)
+make docs-lint            # markdown structure + link integrity
+cos health                # cross-project health summary
+make manifest-regen       # refresh src/core/scaffold_manifest.json
+make regen-rules          # refresh dimension-registry + skill-enforcement
+```
+
+CI runs the matrix on every PR. See `.github/workflows/ci.yml`.
+
+## Documentation
+
+| Doc                                                                                 | What's in it                                                |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| [AGENTS.md](./AGENTS.md)                                                            | **Agent entry point** — Core Loop, Critical Rules, Verification Matrix |
+| [docs/architecture/meta-project.md](./docs/architecture/meta-project.md)            | Hexagonal design, DNA/mRNA/phenotype, propagation matrix    |
+| [docs/governance/critical-rules.md](./docs/governance/critical-rules.md)            | 27 critical rules with rationale + repair steps             |
+| [docs/governance/mcp-tool-inventory.md](./docs/governance/mcp-tool-inventory.md)    | Per-tool spec + envelope contract                           |
+| [docs/governance/agent-workflow.md](./docs/governance/agent-workflow.md)            | Domain routing, task protocol, memory contract              |
+| [docs/engineering/graph_os-queries.md](./docs/engineering/graph_os-queries.md)      | When to query the graph vs grep                             |
+| [docs/engineering/hub-architecture.md](./docs/engineering/hub-architecture.md)      | Hub: FastAPI ↔ React SPA contract                           |
+| [docs/engineering/agent-supervision.md](./docs/engineering/agent-supervision.md)    | Per-role adapter/model routing, capacity breaker, trigger modes |
+| [docs/playbooks/](./docs/playbooks/)                                                | Hook authoring · adapter authoring · template authoring · MCP tool authoring |
+| [docs/adapters/](./docs/adapters/)                                                  | Claude SDK · Codex CLI integration                          |
+| [CONTRIBUTING.md](./CONTRIBUTING.md)                                                | Setup, contribution loop, PR checklist                      |
+| [SECURITY.md](./SECURITY.md)                                                        | Vulnerability disclosure policy                             |
+| [GOVERNANCE.md](./GOVERNANCE.md)                                                    | Decision model, quality gates, becoming a maintainer        |
+| [KNOWN_LIMITATIONS.md](./KNOWN_LIMITATIONS.md)                                      | Honest constraints + the ratchets that shrink them          |
+| [docs/governance/stability-contract.md](./docs/governance/stability-contract.md)    | What 1.0 freezes + the deprecation ladder                   |
+| [CHANGELOG.md](./CHANGELOG.md)                                                      | Release notes                                               |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `cos: command not found` after `uv tool install` | `~/.local/bin` (or uv's tool dir) not on `PATH` | `uv tool update-shell` then open a new shell |
+| `cos doctor` reports `mcp.coding-os = absent` | Adapter installer hasn't run for this project | `bash src/adapters/<agent>/install.sh` from project root, then restart the agent runtime |
+| `cos hub start` fails with `Address already in use :9188` | Port 9188 busy (likely an old Hub still running) | `lsof -ti:9188 \| xargs kill` then re-run; or `cos hub start --port 9999` |
+| `make verify` complains `bash: declare -A …` | macOS default bash 3.2 doesn't have associative arrays | `brew install bash` (Makefile picks up `/opt/homebrew/bin/bash` automatically) |
+| `cos init` fails on `npm ci` step | Node.js missing or below 20 | Install Node ≥20 (`brew install node@20`); only required if your template touches `src/core/web/ui/` |
+| Docker build OOM on `npm ci` | Default Docker memory < 4 GB | Docker Desktop → Settings → Resources → bump memory to 4 GB+ |
+| `ToolSearch` returns `InputValidationError` for a `cos_*` tool | First-call schema not loaded (Claude defers MCP schemas) | `ToolSearch("select:cos_<name>")` first, then call the tool |
+| Codex hook is skipped | Project/hash trust is missing, the hooks feature is disabled, or the event/matcher is unsupported | Run `/hooks`, confirm `[features] hooks = true`, then inspect `cos hooks-list --agent codex` |
+| Hub rejects the meta-repo checkout with `sits inside … already a coding-os project` | A stray `.coding-os/` exists higher up (e.g. `~/.coding-os/` from a test run) — fixed 2026-05-23: only **registered** ancestors block | Update + restart Hub: `git pull && cos hub stop && cos hub start`. If still blocking, the ancestor is genuinely registered: `cos registry remove <ancestor-path>` |
+
+Still stuck? Run `cos doctor --verbose` and open a
+[discussion](https://github.com/kouroshez/coding-os/discussions)
+with the output attached.
+
+## Support / Community
+
+If coding-os saves you time, a star helps others find it. These links also
+live in the Hub footer (never inside the new-project Composer).
+
+- ★ Star / follow on GitHub: <https://github.com/kouroshez/coding-os>
+- Sponsor the project: <https://github.com/sponsors/kouroshez> · <https://coding-os.dev/donate>
+- Questions / ideas: <https://github.com/kouroshez/coding-os/discussions>
+- Community forum: <https://community.coding-os.dev>
+
+## License
+
+Apache License 2.0 — see [LICENSE](./LICENSE). Copyright 2026
+Kourosh Ebrahimzadeh and coding-os contributors.
+
+Development began in April 2026; the full history is preserved in this
+repository. Release automation (release-please) starts at the 0.3.0
+baseline (2026-05-20) — see [CHANGELOG.md](./CHANGELOG.md).