open-multi-agent-kit 0.79.1 → 0.79.3

package/docs/native-root-runtime-hardening.md

@@ -0,0 +1,131 @@
+# Native Root Runtime Hardening
+
+Last updated: 2026-05-24
+Current `new-origin/main`: `6305e2b62185c11549f59e2340936769a3027cdd`
+
+## Current State
+
+OMK is now on the right architectural path: OMK is the root orchestrator and Kimi is one provider adapter, with Codex, DeepSeek, OpenCode, CommandCode, and future adapters routed through OMK-owned runtime contracts.
+
+This is still a hardening milestone, not a stable provider-neutral release claim. The current release stop condition is:
+
+- Local `npm run release:check` must pass on the exact release diff.
+- GitHub Actions Smoke Test must pass on the exact commit.
+- GitHub Actions CI must pass on the exact commit.
+- Release evidence must be kept under `.omk/release-evidence/<short-sha>/` or an equivalent run artifact path.
+
+Fresh verification at the time of this update:
+
+- `new-origin/main` points at `6305e2b62185c11549f59e2340936769a3027cdd`.
+- GitHub Actions Smoke Test for that commit completed successfully.
+- GitHub Actions CI for that commit failed on Windows test jobs, so v1.1.18 publish/tag remains blocked.
+
+For the LaTeX/paper-ready algorithm appendix and acceptance criteria, see
+[Native Root Runtime Algorithms](./native-root-runtime-algorithms.md). Treat
+that appendix as hardening criteria, not a stable-release proof, until the
+exact release diff passes CI, smoke, and local release gates.
+
+## Runtime Safety Contract
+
+Related algorithm appendix:
+[Native Root Runtime Algorithms](./native-root-runtime-algorithms.md)
+documents the current acceptance criteria for turn construction, capsule
+conversion, runtime fallback, Kimi prompt transport, and scoped worker
+environment construction.
+
+### Turn risk and capability routing
+
+Related: Algorithm 2.
+
+Native chat turns must be default-safe. A turn should request only the minimum capability needed:
+
+| Turn risk | Typical intent | Capabilities |
+|-----------|----------------|--------------|
+| `read` | explain, review, summarize, inspect docs | `read` only |
+| `write` | edit, fix, implement, refactor | `read`, `write`, `patch` |
+| `shell` | run tests, build, execute commands | `read`, `write`, `shell` with approval policy |
+| `merge` | publish, release, push, merge, destructive changes | authority provider plus release/security gates |
+
+DeepSeek remains an advisory/read/review lane unless an explicit future contract grants safe write/shell execution. Write/shell tasks should route to Kimi, Codex, or a configured authority provider with the matching approval and sandbox policy.
+
+### Approval and sandbox propagation
+
+Related: Algorithm 2, Algorithm 4, and Algorithm 7.
+
+`--execution ask|auto|never` must flow from chat command parsing into `AgentTask.safety`, runtime routing, and the final adapter invocation.
+
+| OMK execution | Runtime expectation |
+|---------------|---------------------|
+| `ask` | request approval before write/shell side effects; Codex should not use `never` |
+| `auto` | allow only low-risk automatic actions; elevate risky shell/write operations |
+| `never` | explicit high-trust/yolo mode only |
+| read-only turn | use read-only sandbox where adapter supports it |
+
+### Authority provider resolution
+
+Related: Algorithm 5.
+
+`authority`, `primary`, and `omk` are policies, not executable providers. They must resolve to a concrete provider before bootstrap or routing:
+
+1. `OMK_AUTHORITY_PROVIDER`, if set and healthy.
+2. Kimi, when installed/authenticated and compatible with task risk.
+3. A configured fallback provider that satisfies the task capability contract.
+
+Unknown or unresolved authority must fail with remediation instead of silently degrading to advisory-only mode.
+
+### Provider health probes
+
+Related: Algorithm 5. Current routing uses available registry, capability, and
+evidence metadata; uniform auth/model/quota health remains part of this
+hardening backlog.
+
+Provider bootstrap must distinguish:
+
+- `runtimeOk`: binary/API client available.
+- `authOk`: authenticated enough to make a real call.
+- `modelOk`: selected/default model is supported.
+- `quotaOk`: quota/rate-limit known good, known bad, or unknown.
+
+Binary existence alone is not enough. CLI adapters should probe version and auth/session status where possible; API adapters should validate key presence and perform a cheap health/model check when safe.
+
+### Tool-plane diagnostics
+
+Related: Algorithm 4 and Algorithm 7.
+
+MCP, skills, and hooks must not disappear silently. Runtime manifests should include diagnostics for parse/read failures, unknown names, and scope drops. If a task requires runtime MCP, invalid MCP config is a hard failure.
+
+## P0 Backlog
+
+1. Infer native turn risk before building the DAG node; do not default every turn to write/shell.
+2. Keep explicit DeepSeek routes read-only/advisory or block write/shell with a clear fallback message.
+3. Propagate approval policy and sandbox mode into runtime adapters, especially Codex CLI.
+4. Resolve `authority` to a concrete provider during runtime bootstrap.
+5. Replace binary-only provider auth checks with structured provider health probes.
+6. Keep release evidence current; do not tag/publish while CI is red.
+
+## P1 Backlog
+
+1. Make `/model` either a real live state update or clearly restart-only.
+2. Use the provider registry as the source of truth for DeepSeek default models.
+3. Remove `cmd` as a CommandCode fallback binary.
+4. Emit tool-plane diagnostics for MCP config parse/read failures.
+5. Gate Kimi failure stderr previews behind `OMK_DEBUG=1` and redaction.
+6. Preserve routing metadata in external CLI adapter `execute(task)` paths.
+
+## P2 Backlog
+
+1. Add configurable non-zero exit behavior for native root-loop turn failures.
+2. Move prompt envelopes out of `DagNode.name` into structured payload fields.
+3. Validate capability names before prompt/runtime injection.
+4. Persist per-turn route artifacts under `.omk/runs/<run-id>/turns/<turn-id>.json`.
+5. Link provider routes and evidence gates into graph memory for replay/audit.
+
+## Spec-Kit Acceptance Gates
+
+Any spec-kit plan for native root runtime work should include:
+
+- Safety fields: `risk`, `approvalPolicy`, and `sandbox`.
+- Authority fields: requested provider policy and resolved concrete provider.
+- Capability fields: MCP, skills, hooks, write, patch, shell, and review.
+- Diagnostics: provider health, tool-plane parse failures, capability mismatches, and fallback reasons.
+- Evidence: exact commands, local/remote run URLs where available, pass/fail state, and release stop/go decision.

package/docs/neo4j-memory.md

@@ -0,0 +1,5 @@
+# Graph memory and Kuzu
+
+OMK uses project-local ontology graph memory by default and supports the embedded Kuzu backend for Cypher-style graph queries. See [`docs/local-graph-memory.md`](./local-graph-memory.md) for the current memory policy, mind-map ontology, and MCP query examples.
+
+Neo4j support has been removed from the runtime path; stale `[neo4j]` config blocks are ignored and should be deleted from local config files.

package/docs/openai-platform-image-keys.md

@@ -0,0 +1,23 @@
+# OpenAI Platform keys for image generation
+
+OMK separates Codex login from OpenAI API access.
+
+- **Codex/ChatGPT OAuth**: proves the Codex CLI login state only.
+- **OpenAI Platform project API key**: required for `omk image generate` and `omk image edit`, including `gpt-image-2`.
+
+Safe local flow:
+
+1. Complete OpenAI Platform OAuth in a trusted setup surface.
+2. Create an encrypted project API key for the target Platform project.
+3. Decrypt the key locally only when needed.
+4. Run one image command with an ephemeral runtime environment variable.
+5. Unset the env var and remove any decrypted temp key.
+
+Example with a placeholder value:
+
+```bash
+OPENAI_API_KEY=<platform-project-key> omk image generate "ping-pong test" --model gpt-image-2
+unset OPENAI_API_KEY
+```
+
+OMK reads the key only from the runtime environment and does not store it in project files, MCP config, image metadata, or run evidence. Use `--api-key-env <name>` if your local encrypted-key helper injects a different one-shot env var.

package/docs/phase1-final-report.md

@@ -0,0 +1,154 @@
+# Final Report: Phase 1 Integration
+
+**Run ID:** .omk/runs/latest
+**Date:** 2025-05-01
+**Scope:** v0.2 -> v0.3 engine + platform foundation
+**Status:** Complete — all gates passed
+
+---
+
+## Executive Summary
+
+Successfully implemented and merged Phase 1 features (engine + platform layers) using isolated worktree workers with non-overlapping file ownership. All critical review findings were fixed pre-merge. Type check, build, CLI load, doctor, and HUD regression gates all pass with zero errors.
+
+---
+
+## Worker Architecture
+
+| Phase | Worker | Role | Worktree | Branch |
+|-------|--------|------|----------|--------|
+| 0 | Contract | Define cross-worker APIs | .omk/worktrees/contract | work/contract |
+| 1 | B | Engine Layer | .omk/worktrees/engine | work/engine |
+| 1 | C | Platform Layer | .omk/worktrees/platform | work/platform |
+| 2 | A | Commands Layer (pending) | .omk/worktrees/commands | work/commands |
+| 2 | D | Content Layer (pending) | .omk/worktrees/content | work/content |
+| 3 | Integration | Merge + QA | .omk/worktrees/integration | work/integration |
+
+---
+
+## What Was Delivered
+
+### Contracts (Phase 0)
+
+| File | Exports |
+|------|---------|
+| src/contracts/orchestration.ts | DagExecutor, TaskRunner, RunState, RunResult, RunOptions |
+| src/contracts/safety.ts | PolicyEngine, ApprovalDecision, ApprovalContext |
+| src/contracts/hud.ts | HudRenderer, MetricSnapshot, LogHandler |
+
+### Engine Layer (Worker B)
+
+| File | Purpose |
+|------|---------|
+| src/orchestration/executor.ts | Parallel DAG execution up to N workers; state persistence; onStateChange handlers |
+| src/orchestration/scheduler.ts | Runnable node queue; retry logic; completion/failure detection |
+| src/orchestration/state-persister.ts | RunState persistence with path traversal protection |
+| src/safety/guard-hooks.ts | preShellGuard — blocks destructive commands; protectSecrets — blocks sensitive files/patterns |
+| src/kimi/wire-client.ts | createKimiTaskRunner — wire-client-based TaskRunner adapter |
+| src/safety/approval-policy.ts | createPolicyEngine — async PolicyEngine implementation |
+
+### Platform Layer (Worker C)
+
+| File | Purpose |
+|------|---------|
+| src/util/worktree.ts | createWorktree, removeWorktree, listWorktrees |
+| src/util/run-dir.ts | getRunDir, ensureRunDir, writeRunState, readRunState |
+| src/util/kimi-runner.ts | createKimiTaskRunner — runShell-based TaskRunner adapter |
+| src/util/shell.ts | runShellStreaming — line-by-line stdout/stderr callbacks |
+| src/util/git.ts | removeWorktree |
+| src/util/fs.ts | getRunPath |
+| src/memory/memory-store.ts | readRunMemory, writeRunMemory |
+| src/mcp/omk-project-server.ts | omk_list_worktrees, omk_run_quality_gate MCP tools |
+
+---
+
+## Review Findings & Resolutions
+
+### Critical (All Fixed Pre-Merge)
+
+| # | Finding | Worker | File | Fix |
+|---|---------|--------|------|-----|
+| 1 | Unhandled rejection -> permanent deadlock | B | executor.ts | Added catch/finally around runNode promises |
+| 2 | workers: 0 -> indefinite deadlock | B | executor.ts | Validate workers >= 1 at execute() entry |
+| 3 | Generic regex blocks SHA-256, UUIDs, base64 | B | guard-hooks.ts | Removed overly broad generic pattern |
+| 4 | detectPm() always returns npm | C | omk-project-server.ts | Fixed falsy empty-string check |
+| 5 | Path traversal via unsanitized runId | C | memory-store.ts | Reject runId containing .. or absolute paths |
+| 6 | Path traversal via runId/nodeId | C | worktree.ts | Reject IDs containing .. or absolute paths |
+
+---
+
+## Merge Conflicts
+
+| File | Conflict Type | Resolution |
+|------|--------------|------------|
+| WORKER_MANIFEST.md | Both workers added own manifest | Replaced with unified integration manifest |
+| src/util/kimi-runner.ts | Main had runKimiInteractive; Platform added createKimiTaskRunner | Combined both functions in one file |
+
+No other conflicts. Clean ort-strategy merge.
+
+---
+
+## Regression Gates
+
+| Gate | Result | Details |
+|------|--------|---------|
+| npm run check | Pass | tsc --noEmit — 0 errors |
+| npm run build | Pass | All .ts -> .js + .d.ts + .map |
+| node dist/cli.js --help | Pass | All 11 commands render |
+| Dist artifacts | Pass | New modules present in dist/ |
+| node dist/cli.js doctor | Pass | 19/20 checks OK, 1 pre-existing warning |
+| node dist/cli.js hud | Pass | All panels render correctly |
+
+---
+
+## Git History
+
+```
+302f67d merge: integrate work/engine + work/platform into main
+27a6e5b Merge branch work/engine
+533e95d chore: checkpoint pre-merge WIP
+84f4b41 feat(engine): Phase 1 executor, scheduler, state-persister, guard-hooks
+4badf27 feat(platform): Phase 1 worktree, run-dir, streaming shell, MCP tools
+a77ee11 feat(contracts): Phase 0 cross-worker contracts
+```
+
+---
+
+## Remaining Work
+
+### Phase 2 (Ready to Dispatch)
+- Worker A (Commands): Wire run.ts -> DagExecutor, live HUD --watch, dynamic team.ts windows, merge queue
+- Worker D (Content): Update templates, docs, DESIGN.md, AGENTS.md for v0.3
+
+### Known Technical Debt
+1. Executor has no per-node timeout/AbortSignal
+2. KimiWireClient cannot restart with per-task env vars
+3. runShellStreaming uses raw chunks instead of line-buffering
+4. State persister lacks atomic writes (write-to-temp-then-rename)
+5. getProjectRoot() spawns sync shell on every call — should cache
+
+---
+
+## Risk Assessment
+
+| Category | Level | Rationale |
+|----------|-------|-----------|
+| Type safety | Low | All new code typed; tsc passes |
+| Runtime correctness | Low | Reviewer found and fixed deadlock/traversal bugs |
+| Backward compatibility | Very Low | All changes additive; existing exports untouched |
+| Security | Low | Path traversal sanitized; guards are best-effort heuristic |
+| Merge conflict (future) | Low | Clean boundaries; contract layer isolates changes |
+
+---
+
+## Files Changed Summary
+
+New files: 12
+Modified files: 9
+Deleted files: 0
+Lines added: ~830
+Lines removed: ~49
+
+---
+
+Report generated by Integration Worker. Phase 1 complete.

package/docs/provider-maturity.md

@@ -0,0 +1,44 @@
+# Provider maturity
+
+This page documents provider status for the current source tree.
+
+## Current source target
+
+- Package version: `0.79.3`
+- Runtime contract family: `v1.2`
+- Release channel: `pre-1.0`
+
+## Provider matrix
+
+This table describes built-in source defaults. `omk provider list --json` also merges user-local provider configuration, so local output may include custom providers or changed enabled/configured flags.
+
+| Provider | Default model / runtime | Routing role | Auth/config source | Current maturity |
+| --- | --- | --- | --- | --- |
+| Kimi | `kimi-k2.6` / `kimi-api` | Default coding authority and compatibility fallback | Provider/runtime config; no OMK-managed OAuth exchange | Most mature authority path. Still subject to API/key/runtime availability. |
+| MiMo | `mimo-v2.5-pro` / `mimo-api` | Runtime provider for read/review/thinking lanes; advisory after authority downgrade in API runtime | `MIMO_API_KEY` | RC path. Do not claim direct workspace-write authority from the API runtime. |
+| DeepSeek | `deepseek-v4-flash`, `deepseek-v4-pro` | Read/review/QA/research/advisory lanes; direct only for low-risk read-only routes | `DEEPSEEK_API_KEY` or user-local DeepSeek config | Mature enough for opportunistic advisory/read-only lanes; write, MCP, and merge authority stay with the authority provider. |
+| Qwen | `qwen3-max` | Advisory/read/research/review/QA routes | `DASHSCOPE_API_KEY` | Configured provider path exists; broader release-gate coverage is still pending. |
+| OpenRouter | `openrouter/auto` | Advisory/read/research/review/QA routes | `OPENROUTER_API_KEY`; provider-side BYOK/OAuth | Configured provider path exists; OMK records env-var metadata, not secret values. |
+| Codex | `codex-cli` | External CLI provider for read/plan/review/advisory and explicit policy routes | Official Codex CLI login; OMK does not read token files | Compatibility path. MCP authority is not granted to Codex CLI routes. |
+| OpenCode | `opencode-cli` | External CLI runtime for read/write/shell/patch/review when selected and available | External CLI auth/config | Compatibility path; availability depends on the local CLI. |
+| CommandCode | `commandcode-cli` | External CLI runtime for read/write/shell/patch/review when selected and available | External CLI auth/config | Compatibility path; availability depends on the local CLI. |
+| Local LLM | `qwen3-coder-30b-a3b` at `http://localhost:8080/v1` | Local OpenAI-compatible runtime | Local endpoint; optional `LOCAL_LLM_API_KEY` | Local preview path. API runtime rejects direct shell/tool-calling authority. |
+
+## Routing rules to preserve
+
+- OMK is the root orchestrator; individual providers are adapters or worker lanes.
+- Authority/write/merge routes must stay with an authority-capable provider unless a tested contract grants another provider that authority.
+- Advisory API runtimes must not be documented as direct workspace-write, shell, MCP, or merge authorities.
+- Provider setup commands store environment variable names and metadata, not raw secret values.
+- Optional provider lanes may skip or fall back depending on route criticality and failure type.
+
+## Verification commands
+
+```bash
+npm run build:clean
+node dist/cli.js provider list --json
+node dist/cli.js provider doctor kimi --json --soft
+node --test test/provider-routing.test.mjs test/runtime-router.test.mjs test/provider-tool-contracts.test.mjs
+```
+
+Run these before claiming provider-maturity changes are release-ready.

package/docs/runtime-architecture.md

@@ -0,0 +1,89 @@
+# OMK Runtime Architecture
+
+## Overview
+
+OMK CLI V2 implements a runtime pipeline that separates control-plane (OMK orchestration) from model-facing (provider prompt). The key principle: **"모델에게는 작은 NLP prompt만. 런타임에는 sidecar만. 사용자에게는 theme/NLG만."**
+
+## Pipeline
+
+```
+User Input / Slash Command
+  → CommandBus (src/runtime/command-bus.ts)
+  → IntentClassifier (src/runtime/debloat-nlp.ts: classifyIntent)
+  → CapabilitySelector (src/runtime/debloat-nlp.ts: selectCapabilities)
+  → RuntimeSidecar Builder (src/runtime/debloat-nlp.ts: compileBloatToNlp)
+  → NLP Prompt Compiler + Filtered MCP Config
+  → ProviderAdapter + Provider Runtime
+  → ProviderEventNormalizer (src/runtime/provider-event-normalizer.ts)
+  → OmkEventBus (src/runtime/contracts/command-envelope.ts)
+  → OutputRouter (src/runtime/output-router.ts)
+  → ThemeRenderer / NlpRenderer / JsonRenderer / NlgRenderer
+```
+
+## Core Modules
+
+| Module | File | Purpose |
+|--------|------|---------|
+| CommandBus | `src/runtime/command-bus.ts` | Routes slash commands to handlers |
+| IntentClassifier | `src/runtime/debloat-nlp.ts` | Classifies user intent (status/chat/code_edit/etc.) |
+| CapabilitySelector | `src/runtime/debloat-nlp.ts` | Selects required/optional MCP, skills |
+| RuntimeSidecar | `src/runtime/debloat-nlp.ts` | Builds sidecar metadata (provider/model/risk/sandbox) |
+| MCP Config Filter | `src/runtime/debloat-nlp.ts` | Per-turn MCP config filtering |
+| Provider Runtime Selector | `src/runtime/debloat-nlp.ts` | Selects kimi-event vs kimi-print |
+| ProviderEventNormalizer | `src/runtime/provider-event-normalizer.ts` | Converts raw provider events to OmkEvent |
+| OutputRouter | `src/runtime/output-router.ts` | Routes OmkEvent to appropriate renderer |
+| ThemeRenderer | `src/runtime/renderers.ts` | Rich terminal output with ThemePalette |
+| NlpRenderer | `src/runtime/renderers.ts` | Plain text bilingual output |
+| JsonRenderer | `src/runtime/renderers.ts` | Structured JSON output |
+| NlgRenderer | `src/runtime/nlg-renderer.ts` | Consent-aware NLG reports |
+| ReasoningTrace | `src/runtime/reasoning-trace.ts` | Evidence summaries, privacy redaction |
+| UI Components | `src/runtime/ui-components.ts` | statusCard, providerCard, errorBox, etc. |
+| SlashCommands | `src/runtime/slash-commands.ts` | /model, /status, /theme, /help handlers |
+
+## Key Types
+
+- `CommandEnvelope`: Normalized CLI input (kind, source, rawText, outputProfile)
+- `RequestIntent`: status|resume|memory_query|repo_read|code_edit|debug_error|web_research|plan|chat|unknown
+- `CapabilityPlan`: availableMcp[], requiredMcp[], optionalMcp[], disabledMcp[], selectedSkills[]
+- `RuntimeSidecar`: provider, model, intent, risk, sandbox, requiredMcp, optionalMcp, disabledMcp
+- `OmkEvent`: turn_started|progress|mcp_status|warning|result|error|turn_finished
+- `ReasoningTrace`: intent, plan, execution, evidence, result, privacy
+
+## Invariants
+
+- I-001: availableMcp ≠ prompt MUST activate
+- I-004: optional MCP failure = warning, not fatal
+- I-005: raw provider events not visible in stdout
+- I-006: status requiredMcp=[]
+- I-008: slash commands go through CommandBus
+- I-011: kimi-print is debug-only
+
+## Theme System
+
+- `src/cli/theme/theme-registry.ts`: ThemePalette with SemanticToken, 5 palettes (omk/minimal/mono/dark/light)
+- `src/cli/theme/theme-resolver.ts`: Resolves active theme from --theme flag → OMK_THEME env → project config → user config
+
+## i18n
+
+- `src/util/i18n.ts`: Bilingual (KO/EN) support via `t()` function
+- Keys: nlp.*, normalizer.*, ui.*, nlg.*
+
+## CLI v2
+
+- `src/cli/v2/cli-v2-skeleton.ts`: Clipanion-based commands (Chat, Run, Status, Model, Doctor, Memory, Theme)
+- `src/cli/v2/provider-commands.ts`: Provider + Model commands
+- `src/cli/v2/workflow-commands.ts`: Workflow + Consent commands
+- `src/cli/v2/chat-repl.ts`: Interactive REPL with pipeline integration
+- `src/cli/v2/persistent-memory.ts`: Section 17 memory store
+- Enable with `OMK_CLI_V2=1`
+
+## Providers
+
+- Default: mimo (mimo-v2.5-pro) via `https://api.xiaomimimo.com/v1`
+- Kimi: kimi-api (direct Moonshot HTTP), kimi-wire (kimi --wire binary)
+- Others: codex, deepseek, opencode, openrouter, qwen, local-llm
+
+## Tests
+
+- `test/v2-regression.test.mjs`: 10 tests (20.1-20.7) — all PASS
+- `test/cli-v2-gating.test.mjs`: 7 tests — all PASS

package/docs/use-cases/evidence-gated-coding-agents.md

@@ -0,0 +1,52 @@
+# Evidence-gated coding agents
+
+## Short answer
+
+Evidence-gated coding means an agent cannot simply say "done." It must produce verifiable artifacts such as diffs, command output, test results, review logs, or DAG run records before a task is treated as complete.
+
+## What does evidence-gated mean in OMK?
+
+OMK compiles a task into a DAG, assigns scoped lanes, runs provider-specific agents, collects evidence, and writes replayable artifacts under `.omk/runs/<run-id>/`. If a required evidence gate is missing, completion is blocked instead of assumed.
+
+## How OMK implements it
+
+1. The user goal becomes an input envelope.
+2. The envelope compiles into a DAG with lane-level acceptance and evidence expectations.
+3. Lanes execute with explicit read/write/shell/merge authority.
+4. Evidence is collected: command output, diff, artifact, metric, or review.
+5. A verify gate checks the evidence before completion is claimed.
+
+## Example
+
+```bash
+omk do "review this repo for release risk" --dry-run --json
+```
+
+Dry-run artifacts:
+
+```txt
+.omk/runs/<run-id>/input-envelope.json
+.omk/runs/<run-id>/dag.json
+.omk/runs/<run-id>/dag-compile-report.json
+```
+
+Executing the compiled DAG adds loop artifacts such as `loop-state.json` and `loop-decisions.jsonl`.
+
+## How do I verify it locally?
+
+```bash
+npm run verify:no-kimi
+npm run proof:check
+```
+
+Source-controlled proof bundles are listed in the [proof index](https://github.com/dmae97/open-multi-agent-kit/blob/main/proof/PROOF_INDEX.md).
+
+## What this does not claim
+
+Evidence gates do not prove a provider has write authority, do not prove a release is safe, and do not replace full CI. Safety claims are scoped to the exact adapter, command, and gate that produced them.
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [Replayable agent runs](replayable-agent-runs.md)
+- [Provider routing for AI coding](provider-routing-for-ai-coding.md)

package/docs/use-cases/no-kimi-mode.md

@@ -0,0 +1,38 @@
+# No-Kimi mode
+
+## Short answer
+
+OMK is not a Kimi wrapper. It runs as the `open-multi-agent-kit` package with the `omk` binary, and Kimi-compatible lanes are optional adapters.
+
+## Can OMK run without Kimi?
+
+Yes. OMK is provider-neutral. You can run it with Codex, OpenCode, DeepSeek, Qwen, OpenRouter, MiMo, or local models and never select a Kimi-compatible adapter.
+
+## How is no-Kimi verified?
+
+```bash
+npm ci
+npm run build
+npm run verify:no-kimi
+```
+
+`verify:no-kimi` exercises doctor, chat, codex, default-surface, and runtime-routing paths with provider pinning, smoke mode, and `--mcp-scope none` so the legacy Kimi fallback is not used. The source-controlled `009-no-kimi-smoke` proof bundle additionally pins `KIMI_BIN=/nonexistent/kimi`.
+
+## Quick start without Kimi
+
+```bash
+npm install -g open-multi-agent-kit
+omk init
+omk doctor
+omk do "explain this repo" --dry-run --json
+```
+
+## What this does not claim
+
+A no-Kimi run still depends on at least one configured provider; OMK does not ship a bundled model.
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [Provider routing for AI coding](provider-routing-for-ai-coding.md)
+- [Provider maturity](../provider-maturity.md)

package/docs/use-cases/provider-routing-for-ai-coding.md

@@ -0,0 +1,36 @@
+# Provider routing for AI coding
+
+## Short answer
+
+Provider routing means OMK selects a compatible coding runtime for each task and falls back in a ranked order when one fails, instead of hardcoding a single model.
+
+## How does OMK route coding agents?
+
+OMK classifies task intent, filters compatible runtimes, scores them by quality, evidence pass rate, and recent failures, runs the best runtime, and records the selected runtime plus a fallback chain. Routing is evidence-aware, not just provider-name matching.
+
+## Which providers can participate?
+
+- **Codex (app/CLI OAuth)**: compatibility path through the official Codex login.
+- **OpenCode / CommandCode (CLI)**: compatibility paths when the local CLI and auth are present.
+- **Claude Code**: a coding agent surface routed through OMK lanes.
+- **DeepSeek, Qwen, OpenRouter, MiMo, local LLM**: advisory/read/review lanes unless a tested contract grants more authority.
+- **Kimi-compatible API/print lanes**: optional adapters, not the package identity.
+
+Provider authority is not equal. See [provider maturity](../provider-maturity.md) before treating any lane as a write or merge authority.
+
+## Example
+
+```bash
+omk provider list
+omk do "add tests for the router" --provider auto --dry-run --json
+```
+
+## What this does not claim
+
+Routing does not grant every adapter equal write/merge authority, and adapter health depends on local CLI and auth setup.
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [No-Kimi mode](no-kimi-mode.md)
+- [Scoped MCP for coding agents](scoped-mcp-for-coding-agents.md)

package/docs/use-cases/replayable-agent-runs.md

@@ -0,0 +1,40 @@
+# Replayable agent runs
+
+## Short answer
+
+A replayable agent run means OMK records what a coding agent planned and did as artifacts under `.omk/runs/<run-id>/`, so the run can be inspected, audited, and replayed later.
+
+## What artifacts does OMK save?
+
+A dry run writes:
+
+```txt
+.omk/runs/<run-id>/input-envelope.json
+.omk/runs/<run-id>/dag.json
+.omk/runs/<run-id>/dag-compile-report.json
+```
+
+Executing the compiled DAG adds loop artifacts such as `loop-state.json` and `loop-decisions.jsonl`. Run event logs are written to `.omk/runs/<run-id>/events.ndjson`.
+
+## How do I inspect or replay a run?
+
+```bash
+omk runs
+omk inspect <run-id>
+omk replay <run-id>
+omk why
+```
+
+## Why does replay matter?
+
+Replayable artifacts let a reviewer see the goal, the compiled DAG, the routing decisions, and the evidence trail instead of trusting a narrative "done" message.
+
+## What this does not claim
+
+Run artifacts are reviewable local state, not a guarantee of correctness. Treat them as evidence to inspect, not as proof that a change is safe.
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [Evidence-gated coding agents](evidence-gated-coding-agents.md)
+- [OMK claims and evidence](../claims.md)

package/docs/use-cases/scoped-mcp-for-coding-agents.md

@@ -0,0 +1,34 @@
+# Scoped MCP for coding agents
+
+## Short answer
+
+Scoped MCP means each agent lane only sees the Model Context Protocol servers, skills, and hooks it needs, instead of inheriting every global tool and secret.
+
+## Why does tool scope matter for coding agents?
+
+An agent with unrestricted tool access can read secrets, write outside its task, or run shell commands it was never meant to. OMK keeps MCP servers, skills, hooks, and memory bounded per lane so authority matches the task.
+
+## How OMK implements it
+
+- Default project scope reads project `.kimi/mcp.json` and `.omk/mcp.json`; the generated safe default is `omk-project` only.
+- All-scope can read user `~/.kimi/mcp.json` at runtime without copying or printing global MCP secrets.
+- Each lane receives only the capabilities its role requires.
+- Tool authority is separated into read, write, shell, and merge.
+
+## Example
+
+```bash
+omk do "summarize open issues" --mcp-scope project --dry-run --json
+omk mcp doctor
+omk mcp list
+```
+
+## What this does not claim
+
+Scoped MCP is an authority and configuration boundary, not an OS-level sandbox. OS-level sandboxing is planned, not claimed. See [SECURITY.md](../../SECURITY.md).
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [Provider routing for AI coding](provider-routing-for-ai-coding.md)
+- [Evidence-gated coding agents](evidence-gated-coding-agents.md)