open-multi-agent-kit 0.78.8 → 0.79.3

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

@@ -375,8 +375,8 @@ $\texttt{OMK\_NODE\_ROLE}: \omega$
 ## Paper-ready summary paragraphs
 
 ```latex
-\paragraph{Provider-neutral native orchestration.}
-OMK implements a provider-neutral runtime architecture under active hardening. For each interactive root turn, OMK constructs a prompt envelope, injects scoped capabilities such as MCP servers, skills, and hooks, and materializes the turn as a DAG coordinator node. The node is converted into a context capsule and then into a provider-neutral AgentTask. A runtime router classifies the task intent, filters runtimes by capability compatibility, scores them using evidence history and preference priors, and executes the selected runtime with an explicit fallback chain. This design keeps the configured authority provider as the mature authority runtime while allowing Kimi API, Codex, DeepSeek, OpenCode, and CommandCode to participate as typed worker runtimes when adapter health, approval policy, sandbox behavior, and capability contracts match the task.
+\paragraph{Kimi-first native orchestration.}
+OMK implements a Kimi-first but provider-neutral runtime architecture under active hardening. For each interactive root turn, OMK constructs a prompt envelope, injects scoped capabilities such as MCP servers, skills, and hooks, and materializes the turn as a DAG coordinator node. The node is converted into a context capsule and then into a provider-neutral AgentTask. A runtime router classifies the task intent, filters runtimes by capability compatibility, scores them using evidence history and preference priors, and executes the selected runtime with an explicit fallback chain. This design preserves Kimi as the mature authority runtime while allowing Codex, DeepSeek, OpenCode, and CommandCode to participate as typed worker runtimes when adapter health, approval policy, sandbox behavior, and capability contracts match the task.
 
 \paragraph{Secure prompt and environment transport.}
 Recent OMK revisions harden worker execution by removing prompt payloads from process arguments. Kimi DAG prompts are transmitted through standard input with \texttt{--input-format text}, reducing process-list leakage risk. Kimi child execution and default native worker spawn paths receive scoped metadata through sanitized child environments. External CLI adapters and explicit override environments remain trusted local inputs and must be reviewed per adapter.
@@ -400,304 +400,3 @@ Recent OMK revisions harden worker execution by removing prompt payloads from pr
 - Provider stderr diagnostics still require continued redaction/debug-gating work; safety claims depend on the exact adapter path and tests.
 - Provider health probes are improving, but binary/API presence, auth state, model support, and quota state are not yet uniformly separated across every adapter; Algorithm 5 routes by available registry/capability/evidence metadata, not by universal quota-aware health.
 - ActionAtom, Novelty Guard, and provider-lane fanout language in prompt/harness surfaces remains contract-level unless backed by a concrete runtime implementation and tests.
-
-# Appendix: OMK Next-Step Runtime Hardening Algorithms
-
-This appendix defines the hardening gate algorithms used to advance the OMK native root runtime from internal → pre-release → stable. Each algorithm returns a score or verdict; the thresholds and weights below must be preserved exactly.
-
-## Algorithm 1: Next Implementation Stage Controller
-
-**Inputs**
-
-- Current stage $s \in \{\text{internal}, \text{pre-release}, \text{stable}\}$
-- Proof trust score $T_b$
-- Evidence item trust $T_e$
-- Public surface count $P$
-- Router v2 cutover status $C_r \in \{\text{shadow}, \text{cutover}\}$
-
-**Output**
-
-- Next stage $s'$
-
-**Pseudocode**
-
-```text
-function NextStage(s, T_b, T_e, P, C_r):
-    if P > 7:
-        return s
-    if s = internal:
-        if T_b ≥ 0.60 and T_e ≥ 0.75:
-            return pre-release
-    if s = pre-release:
-        if T_b ≥ 0.75 and T_e ≥ 0.75 and C_r = cutover:
-            return stable
-    return s
-```
-
-## Algorithm 2: Public Surface Freeze
-
-**Inputs**
-
-- Public surface set $S_{\text{pub}}$ (documented API, CLI commands, environment variables)
-- Freeze baseline $B_{\text{pub}}$
-
-**Output**
-
-- Freeze verdict $\in \{\text{pass}, \text{fail}\}$
-
-**Pseudocode**
-
-```text
-function PublicSurfaceFreeze(S_pub, B_pub):
-    P ← |S_pub|
-    Δ ← S_pub \ B_pub
-    if P > 7:
-        return fail
-    if |Δ| > 0:
-        return fail
-    return pass
-```
-
-**Invariant**
-
-- Surface public count $P \le 7$.
-- No new public members may be added after the freeze baseline.
-
-## Algorithm 3: Proof Trust MVP
-
-**Inputs**
-
-- Eight normalized proof dimensions $b_1 \dots b_8$:
-  1. Unit test pass rate
-  2. Lint / format gate
-  3. Type-check gate
-  4. Secret-scan gate
-  5. Smoke test gate
-  6. Code-review sign-off
-  7. Documentation sync
-  8. Build / provenance gate
-
-**Formula**
-
-$$
-T_b = 0.15 b_1 + 0.15 b_2 + 0.10 b_3 + 0.15 b_4 + 0.15 b_5 + 0.15 b_6 + 0.05 b_7 + 0.10 b_8
-$$
-
-**Thresholds**
-
-- Stable: $T_b \ge \tau_{\text{proof}} = 0.85$
-- Pre-release: $T_b \ge 0.75$
-- Internal: $T_b \ge 0.60$
-
-## Algorithm 4: Evidence Item Trust
-
-**Inputs**
-
-- Six normalized evidence dimensions $e_1 \dots e_6$:
-  1. Changed-file inventory
-  2. Commands-run log
-  3. Passed quality gates
-  4. Failure disclosure completeness
-  5. Risk note presence
-  6. Harness artifact presence
-
-**Formula**
-
-$$
-T_e = 0.25 e_1 + 0.20 e_2 + 0.15 e_3 + 0.20 e_4 + 0.10 e_5 + 0.10 e_6
-$$
-
-**Threshold**
-
-- $\tau_{\text{evidence}} = 0.75$
-
-## Algorithm 5: Provider Maturity MVP
-
-**Inputs**
-
-- Eight normalized provider dimensions $p_1 \dots p_8$:
-  1. Binary / package presence
-  2. Authentication health
-  3. Model list currency
-  4. Quota-separation probe
-  5. Recent error rate
-  6. Fallback success rate
-  7. Stderr redaction coverage
-  8. Sandbox hint enforcement
-
-**Formula**
-
-$$
-M_p = 0.10 p_1 + 0.10 p_2 + 0.15 p_3 + 0.10 p_4 + 0.15 p_5 + 0.15 p_6 + 0.15 p_7 + 0.10 p_8
-$$
-
-**Cutoffs**
-
-- $M_p \ge 0.75$ required for pre-release worker eligibility.
-- $M_p \ge 0.85$ recommended for stable default authority.
-
-## Algorithm 6: Router v2 Cutover
-
-**Inputs**
-
-- Six positive router quality dimensions $r_1 \dots r_6$:
-  1. Intent classification accuracy
-  2. Median routing latency
-  3. Fallback utilization
-  4. Evidence-pass rate
-  5. Decision-trace completeness
-  6. Health-separation coverage
-- Two penalty terms $r_7, r_8$
-
-**Formula**
-
-$$
-Q_r = 0.25 r_1 + 0.15 r_2 + 0.20 r_3 + 0.15 r_4 + 0.10 r_5 + 0.10 r_6 - 0.15 r_7 - 0.10 r_8
-$$
-
-**Shadow rule**
-
-- If $\texttt{OMK\_ROUTER\_V2} = \text{shadow}$:
-  - Execute Router v2 alongside Router v1.
-  - Record both decisions and discrepancies.
-  - Cutover is allowed only when $Q_r \ge 0.85$ and the discrepancy rate is zero across the minimal verified demo run.
-
-## Algorithm 7: Minimal Verified Demo Run
-
-**Inputs**
-
-- Runtime $\mathcal{R}$
-- Demo scenario set $D = \{d_{\text{read}}, d_{\text{write}}, d_{\text{shell}}, d_{\text{fallback}}\}$
-
-**Output**
-
-- Demo verdict and evidence bundle $\mathcal{E}_D$
-
-**Pseudocode**
-
-```text
-function MinimalVerifiedDemoRun(R, D):
-    E_D ← ∅
-    for d in D:
-        r ← R.Execute(d, abortSignal=NewAbortController())
-        if r.exitCode ≠ 0:
-            return (fail, E_D)
-        if SecretScan(r.stdout, r.stderr) ≠ clean:
-            return (fail, E_D)
-        E_D ← E_D ∪ {d, r.metadata, r.evidence}
-    T_e ← ComputeEvidenceTrust(E_D)
-    if T_e < 0.75:
-        return (fail, E_D)
-    return (pass, E_D)
-```
-
-## Algorithm 8: Release Promotion Gate
-
-**Inputs**
-
-- Nine positive release dimensions $v_1 \dots v_9$:
-  1. Proof trust $T_b$
-  2. Evidence trust $T_e$
-  3. Public surface freeze pass
-  4. Provider maturity $M_p$
-  5. Router v2 quality $Q_r$
-  6. Minimal demo run pass
-  7. Security review closure
-  8. Docs / changelog sync
-  9. Issue closure rate
-- One penalty term $v_{10}$ for unresolved high-severity risk
-
-**Formula**
-
-$$
-R_v = 0.15 v_1 + 0.10 v_2 + 0.10 v_3 + 0.10 v_4 + 0.10 v_5 + 0.15 v_6 + 0.15 v_7 + 0.10 v_8 + 0.10 v_9 - 0.15 v_{10}
-$$
-
-**Promotion logic**
-
-```text
-function ReleasePromotion(R_v, T_b, T_e, P, Δ):
-    if P > 7 or |Δ| > 0:
-        return internal
-    if R_v ≥ 0.85 and T_b ≥ 0.85 and T_e ≥ 0.75:
-        return stable
-    if R_v ≥ 0.75 and T_b ≥ 0.75 and T_e ≥ 0.75:
-        return pre-release
-    return internal
-```
-
-> **Final Rule 1:** No stage promotion may occur while the public surface count exceeds 7 or any new public surface has been added since the freeze baseline.
-
-> **Final Rule 2:** Router v2 cutover remains in `OMK_ROUTER_V2=shadow` mode until $Q_r$ exceeds the stable threshold and zero decision regressions are observed across the minimal verified demo run.
-
-> **Final Rule 3:** Release promotion to stable requires $\tau_{\text{proof}} \ge 0.85$, $\tau_{\text{evidence}} \ge 0.75$, and all eight algorithms to report pass with recorded harness artifacts.
-
-## Algorithm 9: Regression Proof Matrix
-
-Algorithm 9 is the release-defense proof that Algorithms 1--8 are not only documented or implemented, but repeatedly verifiable through tests, proof bundles, decision traces, and reachable CLI surfaces.
-
-**Inputs**
-
-- Algorithm set $A = \{a_1, \dots, a_8\}$
-- Test suite $T$
-- Proof bundles $B$
-- Release candidate $v$
-
-**Per-algorithm coverage**
-
-For each algorithm $a_i$:
-
-$$
-coverage_i =
-0.35\mathbf{1}[|t_i|>0]
-+0.30\mathbf{1}[|b_i|>0]
-+0.20\mathbf{1}[|d_i|>0]
-+0.15\mathbf{1}[c_i=\texttt{reachable}]
-$$
-
-Where:
-
-- $t_i$ is the set of tests linked to algorithm $a_i$
-- $b_i$ is the set of proof bundles linked to algorithm $a_i$
-- $d_i$ is the set of decision traces linked to algorithm $a_i$
-- $c_i$ is whether the algorithm has a reachable CLI or runtime surface
-
-**Pseudocode**
-
-```text
-function RegressionProofMatrix(A, T, B, v):
-    for a_i in A:
-        t_i ← FindTestsForAlgorithm(a_i, T)
-        b_i ← FindProofBundlesForAlgorithm(a_i, B)
-        d_i ← FindDecisionTraceForAlgorithm(a_i, B)
-        c_i ← FindCliSurfaceForAlgorithm(a_i, v)
-
-        coverage_i ←
-            0.35 * 1[|t_i| > 0]
-          + 0.30 * 1[|b_i| > 0]
-          + 0.20 * 1[|d_i| > 0]
-          + 0.15 * 1[c_i = reachable]
-
-        if coverage_i < 0.75:
-            return fail
-
-    trust ← MedianProofTrust(B)
-    router ← RouterShadowSafetyPass(B)
-    maturity ← ProviderAuthorityInvariantPass(B)
-    demo ← MinimalVerifiedDemoPass(v)
-
-    if trust ≥ 0.75 and router = 1 and maturity = 1 and demo = 1:
-        return pass
-    return fail
-```
-
-**Implementation targets**
-
-- `src/evidence/regression-proof-matrix.ts`
-- `scripts/regression-proof-matrix.mjs`
-- `test/regression-proof-matrix.test.mjs`
-- `proof/verified-runs/011-regression-proof-matrix/`
-
-**Release rule**
-
-> Algorithms 1--8 are release-defensible only when Algorithm 9 returns `pass` and `scripts/proof-check.mjs --trust --json` validates the corresponding proof bundles.

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

@@ -46,7 +46,7 @@ Native chat turns must be default-safe. A turn should request only the minimum c
 | `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 only to the configured authority provider, such as Kimi or Codex, when the matching approval and sandbox policy is present.
+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
 

package/docs/provider-maturity.md

@@ -4,7 +4,7 @@ This page documents provider status for the current source tree.
 
 ## Current source target
 
-- Package version: `0.78.8`
+- Package version: `0.79.3`
 - Runtime contract family: `v1.2`
 - Release channel: `pre-1.0`
 

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)

package/docs/versioning.md

@@ -4,11 +4,11 @@ OMK uses two version fields in release artifacts:
 
 | Field | Current value | Source | Meaning |
 | --- | --- | --- | --- |
-| Package version | `0.78.8` | `package.json`, `package-lock.json` | npm/package source version. |
+| Package version | `0.79.3` | `package.json`, `package-lock.json` | npm/package source version. |
 | Runtime version | `v1.2` | `src/version.ts`, JSON schemas | Contract/runtime family used by OMK envelopes. |
 | Release channel | `pre-1.0` | `src/version.ts` | Pre-1.0 package channel. |
 
-`0.78.8` is the package source version for the `v1.2` runtime contract family.
+`0.79.3` is the package source version for the `v1.2` runtime contract family.
 Use `v1.2` only for runtime contracts; do not substitute it for the package version.
 
 ## Contract versions
@@ -16,7 +16,9 @@ Use `v1.2` only for runtime contracts; do not substitute it for the package vers
 Current source declares these machine-readable contracts:
 
 - `omk.contract.v1`
+- `omk.command.v1`
 - `omk.evidence.v1`
+- `omk.evidence-bundle.v1`
 - `omk.decision.v1`
 - `omk.run-manifest.v1`
 - `omk.provider.v1`
@@ -25,6 +27,10 @@ Current source declares these machine-readable contracts:
 
 The JSON schemas live in `schemas/` and are checked by `npm run schema:check`.
 
+`omk.command.v1` is the automation-facing command envelope for new CI/agent integrations. `omk.contract.v1` remains the established CLI JSON envelope for existing commands while command outputs migrate incrementally. To inspect the new envelope without breaking existing automation, run `node dist/cli.js version --json --command-envelope` after `npm run build:clean`.
+
+Runtime event logs are standardized as `.omk/runs/<runId>/events.ndjson`. OMK also mirrors `.omk/runs/<runId>/events.jsonl` for compatibility with existing replay/read tooling during the migration window.
+
 ## Commands
 
 Check package, lockfile, source constants, and schema version constants:
@@ -44,6 +50,6 @@ The `version --json` command emits one `omk.contract.v1` envelope whose data pay
 
 ## Documentation rules
 
-- Use `0.78.8` when referring to the current package source version.
+- Use `0.79.3` when referring to the current package source version.
 - Use `v1.2` only for the runtime contract family.
 - Keep historical changelog entries unchanged unless the text is not clearly historical.

package/docs/what-is-omk.md

@@ -0,0 +1,64 @@
+# What is OMK?
+
+OMK is an evidence-gated control plane for AI coding agents.
+
+It turns a coding task into a scoped DAG run, routes the right provider, limits tool authority, requires evidence before completion, and saves replayable artifacts under `.omk/runs/`.
+
+OMK is useful when developers want to run Codex, Claude Code, OpenCode, DeepSeek, Qwen, OpenRouter, MiMo, optional Kimi-compatible adapters, or local models in the same repository without giving every agent the same write or shell access.
+
+## Short answer
+
+OMK is a local-first control plane for coding agents. It coordinates multiple AI coding providers through scoped DAG lanes, evidence gates, provider authority rules, and replayable run artifacts.
+
+## What problem does OMK solve?
+
+Most coding agents can edit code, but they often claim "done" without auditable evidence. OMK adds a control layer that requires artifacts, command output, tests, diffs, or reviewer output before a run is treated as complete.
+
+## Who is OMK for?
+
+OMK is for developers and teams using multiple coding agents, MCP servers, or local LLMs who need safer execution, provider routing, and verifiable completion.
+
+## How does OMK route coding agents?
+
+OMK classifies task intent, filters compatible runtimes, scores them by quality, evidence pass rate, and recent failures, executes the best runtime, and records the selected runtime plus a ranked fallback chain. Provider authority is explicit: read, write, shell, and merge powers are scoped per lane.
+
+## How does OMK prevent agents from claiming done without evidence?
+
+OMK compiles a task into a DAG, assigns scoped lanes, runs provider-specific agents, and collects evidence. Missing required evidence blocks completion. A dry run already persists reviewable run state before any source file is changed.
+
+## Which providers does OMK support?
+
+OMK is provider-neutral. Codex (app/CLI OAuth), OpenCode/CommandCode (CLI), and Claude Code are compatibility surfaces that depend on local CLIs and auth. DeepSeek, Qwen, OpenRouter, MiMo, and local LLM lanes are advisory/read/review unless a tested contract grants more authority. Kimi-compatible API/print lanes are optional adapters, not the package identity. See [provider maturity](provider-maturity.md).
+
+## Can OMK run without Kimi?
+
+Yes. OMK is not a Kimi wrapper. The package is `open-multi-agent-kit` with the `omk` binary, and a no-Kimi verification path is exercised by `npm run verify:no-kimi`. See [no-Kimi mode](use-cases/no-kimi-mode.md).
+
+## What artifacts does OMK save?
+
+A dry run writes `.omk/runs/<run-id>/input-envelope.json`, `.omk/runs/<run-id>/dag.json`, and `.omk/runs/<run-id>/dag-compile-report.json`. Executing the compiled DAG adds loop artifacts such as `loop-state.json` and `loop-decisions.jsonl`. See [replayable agent runs](use-cases/replayable-agent-runs.md).
+
+## How is OMK different from a normal coding agent?
+
+A coding agent edits code. OMK is the control layer around execution: it routes providers, scopes authority, requires evidence, and records replayable run artifacts. See the [comparisons](comparisons/omk-vs-opencode.md).
+
+## Try it
+
+```bash
+npm install -g open-multi-agent-kit
+omk init
+omk doctor
+omk do "review this repo for release risk" --dry-run --json
+```
+
+## Maturity
+
+Current source version: `open-multi-agent-kit@0.78.9` (`pre-1.0`). The `v1.2` label is a runtime contract family, not a stable npm `1.x` release. OS-level sandboxing is planned, not claimed. See [versioning](versioning.md), [claims](claims.md), and [SECURITY.md](../SECURITY.md).
+
+## Related
+
+- [Evidence-gated coding agents](use-cases/evidence-gated-coding-agents.md)
+- [Scoped MCP for coding agents](use-cases/scoped-mcp-for-coding-agents.md)
+- [Provider routing for AI coding](use-cases/provider-routing-for-ai-coding.md)
+- [Replayable agent runs](use-cases/replayable-agent-runs.md)
+- [OMK claims and evidence](claims.md)