docks-kit 0.22.28 → 0.24.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 (93) hide show
  1. package/AGENTS.md +42 -89
  2. package/README.md +35 -72
  3. package/cli/docs/command-guards.md +233 -197
  4. package/cli/docs/flags.md +17 -65
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +27 -12
  8. package/cli/docs/overview.md +7 -18
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +14 -60
  11. package/cli/docs/toolchain.md +12 -81
  12. package/cli/src/argv.ts +0 -12
  13. package/cli/src/argvValidate.ts +3 -54
  14. package/cli/src/commands/docs.ts +3 -15
  15. package/cli/src/commands/omp.ts +1 -1
  16. package/cli/src/commands/scratch.ts +1 -1
  17. package/cli/src/commands/sync.ts +5 -120
  18. package/cli/src/commands/tidy.ts +1 -1
  19. package/cli/src/commands/toolchain.ts +4 -12
  20. package/cli/src/engine-native/DESIGN.md +69 -100
  21. package/cli/src/engine-native/deps.ts +7 -92
  22. package/cli/src/engine-native/engineCtx.ts +9 -103
  23. package/cli/src/engine-native/exec.ts +1 -18
  24. package/cli/src/engine-native/index.ts +6 -8
  25. package/cli/src/engine-native/jq.ts +4 -37
  26. package/cli/src/engine-native/kitDb.ts +21 -37
  27. package/cli/src/engine-native/modes.ts +3 -132
  28. package/cli/src/engine-native/ompFastMode.ts +1 -1
  29. package/cli/src/engine-native/ompOverlay.ts +1 -1
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +1 -1
  33. package/cli/src/engine-native/os/darwin.ts +0 -4
  34. package/cli/src/engine-native/os/index.ts +1 -2
  35. package/cli/src/engine-native/os/linux.ts +0 -3
  36. package/cli/src/engine-native/os/posix.ts +2 -47
  37. package/cli/src/engine-native/os/types.ts +1 -36
  38. package/cli/src/engine-native/os/windows.ts +0 -50
  39. package/cli/src/engine-native/parseArgs.ts +7 -180
  40. package/cli/src/engine-native/parseHelp.ts +4 -44
  41. package/cli/src/engine-native/scratch.ts +1 -1
  42. package/cli/src/engine-native/services.ts +1 -2
  43. package/cli/src/engine-native/sharedTypes.d.ts +1 -41
  44. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  45. package/cli/src/engine-native/syncDispatch.ts +30 -143
  46. package/cli/src/engine-native/toolchain.ts +6 -45
  47. package/cli/src/engine.ts +0 -75
  48. package/cli/src/generated/sotPayload.ts +14 -43
  49. package/cli/src/main.ts +8 -24
  50. package/cli/src/payload.ts +2 -8
  51. package/cli/tsconfig.json +1 -3
  52. package/package.json +3 -5
  53. package/cli/docs/models.md +0 -58
  54. package/cli/docs/modifiers.md +0 -52
  55. package/cli/docs/plugins.md +0 -70
  56. package/cli/src/checklistPrompt.ts +0 -464
  57. package/cli/src/commands/harnesses.ts +0 -80
  58. package/cli/src/commands/model.ts +0 -68
  59. package/cli/src/commands/models.ts +0 -75
  60. package/cli/src/commands/plugins.ts +0 -35
  61. package/cli/src/commands/skills.ts +0 -40
  62. package/cli/src/commands/status.ts +0 -206
  63. package/cli/src/efforts.ts +0 -89
  64. package/cli/src/engine-native/claudeLsp.ts +0 -301
  65. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  66. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  67. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  68. package/cli/src/engine-native/claudeRetired.ts +0 -165
  69. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  70. package/cli/src/engine-native/claudeSettings.ts +0 -201
  71. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  72. package/cli/src/engine-native/claudeSync.ts +0 -312
  73. package/cli/src/engine-native/codexConfig.ts +0 -214
  74. package/cli/src/engine-native/codexHooks.ts +0 -91
  75. package/cli/src/engine-native/codexPaths.ts +0 -14
  76. package/cli/src/engine-native/codexPlugins.ts +0 -315
  77. package/cli/src/engine-native/codexStatus.ts +0 -25
  78. package/cli/src/engine-native/codexSync.ts +0 -314
  79. package/cli/src/engine-native/codexToml.ts +0 -303
  80. package/cli/src/engine-native/harnesses.ts +0 -138
  81. package/cli/src/engine-native/liveModels.ts +0 -264
  82. package/cli/src/engine-native/models.ts +0 -101
  83. package/cli/src/engine-native/parseModifiers.ts +0 -225
  84. package/cli/src/engine-native/settings.ts +0 -42
  85. package/cli/src/engine-native/skillsInstall.ts +0 -135
  86. package/cli/src/engine-native/skillsLinks.ts +0 -216
  87. package/cli/src/engine-native/skillsManifest.ts +0 -36
  88. package/cli/src/engine-native/skillsPrune.ts +0 -117
  89. package/cli/src/engine-native/skillsRecords.ts +0 -138
  90. package/cli/src/engine-native/skillsSync.ts +0 -57
  91. package/cli/src/engine-native/tomlLines.ts +0 -92
  92. package/cli/src/manifests.ts +0 -145
  93. package/cli/src/terminalCells.ts +0 -191
package/cli/docs/flags.md CHANGED
@@ -1,63 +1,47 @@
1
1
  # Flag reference
2
2
 
3
- Convention: global flags are unprefixed; anything touching one tool's
3
+ Convention: global flags are unprefixed; a flag that touches one tool's
4
4
  deployed config is `--<tool>-<setting>`.
5
5
 
6
- ## Targets (positional)
6
+ ## Sync
7
7
 
8
8
  ```
9
- docks-kit sync # stored harness selection
10
- docks-kit sync claude # one
11
- docks-kit sync claude agents # two
12
- docks-kit sync omp # opt-in harness
9
+ docks-kit sync # deploy the omp SoT
10
+ docks-kit sync --dry-run # preview it
13
11
  ```
14
12
 
15
- Positional targets are `claude`, `codex`, `agents`, and `omp`. A flag-less
16
- `sync` deploys the per-machine harness selection stored in
17
- `~/.docks-kit/kit.db`. A missing selection or an unreadable store selects `claude`,
18
- `codex`, and `agents`, and never selects `omp`. Choose the stored selection
19
- with `docks-kit harnesses`. With no stored selection, its picker pre-ticks all
20
- four harnesses, `omp` included; a flag-less `sync` does not change until the
21
- picker saves a selection. In the picker, Enter or Space ticks or unticks the
22
- harness under the cursor, Enter on the Save row stores the selection, and
23
- Escape leaves it unchanged.
13
+ `sync` deploys the omp SoT and takes no positional argument. A word after
14
+ `sync`, such as `omp`, stops it with `Unexpected positional argument` and
15
+ exit 1.
24
16
 
25
17
  ## Global flags
26
18
 
27
19
  | Flag | Effect |
28
20
  |------|--------|
29
21
  | `--dry-run` | Preview without applying; takes no sync lock and no folder lock |
30
- | `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
31
- | `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, and the universal skills that `~/.agents/.kit-owned-skills` names |
32
- | `--skip-bubblewrap` | Skip optional bubblewrap bootstrap (Codex Linux sandbox) |
33
- | `--skip-plugin-refresh` | Install missing Claude, Codex, and omp plugins but skip refresh-only updates |
34
- | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
22
+ | `--skip-plugin-refresh` | Install missing omp plugins but skip refresh-only updates |
23
+ | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync` and `toolchain` |
35
24
 
36
25
  ## Environment overrides
37
26
 
38
27
  | Variable | Effect |
39
28
  |----------|--------|
40
- | `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
41
- | `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync`, a `model` write, and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
29
+ | `DOCKS_KIT_SYNC_LOCK_WAIT_MS=<ms>` | Time that `sync` and `omp --fast` wait for another sync to release a sync lock. A non-negative safe integer in milliseconds (at most `9007199254740991`); unset or empty means `120000` (120 s). Any other value prints `DOCKS_KIT_SYNC_LOCK_WAIT_MS must be a non-negative safe integer` and exits 2. |
42
30
 
43
31
  ## Sync lock
44
32
 
45
- `sync` and `model <tool> <value>` hold the lock
46
- `~/.cache/docks-kit/sync-lock.db` while they run, so two runs never write the
47
- same files at once.
33
+ `sync` holds the lock `~/.cache/docks-kit/sync-lock.db` while it runs, so two
34
+ runs never write the same files at once.
48
35
 
49
36
  - A run waits up to 120 s for another run to release the lock
50
37
  (`DOCKS_KIT_SYNC_LOCK_WAIT_MS` changes the wait). It then prints
51
38
  `another docks-kit sync holds <path>; run sync again after it ends` and
52
39
  exits 1 with no change.
53
- - Two homes can share a Codex folder (`CODEX_HOME`), an agents folder
54
- (`AGENTS_DIR`), or an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
40
+ - Two homes can share an omp folder (`PI_CODING_AGENT_DIR`, `PI_CONFIG_DIR`,
55
41
  `XDG_DATA_HOME`, or a symlink). So a writing sync also holds
56
- `.docks-kit-sync-lock.db` inside each such folder that it writes. For `codex`
57
- this is the Codex folder, and for `agents` the agents folder. For `omp` it is
58
- the omp agent folder, the intercom folder, and the omp data root. A
59
- `model codex <value>` write holds the Codex folder lock too. The held line
60
- then names that lock file.
42
+ `.docks-kit-sync-lock.db` inside each such folder that it writes: the omp
43
+ agent folder, the intercom folder, and the omp data root. The held line then
44
+ names that lock file.
61
45
  - A writing sync creates a missing folder of this set just before it takes the
62
46
  lock of that folder, after the locks of its ancestors in the set. Each folder
63
47
  that it creates gets mode 0700. The lock step does not change the mode of an
@@ -81,29 +65,11 @@ same files at once.
81
65
  wait and the held line are those of a sync.
82
66
  - A run with `--dry-run`, `-h`, or `--help` takes no lock. A dry run through
83
67
  the `DRY_RUN=1` env global of the private `native-raw` engine channel takes
84
- no lock either. `model <tool>` without a value only reads, so it takes no
85
- lock.
68
+ no lock either.
86
69
  - The lock goes when the run ends, also when the process is killed.
87
70
  - A held lock also delays the error of an invalid argument until the wait
88
71
  ends.
89
72
 
90
- ## Per-tool flags
91
-
92
- | Flag | Effect |
93
- |------|--------|
94
- | `--claude-model=<m>` | Deploy-time modifier: deployed model (aliases or full claude-* IDs; `default` unsets) |
95
- | `--claude-effort=<level>` | Deploy-time modifier: `effortLevel`; valid `low`, `medium`, `high`, `xhigh`, or `default` (Claude SoT: `high`) |
96
- | `--claude-advisor=<state>` | Deploy-time modifier: advisor `on`, `off`, or `default` (SoT off/unset) |
97
- | `--claude-compact-window=<n>` | Deploy-time modifier: autocompact window in tokens (`680000` or `680k`) |
98
- | `--claude-permissive` | Deploy-time modifier: empty permissions.ask/deny (sandboxes) |
99
- | `--claude-plugin=<name>` | Sticky opt-in plugin (known: supabase, n8n); comma-separate for several |
100
- | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
101
- | `--codex-effort=<level>` | Deploy-time modifier: `model_reasoning_effort`; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, or `default` (Codex SoT: `high`; model-dependent) |
102
-
103
- Bare model, effort, or advisor modifiers print the relevant valid-value catalog
104
- and exit 2. A modifier for a target not selected by the positional arguments is
105
- ignored with a warning; Claude modifiers never touch Codex config and vice versa.
106
-
107
73
  ## `omp` session flags
108
74
 
109
75
  | Flag | Effect |
@@ -157,17 +123,3 @@ forwarded `--model` stops the launcher with exit 2, also behind `--`.
157
123
  | `tidy --apply` | Take the lock `~/.cache/docks-kit/tidy-lock.db`, then plan, perform those actions, and append the outcomes to `~/.cache/docks-kit/tidy.log`; exit 1 when an action fails. When another run holds the lock, print only `another docks-kit tidy run holds <path>`, with no plan and no report, and exit 0. A dry run (`tidy` without `--apply`) and the `--report` sections take no lock |
158
124
  | `tidy --repo <path>` | Take the worktree candidates only from that repository, at any location |
159
125
  | `tidy --report` | After the plan, print read-only sections on memory, temporary directories, processes, Docker, caches, Trash, git, agent histories, scheduled jobs, and global installs |
160
-
161
- ## Renamed legacy flags (pre-CLI sync.sh)
162
-
163
- Old flags exit with a rename hint — there is no compat behavior.
164
-
165
- | Old | New |
166
- |-----|-----|
167
- | `--claude` / `--codex` / `--agents` | positional `claude` / `codex` / `agents` |
168
- | `--force` | `--reconcile` |
169
- | `--remove-plugins` | `--prune` |
170
- | `--680k` | `--claude-compact-window=680k` |
171
- | `--permissive` | `--claude-permissive` |
172
- | `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
173
- | `--skip-rtk` | `--skip-bubblewrap` |
@@ -23,7 +23,7 @@ bypasses an ignored stale build.
23
23
  bun add -g docks-kit@latest
24
24
  docks-kit sync
25
25
  # or one-shot, no install:
26
- bunx docks-kit status
26
+ bunx docks-kit toolchain check
27
27
  ```
28
28
 
29
29
  The npm package bundles the CLI and its generated in-memory payload — releases
@@ -159,8 +159,7 @@ sync/config reads.
159
159
  ## Prerequisites
160
160
 
161
161
  - Bun for source/global installs; release binaries embed the runtime
162
- - Node/npm for npm-global LSP servers
163
- - rustup is optional and needed only for the Rust language server
162
+ - npm for an npm-installed kit
164
163
  - jq is optional doctor/test tooling; sync has no jq runtime dependency
165
164
  - curl is needed only to download Bun's upstream installer when Bun is absent:
166
165
  by the POSIX `docks-kit` launcher, by the POSIX `install.sh`, and by sync's
@@ -1,7 +1,9 @@
1
1
  # omp context and compaction
2
2
 
3
3
  This topic records why `SoT/.omp/config.yml` ships no compaction threshold,
4
- and what omp's reserve-based default computes on each model lane.
4
+ and what omp's reserve-based default computes on each model lane. It also
5
+ records the omp 19.0.0 tools that the kit turns on and the kit overrides that
6
+ 0.24.0 returned to the omp defaults.
5
7
 
6
8
  ## How omp resolves the trigger
7
9
 
@@ -100,13 +102,13 @@ No current role model has a window below 272,000, so the hazard was latent
100
102
  rather than live. Not pinning removes it entirely, including for any future
101
103
  model with a smaller window.
102
104
 
103
- ## Idle compaction is a kit-set value
105
+ ## Idle compaction is off
104
106
 
105
- `SoT/.omp/config.yml` sets `compaction.idleEnabled: true`. The omp default is
106
- `false` in omp 18.4.4 through 18.10.4. Idle compaction fires below the
107
- reserve-based trigger on both lanes. A compaction whose reason is `idle`
108
- skips the progress guard. Keep the key. The merge is additive, so a dropped
109
- key turns idle compaction off on fresh installs.
107
+ Up to 0.23.0, `SoT/.omp/config.yml` set `compaction.idleEnabled: true`. In
108
+ 0.24.0 the owner returned the key to the omp default `false` (omp 18.4.4
109
+ through 19.0.0). Sync prunes a deployed `true` that the kit shipped, so idle
110
+ compaction is off. With the default threshold settings, only the
111
+ reserve-based trigger starts a compaction.
110
112
 
111
113
  ## Related settings left at their omp defaults
112
114
 
@@ -119,3 +121,73 @@ key turns idle compaction off on fresh installs.
119
121
 
120
122
  Every row records a decision to leave the omp default in place. None of these
121
123
  keys carries a kit value that differs from the default omp already applies.
124
+
125
+ ## omp 19.0.0 tools and returned overrides
126
+
127
+ The owner made these decisions on 2026-11-19 (#184). They apply from 0.24.0.
128
+
129
+ ### Tools that the kit turns on
130
+
131
+ - `astGrep.enabled: true` gives the `ast_grep` tool. It searches code by its
132
+ syntax tree (AST), on the local disk only.
133
+ - `checkpoint.enabled: true` gives the `checkpoint` and `rewind` tools.
134
+ `checkpoint` marks the start of an investigation. `rewind` replaces the
135
+ transcript after that mark with a short report. It restores no file, git
136
+ state, artifact, or process, and a rule line in `SoT/.omp/AGENTS.md` says
137
+ so. A subagent gets the two tools only when its tool list asks for one of
138
+ them.
139
+
140
+ The memory backend (`memory.backend: off`), `autolearn.enabled`, and
141
+ `prewalk.enabled` stay off. All three are off by default, so the SoT has no
142
+ key for them. Every other omp 19.0.0 feature keeps its omp default, for
143
+ example context notes, `security_scan`, `task.crossInstance`,
144
+ `mcp.evalNamespaces`, and cache warming. The advisor stays removed (0.22.22).
145
+
146
+ ### Overrides returned to the omp defaults
147
+
148
+ The SoT no longer ships these 18 keys. `ompRemovals.ts OMP_RETIRED_VALUES`
149
+ records each key with its old kit value. Sync prunes a deployed key only
150
+ while it holds that value, so a value that you changed stays.
151
+
152
+ | Key | Old kit value | omp 19.0.0 default |
153
+ |---|---|---|
154
+ | `task.maxConcurrency` | `16` | `32` |
155
+ | `task.maxEffort` | `xhigh` | `max` |
156
+ | `task.maxRuntimeMs` | `3600000` | `0` |
157
+ | `task.agentIdleTtlMs` | `120000` | `420000` |
158
+ | `task.enableLsp` | `true` | `false` |
159
+ | `task.eager` | `always` | `default` |
160
+ | `task.showResolvedModelBadge` | `true` | `false` |
161
+ | `find.enabled` | `true` | `auto` |
162
+ | `providers.webSearchTimeoutSeconds` | `30` | `60` |
163
+ | `browser.idleCloseSec` | `600` | `1800` |
164
+ | `steeringMode` | `all` | `one-at-a-time` |
165
+ | `doubleEscapeAction` | `tree` | `rewind` |
166
+ | `features.unexpectedStopDetection` | `smart` | `mechanical` |
167
+ | `compaction.idleEnabled` | `true` | `false` |
168
+ | `compaction.handoffSaveToDisk` | `true` | `false` |
169
+ | `commands.enableOpencodeProject` | `false` | `true` |
170
+ | `statusLine.compactThinkingLevel` | `false` | `true` |
171
+ | `github.enabled` | `true` | `false` |
172
+
173
+ Sync cannot tell the old kit value from the same value that you set again.
174
+ It prunes both on every sync. To keep an old kit value, set it in a project
175
+ configuration or in a `PI_CONFIG_FILES` file, which sync does not write.
176
+
177
+ The `github` tool is off by default. Its `pr_push` operation runs git
178
+ directly, so the `bash.patterns` guards do not see it. The `issue://` and
179
+ `pr://` read schemes do not need the tool. omp reads them through its GitHub
180
+ cache and `gh` (`omp://tools/read.md`, `omp://tools/github.md`), so they still
181
+ work with `github.enabled: false`. The plan-lifecycle work reads issues with
182
+ `gh` in bash, so the change does not affect it.
183
+
184
+ ### Overrides that stay
185
+
186
+ - `branchSummary.enabled: true`.
187
+ - `dev.autoqa: false` with `dev.autoqaConsent: denied`.
188
+ - `codexResets.autoRedeem5h: "no"` and `codexResets.autoRedeemWeekly: "no"`.
189
+ - `startup.quiet: true`.
190
+ - `display.showTokenUsage: true`.
191
+ - The model roles, `cycleOrder`, `retry.fallbackChains`, `modelTags`, the
192
+ reviewer overrides in `task.agentModelOverrides` and
193
+ `task.agentServiceTierOverrides`, and the `bash.patterns` guards.
@@ -102,6 +102,15 @@ Terra and no GPT-6.2 Luna. To recheck, run `omp models openai-codex`; the
102
102
  without a catalog check. On an omp release without these ids, omp can resolve
103
103
  them by fuzzy match to another model without a warning, as on 2026-09-22.
104
104
 
105
+ On 2026-11-19, omp 19.0.0 became the toolchain floor and verified pin. Its
106
+ `omp models --json` catalog listed each of the 12 model selectors of
107
+ `modelRoles` and `retry.fallbackChains` (the `web/` entries left out) as an
108
+ exact `provider/id` row, so no role depends on a fuzzy match. This check read
109
+ the catalog only; it ran no model request. The rows also carry the fields that
110
+ the free launcher reads (`ompOverlay.ts parseFreeModels`): a string
111
+ `selector`, a `cost` object with numeric `input` and `output`, a numeric
112
+ `contextWindow`, and a `thinking` ladder array or `null`.
113
+
105
114
  What omp's settings catalog establishes about these roles:
106
115
 
107
116
  - `cycleOrder` lists the roles the model switcher cycles. `fable` is the
@@ -647,13 +656,15 @@ keeps a block that the user edited.
647
656
  not onto level names: `lo` selects the lowest level, `med` the lower middle,
648
657
  and `hi` the highest (`resolveTaskEffortLevel` in omp's
649
658
  `packages/tui/src/thinking.ts`, omp 18.8.5). Then omp caps the result at
650
- `task.maxEffort`. On the `low, medium, high, xhigh, max` ladder, `hi` gave
651
- `xhigh` under the `xhigh` cap, so many `task` spawns ran Opus 5.5 xhigh
652
- despite the `:high` role suffix. On 2026-11-05, a fresh `omp -p` run on omp
653
- 18.16.0 with the field off had no `effort` field, and its `task` child
654
- recorded `resolvedModel: anthropic/claude-opus-5-5:high`.
655
- - `task.maxEffort` is `xhigh`. With `task.enableEffort` off, the cap applies
656
- only to a per-call `model` with a `:level` suffix.
659
+ `task.maxEffort`. Up to 0.23.0 the kit set that cap to `xhigh`. On the
660
+ `low, medium, high, xhigh, max` ladder, `hi` then gave `xhigh`, so many
661
+ `task` spawns ran Opus 5.5 xhigh despite the `:high` role suffix. On
662
+ 2026-11-05, a fresh `omp -p` run on omp 18.16.0 with the field off had no
663
+ `effort` field, and its `task` child recorded
664
+ `resolvedModel: anthropic/claude-opus-5-5:high`.
665
+ - Since 0.24.0 the kit sets no `task.maxEffort`, so the cap is omp's default
666
+ `max`. With `task.enableEffort` off, the cap applies only to a per-call
667
+ `model` with a `:level` suffix.
657
668
  - In the deployed config, `scout` and `sonic` run GPT-6 Luna `medium`. The
658
669
  four reviewer agents resolve `@reviewer` and run GPT-6.1 Terra `high` on the
659
670
  live tier of the main session. A `docks-kit omp` free session replaces
@@ -693,9 +704,10 @@ web-search provider order therefore applies, and that order includes the paid
693
704
  deployed retry chain, such as a `plan`, `slow`, or `designer` chain, therefore
694
705
  stays in the merged config. A retry of the free model does not reach such a
695
706
  chain, because omp uses the empty chain keyed by the free model first.
696
- The overlay also sets `defaultThinkingLevel` and `task.maxEffort`, except for
697
- a model that publishes no thinking ladder, where both keys are omitted and the
698
- deployed or omp default values apply.
707
+ The overlay also sets `defaultThinkingLevel` and `task.maxEffort` to the
708
+ session level. For a model that publishes no thinking ladder, the overlay
709
+ omits both keys. A value in the deployed config then applies, or else the omp
710
+ default, which is `max` for `task.maxEffort`.
699
711
 
700
712
  The launcher renders a run overlay to
701
713
  `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` at mode 0600 and passes it
@@ -791,7 +803,7 @@ bare selectors with no `:level` suffix, because an invented level makes omp
791
803
  fail when the session starts.
792
804
 
793
805
  The choice persists per machine in `~/.docks-kit/kit.db` (table
794
- `omp_session`), next to the harness selection. It survives across sessions. It is never
806
+ `omp_session`). It survives across sessions. It is never
795
807
  committed. `--model <selector>` records one selector and derives the level
796
808
  from the catalog row. `--pick` opens an interactive wizard.
797
809
 
@@ -906,4 +918,7 @@ on normal processing, use `docks-kit omp --fast` and a new session, not
906
918
  - Update the capture date in the same commit as any number.
907
919
  - Verify Astra ladder changes in `SoT/.omp/models.yml` through the model
908
920
  switcher and in-session thinking control.
909
- - Verify `task.maxEffort` changes with a fresh `omp -p` spawn per bundled agent.
921
+ - The kit leaves `task.maxEffort` and `task.enableEffort` at omp's defaults,
922
+ `max` and `false`. After an omp update, check both in
923
+ `omp config list --json`. Verify a kit change to either key with a fresh
924
+ `omp -p` spawn per bundled agent.
@@ -1,22 +1,18 @@
1
1
  # docks-kit overview
2
2
 
3
- docks-kit is a portable configuration kit for AI coding agents. Per-tool
4
- Single Source of Truth (SoT) directories are deployed to each tool's
5
- user-config location — clone once, sync everywhere, get a consistent
3
+ docks-kit is a portable configuration kit for AI coding agents. Its Single
4
+ Source of Truth (SoT) directory `SoT/.omp/` deploys to the user-config location
5
+ of Oh My Pi (`omp`). Clone once, sync everywhere, and get a consistent
6
6
  AI-assisted dev environment on every machine.
7
7
 
8
8
  ## Pieces
9
9
 
10
10
  | Piece | Role |
11
11
  |-------|------|
12
- | `SoT/.claude/` | Claude Code config (settings template, Bun runtime programs, CLAUDE.md) |
13
- | `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
14
- | `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
15
12
  | `SoT/.omp/` | omp config deployed to `~/.omp/agent/` (AGENTS.md, config.yml, models.yml, mcp.json) plus `intercom.json` for pi intercom, plus the `plugin/` tree, deployed to `~/.docks-kit/omp-plugin` and linked as the `docks-kit-omp` omp plugin |
16
- | `SoT/models.json` | Curated Claude and Codex aliases, notes, and offline fallback for the live model lists (see `docks-kit docs models`) |
17
13
  | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
18
14
  | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
19
- | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain and the `docks-kit omp` session overlay |
15
+ | `cli/src/engine-native/` | EngineNative mutation logic for sync/toolchain and the `docks-kit omp` session overlay |
20
16
  | `cli/` | This CLI (Effect 4 on Bun) plus bundled docs |
21
17
  | `docks-kit` / `docks-kit.ps1` | POSIX and Windows launchers: version-matching compiled binary → Bun-from-source, with Bun auto-install |
22
18
 
@@ -26,21 +22,14 @@ AI-assisted dev environment on every machine.
26
22
  - **Quiet on no-ops**: by default a re-run prints only real changes, warnings
27
23
  (with a platform-correct install command when a tool is missing), and the
28
24
  summary; `--verbose` / `-v` also prints the no-op confirmations.
29
- - **Additive by default**: user-only keys/plugins/skills survive a plain sync.
30
- Reconciliation toward the SoT is explicit: `--reconcile` (settings) and
31
- `--prune` (plugins/marketplaces/skills).
32
- - **Deploy-time modifiers** mutate deployed config only — the SoT never
33
- changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
25
+ - **Additive by default**: user-only keys and plugins survive a plain sync.
34
26
  - **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
35
27
  EngineNative owns mutation. No-Bun recovery is a platform release binary.
36
28
  - **Authoring/runtime split**: changes begin in `SoT/`; build/prepack freshness
37
29
  checks keep the generated in-memory payload byte-identical for every runtime.
38
- - **Native Claude runtime**: three dependency-free Bun `.mjs` programs own the
39
- statusline, SessionStart, and Notification. Quotas come only from native
40
- `rate_limits`; missing Bun defers cutover without deleting legacy fallbacks.
41
30
 
42
31
  ## Where to go next
43
32
 
44
33
  - `docks-kit docs sync-layers` — what a sync actually touches
45
- - `docks-kit docs flags` — full flag reference + old→new renames
46
- - `docks-kit status` — live doctor view of this machine
34
+ - `docks-kit docs flags` — full flag reference
35
+ - `docks-kit toolchain` — doctor view of this machine's external tools
@@ -18,7 +18,7 @@ Rosetta reports `x86_64` and gets the unsupported-host message, so run
18
18
  docks-kit from a native arm64 shell.
19
19
 
20
20
  EngineNative is the only supported engine on supported hosts.
21
- When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`,
22
- `model`, `toolchain`, `status`) exit 2 with the removed-engine message. The
21
+ When `DOCKS_KIT_ENGINE=bash` is set, the commands that run the engine (`sync`
22
+ and `toolchain`) exit 2 with the removed-engine message. The
23
23
  message points at the `bash-engine-final` tag for historical recovery. Other
24
24
  commands ignore the variable.
@@ -1,59 +1,12 @@
1
1
  # Sync layers
2
2
 
3
- `docks-kit sync [claude] [codex] [agents] [omp]` — targets are positional
4
- words; no target means this machine's harness selection in
5
- `~/.docks-kit/kit.db`. The default is `claude codex agents`, and
6
- `docks-kit harnesses` changes it.
7
-
8
- ## claude (→ ~/.claude, ~/.claude.json, shell rc)
9
-
10
- Order matters — runtime readiness and settings form one transaction:
11
-
12
- 1. Resolve/bootstrap pinned Bun, materialize the sentinel settings template,
13
- and prepare the merged settings bytes without mutation. If Bun remains
14
- unavailable, omit only the new runtime pointers and preserve legacy ones.
15
- 2. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
16
- `bin/notify.mjs`, and `notification.mp3`; deploy CLAUDE.md; atomically commit
17
- settings.
18
- 3. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
19
- unioned, user-only keys survive. `--reconcile` replaces permissions arrays
20
- wholesale instead.
21
- 4. **Removed-artifact pruning** — prune old shell assets, the Stop hook, stale
22
- kit-owned settings, retired kit-owned plugin enablement, and every
23
- manifest-listed kit-owned `~/.local/bin` command. A flag-less sync removes
24
- `advisorModel`; an explicit advisor state excludes only that key so the
25
- modifier owns it.
26
- 5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
27
- `--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
28
- 6. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
29
- export.
30
- 7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
31
- (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
32
- SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
33
- 8. LSP server binaries (npm globals plus the rust-analyzer rustup component).
34
-
35
- The statusline reads Claude's native `rate_limits`. There is no OAuth request,
36
- usage cache, jq/curl runtime dependency, or Stop fetch hook.
37
-
38
- ## codex (→ Codex home, ~/.agents/plugins)
39
-
40
- bubblewrap bootstrap (Linux): when `bwrap` is missing, sync runs
41
- `sudo apt-get|dnf|pacman|zypper install bubblewrap` (a sudo prompt may appear)
42
- and then probes unprivileged user namespaces; `--skip-bubblewrap` only warns,
43
- and `--dry-run` only prints the step. Then config.toml merge (top-level keys
44
- replaced per-key, [table] blocks replaced wholesale, user-only keys/tables
45
- preserved, and retired kit-owned `[plugins."<id>"]` tables stripped),
46
- `--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
47
- marketplace file, and `codex plugin add` refresh.
48
-
49
- The Codex home is `$CODEX_HOME` when that variable is set and not empty, else
50
- `~/.codex`. Like Codex, the kit resolves a relative `CODEX_HOME` against the
51
- current directory. Every kit read or write of Codex state uses this directory.
52
-
53
- ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
54
-
55
- `npx skills add` per missing manifest slug, Claude symlink healing, and the
56
- kit-managed snapshot that `--prune` reconciles against.
3
+ `docks-kit sync` deploys the omp SoT. It takes no positional target. Sync
4
+ writes no `.agents` or `.claude` folder of its own; omp's folders follow
5
+ `PI_CONFIG_DIR`, `PI_CODING_AGENT_DIR`, and `XDG_DATA_HOME`, so an override
6
+ that points into one of those folders makes omp's files go there. omp uses
7
+ `XDG_DATA_HOME` only on Linux and macOS, only while `PI_CODING_AGENT_DIR`
8
+ does not move the agent folder, and only after the omp folder under it
9
+ exists. Sync also writes the kit plugin to `~/.docks-kit/omp-plugin`.
57
10
 
58
11
  ## omp (→ resolved agent dir, intercom root)
59
12
 
@@ -64,8 +17,8 @@ deployed-only keys survive; config.yml also drops stale slash-bearing
64
17
  config.yml `bash.patterns`: the merge keeps user rules and groups all rules as
65
18
  kit deny, user deny, user prompt, kit prompt (the kit ships none since 0.22.8),
66
19
  other user rules, and kit allow, so no allow loosens a deny or a prompt (see
67
- `docks-kit docs command-guards`). After each merge, every sync (no
68
- `--reconcile` needed) force-prunes the `ompRemovals.ts` retired-key inventory:
20
+ `docks-kit docs command-guards`). After each merge, every sync (no flag
21
+ needed) force-prunes the `ompRemovals.ts` retired-key inventory:
69
22
  the retired kit `bash.patterns` rules in `OMP_RETIRED_BASH_RULES` (exact
70
23
  `match` and `approval` pairs, including the 492 former kit prompt rules
71
24
  retired in 0.22.8), config.yml keys whose deployed value still equals the value the kit used to
@@ -164,8 +117,9 @@ into `<agent directory>/intercom`. Otherwise it goes into
164
117
  `$PI_CODING_AGENT_DIR/intercom` when that variable is set, else
165
118
  `~/.pi/agent/intercom`.
166
119
 
167
- ## Reconcile flags
120
+ ## Additive by default
168
121
 
169
- - `--reconcile` — settings layer: SoT-declared keys win; user-only preserved.
170
- - `--prune` — plugins + marketplaces + kit-managed skills not in SoT are removed.
171
- - Combine for a full reset to the SoT's kit-managed scope.
122
+ Sync has no removal flag. A key, plugin, or file that only the user added
123
+ stays. Two passes remove kit content on every sync: the `ompRemovals.ts`
124
+ retired-key inventory above, and the kit plugin pass, which removes stale
125
+ files from the kit-owned `~/.docks-kit/omp-plugin`.
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Field | Meaning |
6
6
  |-------|---------|
7
- | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool: `npx` for `skills-cli`, `omp install` for `pi-intercom`; the optional `via` field names that tool in the doctor table, and the default is `npx`) |
7
+ | `kind` | `check` (doctor visibility) / `managed` (kit-managed install) / `pin` (no binary — a version pin for a package that the kit installs through another tool, such as `omp install` for `pi-intercom`; the required `via` field names that tool in the doctor table) |
8
8
  | `policy` | Installation policy; `present` installs when missing and never upgrades |
9
9
  | `floor` | Minimum acceptable version shown in the doctor table |
10
10
  | `verified` | Last kit-tested version and the exact pin for kit-driven installs |
@@ -19,7 +19,7 @@ Their generated Bun floor is intentionally separate from the generated `verified
19
19
 
20
20
  - **bun** — policy `present`: installed from the pinned `verified` release and
21
21
  never auto-upgraded. `bun.ts` `bunBootstrap` owns one per-engine-run memo
22
- shared by the Claude runtime and direct `toolchain ensure bun` on every
22
+ shared by the omp pipeline and direct `toolchain ensure bun` on every
23
23
  supported host. The POSIX modules download `install.sh` with curl and run it
24
24
  with Bash. The Windows module downloads `install.ps1` with curl and runs it
25
25
  through `powershell.exe`. When Bun is already present, `toolchain ensure bun`
@@ -29,84 +29,17 @@ jq and curl are `check` rows, not global prerequisites. jq is not consumed by
29
29
  normal sync. curl is checked only when a requested Bun bootstrap must download
30
30
  an installer. An already-present Bun skips that download on every host.
31
31
 
32
- ## Node floor
33
-
34
- `node` stays a `check` row and now carries a floor of 22.22.2. The floor comes
35
- from `typescript-language-server` 6's `engines` field. The kit installs that
36
- server as an npm global for the `typescript-lsp` plugin, so an older Node runs
37
- a server its own manifest rejects. `docks-kit toolchain check` prints
38
- `below-floor` for a Node older than 22.22.2. The sync pass reads the same
39
- floor: it skips the `typescript-language-server` install on such a host, warns
40
- with the host Node version, and installs the other language servers.
41
- `docks-kit toolchain upgrade` also reads the floor: it skips the
42
- `typescript-language-server` upgrade on such a host and warns. Nothing else
43
- consults the floor, so a host below it still runs every other kit operation.
44
-
45
- ## rust-analyzer: no floor, no pin
46
-
47
- `rust-analyzer` is a `check` row with no floor and no `verified` pin. The kit
48
- installs the component with `rustup component add rust-analyzer` for the
49
- `rust-analyzer-lsp` plugin, so the version follows the host Rust toolchain. A
50
- pin would claim control the kit does not have, the stance `bubblewrap` already
51
- takes for a tool the kit does not publish. `docks-kit toolchain check` reports
52
- the installed version and judges nothing.
53
-
54
- ## Language-server upgrades
55
-
56
- `claudeLsp.ts syncLspServers` installs `intelephense`, `typescript-language-server`,
57
- `typescript`, and `rust-analyzer` only when the binary is missing. It never
58
- upgrades a server that is already present. A `verified` bump therefore reaches
59
- a fresh host immediately and leaves an existing install alone.
60
-
61
- The rustup channel follows the same rule. Sync adds the component only when the
62
- `rust-analyzer` binary is missing or is a rustup proxy that cannot run because
63
- the component is not installed. When `rust-analyzer --version` does not answer
64
- within 60 s, sync warns, stops the probe, and does not add the component on that
65
- run. `rustup update` is the user's remedy for an old component.
66
-
67
- A server below its `floor` shows as `below-floor` in `docks-kit toolchain check`.
68
- A server at or above its floor but below its `verified` pin shows as `ok`.
69
- To move every npm server that is below its `verified` pin to that pin, run:
70
-
71
- ```bash
72
- docks-kit toolchain upgrade --dry-run # print the npm command
73
- docks-kit toolchain upgrade # run it
74
- ```
75
-
76
- `toolchain upgrade` (`claudeLsp.ts upgradeLspServers`) reads `npm ls -g` to see
77
- which of `intelephense`, `typescript-language-server`, and `typescript` npm
78
- owns. It runs one `npm install -g` command that names every npm-owned package
79
- below its pin as `<pkg>@<verified>`. A package already at or above its pin
80
- stays as it is. It leaves
81
- these alone and warns:
82
-
83
- - A binary on PATH that npm does not own. It came from another installer, so
84
- upgrade it with that installer.
85
- - `typescript-language-server` when Node is older than the `node` floor.
86
-
87
- When the PATH copy of an npm-owned server is outside `npm prefix -g`, it warns
88
- that the upgrade changes only the npm copy. The check follows links and
89
- accepts only a file inside the package directory
90
- (`<prefix>/lib/node_modules/<pkg>` on POSIX), so a link from another PATH
91
- directory into it counts as the npm copy, while a distro binary under a
92
- `/usr` prefix does not. On Windows, a shim in `<prefix>` counts. A package that is not installed
93
- stays missing, because `sync claude` owns first installs. A failed npm call
94
- exits 1. After the install, it reads `npm ls -g` again and exits 1 when a
95
- package is not at its pin.
96
-
97
32
  ## Supply-chain stance
98
33
 
99
- Every kit-driven package install from npm, npx, GitHub releases, or
34
+ Every kit-driven package install from npm, GitHub releases, or
100
35
  `omp install` is pinned to a `SoT/toolchain.json` `verified` version — never
101
36
  floating `@latest` (the npm-worm / Shai-Hulud attack surface). That includes
102
- the `npx skills@<verified>` invocations on agents sync and the release workflow
103
- (actions pinned to commit SHAs, exact bun/npm versions). Two installs follow
104
- the host toolchain and have no pin: `rust-analyzer` (rustup) and `bubblewrap`
105
- (distro package manager). The existing Claude Code, Codex, and omp marketplace
106
- plugins have no manifest pin either: sync installs and refreshes them at the
107
- version that their marketplace publishes (see `plugins`). Any new install
108
- surface, a new marketplace or plugin source included, needs a manifest pin
109
- first.
37
+ the release workflow (actions pinned to commit SHAs, exact bun/npm versions).
38
+ The existing omp
39
+ marketplace plugins have no manifest pin: sync installs and refreshes them at
40
+ the version that their marketplace publishes (see `sync-layers`). Any new
41
+ install surface, a new marketplace or plugin source included, needs a
42
+ manifest pin first.
110
43
 
111
44
  The kit's own package is the single exemption from the `@latest` ban. `install.sh` and `install.ps1`
112
45
  end with `bun add -g docks-kit@latest` because a global installer that pinned
@@ -117,17 +50,15 @@ manifest's `verified` version.
117
50
  ## Commands
118
51
 
119
52
  ```text
120
- docks-kit toolchain check # doctor table (also inside docks-kit status)
53
+ docks-kit toolchain check # doctor table
121
54
  docks-kit toolchain ensure bun # ensure the only managed tool
122
55
  docks-kit toolchain ensure bun --dry-run # preview the Bun install
123
56
  docks-kit toolchain outdated [--refresh] # verified pins vs newest upstream release
124
- docks-kit toolchain upgrade [--dry-run] # npm LSP servers below verified -> verified
125
57
  ```
126
58
 
127
59
  `docks-kit toolchain outdated` reads each tool's optional `upstream` entry in
128
- `SoT/toolchain.json`. An `npm` entry reads the registry `latest` tag. With a
129
- `line`, it reads the newest release on that major line instead, so `tsc` stays
130
- on 6.x. A `github` entry reads the latest release tag and strips `tagPrefix`.
60
+ `SoT/toolchain.json`. An `npm` entry reads the registry `latest` tag. A
61
+ `github` entry reads the latest release tag and strips `tagPrefix`.
131
62
  Set `GITHUB_TOKEN` or `GH_TOKEN` to raise the GitHub rate limit. Successful
132
63
  lookups cache for 24 hours in `~/.docks-kit/kit.db`; `--refresh` bypasses the
133
64
  cache. The report never installs anything and never edits a pin. A failed