coding-os 0.3.2__py3-none-any.whl

coding_os-0.3.2.dist-info/METADATA

@@ -0,0 +1,508 @@
+Metadata-Version: 2.4
+Name: coding-os
+Version: 0.3.2
+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
+
+[![release](https://img.shields.io/badge/release-v0.3.2)](https://github.com/kouroshez/coding-os/releases) <!-- x-release-please-version -->
+[![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)
+[![tests](https://img.shields.io/badge/tests-passing-green)](./tests/)
+[![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.
+>
+> Website: <https://coding-os.dev> · Community: <https://community.coding-os.dev>
+
+---
+
+## 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: --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.
+
+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`.
+
+### Choosing how much coding-os you install
+
+The kernel ships as **subsystem modules** — docs, tasks (Scrumban), knowledge
+graph, agent memory, cognition, observability, hub extras, CI/CD — and you pick
+the set at create time. Prefer a small MCP surface, or don't want the web panel
+at all? Start lean:
+
+```bash
+cos init --agent claude --name my-app --profile lite --yes   # kernel only: discipline + safety
+cos init --agent claude --name my-app --profile full --yes   # every subsystem
+cos init --agent claude --name my-app --disable-module memory --yes
+```
+
+`cos init --help` lists the live profiles and module ids (both are read from
+`src/core/subsystems.yaml`, so the help never drifts). Omitting `--profile`
+applies the registry default — today `standard`, which leaves `cognition` and
+`cicd` off. The two flags are **unioned**: a profile can only remove more, so to
+re-enable something start from a wider profile. Everything stays adjustable
+later with `cos module enable|disable` or Hub **Config → Modules**, and the same
+chips appear in the Composer's *Advanced* section. Full model:
+[meta-project.md § subsystem modules](docs/architecture/meta-project.md).
+
+## 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
+   (FA + EN: همه / all / completely / until done), 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 · 98 `cos` subcommands total)
+
+```
+Project lifecycle    init · adopt · setup · add-adapter · add-stack · update · materialize · eject
+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
+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).
+
+## 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/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                             |
+| [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).