docks-kit 0.22.28 → 0.23.0

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 (75) hide show
  1. package/AGENTS.md +31 -77
  2. package/README.md +31 -58
  3. package/cli/docs/command-guards.md +231 -197
  4. package/cli/docs/flags.md +25 -55
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-models.md +9 -0
  7. package/cli/docs/overview.md +4 -12
  8. package/cli/docs/platforms.md +2 -2
  9. package/cli/docs/sync-layers.md +10 -57
  10. package/cli/docs/toolchain.md +9 -78
  11. package/cli/src/argv.ts +0 -8
  12. package/cli/src/argvValidate.ts +2 -46
  13. package/cli/src/commands/docs.ts +2 -14
  14. package/cli/src/commands/harnesses.ts +6 -9
  15. package/cli/src/commands/sync.ts +5 -99
  16. package/cli/src/commands/toolchain.ts +4 -12
  17. package/cli/src/engine-native/DESIGN.md +67 -88
  18. package/cli/src/engine-native/deps.ts +6 -86
  19. package/cli/src/engine-native/engineCtx.ts +7 -76
  20. package/cli/src/engine-native/exec.ts +1 -18
  21. package/cli/src/engine-native/harnesses.ts +6 -6
  22. package/cli/src/engine-native/index.ts +4 -6
  23. package/cli/src/engine-native/jq.ts +4 -37
  24. package/cli/src/engine-native/modes.ts +3 -132
  25. package/cli/src/engine-native/os/darwin.ts +0 -4
  26. package/cli/src/engine-native/os/index.ts +1 -2
  27. package/cli/src/engine-native/os/linux.ts +0 -3
  28. package/cli/src/engine-native/os/posix.ts +2 -46
  29. package/cli/src/engine-native/os/types.ts +1 -32
  30. package/cli/src/engine-native/os/windows.ts +0 -49
  31. package/cli/src/engine-native/parseArgs.ts +11 -124
  32. package/cli/src/engine-native/parseHelp.ts +5 -40
  33. package/cli/src/engine-native/scratch.ts +1 -1
  34. package/cli/src/engine-native/services.ts +1 -2
  35. package/cli/src/engine-native/sharedTypes.d.ts +0 -40
  36. package/cli/src/engine-native/skillsSync.ts +1 -1
  37. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  38. package/cli/src/engine-native/syncDispatch.ts +10 -57
  39. package/cli/src/engine-native/toolchain.ts +5 -40
  40. package/cli/src/engine.ts +0 -75
  41. package/cli/src/generated/sotPayload.ts +12 -39
  42. package/cli/src/main.ts +7 -19
  43. package/cli/src/manifests.ts +1 -93
  44. package/cli/src/payload.ts +2 -8
  45. package/cli/tsconfig.json +1 -3
  46. package/package.json +3 -5
  47. package/cli/docs/models.md +0 -58
  48. package/cli/docs/modifiers.md +0 -52
  49. package/cli/docs/plugins.md +0 -70
  50. package/cli/src/commands/model.ts +0 -68
  51. package/cli/src/commands/models.ts +0 -75
  52. package/cli/src/commands/plugins.ts +0 -35
  53. package/cli/src/commands/status.ts +0 -206
  54. package/cli/src/efforts.ts +0 -89
  55. package/cli/src/engine-native/claudeLsp.ts +0 -301
  56. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  57. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  58. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  59. package/cli/src/engine-native/claudeRetired.ts +0 -165
  60. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  61. package/cli/src/engine-native/claudeSettings.ts +0 -201
  62. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  63. package/cli/src/engine-native/claudeSync.ts +0 -312
  64. package/cli/src/engine-native/codexConfig.ts +0 -214
  65. package/cli/src/engine-native/codexHooks.ts +0 -91
  66. package/cli/src/engine-native/codexPaths.ts +0 -14
  67. package/cli/src/engine-native/codexPlugins.ts +0 -315
  68. package/cli/src/engine-native/codexStatus.ts +0 -25
  69. package/cli/src/engine-native/codexSync.ts +0 -314
  70. package/cli/src/engine-native/codexToml.ts +0 -303
  71. package/cli/src/engine-native/liveModels.ts +0 -264
  72. package/cli/src/engine-native/models.ts +0 -101
  73. package/cli/src/engine-native/parseModifiers.ts +0 -225
  74. package/cli/src/engine-native/settings.ts +0 -42
  75. package/cli/src/engine-native/tomlLines.ts +0 -92
package/AGENTS.md CHANGED
@@ -1,15 +1,15 @@
1
1
  # AGENTS.md
2
2
 
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.
3
+ Canonical instructions for coding agents working on this project. Compatible with Oh My Pi (`omp`), OpenCode, VS Code Copilot, and any other [agents.md](https://agents.md/)-aware tool.
4
4
 
5
5
  Pointers here name concepts, not coordinates — if a path or symbol moved,
6
6
  trust the stated purpose and re-locate it (grep the symbol) before acting.
7
7
 
8
8
  ## Repository purpose
9
9
 
10
- Portable configuration kit for AI coding agents. The kit manages three coding
11
- harnesses: Claude Code, Codex, and Oh My Pi (`omp`). Per-tool Single Source of
12
- Truth (SoT) directories deploy to each harness's user-config location through
10
+ Portable configuration kit for AI coding agents. The kit manages one coding
11
+ harness, Oh My Pi (`omp`). Its Single Source of Truth (SoT) directory deploys
12
+ to omp's user-config location through
13
13
  `./docks-kit sync`. The kit also deploys shared [agentskills.io](https://agentskills.io)
14
14
  skills. Clone once to get a consistent AI-assisted environment on supported
15
15
  Linux, macOS, and Windows hosts. The kit focuses on **token efficiency without
@@ -17,11 +17,7 @@ sacrificing quality**. Every setting and hook minimizes token use while
17
17
  preserving rigorous output. When you add or edit anything, ask: *does this
18
18
  change reduce tokens without weakening correctness?*
19
19
 
20
- Tool-specific instructions live alongside this file:
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.
22
- - Codex uses this `AGENTS.md` file plus the Codex SoT under `SoT/.codex/`; no separate root `CODEX.md` is needed.
23
- - omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
24
-
20
+ omp uses this `AGENTS.md` file plus the omp SoT under `SoT/.omp/`.
25
21
 
26
22
  docks-kit runtime and standalone binary support covers Linux x64/arm64, macOS
27
23
  arm64, and Windows x64. Hosts outside this matrix fail before either
@@ -29,19 +25,17 @@ launcher can fall back to Bun source.
29
25
 
30
26
  ## Context tree
31
27
 
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.
28
+ Per-folder conventions live in nested `AGENTS.md` nodes. An agent can load
29
+ only the nodes from the root down to its working directory, so open the node
30
+ for the folder you edit from this table. Edit the node, not this list, when a
31
+ folder's rules change. `context-tree audit` checks this table against the
32
+ AGENTS.md files on disk.
39
33
 
40
34
  | Node | Governs |
41
35
  |---|---|
42
36
  | `docs/AGENTS.md` | Plan-record routing to `docs/PLAN.md` |
43
37
  | `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 |
38
+ | `.agents/skills/AGENTS.md` | Project skills; omp reads `.agents/skills/` directly |
45
39
 
46
40
  ## Repository layout (cross-cutting)
47
41
 
@@ -50,88 +44,70 @@ table against the AGENTS.md files on disk.
50
44
  | `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. |
51
45
  | `.oxlintrc.json` / `bunfig.toml` | Mechanical lint (correctness, suspicious, eqeqeq, no-var, prefer-const, no-unused) and the `bun fmt` code format settings (`[fmt]`) |
52
46
  | `cli/` | Effect 4 CLI + bundled docs topics |
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 |
54
47
  | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative; optional `upstream` source read by `docks-kit toolchain outdated`) |
55
- | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
56
48
  | `SoT/.omp/` | Kit-owned omp SoT: `AGENTS.md`, `config.yml`, `models.yml`, `mcp.json`, `intercom.json`, and the kit plugin source `plugin/` |
57
49
  | `install.sh` / `install.ps1` | POSIX and Windows global installers. Each installer stops on a host outside the support matrix before it downloads anything. |
58
50
  | `.github/workflows/release-cli.yml` | `cli-v*` release: four binaries (Linux x64 and arm64, macOS arm64, Windows x64), plus `SHA256SUMS` and npm publish |
59
51
  | `README.md` | Front door |
60
52
  | `package.json` / `bun.lock` | npm package: `bin` = `cli/src/main.ts`; bundles `cli/` with the generated in-memory SoT payload |
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. |
62
- | `notification.mp3` | Audio asset for Notification hooks (consumed by Claude Code today; tool-agnostic file) |
53
+ | `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. |
63
54
  | `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 |
66
55
  | `AGENTS.md` | This file — tool-agnostic instructions |
67
56
 
68
57
  Module map for `cli/` (engine axes, commands, kit store, test fixtures, and the release-binary build `bun run build:binaries`): `cli/AGENTS.md`.
69
58
 
70
- Codex SoT notes:
71
- - `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
72
- - `SoT/.codex/config.toml` pins Codex to `model = "gpt-6.2-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). The two project Codex reviewer agents in `.codex/agents/` use the same model.
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.
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.
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.
77
- - Codex `/import` hook cleanup (`codexHooks.ts`): `cli/AGENTS.md`.
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.
59
+ Shared SoT notes:
79
60
  - The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
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.
81
-
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.
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.
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`.
85
61
 
86
62
  omp SoT notes:
87
63
  - `SoT/.omp/AGENTS.md`, `config.yml`, `models.yml`, and `mcp.json` deploy to `~/.omp/agent/`. omp loads `~/.omp/agent/AGENTS.md` only into main sessions and advisors, never into task subagents (`omp://context-files.md`). So `SoT/.omp/AGENTS.md` holds only main-session rules, and a command rule that subagents need goes into a kit plugin trigger rule.
88
64
  - `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.
89
65
  - `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`.
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. The kit plugin trigger rules in `SoT/.omp/plugin/rules/` carry the agent rules for these commands. `git-safety.md` 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.
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.
66
+ - `SoT/.omp/config.yml` `bash.patterns` holds the destructive-command guards. omp 19.0.0 checks a deny rule, then a prompt rule, then its `CRITICAL_BASH_PATTERNS`, then an allow rule (`BashTool.approval` in the v19.0.0 source; `omp://approval-mode.md` still describes the 18.17.0 order, in which the critical check came before a prompt rule). A critical command that no deny or prompt rule matches gets a bare safety override, which replaces a matching allow, and omp's default `tools.approvalMode: yolo` ignores a bare override, so the command runs, in subagents too. A prompt rule asks a person, also on a critical command, but a subagent rejects every prompt. Every `rm` shape that the critical 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. The kit plugin trigger rules in `SoT/.omp/plugin/rules/` carry the agent rules for these commands. `git-safety.md` tells the agent to write each `git push` ref literally and to push the current branch with `git push -u origin HEAD`. The list order is deny, then `trash *`. For a command without shell control, omp takes the first matching rule. For a command with shell control, such as `;` or `|`, each segment takes its first matching deny or prompt rule, a deny chosen for one segment wins over a prompt chosen for another segment, and an allow never matches. A segment also matches without its leading `NAME=value` words. `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 19.0.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.
67
+ - `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, with no flag. 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.
92
68
  - `cycleOrder` ends with `astra` as its fifth stop. `modelRoles.astra` is `openai-codex/gpt-6.2-astra:xhigh`, and `modelTags.astra` (`GPT-6.2 Astra`) is visible. Astra and Fable fall back to each other through concrete selectors: `retry.fallbackChains.astra` holds `anthropic/claude-fable-5-2:medium`, and `retry.fallbackChains.fable` holds `openai-codex/gpt-6.2-astra:xhigh`. `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.2-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.22.2, the oldest release the kit tested with `gpt-6.2-sol` and `gpt-6.2-astra`. That release lists and serves both models through the `openai-codex` provider. The floor is doctor visibility only. Sync does not check the omp catalog, so an older omp can fuzzy-match a missing id to another model. `cli/docs/omp-models.md` records the checks.
69
+ - `modelRoles.task` is `anthropic/claude-opus-5-5:high`, and `retry.fallbackChains.task` falls back to `openai-codex/gpt-6.2-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 and verified pin are 19.0.0, the release the kit tested on 2026-11-19: its `omp models --json` catalog lists each model selector of `modelRoles` and `retry.fallbackChains` exactly, every `SoT/.omp/config.yml` key is a key of `omp config list --json`, and `cli/test/lib/ompBashPatterns.ts` ports its approval source. The floor is doctor visibility only. Sync does not check the omp catalog, so an older omp can fuzzy-match a missing id to another model. `cli/docs/omp-models.md` records the checks.
94
70
  - 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 `astra`, `reviewer`, `fable`, and `switch_fable` rows are the exceptions: they come from v5.0.1 captures read 2026-11-18 (GPT-6.2 Astra), 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 every Opus 5.5 level and every GPT-6.2 Sol and GPT-6.2 Astra row in that topic. GPT-6 Luna medium is the only unmeasured speed and latency row.
95
71
  - `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.
96
72
  - `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 override is keyed `gpt-6.2-astra`, the model id of the `astra` role. `ompRemovals.ts syncOmpModelRemovals` prunes the old `gpt-6-astra` block from `~/.omp/agent/models.yml` while it equals the shipped block. 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.
97
73
  - `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
98
74
  - `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. For each model that an omp role or retry chain uses, the topic keeps AA rows at `high` and `xhigh` at least, with the index version and the capture date.
99
75
  - `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.
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, the `/cleanup` command, and six omp Time Traveling Stream Rules (TTSR, trigger rules) in `rules/`: `file-removal.md`, `git-safety.md`, `temp-and-background.md`, `worktree-location.md`, `literal-paths.md`, and `remote-cleanup.md`. omp's `omp-plugins` provider loads `rules/*.md` from the linked plugin root (`omp://plugin-manager-installer-plumbing.md`). Each rule has a regex `condition` scoped to `tool:bash, tool:eval` that aims at the wrong form; eval is in scope because eval code can run a shell command through `sh()`. A condition reads text, not a parsed command, so it has known false positives: a quoted command word (`echo "rm x"`, or a commit message that starts with `rm`) and eval code after the closing quote of a `sh()` string. `worktree-location.md` fires on each `git worktree add`, also at the correct path, because a condition cannot read `$XDG_DATA_HOME` or the home directory. omp aborts the matching tool call before it runs, injects the rule, and retries (`omp://ttsr-injection-lifecycle.md`). Each rule has `repeatMode: always`: it fires at each later wrong form, but not on the retry that its own reminder starts. The rules reach subagents and cost no prompt tokens until they fire. They teach the correct form; the `bash.patterns` denies still enforce. omp tests each condition on the partial argument buffer after each streamed delta, so a condition must not match a prefix of a correct command: it needs a delimiter after each token it checks, never the end anchor `$`. The buffer is the argument JSON text, the intent field `i` can come before or after `command`, and a provider can put JSON white space around the colon (`{"command": "ls"}`). So each condition starts its match inside the `command` or `code` string with the lookbehind `(?<="(?:command|code)"\s*:\s*"(?:\\.|[^"\\])*)`, each scan stops at an unescaped `"` and at a newline (`\n`), a tab (`\t` in the buffer) counts as shell white space, and a scan that looks for an option stops at a ` -- ` word. `cli/test/unit/ompTriggerRules.test.ts` pins every condition through bash and through Python and JavaScript eval `sh()` calls, in the compact and the spaced JSON layouts, with some rows in the pretty layout and trigger words in the intent before and after the command. It checks that each condition has a wrong row that fires it and that each rule has `repeatMode: always`. `cli/docs/command-guards.md` (topic `command-guards`) lists the rules and the false positives. 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.
76
+ - 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, the `/cleanup` command, and six omp Time Traveling Stream Rules (TTSR, trigger rules) in `rules/`: `file-removal.md`, `git-safety.md`, `temp-and-background.md`, `worktree-location.md`, `literal-paths.md`, and `remote-cleanup.md`. omp's `omp-plugins` provider loads `rules/*.md` from the linked plugin root (`omp://plugin-manager-installer-plumbing.md`). Each rule has a regex `condition` scoped to `tool:bash, tool:eval` that aims at the wrong form; eval is in scope because eval code can run a shell command through `sh()`. A condition reads text, not a parsed command, so it has known false positives: a quoted command word (`echo "rm x"`, or a commit message that starts with `rm`) and eval code after the closing quote of a `sh()` string. `worktree-location.md` fires on each `git worktree add`, also at the correct path, because a condition cannot read `$XDG_DATA_HOME` or the home directory. omp aborts the matching tool call before it runs, injects the rule, and retries (`omp://ttsr-injection-lifecycle.md`). Each rule has `repeatMode: always`: it fires at each later wrong form, but not on the retry that its own reminder starts. The rules reach subagents and cost no prompt tokens until they fire. They teach the correct form; the `bash.patterns` denies still enforce. omp tests each condition on the partial argument buffer after each streamed delta, so a condition must not match a prefix of a correct command: it needs a delimiter after each token it checks, never the end anchor `$`. The buffer is the argument JSON text, the intent field `i` can come before or after `command`, and a provider can put JSON white space around the colon (`{"command": "ls"}`). So each condition starts its match with the forward key prefix `"(?:command|code)"\s*:\s*"[^"\\]*?` and an escape loop that takes up to 8 escape pairs per step; `cli/docs/command-guards.md` shows the full prefix. Only the key prefix is sure to stay inside the `command` or `code` string. The rest of a condition can cross the closing quote: the `Bun.file` condition of `file-removal.md` matches `{"code":"Bun.file(","i":").delete("}`. omp's `Matched:` excerpt is a bounded window around the match start: up to 60 characters before it, and a long match is cut at 180 characters from its start, so in a long call the trigger can be outside the excerpt. A scan stops at an unescaped `"` and at a newline (`\n`), a tab (`\t` in the buffer) counts as shell white space, and a scan that looks for an option stops at a ` -- ` word. omp runs each test on its main thread, in JavaScriptCore. Up to 0.22.29, each condition started with an unbounded lookbehind, which walked back over the buffer from every position. A 20 KB call then froze the session for seconds, and past the JavaScriptCore match limit the rule did not fire. So never start a condition with an unbounded lookbehind. Make each scan after a command start one lazy walk that stops at its first event: `(?=(?<w>[\s\S]*?)(?=EVENT)BOUNDARY)\k<w>`. The events are the flag of the condition, a terminator, the end of the run, and the next command start, each at a real token boundary. The lookahead does not backtrack after it matches, so the walk stays frozen. The stop at the next command start keeps a line that repeats a command start linear. Never put a group loop inside a lookaround over text of unbounded length, because JavaScriptCore then keeps each loop step until the match attempt ends and drops out of the JIT. omp tests open buffers that stop before the closing quote, so a scan must not rely on that quote to stop. `cli/test/unit/ompTriggerRules.test.ts` pins every condition through bash and through Python and JavaScript eval `sh()` calls, in the compact and the spaced JSON layouts, with some rows in the pretty layout and trigger words in the intent before and after the command. It checks that each condition has a wrong row that fires it and that each rule has `repeatMode: always`. Its shape guard checks only the key prefix and that no `|` stands outside every group. Its backstop runs `cli/test/lib/ompTriggerBackstop.ts` under Bun and proves linear time by measurement: a time budget, a fire check, scaling with the JIT off, and dense and head-and-run lines with the JIT on, in bash, open bash, and Python. Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts` after each condition change; it runs both guards. When you rewrite a condition, run the old and the new condition on each buffer of the test table and compare the results. `cli/docs/command-guards.md` (topic `command-guards`) lists the rules, the false positives, and the input families that a forward key prefix alone does not make linear. 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.
101
77
  - `task.agentIdleTtlMs` is `120000`, so omp parks an idle subagent after 2 minutes instead of 7. `browser.idleCloseSec` is `600`.
102
78
  - By owner decision (0.21.0), resources on the workstation are always development, so `docks-kit tidy` sweeps them without a question. The omp `remote-cleanup.md` trigger rule, the `workspace-hygiene` skill, `/cleanup`, and the extension reminders limit the cleanup of a remote resource (reached through SSH, a database client, or a provider CLI such as `wrangler`, `vercel`, `kubectl`, `aws`, 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.
103
79
  - 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.
104
80
  - omp plugin upgrade flow, the `pi-intercom` install, and the `docks-kit omp` free-model launcher: `cli/AGENTS.md`.
105
81
 
106
- For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
82
+ For the omp SoT layout (`SoT/.omp/`), see that directory.
107
83
 
108
84
  ## Engineering rules
109
85
 
110
86
  - **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.
87
+ - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `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-plugin-refresh` (install missing omp plugins without refreshing existing ones), `--prune`, and `--verbose`.
88
+ - **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. The exceptions are the omp retired inventories: `ompRemovals.ts` force-prunes retired kit-owned keys, `bash.patterns` rules, and model blocks on every sync (see the omp SoT notes above).
89
+ - **`--prune` is the one kit-owned removal flag.** It removes 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. Manually installed skills are always preserved.
114
90
  - **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.
115
91
  - **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.
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: …
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.
92
+ - **Regenerate the payload.** After `SoT/` 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.
93
+ - **Dry-run before destructive flags.** Always preview with `./docks-kit sync --prune --dry-run`, with the same targets as the intended run, before invoking `--prune`. Only that preview lists the kit-recorded skills that SoT no longer lists, which `--prune` removes.
94
+ - **SoT prompt files are rules, not explanation.** `SoT/.omp/AGENTS.md` is loaded into agent sessions' prompt context — every line costs prompt tokens on every turn for every user. Restrict its 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` (humans read once) or in commit messages — never in the SoT. For every line, apply the official test: …
95
+ - **Cache-invariance for kit-authored prompt surfaces.** Never put timestamps, counters, or mutable state into SoT prompt files, extension output that lands in the cached prefix, or tool definitions — cache breaks force cold-start writes. Dynamic context belongs in runtime-injected messages, such as the reminders that the kit omp plugin adds to tool results.
120
96
 
121
97
  ## Code style
122
98
 
123
- - Bash: for launchers/installers/hook assets, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
124
- - JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.claude/`, `~/.codex/`, or `~/.omp/agent/` directly.
99
+ - Bash: for launchers and installers, use `set -euo pipefail`, quoted variables, `[[ ]]` over `[ ]`, and function-scoped `local`.
100
+ - JSON and YAML config: edit the SoT (`SoT/<tool>/`) and run `./docks-kit sync`. Never edit deployed config under `~/.omp/agent/` directly.
125
101
 
126
102
  ## Security
127
103
 
128
104
  - No secrets in SoT. The kit's SoT directories are committed; treat them as declarative config only.
129
105
  - 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.
130
106
  - **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.
107
+ - **Exemptions: the kit's own package 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. The existing omp marketplace plugin installs have no manifest pin: 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.
132
108
  ## Testing
133
109
 
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`.
110
+ 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` and `bun run smoke:native`.
135
111
 
136
112
  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.
137
113
 
@@ -145,7 +121,7 @@ Never rewrite published `main` history to correct a routing mistake. Use a follo
145
121
 
146
122
  ## Skills
147
123
 
148
- Project-skill and wrapper-agent authoring rules (scope, canonical layout, Windows symlinks, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
124
+ Project-skill authoring rules (scope, canonical layout, vendored `unslop`, citation constraint): `.agents/skills/AGENTS.md`.
149
125
 
150
126
  **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`).
151
127
 
@@ -228,10 +204,6 @@ No plan markdown is tracked. The pre-GitHub records under
228
204
  them as history, and no lifecycle command restores them. The complete contract
229
205
  lives in `docs/PLAN.md`; `docs/AGENTS.md` routes to it.
230
206
 
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.
234
-
235
207
  Plugin-internal work (skills, commands, agents) belongs in each plugin's
236
208
  own repo, not here.
237
209
 
@@ -248,27 +220,9 @@ cd ~/projects/public
248
220
  ./docks-kit harnesses # view or change this machine's flag-less sync selection
249
221
  ./docks-kit sync # sync this machine's harness selection (additive)
250
222
  ./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
223
+ ./docks-kit sync --prune # remove kit-recorded universal skills that SoT no longer lists
261
224
  ./docks-kit toolchain check # verify installed tools against SoT/toolchain.json floors
262
225
  ```
263
226
 
264
227
  On Windows, replace `./docks-kit` with `.\docks-kit.ps1` in these checkout
265
228
  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
@@ -5,7 +5,7 @@ Truth (SoT)** directories deploy to each tool's user-config location. Clone
5
5
  once to get a consistent AI-assisted environment on supported Linux, macOS,
6
6
  and Windows machines. Tuned for **token efficiency without sacrificing quality**.
7
7
 
8
- Supported harnesses: **Claude Code**, **Codex**, and **Oh My Pi (`omp`)**.
8
+ Supported harness: **Oh My Pi (`omp`)**.
9
9
  The kit also deploys [agentskills.io](https://agentskills.io) universal skills.
10
10
 
11
11
  ## Quick start
@@ -16,7 +16,7 @@ cd ~/projects/public
16
16
  ./docks-kit harnesses # choose this machine's flag-less sync harnesses
17
17
  ./docks-kit sync # deploy this machine's harness selection
18
18
  ./docks-kit sync omp # deploy omp explicitly
19
- ./docks-kit status # doctor view: drift, toolchain, plugins, skills
19
+ ./docks-kit toolchain # doctor view: verified-version floors for external tools
20
20
  ```
21
21
 
22
22
  POSIX hosts use the `./docks-kit` launcher on Linux x64 and arm64 and on macOS
@@ -44,18 +44,16 @@ launcher and installer use Invoke-WebRequest.
44
44
  ## CLI
45
45
 
46
46
  ```text
47
- docks-kit sync [claude] [codex] [agents] [omp] deploy explicit targets or the machine selection
47
+ docks-kit sync [agents] [omp] deploy explicit targets or the machine selection
48
48
  docks-kit harnesses view or change this machine's selection
49
49
  docks-kit update [--no-sync] self-update the kit (autodetects checkout vs global install), then sync
50
- docks-kit model <claude|codex> [value] get/set the DEPLOYED model (TTY picker)
51
- docks-kit models [claude|codex|omp] [--refresh] live catalogs for enabled harnesses (`--json`)
52
50
  docks-kit omp [--model <m>|--pick] [args...] one omp session on a free model, nothing deployed changes
53
51
  docks-kit omp --fast toggle omp fast mode for OpenAI/Codex models, then exit
54
- docks-kit toolchain [check|ensure <tool>|outdated|upgrade] verified-version floors for external tools
55
- docks-kit status [--json] deployed-vs-SoT drift + toolchain + counts
56
- docks-kit plugins list [--json] enabledPlugins tri-state vs installed
52
+ docks-kit toolchain [check|ensure <tool>|outdated] verified-version floors for external tools
57
53
  docks-kit skills list [--json] universal skills vs manifest
58
- docks-kit docs [topic] self-documentation (12 topics)
54
+ docks-kit scratch new|remove agent temporary files and directories
55
+ docks-kit tidy [--apply] [--report] remove safe agent leftovers
56
+ docks-kit docs [topic] self-documentation (9 topics)
59
57
  --help --version --wizard --completions built-in
60
58
  ```
61
59
 
@@ -77,54 +75,34 @@ here.
77
75
  | Flag | Effect |
78
76
  |------|--------|
79
77
  | `--dry-run` | Preview without applying |
80
- | `--reconcile` | Reconcile kit-owned settings toward SoT (user-only keys preserved) |
81
- | `--prune` | Uninstall kit-managed plugins/marketplaces/skills not in SoT |
82
- | `--claude-model=<m>` | Deploy-time modifier: deployed Claude model |
83
- | `--claude-compact-window=<n>` | Deploy-time modifier: autocompact window (`680k`) |
84
- | `--claude-permissive` | Deploy-time modifier: empty ask/deny (sandboxes only) |
85
- | `--claude-plugin=<name>` | Sticky opt-in plugin (supabase, n8n) |
86
- | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
87
- | `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
88
- | `--skip-plugin-refresh` | Install missing plugins but skip refresh-only updates |
89
-
90
- **Deploy-time modifiers** change deployed config only — the SoT is untouched
91
- and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
92
- (includes the old→new rename table for the pre-CLI `sync.sh` flags).
78
+ | `--prune` | Remove kit-managed universal skills not in `SoT/.agents/skills.txt` |
79
+ | `--skip-plugin-refresh` | Install missing omp plugins but skip refresh-only updates |
80
+ | `--verbose` | Also print no-op confirmations |
81
+
82
+ Full reference: `docks-kit docs flags` (includes the old→new rename table for
83
+ the pre-CLI `sync.sh` flags).
93
84
 
94
85
  ## How syncing works
95
86
 
96
87
  - **Additive by default** — user-only settings keys, plugins, and skills
97
- survive a plain sync. Reconciliation toward the SoT is explicit
98
- (`--reconcile` / `--prune`).
88
+ survive a plain sync. Removing kit-managed universal skills that left the
89
+ SoT is explicit (`--prune`).
99
90
  - **Per-machine selection** — `~/.docks-kit/kit.db` drives a flag-less sync.
100
- A missing selection selects Claude Code, Codex, and universal skills. It does not
101
- select omp. Use `docks-kit harnesses` to view or change the selection. With no
102
- stored selection, its picker pre-ticks every harness, omp included.
91
+ A missing selection selects universal skills and omp. Use
92
+ `docks-kit harnesses` to view or change the selection.
103
93
  - **Idempotent** — every step is safe to re-run; no-change syncs are no-ops.
104
94
  - **Toolchain floors** — `SoT/toolchain.json` records the kit-verified version
105
- floors for external tools (bun, bwrap, …). `docks-kit toolchain check` prints
95
+ floors for external tools (bun, omp, …). `docks-kit toolchain check` prints
106
96
  the full doctor table. Bun is the one managed install and is pinned to its
107
97
  verified version.
108
- - **Model catalog** — enabled harnesses provide live Claude, Codex, or omp
109
- model IDs; `SoT/models.json` supplies Claude and Codex aliases, notes, and the
110
- offline fallback. omp has no curated fallback list.
111
- - **Claude runtime** — sync materializes three dependency-free Bun `.mjs`
112
- programs for statusline, SessionStart, and Notification. Quota display uses
113
- Claude's native `rate_limits`; there is no OAuth fetch, shared usage cache,
114
- or Stop hook. If Bun cannot be resolved or bootstrapped, sync preserves a
115
- working legacy hook/statusline setup and reports that migration is deferred.
116
- - **Command guards** — omp, Claude Code, and Codex share one policy for
117
- destructive shell commands; to remove, agents use the trash
118
- (`gio trash -- <path>`, or `trash <path>` on macOS); omp agents remove a
119
- temporary file or directory with `docks-kit scratch remove`. `rm` of the
120
- home directory or `/` and `HOME` reassignment are denied. omp also denies
121
- every recursive `rm`, `find -delete`, `find -exec rm`, and `xargs rm`. The
122
- kit ships no omp prompt rule, so omp runs every command that no deny
123
- matches without a question, in subagents too. Claude Code and Codex ask
124
- before a recursive `rm`, `find -delete`, every `git rm`, `git clean`,
125
- `git reset --hard`, and any `git push` that could force; a Codex ask can go
126
- to its `auto_review` reviewer. Details, per-tool differences, and gaps:
127
- `docks-kit docs command-guards`.
98
+ - **Command guards** — omp's policy for destructive shell commands: to
99
+ remove, agents use the trash (`gio trash -- <path>`, or `trash <path>` on
100
+ macOS) or remove a temporary file or directory with
101
+ `docks-kit scratch remove`. omp denies `rm` of the home directory or `/`,
102
+ `HOME` reassignment, every recursive `rm`, `find -delete`, `find -exec rm`,
103
+ and `xargs rm`. The kit ships no omp prompt rule, so omp runs every command
104
+ that no deny matches without a question, in subagents too. Details and
105
+ gaps: `docks-kit docs command-guards`.
128
106
  - **Agent cleanup (omp)** — `docks-kit scratch` creates agent temporary
129
107
  directories and removes agent temporary files and directories with checked
130
108
  paths. `docks-kit tidy` lists merged idle worktrees, their containers,
@@ -137,19 +115,16 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
137
115
 
138
116
  | Path | Purpose |
139
117
  |------|---------|
140
- | `SoT/.claude/` | Claude Code SoT (settings template, Bun runtime programs, CLAUDE.md) |
141
- | `SoT/.codex/` | Codex SoT (config.toml, rules, AGENTS.md, marketplace) |
142
118
  | `SoT/.omp/` | omp SoT (AGENTS.md, config.yml, models.yml, mcp.json, intercom.json, and the `plugin/` source of `docks-kit-omp`) |
143
119
  | `SoT/.agents/` | Universal-skill manifest |
144
- | `SoT/models.json` | Curated aliases, notes, and offline Claude/Codex fallback |
145
120
  | `SoT/toolchain.json` | Verified-version floors |
146
- | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
121
+ | `cli/src/engine-native/` | EngineNative sync/toolchain implementation |
147
122
  | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
148
123
  | `cli/` | docks-kit CLI (Effect 4 on Bun) + bundled docs topics |
149
124
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers (binary → Bun-from-source) |
150
125
  | `install.sh` / `install.ps1` | POSIX and Windows global installers |
151
126
  | `docs/PLAN.md` | Plan record standard; plans are GitHub issues |
152
- | `AGENTS.md` / `.claude/rules/claude-code.md` | Agent-facing engineering rules / Claude Code specifics (path-scoped rule) |
127
+ | `AGENTS.md` | Agent-facing engineering rules |
153
128
 
154
129
  ## Platform support
155
130
 
@@ -176,9 +151,7 @@ are versioned config snapshots without shipping the authoring `SoT/` tree.
176
151
 
177
152
  ## Deeper docs
178
153
 
179
- - `docks-kit docs <topic>` - overview, sync-layers, flags, modifiers, models,
180
- omp-models, omp-context, command-guards, toolchain, plugins, install,
181
- platforms (works offline, bundled with the CLI)
154
+ - `docks-kit docs <topic>` - overview, sync-layers, flags, toolchain, install,
155
+ platforms, omp-models, omp-context, command-guards (works offline, bundled
156
+ with the CLI)
182
157
  - [`AGENTS.md`](AGENTS.md) — engineering rules for agents working on the kit
183
- - [`.claude/rules/claude-code.md`](.claude/rules/claude-code.md) — Claude Code specifics: env vars, session
184
- management, permission mode, open concerns