open-multi-agent-kit 0.79.1 → 0.79.3

package/docs/adr/0001-no-native-rust-lane.md

@@ -0,0 +1,52 @@
+# ADR-0001: No native Rust lane for omk-safety
+
+Status: Accepted
+Date: 2026-06-10
+
+## Context
+
+`crates/omk-safety` was scaffolded as a future native lane for safety hot paths
+(redact_stream / sanitize_env / check_path_policy). Remediation item A4 required either
+building it into a measured, shippable lane or killing it with evidence.
+
+## Decision
+
+Remove the Rust surface. Keep TypeScript as the only implementation.
+
+## Evidence (measured, not estimated)
+
+| candidate | p (wall fraction, representative run) | Amdahl ceiling 1/(1−p) | gate (≥1.15) | capability gate |
+|---|---|---|---|---|
+| redact_stream | 0.297% | 1.0030 | FAIL (unreachable even at s=∞) | FAIL — TS hot lane already 65–428 MB/s; 0.26–0.70 ms per 64 KiB ≤ 2 ms budget |
+| sanitize_env | 0.018% | 1.0002 | FAIL | FAIL — cold path, once per spawn |
+| check_path_policy | <0.06% (below sampler resolution) | ≈1.0000 | FAIL | FAIL — realpath syscall-bound |
+
+s (local Rust speedup) was not measured: with all ceilings < 1.004, no finite or infinite
+s can satisfy the gate; building napi bindings to measure it cannot change the outcome.
+
+Profiles, throughput benches, and analysis: `proof/rust-lane-2026-06-10/`.
+
+## Removal scope (larger than "delete crates/" — wired surfaces)
+
+- `crates/`, root `Cargo.toml`, `Cargo.lock` (no rust-toolchain.toml exists)
+- package.json: `rust:build`, `native:build`, and `native:build` steps inside
+  `release:check`, `release:full`, `release:rc`; `native:no-kimi:turn` reference check
+- `scripts/build-native.mjs`, `scripts/rust-safety-check.mjs`,
+  `scripts/normalize-native-artifacts.mjs`, native branch of `scripts/package-audit.mjs`
+- `src/util/native-safety.ts` + doctor lane report (`src/commands/doctor/checks.ts:253,358`)
+- CI: rust/cargo steps in `.github/workflows/{ci,release,smoke-test}.yml`
+- README/CHANGELOG native-lane claims; SECURITY.md stays unchanged (it never claimed
+  native sandboxing — verify on execution)
+
+## What we keep instead (TS follow-ups carrying the real value)
+
+1. Fix O(matches × n) `SecretScanner.getLineColumn` (secret-scanner.ts:729) — measured
+   3 404 ms/call at 1 MiB match-heavy input vs 11.7 ms clean.
+2. Enforce `writableRoots` (src/runtime/sandbox-profile.ts:13) in tool dispatch — currently
+   declared but never consulted against any path.
+3. Deduplicate child-env sanitizer clones (kimi runner ↔ adapter).
+
+## Consequences
+
+- No supply-chain surface from prebuilds; `--ignore-scripts` installs remain trivially safe.
+- A future native lane proposal must re-run this gate with new measured p.

package/docs/benchmark-design.md

@@ -0,0 +1,122 @@
+# OMK Control Plane Replay Benchmark Design
+
+## 1. Purpose
+
+Design a reproducible benchmark suite that measures OMK control plane
+performance across 10 representative task categories. The benchmark runs in
+**shadow mode** (recorded traces, no live LLM calls) for baseline
+reproducibility, with optional **live-evaluation mode** for regression
+testing against real providers.
+
+## 2. Task Categories
+
+| # | Category | Intent | Description |
+|---|----------|--------|-------------|
+| 1 | read-only repo Q&A | research | Agent answers questions about codebase structure |
+| 2 | small bug fix | debugging | Single-file typo / logic fix |
+| 3 | failing test repair | debugging | Update implementation to satisfy failing test |
+| 4 | multi-file refactor | refactor | Rename/move symbols across 3+ files |
+| 5 | CLI command task | shell-operation | Execute and verify CLI output |
+| 6 | dependency update | coding | Bump package version, fix breaking changes |
+| 7 | merge-conflict task | merge | Resolve git merge conflict automatically |
+| 8 | security-sensitive task | review | Patch vulnerability with audit trail |
+| 9 | provider failure fallback | debugging | Primary provider fails; fallback succeeds |
+| 10 | quota/auth failure fallback | debugging | Quota/auth error triggers provider switch |
+
+## 3. Metrics
+
+| Metric | Definition | Source |
+|--------|-----------|--------|
+| solve_rate | passed_tasks / total_tasks | harness result |
+| evidence_trust_score | ETS v2 score per task | evidence-trust-score engine |
+| false_done_rate | tasks claiming success with failing evidence / total | harness+ETS |
+| fallback_success_rate | fallback attempts that succeed / total fallback attempts | router decision trace |
+| router_regret | best_available_runtime_score − selected_runtime_score | shadow-mode diff |
+| cost_per_solved_task | Σ costUsdEstimated / solved_count | attempt records |
+| p95_latency | 95th percentile of task latencyMs | attempt records |
+| rollback_rate | tasks rolled back / total tasks | decision trace |
+| sandbox_violation_count | tasks with unexpected file writes outside worktree | sandbox audit |
+
+**router_regret** is computed in shadow mode by scoring all candidates for
+every decision and comparing the selected runtime’s composite against the
+maximum composite.
+
+## 4. Reproducibility Contract
+
+Every benchmark run must pin:
+- **treeHash**: git commit SHA of the repo under test
+- **seed**: PRNG seed for synthetic fixture generation
+- **providerConfigHash**: hash of the runtime provider configuration
+- **omkVersion**: package version
+- **benchmarkSchemaVersion**: `omk.benchmark.v1`
+
+Shadow-mode runs use pre-recorded `BenchmarkTrace` fixtures (see
+`src/benchmark/fixtures.ts`). Live-evaluation mode records new traces into
+`.omk/benchmarks/<runId>/`.
+
+## 5. Shadow Mode
+
+Shadow mode runs router v1 and v2 side-by-side on identical inputs:
+1. Load a `BenchmarkTask` fixture.
+2. Run `createRuntimeRouter` (v1) and `createRouterV2ScoringEngine` (v2).
+3. Record both decisions into `ShadowModeRecord`.
+4. Compute `router_regret` for each.
+5. Diff v1/v2 selections and log disagreements.
+
+No LLM API calls are made. Runtime `runNode` is replaced with a stub that
+returns the recorded outcome from the fixture.
+
+## 6. Benchmark Harness Lifecycle
+
+```
+loadConfig() → discoverTasks() → for each task:
+  setupWorktree() → runTask() → evaluateEvidence() → teardown()
+→ computeSummary() → writeJsonReport()
+```
+
+The harness integrates with `scripts/run-tests.mjs` via:
+```bash
+node scripts/run-benchmark.mjs --shadow --summary-json .omk/benchmarks/latest.json
+```
+
+## 7. CI Integration
+
+A new `benchmark` job runs after `fast-gate` passes on `main` branch merges
+and nightly cron. It:
+1. Checks out the repo at the merge commit.
+2. Runs `npm run benchmark:shadow`.
+3. Uploads `.omk/benchmarks/latest.json` as artifact.
+4. Fails if `solve_rate < 0.85` or `false_done_rate > 0.05`.
+
+## 8. Directory Layout
+
+```
+src/benchmark/
+  contracts.ts      # BenchmarkTask, BenchmarkResult, BenchmarkSummary
+  harness.ts        # runBenchmarkSuite(), runBenchmarkTask()
+  shadow-mode.ts    # ShadowModeEngine, computeRouterRegret()
+  fixtures.ts       # generateSyntheticTraces(), loadRecordedTraces()
+scripts/
+  run-benchmark.mjs # CLI entrypoint
+test/
+  benchmark-harness.test.mjs
+.omk/benchmarks/
+  sample-run.json   # example output
+```
+
+## 9. Extending the Benchmark
+
+To add a new task category:
+1. Add intent mapping in `src/benchmark/fixtures.ts`.
+2. Create a fixture under `test/benchmark-fixtures/`.
+3. Add an evaluation rule in `src/benchmark/harness.ts`.
+4. Register the category in `scripts/run-benchmark.mjs`.
+
+## 10. Risks & Mitigations
+
+| Risk | Mitigation |
+|------|-----------|
+| Fixture drift (codebase changes) | Pin treeHash; auto-regenerate fixtures in CI if drift detected |
+| Shadow mode not representative of live behavior | Weekly live-evaluation job with small sample |
+| Metrics gaming (fake evidence) | ETS v2 gaming penalty + runner-source requirement |
+| Secret leakage in recorded traces | Redact with `redactTrace()` before persistence |

package/docs/claims.md

@@ -0,0 +1,85 @@
+# OMK claims and evidence
+
+This document lists what OMK claims, the current status, and how to verify it. Claims are scoped to the exact adapter, command, and gate that produced them.
+
+## Claim: OMK creates replayable run artifacts
+
+Status: implemented.
+
+Evidence:
+- `.omk/runs/<run-id>/input-envelope.json`
+- `.omk/runs/<run-id>/dag.json`
+- `.omk/runs/<run-id>/dag-compile-report.json`
+- loop artifacts on execution: `loop-state.json`, `loop-decisions.jsonl`
+
+Verification:
+```bash
+omk do "review this repo for release risk" --dry-run --json
+omk runs
+```
+
+## Claim: OMK can run without Kimi
+
+Status: implemented and tested.
+
+Evidence:
+- package name `open-multi-agent-kit`, binary `omk`
+- no-Kimi runtime routing and smoke paths
+
+Verification:
+```bash
+npm run verify:no-kimi
+```
+
+## Claim: OMK blocks completion when required evidence is missing
+
+Status: implemented.
+
+Evidence:
+- evidence-block proof bundle `proof/verified-runs/006-evidence-block/proof-bundle.json`
+
+Verification:
+```bash
+npm run proof:check
+```
+
+## Claim: OMK scopes provider authority by task
+
+Status: implemented at the routing/contract level; enforcement depends on the adapter path.
+
+Evidence:
+- read/write/shell/merge authority metadata in task contracts
+- [provider maturity](provider-maturity.md)
+
+Verification:
+```bash
+omk provider list
+omk do "explain this repo" --dry-run --json
+```
+
+## Claim: OMK provides OS-level sandboxing
+
+Status: not claimed. Child-env hardening and approval gates exist; OS-level sandboxing is planned.
+
+Evidence:
+- [SECURITY.md](../SECURITY.md)
+
+## Claim: OMK is a stable 1.x release
+
+Status: not claimed. Current source version is `0.78.9` (`pre-1.0`); `v1.2` is a runtime contract family.
+
+Evidence:
+- [versioning](versioning.md)
+- release truthfulness proof `proof/verified-runs/012-release-truthfulness/proof-bundle.json`
+
+Verification:
+```bash
+npm run version:check
+npm run proof:check
+```
+
+## Related
+
+- [What is OMK?](what-is-omk.md)
+- [Proof index](https://github.com/dmae97/open-multi-agent-kit/blob/main/proof/PROOF_INDEX.md)
+- [Provider maturity](provider-maturity.md)

package/docs/cli-v2-migration.md

@@ -0,0 +1,87 @@
+# CLI v2 Migration Guide
+
+## Overview
+
+OMK CLI v2 migrates from Commander.js to Clipanion + Clack for a modern CLI experience matching opencode-style terminal UX.
+
+## Enabling CLI v2
+
+```bash
+OMK_CLI_V2=1 omk <command>
+```
+
+## Migrated Commands
+
+### Core Commands (cli-v2-skeleton.ts)
+| Command | Clipanion Class | Status |
+|---------|----------------|--------|
+| `omk chat` | ChatCommand | ✅ |
+| `omk run` | RunCommand | ✅ |
+| `omk status` | StatusCommand | ✅ |
+| `omk model` | ModelCommand | ✅ |
+| `omk doctor` | DoctorCommand | ✅ |
+| `omk memory` | MemoryCommand | ✅ |
+| `omk theme` | ThemeCommand | ✅ |
+
+### Provider Commands (provider-commands.ts)
+| Command | Clipanion Class | Status |
+|---------|----------------|--------|
+| `omk provider list` | ProviderListCommand | ✅ |
+| `omk provider use` | ProviderUseCommand | ✅ |
+| `omk provider set` | ProviderSetCommand | ✅ |
+| `omk provider enable` | ProviderEnableCommand | ✅ |
+| `omk provider disable` | ProviderDisableCommand | ✅ |
+| `omk provider doctor` | ProviderDoctorCommand | ✅ |
+| `omk provider profiles` | ProviderProfilesCommand | ✅ |
+| `omk model list` | ModelListCommand | ✅ |
+| `omk model aliases` | ModelAliasesCommand | ✅ |
+| `omk model resolve` | ModelResolveCommand | ✅ |
+| `omk model use` | ModelUseCommand | ✅ |
+
+### Workflow Commands (workflow-commands.ts)
+| Command | Clipanion Class | Status |
+|---------|----------------|--------|
+| `omk plan` | PlanCommand | ✅ |
+| `omk feature` | FeatureCommand | ✅ |
+| `omk bugfix` | BugfixCommand | ✅ |
+| `omk refactor` | RefactorCommand | ✅ |
+| `omk review` | ReviewCommand | ✅ |
+| `omk team` | TeamCommand | ✅ |
+| `omk orchestrate` | OrchestrateCommand | ✅ |
+| `omk consent` | ConsentCommand | ✅ |
+
+## Architecture
+
+All CLI v2 commands route through the full runtime pipeline:
+
+```
+User Input → Clipanion CLI → OmkCommand.executePipeline()
+  → CommandBus → IntentClassifier → CapabilitySelector
+  → RuntimeSidecar → OutputRouter → ThemeRenderer/NlpRenderer/JsonRenderer
+```
+
+## Key Files
+
+- `src/cli/v2/cli-v2-skeleton.ts`: Core commands + createCliV2()
+- `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
+- `src/cli/v2/interactive-prompt.ts`: Clack prompts
+- `src/cli/v2/persistent-memory.ts`: Memory store
+- `src/cli/main.ts`: CLI v2 routing (isCliV2Enabled())
+
+## UI/UX Style
+
+CLI v2 uses opencode-style terminal output:
+- `> provider · model` one-line header
+- Spinner animation during processing
+- Compact error display with box drawing
+- Status bar at bottom
+- Bilingual (KO/EN) via i18n
+
+## Testing
+
+```bash
+node --test test/cli-v2-gating.test.mjs  # 7 tests
+node --test test/v2-regression.test.mjs   # 10 tests
+```

package/docs/codex-oauth-setup.md

@@ -0,0 +1,62 @@
+# Codex app / OAuth setup
+
+OMK uses the official Codex app/CLI for Codex authentication. OMK does not store Codex login data, read `~/.codex/auth.json`, or print OAuth/session tokens.
+
+## Recommended flow
+
+1. Install or expose the official Codex CLI/app on `PATH`.
+   ```bash
+   codex --version
+   ```
+2. Complete the official Codex OAuth login.
+   ```bash
+   codex login
+   ```
+3. Ask OMK to guide or run the official login flow.
+   ```bash
+   omk codex auth --choice plus-pro --run
+   omk provider doctor codex --soft
+   ```
+4. Import only safe Codex MCP server configuration when needed.
+   ```bash
+   omk mcp import-codex
+   ```
+
+## Policy
+
+- OMK project configuration lives under `.omk/`.
+- Codex-specific login state remains owned by the official Codex app/CLI.
+- OMK may inspect Codex MCP server configuration, but secret-bearing `headers`, `env`, bearer values, and token files are not copied into project MCP config.
+- Do not `cat` token/session files or paste OAuth values into logs.
+
+## OpenAI Images API is separate
+
+Codex/ChatGPT OAuth proves the Codex CLI login state only. It is not an OpenAI Platform API key.
+
+`omk image generate` and `omk image edit`, including `--model gpt-image-2`, require a separate OpenAI Platform project API key supplied only at runtime.
+
+```bash
+OPENAI_API_KEY=<platform-project-key> omk image generate "OMK control-plane hero" --model gpt-image-2
+```
+
+You can also run the guided key setup instead of exporting the variable manually:
+
+```bash
+omk openai setup
+```
+
+Do not store the API key in project files; prefer environment variables or a user-local secret store.
+
+See [`openai-platform-image-keys.md`](openai-platform-image-keys.md) for the one-shot key flow.
+
+## Troubleshooting
+
+- If `codex` is not found, install the official Codex CLI/app or add it to `PATH`.
+- If login status is unclear, run `codex login`, then `omk provider doctor codex --soft`.
+- If MCP import finds nothing, check whether your Codex config has importable MCP servers.
+
+## Security principles
+
+- Never print token/session files.
+- OMK never reuses Codex OAuth values as OpenAI API bearer keys.
+- In shared environments, keep per-provider authentication and project configuration separate.

package/docs/comparisons/omk-vs-claude-code.md

@@ -0,0 +1,31 @@
+# OMK vs Claude Code
+
+## Short answer
+
+Claude Code is a coding agent. OMK is a control plane that can run Claude Code as one provider lane with scoped authority, DAG orchestration, evidence gates, and replayable artifacts.
+
+## Category difference
+
+- **Claude Code**: executes coding tasks as a single-agent assistant.
+- **OMK**: routes tasks across providers, scopes read/write/shell/merge authority, requires evidence before completion, and records replayable run artifacts.
+
+## When to use which
+
+- Use Claude Code when you want a direct coding assistant.
+- Use OMK when you want multi-provider routing, per-task authority, and verifiable completion across agents in the same repository.
+
+## How they work together
+
+Claude Code can act as a coding agent surface inside an OMK lane while OMK keeps routing, authority, and evidence explicit.
+
+```bash
+omk do "review this repo for release risk" --dry-run --json
+```
+
+See [evidence-gated coding agents](../use-cases/evidence-gated-coding-agents.md).
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [OMK vs Codex](omk-vs-codex.md)
+- [OMK vs OpenCode](omk-vs-opencode.md)

package/docs/comparisons/omk-vs-codex.md

@@ -0,0 +1,33 @@
+# OMK vs Codex
+
+## Short answer
+
+Codex is a coding agent. OMK is a control plane that can run Codex as one provider lane with scoped authority, DAG orchestration, evidence gates, and replayable artifacts.
+
+## Category difference
+
+- **Codex**: executes coding tasks through the official Codex app/CLI.
+- **OMK**: routes tasks across providers, scopes read/write/shell/merge authority, requires evidence before completion, and records replayable run artifacts.
+
+## When to use which
+
+- Use Codex when you want a direct coding assistant.
+- Use OMK when you want to route across providers, restrict authority per task, and require evidence before marking work complete.
+
+## How they work together
+
+OMK delegates Codex auth to the official Codex app/CLI and never reads or prints `~/.codex/auth.json` tokens.
+
+```bash
+codex login
+omk codex auth --choice plus-pro --run
+omk provider doctor codex --soft
+```
+
+See [Codex OAuth setup](../codex-oauth-setup.md) and [provider routing](../use-cases/provider-routing-for-ai-coding.md).
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [OMK vs OpenCode](omk-vs-opencode.md)
+- [OMK vs Claude Code](omk-vs-claude-code.md)

package/docs/comparisons/omk-vs-mcp-agent.md

@@ -0,0 +1,33 @@
+# OMK vs MCP agent frameworks
+
+## Short answer
+
+MCP agent frameworks give agents tool access through the Model Context Protocol. OMK adds task-level control on top: scoped MCP per lane, provider routing, evidence gates, and replayable artifacts.
+
+## Category difference
+
+- **MCP agent frameworks**: expose tools to an agent through MCP servers.
+- **OMK**: keeps MCP servers, skills, and hooks scoped per lane, routes providers, separates read/write/shell/merge authority, and requires evidence before completion.
+
+## When to use which
+
+- Use an MCP agent framework when you mainly need tool access for one agent.
+- Use OMK when you need bounded tool authority, multi-provider routing, and verifiable, replayable runs.
+
+## How they work together
+
+OMK consumes MCP servers as scoped capabilities per lane instead of importing every global server into every agent.
+
+```bash
+omk mcp list
+omk mcp doctor
+omk do "summarize open issues" --mcp-scope project --dry-run --json
+```
+
+See [scoped MCP for coding agents](../use-cases/scoped-mcp-for-coding-agents.md).
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [OMK vs OpenCode](omk-vs-opencode.md)
+- [Provider routing for AI coding](../use-cases/provider-routing-for-ai-coding.md)

package/docs/comparisons/omk-vs-opencode.md

@@ -0,0 +1,32 @@
+# OMK vs OpenCode
+
+## Short answer
+
+OpenCode is a terminal coding agent. OMK is a control plane for running coding agents with scoped authority, DAG orchestration, evidence gates, and replayable artifacts.
+
+## Category difference
+
+- **OpenCode**: a direct coding loop in the terminal.
+- **OMK**: a layer around execution that routes providers, scopes authority, requires evidence, and saves replayable run artifacts.
+
+## When to use which
+
+- Use OpenCode when you want a direct coding assistant.
+- Use OMK when you want to route tasks across providers, restrict write or shell authority, and require evidence before marking work complete.
+
+## How they work together
+
+OpenCode/CommandCode can participate as a compatibility lane when the local CLI and auth are present.
+
+```bash
+omk provider list
+omk do "refactor the parser" --provider auto --dry-run --json
+```
+
+See [provider routing](../use-cases/provider-routing-for-ai-coding.md).
+
+## Related
+
+- [What is OMK?](../what-is-omk.md)
+- [OMK vs Codex](omk-vs-codex.md)
+- [OMK vs mcp-agent](omk-vs-mcp-agent.md)

package/docs/decision-layer-calibration.md

@@ -0,0 +1,20 @@
+# Decision-Layer Formalization And Calibration
+
+This note tracks the implementation of the June 11 decision-layer hardening spec.
+
+## Implemented
+
+- Route scoring source prior is now a strict tiebreaker: `project=0.02`, `builtin=0.01`, `global=0`.
+- Route scoring computes a base-score lattice gap and asserts `priorSpread < minBaseGap` at module load.
+- Route selection emits bounded `routeTrace` records with `baseScore`, `sourcePrior`, final `score`, features, and reason for benchmark replay.
+- Route calibration helpers implement simplex projection, structured perturbation candidates, smooth keyword saturation, and exact paired McNemar adoption.
+- Trust calibration helpers implement underpowered-data refusal, MAP-style logistic fitting with shrinkage to current checklist weights, AUC comparison, and threshold selection.
+- Ensemble decision can consume Hedge persona weights; the Hedge module updates online weights with an anti-collapse floor and collapse alert.
+- Provenance ratio helpers and `npm run provenance:ratio` report layer-wise originality against an upstream or merge-base fallback.
+- CI fast gate includes a new-file size guard for source/test/script files over 1,000 LoC.
+
+## Deferred
+
+- `git filter-repo --path proof/ --invert-paths` is destructive and requires explicit branch/tag/force-push scope confirmation before execution.
+- Trust and Hedge adoption should be persisted only after enough labeled runs exist (`n >= 100` for trust calibration).
+- Route calibration needs a benchmark suite with at least 50 paired tasks before changing production weights.

package/docs/decisions/2026-06-10-git-history-bloat.md

@@ -0,0 +1,61 @@
+# Decision: Git history bloat — defer rewrite, apply linguist-vendored interim
+
+- Date: 2026-06-10
+- Status: Accepted (interim mitigation only; rewrite deferred pending owner approval)
+
+## Problem
+
+The repository pack is far larger than the working tree:
+
+- `git count-objects -vH` → `size-pack: 80.19 MiB`
+- Tracked worktree content ≈ 27 MiB
+
+The gap is caused by large binary blobs (GIF/MP4/PNG/PPTX) committed and later
+replaced/removed, which remain in history forever.
+
+## Evidence: top-10 largest blobs
+
+Command:
+
+```bash
+git rev-list --objects --all \
+  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
+  | sort -k3 -rn | head -10
+```
+
+Output (2026-06-10):
+
+```text
+blob f2aa8c50905967a71bab34b5045406ed668b3a1c 29252458 readmeasset/kimicat.gif
+blob fee8957c9ff26f7243d375f919c6cba5fa53ca3d 18261906 readmeasset/oneprompt.mp4
+blob 8ff0eb7cc1fa08c49fe51ade9dc016fb81f31cd7 10528089 readmeasset/kimicat.gif
+blob c4fea42c159c57e82f64e274335b9829ea1e8dbe 7016890 readmeasset/oneprompt.gif
+blob e1aa1c049e1444d250da52202944d6f8ef1aed9f 3643625 EGG_PEAK_IR_Malgun_Gothic_FIXED_TRUE_ANIM.pptx
+blob f6097940de448e09de07e9b949f6caab13fec433 3041622 readmeasset/kimicat.mp4
+blob 5f671d8ac6c8a6011891164a0bdfa84ea7733749 2802989 readmeasset/kimicat.mp4
+blob 75169d7c30c48b552c621c2f23779d6354974e9f 1849634 kimichan.png
+blob 8edbf5a56bf456284bbd8fb5aa580245684d72e0 1708509 readmeasset/kimicat.png
+blob 13a70fc8e0a35e20c1967b0306b29540bfb75b88 1522325 readmeasset/kimicat.png
+```
+
+The top 4 blobs alone account for ~65 MB of the 80.19 MiB pack.
+
+## Decision
+
+1. **No history rewrite now.** A `git filter-repo` rewrite of the blobs above
+   would shrink the pack to roughly worktree scale, but it rewrites every
+   commit hash, **invalidates all existing clones, forks, and open PRs**, and
+   requires a coordinated force-push. Execute it ONLY with explicit owner
+   approval and a scheduled migration window.
+2. **Interim mitigation:** mark the intentionally hand-written template JS
+   under `templates/web-bridge/chrome-extension/**` as `linguist-vendored` in
+   `.gitattributes` so language stats and code-scanning surfaces stay clean.
+   `dist/` and `coverage/` remain git-ignored (already present in `.gitignore`).
+
+## Follow-up (requires owner approval)
+
+- `git filter-repo --strip-blobs-bigger-than 1M` (or an explicit path list for
+  `readmeasset/` historical media + the stray `.pptx`/`.png`), then force-push
+  and re-clone guidance for all contributors.
+- Move future README media to GitHub release assets or an external CDN instead
+  of committing binaries.

package/docs/decisions/ADR-theme-dark-only-assets.md

@@ -0,0 +1,43 @@
+# ADR: Dark-only README SVG assets derived from the night-city theme
+
+- Status: accepted
+- Date: 2026-06-10
+- Owners: OMK theme contract lane (T4)
+- Related: `themes/night-city.theme.json`, `scripts/assets-build.mjs`, `scripts/theme-check.mjs`, `proof/theme-2026-06-10/t1-t2-summary.md`
+
+## Context
+
+OMK ships a single `omk.theme.v1` theme — `night-city` (`mode: dark`) — as the source of
+truth for all branded surfaces. Every foreground/background pair in that theme is
+contrast-gated by `npm run theme:check` (text ≥ 4.5, indicator ≥ 3.0; 48 pairs, 0 failed),
+and the gate blocks merge in CI. The 5 README SVG assets
+(`readmeasset/omk-{badges,core-loop,evidence-ledger,logo-mark,provider-lanes}.svg`) are now
+derived from that theme's primitives by `npm run assets:build`, which embeds a
+`derived-from: omk.theme.v1/night-city@<hash>` provenance comment per SVG.
+
+A light variant of the assets was considered for GitHub light-mode READMEs. There is no
+light theme file, no light contrast matrix, and no reviewed light palette — generating one
+by naive color inversion would ship pairs that were never gated.
+
+## Decision
+
+Do **not** build a light variant. Assets are dark-only and derive exclusively from the
+single contrast-gated dark theme.
+
+`scripts/assets-build.mjs` enforces this: it refuses any theme with `mode` other than
+`dark` unless every foreground/background token pair actually used by the SVGs passes the
+same 4.5/3.0 WCAG gates inline (the same model `theme:check` applies). The inline gate
+also runs for dark themes, so a drifted primitive cannot silently ship an unreadable
+asset.
+
+## Consequences
+
+- README assets render correctly on dark backgrounds only; light-mode viewers see the
+  dark cards as framed panels (each SVG paints its own `dark` background rect, so nothing
+  becomes unreadable on a light page).
+- Introducing a light variant requires: a new `omk.theme.v1` theme file with
+  `mode: light`, a full `npm run theme:check` pass for that file, and only then will
+  `npm run assets:build --theme <file>` accept it (its inline used-pair gate must pass).
+- Theme color changes propagate to assets only via `npm run assets:build`; the
+  `@<hash>` provenance suffix makes a stale asset detectable against the current theme
+  file hash.