@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/update.ts

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { normalizeAgentClients } from './agent-clients/config.ts';
+import {
+  applyAgentClientReconciliation,
+  planAgentClientReconciliation
+} from './agent-clients/reconcile.ts';
 import { info, ok, err } from './log.ts';
 import { resolveTemplateDir } from './paths.ts';
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
-import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.ts';
-import type { BuiltinTUIId } from './builtin-tuis.ts';
+import { renderFile, copySkillDir } from './render.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -24,6 +27,8 @@ type UpdateConfig = {
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
   tuis?: unknown;
+  agentClients?: unknown;
+  customTUIs?: unknown;
 };
 
 type Defaults = {
@@ -40,9 +45,6 @@ const defaults = JSON.parse(
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
-const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
-const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
-const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
 
 // One-time migration of the legacy project-level PR switch to the three-state
 // `prFlow` preference. `true` (the old default / "PR flow on") maps to the
@@ -63,83 +65,6 @@ function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
   return null;
 }
 
-function isLegacyDefaultSandboxTools(value: unknown): value is string[] {
-  if (!Array.isArray(value) || value.length !== LEGACY_DEFAULT_SANDBOX_TOOLS.length) {
-    return false;
-  }
-  const tools = new Set(value);
-  return LEGACY_DEFAULT_SANDBOX_TOOLS.every((tool) => tools.has(tool));
-}
-
-function migrateSandboxTools(config: UpdateConfig): boolean {
-  const tools = config.sandbox?.tools;
-  if (!isLegacyDefaultSandboxTools(tools)) {
-    return false;
-  }
-  config.sandbox = {
-    ...config.sandbox,
-    tools: [...DEFAULT_SANDBOX_TOOLS]
-  };
-  return true;
-}
-
-function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
-  const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
-  if (!top.startsWith('.')) return false;
-
-  const candidate = top.slice(1);
-  if (!KNOWN_PLATFORMS.has(candidate)) return false;
-  return candidate !== platformType;
-}
-
-function syncFileRegistry(config: UpdateConfig, platformType: string, enabledTUIs: Set<BuiltinTUIId>) {
-  config.files ||= {};
-  const before = JSON.stringify({
-    files: {
-      managed: config.files.managed || [],
-      merged: config.files.merged || [],
-      ejected: config.files.ejected || []
-    }
-  });
-  config.files.managed = config.files.managed || [];
-  config.files.merged = config.files.merged || [];
-  config.files.ejected = config.files.ejected || [];
-
-  const allExisting = [
-    ...config.files.managed,
-    ...config.files.merged,
-    ...config.files.ejected
-  ];
-  const added: Pick<FileRegistry, 'managed' | 'merged'> = { managed: [], merged: [] };
-
-  for (const entry of defaults.files.managed) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.managed.push(entry);
-      added.managed.push(entry);
-    }
-  }
-  for (const entry of defaults.files.merged) {
-    if (isPathOwnedByOtherPlatform(entry, platformType)) continue;
-    if (isPathOwnedByDisabledTUI(entry, enabledTUIs)) continue;
-    if (!allExisting.includes(entry)) {
-      config.files.merged.push(entry);
-      added.merged.push(entry);
-    }
-  }
-
-  const after = JSON.stringify({
-    files: {
-      managed: config.files.managed,
-      merged: config.files.merged,
-      ejected: config.files.ejected
-    }
-  });
-
-  return { added, changed: before !== after };
-}
-
 async function cmdUpdate(): Promise<void> {
   console.log('');
   console.log('  ai update');
@@ -167,24 +92,36 @@ async function cmdUpdate(): Promise<void> {
   const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as UpdateConfig;
   const { project, org, language } = config;
   const platformType = config.platform?.type || defaults.platform.type;
-  const enabledTUIs = resolveEnabledTUIs(config.tuis);
   const replacements = { project, org };
 
+  const normalizedOriginal = normalizeAgentClients(config);
+  const currentRegistry: FileRegistry = {
+    managed: config.files?.managed || [],
+    merged: config.files?.merged || [],
+    ejected: config.files?.ejected || []
+  };
+  const platformAdded = !config.platform;
+  const sandboxAdded = !config.sandbox;
+  const taskAdded = !config.task;
+  const labelsAdded = !config.labels;
+  const prFlowMigrated = migratePrFlow(config);
+  if (platformAdded) config.platform = structuredClone(defaults.platform);
+  if (sandboxAdded) config.sandbox = structuredClone(defaults.sandbox);
+  if (taskAdded) config.task = structuredClone(defaults.task);
+  if (labelsAdded) config.labels = structuredClone(defaults.labels);
+
+  const workflowPlan = planAgentClientReconciliation({
+    config: config as unknown as Record<string, unknown>,
+    mutation: { type: 'replace-state', state: normalizedOriginal.state },
+    projectRoot: process.cwd(),
+    templateRoot: templateDir,
+    platformType,
+    language
+  });
+
   info(`Updating seed files for: ${project}`);
   console.log('');
 
-  // select language-specific template filenames
-  let claudeSrc, geminiSrc, opencodeSrc;
-  if (language === 'zh-CN') {
-    claudeSrc = 'update-agent-infra.zh-CN.md';
-    geminiSrc = 'update-agent-infra.zh-CN.toml';
-    opencodeSrc = 'update-agent-infra.zh-CN.md';
-  } else {
-    claudeSrc = 'update-agent-infra.en.md';
-    geminiSrc = 'update-agent-infra.en.toml';
-    opencodeSrc = 'update-agent-infra.en.md';
-  }
-
   // update skill
   copySkillDir(
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
@@ -206,76 +143,19 @@ async function cmdUpdate(): Promise<void> {
     // Ignore missing legacy script from pre-ESM installs.
   }
 
-  // update Claude command (only if enabled)
-  if (enabledTUIs.has('claude-code')) {
-    renderFile(
-      path.join(templateDir, '.claude', 'commands', claudeSrc),
-      path.join('.claude', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .claude/commands/update-agent-infra.md');
-  }
-
-  // update Gemini command (only if enabled)
-  if (enabledTUIs.has('gemini-cli')) {
-    renderFile(
-      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-      replacements
-    );
-    ok(`Updated .gemini/commands/${project}/update-agent-infra.toml`);
-  }
-
-  // update OpenCode command (only if enabled)
-  if (enabledTUIs.has('opencode')) {
-    renderFile(
-      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-      path.join('.opencode', 'commands', 'update-agent-infra.md'),
-      replacements
-    );
-    ok('Updated .opencode/commands/update-agent-infra.md');
-  }
-
-  // sync file registry
-  const { added, changed } = syncFileRegistry(config, platformType, enabledTUIs);
+  const added = {
+    managed: workflowPlan.projectAssets.registry.managed.filter(
+      (entry) => !currentRegistry.managed.includes(entry)
+    ),
+    merged: workflowPlan.projectAssets.registry.merged.filter(
+      (entry) => !currentRegistry.merged.includes(entry)
+    )
+  };
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
-  const platformAdded = !config.platform;
-  const sandboxAdded = !config.sandbox;
-  const taskAdded = !config.task;
-  const labelsAdded = !config.labels;
-  const prFlowMigrated = migratePrFlow(config);
-  const sandboxToolsMigrated = !sandboxAdded && migrateSandboxTools(config);
-  let configChanged = changed;
+  const reconcileResult = applyAgentClientReconciliation(workflowPlan);
+  for (const target of reconcileResult.applied) ok(`Updated ${target}`);
 
-  if (platformAdded) {
-    config.platform = structuredClone(defaults.platform);
-    configChanged = true;
-  }
-
-  if (sandboxAdded) {
-    config.sandbox = structuredClone(defaults.sandbox);
-    configChanged = true;
-  }
-
-  if (taskAdded) {
-    config.task = structuredClone(defaults.task);
-    configChanged = true;
-  }
-
-  if (labelsAdded) {
-    config.labels = structuredClone(defaults.labels);
-    configChanged = true;
-  }
-
-  if (prFlowMigrated) {
-    configChanged = true;
-  }
-
-  if (sandboxToolsMigrated) {
-    configChanged = true;
-  }
-
-  if (configChanged) {
+  if (reconcileResult.configUpdated) {
     console.log('');
     if (hasNewEntries) {
       info(`New file entries synced to ${CONFIG_PATH}:`);
@@ -301,9 +181,6 @@ async function cmdUpdate(): Promise<void> {
       if (prFlowMigrated) {
         info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
-      if (sandboxToolsMigrated) {
-        info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -322,10 +199,6 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && prFlowMigrated) {
       info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && sandboxToolsMigrated) {
-      info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
-    }
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);
   }
 
@@ -333,24 +206,15 @@ async function cmdUpdate(): Promise<void> {
   console.log('');
   ok('Seed files updated successfully!');
   console.log('');
-  if (enabledTUIs.size === 0) {
-    console.log('  No built-in TUI enabled (tuis: []).');
+  if (workflowPlan.nextSteps.length === 0) {
+    console.log('  No Agent Client project integration enabled.');
     console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
     console.log('');
   } else {
     console.log('  Next step: run the full update in your AI TUI:');
     console.log('');
-    const claudeOrOpencode: string[] = [];
-    if (enabledTUIs.has('claude-code')) claudeOrOpencode.push('Claude Code');
-    if (enabledTUIs.has('opencode')) claudeOrOpencode.push('OpenCode');
-    if (claudeOrOpencode.length > 0) {
-      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
-    }
-    if (enabledTUIs.has('gemini-cli')) {
-      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-    }
-    if (enabledTUIs.has('codex')) {
-      console.log('    Codex CLI:               $update-agent-infra');
+    for (const nextStep of workflowPlan.nextSteps) {
+      console.log(`    ${nextStep.displayName}: ${nextStep.command}`);
     }
     console.log('');
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.1",
-  "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
+  "version": "0.9.3",
+  "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
   "author": "CodeCaster <codecaster365@outlook.com>",
@@ -38,7 +38,7 @@
     "collaboration",
     "claude-code",
     "codex",
-    "gemini",
+    "antigravity",
     "opencode",
     "cli",
     "bootstrap",
@@ -73,7 +73,7 @@
     "typescript": "~7.0"
   },
   "optionalDependencies": {
-    "@lydell/node-pty": "^1.2.0-beta.12"
+    "@lydell/node-pty": "^1.2.0-beta.14"
   },
   "overrides": {
     "axios": "1.18.1"

package/templates/.agents/QUICKSTART.en.md

@@ -4,7 +4,7 @@ This guide walks you through using multiple AI coding assistants together on a p
 
 ## Prerequisites
 
-- At least one AI coding tool installed (Claude Code, Codex CLI, Gemini CLI, or OpenCode)
+- At least one AI coding tool installed (Claude Code, Codex CLI, Antigravity CLI, or OpenCode)
 - A project with `.agents/` directory set up (this project)
 - Familiarity with your project's codebase
 
@@ -18,6 +18,23 @@ git config core.hooksPath .git-hooks
 
 This makes Git invoke the hooks in the project repository's `.git-hooks/` directory, including `pre-commit` and `check-version-format.sh`.
 
+## Development Checkout CLI Alignment
+
+When developing agent-infra from a source checkout, install dependencies and rebuild the local CLI before running lifecycle orchestration:
+
+```bash
+npm install
+npm run build
+```
+
+Lifecycle hooks prefer the checkout's `dist/bin/internal-cli.js` when it exists and fall back to `agent-infra-internal` on `PATH` otherwise. Rebuild after CLI source changes. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
+
+```bash
+npm link
+ai version --raw
+node -p "'v' + require('./package.json').version"
+```
+
 ## External Templates And Skills
 
 If your team maintains private platform templates or shared custom skills, configure local sources in `.agents/.airc.json`:
@@ -49,7 +66,7 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | review
 status: open           # open | in-progress | review | blocked | completed
-assigned_to: claude    # claude | codex | gemini | opencode | human
+assigned_to: claude    # claude | codex | antigravity | opencode | human
 ```
 
 3. Describe the task in the body of the document.
@@ -69,11 +86,11 @@ claude
 
 Claude Code excels at codebase exploration and understanding complex relationships between files.
 
-### Phase 2: Design (Recommended: Claude Code or Gemini CLI)
+### Phase 2: Design (Recommended: Claude Code or Antigravity CLI)
 
 ```bash
-# Continue with Claude Code or switch to Gemini CLI for large codebases
-gemini
+# Continue with Claude Code or switch to Antigravity CLI for large codebases
+agy
 
 # Example prompt:
 # "Based on the analysis in .agents/workspace/active/task-001.md,
@@ -134,7 +151,7 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 
 ### Refactoring
 
-1. **Analyze Scope** (Claude Code / Gemini CLI): Map all affected areas.
+1. **Analyze Scope** (Claude Code / Antigravity CLI): Map all affected areas.
 2. **Design** (Claude Code): Plan the refactoring approach.
 3. **Implement** (Codex CLI / OpenCode): Execute the refactoring.
 4. **Verify** (Claude Code): Ensure no regressions, run tests.
@@ -172,9 +189,9 @@ Even if you're switching between AIs quickly, a brief handoff note saves time an
 
 ### 3. Use the Right Tool for the Job
 
-- Complex analysis? Use Claude Code or Gemini CLI.
+- Complex analysis? Use Claude Code or Antigravity CLI.
 - Straightforward implementation? Use Codex CLI or OpenCode.
-- Large file review? Use Gemini CLI.
+- Large file review? Use Antigravity CLI.
 
 ### 4. Keep Tasks Small
 

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -4,7 +4,7 @@
 
 ## 前提条件
 
-- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Gemini CLI 或 OpenCode）
+- 至少安装一个 AI 编程工具（Claude Code、Codex CLI、Antigravity CLI 或 OpenCode）
 - 项目已设置 `.agents/` 目录（本项目已就绪）
 - 熟悉你的项目代码库
 
@@ -18,6 +18,23 @@ git config core.hooksPath .git-hooks
 
 这样 Git 才会调用项目仓库 `.git-hooks/` 目录下的 hook，包括 `pre-commit` 和 `check-version-format.sh`。
 
+## 开发检出中的 CLI 对齐
+
+从源码检出开发 agent-infra 时，请先安装依赖并重新构建本地 CLI，再运行生命周期编排：
+
+```bash
+npm install
+npm run build
+```
+
+本地 `dist/bin/internal-cli.js` 存在时，生命周期 hook 会优先使用它；不存在时则回退到 `PATH` 上的 `agent-infra-internal`。修改 CLI 源码后需要重新构建。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+
+```bash
+npm link
+ai version --raw
+node -p "'v' + require('./package.json').version"
+```
+
 ## 外部模板与 Skill
 
 如果团队维护私有平台模板或共享自定义 skill，可在 `.agents/.airc.json` 中配置本地源：
@@ -49,7 +66,7 @@ cp .agents/templates/task.md .agents/workspace/active/task-001.md
 id: task-001
 type: feature          # feature | bugfix | refactor | docs | chore
 status: active         # active | blocked | completed
-assigned_to: claude    # claude | codex | gemini | opencode | human
+assigned_to: claude    # claude | codex | antigravity | opencode | human
 ```
 
 3. 在文档正文中描述任务。
@@ -69,11 +86,11 @@ claude
 
 Claude Code 擅长代码库探索和理解文件间的复杂关系。
 
-### 阶段 2：设计（推荐：Claude Code 或 Gemini CLI）
+### 阶段 2：设计（推荐：Claude Code 或 Antigravity CLI）
 
 ```bash
-# 继续使用 Claude Code 或切换到 Gemini CLI 处理大型代码库
-gemini
+# 继续使用 Claude Code 或切换到 Antigravity CLI 处理大型代码库
+agy
 
 # 示例提示：
 # "基于 .agents/workspace/active/task-001.md 中的分析结果，
@@ -134,7 +151,7 @@ cp .agents/templates/review-report.md .agents/workspace/active/review-pr-42.md
 
 ### 重构
 
-1. **分析范围**（Claude Code / Gemini CLI）：映射所有受影响区域。
+1. **分析范围**（Claude Code / Antigravity CLI）：映射所有受影响区域。
 2. **设计**（Claude Code）：规划重构方案。
 3. **实现**（Codex CLI / OpenCode）：执行重构。
 4. **验证**（Claude Code）：确保没有回归问题，运行测试。
@@ -172,9 +189,9 @@ cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2
 
 ### 3. 选择合适的工具
 
-- 复杂分析？使用 Claude Code 或 Gemini CLI。
+- 复杂分析？使用 Claude Code 或 Antigravity CLI。
 - 直接的实现工作？使用 Codex CLI 或 OpenCode。
-- 大文件审查？使用 Gemini CLI。
+- 大文件审查？使用 Antigravity CLI。
 
 ### 4. 保持任务小而精
 

package/templates/.agents/README.en.md

@@ -1,6 +1,6 @@
 # Multi-AI Collaboration Guide
 
-This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode, and others.
+This project supports collaboration across multiple AI coding assistants, including Claude Code, OpenAI Codex CLI, Antigravity CLI, OpenCode, and others.
 
 ## Dual-Config Architecture
 
@@ -10,7 +10,7 @@ Different AI tools read configuration from different locations:
 |---------|---------------|----------|
 | Claude Code | `.claude/` (CLAUDE.md, commands/, settings.json) | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
-| Gemini CLI | `AGENTS.md` | - |
+| Antigravity CLI | `AGENTS.md`, `.agents/skills/` | - |
 | OpenCode | `AGENTS.md` | - |
 | Other AI Tools | `AGENTS.md` | Project README |
 
@@ -75,7 +75,7 @@ When one AI completes a phase, it produces a **handoff document** (see `.agents/
 
 Each AI tool has different strengths. Use them accordingly:
 
-| Capability | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+| Capability | Claude Code | Codex CLI | Antigravity CLI | OpenCode |
 |-----------|-------------|-----------|------------|----------|
 | Codebase analysis | Excellent | Good | Excellent | Good |
 | Code review | Excellent | Good | Good | Good |
@@ -88,7 +88,7 @@ Each AI tool has different strengths. Use them accordingly:
 
 - **Analysis & Review** - Claude Code (strong reasoning, thorough exploration)
 - **Implementation** - Codex CLI or OpenCode (fast code generation, command-driven editing)
-- **Large Context Tasks** - Gemini CLI (large context window for cross-file analysis)
+- **Large Context Tasks** - Antigravity CLI (large context window for cross-file analysis)
 - **Command-Driven Iteration** - OpenCode (workflow-friendly TUI execution)
 
 ## Quick Start
@@ -173,7 +173,7 @@ Write `description` as "one-line responsibility + scenario clause": after the sh
 
 Set the generic optional `disable-model-invocation` field to `true` when generated TUI commands should disable model invocation; each TUI adapter consumes it according to its capabilities. To preserve line breaks in a multiline `description`, use a YAML literal block (`|`); sync emits the corresponding multiline metadata format for each TUI.
 
-After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills and generates matching commands for Claude Code, Gemini CLI, and OpenCode automatically.
+After adding or updating a custom skill, run `update-agent-infra` again. The sync step detects non-built-in skills, generates matching commands for Claude Code and OpenCode, and lets Antigravity CLI discover the shared skills directly.
 
 ### Shared skill sources
 
@@ -218,37 +218,41 @@ Ordinary `managed` files keep their overwrite semantics. A small set of platform
 
 `ejected` entries support literal paths or globs, using the same matching rules as `merged`.
 
-## Built-in TUI Selection
+## Agent Client Configuration
 
-Use the top-level `.agents/.airc.json` `tuis` array to pick which built-in TUIs (`claude-code`, `codex`, `gemini-cli`, `opencode`) agent-infra should install command files for and keep in sync.
+Use the top-level `.agents/.airc.json` `agentClients` array to configure all four built-in clients (`claude-code`, `codex`, `antigravity-cli`, `opencode`). Each canonical entry has three required fields and one optional orchestration policy:
 
-| Value | Meaning |
+| Field | Meaning |
 |-------|---------|
-| `tuis` missing or `null` | All four built-in TUIs are enabled (backward-compatible default for legacy `.airc.json` predating this field). |
-| `tuis: []` | No built-in TUI is managed. Use this when the project only relies on `customTUIs` and does not need any built-in command files installed. |
-| `tuis: [<subset>]` | Only the listed TUIs are managed. Unknown ids are ignored. |
+| `id` | Built-in Agent Client id. The canonical array contains exactly one entry for each built-in client. |
+| `enabled` | Whether agent-infra writes and maintains that client's project integration and seed command. |
+| `installInSandbox` | Whether the sandbox image installs that client's CLI. This is independent from `enabled`. |
+| `orchestration` | Optional `run-task` default. It must include executor/reviewer `model` and host-native `reasoningEffort`; both roles may use the same model. |
+
+Explicit `run-task` model/effort flags are atomic: any one requires all four role fields and configuration never fills omissions. With no explicit policy, only the current client's `orchestration` is used. Query model-selection context with `agent-infra-internal agent-client model-selection --client <id>`; it labels results complete, partial, or interactive-only and never presents a local override list as a complete catalog.
 
-`ai init` includes an interactive multi-select for this field:
+Manage these settings without hand-editing JSON:
 
-- Press Enter to accept the default (all built-in TUIs enabled).
-- Type comma-separated numbers or ids (e.g. `1,3` or `claude-code,opencode`) to keep a subset.
-- Type `none` to explicitly disable every built-in TUI (typically combined with a `customTUIs` entry added later).
-- Invalid input (duplicate, out-of-range, unknown id, whitespace-only) aborts init with a non-zero exit code.
+```bash
+ai agent-client list
+ai agent-client status
+ai agent-client enable codex
+ai agent-client disable antigravity-cli
+ai agent-client configure
+```
 
-### Side effects of disabling a TUI
+`enable` and `disable` only change `enabled`; `configure` edits both dimensions. `ai init` asks which clients to enable and preserves the displayed defaults when you press Enter. All clients default to `installInSandbox: true`.
 
-When you disable a built-in TUI (either via `ai init` or by hand-editing `.airc.json`), the next `ai update` / `update-agent-infra` will:
+Legacy `tuis` and built-in client ids in `sandbox.tools` are migration inputs only. The next config-writing command converts them into the canonical `agentClients` array and removes the legacy fields. If canonical and legacy values conflict, the command stops without modifying files so the conflict can be resolved explicitly.
 
-- skip seed command writes for that TUI (e.g. `.gemini/commands/<project>/update-agent-infra.toml`);
-- skip the TUI's owned default entries when backfilling `files.managed` / `files.merged`;
-- **clean up existing files** under the TUI's owned path prefix (`.claude/`, `.codex/`, `.gemini/`, `.opencode/`) — these are listed in `report.managed.removed`, mirroring the cleanup behavior when switching `platform`.
+### Side effects of disabling an Agent Client
 
-To opt a specific file out of this cleanup, list it in `files.ejected`; ejected entries owned by disabled TUIs are preserved as-is and are not re-created by sync.
+When you disable a built-in client, reconciliation stops maintaining its seed command and owned registry entries. An unchanged generated seed may be removed; a locally modified seed is protected and reported instead. Files listed in `files.ejected` remain project-owned and are preserved.
 
 ### Relation to other config fields
 
-- `tuis` controls **which TUI command files agent-infra writes and maintains**. It is independent from `sandbox.tools`, which controls **which CLIs the sandbox image installs**. Toggling one does not affect the other; the README for `sandbox.tools` lives in the Sandbox section.
-- `tuis` is independent from `customTUIs` (see below). CustomTUI command files are not removed when you disable a built-in TUI, even if the customTUI's `dir` falls under that TUI's owned prefix (e.g. a customTUI configured with `dir: ".codex/commands"` is preserved when `codex` is disabled).
+- `sandbox.tools` now lists non-client tools such as `agent-infra` and custom tools. Built-in client installation belongs in `agentClients[].installInSandbox`.
+- `agentClients` is independent from `customTUIs` (see below). Custom TUI command files are preserved even when their directory is under a disabled built-in client's path prefix.
 
 ## Custom TUI Configuration
 
@@ -300,7 +304,7 @@ Namespaced custom TUI:
 
 ## Sandbox Custom Tools
 
-`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in sandbox tools (`claude-code`, `codex`, `opencode`, `gemini-cli`, `agent-infra`) keep working unchanged; `agent-infra` only provides the in-sandbox `ai` / `agent-infra` CLI and is not part of `tuis` or `customTUIs`.
+`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in Agent Clients are installed according to `agentClients[].installInSandbox`; `agent-infra` remains a non-client entry in `sandbox.tools` and only provides the in-sandbox `ai` / `agent-infra` CLI.
 
 ### Required fields