docks-kit 0.22.13 → 0.22.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/AGENTS.md +97 -83
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +12 -7
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +27 -17
  7. package/cli/docs/omp-models.md +91 -70
  8. package/cli/docs/overview.md +1 -1
  9. package/cli/docs/platforms.md +4 -2
  10. package/cli/docs/plugins.md +8 -5
  11. package/cli/docs/sync-layers.md +6 -4
  12. package/cli/docs/toolchain.md +24 -14
  13. package/cli/src/argv.ts +7 -4
  14. package/cli/src/argvValidate.ts +2 -16
  15. package/cli/src/commands/docs.ts +1 -1
  16. package/cli/src/commands/omp.ts +81 -88
  17. package/cli/src/commands/sync.ts +6 -6
  18. package/cli/src/commands/tidy.ts +83 -26
  19. package/cli/src/engine-native/DESIGN.md +93 -56
  20. package/cli/src/engine-native/atomicWrite.ts +168 -8
  21. package/cli/src/engine-native/codexConfig.ts +2 -6
  22. package/cli/src/engine-native/codexPlugins.ts +1 -1
  23. package/cli/src/engine-native/codexSync.ts +137 -26
  24. package/cli/src/engine-native/codexToml.ts +4 -86
  25. package/cli/src/engine-native/deps.ts +51 -51
  26. package/cli/src/engine-native/exec.ts +3 -0
  27. package/cli/src/engine-native/harnesses.ts +5 -11
  28. package/cli/src/engine-native/index.ts +1 -1
  29. package/cli/src/engine-native/kitDb.ts +7 -7
  30. package/cli/src/engine-native/kitLock.ts +121 -0
  31. package/cli/src/engine-native/modes.ts +49 -31
  32. package/cli/src/engine-native/ompChild.ts +26 -0
  33. package/cli/src/engine-native/ompFastMode.ts +14 -7
  34. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  35. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  36. package/cli/src/engine-native/ompOverlay.ts +23 -69
  37. package/cli/src/engine-native/ompPlugins.ts +23 -14
  38. package/cli/src/engine-native/ompRemovals.ts +97 -30
  39. package/cli/src/engine-native/ompSync.ts +66 -32
  40. package/cli/src/engine-native/os/targets.ts +16 -4
  41. package/cli/src/engine-native/os/types.ts +1 -1
  42. package/cli/src/engine-native/parseArgs.ts +27 -17
  43. package/cli/src/engine-native/processes.ts +16 -0
  44. package/cli/src/engine-native/scratch.ts +18 -0
  45. package/cli/src/engine-native/sharedTypes.d.ts +0 -2
  46. package/cli/src/engine-native/skillsInstall.ts +27 -2
  47. package/cli/src/engine-native/skillsPrune.ts +51 -49
  48. package/cli/src/engine-native/skillsRecords.ts +138 -0
  49. package/cli/src/engine-native/skillsSync.ts +16 -13
  50. package/cli/src/engine-native/syncDispatch.ts +186 -4
  51. package/cli/src/engine-native/tidy.ts +102 -119
  52. package/cli/src/engine-native/tomlLines.ts +92 -0
  53. package/cli/src/generated/sotPayload.ts +5 -5
  54. package/cli/src/main.ts +5 -30
  55. package/cli/src/manifests.ts +24 -4
  56. package/package.json +2 -2
  57. package/cli/src/engine-native/tidyLock.ts +0 -163
package/AGENTS.md CHANGED
@@ -1,6 +1,9 @@
1
1
  # AGENTS.md
2
2
 
3
- Canonical instructions for coding agents working on this project. Compatible with OpenAI Codex, Claude Code (via `@AGENTS.md` import in `CLAUDE.md`), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
3
+ Canonical instructions for coding agents working on this project. Compatible with OpenAI Codex, Claude Code (native AGENTS.md support, v2.1.277+), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
4
+
5
+ Pointers here name concepts, not coordinates — if a path or symbol moved,
6
+ trust the stated purpose and re-locate it (grep the symbol) before acting.
4
7
 
5
8
  ## Repository purpose
6
9
 
@@ -15,7 +18,7 @@ preserving rigorous output. When you add or edit anything, ask: *does this
15
18
  change reduce tokens without weakening correctness?*
16
19
 
17
20
  Tool-specific instructions live alongside this file:
18
- - **`CLAUDE.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns.
21
+ - **`.claude/rules/claude-code.md`** — Claude Code SoT (`SoT/.claude/`), env vars, hooks, plugins, status line, session management, permission mode, open concerns. Its `paths:` frontmatter scopes it: Claude Code loads it when it reads or edits a matching file, and any agent can open it by path.
19
22
  - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
20
23
  - omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
21
24
 
@@ -24,100 +27,95 @@ docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
24
27
  arm64, and Windows x64. Hosts outside this matrix fail before either
25
28
  launcher can fall back to Bun source.
26
29
 
30
+ ## Context tree
31
+
32
+ Per-folder conventions live in nested `AGENTS.md` nodes. Claude Code loads a
33
+ folder's AGENTS.md when it reads a file there; Codex loads only the nodes from
34
+ the root down to its working directory, so open the node for the folder you
35
+ edit from this table. Do not add CLAUDE.md files: a CLAUDE.md without an
36
+ `@AGENTS.md` import makes Claude read it instead of AGENTS.md. Edit the node,
37
+ not this list, when a folder's rules change. `context-tree audit` checks this
38
+ table against the AGENTS.md files on disk.
39
+
40
+ | Node | Governs |
41
+ |---|---|
42
+ | `docs/AGENTS.md` | Plan-record routing to `docs/PLAN.md` |
43
+ | `cli/AGENTS.md` | Effect CLI, EngineNative sync engine, bundled docs topics, build scripts, unit and golden suites |
44
+ | `.agents/skills/AGENTS.md` | Project skills, the `.claude/skills/` symlinks, and the wrapper agents in `.claude/agents/` and `.codex/agents/`; Claude Code reads nothing under `.agents/`, so open this node from this table |
45
+
27
46
  ## Repository layout (cross-cutting)
28
47
 
29
48
  | Path | Purpose |
30
49
  |------|---------|
31
- | `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`, and the mismatch warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
32
- | `cli/build-binaries.sh` | Compiles the four release binaries (`docks-kit-linux-x64`, `docks-kit-linux-arm64`, `docks-kit-darwin-arm64`, `docks-kit-windows-x64.exe`). It checksums the four known artifact names rather than globbing `docks-kit-*`, so a packed `docks-kit-<version>.tgz` is never attested as a release binary. It stamps `cli/dist/VERSION` only when the directory holds one version, and on the next build discards every artifact that stamp attributes to a different version, because a launcher refuses to run one and keeping it makes `SHA256SUMS` span two versions. An artifact with no stamp has unknown provenance and may be a hand-built or downloaded recovery binary, so the script keeps it and warns; `--prune` discards those too. Nothing here removes an artifact the stamp vouches for. |
33
- | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
34
- | `cli/src/engine-native/ompSync.ts` | omp sync orchestration and summary |
35
- | `cli/src/commands/omp.ts` | `docks-kit omp` session launcher: rejects model-selecting forwarded flags, checks the free catalog of each candidate profile, renders the free-model run overlay, and starts `omp launch` |
36
- | `cli/src/checklistPrompt.ts` / `cli/src/terminalCells.ts` | Shared terminal checklist prompt on Effect's `Prompt.Custom`: items, a Save row, key hints, an ASCII fallback, and NO_COLOR; `docks-kit harnesses` uses it. `terminalCells.ts` measures text in terminal cells and rows from the pinned Unicode 18.0.0 East Asian Width table; derive the table again from a newer `EastAsianWidth.txt` the same way its header says |
37
- | `cli/src/engine-native/ompOverlay.ts` | Free-model overlay render, omp argv and child environment, plus catalog parse and thinking-ceiling helpers |
38
- | `cli/src/engine-native/scratch.ts` / `cli/src/commands/scratch.ts` | `docks-kit scratch new\|remove`: private agent temporary directories under `~/.cache/docks-kit/scratch/`; removal accepts only a real path strictly inside the scratch root, the system temporary directory, or `/var/tmp` |
39
- | `cli/src/engine-native/tidy.ts` / `tidyReport.ts` / `cli/src/commands/tidy.ts` | `docks-kit tidy [--apply] [--repo <path>] [--report]`: plan and apply the safe leftover sweep (merged idle worktrees and their containers, orphaned processes in agent directories, idle scratch); Docker calls run only against a verified local endpoint (`unix:///…` or `npipe:////./pipe/…`); the report is read-only |
40
- | `cli/src/engine-native/ompKitPlugin.ts` | Materializes the `SoT/.omp/plugin/` payload to `~/.docks-kit/omp-plugin` with the kit version; `ompPlugins.ts syncPlugins` links it |
41
- | `cli/src/engine-native/<axis>.ts` | One change axis per file: `codexConfig`/`codexHooks`/`codexPlugins`/`codexStatus`, `claudeSettings`/`claudeRemovals`/`claudePluginPasses`/`claudeOptionalPlugins`/`claudeLsp`, `parseModifiers`/`parseHelp`, `ompFileDeploy`/`ompMarketplace`/`ompPlugins`, `skillsManifest`/`skillsLinks`/`skillsInstall`/`skillsPrune`, `engineCtx`/`syncConcurrency`/`syncDispatch`; orchestrators keep prior exports |
42
- | `cli/src/engine-native/sharedTypes.d.ts` | Single definition per shared shape (manifest records, settings edits, omp session model, scalar modifier flags, resolved model catalog) |
43
- | `cli/src/engine-native/kitDb.ts` | Only opener of the SQLite store `~/.docks-kit/kit.db`: append-only migrations, one-time `state.json` import, TTL cache |
44
- | `cli/src/engine-native/liveModels.ts` | Live model list per enabled harness (Anthropic API via Claude Code login, Codex model cache, `omp models --json`) merged over `SoT/models.json` |
50
+ | `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` and no file under `cli/src/` or `cli/docs/` is newer than the binary. Otherwise it runs Bun-from-source and auto-installs Bun plus `node_modules`, and the mismatch or newer-source warning names the rebuild remedy. A launcher never deletes a binary: on a host without Bun it is the only remaining recovery path. Hosts outside the support matrix fail before source fallback. The standalone platform release binary provides no-Bun recovery. |
45
51
  | `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
46
- | `cli/test/fixtures/` | Golden fixtures: `home-fresh`, `home-drift`, `home-invalid-json`, `codex-toml`, `statusline` |
47
52
  | `cli/` | Effect 4 CLI + bundled docs topics |
48
53
  | `SoT/models.json` | Curated Claude and Codex model overlay: aliases and notes always apply; id rows are the fallback when a harness live list is unavailable |
49
54
  | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
50
55
  | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
51
- | `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, and `intercom.json` |
56
+ | `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
52
57
  | `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
53
58
  | `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
54
59
  | `README.md` | Front door |
55
60
  | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
56
61
  | `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. |
57
62
  | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
58
- | `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`. |
59
- | `CLAUDE.md` | Claude-specific instructions; imports this `AGENTS.md` |
63
+ | `docs/PLAN.md` | Plan record standard. The plan record is a GitHub issue; no plan markdown is tracked. `docs/AGENTS.md` routes to it. |
64
+ | `.claude/rules/claude-code.md` | Claude Code-only instructions; path-scoped by its `paths:` frontmatter |
65
+ | `.claude/settings.json` | Project Claude Code settings. It holds only `claudeMdExcludes`, so Claude Code does not load the SoT prompt payloads or the test fixtures as project instructions; sync never reads or writes it |
60
66
  | `AGENTS.md` | This file — tool-agnostic instructions |
61
67
 
68
+ Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
69
+
62
70
  Codex SoT notes:
63
71
  - `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
64
72
  - `SoT/.codex/config.toml` pins Codex to `model = "gpt-6.1-sol"`, sets normal and plan reasoning to `high` with concise summaries, and sets `model_verbosity = "low"`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the two Docks plugins `docks@docks` and `plan-lifecycle@docks` (the shared plan lifecycle).
65
73
  - `SoT/.codex/config.toml` does not set `personality`. Codex 0.159.0 deprecated the key, and `friendly` and `pragmatic` no longer select a style. `codexConfig.ts removeRetiredTopLevelSettings, retired top-level key prune` removes the retired `personality = "pragmatic"` line from a deployed `config.toml` on every sync. A different user-set value survives.
66
74
  - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved. Codex applies the strictest matching rule across all files, so a user allow rule cannot loosen a kit `forbidden` or `prompt` rule. Because the strictest rule wins, a narrow allow cannot carve an exception out of a broader prompt prefix, and a prefix rule cannot see an option after an operand. The guards therefore fail closed: every `rm`, `git rm`, `git worktree remove`, and `gio trash` prompts, and only macOS `trash` is allowed (owner decision). A `prompt` goes to `approvals_reviewer = "auto_review"`, a reviewer subagent, not always to a person. `docks.rules` carries the destructive-command guards (`docks-kit docs command-guards`); `cli/test/unit/codexSyncRules.test.ts` parses every one-line `prefix_rule`, alternatives lists and `justification` included, and asserts each guard's decision. Keep each rule on one line so that parser sees it.
75
+ - `codexSync.ts syncRules, kit rules manifest` records the sha256 of the kit bytes of each rules file that the kit deploys in `~/.codex/.kit-managed-rules`, in `<sha256> <file name>` lines. The manifest sits outside `rules/`, so Codex never reads it as a rule file. Sync writes each rules file through `atomicWrite.ts replaceFile`, so an interrupted write keeps the previous file. Codex loads only `*.rules` files, so it never loads the `*.tmp` sibling. Before the deploy, sync writes the manifest ahead. It keeps the recorded set of hashes of each name and adds the new kit hash of each shipped name. So a name whose kit bytes change has two lines. A sync that stops after a deploy thus leaves a record of the bytes that it wrote. A stale kit rules file keeps its old rules active. When the SoT drops a rules file, every sync therefore removes the deployed copy while its hash is in the recorded set of its name. A dropped file that the user edited stays, keeps its set, and gets a warning on each sync. Every recorded hash is a hash of kit bytes, so no record lets cleanup remove bytes that the user wrote. Cleanup reads and removes only recorded names that the SoT no longer ships. It never reads or removes a file that the SoT does not ship and no sync recorded, such as `default.rules`. Sync still deploys each name that the SoT ships over an existing file, recorded or not. It backs up a file that differs to `<name>.bak` and replaces it. After the deploy and the cleanup, the final manifest holds one line per shipped name, plus the set of each kept dropped name. Sync replaces the manifest through a temporary file and a rename, so an interrupted sync keeps the previous complete manifest. `--dry-run` prints `[dry-run] remove <file>` and writes nothing.
67
76
  - `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.
68
- - Codex `/import` can copy Claude hooks into `~/.codex/hooks.json`. `codexHooks.ts removeRetiredImportedHooks, legacy SessionStart cleanup` removes only recognized hooks from retired docks-kit Claude settings, backs up a changed file, and preserves user-authored hooks. Codex `/import` (codex-rs external-agent-migration `hooks_cla.rs`) skips a handler with keys outside `type`/`command`/`timeout`/`timeoutSec`/`statusMessage`/`async`, and it skips `async: true` handlers. Thus it imports neither the kit's exec-form (`args`) SessionStart handler nor its async Notification handler.
77
+ - Codex `/import` hook cleanup (`codexHooks.ts`): `cli/AGENTS.md`.
69
78
  - Codex limits the initial skill list to 2% of the model context and shortens descriptions first; it still reads a selected skill's full `SKILL.md`. Additive sync preserves user-added plugins, so their skill count and malformed cached `SKILL.md` files remain plugin-owned. Sync never patches a plugin cache in place.
70
79
  - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
71
80
  - 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.
72
81
 
73
82
  - 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.
74
83
  - 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: opus` after the settings merge. `opus` is the alias, not a pinned id: the `minimumVersion` floor of 2.1.280 makes Claude Code resolve it to Opus 5.5, the default Opus from that release, instead of capping at Opus 5 under the former 2.1.219 floor. Keeping the alias tracks the next Opus release without a kit change and stays portable across providers. The floor also subsumes Fable 5.1's 2.1.257 requirement.
75
- - Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeRemovals.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries (`Read`, `Glob`, `Grep`, and `WebSearch`) plus the working-directory edit rule `Edit(./)`. Broad shell allow rules are not restored, because an allow rule resolves before Claude Code's read-only command analyzer and the auto-mode classifier. `autoMemoryEnabled` and `autoDreamEnabled` are both `false`.
84
+ - Claude permission rules are pruned, not host-scoped. The kit deploys its `PowerShell(...)` deny and ask rules on every host, because Claude Code leaves the PowerShell tool opt-in off Windows rather than unavailable, and a host that enables it must already carry the guards. `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory` lists the rules the kit no longer ships. `claudeRemovals.ts syncRemovals, retired-permission pass` force-prunes those exact strings from the kit-managed `~/.claude/settings.json` on every sync, because `settings.ts mergeSettings, permission-array union` would otherwise keep a dropped rule forever. A different user-authored rule survives. To restore an exact retired rule for one checkout, put it in that checkout's `.claude/settings.local.json`. Claude Code resolves that file against the working directory and merges it over user settings. Sync never reads or writes the checkout-local file. Claude Code has no user-scope local settings file. For a machine-wide restoration, add the rule to `SoT/.claude/settings.json`. At the same time, remove the exact string from `claudeRetired.ts RETIRED_PERMISSION_RULES, exact retired-rule inventory`. `permissions.allow` holds four read-only entries, `Read`, `Glob`, `Grep`, and `WebSearch`, the working-directory edit rule `Edit(./)`, and two narrow trash allows, `Bash(gio trash -- *)` and `Bash(trash *)`. Broad shell allow rules are not restored, because an allow rule resolves before Claude Code's read-only command analyzer and the auto-mode classifier. `autoMemoryEnabled` and `autoDreamEnabled` are both `false`.
76
85
 
77
86
  omp SoT notes:
78
87
  - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`.
79
88
  - `SoT/.omp/intercom.json` deploys to `$PI_CODING_AGENT_DIR/intercom/config.json`. The default root is `~/.pi/agent`. Under a named omp profile (`OMP_PROFILE` or `PI_PROFILE`), it deploys to `<profile agentDir>/intercom/config.json`, because omp exports `PI_CODING_AGENT_DIR` as the profile agent directory.
80
89
  - `ompFileDeploy.ts syncMergedYaml` deep-merges `config.yml` through `ompYaml.ts mergeOmpConfig` and `models.yml` through `mergeOmpModels`. Both wrap one generic mapping merge; only the config wrapper prunes stale `retry.fallbackChains` wildcards and merges `bash.patterns`.
81
- - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. A `$` or a backtick anywhere after `git push` in the same command is a deny, not a prompt (0.22.5, #120). A variable can expand to a `+` refspec or `--force`, and the matcher reads the text before the shell expands it. The agent reads the refusal and writes the ref literally, so no person is asked. The two rules are `*git push *$*` and ``*git push *`*``. Their leading `*` keeps a shell keyword such as `do`, a wrapper such as `env`, or a path before `git` from hiding the push. By owner decision (0.22.8, #126), the kit ships no omp prompt rule: `bash.patterns` holds only the denies plus the `trash *` allow, so every command that no deny matches runs without a question, in subagents too. Since 0.20.9 this run-without-question behavior covers a non-denied `rm`, `git rm`, `git worktree remove`, `gio trash`, and `docks-kit scratch remove`. Since 0.22.8 it also covers `git clean`, `git reset --hard`, a hook skip, and every `git push` that no deny matches. The force-push denies match only `git push --force` or `-f` directly before `origin main` or `origin master`, so another spelling, such as `git push origin main --force`, runs. A prompt rule that the user adds survives sync and still asks. `SoT/.omp/AGENTS.md` carries the agent rules for these commands, and it tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. Claude Code `permissions.ask` and Codex `docks.rules` keep their ask tiers. The list order is deny, then `trash *`. omp takes the first match. `ompYaml.ts mergeBashPatterns, grouped rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 18.11.1's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
90
+ - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp's `CRITICAL_BASH_PATTERNS` check returns a bare safety override before a matching prompt rule, and omp's default `tools.approvalMode: yolo` ignores a bare override, so a prompt on a critical command becomes an allow, in subagents too (`omp://approval-mode.md`). Every `rm` shape that check can flag is therefore a deny: recursive `rm`, `sudo` anywhere before `rm` (also by path), any `rm` with an `r` or `f` option before an absolute path, and `--no-preserve-root`. By owner decision (0.20.9), the recursive-`rm` deny also covers any prefix (a `* rm ` copy of each bare cluster rule, so `env X=1 rm -rf b`, `xargs rm -rf`, `find . -exec rm -rf {} +`, and `git rm -r dir` are denied) and the `-ri`, `-ir`, `-Ri`, and `-iR` clusters for bare `rm`, `*/rm`, and `* rm`. By owner decision (0.21.0), 17 more denies cover bulk removal that can empty the home directory: `find -delete` (bare, `*/find`, `* find`), `-exec`, `-execdir`, `-ok`, and `-okdir` with `rm` or `*/rm`, and `xargs rm` in six shapes. No glob can express "inside the temporary directory", so `docks-kit scratch remove` checks that path in code. A `$` or a backtick anywhere after `git push` in the same command is a deny, not a prompt (0.22.5, #120). A variable can expand to a `+` refspec or `--force`, and the matcher reads the text before the shell expands it. The agent reads the refusal and writes the ref literally, so no person is asked. The two rules are `*git push *$*` and ``*git push *`*``. Their leading `*` keeps a shell keyword such as `do`, a wrapper such as `env`, or a path before `git` from hiding the push. By owner decision (0.22.8, #126), the kit ships no omp prompt rule: `bash.patterns` holds only the denies plus the `trash *` allow, so every command that no deny matches runs without a question, in subagents too. Since 0.20.9 this run-without-question behavior covers a non-denied `rm`, `git rm`, `git worktree remove`, and `gio trash`. Since 0.21.0 it also covers `docks-kit scratch remove`. Since 0.22.8 it also covers `git clean`, `git reset --hard`, a hook skip, and every `git push` that no deny matches. The force-push denies match only `git push --force` or `-f` directly before `origin main` or `origin master`, so another spelling, such as `git push origin main --force`, runs. A prompt rule that the user adds survives sync and still asks. `SoT/.omp/AGENTS.md` carries the agent rules for these commands, and it tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. Claude Code `permissions.ask` and Codex `docks.rules` keep their ask tiers. The list order is deny, then `trash *`. omp takes the first match. `ompYaml.ts mergeBashPatterns, grouped rule merge` keeps user rules and groups all rules as kit deny, user deny, user prompt, kit prompt, other user rules, kit allow, so a user deny or prompt precedes every kit allow. It treats a deployed rule equal to a kit rule (approval case-folded, `match` whitespace collapsed) as the kit copy, so a re-sync is a no-op. A rule the kit stops shipping stays as a user rule, so retire one through `ompRemovals.ts OMP_RETIRED_BASH_RULES`. `cli/test/lib/ompBashPatterns.ts` ports omp 18.17.0's matcher, critical patterns, and yolo resolution; `cli/test/unit/ompBashPatterns.test.ts` asserts each command's final outcome and the merge. omp subagents reject every `prompt`, and the `eval` tool stays unrestricted by owner decision.
82
91
  - `ompSync.ts` runs `ompRemovals.ts syncOmpRemovals, retired-key inventory` right after the config merge, and that pass force-prunes retired kit-owned keys from `~/.omp/agent/config.yml` on every sync, without `--reconcile`. The pass is required because `mergeOmpConfig` is additive, so removing a key from the SoT alone never removes it from a deployed file. A key retired with a recorded value is pruned only while the deployed value still matches that value, so a user edit survives; a key retired outright, such as `providers.webSearchOrder`, is pruned at any value. The same pass removes each `bash.patterns` rule listed in `OMP_RETIRED_BASH_RULES`: the 39 file-removal rules retired in 0.20.9, the four `git push` prompts for a `$` or backtick word that 0.22.5 replaced with denies, and the 492 prompt rules retired in 0.22.8 (`RETIRED_PROMPT_MATCHES`). It compares with the merge's kit-rule normalization (approval case-folded, `match` whitespace collapsed), so a user rule with a different `match` or `approval` survives.
83
- - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` remains `anthropic/claude-fable-5-1:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
84
- - `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.1-sol:high`. `task.enableEffort` is `false`: a caller `effort` outranks the role's level suffix, and `hi` maps to the top of the model ladder, so with the field on, `hi` spawns ran at `task.maxEffort` (`xhigh`) instead of the role level. With the field off, every spawn runs its role level, and `task.maxEffort` bounds only a per-call `model` with a `:level` suffix. `advisor` is `anthropic/claude-opus-5-5:medium` with an empty fallback chain, because a GPT-6 Sol advisor looped on repeated reads under an Opus 5.5 session. Never put any GPT model (`openai-codex/gpt-*`, including GPT-6.1 Sol and GPT-6 Astra) in the advisor role or chain; Astra also costs too much for this role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-terra:high`. Its retry fallback is `anthropic/claude-opus-5-5:high`. All four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `task.agentServiceTierOverrides` sets the same four agents to `inherit`, so they take the live tier of the main session for each provider. The user set the effort `high` and chose to follow the fast toggle (#134); the review benchmark of #130 chose the model. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. omp bundles the `reviewer` and `security-reviewer` agents, and the `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`. The `SoT/toolchain.json` omp floor is 18.4.4, the oldest release the kit tested with `gpt-6.1-sol`. That release lists and serves the model through the `openai-codex` provider. `cli/docs/omp-models.md` records the checks.
85
- - The seven Opus 5.5 roles (`default`, `slow`, `plan`, `designer`, `vision`, `task`, `advisor`) and the `smol`, `tiny`, `commit`, and `reviewer` retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-29 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. The `reviewer` row is the exception: it comes from a v5.0.1 capture read 2026-11-05, and it compares only with other v5.0.1 figures. Opus 5.5 max has the highest index in that topic, at 58. AA has measured speed and latency for Opus 5.5 max and every GPT-6.1 Sol level; GPT-6 Luna medium is the only unmeasured speed and latency row.
92
+ - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6-astra:xhigh`, and `modelTags.astra` is visible. Astra and Fable fall back to each other through concrete selectors. `modelRoles.fable` is `anthropic/claude-fable-5-2:medium`, with visible `modelTags.fable`. The hidden `switch_fable` role uses the same Fable selector and keeps an empty fallback chain.
93
+ - `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.1-sol:high`. The kit relies on omp's default `task.enableEffort: false`: a caller `effort` outranks the role's level suffix, and `hi` maps to the top of the model ladder, so with the field on, `hi` spawns ran at `task.maxEffort` (`xhigh`) instead of the role level. With the field off, every spawn runs its role level, and `task.maxEffort` bounds only a per-call `model` with a `:level` suffix. By owner decision (0.22.22), the omp advisor is removed: the SoT has no `advisor` block, `advisor` role, or `advisor` fallback chain. The plan-lifecycle verification loop replaces a second model on every turn. A session that runs `/advisor on` takes its advisor model from the `slow` role. `smol`, `commit`, and `tiny` use `openai-codex/gpt-6-luna`. The kit-defined hidden `reviewer` role is `openai-codex/gpt-6.1-terra:high`. Its retry fallback is `anthropic/claude-opus-5-5:high`. All four reviewer entries in `task.agentModelOverrides` point to `@reviewer`. `task.agentServiceTierOverrides` sets the same four agents to `inherit`, so they take the live tier of the main session for each provider. The user set the effort `high` and chose to follow the fast toggle (#134); the review benchmark of #130 chose the model. `ompOverlay.ts ROLE_ORDER, FALLBACK_ORDER` list `reviewer`, so a free session also replaces it. omp bundles the `reviewer` and `security-reviewer` agents, and the `plan-lifecycle` plugin ships `code-reviewer` and `plan-reviewer`. The `SoT/toolchain.json` omp floor is 18.4.4, the oldest release the kit tested with `gpt-6.1-sol`. That release lists and serves the model through the `openai-codex` provider. `cli/docs/omp-models.md` records the checks.
94
+ - The six Opus 5.5 roles (`default`, `slow`, `plan`, `designer`, `vision`, `task`) and the `smol`, `tiny`, `commit`, and `reviewer` retry chains use `anthropic/claude-opus-5-5` at the levels the role map records. `cli/docs/omp-models.md` carries the Artificial Analysis capture behind the role map, read 2026-09-29 at Intelligence Index v4.3.2 and Coding Agent Index v1.5 from the AA comparison-page metric tables. The `reviewer`, `fable`, and `switch_fable` rows are the exceptions: they come from v5.0.1 captures read 2026-11-05 (GPT-6.1 Terra) and 2026-11-12 (Fable 5.2), and they compare only with other v5.0.1 figures. Opus 5.5 max has the highest v4.3.2 index in that topic, at 58. AA has measured speed and latency for Opus 5.5 max and every GPT-6.1 Sol level; GPT-6 Luna medium is the only unmeasured speed and latency row.
86
95
  - `modelRoles.web` is `web/firecrawl` and `retry.fallbackChains.web` carries the explicit 20-entry provider order. The kit declares both keys because the legacy `providers.webSearchOrder` key is retired: omp expands it in memory into these two keys and then drops it, and never writes that expansion back to disk. An explicit chain replaces omp's built-in web order wholesale, so every entry left out is a provider omp never tries. The owner removed the seven entries that named older models (Gemini 2.5 Flash, Claude Haiku 4.5, GPT-5.6, GPT-5.5, and Grok 4.5); keep every other provider.
87
96
  - `SoT/.omp/models.yml` declares Astra's full `low, medium, high, xhigh, max` ladder with `defaultLevel: xhigh` as the worked provider ladder-override example. The temporary `anthropic.modelOverrides.claude-opus-5-5` block is gone, because the shared catalog now publishes the same limits, ladder, and prices. The removal switches omp from the block's `thinking.mode: effort` (a `budget_tokens` value per level from `ANTHROPIC_THINKING`, no effort value) to the catalog's `anthropic-adaptive` (adaptive thinking with the role's effort level); every kit Opus selector names its level, so the block's bare-selector `defaultLevel: high` is not needed. `ompRemovals.ts syncOmpModelRemovals, retired-block inventory` prunes it from `~/.omp/agent/models.yml` after the models merge, but only while the deployed block still equals the shipped one. `ompYaml.ts mergeOmpModels` preserves deployed-only keys in `~/.omp/agent/models.yml`, because a user file may carry provider credentials. Whole-file replacement is wrong.
88
97
  - `SoT/.omp/AGENTS.md` carries the rule `Please remove all mannered prose.` Anthropic's Fable 5.1 prompting guide documents mannered prose as a Fable 5.1 behavior and gives that sentence as its short-version fix: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
89
98
  - `cli/docs/omp-models.md` (topic `omp-models`) records the role map rationale and the Artificial Analysis snapshot behind it. Model choices change with published benchmarks, so update that topic in the same commit as a role change.
90
- - `SoT/.omp/config.yml` sets `compaction.thresholdTokens` to `-1`, omp's schema default sentinel selecting reserve-based behavior: the trigger becomes `contextWindow` minus `max(floor(contextWindow * 0.15), 16384)`, which is 231,200 on the 272,000-token Codex window and 850,000 on the 1,000,000-token Anthropic window. The key ships as `-1` rather than being deleted because `ompYaml.ts mergeOmpConfig` is additive, so removing a key from SoT never removes it from a deployed file. `cli/docs/omp-context.md` (topic `omp-context`) carries the derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
91
- - Sync registers the `docks` marketplace. It installs or upgrades `docks@docks` and `plan-lifecycle@docks` at user scope. omp deletes the previous plugin folder on upgrade, so running omp sessions lose that plugin's agents. A test on omp 18.16.0 showed that `/reload-plugins` brings the agents back, and that `skill://` resolves to the new folder (#139). When an upgrade changes a version, `ompPlugins.ts syncPlugins, upgrade log` warns, sets the `ompPluginUpgraded` next-step trigger, and writes one event file into `~/.cache/docks-kit/omp-plugin-upgrades/`. The warning and the next step give one rule: run `/reload-plugins` in each running session, then read each plugin skill again through `skill://`. Restart omp instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools, as the omp marketplace docs say. A version-changing upgrade does not set `ompRestart`. Each other plugin operation sets it: an install, a reinstall at the same version, an npm install, or a link. A changed kit plugin or config file also sets it. The restart next step then prints next to the upgrade rule. If the versions cannot be read after the upgrade, it warns once more, and each upgrade counts as a change to the version `unknown`. A failed write of the log only warns; it does not fail the sync. The log keeps the newest 100 event files; `cli/docs/sync-layers.md` gives the file format and the limits.
92
- - Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
99
+ - `SoT/.omp/config.yml` carries only keys whose value differs from the omp default. When a kit value equals the omp default, remove the key from the SoT. Add it with its shipped value to `ompRemovals.ts OMP_RETIRED_VALUES`, because `ompYaml.ts mergeOmpConfig` is additive and only that pass prunes the deployed copy. For example, the kit ships no `compaction.thresholdTokens`, and sync prunes a deployed `-1` and the former `231200` pin. `cli/docs/omp-context.md` (topic `omp-context`) carries the reserve-based derivation and the measured evidence, so update that topic in the same commit as any compaction-setting change.
93
100
  - Sync materializes the kit omp plugin `docks-kit-omp` from `SoT/.omp/plugin/` to `~/.docks-kit/omp-plugin` (`ompKitPlugin.ts syncKitPlugin`). It sets directories to 0700, files to 0600, and the `package.json` `version` to the kit version, and it removes stale files. It keeps no backups, because the directory is kit-owned. `ompPlugins.ts syncPlugins, kit plugin link` then runs `omp plugin link <dir>`. It skips the link when the `omp plugin list --json` npm row `docks-kit-omp` already has a `path` that resolves to that directory. `--skip-plugin-refresh` does not skip the link. The `hygiene.ts` extension registers `scratch_new`, `scratch_remove`, and `tidy_report`. It adds a reminder after each bash command that created a resource, and it checks at session stop that those resources are gone. At a main-session start, it claims `~/.cache/docks-kit/tidy.stamp.claim` and runs `docks-kit tidy --apply` in the background at most once per 12 hours. Every extension subprocess runs without a shell. The `pluginUpgrades.ts` extension reads the omp plugin upgrade log. In a tool result of each main session, it adds one reminder for the logged upgrades that the session did not get before. It names only the upgrades that finished after its omp process started. The reminder tells the agent to ask the user to run `/reload-plugins`. It then tells the agent to read each plugin skill again through `skill://` before it runs a skill script. It asks for a restart instead when an upgraded plugin ships hooks, extension modules, or non-MCP tools. omp imports extensions only at startup. An omp process that started before a sync deployed `pluginUpgrades.ts` did not load it, so its sessions get no reminder. The plugin also ships the `workspace-hygiene` skill and the `/cleanup` command. The plugin, the deployed rules, and the sweep call `docks-kit scratch` and `docks-kit tidy`. So a checkout sync must not run before the global `docks-kit` carries those commands.
94
101
  - `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
95
102
  - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp agent prompt, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH or a provider CLI such as `wrangler`, `vercel`, `kubectl`, or a remote Docker host) to targets named local, development, dev, test, homolog, homologation, staging, or preview, the plan-lifecycle non-production definition. A production cleanup needs an `ask` immediately before it, must be rare, and a `yolo` invocation does not answer that ask. Prompt rules cannot force an agent to ask, so this rule has no `bash.patterns` guard.
96
103
  - The omp CLI is upstream-owned. It updates through `omp update`, or through the external manager that owns the install, such as Tern or Nix. `omp update` refuses to run on an install that an external manager owns. Sync never installs or upgrades the CLI.
97
- - `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session. The overlay sets the 16 roles in `ompOverlay.ts ROLE_ORDER`, `judge` and `memory` included, to one free model, empties the 13 retry chains in `FALLBACK_ORDER`, and empties the chains keyed by the free model (bare, `off`, and every `THINKING_LADDER` level). Every other deployed chain stays as deployed. In particular, `modelRoles.web` and `retry.fallbackChains.web` keep the deployed web-search provider order. Thus a web search that falls through the `web/*` providers can reach the paid `openai-codex/gpt-6-luna` entry. It renders the overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600). `ompOverlay.ts overlayFileName` gives each distinct model-and-level combination its own file, and the digest covers the selector and both levels. omp can re-read the overlay during a live session, so a second launcher with another model or level must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again.
98
- - The launcher enforces the free model before omp starts. `omp.ts rejectedForwardedFlag` rejects a forwarded `--config`, `--model`, `--smol`, `--slow`, `--plan`, `--models`, `--provider`, `--prewalk-into`, or `--plan-yolo-into`, in both forms and also after a `--`, with exit 2 and a message that names the recoveries. `ompOverlay.ts buildOmpArgs` starts omp as `omp launch --config <overlay> --model <selector>[:<level>] [args...]`, so every forwarded word is message text, no omp subcommand runs through the launcher, and `--continue` or `--resume` keeps the free model. `ompOverlay.ts ompChildEnvironment` sets `PI_SMOL_MODEL`, `PI_SLOW_MODEL`, and `PI_PLAN_MODEL` to the free role values, and appends the overlay to `PI_CONFIG_FILES` so an `omp` that the bash tool of the session starts loads it too. The launcher prints one warning for each exported model variable that it replaces. In-session selection (`Alt+M`, `Alt+P`, `/switch`, `/model`, `/modelpreset`, `/resume`, a seance subagent), the `web` role, the model-kind roles `image`, `speech`, and `dictation`, and extensions and hooks stay outside the launcher. An `Alt+M` assignment of `default` writes `modelRoles.default` to the deployed `~/.omp/agent/config.yml`. `cli/docs/omp-models.md` lists these paths.
99
- - The session model persists per machine in `~/.docks-kit/kit.db` (table `omp_session`), next to the harness selection. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. Every launch, a plain launch included, runs `omp models --json` for the profile of the environment and `omp --profile <name> models --json` for each forwarded `--profile` value, and checks the remembered or default model against each live free catalog. When that model is not free in every one of these catalogs, the launcher stops with an error and does not start omp. `--model` and `--pick` resolve against the catalog of the last forwarded profile. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only catalog models at zero input and output cost with `pricingStatus` free or unknown.
100
- - `docks-kit omp --fast` toggles `tier.openai` in the deployed `~/.omp/agent/config.yml` between `priority` (omp's `/fast on` tier for OpenAI and OpenAI-Codex models) and `none`, prints the change, and exits. `ompFastMode.ts toggleOpenAiFast` edits only that key. `SoT/.omp/config.yml` does not declare `tier.openai`, so the additive merge keeps the toggled value across sync. The four review agents inherit the live tier of the main session, so they follow the toggle in a new session; a running session keeps its tier. `--fast` never changes the Anthropic tier, and sync sets the deployed `tier.anthropic` to the SoT value `none`, so each session starts with it. `/fast on` in an Opus session sets `anthropic: priority` for that session, and the reviewers and their Opus fallback inherit it; omp has no override that inherits only the OpenAI tier. There is no Ultrafast flag: omp ignores `ultrafast` for a Codex model whose catalog `serviceTiers` omits it, and the current GPT models omit it.
104
+ - omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
101
105
 
102
106
  For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
103
107
 
104
108
  ## Engineering rules
105
109
 
106
- - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
107
- - **Failed harness-CLI operations fail the sync.** A kit-managed marketplace or plugin command that exits non-zero is recorded through `failures.ts recordFailure` — it still warns in place, and `syncDispatch.ts engineSync, failure ledger` lists every entry under `--- Failures ---` after the summary, then returns exit 1. A skip is not a failure: a missing harness CLI, missing git, and a missing `SoT/toolchain.json` pin stay warn-only with exit 0; an unavailable plugin inventory warns without a ledger row and falls back to the full refresh, whose failed commands are recorded. `ompMarketplace.ts syncMarketplace, probe guard` returns before spawning so a host without omp never records one. Aggregate roll-up warnings (`N plugin operation(s) failed`) stay warns, because each counted site already records itself.
108
- - **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.
109
- - **Effect 4 CLI stack.** The CLI pins `effect@4.1.2` (including `effect/cli`), `@effect/platform-bun@4.1.2` (`BunServices.layer`, `BunRuntime.runMain`), and `@effect/platform-node-shared@4.1.2`. `effect/cli`, `effect/Terminal`, `BunRuntime`, and `BunServices` carry `@stability unstable`, so a minor Effect release can break them; 4.1.0 added a required `Terminal.size`. Tests run on `vitest@5.1.0`, a plain devDependency. No GitHub advisory affects vitest 5.1.0: 5.0.3 fixed GHSA-qxg6-89mg-rqv8 and GHSA-xp26-3454-mjgp, and 5.0.0-rc.2 fixed GHSA-82fw-gwwq-j7x9. The lockfile resolves the `vite` peer to 7.3.7, which fixes the launch-editor and `server.fs.allow` advisories up to 7.3.6 and has no open advisory. `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
110
- - **Effect skill routing.** Effect work in this checkout must verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/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.
111
- - **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), `--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).
112
- - **Per-machine harness selection.** The SQLite store `~/.docks-kit/kit.db` drives a flag-less sync. A missing selection selects `claude`, `codex`, and `agents`; it never selects `omp` implicitly. `sync` never prompts and never writes the selection. `docks-kit harnesses` is the only command that writes the `harness_selection` table. With no stored selection, its picker pre-ticks all four harnesses, `omp` included, so a new machine opts out of omp instead of opting in; nothing changes until the picker saves. The same store holds the independent `omp_session` table, which only `docks-kit omp` writes, and a TTL cache (`cache_entry`) for the live Anthropic model list and `toolchain outdated` lookups. `kitDb.ts withKitDb` is the only opener: it runs the append-only `MIGRATIONS`, imports a legacy `state.json` once and renames it to `state.json.migrated`, and refuses a store from a newer schema. Cache rows carry the kit version as fingerprint, so a new release refetches them.
113
- - **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 (`claudeRemovals.ts REMOVED_MANIFEST, baseline removal inventory`), a curated list of unambiguous kit-owned artifacts that `claudeRemovals.ts syncRemovals, baseline artifact prune` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts. Codex `config.toml` merges at table granularity: a table the SoT declares (`[features]`, `[sandbox_workspace_write]`, `[tui]`, ...) is replaced wholesale, so user keys inside it are dropped. The prior file stays in `config.toml.bak`, and user-only top-level keys and tables survive.
114
- - **`--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` removes what SoT does not declare: every user-scope Claude plugin whose id is absent from SoT `enabledPlugins` (third-party and previously opted-in plugins included, unless this run passes their `--claude-plugin` flag), every Claude marketplace except `claude-plugins-official`, SoT/opt-in plugin marketplaces, and marketplaces referenced by project/local installs, and the `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills` that SoT no longer lists. Combine with `--reconcile` for a full reset to SoT. Always preserved: user-only settings keys (custom env vars, mcpServers), manually-installed skills, and project/local-scope plugin installs. Each tool's per-tool file documents the specific paths and diff recipes.
115
- - **SOLID-aligned modules.** Axis modules own one concern each (see layout); orchestrators (`claudeSync.ts`, `codexSync.ts`, `skillsSync.ts`, `ompSync.ts`, `index.ts`, `argv.ts`, `parseArgs.ts`) keep prior exports. New shared shapes go in `sharedTypes.d.ts`, never a second local copy. The public CLI seam is `cli/src/engine.ts`.
110
+ - **EngineNative and CLI rules** (idempotency, failure ledger, removed bash engine, Effect stack and skill routing, harness-selection store, module boundaries): `cli/AGENTS.md`.
111
+ - **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), `--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 § Deploy-time modifiers under `## Setup` in this file, and the Claude table in `.claude/rules/claude-code.md` § Deploy-time modifiers).
112
+ - **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 (`claudeRemovals.ts REMOVED_MANIFEST, baseline removal inventory`), a curated list of unambiguous kit-owned artifacts that `claudeRemovals.ts syncRemovals, baseline artifact prune` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `.claude/rules/claude-code.md` § Pruning stale artifacts. Codex `config.toml` merges at table granularity: a table the SoT declares (`[features]`, `[sandbox_workspace_write]`, `[tui]`, ...) is replaced wholesale, so user keys inside it are dropped. The prior file stays in `config.toml.bak`, and user-only top-level keys and tables survive.
113
+ - **`--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` removes what SoT does not declare: every user-scope Claude plugin whose id is absent from SoT `enabledPlugins` (third-party and previously opted-in plugins included, unless this run passes their `--claude-plugin` flag), every Claude marketplace except `claude-plugins-official`, SoT/opt-in plugin marketplaces, and marketplaces referenced by project/local installs, and the `~/.agents/skills/*` entries named in `~/.agents/.kit-owned-skills` that SoT no longer lists. A slug enters that record only when an install of the kit created its directory, so a directory that existed before is never recorded. `--prune` removes it only while the directory keeps the `<dev>:<ino>` that the record names; else it prints `keep <slug>: the directory is not the one that the kit installed`. The legacy `~/.agents/.kit-managed-skills` of an older kit is read only and never authorizes a removal. `--prune` prints a `keep <slug>` line for each of its dropped slugs whose directory exists. Combine with `--reconcile` for a full reset to SoT. Always preserved: user-only settings keys (custom env vars, mcpServers), manually-installed skills, and project/local-scope plugin installs. `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune` documents the Claude paths and diff recipes.
116
114
  - **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.
117
115
  - **Version bumps.** Bump `package.json` on user-visible behavior change; bump a `SoT/toolchain.json` `verified` pin only after testing that release. Refactors, splits, and doc edits bump nothing.
118
- - **Regenerate the payload.** After `SoT/`, `notification.mp3`, `package.json`, or `cli/tsconfig.json` changes, run `bun cli/scripts/generate-sot-payload.ts`; `bun run check:generated` verifies it. After file moves, clamp cited `metadata.source_files[].lines` ranges so `skillMetadata.test.ts` passes.
119
- - **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.
120
- - **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: …
116
+ - **Regenerate the payload.** After `SoT/`, `notification.mp3`, or `package.json` changes, run `bun cli/scripts/generate-sot-payload.ts`; `bun run check:generated` verifies it. After file moves, clamp cited `metadata.source_files[].lines` ranges so `skillMetadata.test.ts` passes.
117
+ - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --dry-run` (or the relevant `diff <(jq -S …)` recipe in `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune`) before invoking `--reconcile` or `--prune`. User-added permissions / env vars / plugins absent from SoT will be discarded.
118
+ - **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 `AGENTS.md` or `.claude/rules/claude-code.md` (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
121
119
  - **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.
122
120
 
123
121
  ## Code style
@@ -129,47 +127,27 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the m
129
127
 
130
128
  - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
131
129
  - Treat external plugin marketplaces and installer downloads as untrusted input. Prefer download-then-run over `curl … | bash` so a truncated stream cannot execute a partial script.
132
- - **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Moving the Effect release is therefore one lockstep commit: set `effect`, `@effect/platform-bun`, and `@effect/platform-node-shared` to the same version together, then run `bun run smoke:package`. The offline guard fails when a lag breaks a declared range. Its peer-range check fails when the installed `effect` is outside a non-optional peer range of the runtime closure. Its nested-copy check fails when `@effect/platform-node-shared` lags. A lagging `@effect/platform-bun` can keep every declared range satisfied (4.1.1 accepts `@effect/platform-node-shared` `^4.1.1`), so only the lockstep commit keeps it in step. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
133
- - **One exemption: the kit's own package.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer.
130
+ - **Pin, never float.** Every kit-driven install of third-party software is pinned to a `SoT/toolchain.json` `verified` version, except the exemptions in the next item — no `@latest` npm/bun installs (Shai-Hulud-class worm surface), no mutable action tags in workflows (commit SHAs only), installer scripts fetched from version tags where upstream supports it. New third-party install surface ⇒ manifest pin first. The rule also covers a transitive dependency whose declared range is a caret or tilde over a prerelease: `^4.0.0-rc.109` admits every later prerelease of the same version tuple, and a published install resolves that range fresh because `bun.lock` is not packaged, so a runtime pinned in `package.json` meets a newer sibling and the process fails at startup. The fix is an exact root pin plus both guards: the offline `cli/test/unit/dependencyPins.test.ts` and the clean-room `bun run smoke:package`. Moving the Effect release is therefore one lockstep commit: set `effect`, `@effect/platform-bun`, and `@effect/platform-node-shared` to the same version together, then run `bun run smoke:package`. The offline guard fails when a lag breaks a declared range. Its peer-range check fails when the installed `effect` is outside a non-optional peer range of the runtime closure. Its nested-copy check fails when `@effect/platform-node-shared` lags. A lagging `@effect/platform-bun` can keep every declared range satisfied (4.1.1 accepts `@effect/platform-node-shared` `^4.1.1`), so only the lockstep commit keeps it in step. Details: the `toolchain-context` skill and `cli/docs/toolchain.md`.
131
+ - **Exemptions: the kit's own package, two host-toolchain installs, and the existing marketplace plugins.** `install.sh` and `install.ps1` end with `bun add -g docks-kit@latest`, because a global installer that pinned itself would install a fixed old kit forever, and pinning it to `package.json` would request an unpublished version between the release-prep commit and the npm publish. The `@latest` exemption covers `docks-kit` alone. Both installers still pin the Bun installer they download to the manifest's verified version. `cli/test/unit/hostTargets.test.ts` asserts that pin in all four launcher and installer scripts, and `cli/test/unit/install.test.ts` proves `install.sh` passes it to the Bun installer. Two host-toolchain installs have no pin, because the host toolchain controls their version and the kit does not: `claudeLsp.ts installRustAnalyzer` adds `rust-analyzer` through `rustup component add rust-analyzer`, and `codexSync.ts ensureBubblewrap` installs `bubblewrap` through the distro package manager. Their `SoT/toolchain.json` rows (`rust-analyzer`, and `bwrap` with a floor only) and `cli/docs/toolchain.md` record this. The existing Claude Code, Codex, and omp marketplace plugin installs have no manifest pin either: sync installs and refreshes those plugins at the version that their marketplace publishes. Any new install surface, a new marketplace or plugin source included, still needs a manifest pin first.
134
132
  ## Testing
135
133
 
136
- Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on push and pull request with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
134
+ Run `bun run check` before and after each change: oxlint, `lint:effect` (Effect rules through `effect-tsgo diagnostics --strict`), `bun fmt --check`, `bun check`, the generated-payload check (`check:generated`), unit tests, and both golden suites. Scripts: `lint`, `lint:effect`, `format:check`, `typecheck`, `check:generated`, `test:unit`, `test:integration` (goldens), `test`, `format`; CI runs `check` on pushes to `main` and on pull requests with Bun 1.4.4. Prove-red modes must exit non-zero after detecting planted mismatches. The golden writer emits two-space JSON that `bun fmt` re-serializes, so run `bun run format` after `--update-goldens` or `format:check` fails. For Effect diagnostics in the editor, set the TypeScript language server command to `node_modules/.bin/effect-tsgo tsc --lsp --stdio`. Keep the `@effect/language-service` plugin entry in `cli/tsconfig.json`: without it, `lint:effect` checks no file and passes. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), `bun run test:runtime:posix`, and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from `.claude/rules/claude-code.md` § When to use `--reconcile` and `--prune`.
137
135
 
138
136
  Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
139
137
 
140
- The spawning suites launch a prebuilt bundle of `cli/src/main.ts`. The build runs once per run, into the ignored `cli/dist-test/`. Bun otherwise transpiles the whole CLI on every child spawn. Set `DOCKS_KIT_TEST_CLI_ENTRY=<repo>/cli/src/main.ts` to run those suites against the TypeScript entry. Use that variable to read a real stack trace. See `cli/test/lib/cliEntry.ts`.
138
+ Spawning-suite bundle and `DOCKS_KIT_TEST_CLI_ENTRY`: `cli/AGENTS.md`.
141
139
 
142
140
  ## Landing changes
143
141
 
144
- Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every required check, then ask before merge. Push direct to `main` only for prose: root Markdown and code comments.
142
+ Open a pull request when the change can alter what CI proves: `cli/`, `SoT/`, `.github/`, the launchers, the installers, `package.json`, `bun.lock`. Wait for every reported check to finish, then ask before merge. A failed or cancelled check blocks the merge. Push direct to `main` only for prose: root Markdown and code comments.
145
143
 
146
144
  Never rewrite published `main` history to correct a routing mistake. Use a follow-up commit and say what happened.
147
145
 
148
146
  ## Skills
149
147
 
150
- **Project-skill scope.** Keep project skills within two classes: kit-mechanic skills and the `unslop` repo-prose skill.
151
- Canonical project skills live in `.agents/skills/<name>/SKILL.md`.
152
- Each `.claude/skills/<name>` entry is a relative symlink to its canonical directory.
153
- Codex reads `.agents/skills/` natively, so one copy serves both tools.
154
- Kit-mechanic skills document regression-prone TypeScript sync logic in `cli/src/engine-native/`.
155
- 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`.
156
- **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.
157
-
158
- **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.
148
+ Project-skill and wrapper-agent authoring rules (scope, canonical layout, Windows symlinks, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
159
149
 
160
- `npx skills add cursor/plugins -s unslop -y -a claude-code codex` installs `unslop`, and root `skills-lock.json` pins it.
161
- The repository vendors upstream `unslop` text and pins it by the lockfile hash, so never edit it locally.
162
- Upstream licenses `pstack/` under MIT (Copyright (c) 2026 Lauren Tan), so redistribution is permitted.
163
- MIT requires the notice to travel with the copy, so `.agents/skills/unslop/LICENSE` vendors it verbatim and must stay beside `SKILL.md`.
164
- The `unslop` "adding soul" guidance conflicts with the global Simplified Technical English Output Standard.
165
- The Output Standard wins.
166
- Use `unslop` only for its pattern-detection lists.
167
-
168
- <constraint>
169
- 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. `claudePluginPasses.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.
170
- </constraint>
171
-
172
- **Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsInstall.ts syncUniversal` with `npx --yes skills@<verified> add <slug> -g -y -a claude-code codex`, where `<verified>` is the `skills-cli` pin in `SoT/toolchain.json`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently, `--prune` removes only entries tracked in `~/.agents/.kit-managed-skills`, and skills requiring a separate CLI retain explicit helpers in `skillsSync.ts`.
150
+ **Universal-skill bootstrap.** `SoT/.agents/skills.txt` is intentionally empty, so the default sync exposes no universal skills. The generic opt-in contract remains: each [agentskills.io](https://agentskills.io/specification) slug is installed by `skillsInstall.ts syncUniversal` with `npx --yes skills@<verified> add <slug> -g -y -a claude-code codex`, where `<verified>` is the `skills-cli` pin in `SoT/toolchain.json`. The slug comes first because `-a/--agent` is variadic; naming both supported agents preserves the canonical `~/.agents/skills/<name>/SKILL.md` plus Claude's `~/.claude/skills/<name>` symlink. Existing canonical directories are reused idempotently and are never recorded as kit-owned. When no record names a reused directory, sync warns that `--prune` keeps it. Before an install, sync records the slug in `~/.agents/.kit-pending-skills`, and only when the canonical directory does not exist. After the install, the slug moves to `~/.agents/.kit-owned-skills` when its directory exists. `--prune` removes only entries in `~/.agents/.kit-owned-skills`; the legacy `~/.agents/.kit-managed-skills` is read only and never authorizes a removal (`skillsRecords.ts`).
173
151
 
174
152
  ## Plans
175
153
 
@@ -191,7 +169,7 @@ review, implement, and code review. It uses bounded repair and fresh re-review
191
169
  in both review phases, then archives. Internal `plan-reviewer` returns one
192
170
  readable pre-implementation verdict block per round. Two read-only reviewer
193
171
  wrappers ship: `plan-reviewer` and `code-reviewer`.
194
- The explicit-only `yolo` skill runs the same workflow and asks only before merge.
172
+ The explicit-only `yolo` skill runs the same workflow. It still asks before merge, on a review stall, before a production cleanup, and before a step after the landing merge, as the contract's Yolo runs section says.
195
173
  </constraint>
196
174
 
197
175
  After the marker and blank line, the record carries exactly seven sections.
@@ -205,8 +183,12 @@ GitHub `state` and `stateReason` determine closed status. Review records live
205
183
  only in issue comments. Each reviewer returns one markdown block.
206
184
  The manager posts that block as one issue comment. The latest trusted eligible
207
185
  comment per review kind wins. Its author must equal the plan's sole assignee.
208
- Both review phases use fresh inputs and run at most five rounds. They stop on
209
- pass, no progress, a finding that survives repair, or a round-five non-pass.
186
+ Both review phases use fresh inputs for each round. They stop on
187
+ pass. Ask the user to continue or block when a round makes no progress, the
188
+ same finding returns after a repair, round 5 does not pass, or dispatch fails
189
+ again without a relevant change. If no answer is available, record the reason
190
+ and block. A yolo run uses the round ceiling of the contract's Yolo runs
191
+ section instead.
210
192
  A plan-review `blocked` verdict routes its user-only decision through
211
193
  `## Open questions` and `ask`.
212
194
 
@@ -237,20 +219,18 @@ before it runs; when `ask` is unavailable the step is set `blocked` and the plan
237
219
  reason becomes the first `## Open questions` line, `Blocked: <reason>`.
238
220
  Persisted effects record intent only. Routine issue publication and landing
239
221
  actions are outside the Steps table.
240
- A user-invoked `yolo` run replaces these asks, the five-round stop, and the `blocked`-verdict question with the Yolo runs section of the installed `plan-lifecycle` contract.
222
+ A user-invoked `yolo` run replaces these asks, the continue-or-block question of the review loop, and the `blocked`-verdict question with the Yolo runs section of the installed `plan-lifecycle` contract.
241
223
 
242
224
  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.
243
225
 
244
226
  No plan markdown is tracked. The pre-GitHub records under
245
227
  `docs/plans/finished/` were deleted; `git log -- docs/plans/finished/` recovers
246
228
  them as history, and no lifecycle command restores them. The complete contract
247
- lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it and `docs/CLAUDE.md`
248
- contains only `@AGENTS.md`.
229
+ lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it.
249
230
 
250
- Distinct from per-tool **Open Concerns** sections (wait-on-upstream
251
- blockers tied to a vendor shipping a fix — these live inside the per-tool
252
- file): plans are kit-internal work we control; Open Concerns is
253
- conditions-for-resolution.
231
+ Distinct from the **Open Concerns** section of `.claude/rules/claude-code.md`
232
+ (wait-on-upstream blockers tied to a vendor shipping a fix): plans are
233
+ kit-internal work we control; Open Concerns is conditions-for-resolution.
254
234
 
255
235
  Plugin-internal work (skills, commands, agents) belongs in each plugin's
256
236
  own repo, not here.
@@ -258,3 +238,37 @@ own repo, not here.
258
238
  ## Notes for nested overrides
259
239
 
260
240
  Per the agents.md open standard, place an `AGENTS.md` inside any subdirectory that needs different rules. The closest `AGENTS.md` to the file being edited wins; explicit user prompts override everything.
241
+
242
+ ## Setup
243
+
244
+ ```bash
245
+ # Clone and sync the kit
246
+ git clone <this-repo> ~/projects/public
247
+ cd ~/projects/public
248
+ ./docks-kit harnesses # view or change this machine's flag-less sync selection
249
+ ./docks-kit sync # sync this machine's harness selection (additive)
250
+ ./docks-kit sync --dry-run # preview before applying
251
+ ./docks-kit sync --skip-bubblewrap # skip optional bubblewrap bootstrap (Codex Linux sandbox)
252
+ ./docks-kit sync --reconcile # reconcile settings toward SoT: SoT keys and arrays win, user-only keys kept (settings layer only)
253
+ ./docks-kit sync --prune # uninstall plugins/marketplaces not in SoT (plugin layer only)
254
+ ./docks-kit sync --reconcile --prune # full reset to SoT (both layers)
255
+ ./docks-kit sync claude --claude-compact-window=680k # deploy-time: raise autocompact window (any token count: 680k or 680000) for disposable sessions (model unchanged)
256
+ ./docks-kit sync claude --claude-permissive # deploy-time: empty permissions.ask/deny — unattended commits/pushes in sandboxes
257
+ ./docks-kit sync --claude-plugin=supabase # opt in the supabase plugin (install + enable in deployed settings)
258
+ ./docks-kit sync --claude-plugin=n8n # opt in the n8n-mcp-skills plugin (add marketplace + install + enable); repeatable/comma-separated
259
+ ./docks-kit model claude opus # deploy-time: set Opus explicitly (matches the SoT; standalone form of --claude-model=)
260
+ ./docks-kit status # show deployed vs SoT state
261
+ ./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
262
+ ```
263
+
264
+ On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout
265
+ commands.
266
+
267
+ For Codex plugins, after deploying `SoT/.codex/config.toml` and the personal marketplace file, sync runs `codex plugin add <plugin@marketplace>` for each enabled SoT plugin. Re-running sync therefore refreshes stale Codex plugin caches instead of only updating marketplace metadata. Sync also removes the older kit-created configured Docks marketplace source so Codex uses the personal marketplace file as the single source.
268
+
269
+ ### Deploy-time modifiers
270
+
271
+ Unlike `--reconcile`/`--prune` (which reconcile toward SoT), modifiers change the **deployed** config for a specific machine profile. The SoT is never touched, and a later flag-less sync reasserts it: Claude returns to Opus/high/advisor-off and Codex returns to its model/high effort. Modifiers run after the base merge/removal passes, are idempotent, honor `--dry-run`, and warn when their tool target is not selected. `docks-kit model <tool> <value>` is the standalone form of the model modifiers.
272
+
273
+ Codex mirrors the model/effort contract with `--codex-model=<m>` and
274
+ `--codex-effort=<level>`; Codex `default` effort restores `high`.
package/README.md CHANGED
@@ -127,11 +127,11 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
127
127
  `docks-kit docs command-guards`.
128
128
  - **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
129
129
  directories and removes agent temporary files and directories with checked
130
- paths, and `docks-kit tidy` removes merged idle worktrees, their containers,
131
- orphaned processes, and idle scratch directories; `--report` lists other
132
- disk and memory use. The kit omp plugin `docks-kit-omp` exposes these as
133
- tools, reminds the agent of what it created, and runs the sweep at most
134
- once per 12 hours.
130
+ paths. `docks-kit tidy` lists merged idle worktrees, their containers,
131
+ orphaned processes, and idle scratch directories, and `docks-kit tidy
132
+ --apply` removes them; `--report` lists other disk and memory use. The kit
133
+ omp plugin `docks-kit-omp` exposes these as tools, reminds the agent of
134
+ what it created, and runs the sweep at most once per 12 hours.
135
135
 
136
136
  ## Repository map
137
137
 
@@ -149,7 +149,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
149
149
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
150
150
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
151
151
  | `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
152
- | `AGENTS.md` / `CLAUDE.md` | Agent-facing engineering rules / Claude Code specifics |
152
+ | `AGENTS.md` / `.claude/rules/claude-code.md` | Agent-facing engineering rules / Claude Code specifics (path-scoped rule) |
153
153
 
154
154
  ## Platform support
155
155
 
@@ -180,5 +180,5 @@ are versioned config snapshots without shipping the authoring `SoT/` tree.
180
180
  omp-models, omp-context, command-guards, toolchain, plugins, install,
181
181
  platforms (works offline, bundled with the CLI)
182
182
  - [`AGENTS.md`](AGENTS.md) — engineering rules for agents working on the kit
183
- - [`CLAUDE.md`](CLAUDE.md) — Claude Code specifics: env vars, session
183
+ - [`.claude/rules/claude-code.md`](.claude/rules/claude-code.md) — Claude Code specifics: env vars, session
184
184
  management, permission mode, open concerns
@@ -16,8 +16,8 @@ ask tier is accepted.
16
16
 
17
17
  omp is the exception: by owner decision (0.22.8, #126), the kit ships no omp
18
18
  prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
19
- allow. Under the kit's `tools.approvalMode: yolo`, omp runs every command
20
- that no deny matches without a question, in the main session and in
19
+ allow. Under omp's default `tools.approvalMode: yolo`, omp runs every
20
+ command that no deny matches without a question, in the main session and in
21
21
  subagents. This includes any `rm` that omp does not deny, `git clean`,
22
22
  `git reset --hard`, a force push that no deny matches, and a git command
23
23
  that skips the repository's hooks. A prompt rule that the user adds to
@@ -55,7 +55,7 @@ that `eval` starts.
55
55
  | Recursive `rm` (`-r`, `-R`, `-rf`, `-fr`, `-rfv`, `-ri`, `-ir`, `-Ri`, `-iR`, `--recursive`, other listed clusters) | deny, also behind any prefix (`env`, `xargs`, `nice`, `find -exec`, `git rm -r`) | ask | ask (every `rm` asks) |
56
56
  | `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny | ask if recursive, else classifier | ask |
57
57
  | Any other `rm`: one file, several files, a glob, `-f` | run | glob asks; the rest goes to the classifier | ask |
58
- | `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask | ask (every `find` asks) |
58
+ | `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask for `-delete`, `-exec rm` and `-execdir rm`; `-ok`/`-okdir rm` and a non-recursive `xargs rm` go to the classifier | ask (every `find` asks) |
59
59
  | `git clean`, `git reset --hard` | run | ask | ask |
60
60
  | `git push` that could force: see below | run, unless a deny above matches | ask | ask (every `git push` asks) |
61
61
  | A `$` or a backtick anywhere after `git push` in the same command | deny, also after a shell keyword, a wrapper, or a path before `git`: see below | ask for a word that starts with `$` or a backtick | ask (every `git push` asks) |
@@ -175,8 +175,9 @@ omp has a built-in check for critical commands. For example, it flags:
175
175
  - `sudo rm`, also when `sudo` is called by its path.
176
176
 
177
177
  For a critical command, omp returns a bare safety override before it returns
178
- a matching prompt rule. Under the kit's `tools.approvalMode: yolo`, omp
179
- ignores a bare override, so the command runs. This applies in subagents too.
178
+ a matching prompt rule. Under omp's default `tools.approvalMode: yolo`,
179
+ omp ignores a bare override, so the command runs. This applies in subagents
180
+ too.
180
181
  Only a deny rule stops a critical command (`omp://approval-mode.md`).
181
182
 
182
183
  The kit therefore denies every `rm` shape that the check can flag:
@@ -322,7 +323,11 @@ prompt. In Claude Code, any form with `--empty` or `--restore` asks.
322
323
  so user rules stay. `--reconcile` replaces the arrays with the SoT arrays.
323
324
  - **Codex**: sync writes `~/.codex/rules/docks.rules` whole. Keep your own
324
325
  rules in another `.rules` file, such as `default.rules`. Codex applies the
325
- strictest rule across all files.
326
+ strictest rule across all files. Sync records each kit rules file in
327
+ `~/.codex/.kit-managed-rules`. When the SoT drops a kit rules file, sync
328
+ removes the deployed copy while it holds the kit bytes. A dropped file that
329
+ you edited stays, and each sync warns about it. Sync never removes a file
330
+ that it did not write, such as `default.rules`.
326
331
 
327
332
  ## Check the deployed rules
328
333
 
@@ -338,7 +343,7 @@ Each check below is safe, because the shell never reaches `rm`.
338
343
  ## Sources
339
344
 
340
345
  - omp: `omp://tools/bash.md`, `omp://approval-mode.md`, and the
341
- `@oh-my-pi/pi-coding-agent` 18.11.1 source `src/tools/bash.ts`
346
+ `@oh-my-pi/pi-coding-agent` 18.17.0 source `src/tools/bash.ts`
342
347
  (`CRITICAL_BASH_PATTERNS`, `BashTool.approval`).
343
348
  - Claude Code: https://code.claude.com/docs/en/permissions and
344
349
  https://code.claude.com/docs/en/permission-modes