argsbarg 4.1.0 → 5.0.1

package/index.d.ts

@@ -1,5 +1,9 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
+export declare function resolveAppConfigPath(program: CliProgram): string;
+/** Human-readable config path for error messages (`~/…` when under home). */
+export declare function displayAppConfigPath(program: CliProgram): string;
 export type ResolvedConfig = Record<string, unknown>;
 declare class EmptyAppConfigSnapshot {
 	private readonly program;
@@ -245,21 +249,24 @@ export interface CliMcpToolConfig {
 	 */
 	outputSchema?: Record<string, unknown>;
 }
+/** Context passed to {@link CliAppConfigEntry.resolve} for one config key. */
+export interface CliAppConfigResolveContext {
+	/** Schema key being resolved. */
+	key: string;
+	/** Entry metadata for this key. */
+	entry: CliAppConfigEntry;
+	/** Program root (read-only). */
+	program: CliProgram;
+	/** Raw value from the config file, if any. */
+	fileValue: unknown;
+	/** Non-empty host env string when `entry.env` is set; otherwise `undefined`. */
+	envValue: string | undefined;
+}
 /**
- * Opt-out and defaults for the `install` built-in (program root only).
+ * Optional fallback resolver for one config key (e.g. `gh auth token` when `GH_TOKEN` is unset).
+ * Return `undefined` to continue resolution (env, then default).
  */
-export interface CliUpdateArtifact {
-	/** Path to an executable binary to copy into the install location. */
-	path: string;
-	/** Release version of `path` (used for already-current checks and success messages). */
-	version?: string;
-	/** Called after reinstall completes (e.g. remove a temp download directory). */
-	cleanup?: () => void | Promise<void>;
-}
-/** Fetches the latest release binary for `install --update`. */
-export type CliUpdateGetLatest = (ctx: {
-	version: string;
-}) => Promise<CliUpdateArtifact>;
+export type CliAppConfigResolveFn = (ctx: CliAppConfigResolveContext) => unknown;
 /**
  * Metadata overlay for one key in {@link CliAppConfig.entries}.
  * Types and validation come from {@link CliAppConfig.jsonSchema} when set; otherwise all values are strings.
@@ -280,6 +287,11 @@ export interface CliAppConfigEntry {
 	sensitive?: boolean;
 	/** When set: non-empty `process.env[env]` overrides file; value exported after resolve. */
 	env?: string;
+	/**
+	 * Optional fallback after file when env is empty.
+	 * Return `undefined` to fall back to `env` (if set) and schema defaults.
+	 */
+	resolve?: CliAppConfigResolveFn;
 }
 /**
  * App configuration block on the program root ({@link CliProgram.appConfig}).
@@ -295,23 +307,23 @@ export interface CliAppConfig {
 	/** Per-key metadata; keys must match `jsonSchema.properties` when `jsonSchema` is set. */
 	entries: Record<string, CliAppConfigEntry>;
 }
-export interface CliInstallConfig {
-	/** When `false`, hide/disable `install` (default: enabled). */
+/** Opt-out for the `completion` built-in (default: enabled). */
+export interface CliCompletionConfig {
+	/** When `false`, hide/disable `completion` (default: enabled). */
+	enabled?: boolean;
+}
+export interface CliConfigureConfig {
+	/** When `false`, hide/disable `configure` (default: enabled). */
 	enabled?: boolean;
 	/**
-	 * Default agent integration for full install (`install --all`).
-	 * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in `--all`; paired skills excluded.
-	 * - `'skill'` when MCP is off (default): skill targets in `--all`; paired MCP excluded.
-	 * - `'both'`: install MCP and skill for the same host when both are available.
+	 * Default agent integration for sync (`configure --sync`).
+	 * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in sync; paired skills excluded.
+	 * - `'skill'` when MCP is off (default): skill targets in sync; paired MCP excluded.
+	 * - `'both'`: sync MCP and skill for the same host when both are available.
 	 */
 	agentIntegration?: InstallAgentIntegration;
-	/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-	targets?: CliInstallTargets;
-	/**
-	 * When set, enables `install --update` on the program root.
-	 * Should download or locate the latest release binary and return its path.
-	 */
-	updateGetLatest?: CliUpdateGetLatest;
+	/** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
+	targets?: CliConfigureTargets;
 }
 /** Agent integration mode for install — MCP vs shell skill per host. */
 export type InstallAgentIntegration = "mcp" | "skill" | "both";
@@ -319,16 +331,16 @@ export type InstallAgentIntegration = "mcp" | "skill" | "both";
 export type InstallTargetSpec = boolean | {
 	/** When false, artifact is never installed (even with scoped CLI flags). Default true. */
 	enabled?: boolean;
-	/** When true, included in bare `install` / `install --all`. Default varies by key. */
+	/** When true, included in `configure --sync`. Default varies by key. */
 	includedInAll?: boolean;
 };
 export interface ResolvedInstallTarget {
 	enabled: boolean;
 	includedInAll: boolean;
 }
-/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
-export interface CliInstallTargets {
-	/** Copy app to `~/.local/bin/<key>`. Default includedInAll true (opt-out). */
+/** Per-artifact gates for configure. See {@link resolveEffectiveInstallTargets}. */
+export interface CliConfigureTargets {
+	/** App binary status only (Homebrew PATH); no self-install. */
 	app?: InstallTargetSpec;
 	/** ChatGPT desktop MCP. Default false. */
 	chatgptMcp?: InstallTargetSpec;
@@ -342,9 +354,7 @@ export interface CliInstallTargets {
 	codexMcp?: InstallTargetSpec;
 	/** Codex skill. Default false. */
 	codexSkill?: InstallTargetSpec;
-	/** Shell completions for detected shells. Default includedInAll true (opt-out). */
-	completions?: InstallTargetSpec;
-	/** App config: wizard on install, file removal on uninstall. Default includedInAll true. */
+	/** App config: interactive wizard step in `configure`. Default not in sync. */
 	configure?: InstallTargetSpec;
 	/** Cursor MCP. Default false. */
 	cursorMcp?: InstallTargetSpec;
@@ -442,8 +452,10 @@ export type CliProgram = CliNode & {
 	appConfig?: CliAppConfig;
 	/** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
 	mcpServer?: CliMcpServerConfig;
-	/** Opt-out and defaults for `install`. */
-	install?: CliInstallConfig;
+	/** Opt-out and defaults for `configure`. */
+	configure?: CliConfigureConfig;
+	/** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
+	completion?: CliCompletionConfig;
 	/** When set with `enabled: true`, enables the `docs` built-in command group. */
 	docs?: CliDocsConfig;
 };
@@ -461,11 +473,10 @@ export declare class CliSchemaValidationError extends Error {
 }
 /** Platform builtins derived from program config and runtime. */
 export interface CliCapabilities {
-	completion: true;
+	completion: boolean;
 	mcp: boolean;
-	install: boolean;
+	configure: boolean;
 	docs: boolean;
-	update: boolean;
 	configCommands: boolean;
 }
 /** JSON-safe command node (no handlers). */
@@ -547,49 +558,6 @@ export declare function shouldRunHeadlessWithYes(ctx: HeadlessContext, opts: {
 export declare function requireYesInNonTty(yes: boolean, hint: string, dryRun?: boolean, interactive?: boolean): void;
 /** Prefixes a success message when running in dry-run mode. */
 export declare function formatDryRunMessage(message: string, dryRun: boolean): string;
-/** Config for {@link ghReleaseUpdateGetLatest}. */
-export interface GhReleaseUpdateConfig {
-	/** GitHub `owner/repo` slug. */
-	repo: string;
-	/** Release asset filename (e.g. `myapp`). */
-	asset: string;
-	/** Temp directory name prefix for downloads. */
-	tempPrefix: string;
-	/** Path to the on-disk version-check cache JSON file. */
-	cachePath: string;
-	/** Optional hint when `gh auth` fails or no releases exist. */
-	repoEnvHint?: string;
-}
-/** Config for {@link createGhVersionCheck}. */
-export interface GhVersionCheckConfig {
-	/** Installed semver string. */
-	currentVersion: string;
-	/** CLI command name for update notices (e.g. `qa`). */
-	commandName: string;
-	/** Path to the on-disk version-check cache JSON file. */
-	cachePath: string;
-	/** Cache TTL in milliseconds (default 24h). */
-	ttlMs?: number;
-	/** When true, skip background refresh (e.g. test subprocess). */
-	skipRefresh?: () => boolean;
-	/** When true, skip refresh because `gh` is unavailable. */
-	ghAvailable?: () => boolean;
-	/** Fetches latest release version via `gh`. */
-	fetchLatest: () => Promise<string>;
-}
-/** Returns whether the installed version matches the latest release. */
-export declare function isAlreadyCurrent(current: string, latest: string): boolean;
-/** Strips a leading `v` from a release tag. */
-export declare function parseReleaseTag(tag: string): string;
-/** Builds a `CliUpdateGetLatest` hook that downloads a release via `gh`. */
-export declare function ghReleaseUpdateGetLatest(config: GhReleaseUpdateConfig): CliUpdateGetLatest;
-/** Version-check cache helpers for summary notices and background refresh. */
-export declare function createGhVersionCheck(config: GhVersionCheckConfig): {
-	getUpdateNotice: () => string | null;
-	refreshIfStale: () => void;
-};
-/** Shared `gh release view` fetcher for hooks and version-check refresh. */
-export declare function createGhFetchLatest(config: Pick<GhReleaseUpdateConfig, "repo" | "repoEnvHint">): () => Promise<string>;
 /** Resolved paths for `mcp bundle`. */
 export interface McpBundlePaths {
 	binaryPath: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "4.1.0",
+  "version": "5.0.1",
   "type": "module",
   "engines": {
     "bun": ">=1.3"
@@ -12,7 +12,7 @@
   "module": "./src/index.ts",
   "types": "./index.d.ts",
   "bin": {
-    "argsbarg": "src/index.ts"
+    "argsbarg": "src/cli-tool/main.ts"
   },
   "exports": {
     ".": {

package/src/builtins/builtins.test.ts

@@ -1,9 +1,12 @@
 import { describe, expect, test } from "bun:test";
+import { resolveCapabilities } from "../capabilities.ts";
+import { cliBuiltinDocsGroup } from "../docs/builtin.ts";
 import { ParseKind, parse, postParseValidate } from "../parse.ts";
 import type { CliProgram } from "../types.ts";
+import { cliBuiltinConfigureCommand, configureBuiltinOptions } from "./configure.ts";
+import { configureCommandDescription, configureSyncOptionDescription } from "./configure-copy.ts";
 import { exportPresentationBuiltins } from "./export.ts";
 import { completionBashScript, completionFishScript, completionZshScript } from "./index.ts";
-import { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliParseRoot, cliPresentationRoot } from "./presentation.ts";
 
@@ -21,55 +24,61 @@ const fixture: CliProgram = {
   ],
 };
 
+const noMcp: CliProgram = {
+  key: "skillonly",
+  version: "0.0.0",
+  description: "Skills only.",
+  commands: [{ key: "ping", description: "Ping.", handler: () => {} }],
+};
+
 describe("builtins help copy", () => {
-  test("install command includes description and option text", () => {
-    const install = cliBuiltinInstallCommand(fixture);
-    expect(install.description).toContain("shell completions");
-    expect(install.notes).toContain("install --all");
-    const names = installBuiltinOptions(fixture).map((o) => o.name);
-    expect(names).toContain("all");
-    expect(names).toContain("mcp");
-    expect(names.indexOf("all")).toBeLessThan(names.indexOf("mcp"));
-    expect(names.indexOf("mcp")).toBeLessThan(names.indexOf("status"));
-    expect(names.indexOf("status")).toBeLessThan(names.indexOf("uninstall"));
-    expect(names.indexOf("uninstall")).toBeLessThan(names.indexOf("from"));
-    expect(names.indexOf("from")).toBeLessThan(names.indexOf("yes"));
-    const yesOpt = installBuiltinOptions(fixture).find((o) => o.name === "yes");
+  test("configure command includes Homebrew-oriented description", () => {
+    const configure = cliBuiltinConfigureCommand(fixture);
+    expect(configure.description).toContain("agent skills");
+    expect(configure.description).toContain("MCP config");
+    expect(configure.notes).toContain("brew install");
+    const names = configureBuiltinOptions(fixture).map((o) => o.name);
+    expect(names).toContain("sync");
+    expect(names).toContain("remove-all");
+    expect(names).toContain("status");
+    const yesOpt = configureBuiltinOptions(fixture).find((o) => o.name === "yes");
     expect(yesOpt?.shortName).toBe("y");
   });
 
-  test("install -y parses as --yes", () => {
-    const root = cliParseRoot(fixture);
-    const pr = postParseValidate(root, parse(root, ["install", "-y"]));
-    expect(pr.kind).toBe(ParseKind.Ok);
-    if (pr.kind === ParseKind.Ok) {
-      expect(pr.opts.yes).toBe("1");
-    }
-  });
-
-  test("install omits --mcp option when mcpServer unset", () => {
-    const noMcp: CliProgram = { key: "x", version: "0.0.0", description: "x", handler: () => {} };
-    const names = installBuiltinOptions(noMcp).map((o) => o.name);
-    expect(names).not.toContain("mcp");
+  test("configure copy omits MCP when mcpServer unset", () => {
+    const caps = resolveCapabilities(noMcp);
+    expect(configureCommandDescription(noMcp, caps)).toBe(
+      "Set up agent skills for this app (binary via Homebrew).",
+    );
+    expect(configureCommandDescription(noMcp, caps)).not.toContain("MCP");
+    expect(configureSyncOptionDescription(noMcp, caps)).not.toContain("MCP");
+    const configure = cliBuiltinConfigureCommand(noMcp);
+    expect(configure.description).not.toContain("MCP");
   });
 
-  test("install omits --update when updateGetLatest unset", () => {
-    const install = cliBuiltinInstallCommand(fixture);
-    expect(installBuiltinOptions(fixture).map((o) => o.name)).not.toContain("update");
-    expect(install.notes).not.toContain("Upgrade to latest release");
-    expect(install.notes).toContain("Refresh after upgrading");
-  });
+  test("configure notes mention brew upgrade and interactive configure", () => {
+    const configure = cliBuiltinConfigureCommand(fixture);
+    expect(configure.notes).toContain("brew upgrade");
+    expect(configure.notes).toContain("configure --sync --yes");
+    expect(configure.notes).toContain(`${fixture.key} configure`);
 
-  test("install notes include upgrade section when updateGetLatest is set", () => {
-    const withUpdate: CliProgram = {
+    const withConfig: CliProgram = {
       ...fixture,
-      install: { updateGetLatest: async () => ({ path: process.execPath }) },
+      appConfig: {
+        entries: { token: { description: "Token.", env: "TOKEN" } },
+      },
     };
-    const install = cliBuiltinInstallCommand(withUpdate);
-    const notes = install.notes ?? "";
-    expect(installBuiltinOptions(withUpdate).map((o) => o.name)).toContain("update");
-    expect(notes).toContain("Upgrade to latest release");
-    expect(notes.indexOf("install --reinstall")).toBeLessThan(notes.indexOf("install --update"));
+    expect(configureBuiltinOptions(withConfig).map((o) => o.name)).toContain("remove-config");
+  });
+
+  test("configure -y parses as --yes", () => {
+    const root = cliParseRoot(fixture);
+    const pr = postParseValidate(root, parse(root, ["configure", "-y", "--sync"]));
+    expect(pr.kind).toBe(ParseKind.Ok);
+    if (pr.kind === ParseKind.Ok) {
+      expect(pr.opts.yes).toBe("1");
+      expect(pr.opts.sync).toBe("1");
+    }
   });
 
   test("mcp builtin description is user-facing", () => {
@@ -79,38 +88,31 @@ describe("builtins help copy", () => {
     };
     const mcp = cliBuiltinMcpCommand(withDocs);
     expect(mcp.description).toContain("MCP server");
-    expect(mcp.notes).toContain("install --mcp --yes");
+    expect(mcp.notes).toContain("configure");
     expect(mcp.notes).toContain("docs mcp");
   });
 });
 
 describe("presentation root", () => {
-  test("includes mcp and install when enabled", () => {
+  test("includes mcp and configure when enabled", () => {
     const root = cliPresentationRoot(fixture);
     const keys = root.commands?.map((c) => c.key) ?? [];
     expect(keys).toContain("mcp");
-    expect(keys).toContain("install");
+    expect(keys).toContain("configure");
+    expect(keys).not.toContain("completion");
+    expect(keys).not.toContain("install");
   });
 
-  test("omits install when install.enabled is false", () => {
-    const disabled: CliProgram = { ...fixture, install: { enabled: false } };
+  test("omits configure when configure.enabled is false", () => {
+    const disabled: CliProgram = { ...fixture, configure: { enabled: false } };
     const root = cliPresentationRoot(disabled);
-    expect(root.commands?.map((c) => c.key)).not.toContain("install");
+    expect(root.commands?.map((c) => c.key)).not.toContain("configure");
   });
+
   test("includes version builtin", () => {
     const root = cliPresentationRoot(fixture);
     expect(root.commands?.map((c) => c.key)).toContain("version");
   });
-
-  test("root notes include agent hint when docs enabled", () => {
-    const withDocs: CliProgram = {
-      ...fixture,
-      docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
-    };
-    const root = cliPresentationRoot(withDocs);
-    expect(root.notes).toContain("For AI agents: `myapp docs skill`.");
-    expect(root.notes).not.toContain("install --skill");
-  });
 });
 
 describe("completion emitters", () => {
@@ -119,14 +121,14 @@ describe("completion emitters", () => {
     const fish = completionFishScript(schema);
     expect(fish).toContain("complete -c myapp");
     expect(fish).toContain("hello");
-    expect(fish).toContain("install");
+    expect(fish).toContain("configure");
   });
 
-  test("bash script includes install flags", () => {
+  test("bash script includes configure flags", () => {
     const schema = cliPresentationRoot(fixture);
     const bash = completionBashScript(schema);
-    expect(bash).toContain("--all");
-    expect(bash).toContain("install");
+    expect(bash).toContain("hello");
+    expect(bash).toContain("--sync");
   });
 
   test("zsh script registers compdef", () => {
@@ -154,11 +156,29 @@ describe("schema export builtins", () => {
     };
     const builtins = exportPresentationBuiltins(withConfig);
     expect(builtins.map((b) => b.key)).toContain("config");
+    expect(builtins.map((b) => b.key)).toContain("configure");
   });
 
-  test("exportPresentationBuiltins includes install options", () => {
+  test("exportPresentationBuiltins omits hidden completion", () => {
     const builtins = exportPresentationBuiltins(fixture);
-    const install = builtins.find((b) => b.key === "install");
-    expect(install?.options?.find((o) => o.name === "all")?.description).toContain("app");
+    expect(builtins.map((b) => b.key)).not.toContain("completion");
+  });
+});
+
+describe("docs skill topic copy", () => {
+  test("mentions configure when configure is enabled", () => {
+    const withDocs: CliProgram = {
+      ...noMcp,
+      docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    };
+    const skill = cliBuiltinDocsGroup(withDocs).commands.find((c) => c.key === "skill");
+    expect(skill?.description).toContain("configure");
+
+    const configureOff: CliProgram = {
+      ...withDocs,
+      configure: { enabled: false },
+    };
+    const skillOff = cliBuiltinDocsGroup(configureOff).commands.find((c) => c.key === "skill");
+    expect(skillOff?.description).not.toContain("configure");
   });
 });

package/src/builtins/completion-group.ts

@@ -1,23 +1,22 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import type { CliProgram, CliRouter } from "../types.ts";
+import type { CliProgram } from "../types.ts";
 
 /**
  * Builds the static `completion` / `bash` / `zsh` / `fish` command subtree (merged into the program root at runtime).
  */
-export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
+export function cliBuiltinCompletionGroup(program: CliProgram): import("../types.ts").CliRouter {
   const appName = program.key;
-  const caps = resolveCapabilities(program);
-  const router: CliRouter = {
+  const router: import("../types.ts").CliRouter = {
     key: "completion",
+    hidden: true,
     description: "Generate the autocompletion script for shells.",
     commands: [
       {
         key: "bash",
         description: "Print a bash tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion bash > ~/.bash_completion.d/${appName}\n` +
-          `  echo 'source ~/.bash_completion.d/${appName}' >> ~/.bashrc\n\n` +
+          "Homebrew installs completions during `brew install` via generate_completions_from_executable.\n\n" +
+          "Ensure your shell loads Homebrew completions:\n" +
+          "  https://docs.brew.sh/Shell-Completion\n\n" +
           "Try this session only:\n\n" +
           `  source <(${appName} completion bash)`,
         handler: () => {},
@@ -26,9 +25,9 @@ export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
         key: "zsh",
         description: "Print a zsh tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion zsh > ~/.zsh/completions/_${appName}\n\n` +
-          "Ensure ~/.zsh/completions is on your fpath, then restart zsh.\n\n" +
+          "Homebrew installs completions to $(brew --prefix)/share/zsh/site-functions.\n\n" +
+          "Ensure brew shellenv + compinit are configured:\n" +
+          "  https://docs.brew.sh/Shell-Completion\n\n" +
           "Try this session only:\n\n" +
           `  eval "$(${appName} completion zsh)"`,
         handler: () => {},
@@ -37,15 +36,16 @@ export function cliBuiltinCompletionGroup(program: CliProgram): CliRouter {
         key: "fish",
         description: "Print a fish tab-completion script.",
         notes:
-          "Manual install:\n\n" +
-          `  ${appName} completion fish > ~/.config/fish/completions/${appName}.fish\n\n` +
-          "Fish loads completions from that directory automatically.",
+          "Homebrew installs completions to $(brew --prefix)/share/fish/vendor_completions.d.\n\n" +
+          "See: https://docs.brew.sh/Shell-Completion\n\n" +
+          "Try this session only:\n\n" +
+          `  ${appName} completion fish | source`,
         handler: () => {},
       },
     ],
   };
-  if (caps.install) {
-    router.notes = `Install for all shells:\n\n  ${appName} install --completions --yes`;
-  }
+  router.notes =
+    "Completions are installed by Homebrew during formula install.\n\n" +
+    "See: https://docs.brew.sh/Shell-Completion";
   return router;
 }

package/src/builtins/configure-copy.ts

@@ -0,0 +1,86 @@
+/** Capability-aware labels for configure builtin and docs copy. */
+
+import type { CliCapabilities } from "../capabilities.ts";
+import type { CliProgram } from "../types.ts";
+
+type Kind = "skills" | "mcp" | "config";
+
+const LABEL: Record<Kind, { prose: string; short: string }> = {
+  skills: { prose: "agent skills", short: "skills" },
+  mcp: { prose: "MCP config", short: "MCP" },
+  config: { prose: "app config", short: "config" },
+};
+
+function enabledKinds(program: CliProgram, caps: CliCapabilities): Kind[] {
+  const kinds: Kind[] = ["skills"];
+  if (caps.mcp) kinds.push("mcp");
+  if (program.appConfig) kinds.push("config");
+  return kinds;
+}
+
+function joinEnglish(items: string[]): string {
+  if (items.length === 0) return "agent artifacts";
+  if (items.length === 1) return items[0]!;
+  if (items.length === 2) return `${items[0]} and ${items[1]}`;
+  return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+
+function prose(program: CliProgram, caps: CliCapabilities): string {
+  return joinEnglish(enabledKinds(program, caps).map((k) => LABEL[k].prose));
+}
+
+function short(program: CliProgram, caps: CliCapabilities): string {
+  return joinEnglish(enabledKinds(program, caps).map((k) => LABEL[k].short));
+}
+
+export function configureCommandDescription(program: CliProgram, caps: CliCapabilities): string {
+  return `Set up ${prose(program, caps)} for this app (binary via Homebrew).`;
+}
+
+export function configureSyncOptionDescription(program: CliProgram, caps: CliCapabilities): string {
+  return `Refresh installed ${short(program, caps)}. Used by Homebrew post_install.`;
+}
+
+export function docsSkillTopicDescription(program: CliProgram, caps: CliCapabilities): string {
+  if (caps.configure) {
+    return "Print a reference agent SKILL; run `configure` to install an optimized copy.";
+  }
+  return "Print a reference agent SKILL for AI agents.";
+}
+
+export function configureCommandNotes(program: CliProgram, caps: CliCapabilities): string {
+  const app = program.key;
+  const lines = [
+    "Install the binary via Homebrew (tap-from-repo), then set up agent artifacts:",
+    `  brew tap <org>/<repo>`,
+    `  brew install <tap>/${app}`,
+    "",
+    "Homebrew post_install runs:",
+    `  ${app} configure --sync --yes`,
+    "",
+    "Interactive setup (per target):",
+    `  ${app} configure`,
+    "",
+    "Upgrade:",
+    `  brew upgrade ${app}`,
+    "",
+    "Shell completions are installed by Homebrew during brew install.",
+    "See: https://docs.brew.sh/Shell-Completion",
+    "",
+    "See what is installed:",
+    `  ${app} configure --status`,
+    "",
+    "Remove agent artifacts before brew uninstall:",
+    `  ${app} configure --remove-all --yes`,
+    `  brew uninstall <tap>/${app}`,
+    "",
+  ];
+  if (program.appConfig) {
+    lines.push("Remove app config only:", `  ${app} configure --remove-config --yes`, "");
+  }
+  lines.push(
+    "Use --dry to preview changes without writing files.",
+    "Use --json for machine-readable output.",
+  );
+  return lines.join("\n");
+}

package/src/builtins/configure.ts

@@ -0,0 +1,70 @@
+import { resolveCapabilities } from "../capabilities.ts";
+import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram } from "../types.ts";
+import {
+  configureCommandDescription,
+  configureCommandNotes,
+  configureSyncOptionDescription,
+} from "./configure-copy.ts";
+
+/** Configure command options. */
+export function configureBuiltinOptions(root: CliProgram): CliOption[] {
+  const caps = resolveCapabilities(root);
+  const opts: CliOption[] = [
+    {
+      name: "sync",
+      description: configureSyncOptionDescription(root, caps),
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "remove-all",
+      description: "Remove all detected agent artifacts (skills and MCP).",
+      kind: CliOptionKind.Presence,
+    },
+  ];
+
+  if (root.appConfig) {
+    opts.push({
+      name: "remove-config",
+      description: "Remove the app config file only.",
+      kind: CliOptionKind.Presence,
+    });
+  }
+
+  opts.push(
+    {
+      name: "status",
+      description: "Print what is currently installed (read-only).",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "yes",
+      description: "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+      kind: CliOptionKind.Presence,
+      shortName: "y",
+    },
+    {
+      name: "dry",
+      description: "Show what would change without writing files.",
+      kind: CliOptionKind.Presence,
+    },
+    {
+      name: "json",
+      description: "Print changed paths or status JSON on stdout.",
+      kind: CliOptionKind.Presence,
+    },
+  );
+
+  return opts;
+}
+
+/** Builds the `configure` built-in command. */
+export function cliBuiltinConfigureCommand(root: CliProgram): CliLeaf {
+  const caps = resolveCapabilities(root);
+  return {
+    key: "configure",
+    description: configureCommandDescription(root, caps),
+    options: configureBuiltinOptions(root),
+    notes: configureCommandNotes(root, caps),
+    handler: () => {},
+  };
+}