docks-kit 0.8.2 → 0.10.0

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

@@ -5,12 +5,12 @@
  * and the snapshot write.
  */
 import { spawnSync } from "node:child_process"
-import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs"
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync } from "node:fs"
 import { p, writeFileIfChanged } from "./exec"
 import { bunBootstrap } from "./bun"
 import type { Ctx } from "./index"
 import { compareCodepoints } from "./jq"
-import type { EngineServices, Platform } from "./services"
+import type { EngineServices } from "./services"
 import { ensure, field } from "./toolchain"
 import { payloadText } from "../payload"
 
@@ -139,9 +139,6 @@ function healClaudeSymlink(ctx: Ctx, skillsDir: string, base: string): boolean {
   if (linkStat?.isSymbolicLink() === true) {
     const current = safeReadlink(claudeLink)
     if (current === relTarget) return false
-    // win32: `npx skills add` creates absolute symlinks/junctions — any link
-    // that RESOLVES to the canonical dir is healthy, not stale.
-    if (ctx.services.platform.isWindows() && realpathEquals(claudeLink, canonical)) return false
     if (ctx.dryRun) {
       echo(`[dry-run] would replace stale Claude symlink: ~/.claude/skills/${base} -> ${current}  (correct: ${relTarget})`)
       return true
@@ -178,36 +175,22 @@ function safeReadlink(path: string): string {
   }
 }
 
-function realpathEquals(a: string, b: string): boolean {
-  try {
-    return realpathSync(a) === realpathSync(b)
-  } catch {
-    return false
-  }
-}
 
-/**
- * Remove a symlink/junction without crashing: Bun's rmSync throws EFAULT on
- * win32 directory symlinks. unlink handles file symlinks, rmdir handles
- * dir symlinks/junctions, rmSync is the POSIX catch-all.
- */
+/** Remove a symlink without touching a real directory. */
 function removeLink(path: string): boolean {
-  for (const rm of [() => unlinkSync(path), () => rmdirSync(path), () => rmSync(path, { force: true })]) {
-    try {
-      rm()
-      return true
-    } catch {
-      // try the next removal shape
-    }
+  try {
+    rmSync(path, { force: true })
+    return true
+  } catch {
+    return lstat(path) === undefined
   }
-  return lstat(path) === undefined
 }
 
-/** skills::_link_or_copy — real symlink preferred, copy fallback (Windows). */
-export function linkOrCopy(target: string, link: string, platform: Platform): boolean {
+/** skills::_link_or_copy — real symlink preferred, copy fallback. */
+export function linkOrCopy(target: string, link: string): boolean {
   removeLink(link)
   try {
-    symlinkSync(target, link, platform.isWindows() ? "dir" : undefined)
+    symlinkSync(target, link)
   } catch {
     // fall through to the copy fallback below
   }
@@ -223,11 +206,11 @@ export function linkOrCopy(target: string, link: string, platform: Platform): bo
 }
 
 function linkOrCopyWithWarnings(target: string, link: string, services: EngineServices): boolean {
-  const linked = linkOrCopy(target, link, services.platform)
+  const linked = linkOrCopy(target, link)
   if (!linked) {
     services.logger.warn(`could not create ${link} (symlink and copy both failed)`)
   } else if (lstat(link)?.isSymbolicLink() !== true) {
-    services.logger.warn(`symlinks unsupported here — ${link} is a copy (refreshed on sync; enable Windows Developer Mode for real links)`)
+    services.logger.warn(`symlinks unsupported here — ${link} is a copy refreshed on sync`)
   }
   return linked
 }
@@ -298,14 +281,6 @@ export function effectSolutionsInstall(
 
     const location = services.deps.location("effect-solutions")
     const gbin = location.binDir
-    // win32: bun writes an .exe shim (not the bare Unix name), and the
-    // ~/.local/bin link step below is Unix-only plumbing (non-interactive
-    // agent PATH) — bun's global bin is already the Windows PATH entry.
-    if (services.platform.isWindows()) {
-      if (location.path !== "") change(`effect-solutions CLI ready (${gbin})`)
-      else warn(`effect-solutions installed but no shim found under '${gbin !== "" ? gbin : "<unknown>"}' — check bun pm -g bin`)
-      return 0
-    }
     if (location.path !== "") {
       mkdirSync(p(ctx.home, ".local", "bin"), { recursive: true })
       linkOrCopyWithWarnings(bun, p(ctx.home, ".local", "bin", "bun"), services)

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

@@ -57,6 +57,8 @@ export function installedVersion(ctx: Ctx, tool: ToolId): string {
     case "codex":
     case "agent-browser":
       return firstLineField(version(), -1)
+    case "session-relay":
+      return firstLineField(version(), 1)
     case "git":
       return firstLineField(version(), 2)
     case "node":

package/cli/src/engine.ts

@@ -5,28 +5,32 @@ import { makeEngineServices } from "./engine-native/services"
 import { kitHome } from "./kitHome"
 import { DependencyManagerService, LoggerService, PlatformService } from "./services"
 
-// Same factory as the Effect rim's live layers — this path runs outside the
-// runtime (child-spawn capture), so it takes the services directly.
-const services = makeEngineServices()
-
 /**
  * The single seam between the typed CLI and EngineNative. Engine execution
  * stays in-process after @effect/cli has parsed pickers and flag spellings.
  */
 const bashRemovedMessage = "bash engine removed — recover at tag bash-engine-final"
 const bashEngineRequested = (): boolean => process.env["DOCKS_KIT_ENGINE"] === "bash"
+const requireSupportedHost = () => {
+  const platform = process.platform
+  const arch = process.arch
+  return (platform === "linux" || platform === "darwin") && (arch === "x64" || arch === "arm64")
+    ? Effect.void
+    : bail(
+      `unsupported host ${platform}/${arch}; docks-kit supports only Linux and macOS on x64 or arm64`,
+      2
+    )
+}
 
-// bun build --compile runs the embedded entry from a virtual path
-// ("/$bunfs/root/…" on POSIX, "B:\~BUN\root\…" on Windows). There
-// process.execPath IS the CLI, so a re-spawn must not pass main.ts.
-// The Windows check is anchored to the drive-rooted "~BUN" segment so a
-// real checkout under a ~BUN-named directory can't false-positive.
+// bun build --compile runs the embedded entry from a virtual POSIX path
+// ("/$bunfs/root/…"). There process.execPath IS the CLI, so a re-spawn must
+// not pass main.ts.
 export const compiled =
-  process.argv[1] !== undefined &&
-  (process.argv[1].startsWith("/$bunfs/") || /^[A-Za-z]:[\\/]~BUN[\\/]/i.test(process.argv[1]))
+  process.argv[1] !== undefined && process.argv[1].startsWith("/$bunfs/")
 
 export const engine = (args: ReadonlyArray<string>) =>
   Effect.gen(function* () {
+    yield* requireSupportedHost()
     if (bashEngineRequested()) {
       yield* bail(bashRemovedMessage, 2)
     }
@@ -41,9 +45,12 @@ export const engine = (args: ReadonlyArray<string>) =>
 
 /** Run the engine capturing stdout (engine logs/warns go to stderr and pass through). */
 export const engineCapture = (args: ReadonlyArray<string>) =>
-  bashEngineRequested()
-    ? bail(bashRemovedMessage, 2)
-    : Effect.sync(() => {
+  Effect.gen(function* () {
+    yield* requireSupportedHost()
+    if (bashEngineRequested()) {
+      return yield* bail(bashRemovedMessage, 2)
+    }
+    return yield* Effect.sync(() => {
       // Child process (raw channel): runEngineNative writes straight to
       // process.stdout, so in-process capture isn't possible.
       const res = spawnSync(process.execPath, compiled ? [...args] : [`${kitHome()}/cli/src/main.ts`, ...args], {
@@ -52,10 +59,11 @@ export const engineCapture = (args: ReadonlyArray<string>) =>
         stdio: ["ignore", "pipe", "inherit"]
       })
       if (res.error !== undefined || res.status !== 0) {
-        services.logger.warn(`engine capture failed (${args.join(" ")} exited ${res.status ?? "spawn-error"})`)
+        makeEngineServices().logger.warn(`engine capture failed (${args.join(" ")} exited ${res.status ?? "spawn-error"})`)
       }
       return res.stdout ?? ""
     })
+  })
 
 /** Print a message to stderr and exit — for CLI-side validation failures. */
 export const bail = (message: string, code = 2) =>

package/cli/src/generated/sotPayload.ts

@@ -1,12 +1,12 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.8.2"
+export const GENERATED_PACKAGE_VERSION = "0.10.0"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",
   "SoT/models.json": "{\n  \"$comment\": \"Kit-verified model catalog — single source for EngineNative validators, the docks-kit CLI (models/model commands, workflow selectors, 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. Deploy-time model flags remain permissive; workflow selectors are strict.\",\n  \"claude\": {\n    \"verified\": \"2026-07-08\",\n    \"models\": [\n      { \"id\": \"best\", \"kind\": \"alias\", \"note\": \"Fable 5 where the org has access, latest Opus otherwise (Claude Code >=2.1.170)\" },\n      { \"id\": \"opus\", \"kind\": \"alias\", \"note\": \"latest Opus (currently Opus 4.8)\" },\n      { \"id\": \"fable\", \"kind\": \"alias\", \"note\": \"Fable 5 — the kit SoT default; needs org access + Claude Code >=2.1.170\" },\n      { \"id\": \"sonnet\", \"kind\": \"alias\", \"note\": \"latest Sonnet (currently Sonnet 5)\" },\n      { \"id\": \"haiku\", \"kind\": \"alias\", \"note\": \"latest Haiku (currently Haiku 4.5)\" },\n      { \"id\": \"default\", \"kind\": \"alias\", \"note\": \"engine pseudo-value: deletes the deployed model key so the account default applies\" },\n      { \"id\": \"claude-fable-5\", \"kind\": \"id\", \"note\": \"Fable 5\" },\n      { \"id\": \"claude-opus-4-8\", \"kind\": \"id\", \"note\": \"Opus 4.8\" },\n      { \"id\": \"claude-sonnet-5\", \"kind\": \"id\", \"note\": \"Sonnet 5\" },\n      { \"id\": \"claude-haiku-4-5-20251001\", \"kind\": \"id\", \"note\": \"Haiku 4.5\" }\n    ]\n  },\n  \"codex\": {\n    \"verified\": \"2026-07-16\",\n    \"models\": [\n      { \"id\": \"gpt-5.6-sol\", \"kind\": \"id\", \"note\": \"GPT-5.6 Sol — frontier, recommended default; the kit SoT pin\" },\n      { \"id\": \"gpt-5.6-terra\", \"kind\": \"id\", \"note\": \"GPT-5.6 Terra — balanced tier\" },\n      { \"id\": \"gpt-5.6-luna\", \"kind\": \"id\", \"note\": \"GPT-5.6 Luna — fast/light tier\" },\n      { \"id\": \"gpt-5.5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5.5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5.5\" },\n      { \"id\": \"gpt-5.1\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5\", \"kind\": \"id\", \"note\": \"previous generation\" },\n      { \"id\": \"gpt-5-codex\", \"kind\": \"id\", \"note\": \"codex-tuned gpt-5\" }\n    ]\n  },\n  \"workflow\": {\n    \"schema\": 2,\n    \"profiles\": {\n      \"claude-best\": {\n        \"candidates\": [\n          { \"company\": \"anthropic\", \"tool\": \"claude\", \"model\": \"fable\", \"effort\": \"high\" },\n          { \"company\": \"anthropic\", \"tool\": \"claude\", \"model\": \"opus\", \"effort\": \"xhigh\" }\n        ]\n      }\n    },\n    \"defaults\": {\n      \"orchestrator\": \"profile:claude-best\",\n      \"reviewer\": \"codex:gpt-5.6-sol@high\",\n      \"implementer\": \"codex:gpt-5.6-sol@high\",\n      \"review\": {\n        \"minimum_score\": 90,\n        \"max_rounds\": 3\n      }\n    },\n    \"exact_target_grammar\": \"<tool>:<model>@<effort>[+fast]\",\n    \"availability\": \"checked_when_used\"\n  }\n}\n",
-  "SoT/toolchain.json": "{\n  \"$comment\": \"Kit toolchain manifest — DATA only (versions, floors, policy); check/install logic lives in cli/src/engine-native/toolchain.ts with per-surface sync callbacks in cli/src/engine-native/. kind: 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.\",\n  \"tools\": {\n    \"jq\":     { \"kind\": \"check\", \"note\": \"optional operator CLI; EngineNative JSON and Claude runtime do not invoke it\" },\n    \"curl\":   { \"kind\": \"check\", \"note\": \"contextual POSIX installer transport for RTK/Bun bootstrap\" },\n    \"git\":    { \"kind\": \"check\", \"note\": \"plugin marketplaces (claude/codex clone them) + kit checkout updates\" },\n    \"node\":   { \"kind\": \"check\", \"note\": \"hosts npm globals (agent-browser, LSP servers)\" },\n    \"npm\":    { \"kind\": \"check\", \"note\": \"npm-global installer\" },\n    \"claude\": { \"kind\": \"check\", \"floor\": \"2.1.170\", \"note\": \"kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)\" },\n    \"codex\":  { \"kind\": \"check\", \"note\": \"upstream-owned; standalone installer prints when missing\" },\n    \"ffplay\": { \"kind\": \"check\", \"note\": \"Notification hook sound (previously unchecked)\" },\n    \"bwrap\":  { \"kind\": \"check\", \"os\": \"linux\", \"note\": \"Codex Linux sandbox runtime\" },\n    \"intelephense\": { \"kind\": \"check\", \"verified\": \"1.18.5\", \"note\": \"php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"typescript-language-server\": { \"kind\": \"check\", \"verified\": \"5.3.0\", \"note\": \"typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"tsc\":    { \"kind\": \"check\", \"verified\": \"6.0.3\", \"note\": \"typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install. Deliberately on the 6.x line: typescript-language-server embeds TypeScript's programmatic API, which TS7 (native) doesn't yet expose — the repo's own devDependency runs TS7 for tsc --noEmit\" },\n    \"rtk\":    { \"kind\": \"managed\", \"policy\": \"track\", \"floor\": \"0.43.0\", \"verified\": \"0.43.0\", \"pinnable\": true,\n                \"note\": \"PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin\" },\n    \"bun\":    { \"kind\": \"managed\", \"policy\": \"present\", \"verified\": \"1.3.14\", \"pinnable\": true,\n                \"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\" },\n    \"effect-solutions\": { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.5.3\", \"pinnable\": true,\n                \"note\": \"Effect docs CLI (bun global) — track keeps it self-upgrading, gated by the verified pin\" },\n    \"agent-browser\":    { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.32.0\", \"pinnable\": true,\n                \"note\": \"browser-automation CLI (npm global), gated by the verified pin; first install also downloads Chrome for Testing\" },\n    \"skills-cli\": { \"kind\": \"pin\", \"verified\": \"1.5.15\",\n                \"note\": \"the `skills` npm package the kit runs via `npx skills@<verified>` on every agents sync (universal-skill install/remove) — pinned, never @latest\" }\n  }\n}\n",
+  "SoT/toolchain.json": "{\n  \"$comment\": \"Kit toolchain manifest — DATA only (versions, floors, policy); check/install logic lives in cli/src/engine-native/toolchain.ts with per-surface sync callbacks in cli/src/engine-native/. kind: check (doctor visibility only) | managed (kit installs/upgrades it) | managed-release (dedicated source-pinned release installer) | 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); managed-release uses exact. `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.\",\n  \"tools\": {\n    \"jq\":     { \"kind\": \"check\", \"note\": \"optional operator CLI; EngineNative JSON and Claude runtime do not invoke it\" },\n    \"curl\":   { \"kind\": \"check\", \"note\": \"contextual POSIX installer transport for RTK/Bun bootstrap\" },\n    \"git\":    { \"kind\": \"check\", \"note\": \"plugin marketplaces (claude/codex clone them) + kit checkout updates\" },\n    \"node\":   { \"kind\": \"check\", \"note\": \"hosts npm globals (agent-browser, LSP servers)\" },\n    \"npm\":    { \"kind\": \"check\", \"note\": \"npm-global installer\" },\n    \"claude\": { \"kind\": \"check\", \"floor\": \"2.1.170\", \"note\": \"kit floor — `best` alias + Fable 5 need >=2.1.170 (mirrors settings minimumVersion)\" },\n    \"codex\":  { \"kind\": \"check\", \"note\": \"upstream-owned; standalone installer prints when missing\" },\n    \"ffplay\": { \"kind\": \"check\", \"note\": \"Notification hook sound (previously unchecked)\" },\n    \"bwrap\":  { \"kind\": \"check\", \"os\": \"linux\", \"note\": \"Codex Linux sandbox runtime\" },\n    \"intelephense\": { \"kind\": \"check\", \"verified\": \"1.18.5\", \"note\": \"php-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"typescript-language-server\": { \"kind\": \"check\", \"verified\": \"5.3.0\", \"note\": \"typescript-lsp server binary; `verified` pins claude::sync_lsp_servers' npm install\" },\n    \"tsc\":    { \"kind\": \"check\", \"verified\": \"6.0.3\", \"note\": \"typescript-lsp dependency (npm package `typescript`); `verified` pins claude::sync_lsp_servers' npm install. Deliberately on the 6.x line: typescript-language-server embeds TypeScript's programmatic API, which TS7 (native) doesn't yet expose — the repo's own devDependency runs TS7 for tsc --noEmit\" },\n    \"rtk\":    { \"kind\": \"managed\", \"policy\": \"track\", \"floor\": \"0.43.0\", \"verified\": \"0.43.0\", \"pinnable\": true,\n                \"note\": \"PreToolUse hook — supply-chain review before unverified upgrades; installer honors RTK_VERSION=vX.Y.Z pin\" },\n    \"bun\":    { \"kind\": \"managed\", \"policy\": \"present\", \"verified\": \"1.3.14\", \"pinnable\": true,\n                \"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\" },\n    \"effect-solutions\": { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.5.3\", \"pinnable\": true,\n                \"note\": \"Effect docs CLI (bun global) — track keeps it self-upgrading, gated by the verified pin\" },\n    \"agent-browser\":    { \"kind\": \"managed\", \"policy\": \"track\", \"verified\": \"0.32.0\", \"pinnable\": true,\n                \"note\": \"browser-automation CLI (npm global), gated by the verified pin; first install also downloads Chrome for Testing\" },\n    \"session-relay\": { \"kind\": \"managed-release\", \"policy\": \"exact\", \"verified\": \"0.12.0\", \"repository\": \"DocksDocks/docks\", \"tag\": \"session-relay--v0.12.0\", \"plugin_id\": \"session-relay@docks\", \"plugin_version\": \"0.12.0\", \"install_path\": \"~/.local/bin/session-relay\",\n                \"assets\": {\n                  \"x86_64-unknown-linux-musl\": \"ead7faead73ba5835879e4823bc4bca6b6d1003d8a9bcbdbea6cf9f266ce5b42\",\n                  \"aarch64-unknown-linux-musl\": \"d7171bbaa33c4da8b0a9e15f9bfe7a3fb31930a1fad95cc9f682f153369b421b\",\n                  \"x86_64-apple-darwin\": \"be12a6f782453d8cc90d98ab77f408f0e7c61b55f8ccdf36bf0584c8cec2f1d8\",\n                  \"aarch64-apple-darwin\": \"5022354025d0c639406cf8b027d824724d8366f74e2b778c37d705e7e9f53889\"\n                } },\n    \"skills-cli\": { \"kind\": \"pin\", \"verified\": \"1.5.15\",\n                \"note\": \"the `skills` npm package the kit runs via `npx skills@<verified>` on every agents sync (universal-skill install/remove) — pinned, never @latest\" }\n  }\n}\n",
   "SoT/.claude/CLAUDE.md": "## Research Before Implementation\n\nBefore writing or modifying code that uses an API, hook, method, or config surface you have not verified in this session, research current documentation first.\n\nResearch workflow:\n1. Prefer official documentation and primary sources for the specific library, framework, or API.\n2. If a local docs or MCP tool is available, use it before broad web search.\n3. Only then proceed to implementation.\n\nResearch when:\n- Installing or configuring a dependency.\n- Using an API, hook, method, or pattern not verified in this session.\n- Upgrading or migrating between versions.\n- Any task where relying on memory could cause stale syntax or behavior.\n\nDo not:\n- Assume API signatures, method names, or config options from memory.\n- Generate framework code without checking current docs first.\n- Skip research because the library seems familiar.\n\n<constraint>\nResearch the codebase before editing. Never change code you have not read.\n</constraint>\n\n## Agentic Harness Heuristics\n\n**1. Persistence.** Keep going until the user's query is completely resolved. Only yield when sure the problem is solved. Before ending a turn, check the last paragraph: if it is a plan, a question you can answer yourself, or a promise of work not done (\"I'll…\"), do that work now.\n\n**2. Default to parallel.** Whenever you have multiple independent operations (reads, greps, web fetches, independent edits), invoke them in a single response with multiple tool-use blocks. Sequential calls only when output of one operation is required as input to the next.\n\n**3. Multi-pass search.** First-pass search often misses — vary the wording (colleague-questions over keywords) before concluding something doesn't exist.\n\n**4. Trace symbols.** Before modifying a symbol, trace it to its definitions and all usages. Don't assume a function's behavior or a type's shape from the call site alone.\n\n**5. Linter-loop 3-strike rule.** Don't loop more than 3 times fixing linter errors on the same file. On the third attempt, stop and ask the user — repeated failure usually means the diagnosis is wrong, not the code.\n\n**6. Read-before-Edit TTL.** If you haven't read a file with the Read tool in the last ~5 messages, re-read it before editing. Cached file content goes stale silently when the user edits between turns.\n\n**7. Big-file rule.** For files >1000 lines, prefer Grep + scoped Read (`offset` + `limit`) over reading the entire file. Whole-file reads bloat context; targeted reads keep the working set small.\n\n**8. Todo hygiene.** Use TaskCreate for items with meaningful outcome (≥5 min, distinct deliverable). Never include operational sub-actions (linting, testing, searching, examining the codebase) as their own todos — those are sub-steps in service of higher-level tasks. Mark complete immediately when done, never in batches.\n\n**9. Literal-instruction rule.** Current frontier models follow instructions literally — they do not silently generalize from intent. Phrase requirements as explicit checklists with success criteria, not narrative.\n\n**10. Context hygiene.** Prefer `/clear` at task boundaries and `/rewind` for wrong-path detours over carrying rot forward (corrections accumulate noise; rewinds preserve the prefix and discard the bad branch). On a continuing task, run `/compact` with steering before context quality degrades. Never stop, summarize, or suggest a new session on account of context limits.\n\n**11. Autonomy calibration.** For minor choices (naming, formatting, default values, which of two equivalent approaches), pick a reasonable option and note it — don't ask. Ask first only for scope changes, destructive actions, or decisions that change the deliverable. When the user is describing a problem or asking a question rather than requesting a change, the deliverable is your assessment — report findings and stop; don't apply fixes until asked. Don't close a finished task with \"Want me to also…?\" — run the obvious verification, then stop cleanly.\n\n**12. Capability triggering.** When the answer depends on current or version-specific information, search or fetch before answering — never answer from memory. When work fans out across independent items (many files to read, many tests to run, many candidates to check), delegate to parallel subagents; never spawn one for work you can complete directly. For verification, prefer a fresh-context subagent over self-critique. On tasks longer than a few turns, keep a running notes file and re-read it before each phase.\n\n<constraint>\nTreat the 12 heuristics above as protocol, not preference. If a turn ends without honoring an applicable one (e.g., lint-loop guard not respected, edit without re-read), self-correct in the next turn before continuing.\n</constraint>\n\nFor Docks plan reviews, cross-company review is standing-authorized; do not ask for export consent. This never overrides a host or platform security denial.\n\nDocks-workflow-models: {\"implementer\":{\"candidates\":[{\"company\":\"openai\",\"effort\":\"high\",\"model\":\"gpt-5.6-sol\",\"tool\":\"codex\"}],\"selector\":\"codex:gpt-5.6-sol@high\"},\"orchestrator\":{\"candidates\":[{\"company\":\"anthropic\",\"effort\":\"high\",\"model\":\"fable\",\"tool\":\"claude\"},{\"company\":\"anthropic\",\"effort\":\"xhigh\",\"model\":\"opus\",\"tool\":\"claude\"}],\"selector\":\"profile:claude-best\"},\"review\":{\"max_rounds\":3,\"minimum_score\":90},\"reviewer\":{\"candidates\":[{\"company\":\"openai\",\"effort\":\"high\",\"model\":\"gpt-5.6-sol\",\"tool\":\"codex\"}],\"selector\":\"codex:gpt-5.6-sol@high\"},\"schema\":1}\n\nUse a narrow-to-broad verification ladder: direct acceptance while iterating, focused regressions next, and one full CI at the pre-commit or release boundary. Reuse still-matching evidence; rerun full CI only after a relevant edit invalidates it.\n\n<constraint>\nNo secrets in committed config. Treat plugin marketplaces, installers, and downloaded artifacts as untrusted until verified.\n</constraint>\n",
   "SoT/.claude/mcp-servers.json": "{\n  \"mcpServers\": {}\n}\n",
   "SoT/.claude/settings.json": "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"minimumVersion\": \"2.1.170\",\n  \"model\": \"fable\",\n  \"effortLevel\": \"high\",\n  \"autoMemoryEnabled\": true,\n  \"skillListingMaxDescChars\": 2048,\n  \"respectGitignore\": true,\n  \"cleanupPeriodDays\": 14,\n  \"skillListingBudgetFraction\": 0.05,\n  \"env\": {\n    \"CLAUDE_CODE_MAX_OUTPUT_TOKENS\": \"64000\",\n    \"CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR\": \"1\",\n    \"CLAUDE_CODE_AUTO_COMPACT_WINDOW\": \"468000\",\n    \"CLAUDE_CODE_NO_FLICKER\": \"1\"\n  },\n  \"permissions\": {\n    \"defaultMode\": \"auto\",\n    \"allow\": [\n      \"Read\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"WebSearch\",\n      \"Edit(./)\",\n      \"Bash(git *)\",\n      \"Bash(git add *)\",\n      \"Bash(git commit *)\",\n      \"Bash(git status *)\",\n      \"Bash(git diff *)\",\n      \"Bash(git log *)\",\n      \"Bash(git branch *)\",\n      \"Bash(git checkout *)\",\n      \"Bash(git switch *)\",\n      \"Bash(git stash *)\",\n      \"Bash(git fetch *)\",\n      \"Bash(git pull *)\",\n      \"Bash(git tag *)\",\n      \"Bash(git show *)\",\n      \"Bash(git blame *)\",\n      \"Bash(git worktree *)\",\n      \"Bash(gh *)\",\n      \"Bash(pnpm *)\",\n      \"Bash(npm *)\",\n      \"Bash(npx *)\",\n      \"Bash(node *)\",\n      \"Bash(docker *)\",\n      \"Bash(docker-compose *)\",\n      \"Bash(rtk *)\",\n      \"Bash(ls *)\",\n      \"Bash(cat *)\",\n      \"Bash(find *)\",\n      \"Bash(grep *)\",\n      \"Bash(head *)\",\n      \"Bash(tail *)\",\n      \"Bash(wc *)\",\n      \"Bash(sort *)\",\n      \"Bash(uniq *)\",\n      \"Bash(diff *)\",\n      \"Bash(which *)\",\n      \"Bash(pwd *)\",\n      \"Bash(date *)\",\n      \"Bash(mkdir *)\",\n      \"Bash(basename *)\",\n      \"Bash(dirname *)\",\n      \"Bash(realpath *)\",\n      \"Bash(jq *)\",\n      \"Bash(curl *)\",\n      \"Bash(tree *)\",\n      \"Bash(sed *)\",\n      \"Bash(awk *)\",\n      \"Bash(cut *)\",\n      \"Bash(tr *)\",\n      \"Bash(tee *)\",\n      \"Bash(echo *)\",\n      \"Bash(printf *)\",\n      \"Bash(env *)\",\n      \"Bash(printenv *)\",\n      \"Bash(uname *)\",\n      \"Bash(file *)\",\n      \"Bash(stat *)\",\n      \"Bash(du *)\",\n      \"Bash(id *)\",\n      \"Bash(whoami *)\",\n      \"Bash(php *)\",\n      \"Bash(composer *)\",\n      \"Bash(python3 *)\",\n      \"Bash(python *)\",\n      \"Bash(pip *)\",\n      \"Bash(pip3 *)\"\n    ],\n    \"deny\": [\n      \"Read(**/.env)\",\n      \"Read(**/.env.local)\",\n      \"Read(**/secrets/**)\",\n      \"Read(**/*.key)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.p12)\",\n      \"Read(**/.credentials*)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.local)\",\n      \"Edit(**/secrets/**)\",\n      \"Bash(sudo *)\",\n      \"Bash(rm -rf /)\",\n      \"Bash(rm -rf / *)\",\n      \"Bash(rm -rf ~)\",\n      \"Bash(rm -rf ~ *)\",\n      \"Bash(rm -rf $HOME)\",\n      \"Bash(rm -rf $HOME *)\",\n      \"Bash(> /dev *)\",\n      \"Bash(dd if= *)\",\n      \"Bash(mkfs *)\",\n      \"Bash(eval *)\",\n      \"Bash(chmod 777 *)\",\n      \"Bash(chmod -R 777 *)\",\n      \"Bash(git push --force origin main *)\",\n      \"Bash(git push --force origin master *)\",\n      \"Bash(git push -f origin main *)\",\n      \"Bash(git push -f origin master *)\"\n    ],\n    \"ask\": [\n      \"Bash(git clean *)\",\n      \"Bash(docker volume rm *)\",\n      \"Bash(docker system prune *)\"\n    ]\n  },\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_SESSION_START__\"],\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"__DOCKS_KIT_BUN__\",\n            \"args\": [\"__DOCKS_KIT_NOTIFY__\"],\n            \"timeout\": 10,\n            \"async\": true\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"rtk hook claude\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUseFailure\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo '{\\\"hookSpecificOutput\\\":{\\\"hookEventName\\\":\\\"PostToolUseFailure\\\",\\\"additionalContext\\\":\\\"Last bash command failed. Repository / file state may have shifted \\u2014 re-read affected files before retrying. If the failure is a missing dependency or env mismatch, surface it to the user rather than retrying blindly.\\\"}}'\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"You are a quality gate for subagent outputs in a multi-agent code-analysis pipeline.\\n\\nEvaluate the subagent's `last_assistant_message` field (in the JSON below) against these requirements:\\n\\n1. ALLOW (return `{}`): Mode-selection or no-issues responses. Examples: \\\"Which mode do you prefer\\\", \\\"select an option\\\", \\\"no issues / problems / violations / blockers found\\\".\\n\\n2. ALLOW (return `{}`): Output contains at least one concrete file:line citation \\u2014 e.g. `src/auth.ts:42`, `lib/db.ts:100-115`, or path references that include line numbers.\\n\\n3. BLOCK (return `{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"<one-line explanation>\\\"}`): Output claims about code or findings WITHOUT concrete file:line citations. Vague references like \\\"the auth handler\\\" or \\\"near the database code\\\" are not acceptable as the only evidence.\\n\\nSubagent invocation JSON:\\n$ARGUMENTS\\n\\nReturn ONLY the JSON decision (no commentary, no markdown fences).\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  },\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"__DOCKS_KIT_STATUSLINE__\",\n    \"refreshInterval\": 5\n  },\n  \"enabledPlugins\": {\n    \"docks@docks\": true,\n    \"session-relay@docks\": true,\n    \"effect-kit@docks\": true,\n    \"php-lsp@claude-plugins-official\": true,\n    \"typescript-lsp@claude-plugins-official\": true\n  },\n  \"extraKnownMarketplaces\": {\n    \"docks\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"DocksDocks/docks\"\n      }\n    }\n  },\n  \"alwaysThinkingEnabled\": true,\n  \"showThinkingSummaries\": true,\n  \"viewMode\": \"default\",\n  \"theme\": \"dark-daltonized\",\n  \"skipDangerousModePermissionPrompt\": true\n}\n",
@@ -40,4 +40,4 @@ export const GENERATED_PAYLOAD_PATHS = [
   "notification.mp3"
 ] as const
 
-export const GENERATED_PAYLOAD_HASH = "4decac588a31cdaf6cbc88997bccb77add7bf0cbcfc3ae0fba30eca23525707d"
+export const GENERATED_PAYLOAD_HASH = "a549edb9fd7a7c9a1684ea31bc3b252c66c358e45efe6e7eea9d7ce66dacf753"

package/docks-kit

@@ -11,17 +11,18 @@ REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
 BUN_PIN="1.3.14"
 # END GENERATED BUN PIN
 
-case "$(uname -s)-$(uname -m)" in
-  Linux-x86_64)   KIT_BIN="docks-kit-linux-x64" ;;
-  Linux-aarch64)  KIT_BIN="docks-kit-linux-arm64" ;;
-  Darwin-x86_64)  KIT_BIN="docks-kit-darwin-x64" ;;
-  Darwin-arm64)   KIT_BIN="docks-kit-darwin-arm64" ;;
-  # Git Bash unames look like MINGW64_NT-10.0-19045-x86_64. The compiled
-  # binary is the supported Windows path; the Bun fallback below is Unix-shaped.
-  MINGW*-x86_64|MSYS*-x86_64|CYGWIN*-x86_64) KIT_BIN="docks-kit-windows-x64.exe" ;;
-  *)              KIT_BIN="" ;;
+HOST="$(uname -s)-$(uname -m)"
+case "$HOST" in
+  Linux-x86_64)  KIT_BIN="docks-kit-linux-x64" ;;
+  Linux-aarch64) KIT_BIN="docks-kit-linux-arm64" ;;
+  Darwin-x86_64) KIT_BIN="docks-kit-darwin-x64" ;;
+  Darwin-arm64)  KIT_BIN="docks-kit-darwin-arm64" ;;
+  *)
+    echo "[docks-kit] unsupported host $HOST; docks-kit supports only Linux and macOS on x64 or arm64." >&2
+    exit 1
+    ;;
 esac
-if [[ -n "$KIT_BIN" && -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
+if [[ -x "$REPO_DIR/cli/dist/$KIT_BIN" ]]; then
   CHECKOUT_VERSION=""
   while IFS= read -r line; do
     if [[ "$line" =~ ^[[:space:]]*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]]; then

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "docks-kit",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",
+  "os": [
+    "linux",
+    "darwin"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DocksDocks/public.git"

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

@@ -1,11 +0,0 @@
-export function powerShellLiteral(value: string): string {
-  return `'${value.replaceAll("'", "''")}'`
-}
-
-export function encodePowerShellCommand(script: string): string {
-  return Buffer.from(script, "utf16le").toString("base64")
-}
-
-export function decodePowerShellCommand(encoded: string): string {
-  return Buffer.from(encoded, "base64").toString("utf16le")
-}