docks-kit 0.1.0

package/SoT/.codex/rules/docks.rules

@@ -0,0 +1,116 @@
+prefix_rule(pattern=["pwd"], decision="allow")
+prefix_rule(pattern=["ls"], decision="allow")
+prefix_rule(pattern=["cat"], decision="allow")
+prefix_rule(pattern=["head"], decision="allow")
+prefix_rule(pattern=["tail"], decision="allow")
+prefix_rule(pattern=["wc"], decision="allow")
+prefix_rule(pattern=["nl"], decision="allow")
+prefix_rule(pattern=["grep"], decision="allow")
+prefix_rule(pattern=["sort"], decision="allow")
+prefix_rule(pattern=["uniq"], decision="allow")
+prefix_rule(pattern=["diff"], decision="allow")
+prefix_rule(pattern=["which"], decision="allow")
+prefix_rule(pattern=["date"], decision="allow")
+prefix_rule(pattern=["basename"], decision="allow")
+prefix_rule(pattern=["dirname"], decision="allow")
+prefix_rule(pattern=["realpath"], decision="allow")
+prefix_rule(pattern=["readlink"], decision="allow")
+prefix_rule(pattern=["jq"], decision="allow")
+prefix_rule(pattern=["tree"], decision="allow")
+prefix_rule(pattern=["cut"], decision="allow")
+prefix_rule(pattern=["tr"], decision="allow")
+prefix_rule(pattern=["echo"], decision="allow")
+prefix_rule(pattern=["printf"], decision="allow")
+prefix_rule(pattern=["printenv"], decision="allow")
+prefix_rule(pattern=["uname"], decision="allow")
+prefix_rule(pattern=["file"], decision="allow")
+prefix_rule(pattern=["stat"], decision="allow")
+prefix_rule(pattern=["du"], decision="allow")
+prefix_rule(pattern=["id"], decision="allow")
+prefix_rule(pattern=["whoami"], decision="allow")
+
+prefix_rule(pattern=["git", "status"], decision="allow")
+prefix_rule(pattern=["git", "diff"], decision="allow")
+prefix_rule(pattern=["git", "log"], decision="allow")
+prefix_rule(pattern=["git", "show"], decision="allow")
+prefix_rule(pattern=["git", "blame"], decision="allow")
+prefix_rule(pattern=["git", "rev-parse"], decision="allow")
+prefix_rule(pattern=["git", "ls-files"], decision="allow")
+prefix_rule(pattern=["git", "grep"], decision="allow")
+prefix_rule(pattern=["git", "ls-tree"], decision="allow")
+prefix_rule(pattern=["git", "branch", "--show-current"], decision="allow")
+prefix_rule(pattern=["git", "branch", "-vv"], decision="allow")
+prefix_rule(pattern=["git", "mv"], decision="allow")
+
+prefix_rule(pattern=["gh", "pr", "view"], decision="allow")
+prefix_rule(pattern=["gh", "pr", "list"], decision="allow")
+prefix_rule(pattern=["gh", "pr", "diff"], decision="allow")
+prefix_rule(pattern=["gh", "pr", "status"], decision="allow")
+prefix_rule(pattern=["gh", "pr", "checks"], decision="allow")
+
+prefix_rule(pattern=["docker", "ps"], decision="allow")
+
+prefix_rule(pattern=["git", "push"], decision="prompt")
+prefix_rule(pattern=["git", "reset"], decision="prompt")
+prefix_rule(pattern=["git", "clean"], decision="prompt")
+prefix_rule(pattern=["git", "merge"], decision="prompt")
+prefix_rule(pattern=["git", "rebase"], decision="prompt")
+prefix_rule(pattern=["git", "checkout"], decision="prompt")
+
+prefix_rule(pattern=["rm"], decision="prompt")
+prefix_rule(pattern=["mv"], decision="prompt")
+prefix_rule(pattern=["chmod"], decision="prompt")
+prefix_rule(pattern=["chown"], decision="prompt")
+prefix_rule(pattern=["kill"], decision="prompt")
+prefix_rule(pattern=["pkill"], decision="prompt")
+
+prefix_rule(pattern=["npm", "install"], decision="prompt")
+prefix_rule(pattern=["npm", "uninstall"], decision="prompt")
+prefix_rule(pattern=["pnpm", "add"], decision="prompt")
+prefix_rule(pattern=["pnpm", "remove"], decision="prompt")
+prefix_rule(pattern=["yarn", "add"], decision="prompt")
+prefix_rule(pattern=["yarn", "remove"], decision="prompt")
+prefix_rule(pattern=["pip", "install"], decision="prompt")
+prefix_rule(pattern=["pip", "uninstall"], decision="prompt")
+prefix_rule(pattern=["pip3", "install"], decision="prompt")
+prefix_rule(pattern=["pip3", "uninstall"], decision="prompt")
+
+prefix_rule(pattern=["docker", "run"], decision="prompt")
+prefix_rule(pattern=["docker", "rm"], decision="prompt")
+prefix_rule(pattern=["docker", "stop"], decision="prompt")
+prefix_rule(pattern=["docker", "volume"], decision="prompt")
+prefix_rule(pattern=["docker", "system"], decision="prompt")
+prefix_rule(pattern=["docker", "compose", "up"], decision="prompt")
+prefix_rule(pattern=["docker", "compose", "down"], decision="prompt")
+prefix_rule(pattern=["docker", "compose", "rm"], decision="prompt")
+prefix_rule(pattern=["docker", "compose", "stop"], decision="prompt")
+prefix_rule(pattern=["docker-compose", "up"], decision="prompt")
+prefix_rule(pattern=["docker-compose", "down"], decision="prompt")
+prefix_rule(pattern=["docker-compose", "rm"], decision="prompt")
+prefix_rule(pattern=["docker-compose", "stop"], decision="prompt")
+
+# `tail -f`/`--follow` never returns and hangs the agent (bare `tail` stays allowed above).
+prefix_rule(pattern=["tail", "-f"], decision="prompt")
+prefix_rule(pattern=["tail", "--follow"], decision="prompt")
+# rg and `sed -n` are prompt, NOT allow: argv-prefix matching cannot gate their
+# code-exec forms (rg --pre=CMD or a reordered --pre; sed -n 'e CMD' / -ni) while a
+# shorter allow prefix would auto-approve the whole command.
+prefix_rule(pattern=["rg"], decision="prompt")
+prefix_rule(pattern=["sed", "-n"], decision="prompt")
+prefix_rule(pattern=["find"], decision="prompt")
+prefix_rule(pattern=["sed", "-i"], decision="prompt")
+prefix_rule(pattern=["sed", "--in-place"], decision="prompt")
+prefix_rule(pattern=["awk"], decision="prompt")
+prefix_rule(pattern=["xargs"], decision="prompt")
+prefix_rule(pattern=["tee"], decision="prompt")
+prefix_rule(pattern=["curl"], decision="prompt")
+prefix_rule(pattern=["env"], decision="prompt")
+
+prefix_rule(pattern=["sudo"], decision="forbidden")
+prefix_rule(pattern=["eval"], decision="forbidden")
+prefix_rule(pattern=["mkfs"], decision="forbidden")
+prefix_rule(pattern=["dd"], decision="forbidden")
+prefix_rule(pattern=["git", "push", "--force", "origin", "main"], decision="forbidden")
+prefix_rule(pattern=["git", "push", "--force", "origin", "master"], decision="forbidden")
+prefix_rule(pattern=["git", "push", "-f", "origin", "main"], decision="forbidden")
+prefix_rule(pattern=["git", "push", "-f", "origin", "master"], decision="forbidden")

package/SoT/models.json

@@ -0,0 +1,28 @@
+{
+  "$comment": "Kit-verified model catalog — single source for the engine validators (lib/common.sh), the docks-kit CLI (models/model commands, pickers, bare-flag help), and docs. Entries are research-proofed: update an entry and its tool-level `verified` date when a model ships or retires. The catalog informs, it doesn't imprison: well-formed IDs outside it (claude-* / codex charset) apply with a warning.",
+  "claude": {
+    "verified": "2026-07-08",
+    "models": [
+      { "id": "best", "kind": "alias", "note": "Fable 5 where the org has access, latest Opus otherwise (Claude Code >=2.1.170)" },
+      { "id": "opus", "kind": "alias", "note": "latest Opus (currently Opus 4.8) — the kit SoT default, paired with the fable advisor" },
+      { "id": "fable", "kind": "alias", "note": "Fable 5 — needs org access + Claude Code >=2.1.170" },
+      { "id": "sonnet", "kind": "alias", "note": "latest Sonnet (currently Sonnet 5)" },
+      { "id": "haiku", "kind": "alias", "note": "latest Haiku (currently Haiku 4.5)" },
+      { "id": "default", "kind": "alias", "note": "engine pseudo-value: deletes the deployed model key so the account default applies" },
+      { "id": "claude-fable-5", "kind": "id", "note": "Fable 5" },
+      { "id": "claude-opus-4-8", "kind": "id", "note": "Opus 4.8" },
+      { "id": "claude-sonnet-5", "kind": "id", "note": "Sonnet 5" },
+      { "id": "claude-haiku-4-5-20251001", "kind": "id", "note": "Haiku 4.5" }
+    ]
+  },
+  "codex": {
+    "verified": "2026-07-08",
+    "models": [
+      { "id": "gpt-5.5", "kind": "id", "note": "Codex default — the kit SoT pin" },
+      { "id": "gpt-5.5-codex", "kind": "id", "note": "codex-tuned gpt-5.5" },
+      { "id": "gpt-5.1", "kind": "id", "note": "previous generation" },
+      { "id": "gpt-5", "kind": "id", "note": "previous generation" },
+      { "id": "gpt-5-codex", "kind": "id", "note": "codex-tuned gpt-5" }
+    ]
+  }
+}

package/SoT/toolchain.json

@@ -0,0 +1,26 @@
+{
+  "$comment": "Kit toolchain manifest — DATA only (versions, floors, policy); the check/install logic lives in lib/toolchain.sh and the per-tool install callbacks in each lib. kind: required (preflight hard dep) | check (doctor visibility only) | managed (kit installs/upgrades it) | pin (no binary probe — a version pin for a tool the kit invokes via npx). policy (managed only): track (upgrade toward latest, gated by `verified`) | present (install when missing, never upgrade). `verified` = last kit-tested version — anything above it prompts before install (--yes auto-accepts; non-TTY declines and falls back to the pinned `verified` when pinnable). Supply-chain stance: every kit-driven install is pinned to `verified` or gated by it — never floating @latest (npm-worm/Shai-Hulud surface). Update `verified` after testing a new release.",
+  "tools": {
+    "jq":     { "kind": "required", "note": "settings merges + manifest reads" },
+    "curl":   { "kind": "required", "note": "installers + usage fetch" },
+    "node":   { "kind": "check", "note": "hosts npm globals (agent-browser, LSP servers)" },
+    "npm":    { "kind": "check", "note": "npm-global installer" },
+    "claude": { "kind": "check", "floor": "2.1.170", "note": "kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)" },
+    "codex":  { "kind": "check", "note": "upstream-owned; standalone installer prints when missing" },
+    "ffplay": { "kind": "check", "note": "Notification hook sound (previously unchecked)" },
+    "bwrap":  { "kind": "check", "os": "linux", "note": "Codex Linux sandbox runtime" },
+    "intelephense": { "kind": "check", "verified": "1.18.5", "note": "php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
+    "typescript-language-server": { "kind": "check", "verified": "5.3.0", "note": "typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install" },
+    "tsc":    { "kind": "check", "verified": "6.0.3", "note": "typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install" },
+    "rtk":    { "kind": "managed", "policy": "track", "floor": "0.43.0", "verified": "0.43.0", "pinnable": true,
+                "note": "PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin" },
+    "bun":    { "kind": "managed", "policy": "present", "verified": "1.3.14", "pinnable": true,
+                "note": "runtime for effect-solutions + the docks-kit CLI; bootstrap installs the verified release (installer takes bun-vX.Y.Z); self-updates via `bun upgrade` when wanted" },
+    "effect-solutions": { "kind": "managed", "policy": "track", "verified": "0.5.3", "pinnable": true,
+                "note": "Effect docs CLI (bun global) — track keeps it self-upgrading, gated by the verified pin" },
+    "agent-browser":    { "kind": "managed", "policy": "track", "verified": "0.31.1", "pinnable": true,
+                "note": "browser-automation CLI (npm global), gated by the verified pin; first install also downloads Chrome for Testing" },
+    "skills-cli": { "kind": "pin", "verified": "1.5.15",
+                "note": "the `skills` npm package the kit runs via `npx skills@<verified>` on every agents sync (universal-skill install/remove) — pinned, never @latest" }
+  }
+}

package/cli/docs/flags.md

@@ -0,0 +1,48 @@
+# Flag reference
+
+Convention: global flags are unprefixed; anything touching one tool's
+deployed config is `--<tool>-<setting>`.
+
+## Targets (positional)
+
+```
+docks-kit sync                      # all three
+docks-kit sync claude               # one
+docks-kit sync claude agents        # two
+```
+
+## Global flags
+
+| Flag | Effect |
+|------|--------|
+| `--dry-run` | Preview without applying |
+| `--reconcile` | Settings layer reconciled toward SoT (SoT keys win; user-only keys preserved; permissions arrays replaced) |
+| `--prune` | Uninstall kit-managed installs not in SoT: plugins, marketplaces, universal skills |
+| `--skip-rtk` | Skip optional tool bootstrap (RTK, bubblewrap) |
+| `--yes` | Auto-accept toolchain above-verified prompts (containers/CI) |
+
+## Per-tool flags
+
+| Flag | Effect |
+|------|--------|
+| `--claude-model=<m>` | Deploy-time modifier: deployed model (aliases or full claude-* IDs; `default` unsets) |
+| `--claude-compact-window=<n>` | Deploy-time modifier: autocompact window in tokens (`680000` or `680k`) |
+| `--claude-permissive` | Deploy-time modifier: empty permissions.ask/deny (sandboxes) |
+| `--claude-plugin=<name>` | Sticky opt-in plugin (known: supabase, n8n); comma-separate for several |
+| `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
+
+Bare `--claude-model` / `--codex-model` (no value) prints the model catalog.
+
+## Renamed legacy flags (pre-CLI sync.sh)
+
+Old flags exit with a rename hint — there is no compat behavior.
+
+| Old | New |
+|-----|-----|
+| `--claude` / `--codex` / `--agents` | positional `claude` / `codex` / `agents` |
+| `--force` | `--reconcile` |
+| `--remove-plugins` | `--prune` |
+| `--680k` | `--claude-compact-window=680k` |
+| `--permissive` | `--claude-permissive` |
+| `--supabase` / `--n8n` | `--claude-plugin=supabase` / `--claude-plugin=n8n` |
+| `--no-rtk` | `--skip-rtk` |

package/cli/docs/install.md

@@ -0,0 +1,56 @@
+# Installing docks-kit
+
+## 1. Repo checkout (development / current users)
+
+```
+git clone https://github.com/DocksDocks/public.git ~/projects/public
+cd ~/projects/public
+./docks-kit sync
+```
+
+The `./docks-kit` launcher prefers a compiled binary in `cli/dist/`, then
+falls back to Bun-from-source (auto-installing Bun via download-then-run and
+`bun install --frozen-lockfile` when needed).
+
+## 2. Global via Bun (effect-solutions-style)
+
+```
+bun add -g docks-kit@latest
+docks-kit sync
+# or one-shot, no install:
+bunx docks-kit status
+```
+
+The npm package bundles the engine (`lib/*.sh`) and the SoT — releases are
+versioned config snapshots. Kit-home resolution: `DOCKS_KIT_HOME` env →
+nearest ancestor directory containing `SoT/` (a checkout wins over the
+bundled copy) → the package's own bundled SoT.
+
+## 3. curl installer
+
+```
+curl -fsSL https://raw.githubusercontent.com/DocksDocks/public/main/install.sh -o /tmp/docks-kit-install.sh
+bash /tmp/docks-kit-install.sh && rm /tmp/docks-kit-install.sh
+```
+
+Download-then-run, never `curl | bash` — stream truncation has bitten this
+kit before. The installer bootstraps Bun when absent, runs
+`bun add -g docks-kit`, and links the binary into `~/.local/bin`.
+
+## Zero-dependency escape hatch
+
+No Bun, no binary, constrained sandbox:
+
+```
+bash lib/engine.sh sync [targets] [flags]
+bash lib/engine.sh model claude opus
+bash lib/engine.sh toolchain check
+```
+
+Requires only bash + jq (+ curl for installers).
+
+## Prerequisites
+
+- bash, jq, curl (hard requirements — preflight checks them)
+- Node/npm for npm-global tools (agent-browser, LSP servers)
+- See `docks-kit toolchain check` for the full picture on this machine

package/cli/docs/models.md

@@ -0,0 +1,42 @@
+# Models
+
+`SoT/models.json` is the kit-verified model catalog — the single source for
+the engine validators, `docks-kit models`, the interactive picker, and the
+bare-flag helper output. Each tool section carries a `verified` date; update
+the entry and date when a model ships or retires.
+
+## Validation rules
+
+- **Claude**: catalog aliases (`best`, `opus`, `fable`, `sonnet`, `haiku`,
+  `default`) and full IDs validate silently; any other `claude-*` ID is
+  accepted with a warning (new models outrun the catalog); everything else
+  exits 2 with the catalog printed.
+- **Codex**: hard charset gate `^[A-Za-z0-9._-]+$` (also blocks TOML-quote
+  injection — the value lands inside a quoted config.toml string); catalog
+  misses warn but apply.
+
+## The `best` alias and `default` pseudo-value
+
+- `best` resolves to Fable 5 where the org has access, latest Opus otherwise.
+  Needs Claude Code >= 2.1.170. (The kit SoT default is `opus`, paired with
+  the `fable` advisor — see the advisor note below.)
+- `default` is an engine pseudo-value: it DELETES the deployed `model` key so
+  the account default applies. It never reaches the settings file as a value.
+
+## Commands
+
+```
+docks-kit models                  # both catalogs
+docks-kit models claude --json    # machine-readable
+docks-kit model claude            # current deployed + SoT + picker (TTY)
+docks-kit model claude fable      # set deployed model
+docks-kit sync claude --claude-model=opus   # same, as part of a sync
+```
+
+## Advisor pairing note (Claude)
+
+The advisor model must be at least as capable as the main model; Fable
+outranks Opus, so an Opus main + Fable advisor works while Fable main +
+Opus advisor is rejected. The SoT ships `model: opus` + `advisorModel:
+fable` as the deployed-everywhere default; use settings.local.json only
+for a deliberate per-machine deviation.

package/cli/docs/modifiers.md

@@ -0,0 +1,33 @@
+# Deploy-time modifiers
+
+Modifiers change the **deployed** config for a specific machine profile —
+the SoT is never touched. They all share one contract:
+
+> A later flag-less sync reverts the modifier: the settings merge (Claude)
+> and the config.toml merge (Codex) re-assert SoT values for kit-owned keys.
+> Re-pass the flag on machines that should keep the override, or make it
+> persistent in `~/.claude/settings.local.json` (which sync never touches).
+
+| Modifier | Deployed change | Typical use |
+|----------|-----------------|-------------|
+| `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Drop one machine to opus while the SoT stays on `best` |
+| `--claude-compact-window=<n>` | `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Disposable containers running long autonomous work (e.g. `680k`) — not host machines |
+| `--claude-permissive` | `permissions.ask = []`, `permissions.deny = []` | Sandboxes/containers where prompts stall unattended work. Never on a host — the deny list is the safety floor |
+| `--codex-model=<m>` | top-level `model = "…"` in ~/.codex/config.toml | Same as claude-model, for Codex |
+
+## Standalone get/set (no full sync)
+
+```
+docks-kit model claude            # show deployed + SoT + catalog (+ TTY picker)
+docks-kit model claude opus       # set deployed model
+docks-kit model claude default    # delete the key (account default applies)
+docks-kit model codex gpt-5.5     # codex flavor
+```
+
+The set path calls the same engine functions as the sync flags —
+one implementation, two entry points.
+
+## Sticky opt-ins are NOT modifiers
+
+`--claude-plugin=<name>` installs+enables an optional plugin and it STAYS
+(the SoT has no key to revert against). Only `--prune` removes it.

package/cli/docs/overview.md

@@ -0,0 +1,37 @@
+# docks-kit overview
+
+docks-kit is a portable configuration kit for AI coding agents. Per-tool
+Single Source of Truth (SoT) directories are deployed to each tool's
+user-config location — clone once, sync everywhere, get a consistent
+AI-assisted dev environment on every machine.
+
+## Pieces
+
+| Piece | Role |
+|-------|------|
+| `SoT/.claude/` | Claude Code config (settings, hooks, status line, CLAUDE.md) |
+| `SoT/.codex/` | Codex config (config.toml, rules, AGENTS.md, marketplace) |
+| `SoT/.agents/` | Universal agent skills manifest (agentskills.io standard) |
+| `SoT/models.json` | Kit-verified model catalog (see `docks-kit docs models`) |
+| `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
+| `lib/*.sh` | The bash engine — all mutation logic; battle-tested, idempotent |
+| `lib/engine.sh` | Engine entry: `sync`, `model`, `toolchain` — the zero-dependency escape hatch |
+| `cli/` | This CLI (Effect-TS on Bun) — typed front-end over the engine |
+| `docks-kit` | Launcher: compiled binary → bun-from-source, with Bun auto-install |
+
+## Design rules
+
+- **Idempotent**: every sync step is safe to re-run; no-change syncs are no-ops.
+- **Additive by default**: user-only keys/plugins/skills survive a plain sync.
+  Reconciliation toward the SoT is explicit: `--reconcile` (settings) and
+  `--prune` (plugins/marketplaces/skills).
+- **Deploy-time modifiers** mutate deployed config only — the SoT never
+  changes, and a later flag-less sync reverts them (`docks-kit docs modifiers`).
+- **Engine/CLI split**: the CLI adds UX (typed flags, pickers, docs, JSON);
+  the engine owns mutation. `bash lib/engine.sh <same args>` always works.
+
+## Where to go next
+
+- `docks-kit docs sync-layers` — what a sync actually touches
+- `docks-kit docs flags` — full flag reference + old→new renames
+- `docks-kit status` — live doctor view of this machine

package/cli/docs/platforms.md

@@ -0,0 +1,31 @@
+# Platform support
+
+| Platform | CLI (docks-kit) | Sync engine | Notes |
+|----------|-----------------|-------------|-------|
+| Linux | native | native | Primary target |
+| macOS | native (x64 + arm64) | native | bash 3.2-compatible engine |
+| Windows | native (binary/Bun) | **experimental via Git Bash**; full hooks under WSL | See below |
+
+## Windows detail
+
+The managed tools all run natively on Windows: Claude Code (requires Git
+Bash for its Bash tool — so Git Bash is present on any Windows machine
+running Claude Code), Codex CLI (native PowerShell + Windows sandbox),
+RTK (native binaries via GitHub releases/winget — but its PreToolUse hook
+mechanism is Unix-only; Windows falls back to RTK's `--claude-md` mode).
+
+The kit's engine is bash+jq, so on Windows it runs under Git Bash. Status:
+**experimental and not yet verified on a real Windows machine** — expect
+rough edges around:
+
+- shell-rc env exports (needs `setx` translation)
+- the notification hook (ffplay)
+- bubblewrap (Linux-only; skipped)
+
+For full fidelity (RTK hooks included), run the kit inside WSL.
+
+## Roadmap
+
+A native TypeScript engine (module-by-module port inside the CLI, swappable
+behind the same seam) would remove the Git Bash requirement entirely. Tracked
+as a follow-up plan — not part of the current CLI.

package/cli/docs/plugins.md

@@ -0,0 +1,44 @@
+# Plugins: the enabledPlugins tri-state
+
+`SoT/.claude/settings.json` → `enabledPlugins` values carry three meanings:
+
+| Value | Meaning | `--prune` |
+|-------|---------|-----------|
+| `true` | Installed + enabled in every project | keeps installed |
+| `false` | Installed + globally disabled; a project's `.claude/settings.json` can flip it to `true` per-repo | keeps installed |
+| key absent | Not installed | uninstalls if present |
+
+The user-scope key MUST stay present (as `false`) for per-project
+re-enablement to work — Claude Code ignores project-level entries whose key
+is absent from user settings.
+
+## Sync passes (idempotent, via the `claude plugin` CLI)
+
+1. Add SoT marketplaces not yet known
+2. Install SoT-declared plugins missing at user scope
+3. Refresh marketplace manifests; update installed plugins
+4. (`--prune` only) uninstall plugins / remove marketplaces not in SoT
+5. Re-assert SoT enabled-state (undoes install's enable side effect on
+   false-keyed plugins)
+
+## Optional opt-ins
+
+Situational plugins are kept OUT of the SoT and opted in per machine:
+
+```
+docks-kit sync claude --claude-plugin=supabase
+docks-kit sync claude --claude-plugin=supabase,n8n
+```
+
+Opt-ins are STICKY: with no SoT key to revert against, a later flag-less
+sync leaves them alone; only `--prune` uninstalls them.
+
+Caveat (supabase): its bundled MCP server's OAuth is account-global — the
+opt-in only fits while every repo on the machine shares one Supabase account;
+otherwise pin a per-repo .mcp.json instead.
+
+## Inspect
+
+```
+docks-kit plugins list [--json]
+```

package/cli/docs/sync-layers.md

@@ -0,0 +1,43 @@
+# Sync layers
+
+`docks-kit sync [claude] [codex] [agents]` — targets are positional words;
+no target means all three.
+
+## claude (→ ~/.claude, ~/.claude.json, shell rc)
+
+Order matters — toolchain first, config after:
+
+1. **RTK** (toolchain-gated): install/upgrade, then `rtk init --global` on
+   first install. Runs FIRST because rtk init rewrites settings.json — the
+   later settings merge normalizes whatever it wrote.
+2. Scripts (statusline, fetch-usage, notification.mp3), hooks, CLAUDE.md.
+3. **settings.json merge** — additive: SoT keys win, permissions arrays are
+   unioned, user-only keys survive. `--reconcile` replaces permissions arrays
+   wholesale instead.
+4. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
+   `--claude-model`) — deployed file only.
+5. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
+   export, removed-artifact pruning.
+6. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+   (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
+   SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
+7. LSP server binaries (npm globals).
+
+## codex (→ ~/.codex, ~/.agents/plugins)
+
+bubblewrap check (Linux), config.toml merge (top-level keys replaced
+per-key, [table] blocks replaced wholesale, user-only keys/tables preserved),
+`--codex-model` modifier, rules, AGENTS.md, personal marketplace file,
+`codex plugin add` refresh.
+
+## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
+
+`npx skills add` per missing manifest slug, Claude symlink healing,
+CLI binaries (agent-browser, effect-solutions — toolchain-gated), and the
+kit-managed snapshot that `--prune` reconciles against.
+
+## Reconcile flags
+
+- `--reconcile` — settings layer: SoT-declared keys win; user-only preserved.
+- `--prune` — plugins + marketplaces + kit-managed skills not in SoT are removed.
+- Combine for a full reset to the SoT's kit-managed scope.

package/cli/docs/toolchain.md

@@ -0,0 +1,54 @@
+# Toolchain: verified-version floors
+
+`SoT/toolchain.json` declares every external tool the kit touches, with:
+
+| Field | Meaning |
+|-------|---------|
+| `kind` | `required` (preflight hard dep) / `check` (doctor visibility) / `managed` (kit installs + upgrades) / `pin` (no binary — a version pin for npx-invoked tools, e.g. `skills-cli`) |
+| `policy` | `track` (upgrade toward latest, gated by `verified`) / `present` (install when missing, never upgrade) |
+| `floor` | Minimum acceptable version (below → upgrade automatically) |
+| `verified` | Last kit-tested version — the gate line |
+| `pinnable` | Whether an exact version can be installed (rtk: `RTK_VERSION=vX.Y.Z`) |
+
+## The gate
+
+When an install/upgrade candidate is **above `verified`**:
+
+- **TTY**: prompt — "X <latest> is not kit-verified (verified: <v>). Install anyway? [y/N]"
+- **`--yes`**: proceed with a warning (containers/CI)
+- **non-TTY, declined**:
+  - install mode (tool missing) + pinnable → install the pinned `verified` version
+  - upgrade mode → stay on the installed version, warn
+
+At or below `verified`, installs/upgrades run silently. After testing a new
+release, bump `verified` in SoT/toolchain.json — that is the "this version is
+now kit-approved" act.
+
+## Managed tools
+
+- **rtk** — PreToolUse hook (supply-chain sensitive: review releases before
+  bumping `verified`). Runs FIRST in the claude sync so `rtk init`'s
+  settings rewrite is normalized by the merge that follows. Pinned installs
+  fetch the installer script from the version tag, not mutable master.
+- **bun** — policy `present`: bootstrap only (pinned to `verified` via the
+  installer's `bun-vX.Y.Z` release-tag argument), never auto-upgraded.
+- **effect-solutions**, **agent-browser** — policy `track`: self-upgrade
+  toward npm latest, gated by their `verified` pins.
+
+## Supply-chain stance
+
+Every kit-driven install is pinned to a `verified` version or gated by one —
+never floating `@latest` (the npm-worm / Shai-Hulud attack surface). That
+includes the `npx skills@<verified>` invocations on every agents sync, the
+`chrome-devtools-mcp` MCP server pin in SoT/.claude/mcp-servers.json, and the
+release workflow (actions pinned to commit SHAs, exact bun/npm versions).
+Callbacks receive the exact gate-approved version; an offline "latest unknown"
+probe falls back to the pinned `verified`, never to an ungated latest.
+
+## Commands
+
+```
+docks-kit toolchain check            # doctor table (also inside docks-kit status)
+docks-kit toolchain ensure rtk       # install/upgrade one tool per policy
+docks-kit sync --yes                 # unattended: auto-accept gates
+```

package/cli/src/commands/docs.ts

@@ -0,0 +1,65 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { bail } from "../engine"
+import overview from "../../docs/overview.md" with { type: "text" }
+import flags from "../../docs/flags.md" with { type: "text" }
+import modifiers from "../../docs/modifiers.md" with { type: "text" }
+import models from "../../docs/models.md" with { type: "text" }
+import toolchain from "../../docs/toolchain.md" with { type: "text" }
+import plugins from "../../docs/plugins.md" with { type: "text" }
+import syncLayers from "../../docs/sync-layers.md" with { type: "text" }
+import install from "../../docs/install.md" with { type: "text" }
+import platforms from "../../docs/platforms.md" with { type: "text" }
+
+const TOPICS: Record<string, { summary: string; body: string }> = {
+  "overview": { summary: "What docks-kit is and how the pieces fit", body: overview },
+  "sync-layers": { summary: "The three sync layers and additive-by-default semantics", body: syncLayers },
+  "flags": { summary: "Full flag reference incl. the old→new rename table", body: flags },
+  "modifiers": { summary: "Deploy-time modifiers and the flag-less-sync-reverts contract", body: modifiers },
+  "models": { summary: "Model catalog, validation rules, model get/set", body: models },
+  "toolchain": { summary: "Verified-version floors, gate policy, --yes semantics", body: toolchain },
+  "plugins": { summary: "enabledPlugins tri-state + optional plugin opt-ins", body: plugins },
+  "install": { summary: "Install paths: repo checkout, bun add -g, curl installer", body: install },
+  "platforms": { summary: "Platform support: Linux/macOS native, Windows via Git Bash/WSL", body: platforms }
+}
+
+const topic = Args.text({ name: "topic" }).pipe(
+  Args.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
+  Args.optional
+)
+const json = Options.boolean("json").pipe(
+  Options.withDescription("List topics as JSON")
+)
+
+export const docsCommand = Command.make("docs", { topic, json }, (config) =>
+  Effect.gen(function* () {
+    const requested = Option.getOrUndefined(config.topic)
+
+    if (requested === undefined) {
+      if (config.json) {
+        return yield* Console.log(
+          JSON.stringify(
+            Object.entries(TOPICS).map(([name, t]) => ({ name, summary: t.summary })),
+            null,
+            2
+          )
+        )
+      }
+      yield* Console.log("docks-kit documentation topics (docks-kit docs <topic>):\n")
+      for (const [name, t] of Object.entries(TOPICS)) {
+        yield* Console.log(`  ${name.padEnd(14)} ${t.summary}`)
+      }
+      return
+    }
+
+    const entry = TOPICS[requested]
+    if (entry === undefined) {
+      return yield* bail(`Unknown topic '${requested}'. Valid: ${Object.keys(TOPICS).join(", ")}`)
+    }
+    yield* Console.log(entry.body)
+  })
+).pipe(
+  Command.withDescription(
+    "Self-documentation: the kit's concepts as readable topics, bundled with the CLI — a fresh agent can learn the kit from here alone."
+  )
+)