open-multi-agent-kit 0.78.0

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 only to the configured authority provider, such as Kimi or Codex, when the matching approval and sandbox policy is present.
+
+### 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.78.0`
+- 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/versioning.md

@@ -0,0 +1,49 @@
+# Versioning
+
+OMK uses two version fields in release artifacts:
+
+| Field | Current value | Source | Meaning |
+| --- | --- | --- | --- |
+| Package version | `0.78.0` | `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.0` is the package 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
+
+Current source declares these machine-readable contracts:
+
+- `omk.contract.v1`
+- `omk.evidence.v1`
+- `omk.decision.v1`
+- `omk.run-manifest.v1`
+- `omk.provider.v1`
+- `omk.version.v1`
+- `omk.proof-bundle.v1`
+
+The JSON schemas live in `schemas/` and are checked by `npm run schema:check`.
+
+## Commands
+
+Check package, lockfile, source constants, and schema version constants:
+
+```bash
+npm run version:check
+```
+
+After building, inspect the runtime version envelope:
+
+```bash
+npm run build:clean
+node dist/cli.js version --json
+```
+
+The `version --json` command emits one `omk.contract.v1` envelope whose data payload uses `omk.version.v1`.
+
+## Documentation rules
+
+- Use `0.78.0` 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/llms.txt

@@ -0,0 +1,38 @@
+# open-multi-agent-kit
+
+> Provider-neutral multi-agent orchestration harness for OMK-managed coding agents.
+
+## What is open-multi-agent-kit?
+
+open-multi-agent-kit (OMK) is an open-source CLI tool that turns agent CLIs and model APIs into a parallel, multi-role coding team. OMK is the root orchestrator: it assigns provider lanes, skills, hooks, MCP scope, real-time quality gates, Git worktree-based isolated agent workspaces, local graph memory, and built-in MCP / LSP integration.
+
+## Key Features
+
+- **Multi-Agent Orchestration** — Run planner, coder, reviewer, QA, and security agents in parallel via Git worktrees
+- **DESIGN.md Integration** — Generate UI from Google DESIGN.md standards
+- **Real-Time Quality Gates** — Automated lint, typecheck, test, and build verification
+- **Live HUD / Cockpit** — Terminal dashboard for monitoring parallel agent execution
+- **Local Graph Memory** — Project/session memory stored in `.omk/memory/graph-state.json` with optional Neo4j/Kuzu backends
+- **MCP & LSP Integration** — Seamless Model Context Protocol servers and bundled TypeScript language server
+- **16 Built-in Agent Roles** — planner, coder, reviewer, qa, security, architect, explorer, tester, docs, merger, release, integrator, interviewer, researcher, vision-debugger
+
+## Install
+
+```bash
+npm install -g open-multi-agent-kit
+```
+
+## Quick Start
+
+```bash
+omk init      # Scaffold project
+omk doctor    # Verify environment
+omk chat      # Start interactive OMK session
+omk hud       # Launch live dashboard
+```
+
+## Repository
+
+- GitHub: https://github.com/dmae97/open-multi-agent-kit
+- npm: https://www.npmjs.com/package/open-multi-agent-kit
+- License: MIT