docks-kit 0.1.0

package/cli/src/commands/model.ts

@@ -0,0 +1,60 @@
+import { Args, Command, Options, Prompt } from "@effect/cli"
+import { Effect, Option } from "effect"
+import { bail, engine } from "../engine"
+import { modelCatalog, type Tool } from "../manifests"
+
+const tool = Args.text({ name: "tool" }).pipe(
+  Args.withDescription("Which tool: claude | codex")
+)
+const value = Args.text({ name: "value" }).pipe(
+  Args.withDescription("Model to set (omit to view current + pick interactively on a TTY)"),
+  Args.optional
+)
+const dryRun = Options.boolean("dry-run").pipe(
+  Options.withDescription("Preview without applying")
+)
+
+const KEEP = "__keep__"
+
+export const modelCommand = Command.make(
+  "model",
+  { tool, value, dryRun },
+  (config) =>
+    Effect.gen(function* () {
+      if (config.tool !== "claude" && config.tool !== "codex") {
+        return yield* bail(`Unknown tool '${config.tool}' (valid: claude, codex)`)
+      }
+      const t = config.tool as Tool
+      const dry = config.dryRun ? ["--dry-run"] : []
+
+      if (Option.isSome(config.value)) {
+        return yield* engine(["model", t, config.value.value, ...dry])
+      }
+
+      // No value: show current (engine prints deployed + SoT + catalog) …
+      yield* engine(["model", t])
+
+      // … and offer an interactive picker when attached to a terminal.
+      if (!process.stdin.isTTY || !process.stdout.isTTY) return
+
+      const catalog = modelCatalog(t)
+      const chosen = yield* Prompt.select({
+        message: `Set the deployed ${t} model (deployed config only; a flag-less sync reverts to SoT)`,
+        choices: [
+          { title: "(keep current)", value: KEEP },
+          ...catalog.models.map((m) => ({
+            title: m.id,
+            value: m.id,
+            description: m.note ?? ""
+          }))
+        ]
+      })
+      if (chosen !== KEEP) {
+        yield* engine(["model", t, chosen, ...dry])
+      }
+    })
+).pipe(
+  Command.withDescription(
+    "Get or set the DEPLOYED model for one tool without a full sync (deploy-time modifier semantics: SoT untouched; flag-less sync reverts)."
+  )
+)

package/cli/src/commands/models.ts

@@ -0,0 +1,46 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { bail } from "../engine"
+import { modelCatalog, type Tool } from "../manifests"
+
+const tool = Args.text({ name: "tool" }).pipe(
+  Args.withDescription("claude | codex (omit for both)"),
+  Args.optional
+)
+const json = Options.boolean("json").pipe(
+  Options.withDescription("Machine-readable output")
+)
+
+const renderTool = (t: Tool) =>
+  Effect.gen(function* () {
+    const catalog = modelCatalog(t)
+    yield* Console.log(`${t} models (kit-verified ${catalog.verified}):`)
+    for (const m of catalog.models) {
+      yield* Console.log(`  ${m.id.padEnd(28)} ${m.kind.padEnd(6)} ${m.note ?? ""}`)
+    }
+    yield* Console.log("")
+  })
+
+export const modelsCommand = Command.make("models", { tool, json }, (config) =>
+  Effect.gen(function* () {
+    const requested = Option.getOrUndefined(config.tool)
+    if (requested !== undefined && requested !== "claude" && requested !== "codex") {
+      return yield* bail(`Unknown tool '${requested}' (valid: claude, codex)`)
+    }
+    const tools: Array<Tool> = requested !== undefined ? [requested as Tool] : ["claude", "codex"]
+
+    if (config.json) {
+      const out = Object.fromEntries(tools.map((t) => [t, modelCatalog(t)]))
+      return yield* Console.log(JSON.stringify(out, null, 2))
+    }
+
+    for (const t of tools) {
+      yield* renderTool(t)
+    }
+    yield* Console.log(
+      "Catalog: SoT/models.json (research-verified). Well-formed IDs outside it apply with a warning."
+    )
+  })
+).pipe(
+  Command.withDescription("List the kit-verified model catalog (SoT/models.json) for claude/codex.")
+)

package/cli/src/commands/plugins.ts

@@ -0,0 +1,34 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { bail } from "../engine"
+import { pluginsView } from "../manifests"
+
+const action = Args.text({ name: "action" }).pipe(
+  Args.withDescription("list (default)"),
+  Args.optional
+)
+const json = Options.boolean("json").pipe(
+  Options.withDescription("Machine-readable output")
+)
+
+export const pluginsCommand = Command.make("plugins", { action, json }, (config) =>
+  Effect.gen(function* () {
+    const act = Option.getOrElse(config.action, () => "list")
+    if (act !== "list") {
+      return yield* bail(
+        `Unknown plugins action '${act}' (valid: list). Install/removal runs through sync: --claude-plugin=<name> opts in, --prune reconciles.`
+      )
+    }
+    const view = pluginsView()
+    if (config.json) {
+      return yield* Console.log(JSON.stringify(view, null, 2))
+    }
+    yield* Console.log("SoT tri-state: true = enabled everywhere, false = installed-but-disabled (per-project enable), absent = not kit-managed\n")
+    yield* Console.log(`${"PLUGIN".padEnd(44)} ${"SOT".padEnd(7)} INSTALLED`)
+    for (const p of view) {
+      yield* Console.log(`${p.plugin.padEnd(44)} ${p.sot.padEnd(7)} ${p.installed ? "yes" : "no"}`)
+    }
+  })
+).pipe(
+  Command.withDescription("Installed plugins vs SoT enabledPlugins tri-state (read-only).")
+)

package/cli/src/commands/skills.ts

@@ -0,0 +1,37 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Console, Effect, Option } from "effect"
+import { bail } from "../engine"
+import { skillsView } from "../manifests"
+
+const action = Args.text({ name: "action" }).pipe(
+  Args.withDescription("list (default)"),
+  Args.optional
+)
+const json = Options.boolean("json").pipe(
+  Options.withDescription("Machine-readable output")
+)
+
+export const skillsCommand = Command.make("skills", { action, json }, (config) =>
+  Effect.gen(function* () {
+    const act = Option.getOrElse(config.action, () => "list")
+    if (act !== "list") {
+      return yield* bail(
+        `Unknown skills action '${act}' (valid: list). Declare skills in SoT/.agents/skills.txt and run sync; --prune removes undeclared kit-managed ones.`
+      )
+    }
+    const view = skillsView()
+    if (config.json) {
+      return yield* Console.log(JSON.stringify(view, null, 2))
+    }
+    yield* Console.log(`${"SKILL".padEnd(28)} ${"DECLARED".padEnd(9)} ${"INSTALLED".padEnd(10)} CLAUDE-SYMLINK`)
+    for (const s of view) {
+      yield* Console.log(
+        `${s.skill.padEnd(28)} ${(s.declared ? "yes" : "no").padEnd(9)} ${(s.installed ? "yes" : "no").padEnd(10)} ${s.claudeSymlink ? "ok" : "-"}`
+      )
+    }
+  })
+).pipe(
+  Command.withDescription(
+    "Universal agent skills: SoT/.agents/skills.txt vs ~/.agents/skills + the ~/.claude/skills symlink health (read-only)."
+  )
+)

package/cli/src/commands/status.ts

@@ -0,0 +1,79 @@
+import { Command, Options } from "@effect/cli"
+import { Console, Effect } from "effect"
+import { engineCapture } from "../engine"
+import {
+  deployedClaudeSettings,
+  deployedCodexModel,
+  pluginsView,
+  skillsView,
+  sotClaudeSettings,
+  sotCodexModel
+} from "../manifests"
+import { kitHome } from "../kitHome"
+
+const json = Options.boolean("json").pipe(
+  Options.withDescription("Machine-readable output")
+)
+
+interface Drift {
+  readonly setting: string
+  readonly deployed: string
+  readonly sot: string
+  readonly drifted: boolean
+}
+
+const gatherDrift = (): Array<Drift> => {
+  const sot = sotClaudeSettings()
+  const dep = deployedClaudeSettings() ?? {}
+  const row = (setting: string, deployed: unknown, sotVal: unknown): Drift => {
+    const d = String(deployed ?? "(unset)")
+    const s = String(sotVal ?? "(unset)")
+    return { setting, deployed: d, sot: s, drifted: d !== s }
+  }
+  return [
+    row("claude.model", dep.model, sot.model),
+    row("claude.effortLevel", dep.effortLevel, sot.effortLevel),
+    row(
+      "claude.compactWindow",
+      dep.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW,
+      sot.env?.CLAUDE_CODE_AUTO_COMPACT_WINDOW
+    ),
+    row("codex.model", deployedCodexModel(), sotCodexModel())
+  ]
+}
+
+export const statusCommand = Command.make("status", { json }, (config) =>
+  Effect.gen(function* () {
+    const drift = gatherDrift()
+    const plugins = pluginsView()
+    const skills = skillsView()
+    const toolchainTable = yield* engineCapture(["toolchain", "check"])
+
+    if (config.json) {
+      return yield* Console.log(
+        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, toolchainTable }, null, 2)
+      )
+    }
+
+    yield* Console.log(`Kit home: ${kitHome()}\n`)
+    yield* Console.log("Deployed vs SoT (drift is expected for deploy-time modifiers):")
+    for (const d of drift) {
+      const mark = d.drifted ? "≠" : "="
+      yield* Console.log(`  ${d.setting.padEnd(22)} deployed=${d.deployed}  ${mark}  SoT=${d.sot}`)
+    }
+    yield* Console.log("\nToolchain:")
+    yield* Console.log(toolchainTable.trimEnd())
+    const enabled = plugins.filter((p) => p.sot === "true").length
+    yield* Console.log(
+      `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`
+    )
+    const installed = skills.filter((s) => s.installed).length
+    yield* Console.log(
+      `Skills:  ${skills.length} known (${installed} installed) — details: docks-kit skills list`
+    )
+  })
+).pipe(
+  Command.withDescription(
+    "Doctor view: deployed-vs-SoT drift (model, effort, compact window), toolchain table, plugin/skill counts."
+  )
+)

package/cli/src/commands/sync.ts

@@ -0,0 +1,134 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Effect, Option } from "effect"
+import { bail, engine } from "../engine"
+import { modelCatalog, type Tool } from "../manifests"
+
+const VALID_TARGETS = ["claude", "codex", "agents"]
+
+// Renamed sync.sh-era flags: @effect/cli routes unknown flags into the excess
+// positional args, so the rename hints (lib/common.sh's exit-2 arms) are
+// mirrored here to keep the parser contract identical across both front-ends.
+const LEGACY_HINTS: Record<string, string> = {
+  "--force": "--force was renamed to --reconcile",
+  "--remove-plugins":
+    "--remove-plugins was renamed to --prune (it also removes marketplaces + kit-managed skills)",
+  "--680k": "--680k was renamed to --claude-compact-window=680k",
+  "--permissive": "--permissive was renamed to --claude-permissive",
+  "--supabase": "--supabase was renamed to --claude-plugin=supabase",
+  "--n8n": "--n8n was renamed to --claude-plugin=n8n",
+  "--no-rtk": "--no-rtk was renamed to --skip-rtk",
+  "--claude": "--claude was renamed: pass the target as a word, e.g. 'sync claude'",
+  "--codex": "--codex was renamed: pass the target as a word, e.g. 'sync codex'",
+  "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
+}
+
+const catalogHint = (t: Tool): string => {
+  const c = modelCatalog(t)
+  const list = c.models
+    .map((m) => `  ${m.id}${m.note !== undefined ? `  — ${m.note}` : ""}`)
+    .join("\n")
+  return `Available ${t} models (kit-verified ${c.verified} — SoT/models.json):\n${list}`
+}
+
+const targets = Args.text({ name: "target" }).pipe(
+  Args.withDescription("Sync targets: claude, codex, agents (default: all three)"),
+  Args.repeated
+)
+
+const dryRun = Options.boolean("dry-run").pipe(
+  Options.withDescription("Preview without applying")
+)
+const reconcile = Options.boolean("reconcile").pipe(
+  Options.withDescription("Reconcile kit-owned settings with SoT (SoT keys win; user-only keys preserved; permissions arrays replaced)")
+)
+const prune = Options.boolean("prune").pipe(
+  Options.withDescription("Uninstall kit-managed installs not in SoT (plugins, marketplaces, universal skills)")
+)
+const skipRtk = Options.boolean("skip-rtk").pipe(
+  Options.withDescription("Skip optional tool bootstrap (RTK, bubblewrap)")
+)
+const yes = Options.boolean("yes").pipe(
+  Options.withDescription("Auto-accept toolchain prompts (containers/CI)")
+)
+const claudeModel = Options.text("claude-model").pipe(
+  Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
+  Options.optional
+)
+const claudeCompactWindow = Options.text("claude-compact-window").pipe(
+  Options.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
+  Options.optional
+)
+const claudePermissive = Options.boolean("claude-permissive").pipe(
+  Options.withDescription("Deploy-time modifier: empty permissions.ask/deny in deployed settings (sandboxes)")
+)
+const claudePlugin = Options.text("claude-plugin").pipe(
+  Options.withDescription(
+    "Sticky opt-in plugin(s); repeatable and/or comma-separated (known: supabase, n8n)"
+  ),
+  Options.repeated
+)
+const codexModel = Options.text("codex-model").pipe(
+  Options.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
+  Options.optional
+)
+
+export const syncCommand = Command.make(
+  "sync",
+  {
+    targets,
+    dryRun,
+    reconcile,
+    prune,
+    skipRtk,
+    yes,
+    claudeModel,
+    claudeCompactWindow,
+    claudePermissive,
+    claudePlugin,
+    codexModel
+  },
+  (config) =>
+    Effect.gen(function* () {
+      for (const t of config.targets) {
+        if (VALID_TARGETS.includes(t)) continue
+        if (t === "--claude-model" || t === "--codex-model") {
+          const tool: Tool = t === "--claude-model" ? "claude" : "codex"
+          return yield* bail(`${catalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
+        }
+        const hint = LEGACY_HINTS[t]
+        if (hint !== undefined) {
+          return yield* bail(hint)
+        }
+      }
+      const bad = config.targets.filter((t) => !VALID_TARGETS.includes(t))
+      if (bad.length > 0) {
+        return yield* bail(
+          `Unknown sync target(s): ${bad.join(", ")} (valid: ${VALID_TARGETS.join(", ")})`
+        )
+      }
+
+      const args: Array<string> = ["sync", ...config.targets]
+      if (config.dryRun) args.push("--dry-run")
+      if (config.reconcile) args.push("--reconcile")
+      if (config.prune) args.push("--prune")
+      if (config.skipRtk) args.push("--skip-rtk")
+      if (config.yes) args.push("--yes")
+      if (config.claudePermissive) args.push("--claude-permissive")
+      Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`))
+      Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`))
+      Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`))
+      for (const occurrence of config.claudePlugin) {
+        occurrence
+          .split(",")
+          .map((p) => p.trim())
+          .filter((p) => p.length > 0)
+          .forEach((p) => args.push(`--claude-plugin=${p}`))
+      }
+
+      yield* engine(args)
+    })
+).pipe(
+  Command.withDescription(
+    "Deploy the SoT to this machine (engine: lib/engine.sh — same flags, zero-dependency escape hatch). Deploy-time modifiers touch deployed config only; a later flag-less sync reverts them to SoT."
+  )
+)

package/cli/src/commands/toolchain.ts

@@ -0,0 +1,42 @@
+import { Args, Command, Options } from "@effect/cli"
+import { Effect, Option } from "effect"
+import { bail, engine } from "../engine"
+
+const MANAGED = ["rtk", "bun", "effect-solutions", "agent-browser"]
+
+const op = Args.text({ name: "op" }).pipe(
+  Args.withDescription("check (default) | ensure <tool>"),
+  Args.optional
+)
+const tool = Args.text({ name: "tool" }).pipe(
+  Args.withDescription(`Managed tool for ensure: ${MANAGED.join(", ")}`),
+  Args.optional
+)
+const yes = Options.boolean("yes").pipe(
+  Options.withDescription("Auto-accept above-verified installs")
+)
+
+export const toolchainCommand = Command.make("toolchain", { op, tool, yes }, (config) =>
+  Effect.gen(function* () {
+    const operation = Option.getOrElse(config.op, () => "check")
+    const flags = config.yes ? ["--yes"] : []
+
+    switch (operation) {
+      case "check":
+        return yield* engine(["toolchain", "check"])
+      case "ensure": {
+        const t = Option.getOrUndefined(config.tool)
+        if (t === undefined || !MANAGED.includes(t)) {
+          return yield* bail(`toolchain ensure needs a managed tool: ${MANAGED.join(", ")}`)
+        }
+        return yield* engine(["toolchain", "ensure", t, ...flags])
+      }
+      default:
+        return yield* bail(`Unknown toolchain op '${operation}' (valid: check, ensure)`)
+    }
+  })
+).pipe(
+  Command.withDescription(
+    "Verified-version floors for external tools (SoT/toolchain.json): check prints the doctor table; ensure installs/upgrades one managed tool per policy (above-verified versions prompt; --yes accepts)."
+  )
+)

package/cli/src/engine.ts

@@ -0,0 +1,36 @@
+import { Command as Subprocess } from "@effect/platform"
+import { Console, Effect } from "effect"
+import { kitHome } from "./kitHome"
+
+/**
+ * The single seam between the typed CLI and the bash engine. All mutation runs
+ * through lib/engine.sh (same flag vocabulary as this CLI), so the engine stays
+ * independently usable as the zero-dependency escape hatch.
+ */
+export const engine = (args: ReadonlyArray<string>) =>
+  Effect.gen(function* () {
+    const code = yield* Subprocess.make("bash", join("lib/engine.sh"), ...args).pipe(
+      Subprocess.workingDirectory(kitHome()),
+      Subprocess.stdin("inherit"),
+      Subprocess.stdout("inherit"),
+      Subprocess.stderr("inherit"),
+      Subprocess.exitCode
+    )
+    if (code !== 0) {
+      yield* Effect.sync(() => process.exit(code))
+    }
+  })
+
+/** Run the engine capturing stdout (engine logs/warns go to stderr and pass through). */
+export const engineCapture = (args: ReadonlyArray<string>) =>
+  Subprocess.make("bash", join("lib/engine.sh"), ...args).pipe(
+    Subprocess.workingDirectory(kitHome()),
+    Subprocess.stderr("inherit"),
+    Subprocess.string
+  )
+
+const join = (rel: string): string => `${kitHome()}/${rel}`
+
+/** Print a message to stderr and exit — for CLI-side validation failures. */
+export const bail = (message: string, code = 2) =>
+  Console.error(message).pipe(Effect.andThen(Effect.sync(() => process.exit(code))))

package/cli/src/kitHome.ts

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+const isKitHome = (dir: string): boolean =>
+  existsSync(join(dir, "SoT")) && existsSync(join(dir, "lib", "engine.sh"))
+
+/**
+ * Resolve the kit home (the directory holding SoT/ + lib/engine.sh):
+ * DOCKS_KIT_HOME env → nearest ancestor of cwd (repo-checkout usage) →
+ * the package's own root (bunx / bun add -g usage: main.ts lives at
+ * <root>/cli/src, and the npm package bundles SoT/ + lib/ alongside).
+ */
+export const kitHome = (): string => {
+  const env = process.env["DOCKS_KIT_HOME"]
+  if (env !== undefined && env !== "") {
+    if (isKitHome(env)) return env
+    throw new Error(`DOCKS_KIT_HOME=${env} does not contain SoT/ + lib/engine.sh`)
+  }
+  let dir = process.cwd()
+  for (;;) {
+    if (isKitHome(dir)) return dir
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  const packageRoot = resolve(import.meta.dir, "..", "..")
+  if (isKitHome(packageRoot)) return packageRoot
+  throw new Error(
+    "docks-kit home not found — run inside the kit repo or set DOCKS_KIT_HOME"
+  )
+}

package/cli/src/main.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+import { Command } from "@effect/cli"
+import { BunContext, BunRuntime } from "@effect/platform-bun"
+import { Console, Effect } from "effect"
+import { docsCommand } from "./commands/docs"
+import { modelCommand } from "./commands/model"
+import { modelsCommand } from "./commands/models"
+import { pluginsCommand } from "./commands/plugins"
+import { skillsCommand } from "./commands/skills"
+import { statusCommand } from "./commands/status"
+import { syncCommand } from "./commands/sync"
+import { toolchainCommand } from "./commands/toolchain"
+
+const root = Command.make("docks-kit", {}, () =>
+  Effect.gen(function* () {
+    yield* Console.log("docks-kit — portable AI coding agent config kit")
+    yield* Console.log("")
+    yield* Console.log("  docks-kit sync [claude] [codex] [agents]   deploy the SoT to this machine")
+    yield* Console.log("  docks-kit model <claude|codex> [value]     get/set the deployed model")
+    yield* Console.log("  docks-kit models [tool]                    kit-verified model catalog")
+    yield* Console.log("  docks-kit toolchain [check|ensure <tool>]  verified-version floors")
+    yield* Console.log("  docks-kit status                           deployed-vs-SoT doctor view")
+    yield* Console.log("  docks-kit plugins list                     plugin tri-state")
+    yield* Console.log("  docks-kit skills list                      universal skills")
+    yield* Console.log("  docks-kit docs [topic]                     self-documentation")
+    yield* Console.log("")
+    yield* Console.log("Run 'docks-kit --help' for full option listings (also: --wizard, --completions).")
+    yield* Console.log("Zero-dependency escape hatch: bash lib/engine.sh <same subcommands/flags>")
+  })
+).pipe(
+  Command.withDescription(
+    "Portable AI coding agent config kit — SoT sync engine + helpers for Claude Code, Codex, and universal agent skills."
+  ),
+  Command.withSubcommands([
+    syncCommand,
+    modelCommand,
+    modelsCommand,
+    toolchainCommand,
+    statusCommand,
+    pluginsCommand,
+    skillsCommand,
+    docsCommand
+  ])
+)
+
+const cli = Command.run(root, {
+  name: "docks-kit",
+  version: "0.1.0"
+})
+
+// @effect/cli's Options.repeated does not accept `--flag=value` syntax (only
+// `--flag value`), but the documented form for the repeatable opt-in is
+// `--claude-plugin=<name>` — normalize it here so both spellings work.
+const argv = process.argv.flatMap((a) =>
+  a.startsWith("--claude-plugin=")
+    ? ["--claude-plugin", a.slice("--claude-plugin=".length)]
+    : [a]
+)
+
+cli(argv).pipe(Effect.provide(BunContext.layer), BunRuntime.runMain)

package/cli/src/manifests.ts

@@ -0,0 +1,105 @@
+import { readFileSync, readdirSync, readlinkSync, existsSync } from "node:fs"
+import { join } from "node:path"
+import { kitHome } from "./kitHome"
+
+export interface ModelEntry {
+  readonly id: string
+  readonly kind: "alias" | "id"
+  readonly note?: string
+}
+
+export interface ModelCatalog {
+  readonly verified: string
+  readonly models: ReadonlyArray<ModelEntry>
+}
+
+export type Tool = "claude" | "codex"
+
+const readJson = (path: string): any => JSON.parse(readFileSync(path, "utf8"))
+
+export const modelCatalog = (tool: Tool): ModelCatalog =>
+  readJson(join(kitHome(), "SoT", "models.json"))[tool]
+
+export const toolchainManifest = (): Record<string, any> =>
+  readJson(join(kitHome(), "SoT", "toolchain.json")).tools
+
+/** SoT settings (claude) — model/effort/env for drift display. */
+export const sotClaudeSettings = (): any =>
+  readJson(join(kitHome(), "SoT", ".claude", "settings.json"))
+
+export const deployedClaudeSettings = (): any | undefined => {
+  const p = join(homedir(), ".claude", "settings.json")
+  return existsSync(p) ? readJson(p) : undefined
+}
+
+const tomlModel = (path: string): string | undefined => {
+  if (!existsSync(path)) return undefined
+  const m = readFileSync(path, "utf8").match(/^model\s*=\s*"([^"]+)"/m)
+  return m?.[1]
+}
+
+export const sotCodexModel = (): string | undefined =>
+  tomlModel(join(kitHome(), "SoT", ".codex", "config.toml"))
+
+export const deployedCodexModel = (): string | undefined =>
+  tomlModel(join(homedir(), ".codex", "config.toml"))
+
+export const homedir = (): string => process.env["HOME"] ?? "~"
+
+/** Installed plugins (user scope) vs SoT enabledPlugins tri-state. */
+export const pluginsView = (): Array<{
+  plugin: string
+  sot: "true" | "false" | "absent"
+  installed: boolean
+}> => {
+  const sot: Record<string, boolean> = sotClaudeSettings().enabledPlugins ?? {}
+  const installedPath = join(homedir(), ".claude", "plugins", "installed_plugins.json")
+  const installed: Record<string, unknown> = existsSync(installedPath)
+    ? readJson(installedPath).plugins ?? {}
+    : {}
+  const names = new Set([...Object.keys(sot), ...Object.keys(installed)])
+  return [...names].sort().map((plugin) => ({
+    plugin,
+    sot: plugin in sot ? (sot[plugin] ? "true" : "false") : "absent",
+    installed: plugin in installed
+  }))
+}
+
+/** Universal skills: SoT manifest slugs vs ~/.agents/skills contents. */
+export const skillsView = (): Array<{
+  skill: string
+  declared: boolean
+  installed: boolean
+  claudeSymlink: boolean
+}> => {
+  const manifestPath = join(kitHome(), "SoT", ".agents", "skills.txt")
+  const declared = existsSync(manifestPath)
+    ? readFileSync(manifestPath, "utf8")
+        .split("\n")
+        .map((l) => l.replace(/#.*$/, "").trim())
+        .filter((l) => l.length > 0)
+        .map((slug) => slug.split("/").pop() as string)
+    : []
+  const skillsDir = join(homedir(), ".agents", "skills")
+  const installed = existsSync(skillsDir)
+    ? readdirSync(skillsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+    : []
+  const names = new Set([...declared, ...installed])
+  return [...names].sort().map((skill) => {
+    const link = join(homedir(), ".claude", "skills", skill)
+    let claudeSymlink = false
+    try {
+      claudeSymlink = readlinkSync(link).includes(".agents/skills")
+    } catch {
+      /* not a symlink or missing */
+    }
+    return {
+      skill,
+      declared: declared.includes(skill),
+      installed: installed.includes(skill),
+      claudeSymlink
+    }
+  })
+}

package/cli/src/md.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string
+  export default content
+}