docks-kit 0.14.3 → 0.15.0

package/AGENTS.md

@@ -21,7 +21,7 @@ Bun source.
 |------|---------|
 | `docks-kit` | CLI launcher: on supported hosts, runs the platform binary in `cli/dist/` only when its `--version` matches `package.json`, otherwise Bun-from-source (auto-installs Bun + `node_modules`). Unsupported hosts fail before source fallback. No-Bun recovery is the standalone platform release binary |
 | `cli/src/engine-native/` | EngineNative implementation for `sync`, `model`, and `toolchain`; idempotent, flag-gated for destructive reconciliation |
-| `cli/` | Effect-TS CLI + bundled docs topics |
+| `cli/` | Effect 4 beta CLI + bundled docs topics |
 | `SoT/models.json` | Kit-verified Claude and Codex model catalog |
 | `SoT/toolchain.json` | Toolchain floors manifest (verified pins consumed by EngineNative) |
 | `SoT/.claude/bin/` | Dependency-free Bun runtime programs for Claude's statusline, SessionStart, and Notification |
@@ -51,6 +51,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
+- **Effect 4 CLI stack.** The CLI pins `effect@4.0.0-beta.107` (including `effect/unstable/cli`), `@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer`, `BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10` (required by the `@effect/vitest` peer range). `@effect/cli` and `@effect/platform` are removed and must not be reintroduced.
+- **Effect skill routing.** Effect work in this checkout must use the `effect-v4` skill from the already-enabled `effect-kit@docks` plugin; `effect-ts-setup`, `effect-ts-port`, and `effect-ts-specialist` target Effect 3.x and do not apply. Verify migration and API call shapes against the installed declarations under `node_modules/effect/dist/unstable/cli/`, never from memory or a mutable dist-tag.
 - **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-bubblewrap` (skip optional bubblewrap bootstrap for the Codex Linux sandbox), `--skip-plugin-refresh` (install missing plugins without refreshing existing caches; used by `docks-kit update`), `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync, including the home-relative `~/.local/bin/session-relay` artifact installed outside `~/.claude`; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.

package/README.md

@@ -52,9 +52,15 @@ docks-kit docs [topic]                     self-documentation (9 topics)
 --help --version --wizard --completions    built-in
 ```
 
-The CLI is a typed front-end ([Effect-TS](https://effect.website) on Bun);
-all mutation runs through EngineNative in `cli/src/engine-native/`, with
-golden-regression coverage for dry-run output, mutation snapshots, and argv logs.
+The CLI is a typed Effect 4 beta front-end on Bun; all mutation runs through
+EngineNative in `cli/src/engine-native/`, with golden-regression coverage for
+dry-run output, mutation snapshots, and argv logs. Its dependency graph is
+`effect@4.0.0-beta.107` (including `effect/unstable/cli`),
+`@effect/platform-bun@4.0.0-beta.107` (`BunServices.layer` and
+`BunRuntime.runMain`), `@effect/vitest@4.0.0-beta.107`, and `vitest@4.1.10`
+(required by the `@effect/vitest` peer range). `@effect/cli` and
+`@effect/platform` are removed: neither has a 4.x release, the CLI API moved
+into core, and the standalone platform package was unused here.
 
 ### Key flags (`docks-kit sync`)
 
@@ -106,7 +112,7 @@ and a later flag-less sync reverts them. Full reference: `docks-kit docs flags`
 | `SoT/toolchain.json` | Verified-version floors |
 | `cli/src/engine-native/` | EngineNative sync/model/toolchain implementation |
 | `cli/src/generated/sotPayload.ts` | Generated in-memory payload used by standalone and npm installs |
-| `cli/` | docks-kit CLI (Effect-TS on Bun) + bundled docs topics |
+| `cli/` | docks-kit CLI (Effect 4 beta on Bun) + bundled docs topics |
 | `docks-kit` | Launcher (binary → bun-from-source) |
 | `install.sh` | Global installer (Bun bootstrap + `bun add -g`) |
 | `docs/plans/` | Multi-commit work-item plans |
@@ -128,7 +134,7 @@ Details: `docks-kit docs platforms`.
 Tagging `cli-v*` builds four standalone binaries (Linux x64/arm64 and macOS
 x64/arm64) plus `SHA256SUMS` and attaches them to the GitHub release; npm
 publishes the exact package tarball through trusted publishing with OIDC provenance.
-Package `docks-kit` 0.14.3 bundles the CLI + generated payload, so npm releases
+Package `docks-kit` 0.15.0 bundles the CLI + generated payload, so npm releases
 are versioned config snapshots without shipping the authoring `SoT/` tree.
 
 ## Deeper docs

package/cli/docs/flags.md

@@ -23,6 +23,12 @@ docks-kit sync claude agents        # two
 | `--yes` | Auto-accept toolchain above-verified prompts (containers/CI) |
 | `--verbose` / `-v` | Also print no-op confirmations (already in sync, up to date, left as-is); accepted on `sync`, `model`, and `toolchain` |
 
+## Environment overrides
+
+| Variable | Effect |
+|----------|--------|
+| `DOCKS_KIT_SYNC_CONCURRENCY=1\|2\|3` | Maximum selected sync pipelines running at once. Default `3`; use `1` for serial golden/debug execution. Invalid values fail `sync` with exit 2 but do not affect `model` or `toolchain`. |
+
 ## Per-tool flags
 
 | Flag | Effect |

package/cli/docs/overview.md

@@ -16,7 +16,7 @@ AI-assisted dev environment on every machine.
 | `SoT/toolchain.json` | Verified-version floors for external tools (see `docks-kit docs toolchain`) |
 | `cli/src/generated/sotPayload.ts` | Deterministic generated payload embedded in standalone/npm execution |
 | `cli/src/engine-native/` | EngineNative mutation logic for sync/model/toolchain |
-| `cli/` | This CLI (Effect-TS on Bun) plus bundled docs |
+| `cli/` | This CLI (Effect 4 beta on Bun) plus bundled docs |
 | `docks-kit` | Launcher: version-matching compiled binary → bun-from-source, with Bun auto-install |
 
 ## Design rules

package/cli/src/argv.ts

@@ -0,0 +1,433 @@
+import { GlobalFlag } from "effect/unstable/cli"
+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"
+import { updateCommand } from "./commands/update"
+import {
+  advisorCatalog,
+  advisorFlagGrammar,
+  effortCatalog,
+  effortFlagGrammar
+} from "./efforts"
+import { KNOWN_CLAUDE_OPTIN_PLUGINS } from "./engine-native/parseArgs"
+import { modelCatalog, type Tool } from "./manifests"
+
+export type ArgvOutcome =
+  | { readonly kind: "reject"; readonly message: string; readonly exitCode: number }
+  | { readonly kind: "accept"; readonly args: ReadonlyArray<string> }
+
+interface FlagSurface {
+  readonly longFlags: ReadonlyArray<string>
+  readonly aliases: ReadonlyMap<string, string>
+  readonly valueFlags: ReadonlyArray<string>
+  readonly repeatableFlags: ReadonlyArray<string>
+}
+interface GlobalFlagSurface extends FlagSurface {
+  readonly actionFlags: ReadonlySet<string>
+}
+
+interface CommandValue {
+  readonly name: string
+}
+
+
+const flagMetadata = (
+  param: unknown
+): {
+  readonly name: string
+  readonly aliases: ReadonlyArray<string>
+  readonly takesValue: boolean
+  readonly repeatable: boolean
+} => {
+  let current = param
+  let repeatable = false
+
+  while (typeof current === "object" && current !== null) {
+    if (!("_tag" in current)) break
+    if (current._tag === "Variadic") repeatable = true
+    if (current._tag !== "Single") {
+      if (!("param" in current)) break
+      current = current.param
+      continue
+    }
+
+    if (!("name" in current) || typeof current.name !== "string") {
+      throw new Error("Effect CLI exposed a flag without a string name")
+    }
+    if (
+      !("aliases" in current) ||
+      !Array.isArray(current.aliases) ||
+      !current.aliases.every((alias) => typeof alias === "string")
+    ) {
+      throw new Error(`Effect CLI exposed invalid aliases for --${current.name}`)
+    }
+    if (
+      !("primitiveType" in current) ||
+      typeof current.primitiveType !== "object" ||
+      current.primitiveType === null ||
+      !("_tag" in current.primitiveType) ||
+      typeof current.primitiveType._tag !== "string"
+    ) {
+      throw new Error(`Effect CLI exposed no primitive type for --${current.name}`)
+    }
+    const aliases: ReadonlyArray<string> = current.aliases
+    return {
+      name: current.name,
+      aliases,
+      takesValue: current.primitiveType._tag !== "Boolean",
+      repeatable
+    }
+  }
+
+  throw new Error("Effect CLI exposed an unsupported flag parameter")
+}
+
+const flagSurface = (params: ReadonlyArray<unknown>): FlagSurface => {
+  const longFlags: Array<string> = []
+  const aliases = new Map<string, string>()
+  const valueFlags: Array<string> = []
+  const repeatableFlags: Array<string> = []
+
+  for (const param of params) {
+    const metadata = flagMetadata(param)
+    const longName = `--${metadata.name}`
+    longFlags.push(longName)
+    if (metadata.takesValue) valueFlags.push(longName)
+    if (metadata.repeatable) repeatableFlags.push(longName)
+    for (const alias of metadata.aliases) aliases.set(`-${alias}`, longName)
+  }
+
+  return { longFlags, aliases, valueFlags, repeatableFlags }
+}
+
+const commandSurface = (command: CommandValue): FlagSurface => {
+  if (!("config" in command)) {
+    throw new Error(`Effect CLI did not expose flags for '${command.name}'`)
+  }
+  const config = command.config
+  if (
+    typeof config !== "object" ||
+    config === null ||
+    !("flags" in config) ||
+    !Array.isArray(config.flags)
+  ) {
+    throw new Error(`Effect CLI did not expose flags for '${command.name}'`)
+  }
+
+  return flagSurface(config.flags)
+}
+
+const globalSurface = (): GlobalFlagSurface => {
+  const builtIns: unknown = GlobalFlag.BuiltIns
+  if (!Array.isArray(builtIns)) {
+    throw new Error("Effect CLI did not expose its built-in global flags")
+  }
+
+  const actionFlags = new Set<string>()
+  const flags = builtIns.map((builtIn) => {
+    if (
+      (typeof builtIn !== "object" && typeof builtIn !== "function") ||
+      builtIn === null ||
+      !("flag" in builtIn) ||
+      !("_tag" in builtIn) ||
+      typeof builtIn._tag !== "string"
+    ) {
+      throw new Error("Effect CLI exposed an unsupported built-in global flag")
+    }
+    if (builtIn._tag === "Action") {
+      // Only a presence-based action is idempotent. `--completions` is an action
+      // that takes a value, and Effect 4 would silently keep the first one, which
+      // is exactly what the duplicate rule exists to refuse.
+      const metadata = flagMetadata(builtIn.flag)
+      if (!metadata.takesValue) actionFlags.add(`--${metadata.name}`)
+    }
+    return builtIn.flag
+  })
+  return { ...flagSurface(flags), actionFlags }
+}
+
+const COMMANDS: ReadonlyArray<CommandValue> = [
+  syncCommand,
+  updateCommand,
+  modelCommand,
+  toolchainCommand,
+  modelsCommand,
+  statusCommand,
+  pluginsCommand,
+  skillsCommand,
+  docsCommand
+]
+
+// A Map, not a plain object: an object literal answers `toString` and friends from
+// `Object.prototype`, so an unknown subcommand with such a name would slip past the
+// unknown-command guard and dereference a surface that was never built.
+const COMMAND_SURFACES: ReadonlyMap<string, FlagSurface> = new Map(
+  COMMANDS.map((command) => [command.name, commandSurface(command)])
+)
+
+const GLOBAL_SURFACE: GlobalFlagSurface = globalSurface()
+
+const LEGACY_HINTS: Readonly<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",
+  "--skip-rtk": "--skip-rtk was renamed to --skip-bubblewrap",
+  "--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 flagNameOf = (token: string): string => {
+  const equals = token.indexOf("=")
+  return equals === -1 ? token : token.slice(0, equals)
+}
+
+const canonicalFlagName = (
+  name: string,
+  surface: FlagSurface | undefined
+): string | undefined => {
+  if (surface === undefined) return undefined
+  const aliased = surface.aliases.get(name)
+  if (aliased !== undefined) return aliased
+  return surface.longFlags.includes(name) ? name : undefined
+}
+
+const declaredFlagName = (
+  name: string,
+  commandSurface: FlagSurface | undefined
+): string | undefined =>
+  canonicalFlagName(name, commandSurface) ?? canonicalFlagName(name, GLOBAL_SURFACE)
+
+const declaredInAnySurface = (name: string): boolean => {
+  if (canonicalFlagName(name, GLOBAL_SURFACE) !== undefined) return true
+  return COMMANDS.some(
+    (command) => canonicalFlagName(name, COMMAND_SURFACES.get(command.name)) !== undefined
+  )
+}
+
+const takesValueInAnySurface = (name: string): boolean => {
+  const globalName = canonicalFlagName(name, GLOBAL_SURFACE)
+  if (globalName !== undefined && GLOBAL_SURFACE.valueFlags.includes(globalName)) return true
+  return COMMANDS.some((command) => {
+    const surface = COMMAND_SURFACES.get(command.name)
+    if (surface === undefined) return false
+    const canonicalName = canonicalFlagName(name, surface)
+    return canonicalName !== undefined && surface.valueFlags.includes(canonicalName)
+  })
+}
+
+/** The resolved subcommand word, or undefined at the root. */
+export const subcommandName = (args: ReadonlyArray<string>): string | undefined => {
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]
+    if (token === "--") return undefined
+    const name = flagNameOf(token)
+    if (token === name && takesValueInAnySurface(name)) {
+      const next = args[index + 1]
+      if (next === "--") return undefined
+      if (
+        next !== undefined &&
+        !(next.startsWith("-") && declaredInAnySurface(flagNameOf(next)))
+      ) {
+        index++
+        continue
+      }
+    }
+    if (!token.startsWith("-")) return token
+  }
+  return undefined
+}
+
+interface ScannedFlag {
+  readonly token: string
+  readonly name: string
+  readonly canonicalName: string | undefined
+  readonly hasValue: boolean
+  readonly takesValue: boolean
+}
+
+interface ArgvNormalization {
+  readonly flagIndex: number
+  readonly valueIndex: number
+  readonly token: string
+}
+
+interface ScannedArgv {
+  readonly flags: ReadonlyArray<ScannedFlag>
+  readonly normalizations: ReadonlyArray<ArgvNormalization>
+}
+
+const scanArgv = (
+  args: ReadonlyArray<string>,
+  commandSurface: FlagSurface | undefined
+): ScannedArgv => {
+  const flags: Array<ScannedFlag> = []
+  const normalizations: Array<ArgvNormalization> = []
+
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]
+    if (token === "--") break
+    if (!token.startsWith("-")) continue
+
+    const name = flagNameOf(token)
+    const canonicalName = declaredFlagName(name, commandSurface)
+    let hasValue = token.includes("=")
+    const takesValue =
+      canonicalName !== undefined &&
+      (commandSurface?.valueFlags.includes(canonicalName) === true ||
+        GLOBAL_SURFACE.valueFlags.includes(canonicalName))
+
+    if (!hasValue && takesValue) {
+      const next = args[index + 1]
+      const nextIsRecognizedFlag =
+        next !== undefined &&
+        next.startsWith("-") &&
+        declaredFlagName(flagNameOf(next), commandSurface) !== undefined
+      // A legitimate value may begin with `-`; only a recognized flag proves it is missing.
+      if (next !== undefined && next !== "--" && !nextIsRecognizedFlag) {
+        hasValue = true
+        if (next.startsWith("-")) {
+          // Effect 4's lexer treats any `-`-leading token as an option, so a legitimate
+          // dash-leading value only survives in the inline form.
+          normalizations.push({
+            flagIndex: index,
+            valueIndex: index + 1,
+            token: `${token}=${next}`
+          })
+        }
+        index++
+      }
+    }
+
+    flags.push({ token, name, canonicalName, hasValue, takesValue })
+  }
+
+  return { flags, normalizations }
+}
+
+const normalizeArgv = (
+  args: ReadonlyArray<string>,
+  normalizations: ReadonlyArray<ArgvNormalization>
+): ReadonlyArray<string> => {
+  if (normalizations.length === 0) return args
+
+  const normalized: Array<string> = []
+  let normalizationIndex = 0
+  for (let index = 0; index < args.length; index++) {
+    const normalization = normalizations[normalizationIndex]
+    if (normalization !== undefined && normalization.flagIndex === index) {
+      normalized.push(normalization.token)
+      index = normalization.valueIndex
+      normalizationIndex++
+      continue
+    }
+    normalized.push(args[index])
+  }
+  return normalized
+}
+
+const reject = (message: string): ArgvOutcome => ({
+  kind: "reject",
+  message,
+  exitCode: 2
+})
+
+const modelCatalogHint = (tool: Tool): string => {
+  const catalog = modelCatalog(tool)
+  const list = catalog.models
+    .map((model) => `  ${model.id}${model.note !== undefined ? `  — ${model.note}` : ""}`)
+    .join("\n")
+  return `Available ${tool} models (kit-verified ${catalog.verified} — SoT/models.json):\n${list}`
+}
+
+const missingModifierValue = (flag: string): string | undefined => {
+  switch (flag) {
+    case "--claude-model":
+    case "--codex-model": {
+      const tool: Tool = flag === "--claude-model" ? "claude" : "codex"
+      return `${modelCatalogHint(tool)}\n${flag} requires a value: ${flag}=<model>`
+    }
+    case "--claude-effort":
+    case "--codex-effort": {
+      const tool: Tool = flag === "--claude-effort" ? "claude" : "codex"
+      return `${effortCatalog(tool)}\n${flag} requires a value: ${effortFlagGrammar(tool)}`
+    }
+    case "--claude-advisor":
+      return `${advisorCatalog()}\n${flag} requires a value: ${advisorFlagGrammar()}`
+    case "--claude-compact-window":
+      return `${flag} requires a value: ${flag}=<tokens> (e.g. 680k)`
+    case "--claude-plugin":
+      return `${flag} requires a value: ${flag}=<${KNOWN_CLAUDE_OPTIN_PLUGINS.join("|")}>`
+    default:
+      return undefined
+  }
+}
+
+/** Validate the argument list, then hand back the arguments Effect 4 should parse. */
+export const prepareArgv = (args: ReadonlyArray<string>): ArgvOutcome => {
+  const subcommand = subcommandName(args)
+  const commandSurface = subcommand === undefined ? undefined : COMMAND_SURFACES.get(subcommand)
+  const { flags, normalizations } = scanArgv(args, commandSurface)
+  const unknownCommandWouldMisdiagnoseFlag =
+    subcommand !== undefined &&
+    commandSurface === undefined &&
+    flags.some((flag) => flag.canonicalName === undefined)
+  if (unknownCommandWouldMisdiagnoseFlag) {
+    return reject(`unknown command '${subcommand}'`)
+  }
+
+  if (subcommand === "sync") {
+    for (const flag of flags) {
+      const hint = LEGACY_HINTS[flag.name]
+      if (hint !== undefined) return reject(hint)
+    }
+  }
+
+  // Effect 4 expands clustered shorts, but the kit declares no clusterable alias
+  // pair, so refusing a cluster as one unknown flag is the conservative direction.
+  for (const flag of flags) {
+    if (flag.canonicalName !== undefined) continue
+    const scope = subcommand === undefined ? "" : ` for '${subcommand}'`
+    return reject(`unknown flag ${flag.token}${scope}`)
+  }
+
+  for (const flag of flags) {
+    if (!flag.token.includes("=") || flag.takesValue) continue
+    // These booleans are presence-based; Effect 4 would otherwise let
+    // `--dry-run=false` read as a dry run while performing a real mutating sync.
+    return reject(`flag ${flag.name} does not take a value`)
+  }
+
+  const seen = new Set<string>()
+  for (const flag of flags) {
+    const name = flag.canonicalName
+    if (name === undefined) continue
+    const duplicateAllowed =
+      commandSurface?.repeatableFlags.includes(name) === true ||
+      GLOBAL_SURFACE.repeatableFlags.includes(name) ||
+      GLOBAL_SURFACE.actionFlags.has(name)
+    if (!duplicateAllowed && seen.has(name)) {
+      return reject(`flag ${name} was given more than once`)
+    }
+    seen.add(name)
+  }
+
+  if (subcommand === "sync") {
+    for (const flag of flags) {
+      if (flag.hasValue) continue
+      const message = missingModifierValue(flag.name)
+      if (message !== undefined) return reject(message)
+    }
+  }
+
+  return { kind: "accept", args: normalizeArgv(args, normalizations) }
+}

package/cli/src/commands/docs.ts

@@ -1,4 +1,4 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/cli"
 import { Console, Effect, Option } from "effect"
 import { bail } from "../engine"
 import overview from "../../docs/overview.md" with { type: "text" }
@@ -23,12 +23,12 @@ const TOPICS: Record<string, { summary: string; body: string }> = {
   "platforms": { summary: "Platform support: Linux/macOS x64 and arm64", body: platforms }
 }
 
-const topic = Args.text({ name: "topic" }).pipe(
-  Args.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
-  Args.optional
+const topic = Argument.string("topic").pipe(
+  Argument.withDescription(`One of: ${Object.keys(TOPICS).join(", ")}`),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("List topics as JSON")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("List topics as JSON")
 )
 
 export const docsCommand = Command.make("docs", { topic, json }, (config) =>

package/cli/src/commands/model.ts

@@ -1,21 +1,21 @@
-import { Args, Command, Options, Prompt } from "@effect/cli"
+import { Argument, Command, Flag, Prompt } from "effect/unstable/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 tool = Argument.string("tool").pipe(
+  Argument.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 value = Argument.string("value").pipe(
+  Argument.withDescription("Model to set (omit to view current + pick interactively on a TTY)"),
+  Argument.optional
 )
-const dryRun = Options.boolean("dry-run").pipe(
-  Options.withDescription("Preview without applying")
+const dryRun = Flag.boolean("dry-run").pipe(
+  Flag.withDescription("Preview without applying")
 )
-const verbose = Options.boolean("verbose").pipe(
-  Options.withAlias("v"),
-  Options.withDescription("Also print no-op confirmations (already in sync, up to date)")
+const verbose = Flag.boolean("verbose").pipe(
+  Flag.withAlias("v"),
+  Flag.withDescription("Also print no-op confirmations (already in sync, up to date)")
 )
 
 const KEEP = "__keep__"

package/cli/src/commands/models.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/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 tool catalogs)"),
-  Args.optional
+const tool = Argument.string("tool").pipe(
+  Argument.withDescription("claude | codex (omit for both tool catalogs)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 const renderTool = (t: Tool) =>

package/cli/src/commands/plugins.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/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 action = Argument.string("action").pipe(
+  Argument.withDescription("list (default)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 export const pluginsCommand = Command.make("plugins", { action, json }, (config) =>

package/cli/src/commands/skills.ts

@@ -1,14 +1,14 @@
-import { Args, Command, Options } from "@effect/cli"
+import { Argument, Command, Flag } from "effect/unstable/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 action = Argument.string("action").pipe(
+  Argument.withDescription("list (default)"),
+  Argument.optional
 )
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 export const skillsCommand = Command.make("skills", { action, json }, (config) =>

package/cli/src/commands/status.ts

@@ -1,4 +1,4 @@
-import { Command, Options } from "@effect/cli"
+import { Command, Flag } from "effect/unstable/cli"
 import { Console, Effect } from "effect"
 import { engineCapture } from "../engine"
 import {
@@ -11,8 +11,8 @@ import {
 } from "../manifests"
 import { kitHome } from "../kitHome"
 
-const json = Options.boolean("json").pipe(
-  Options.withDescription("Machine-readable output")
+const json = Flag.boolean("json").pipe(
+  Flag.withDescription("Machine-readable output")
 )
 
 interface Drift {