docks-kit 0.15.5 → 0.16.0

package/AGENTS.md

@@ -4,17 +4,20 @@ Canonical instructions for coding agents working on this project. Compatible wit
 
 ## Repository purpose
 
-Portable configuration kit for AI coding agents. Per-tool Single Source of Truth
-(SoT) directories deploy to each tool's user-config location through
-`./docks-kit sync`. Clone once to get a consistent AI-assisted environment on
-supported Linux, macOS, and Windows hosts. The kit focuses on **token efficiency
-without sacrificing quality**. Every setting and hook minimizes token use while
+Portable configuration kit for AI coding agents. The kit manages three coding
+harnesses: Claude Code, Codex, and Oh My Pi (`omp`). Per-tool Single Source of
+Truth (SoT) directories deploy to each harness's user-config location through
+`./docks-kit sync`. The kit also deploys shared [agentskills.io](https://agentskills.io)
+skills. Clone once to get a consistent AI-assisted environment on supported
+Linux, macOS, and Windows hosts. The kit focuses on **token efficiency without
+sacrificing quality**. Every setting and hook minimizes token use while
 preserving rigorous output. When you add or edit anything, ask: *does this
 change reduce tokens without weakening correctness?*
 
 Tool-specific instructions live alongside this file:
 - **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns.
 - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
+- omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
 
 
 docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
@@ -27,17 +30,19 @@ launcher can fall back to Bun source.
 |------|---------|
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows CLI launchers. On supported hosts, each runs the matching binary in `cli/dist/` only when its `--version` matches `package.json`. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
+| `cli/src/engine-native/ompSync.ts` | omp file deployment, marketplace registration, and plugin synchronization |
 | `cli/` | Effect 4 RC CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
+| `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `mcp.json`, and `intercom.json` |
 | `install.sh` / `install.ps1` | POSIX and Windows global installers |
 | `.github/workflows/release-cli.yml` | `cli-v*` release: six binaries for Linux, macOS, and Windows on x64 and arm64, plus `SHA256SUMS` and npm publish |
 | `README.md` | Front door |
 | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
 | `SoT/.agents/skills.txt` | Universal-skill manifest, intentionally empty by default. Adding an [agentskills.io](https://agentskills.io/specification) slug opts it into EngineNative's shared `~/.agents/skills/` bootstrap and Claude symlink. |
 | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
-| `docs/plans/` | Multi-commit work-item plans (`active/` with status in frontmatter, plus `finished/` archive). Convention: `docs/plans/AGENTS.md` |
+| `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it and `docs/CLAUDE.md` contains only `@AGENTS.md`. |
 | `CLAUDE.md` | Claude-specific instructions; imports this `AGENTS.md` |
 | `AGENTS.md` | This file — tool-agnostic instructions |
 
@@ -48,10 +53,19 @@ Codex SoT notes:
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
 - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
+
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
 - Claude's deployed SoT defaults are `model: opus` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: fable` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.219 ensures Claude Code can resolve it to the newest Opus its provider offers — Opus 5 on the Anthropic API or Opus 4.6 on Microsoft Foundry — instead of silently capping Anthropic API users at Opus 4.8 under the former 2.1.170 floor. Keeping the alias provides provider portability and tracks future Opus releases; the literal `claude-opus-5` is unavailable on Foundry. The floor also subsumes Fable 5's older 2.1.170 requirement.
 
-For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT directory.
+omp SoT notes:
+- `SoT/.omp/AGENTS.md`, `config.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
+- `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`.
+- `ompSync.ts syncConfig` deep-merges `config.yml` through `mergeOmpConfig`.
+- Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope.
+- Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
+- The omp CLI is upstream-owned and self-updating through `omp update`. Sync never installs or upgrades the CLI.
+
+For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
 
 ## Engineering rules
 
@@ -59,19 +73,20 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
 - **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-rc.109` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-rc.109` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-rc.109`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
 - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag. The `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` skills target Effect 3.x and do not apply.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, `agents`, and `omp`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync omp` for omp-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Per-machine harness selection.** `~/.docks-kit/state.json` drives a flag-less sync. A missing file selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection file. `docks-kit harnesses` is the only command that writes the selection.
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
-- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
+- **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing and validation. `toolchain.ts` owns verified-version floor reporting over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own their tool-specific sync logic. `ompSync.ts` owns omp file and plugin sync. `ompYaml.ts` owns the omp YAML merge. `harnesses.ts` owns per-machine harness selection. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
 - **Small, reviewable changes.** Bundled multi-concern PRs are harder to review and revert. Split an engine/CLI change and a per-tool config change unless the change requires atomicity.
 - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in the per-tool file) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
-- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md` and `SoT/.codex/AGENTS.md` are loaded into every agent session's prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: would removing it cause the agent to make mistakes? If not, cut it — over-instruction degrades adherence on current frontier models.
+- **SoT prompt files are rules, not explanation.** `SoT/.claude/CLAUDE.md`, `SoT/.codex/AGENTS.md`, and `SoT/.omp/AGENTS.md` are loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict their content to rules, heuristics, and `<constraint>` blocks the agent must *act on* during a turn. Do NOT add inline source citations (`Source: …`, attributed quotes), "why this rule exists" preface text, version-watermarking trivia (e.g. "Distilled from X v2.0, captured 2025-11-07"), per-bug workarounds, or installation instructions. Provenance, motivation, and historical context belong in `CLAUDE.md` / `AGENTS.md` at the repo root (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
 - **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, hook outputs that land in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages (e.g. SessionStart hook output), which is exactly how the kit's date/config injection works.
 
 ## Code style
 
 - Bash: for launchers/installers/hook assets, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
-- JSON config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config (`~/.claude/`, `~/.codex/`) directly.
+- JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.claude/`, `~/.codex/`, or `~/.omp/agent/` directly.
 
 ## Security
 
@@ -87,7 +102,23 @@ Use direct acceptance and focused regressions while iterating, then run the full
 
 ## Skills
 
-This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how EngineNative works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone TypeScript sync logic in `cli/src/engine-native/`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
+**Project-skill scope.** Keep project skills within two classes: kit-mechanic skills and the `unslop` repo-prose skill.
+Canonical project skills live in `.agents/skills/<name>/SKILL.md`.
+Each `.claude/skills/<name>` entry is a relative symlink to its canonical directory.
+Codex reads `.agents/skills/` natively, so one copy serves both tools.
+Kit-mechanic skills document regression-prone TypeScript sync logic in `cli/src/engine-native/`.
+Kit-mechanic skills: `codex-config-merge-context`, `engine-native-context`, `plugin-bootstrap-context`, `settings-merge-context`, `sync-orchestration-context`, `toolchain-context`, `universal-skills-context`, and `omp-sync-context`.
+**Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.
+
+**Windows checkouts.** These nine entries are the only symlinks this repository tracks. Git for Windows defaults to `core.symlinks=false`, which checks a symlink out as a plain file holding the target path, so Claude Code finds no `SKILL.md` and silently loads no project skill. Codex is unaffected, because it reads the real directories under `.agents/skills/`. To restore Claude Code on Windows, enable Developer Mode or run as administrator, then `git config core.symlinks true` and re-checkout the paths: `git checkout -- .claude/skills`. Never repair this by replacing an entry with a copy; two copies drift, which is the failure the canonical layout removes. This limitation is confined to project skills in this checkout. It does not affect the deployed user-level skills, where `skillsSync.ts linkOrCopyWithWarnings` already falls back from symlink to junction to marked copy.
+
+`npx skills add cursor/plugins -s unslop -y -a claude-code codex` installs `unslop`, and root `skills-lock.json` pins it.
+The repository vendors upstream `unslop` text and pins it by the lockfile hash, so never edit it locally.
+Upstream licenses `pstack/` under MIT (Copyright (c) 2026 Lauren Tan), so redistribution is permitted.
+MIT requires the notice to travel with the copy, so `.agents/skills/unslop/LICENSE` vendors it verbatim and must stay beside `SKILL.md`.
+The `unslop` "adding soul" guidance conflicts with the global Simplified Technical English Output Standard.
+The Output Standard wins.
+Use `unslop` only for its pattern-detection lists.
 
 <constraint>
 When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agents/*.md` + its `.codex/agents/*.toml` twin) cites EngineNative internals, name the **module + exported/local function + semantic anchor** (e.g. `claudeSync.ts syncPlugins, pass 5 uninstall guard`) — never a raw `file:NNN` line number, which goes stale on every refactor. Keep exactly one coarse `metadata.source_files[].lines` range per skill file as the sole intentional line-number touchpoint.
@@ -98,42 +129,78 @@ When a kit-mechanic skill, its `references/`, or a wrapper agent (`.claude/agent
 ## Plans
 
 Use direct implementation for one clear, reversible, low-risk local diff with one
-bounded acceptance path; it creates no tracked plan, reviewer, or automatic
+bounded acceptance path; it creates no plan issue, reviewer, or automatic
 commit. Use a canonical plan for explicit planning, multi-commit or
 cross-repository work, cold handoff, an unresolved decision, a cross-subsystem or
 public-contract change, security-sensitive or destructive work, or any
 non-`local` effect.
 
 <constraint>
-Canonical plans live in `docs/plans/active/`; status is frontmatter and
-`docs/plans/finished/` is terminal. Exactly three skills own the workflow:
-`plan-workspace` maintains the workspace; main-context `plan-manager` runs six
-phases — decide, draft, research, one plan review, implement, code review — and
-archives; internal `plan-reviewer` returns a readable pre-implementation verdict.
-Two read-only reviewer wrappers ship, `plan-reviewer` and `code-reviewer`, and
-nothing else in the lifecycle has a wrapper.
+The plan record is a GitHub issue. Its body starts with
+`<!-- plan-contract: v3 -->`, then a blank line and the exact eight `##`
+sections; it has no frontmatter. GitHub owns title, open-work phase, owner,
+timestamps, and completion, and no plan markdown is tracked in the repository.
+Exactly three skills own the workflow: `plan-workspace` maintains the workspace;
+main-context `plan-manager` runs six phases - decide, draft, research, plan
+review, implement, code review - with bounded repair and fresh re-review in both
+review phases, then archives; internal `plan-reviewer` returns one readable
+pre-implementation verdict block per round. Two read-only reviewer wrappers
+ship, `plan-reviewer` and `code-reviewer`, and nothing else in the lifecycle has
+a wrapper.
 </constraint>
 
-The record is markdown only: `plan_contract: v2` frontmatter plus eight `##`
-sections — `## Goal`, `## Research`, `## Steps`, `## Acceptance`,
-`## Do not touch`, `## Open questions`, `## Review`, `## Verification Results`.
-There are no hashes, permits, run identities, locks, bundles, or `v2`/`vN` plan
-files, and the `plan.mjs` shipped inside the installed `plan-lifecycle` plugin
-is the only lifecycle tool. This lifecycle creates zero commits and never
-pushes; commit when the user asks, under `docks:commit-discipline`.
+After the marker and blank line, the record carries exactly `## Goal`,
+`## Research`, `## Steps`, `## Acceptance`, `## Do not touch`,
+`## Open questions`, `## Review`, and `## Verification Results`, in that order
+and once each. `## Goal` carries exactly one mode line. Open-work phase is one
+of `drafting`, `planned`, `ongoing`, or `blocked` in a `plan:<phase>` label; a
+blocked plan starts `## Open questions` with `Blocked: <one-line reason>`.
+Closed completion derives from GitHub `state` and `stateReason`. `## Review`
+contains exactly `_Review records are stored in issue comments._`. Each reviewer
+returns one markdown block, and the manager posts that whole block as one issue
+comment. The latest trusted well-formed record per review kind wins; its author
+must equal the plan's sole assignee. A legacy body verdict is consulted only
+when no trusted comment record exists for that kind. Both review phases use
+fresh inputs and run at most five rounds, stopping on pass, no progress, a
+finding surviving its fix, or `repair` or `fixes-required` in round five. A
+plan-review `blocked` verdict always routes its user-only decision through
+`## Open questions` and `ask`.
+
+The record carries no hash, permit, run identity, lock, or bundle, and the
+`plan.mjs` shipped inside the installed `plan-lifecycle` plugin is the only
+lifecycle tool. An `export` writes the sha256 of the body it copied beside the
+copy so a stale copy cannot revert the record; that digest detects staleness and
+authorizes nothing. Routine plan issue publication, implement-start linked
+branch creation, commits, normal pushes, and the closing pull request carry the
+settled mode's authorization and need no repeated prompt. Before any branch
+checkout, including `gh issue develop --checkout`, require
+`git status --porcelain` to be empty. If it is dirty, never stash, move, or
+commit ambient work; set the plan `blocked` and name the dirty paths, or use an
+authorized clean worktree.
+Immediately after setting the plan `ongoing`, every `gh issue develop` call uses
+`--repo`; the manager reuses a linked branch or creates one with
+`--base <default> --checkout`, then re-lists and recovers after failure.
+Implementation stops when no linked branch can be verified; there is no local
+fallback. After the checks policy passes, the manager asks immediately before
+merge. Without a fresh `Merge now` answer, it leaves the pull request and issue
+open. `plan.mjs archive` verifies the latest trusted code-review result and
+merged closing pull request after landing.
 
 Every Steps row carries an `Effect` of exactly
 `local|probe|production_access|publish|push|release|deploy`. A step whose
 `Effect` is not `local` requires an in-session `ask` confirmation immediately
-before it runs; when `ask` is unavailable the step is set `blocked` with
-`blocked_reason` naming the unconfirmed effect. Persisted effects record intent
-only.
-
-A plan carrying a `Plan-run:` line is a v1 plan: render it, never parse or
-migrate it, and finish it by hand by moving the file byte-unchanged to
-`docs/plans/finished/<YYYY-MM-DD>-<slug>.md` with a `## Retirement` section
-appended. The complete contract lives in `docs/plans/AGENTS.md`;
-`docs/plans/CLAUDE.md` contains only `@AGENTS.md`.
+before it runs; when `ask` is unavailable the step is set `blocked` and the plan
+reason becomes the first `## Open questions` line, `Blocked: <reason>`.
+Persisted effects record intent only. Routine issue publication and landing
+actions are outside the Steps table.
+
+Render a plan body verbatim only when the user names that plan and asks to see it. After a write, report the one-line header strip and the changed lines only; a write never re-renders the body.
+
+No plan markdown is tracked. The pre-GitHub records under
+`docs/plans/finished/` were deleted; `git log -- docs/plans/finished/` recovers
+them as history, and no lifecycle command restores them. The complete contract
+lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it and `docs/CLAUDE.md`
+contains only `@AGENTS.md`.
 
 Distinct from per-tool **Open Concerns** sections (wait-on-upstream
 blockers tied to a vendor shipping a fix — these live inside the per-tool

package/README.md

@@ -5,15 +5,17 @@ Truth (SoT)** directories deploy to each tool's user-config location. Clone
 once to get a consistent AI-assisted environment on supported Linux, macOS,
 and Windows machines. Tuned for **token efficiency without sacrificing quality**.
 
-Supported tools: **Claude Code**, **Codex**, and any agent consuming
-[agentskills.io](https://agentskills.io) universal skills.
+Supported harnesses: **Claude Code**, **Codex**, and **Oh My Pi (`omp`)**.
+The kit also deploys [agentskills.io](https://agentskills.io) universal skills.
 
 ## Quick start
 
 ```bash
 git clone https://github.com/DocksDocks/public.git ~/projects/public
 cd ~/projects/public
-./docks-kit sync            # deploy everything (Claude Code + Codex + skills)
+./docks-kit harnesses       # choose this machine's flag-less sync harnesses
+./docks-kit sync            # deploy this machine's harness selection
+./docks-kit sync omp        # deploy omp explicitly
 ./docks-kit status          # doctor view: drift, toolchain, plugins, skills
 ```
 
@@ -41,15 +43,16 @@ PowerShell.
 ## CLI
 
 ```text
-docks-kit sync [claude] [codex] [agents]   deploy the SoT (default: all three)
-docks-kit update [--no-sync]               self-update the kit (autodetects checkout vs global install), then sync
-docks-kit model <claude|codex> [value]     get/set the DEPLOYED model (TTY picker)
-docks-kit models [claude|codex]            model catalogs (`--json`)
-docks-kit toolchain [check|ensure <tool>]  verified-version floors for external tools
-docks-kit status [--json]                  deployed-vs-SoT drift + toolchain + counts
-docks-kit plugins list [--json]            enabledPlugins tri-state vs installed
-docks-kit skills list [--json]             universal skills vs manifest
-docks-kit docs [topic]                     self-documentation (9 topics)
+docks-kit sync [claude] [codex] [agents] [omp]  deploy explicit targets or the machine selection
+docks-kit harnesses                             view or change this machine's selection
+docks-kit update [--no-sync]                    self-update the kit (autodetects checkout vs global install), then sync
+docks-kit model <claude|codex> [value]          get/set the DEPLOYED model (TTY picker)
+docks-kit models [claude|codex]                 model catalogs (`--json`)
+docks-kit toolchain [check|ensure <tool>]       verified-version floors for external tools
+docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
+docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed
+docks-kit skills list [--json]                  universal skills vs manifest
+docks-kit docs [topic]                          self-documentation (9 topics)
 --help --version --wizard --completions    built-in
 ```
 
@@ -87,6 +90,9 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 - **Additive by default** — user-only settings keys, plugins, and skills
   survive a plain sync. Reconciliation toward the SoT is explicit
   (`--reconcile` / `--prune`).
+- **Per-machine selection** — `~/.docks-kit/state.json` drives a flag-less sync.
+  A missing file selects Claude Code, Codex, and universal skills. It does not
+  select omp. Use `docks-kit harnesses` to view or change the selection.
 - **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
 - **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
   floors for external tools (bun, bwrap, …). `docks-kit toolchain check` prints
@@ -106,6 +112,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 |------|---------|
 | `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
 | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
+| `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, mcp.json, intercom.json) |
 | `SoT/.agents/` | Universal-skill manifest |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Verified-version floors |
@@ -114,7 +121,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `cli/` | docks-kit CLI (Effect 4 RC on Bun) + bundled docs topics |
 | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
 | `install.sh` / `install.ps1` | POSIX and Windows global installers |
-| `docs/plans/` | Multi-commit work-item plans |
+| `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
 | `AGENTS.md` / `CLAUDE.md` | Agent-facing engineering rules / Claude Code specifics |
 
 ## Platform support
@@ -136,7 +143,7 @@ Tagging `cli-v*` builds six standalone binaries for Linux, macOS, and Windows
 on x64 and arm64. The workflow attaches them plus `SHA256SUMS` to the GitHub
 release. npm publishes the exact package tarball through trusted publishing
 with OIDC provenance.
-Package `docks-kit` 0.15.5 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.16.0 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/sync-layers.md

@@ -1,7 +1,9 @@
 # Sync layers
 
-`docks-kit sync [claude] [codex] [agents]` — targets are positional words;
-no target means all three.
+`docks-kit sync [claude] [codex] [agents] [omp]` — targets are positional
+words; no target means this machine's harness selection in
+`~/.docks-kit/state.json`. The default is `claude codex agents`, and
+`docks-kit harnesses` changes it.
 
 ## claude (→ ~/.claude, ~/.claude.json, shell rc)
 
@@ -46,6 +48,34 @@ and `codex plugin add` refresh.
 `npx skills add` per missing manifest slug, Claude symlink healing, and the
 kit-managed snapshot that `--prune` reconciles against.
 
+## omp (→ resolved agent dir, intercom root)
+
+AGENTS.md, mcp.json, and intercom config.json are whole-file deploys;
+config.yml is deep-merged (SoT keys win, mapping nodes merge, deployed-only
+keys survive, stale slash-bearing `retry.fallbackChains` wildcards pruned).
+Directories are mode 0700 and files mode 0600. Then the `docks` marketplace is
+registered, `docks@docks` and `plan-lifecycle@docks` are installed or upgraded
+through `omp plugin`, and `pi-intercom` is installed at its
+`SoT/toolchain.json` pin. Inventory comes from `omp plugin list --json`, where a
+marketplace row counts as installed only when its `scope` is `user`, so a repeat
+run is a no-op and a project-only row still installs. When just the legacy
+config-root registry lists `docks`, omp copies it forward itself: the sync runs
+`marketplace update`, or the read-only `marketplace list` under
+`--skip-plugin-refresh`, which keeps installs but fetches nothing. A dry run
+invokes no omp subcommand.
+
+Paths mirror upstream `dirs.ts` `DirResolver`, resolved from the environment
+plus directory probes, so a dry run still runs no omp subcommand. The agent
+directory is `<config root>/agent`, where the config root is
+`~/<PI_CONFIG_DIR or .omp>` plus `profiles/<name>` under an active profile
+(`OMP_PROFILE`, else legacy `PI_PROFILE`). For the default profile only,
+`PI_CODING_AGENT_DIR` replaces the agent directory outright. The agent
+directory never moves under XDG. Only the data root that holds
+`marketplaces.json` does: on Linux and macOS, with no agent-dir override
+active, an existing `$XDG_DATA_HOME/omp` (or `$XDG_DATA_HOME/omp/profiles/<name>`
+for a named profile) is adopted. The intercom file keeps pi-intercom's own
+root: `$PI_CODING_AGENT_DIR/intercom`, else `~/.pi/agent/intercom`.
+
 ## Reconcile flags
 
 - `--reconcile` — settings layer: SoT-declared keys win; user-only preserved.

package/cli/src/commands/harnesses.ts

@@ -0,0 +1,64 @@
+import { Command, Prompt } from "effect/unstable/cli"
+import { Console, Effect } from "effect"
+import { bail } from "../engine"
+import {
+  engineHome,
+  HARNESSES,
+  harnessStateFile,
+  LEGACY_SELECTION,
+  readHarnessSelection,
+  writeHarnessSelection,
+  type Harness
+} from "../engine-native/harnesses"
+
+const DESCRIPTIONS: Record<Harness, string> = {
+  claude: "Claude Code user configuration",
+  codex: "Codex user configuration",
+  agents: "universal agent skills",
+  omp: "Oh My Pi user configuration"
+}
+
+export const harnessesCommand = Command.make(
+  "harnesses",
+  {},
+  () =>
+    Effect.gen(function* () {
+      const home = engineHome(process.env)
+      const stored = yield* Effect.sync(() => readHarnessSelection(home))
+      const selection = stored ?? LEGACY_SELECTION
+      const names = selection.join(", ")
+
+      if (stored === undefined) {
+        yield* Console.log(
+          `Harness selection: ${names} (no selection is stored yet; the legacy default applies)`
+        )
+      } else {
+        yield* Console.log(`Harness selection: ${names}`)
+      }
+
+      if (!process.stdout.isTTY) return
+
+      const answer = yield* Prompt.multiSelect({
+        message: "Choose the harnesses for a flag-less docks-kit sync",
+        choices: HARNESSES.map((harness) => ({
+          title: harness,
+          value: harness,
+          description: DESCRIPTIONS[harness],
+          selected: selection.includes(harness)
+        }))
+      })
+
+      if (answer.length === 0) {
+        return yield* bail("Select at least one harness. The stored selection was not changed.")
+      }
+
+      yield* Effect.sync(() => writeHarnessSelection(home, answer))
+      yield* Console.log(
+        `Saved harness selection: ${answer.join(", ")} (${harnessStateFile(home)})`
+      )
+    })
+).pipe(
+  Command.withDescription(
+    "Choose the harness selection that drives a flag-less docks-kit sync."
+  )
+)

package/cli/src/commands/sync.ts

@@ -29,11 +29,11 @@ const updateNudge = (logger: Logger): void => {
   }
 }
 
-const VALID_TARGETS = ["claude", "codex", "agents"]
+const VALID_TARGETS = ["claude", "codex", "agents", "omp"]
 
 const targets = Argument.variadic(
   Argument.string("target").pipe(
-    Argument.withDescription("Sync targets: claude, codex, agents (default: all three)")
+    Argument.withDescription("Sync targets: claude, codex, agents, omp (default: selected harnesses)")
   )
 )
 

package/cli/src/engine-native/deps.ts

@@ -23,6 +23,7 @@ export type ToolId =
   | "npx"
   | "claude"
   | "codex"
+  | "omp"
   | "bun"
   | "bwrap"
   | "ffplay"
@@ -181,6 +182,12 @@ export const DEPENDENCIES: Record<ToolId, DependencySpec> = {
     (pf = rawPlatform()) => hostOs(platformName(pf)).installHint("codex"),
     { version: versionProbe("codex") }
   ),
+  omp: spec(
+    "omp",
+    "optional",
+    () => "install omp from https://github.com/can1357/oh-my-pi (an existing install self-updates with `omp update`)",
+    { version: versionProbe("omp", ["--version"], (out) => out.trim().replace(/^omp[/v]/, "")) }
+  ),
   bun: spec(
     "bun",
     "optional",

package/cli/src/engine-native/harnesses.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-machine harness selection at ~/.docks-kit/state.json. The selection keeps
+ * the omp harness opt-in. A missing or unreadable state file is represented by
+ * undefined so callers resolve it to LEGACY_SELECTION and existing machines
+ * keep today's behavior.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+
+import { p } from "./exec"
+
+export type Harness = "claude" | "codex" | "agents" | "omp"
+
+export const HARNESSES: ReadonlyArray<Harness> = ["claude", "codex", "agents", "omp"]
+export const LEGACY_SELECTION: ReadonlyArray<Harness> = ["claude", "codex", "agents"]
+
+function isHarness(value: unknown): value is Harness {
+  return value === "claude" || value === "codex" || value === "agents" || value === "omp"
+}
+
+function normalizeHarnesses(selection: ReadonlyArray<unknown>): Array<Harness> {
+  const selected = new Set<Harness>()
+  for (const value of selection) {
+    if (isHarness(value)) selected.add(value)
+  }
+  return HARNESSES.filter((harness) => selected.has(harness))
+}
+
+/** Resolve the engine home root from HOME with the platform home as fallback. */
+export function engineHome(env: NodeJS.ProcessEnv = process.env): string {
+  const home = env["HOME"]
+  return home !== undefined && home !== "" ? home : homedir()
+}
+
+export function harnessStateFile(home: string): string {
+  return p(home, ".docks-kit", "state.json")
+}
+
+/** Read valid local state without allowing corruption to make sync unusable. */
+export function readHarnessSelection(home: string): ReadonlyArray<Harness> | undefined {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(readFileSync(harnessStateFile(home), "utf8")) as unknown
+  } catch {
+    return undefined
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined
+  const state = parsed as Record<string, unknown>
+  if (state["version"] !== 1 || !Array.isArray(state["harnesses"])) return undefined
+
+  const selection = normalizeHarnesses(state["harnesses"])
+  return selection.length > 0 ? selection : undefined
+}
+
+export function writeHarnessSelection(home: string, selection: ReadonlyArray<Harness>): void {
+  if (selection.length === 0) {
+    throw new Error("Cannot write an empty harness selection because sync would become a no-op")
+  }
+
+  const harnesses = normalizeHarnesses(selection)
+  if (harnesses.length === 0) {
+    throw new Error("Harness selection must contain at least one known harness name")
+  }
+
+  const directory = p(home, ".docks-kit")
+  const file = harnessStateFile(home)
+  const text = `${JSON.stringify({ version: 1, harnesses }, null, 2)}\n`
+  // `mode` applies only when mkdir creates the path, so an existing permissive
+  // ~/.docks-kit would keep its mode.
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  chmodSync(directory, 0o700)
+  writeFileSync(file, text, { mode: 0o600 })
+  chmodSync(file, 0o600)
+}