@kal-elsam/kairo-runtime 0.13.0 → 0.14.0

package/README.md

@@ -1,1228 +1,100 @@
 # Kairo Runtime
 
 [![npm version](https://img.shields.io/npm/v/@kal-elsam/kairo-runtime.svg)](https://www.npmjs.com/package/@kal-elsam/kairo-runtime)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**Kairo Runtime** is a local agent operating system — not a template dumper and not an
-installer for AI apps. It detects agents you already use (Cursor, Codex, OpenCode,
-Claude), writes managed sections into their configs, installs coordination components
-under `~/.harness`, and keeps that ecosystem healthy with status, sync, backups,
-and rollback.
+Kairo finds the AI agents you already use — Cursor, Codex, Claude, OpenCode — and keeps
+their configuration under control. One place to see what's set up, repair what drifted,
+and roll back when something breaks.
 
-The npm package (`@kal-elsam/kairo-runtime`) is how Kairo Runtime is distributed. The
-product identity is the local control plane: setup, status, sync, doctor (with `update`
-as a technical alias).
+It does not install AI apps and it does not dump templates. It manages marked sections
+inside the configs you already have, and it never writes without asking.
 
-`@kal-elsam/harness` remains available as a **compatibility bridge** that delegates to
-Kairo Runtime and prints a migration warning. Prefer `@kal-elsam/kairo-runtime` and the
-`kairo` CLI for new installs. See [`packages/harness-bridge/README.md`](packages/harness-bridge/README.md).
-
-Terminal UX is **terminal-first**: bare `kairo` opens the Ink Control Center (or Setup
-when unconfigured). Explicit commands (`setup`, `status`, `sync`, `doctor`, `monitor`,
-`shell`, …) keep their current behavior. Progressive disclosure keeps paths and IDs in
-Details, list caps honest (`… N more`), and Callout reserved for status — never for
-primary values. No web loopback / `kairo ui` in this release.
-
-- **npm:** https://www.npmjs.com/package/@kal-elsam/kairo-runtime
-- **repo:** https://github.com/Kal-elSam/harness
-
-## Quick start
-
-Recommended entry — run Kairo Runtime in your terminal:
+## Start
 
 ```bash
 npx @kal-elsam/kairo-runtime
-# or, after a global install:
-kairo
-```
-
-**First run** (no `~/.harness/state.json`): semantic Setup (Detect → Agents →
-Components → Preview → Confirm) → full-screen Control Center.
-
-**Later runs** (state present): semantic Cockpit — Overview, Governance, Activity,
-Orchestration, Usage, Settings — plus Alerts inbox. Layout adapts to terminal size:
-
-| Mode | Size | Layout |
-|------|------|--------|
-| Wide | ≥100 cols × ≥28 rows | TopBar + nav strip + main panel + footer |
-| Compact | ≥72×20 | Same single-panel shell (tighter lists) |
-| Minimal | 60–71 cols or short height | Selected section + essential readiness/next |
-| Below gate | <60 cols | Explicit TTY fallback (Ink disabled) |
-
-Keys: `↑↓` navigate · `Enter` open/activate · `/` actions palette ·
-`Esc` back (exit only from Overview) · `R` refresh/retry · `C` cancel run ·
-`?` help. `Tab` switches region when content is interactive (runs, alerts,
-Activity, Settings, launch).
-
-Navigation: Overview · Governance · Activity · Orchestration · Usage · Settings.
-
-### Monitor (opt-in)
-
-```bash
-kairo monitor enable
-kairo monitor status
-kairo monitor tick
-kairo monitor disable
-```
-
-Scans governance drift and orphan/failed runs into the alert store. On macOS,
-`enable` can install a LaunchAgent; other OS degrade honestly. Notifications fire
-only when a new alert claim succeeds.
-
-### Settings (curated integrations)
-
-Settings browses a curated catalog (pinned `pi-usage-widget@0.2.1`, MIT).
-Preview → confirm shows an in-session confirmation receipt (`wroteFiles: false`);
-it does not persist or install anything.
-
-### Usage evidence
-
-Usage shows measured budget pairs, profile limits, and finite run `tokenUsage`
-fields only. It never invents totals, costs, or savings.
-
-Respects `NO_COLOR`, `HARNESS_ASCII=1`, and `HARNESS_INK=0`. Status is always labeled
-in text, never color alone.
-
-Explicit commands and setup flags keep their current behavior (`kairo setup`,
-`kairo --dry-run`, `kairo shell`, non-TTY scripts, etc.).
-
-Preview setup without writing anything:
-
-```bash
-npx @kal-elsam/kairo-runtime --dry-run
-```
-
-One-liner bootstrap (checks Node/npm, previews the plan, writes nothing by default):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh
-```
-
-Preview the installer plan only (no download, no network package run):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --dry-run
-```
-
-The bootstrap installer:
-
-- requires Node.js 20.12+ and npm
-- installs `@kal-elsam/kairo-runtime` globally (`kairo` CLI)
-- runs `kairo setup --dry-run` by default (no agent configs, no `~/.harness` writes)
-- never uses `sudo`, never modifies shell profiles, and never installs AI apps
-
-Apply the plan when you are ready:
-
-```bash
-kairo setup --yes
-# or
-curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --yes
-```
-
-CI, scripts, and advanced non-interactive configure:
-
-```bash
-kairo install --agents cursor,codex --yes
-kairo setup --yes --agents all
-```
-
-Passthrough examples:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --agents all --yes
-curl -fsSL https://raw.githubusercontent.com/Kal-elSam/harness/main/scripts/install.sh | sh -s -- --components orchestrator,sdd-core --yes
-```
-
-Control plane:
-
-```bash
-kairo status
-kairo sync
-kairo upgrade --dry-run
-kairo setup --yes
 ```
 
-After `install.sh --yes`, verify health with `kairo status`, repair drift with `kairo sync`,
-and preview upgrades with `kairo upgrade --dry-run`.
-
-### Version and updates
-
-```bash
-# Installed CLI version (local package / PATH)
-kairo --version
-npx @kal-elsam/kairo-runtime --version
-
-# Latest published version on npm
-npm view @kal-elsam/kairo-runtime version
+That's it. The first run walks you through setup; after that it opens the cockpit:
 
-# Converge to the latest published package
-kairo upgrade --dry-run
-npx @kal-elsam/kairo-runtime@latest setup --yes
-npx @kal-elsam/kairo-runtime@latest sync
 ```
+KAIRO
 
-### npm alternative
-
-If you prefer npm directly (no curl):
-
-```bash
-npx @kal-elsam/kairo-runtime
-npx @kal-elsam/kairo-runtime --dry-run
-npx @kal-elsam/kairo-runtime install --agents cursor,codex --components orchestrator,sdd-core --yes
-```
+Needs attention · 4/4 agents · drift pending
+Kairo coordinates installed AI agents for this project.
 
-Optional global install:
+→ Repair 3 changes
+  You will see the exact plan before anything is written.
 
-```bash
-npm i -g @kal-elsam/kairo-runtime
-kairo --version
+  Configure
+  Agents, Obsidian vault, integrations.
 ```
 
-Legacy opt-in: scaffold governance files into a repository:
-
-```bash
-npx @kal-elsam/kairo-runtime install --scope=workspace
-```
+`↑↓` move · `Enter` open · `Tab` nav · `Space` details · `R` refresh · `Esc` back · `?` help
 
-## CLI commands
+## Day-to-day commands
 
-| Command | Description |
+| Command | What it does |
 |---|---|
-| `kairo` | Primary — short and direct |
-| `kairo-runtime` | Descriptive alias |
-| `harness` | Legacy alias (prefer `kairo`) |
-| `agentic-harness` | Legacy descriptive alias |
-
-```bash
-kairo --version
-kairo
-kairo --dry-run
-kairo setup
-kairo setup --dry-run
-kairo setup --agents all
-kairo install --agents cursor,codex --yes
-kairo status
-kairo status --json
-kairo adapters
-kairo adapters --json
-kairo sync
-kairo sync --dry-run
-kairo sync --dry-run --json
-kairo policy
-kairo policy --json
-kairo policy set profile safe
-kairo policy reset
-kairo install
-kairo install --agents all
-kairo install --agents cursor,codex --components orchestrator,sdd-core
-kairo doctor
-kairo doctor --json
-kairo orchestrator --json
-kairo intelligence status
-kairo intelligence models
-kairo intelligence context --json
-kairo intelligence route --task "explain architecture"
-kairo intelligence ask --prompt "Summarize project risks" --json
-# Cloud (OpenRouter/free) only after explicit consent + confirm:
-# OPENROUTER_API_KEY=... kairo intelligence ask --prompt "..." --cloud-consent --yes
-kairo update   # technical alias; prefer sync
-kairo detect
-kairo components
-kairo components validate
-kairo components init <id> --label "<label>"
-kairo components pack <id> --out <file>    # advanced
-kairo components import <file>             # advanced
-kairo backups
-kairo history
-kairo history --command sync --action repaired
-kairo history last --json
-kairo report
-kairo report --json
-kairo report --out ./diagnostics.txt
-kairo rollback --to <snapshot> [--apply]
-kairo uninstall
-kairo install --scope=workspace   # opt-in / legacy
-```
-
-### Intelligence layer
-
-Kairo owns **Harness Engineering** governance: compile relevant project context, route to a backend, and require human confirmation for cloud transmission. It does not store credentials and never reads OpenCode `auth.json`.
-
-| Backend | Detection | Invoke |
-|---|---|---|
-| Ollama | `GET $OLLAMA_HOST/api/tags` (default `http://127.0.0.1:11434`) | Local chat |
-| OpenCode Go | `OPENCODE_API_KEY` → `https://opencode.ai/zen/go/v1` | Chat Completions (subscription labels; entitlement unverified from key alone) |
-| OpenCode Zen | `OPENCODE_API_KEY` → `https://opencode.ai/zen/v1` | Chat Completions + Responses (credits; never auto-spent from Go failures) |
-| OpenCode CLI (`opencode`) | CLI installed + `opencode auth list` providers | `opencode run --format json --model` with an analysis-only preamble (not a universal non-mutation guarantee) |
-| OpenRouter | `OPENROUTER_API_KEY` in env | `openrouter/free` after `--cloud-consent` + `--yes` |
-| Custom HTTP | Profile `customProviders` (`baseUrl`, `modelId`, optional local-only `apiKeyEnv`) | OpenAI-compatible `/chat/completions` |
-
-Routing order: ephemeral CLI `--backend`/`--model` → profile override → Ollama → OpenCode Go → OpenCode Zen → OpenRouter free → diagnostics. OpenCode CLI runtime is override-only (not auto-routed).
-
-```bash
-export OPENCODE_API_KEY=...   # env only; never persisted by Kairo
-kairo intelligence status --json
-kairo intelligence models --backend opencode-go
-kairo intelligence route --backend opencode-go --model kimi-k2.7-code --cloud-consent
-kairo intelligence ask --prompt "Summarize risks" --backend opencode --model opencode/claude-haiku-4-5 --cloud-consent --yes
-```
-
-Detection states stay differentiated: configured ≠ authenticated ≠ entitlement ≠ balance. An API key means a credential is present, not that login, subscription, or spend was verified.
-
-Private paths (`.env`, secrets, keys) are excluded from context packs unless `--include-private`.
-Remote custom providers require explicit cloud consent and cannot receive an `apiKeyEnv` credential in 0.2.0; use a built-in provider or a local custom endpoint for env-backed authentication.
-
-Legacy CLI aliases (backward compatible): `harness`, `agentic-harness`, `sgs-harness`, `harness-sgs`
-
-`kairo help` lists commands and JSON support; longer examples live in this README.
-
-To try locally from this repo:
-
-```bash
-node ./bin/kairo.js setup --dry-run
-node ./bin/kairo.js status
-node ./bin/kairo.js sync --dry-run
-node ./bin/kairo.js adapters --json
-node ./bin/kairo.js install --dry-run
-```
-
-## Supported adapters (agent-global)
-
-Kairo Runtime does **not** install Cursor, Codex, OpenCode, Claude Code, or Pi. It detects
-their home-directory roots and writes managed sections into their config files.
-
-| Adapter | Label | Root | Config file |
-|---|---|---|---|
-| `cursor` | Cursor | `~/.cursor` | `~/.cursor/AGENTS.md` |
-| `codex` | Codex | `~/.codex` | `~/.codex/AGENTS.md` |
-| `opencode` | OpenCode | `~/.config/opencode` | `~/.config/opencode/AGENTS.md` |
-| `claude` | Claude Code | `~/.claude` | `~/.claude/CLAUDE.md` |
-| `pi` | Pi | `~/.pi/agent` | `~/.pi/agent/AGENTS.md` |
-
-Inspect detection and managed state:
-
-```bash
-kairo adapters
-kairo adapters --json
-```
-
-Agent selection defaults:
-
-- If agent roots are detected → configure detected agents only.
-- If none are detected → safe fallback to all five supported adapters.
-- Force all five explicitly:
-
-```bash
-kairo setup --agents all
-kairo install --agents all
-```
-
-### Pi runtime (auditable)
-
-```bash
-kairo run --agent pi --task "Review this repository" --permissions read-only --follow
-```
-
-Launches `pi --mode json --no-session` (optional `--model`). `read-only` maps to
-`--tools read,grep,find,ls`; other permission aliases are rejected (never translated
-to `--approve`). Custom `PI_CODING_AGENT_DIR` blocks config writes in 0.6.0 but does
-not block runtime. Kairo does not install Pi or assert subscription/entitlement.
-
-### Orchestrated Pi (Context Orchestration)
-
-```bash
-kairo run --agent pi --strategy orchestrated --task "..."
-```
-
-Loads the managed minion extension, injects `KAIRO_ORCH_*`, and persists a depth≤1
-DAG under `~/.harness/runs/<rootRunId>/orchestration/state.json`. Normal completion
-seals write-once `receipt.json`; interrupt recovery seals `recovered:true`. Limits:
-concurrency 2, max attempts 2, context compact at 70% / stop at 90%, cascade cancel
-on parent abort. No same-root resume. Direct `--strategy direct` (default) is unchanged.
-
-### Bounded review (Codex / Pi)
-
-Read-only native review against a Git snapshot. Never mutates the repo, never
-auto-fixes, and never persists prompts, diffs, or transcripts. Receipts land under
-`~/.harness/reviews/<reviewId>/receipt.json` (secret-free). Only Codex and Pi are
-`reviewCompatible` in 0.7.0; Cursor / Claude / OpenCode report `false` until audited.
-
-```bash
-kairo review --agent codex
-kairo review --agent pi --base main
-kairo review --agent codex --commit <sha>
-kairo review --agent codex --fail-on high --json
-kairo reviews list [--limit N] [--json]
-kairo reviews show <reviewId> [--json]
-```
-
-`--agent` is always required. Scope is working-tree by default; use `--base` or
-`--commit` (mutually exclusive). Private paths need `--include-private` plus TTY
-confirm or `--yes`/`--confirm`. Exit codes: `0` ok, `1` severity threshold,
-`2` operational/stale/invalid/cancel.
-
-Cockpit: **Runs → Reviews** lists receipts and opens a read-only detail view
-(no launch from Cockpit in v1).
-
-Primary governance flow:
-
-```txt
-scan (read-only) → evidence proposals → preview → confirm → apply → re-scan → recovery
-```
-
-Bare `kairo` opens the Control Center cockpit when the ecosystem is configured.
-Runs stay secondary until setup/repairs/verification are healthy. CLI equivalents
-remain `kairo status` / `kairo diff` / `kairo sync` (or `kairo setup` explicitly).
-
-## Install scopes
-
-| Scope | Default for | Behavior |
-|---|---|---|
-| `agent-global` | bare `kairo`, `setup`, `install`, `update`, `doctor`, `status`, `uninstall` | Primary path. Configures local agent roots, managed sections, `~/.harness` state. No project folders. |
-| `workspace` | `init` only (opt-in/legacy) | Explicit `--scope=workspace`. Copies `repo-template/` into the current repo. |
-
-### `kairo` / `kairo setup`
-
-Bare `kairo` opens the Ink setup UI (**Local Agent Operating System**) in a TTY. `kairo setup --simple` uses the Clack wizard instead. `kairo setup`
-is equivalent. Detects agents, shows a plan, and lets you choose agents/components before
-applying. Use `--dry-run` to preview without writing, or `--yes` / flags to skip prompts.
-Use `kairo install` for explicit non-interactive configure in CI and scripts.
-
-```bash
-kairo
-kairo --dry-run
-kairo setup
-kairo setup --dry-run
-kairo setup --agents cursor,codex --components orchestrator,sdd-core --yes
-kairo install --agents cursor,codex --yes
-```
-
-### `kairo status`
-
-Control panel for the local ecosystem: detected vs managed agents, installed
-components, check counts (ok/missing/stale/warning), backups, overall status, and the
-recommended next action. Installed components expose public health
-(`healthy` / `degraded` / `drifted` / `missing`).
-
-```bash
-kairo status
-kairo status --json
-```
-
-`--json` prints a stable machine-readable envelope for CI, tooling, and debugging
-(`ok`, `overall`, `agents`, `components`, `componentHealth`, `checks`, `backups`,
-`nextAction`, `cliVersion`). Human text remains the default. Exit code is non-zero when
-`overall` is not `ok`.
-
-### `kairo sync`
-
-Primary convergence command. Detects managed state, repairs drift with the same
-safe engine as `update` (managed content only, backups before config changes,
-user content preserved), then prints a status summary.
-
-```bash
-kairo sync
-kairo sync --dry-run
-kairo sync --dry-run --json
-```
-
-- No state → recommends `kairo setup`, writes nothing.
-- Already OK → writes nothing.
-- Drift/missing/stale → repairs, then shows status.
-- `--json` uses the same stable envelope as `status`, plus sync fields
-  (`action`, `wrote`, planned/applied repairs when present).
-- `kairo update` remains as a technical alias.
-
-### `kairo history`
-
-Read-only audit log of managed operations under `~/.harness/history.jsonl`.
-Use it to investigate what Kairo Runtime applied without parsing JSONL manually.
-
-```bash
-kairo history
-kairo history --command sync
-kairo history --action repaired --limit 10
-kairo history last
-kairo history last --json
-kairo history last --command sync
-```
-
-- Filters: `--command`, `--action`, `--limit` (combine before limiting).
-- `history last` prints the most recent matching event; exit 0 when empty.
-- Queries never write to `~/.harness`.
-
-### `kairo report`
-
-Read-only local diagnostics bundle for support and debugging. Combines status,
-policy, adapters, diff/drift preview, and recent history without modifying
-`~/.harness` or agent configs.
-
-```bash
-kairo report
-kairo report --json
-kairo report --out ./diagnostics.txt
-kairo report --limit 10
-```
-
-- Default stdout is human-readable; `--json` is stable for CI.
-- `--out <file>` writes only to the path you specify (text or JSON per flags).
-- `--limit <n>` controls history events included (default 20).
-- Corrupt `history.jsonl` lines appear as warnings; valid events still display.
-- No telemetry and no full config contents — paths, states, and summaries only.
-
-### `kairo policy`
-
-Optional local operation preferences under `~/.harness/policy.json`. Use this
-when your team wants consistent apply/preflight defaults without repeating CLI
-flags on every `setup`, `sync`, or `upgrade`.
-
-```bash
-kairo policy
-kairo policy --json
-kairo policy set profile ci
-kairo policy set preflight true
-kairo policy set agents detected
-kairo policy set components orchestrator,sdd-core
-kairo policy reset
-```
-
-Profiles:
-
-| Profile | Behavior |
-|---|---|
-| `safe` | Preflight on; interactive terminal prompts before apply (default). |
-| `ci` | Preflight on; non-interactive apply allowed via policy (`applyMode: confirm`). |
-| `fast` | Same as `ci` — preflight on, confirmation via policy instead of a prompt. |
-
-Precedence: **CLI flags > policy file > internal defaults**. Without a policy
-file, behavior matches 0.18.0. `policy reset` deletes only `policy.json`; it
-does not touch `state.json`, managed adapters, or installed components.
-
-Keys: `profile`, `applyMode` (`prompt` \| `confirm`), `preflight`, `agents`
-(`detected`, `all`, or a comma-separated list), `components`.
-
-Visibility (0.20.0+): `kairo status`, `kairo explain`, and apply preflight on
-`setup`/`sync`/`upgrade` show the effective policy and consent source (`cli`,
-`policy`, `interactive`, or `none`). `status --json` includes a stable `policy`
-field.
-
-### `kairo install` (agent-global)
-
-Non-interactive configure. Same engine as `setup`.
-
-```bash
-kairo install --dry-run   # preview the plan, writes nothing
-kairo install             # apply
-kairo install --agents cursor,claude
-```
-
-What it does:
-
-- Detects local agents: `cursor`, `codex`, `opencode`, `claude`. If none are
-  detected, it targets all supported agents.
-- Installs the orchestrator/conductor contract to `~/.harness/core/`.
-- Adds a managed marker section to each agent config
-  (for example `~/.cursor/AGENTS.md`):
-
-```md
-<!-- harness:managed:start -->
-...managed content, refreshed by kairo sync...
-<!-- harness:managed:end -->
-```
-
-- Everything outside the markers is user-owned and always preserved.
-- Before modifying any existing config it snapshots the file to
-  `~/.harness/backups/<timestamp>/`.
-- Records everything in `~/.harness/state.json`.
-- Set `HARNESS_HOME=/some/dir` to redirect the whole managed root (useful for
-  testing and sandboxed environments).
-
-### `kairo update` (agent-global)
-
-Technical/compatibility alias for the repair engine used by `sync`. Prefer
-`kairo sync` for day-to-day use. Requires an existing `~/.harness/state.json`.
-
-### `kairo doctor` (agent-global)
-
-Reports installed agents, managed state, backups, and missing configs.
-Exits non-zero when managed state or a tracked config is missing.
-
-```bash
-kairo doctor
-kairo doctor --json
-```
-
-`--json` uses the same stable control-plane envelope as `status`, including the
-detailed `checks` array.
-
-### `kairo uninstall` (agent-global)
-
-Removes managed sections from agent configs (with a fresh backup first),
-deletes `~/.harness/state.json` and `~/.harness/core/`. Backups are preserved.
-
-### Workspace components
-
-Opt-in custom components live in the current repo under `.harness/components/`.
-They never override bundled IDs (`orchestrator`, `sdd-core`, `engram-memory`,
-`graphify-context`) and install copies assets into `~/.harness/components/<id>/`
-only when you pass `--components`.
-
-#### Component Manifest v2
-
-Catalogs are a validated contract. Bundled `catalog.json` uses `schemaVersion: 2`
-with `kind`, `capabilities`, `dependencies`, and `healthChecks`. Workspace v1
-catalogs (no `schemaVersion`) still load — fields normalize in memory; persisted
-`~/.harness/state.json` stays compatible and derives new metadata from the catalog.
-
-- Dependencies resolve topologically (deps first, no duplicates).
-- Public component health: `healthy` | `degraded` | `drifted` | `missing`.
-- Engram/Graphify integration warnings degrade that component; they do not fail
-  global `doctor` by themselves.
-- Workspace entries stay declarative JSON (no arbitrary code execution).
-- `engram-memory` may declare `integration.provider: "engram"`. Kairo detects the
-  Engram binary, plans official `engram setup <agent>`, and never installs Engram
-  silently or runs `engram doctor` (SQLite side effects).
-
-Configure Engram (requires `engram-memory` installed and Engram `>=1.19.0 <2.0.0`):
-
-```bash
-kairo components configure engram-memory --agents codex,opencode --dry-run
-kairo components configure engram-memory --agents codex,opencode --yes
-kairo components rollback engram-memory --receipt <id> --dry-run
-```
-
-Without `--agents`, Kairo uses the intersection of detected agents and
-Kairo-managed Engram agents (`cursor`, `codex`, `opencode`, `claude` → setup slug
-`claude-code`, `pi` → `pi`). After setup, status is `restart_required` — restart the agent to
-load MCP; configuration evidence is not runtime-active. Receipts live under
-`~/.harness/integrations/engram/`. For Pi, positive evidence requires
-`~/.pi/agent/settings.json` packages (`npm:gentle-engram`, `npm:pi-mcp-adapter`) and
-`~/.pi/agent/mcp.json` with `mcpServers.engram`.
-
-### SDD Core skills
-
-`sdd-core` (default with setup/install) materializes nine phase skills:
-
-`sdd-init`, `sdd-explore`, `sdd-propose`, `sdd-spec`, `sdd-design`,
-`sdd-tasks`, `sdd-apply`, `sdd-verify`, `sdd-archive`.
+| `kairo` | Open the cockpit |
+| `kairo status` | See how your setup is doing |
+| `kairo sync` | Repair what drifted |
+| `kairo update` | Update Kairo itself from npm |
+| `kairo doctor` | Deeper health checks |
 
-Each skill ships as a directory (`SKILL.md` + `references/contract.md`).
+Run `kairo help --all` for everything else, or read the
+[CLI reference](https://github.com/Kal-elSam/harness/blob/main/docs/cli-reference.md).
 
-**Auto-materialization.** When `sdd-core` is selected/installed,
-`install` / `setup` / `sync` / `upgrade` materialize (or repair) skills via the
-same `sdd-core` apply path. Lifecycle keeps persona frozen (`preservePersona`):
-it never auto-activates teaching. Explicit persona changes stay on
-`kairo components configure sdd-core`.
+## What it guarantees
 
-**Destinations.** Cursor, Codex, OpenCode, and Pi share `~/.agents/skills/<id>/`.
-Claude uses `~/.claude/skills/<id>/`. One physical tree per root; consumers are
-recorded per destination.
+- **Your files stay yours.** Kairo writes only between
+  `<!-- harness:managed:start -->` / `<!-- harness:managed:end -->` markers.
+  Everything outside them is preserved untouched.
+- **Every write is reversible.** Configs are snapshotted first; `kairo rollback`
+  restores a prior snapshot.
+- **Nothing happens without consent.** Previews are the default; applying requires
+  an explicit `--yes` or a confirmation in the UI.
+- **No permanent daemons.** Background monitoring is opt-in via `kairo monitor enable`.
 
-**Persona.** Defaults to `off`. `--persona teaching` activates per managed
-agent via `state.sdd.personaAgentIds` (managed-section gate only — explanations,
-never code/docs/commits/PRs). `--persona off` removes teaching only for the
-targeted agents.
+## Install
 
-**Consent and conflicts.** Dry-run writes nothing. Non-interactive mutating
-configure/rollback without `--json` requires `--yes`, `--confirm`, or
-`--no-preflight`. `--json` selects machine-readable output and skips the
-prompt/consent gate (same apply-confirmation policy as setup/sync/upgrade).
-Conflicts and user-owned files are never overwritten, even with `--yes`.
-Receipts live under `~/.harness/integrations/sdd-core/` and may be `partial`
-when some actions succeed and others fail.
-
-**Session refresh.** After skill or managed-section changes, results report
-`session_refresh_required` — restart agents to load skills; Kairo does not claim
-existing sessions already loaded them. Verify health is
-`configured` | `missing` | `drifted` | `conflict`.
-
-```bash
-kairo components configure sdd-core --agents codex,opencode,cursor,claude --persona off --dry-run
-kairo components configure sdd-core --agents codex,opencode --persona teaching --yes
-kairo components verify sdd-core --json
-kairo components rollback sdd-core --receipt <id> --dry-run
-```
-
-Create, validate, and install:
-
-```bash
-kairo components init team-rules --label "Team Rules"
-# edit .harness/components/team-rules/README.md
-kairo components validate
-kairo install --components team-rules
-```
-
-Advanced: share a workspace component between repos (no remote registry):
-
-```bash
-kairo components pack team-rules --out team-rules.tgz
-# copy team-rules.tgz into another repo
-kairo components import team-rules.tgz
-kairo components validate
-kairo install --components team-rules
-```
-
-- `kairo components` lists bundled and workspace catalogs.
-- `kairo components validate [--cwd <path>]` runs the same loader used by install/doctor.
-- `kairo components init <id> --label "<label>"` scaffolds `catalog.json`,
-  `.harness/components/<id>/README.md`, and a catalog entry (`version: "0.1.0"`).
-  It refuses existing IDs and bundled IDs, and does not write to `~/.harness`.
-- `kairo components pack <id> --out <file>` builds a portable `.tgz` (partial catalog + assets).
-- `kairo components import <file>` installs declared assets only; no overwrite by default,
-  no `~/.harness` writes, no package scripts.
-
-## Workspace lifecycle: init, update, doctor
-
-The workspace harness is not a one-shot copy. Every `init` writes a manifest
-that later `update` and `doctor` runs rely on. All workspace commands accept
-`--scope=workspace`; `init` implies it.
-
-### `kairo init` / `kairo install --scope=workspace`
-
-Installs `repo-template/` into the target project and writes
-`.harness/manifest.json` with the installed mode, CLI version, and a content
-hash for every file the harness created.
-
-```bash
-kairo init --mode enterprise --all-adapters
-kairo install --scope=workspace --mode standard --adapters codex,cursor
-```
-
-By default it never overwrites a file that already exists. Pass `--force` to
-overwrite, or `--dry-run` to preview without writing anything.
-
-Important behavior:
-
-- Running just `kairo` (or `npx/pnpm dlx @kal-elsam/kairo-runtime`) now runs the
-  **agent-global** install, not the workspace scaffold.
-- Within workspace scope, `mode=standard` remains the default.
-- `--adapters` installs only the requested adapters.
-- `--all-adapters` keeps the previous “install everything” behavior.
-
-Supported adapters:
-
-```txt
-codex, cursor, claude, gemini, copilot, opencode, pi
-```
-
-### `kairo detect`
-
-Read-only inspection command. It reports the global agents detected on this
-machine, then the current project stack and adapter markers, and prints the
-recommended install command.
-
-```bash
-kairo detect
-```
-
-### `kairo update --scope=workspace`
-
-Reapplies the current harness templates to an already-installed project.
-
-```bash
-kairo update --scope=workspace --dry-run   # preview: created / updated / unchanged / skipped
-kairo update --scope=workspace             # apply
-kairo update --scope=workspace --force     # also overwrite files you modified locally
-```
-
-`update` is conservative by design:
-
-- Files unchanged since install are safely refreshed to the latest template.
-- Files you edited locally are **skipped** unless `--force` is passed.
-- Files that exist but were never tracked by the harness are left alone.
-- New files added in newer harness releases are created.
-- `.harness/manifest.json` is rewritten with the new hashes, CLI version, and adapter selection.
-
-### `kairo doctor --scope=workspace`
-
-Read-only health check. Never modifies files.
-
-```bash
-kairo doctor --scope=workspace
-```
-
-Reports each check as `OK`, `WARNING`, or `MISSING`:
-
-- **Required** files missing (`AGENTS.md`, `docs/ai/harness.md`,
-  `docs/ai/memory.md`) fail the check (non-zero exit code).
-- **Recommended** files missing are reported as warnings.
-- If `.harness/manifest.json` is missing, doctor warns and suggests
-  `kairo init`.
-- If a file tracked in the manifest was deleted after install, doctor
-  reports manifest drift.
-
-### `.harness/manifest.json`
-
-```json
-{
-  "packageName": "@kal-elsam/kairo-runtime",
-  "cliVersion": "0.2.0",
-  "mode": "enterprise",
-  "adapters": ["codex", "cursor"],
-  "installedAt": "2026-07-02T18:00:00.000Z",
-  "updatedAt": "2026-07-02T18:00:00.000Z",
-  "files": {
-    "AGENTS.md": "3f9a...",
-    "docs/ai/harness.md": "8b21..."
-  }
-}
-```
-
-This file is the source of truth for what the harness owns in a project.
-Commit it to version control.
-
-## What it installs
-
-The CLI copies and personalizes `repo-template/` into the target project.
-
-Always-installed core depends on the selected mode, and adapter folders are now
-filtered separately.
-
-Core examples:
-
-```txt
-AGENTS.md
-docs/ai/
-docs/skills/
-docs/specs/
-.gentle-ai/
-.harness/
-setup-agent-links.sh
-```
-
-Adapter-specific examples:
-
-```txt
-.codex/
-.cursor/
-.claude/
-.pi/
-.opencode/
-.github/copilot-instructions.md
-CLAUDE.md
-GEMINI.md
-```
-
-Feature/extended examples (mostly `standard`/`enterprise` depending on mode):
-
-```txt
-.github/
-evals/
-scripts/harness/
-```
-
-Core rule:
-
-```txt
-AGENTS.md governs.
-Adapters translate.
-MCPs observe and preserve context.
-Human approves impact.
-```
-
-Engram and Graphify are documented as external integrations: they help with memory and context graphs, but they do not replace the repo as the source of truth.
-
-Built for:
-
-- Cursor-first, but not Cursor-only.
-- Gentle AI as the operational reference for SDD/TDD.
-- AGENTS.md as the universal source.
-- SDD, TDD, evals, checkpoints, review, and human approval.
-- Engram/Graphify as external memory, analysis, or context-graph systems without locking the repo to a single tool.
-
-## Key files
-
-```txt
-prompts/HARNESS_INSTALLER_MASTER.md
-prompts/HARNESS_MINIMAL.md
-prompts/HARNESS_STANDARD.md
-prompts/HARNESS_ENTERPRISE.md
-repo-template/
-```
-
-## Recommended usage
-
-Install from the package:
+Requires Node.js 20.12 or newer.
 
 ```bash
-pnpm dlx @kal-elsam/kairo-runtime install
-pnpm dlx @kal-elsam/kairo-runtime detect
-pnpm dlx @kal-elsam/kairo-runtime install --scope=workspace --mode standard --adapters codex,cursor
-pnpm dlx @kal-elsam/kairo-runtime init --mode enterprise --all-adapters
-pnpm dlx @kal-elsam/kairo-runtime doctor
-```
+# Run without installing
+npx @kal-elsam/kairo-runtime
 
-Manual fallback for a new Cursor project (without the npm package):
+# Install globally
+npm i -g @kal-elsam/kairo-runtime && kairo
 
-1. Open the project.
-2. Copy the contents of `prompts/HARNESS_INSTALLER_MASTER.md`.
-3. Paste it into Cursor.
-4. Specify the mode:
+# Later: update the CLI itself
+kairo update
+kairo update --yes
 
-```txt
-Install the harness in standard mode.
+# Preview the setup plan, write nothing
+npx @kal-elsam/kairo-runtime --dry-run
 ```
 
-Or:
+There is also a bootstrap script that checks Node, installs the CLI, and previews the
+plan without writing anything — see
+[installation options](https://github.com/Kal-elSam/harness/blob/main/docs/install.md).
 
-```txt
-Install the harness in enterprise mode because this project will have AI, API, DB, and external integrations.
-```
-
-## Modes
+## Docs
 
-| Mode | Use case |
+| Guide | Contents |
 |---|---|
-| minimal | scripts, technical spikes, landing pages, small prototypes |
-| standard | real frontend/backend apps, simple SaaS, medium products |
-| enterprise | AI agents, critical workflows, API/DB/auth/evals, multi-agent |
-
-## Publishing
-
-Published on npm as `@kal-elsam/kairo-runtime`. Releases use **npm Trusted Publishing/OIDC**
-from GitHub Actions — no `NPM_TOKEN`.
-
-`@kal-elsam/harness` is published separately as a compatibility bridge from
-`packages/harness-bridge/` (see bridge README).
-
-### Git tags (package-aware)
-
-| Tag pattern | Package | Publish root |
-|---|---|---|
-| `kairo-runtime-v*` | `@kal-elsam/kairo-runtime` | repo root |
-| `harness-bridge-v*` | `@kal-elsam/harness` | `packages/harness-bridge/` |
-| `v*` | legacy / historical root releases | repo root |
-
-Kairo Runtime releases should use `kairo-runtime-vX.Y.Z` going forward. The first
-bootstrap used `v0.1.0`; later releases use package-aware tags such as
-`kairo-runtime-v0.1.1`.
-
-Before tagging a new version:
-
-```bash
-npm test
-npm run smoke
-npm pack --dry-run
-```
-
-After the release commit, verify attribution was not added to the message:
-
-```bash
-npm run release:check
-git log -1 --format=%B
-```
-
-CI also scans commit ranges for attribution trailers:
-
-```bash
-npm run release:check -- --range origin/main...HEAD
-```
-
-Release commits must **not** include `Co-authored-by` or other AI attribution
-trailers. Do not rewrite published tags; ship a corrective patch version instead.
-
-`npm run smoke` packs the current source into a tarball, installs it in a
-throwaway temp project with a fake `HARNESS_HOME`, and exercises both scopes end
-to end:
-
-- **agent-global:** `setup --dry-run`, `status`, `install`, `doctor`, drift
-  simulation, `sync` repair, `backups`, rollback preview (no writes),
-  rollback apply (with safety backup), `uninstall`.
-- **workspace:** `install --scope=workspace`, `doctor`, `update --dry-run`.
-
-Release flow (Kairo Runtime):
-
-```bash
-# bump version in package.json and package-lock.json
-git add .
-git commit -m "chore: release kairo-runtime 0.1.1"
-npm run release:check
-git tag kairo-runtime-v0.1.1
-git push origin main
-git push origin kairo-runtime-v0.1.1
-```
-
-Bridge release flow:
-
-```bash
-# bump packages/harness-bridge/package.json (+ lockfile)
-git add .
-git commit -m "chore: release harness bridge 0.30.0"
-npm run release:check
-git tag harness-bridge-v0.30.0
-git push origin main
-git push origin harness-bridge-v0.30.0
-```
-
-Legacy `v*` tags still publish from the repo root for historical continuity.
-
-After npm publishes the tag, verify published provenance against git and the registry:
-
-```bash
-git fetch --tags origin
-git fetch origin main
-npm run release:published -- --version 0.1.1 --tag kairo-runtime-v0.1.1
-npm run smoke:registry -- --version 0.1.1
-npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
-npm run smoke:bridge
-```
-
-`release:published` checks npm `version`, npm `gitHead`, the release git tag on
-`origin`, and `origin/main`. Override the package and tag when needed:
-
-```bash
-npm run release:published -- \
-  --package @kal-elsam/kairo-runtime \
-  --tag kairo-runtime-v0.1.1 \
-  --version 0.1.1
-
-npm run release:published -- \
-  --package @kal-elsam/harness \
-  --tag harness-bridge-v0.30.0 \
-  --version 0.30.0
-```
-
-Without `--tag`, provenance checks fall back to `v${version}` (legacy tags).
-
-`smoke:registry` installs `@kal-elsam/kairo-runtime` from the npm registry (not the local tarball) into a throwaway workspace with a fake `HARNESS_HOME` and npm cache, then runs the recommended flow via `kairo`: `setup --dry-run`, `setup --yes`, `status`, drift simulation, `sync`, `status --json` (expects `overall=ok`), and `uninstall`. Use `latest` by default, pin with `--version x.y.z`, or override with `--package`.
-
-`smoke:installer` validates the public one-liner path: `curl .../install.sh | sh` against GitHub `raw` and the npm registry with isolated `HARNESS_HOME`. Preview must not write `~/.harness`; `--yes --agents all` must reach `kairo status --json` with `overall=ok`, then `kairo uninstall` must remove managed sections. Pin with `--version x.y.z` after publish. For package-aware Kairo Runtime tags, pass the git tag explicitly:
-
-```bash
-npm run smoke:installer -- --version 0.1.1 --tag kairo-runtime-v0.1.1
-```
-
-Without `--tag`, the install script resolves from legacy `v${version}` tags.
-
-Suggested first Kairo Runtime tag after bootstrap: `kairo-runtime-v0.1.1`.
-
-The `publish.yml` workflow runs on `v*`, `kairo-runtime-v*`, and `harness-bridge-v*`
-tags and publishes to npm using the `npm-publish` environment.
-It runs `npm run release:check` on `HEAD` immediately before `npm publish`.
-
-See the full policy in `SECURITY.md`.
-
-## Base rule
-
-The agent must not operate as a free-form programmer.
-
-```txt
-Requirement
-→ Spec
-→ Plan
-→ Tests failing first
-→ Implementation
-→ Validation
-→ Review
-→ Human approval
-```
-
-## Gentle AI integration
-
-After installing the harness in a repo, run:
-
-```bash
-/sdd-init
-gentle-ai skill-registry refresh
-gentle-ai doctor
-```
-
-`/sdd-init` detects stack and testing.  
-`skill-registry refresh` updates the skill registry.  
-`doctor` checks ecosystem health.
-
-## Engram/Graphify integration
-
-Engram and Graphify are **external** integrations. Kairo verifies configuration,
-version, and freshness evidence when present; it does not install them, read the
-Engram database, or traverse the Graphify graph at runtime, and never claims they
-are actively running.
-
-Integration points (repo docs / optional components):
-
-```txt
-docs/ai/context-graph.md
-docs/ai/memory.md
-docs/skills/context-graph.md
-global-template/components/engram-memory/
-global-template/components/graphify-context/
-```
-
-The rule:
-
-- The repo keeps the source of truth in Markdown (`AGENTS.md`, `docs/ai/`, code).
-- Engram may index decisions, specs, memory, and conventions when configured separately.
-- Graphify may build an architecture graph when you run `graphify` yourself.
-- Control-plane proposals for Engram/Graphify appear only with verifiable
-  config/version/freshness checks — never from optional intelligence absence alone.
-- No external memory replaces `AGENTS.md`, `docs/ai/`, or the code.
-
-## v2 — Universal-first, adapter-based
-
-This version adds:
-
-- `docs/ai/model-policy.md`
-- `docs/ai/provider-routing.md`
-- `docs/ai/tool-adapters.md`
-- `docs/ai/context-budget.md`
-- `docs/skills/model-selection.md`
-- `docs/skills/tool-adapter-sync.md`
-- Adapters for Codex, Claude, Gemini, GitHub Copilot, Cursor, and Gentle AI
-- Codex skills: SDD, TDD, evals, checkpoint
-- Claude agents/skills pointers
-- Gemini pointer
-- SDD subagents per phase
-- Explicit policy for cost-efficient models such as DeepSeek
-
-v2 principle:
-
-```txt
-Universal core first.
-Tool adapters second.
-Model providers third.
-```
-
-Cursor remains the primary editor, but not the source of truth.
-
-## v3 — Loop Engineering + OpenCode-first execution adapter
-
-This version adds Loop Engineering as a formal harness layer and positions OpenCode + Gentle AI + DeepSeek as the primary execution adapter for this flow.
-
-```txt
-OpenCode executes.
-Gentle AI structures SDD/TDD.
-DeepSeek iterates cheaply.
-Harness governs.
-Loops repair with boundaries.
-Evals validate.
-Graphify observes dependencies.
-Engram preserves learning.
-Human approves impact.
-```
-
-New modules:
-
-```txt
-docs/ai/loops.md
-docs/ai/loop-policy.md
-docs/ai/loop-observability.md
-docs/ai/loop-log.md
-docs/skills/loop-design.md
-docs/skills/loop-debugging.md
-docs/skills/loop-review.md
-docs/skills/loop-retrospective.md
-.opencode/
-.gentle-ai/loops/
-evals/loop-regression/
-```
-
-## v4 — Universal Adapter Parity
-
-This version corrects the interpretation that the harness is OpenCode-based.
-
-v4 rule:
-
-```txt
-AGENTS.md governs.
-docs/ai defines.
-docs/skills operationalize.
-docs/specs specify.
-evals validate.
-Adapters translate.
-Models execute.
-Humans approve impact.
-```
-
-OpenCode may be the user's preferred runtime because Gentle AI + DeepSeek live there, but it has no higher authority than Cursor, Codex, Claude, Gemini, or Pi.
-
-Key new document:
-
-```txt
-docs/ai/adapter-parity.md
-```
-
-New rule:
-
-```txt
-No adapter is primary by authority.
-An adapter can be primary only by workflow preference.
-The core universal remains the governance layer.
-```
-
-## v5 — Enforcement-first Harness
-
-This version moves the harness closer to a real control plane — beyond methodology and documentation.
-
-```txt
-Docs guide.
-Policies constrain.
-CI gates enforce.
-Evals measure.
-Hooks block unsafe actions.
-Trust policy protects skills/tools.
-Installer manages lifecycle.
-```
-
-New modules:
-
-```txt
-docs/ai/enforcement.md
-docs/ai/quality-gates.md
-docs/ai/eval-strategy.md
-docs/ai/trust-policy.md
-docs/ai/installer-cli.md
-docs/ai/observability-runtime.md
-docs/ai/rollback-runtime.md
-docs/ai/maintainability-gates.md
-.github/workflows/harness-quality-gate.yml
-.github/workflows/harness-security-gate.yml
-.github/dependabot.yml
-scripts/harness/
-evals/golden/
-evals/tool-calls/
-evals/schema/
-evals/regression/
-```
-
-## v6 — Spec Sizing and Complexity Classification
-
-This version adds explicit feature/task spec sizing.
-
-The harness already had installation modes:
-
-```txt
-minimal
-standard
-enterprise
-```
-
-But those describe harness installation size, not the complexity of a feature spec.
-
-v6 adds:
-
-```txt
-basic spec
-standard spec
-complex spec
-```
-
-Rule:
-
-```txt
-Do not force complex SDD on simple tasks.
-Do not allow basic specs for high-impact work.
-Spec complexity must match risk, ambiguity, architecture impact, testability and blast radius.
-```
-
-New core files:
-
-```txt
-docs/ai/spec-sizing.md
-docs/ai/spec-intake.md
-docs/ai/spec-escalation.md
-docs/specs/templates/basic-spec.md
-docs/specs/templates/standard-spec.md
-docs/specs/templates/complex-spec.md
-docs/skills/spec-complexity-classifier.md
-docs/skills/spec-intake.md
-docs/skills/spec-escalation-review.md
-```
+| [CLI reference](https://github.com/Kal-elSam/harness/blob/main/docs/cli-reference.md) | Every command, flag, and `--json` output |
+| [Agents & adapters](https://github.com/Kal-elSam/harness/blob/main/docs/adapters.md) | Supported agents, config roots, Pi runtime, reviews |
+| [Components](https://github.com/Kal-elSam/harness/blob/main/docs/components.md) | Orchestrator, Engram memory, SDD Core skills |
+| [Intelligence](https://github.com/Kal-elSam/harness/blob/main/docs/intelligence.md) | Local-first routing, budgets, cloud consent |
+| [Integrations](https://github.com/Kal-elSam/harness/blob/main/docs/integrations.md) | Gentle AI, Engram, Graphify, Obsidian |
+| [Workspace scope](https://github.com/Kal-elSam/harness/blob/main/docs/workspace.md) | Opt-in per-repo scaffolding and manifests |
+| [Contributing](https://github.com/Kal-elSam/harness/blob/main/docs/contributing.md) | Release process, tags, branch chains |
+
+## Links
+
+- npm: https://www.npmjs.com/package/@kal-elsam/kairo-runtime
+- Repo: https://github.com/Kal-elSam/harness
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- License: [MIT](LICENSE)