subconscious-cli 6.0.1 → 6.2.0

package/bin/profiles.js

@@ -7,23 +7,28 @@
  */
 
 import { execFileSync, spawn } from 'node:child_process';
-import { readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { c } from './colors.js';
 import { PUBLIC_CATALOG_FALLBACK_MESSAGE } from './models.js';
-import { runWindows, windowsEditor } from './windows/process.js';
+import {
+  profileTemplate,
+  RUNBOOK_DEFAULTS,
+  SUPPORTED_MODELS,
+} from './profile-settings.js';
+
+export {
+  PROFILE_SETTING_GROUPS,
+  profileSettingsForAgent,
+  RUNBOOK_DEFAULTS,
+  resolvedProfileValues,
+  SUPPORTED_MODELS,
+} from './profile-settings.js';
 
-const registry = JSON.parse(
-  readFileSync(new URL('./registry.generated.json', import.meta.url), 'utf-8'),
-);
+import { runWindows, windowsEditor } from './windows/process.js';
 
 export const DEFAULT_PROFILE = 'default';
-export const SUPPORTED_MODELS =
-  Array.isArray(registry.defaults.models) && registry.defaults.models.length
-    ? registry.defaults.models
-    : [registry.defaults.model];
 const PREVIOUS_DEFAULT_GATEWAYS = new Set([
   'https://api.subconscious.dev',
   'https://api.subconscious.dev/',
@@ -35,416 +40,6 @@ const LEGACY_PROFILES_DIR = CONFIG_OVERRIDE
   ? null
   : path.join(os.homedir(), '.subcon', 'profiles');
 
-export const RUNBOOK_DEFAULTS = {
-  GATEWAY_URL: registry.defaults.baseUrl,
-  API_KEY: '',
-  MODEL: registry.defaults.model,
-  SC_API_KEY: '',
-  CLAUDE_CODE_SUBAGENT_MODEL: '',
-  CLAUDE_GATEWAY_URL: '',
-  CLAUDE_CODE_API_KEY: '',
-  CODEX_API_KEY: '',
-  OPENCODE_API_KEY: '',
-  CURSOR_API_KEY: '',
-  COPILOT_API_KEY: '',
-  PI_API_KEY: '',
-  DEEPSEEK_HARNESS_API_KEY: '',
-  CLAUDE_CODE_AUTO_COMPACT_WINDOW: '1000000',
-  CLAUDE_CODE_MAX_CONTEXT_TOKENS: '3000000',
-  MAX_CONCURRENT_SUBAGENTS: '4',
-  MAX_SUBAGENT_SPAWN_DEPTH: '1',
-  CODEX_CONTEXT_WINDOW: '5000000',
-  CODEX_MAX_CONTEXT_WINDOW: '5000000',
-  CODEX_AUTO_COMPACT_TOKEN_LIMIT: '4500000',
-  CODEX_REASONING_EFFORT: 'max',
-  CODEX_EXTERNAL_TOOLS: 'false',
-  OPENCODE_CONTEXT_LIMIT: '5000000',
-  OPENCODE_OUTPUT_LIMIT: '65536',
-  PI_CONTEXT_WINDOW: '5000000',
-  PI_MAX_TOKENS: '65536',
-  DEEPSEEK_HARNESS_CONTEXT_WINDOW: '5000000',
-  DEEPSEEK_HARNESS_MAX_TOKENS: '65536',
-  COPILOT_MAX_INPUT_TOKENS: '5000000',
-  COPILOT_MAX_OUTPUT_TOKENS: '65536',
-  VSCODE_APP: '',
-};
-
-const SETTINGS = {
-  GATEWAY_URL: {
-    key: 'GATEWAY_URL',
-    label: 'Gateway URL',
-    description: 'Subconscious gateway origin shared by every integration.',
-    type: 'url',
-    required: true,
-  },
-  PLATFORM_URL: {
-    key: 'PLATFORM_URL',
-    label: 'Platform URL',
-    description: 'Subconscious platform origin for login, whoami, and usage.',
-    type: 'url',
-  },
-  API_KEY: {
-    key: 'API_KEY',
-    label: 'Shared API key',
-    description: 'Default credential used when an agent-specific key is blank.',
-    type: 'secret',
-  },
-  MODEL: {
-    key: 'MODEL',
-    label: 'Default model',
-    description:
-      'Initial model used by coding-agent launches and setup. UNSET uses the first live catalog model.',
-    type: 'choice',
-    choices: SUPPORTED_MODELS,
-  },
-  SC_API_KEY: {
-    key: 'SC_API_KEY',
-    label: 'Subconscious Code API key',
-    description: 'Subconscious Code credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  CLAUDE_CODE_SUBAGENT_MODEL: {
-    key: 'CLAUDE_CODE_SUBAGENT_MODEL',
-    label: 'Subagent model',
-    description:
-      'Model used by Claude Code subagents. UNSET follows the default model.',
-    type: 'choice',
-    choices: SUPPORTED_MODELS,
-  },
-  CLAUDE_GATEWAY_URL: {
-    key: 'CLAUDE_GATEWAY_URL',
-    label: 'Claude gateway override',
-    description: 'Optional Claude-only gateway origin; blank uses GATEWAY_URL.',
-    type: 'url',
-  },
-  CLAUDE_CODE_API_KEY: {
-    key: 'CLAUDE_CODE_API_KEY',
-    label: 'Claude API key',
-    description: 'Claude-specific credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  CLAUDE_CODE_AUTO_COMPACT_WINDOW: {
-    key: 'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
-    label: 'Auto-compact window',
-    description: 'Claude token window before compaction (100000–1000000).',
-    type: 'integer',
-    min: 100000,
-    max: 1000000,
-  },
-  CLAUDE_CODE_MAX_CONTEXT_TOKENS: {
-    key: 'CLAUDE_CODE_MAX_CONTEXT_TOKENS',
-    label: 'Maximum context tokens',
-    description: 'Maximum context advertised to Claude Code.',
-    type: 'integer',
-    min: 1,
-  },
-  MAX_CONCURRENT_SUBAGENTS: {
-    key: 'MAX_CONCURRENT_SUBAGENTS',
-    label: 'Concurrent subagents',
-    description: 'Maximum concurrent Claude/Codex subagent threads.',
-    type: 'integer',
-    min: 1,
-  },
-  CODEX_SUBAGENT_REASONING_EFFORT: {
-    key: 'CODEX_SUBAGENT_REASONING_EFFORT',
-    label: 'Subagent reasoning effort',
-    description:
-      'Effort for Codex subagents, set separately from the parent: a marathon model at max thinks for minutes without emitting a token, and a subagent turn is one uninterrupted think, so inheriting max makes every delegated subtask look like a hang.',
-    type: 'text',
-  },
-  CODEX_MULTI_AGENT_VERSION: {
-    key: 'CODEX_MULTI_AGENT_VERSION',
-    label: 'Codex multi-agent version',
-    description:
-      'Which subagent implementation Codex offers: v2 gives the collaboration tools. Leave empty to turn subagents off entirely.',
-    type: 'text',
-  },
-  CODEX_STREAM_IDLE_TIMEOUT_MS: {
-    key: 'CODEX_STREAM_IDLE_TIMEOUT_MS',
-    label: 'Stream idle timeout (ms)',
-    description:
-      'How long Codex waits on a silent stream before giving up. Needs to exceed the longest think the model will take.',
-    type: 'integer',
-    min: 1,
-  },
-  MAX_SUBAGENT_SPAWN_DEPTH: {
-    key: 'MAX_SUBAGENT_SPAWN_DEPTH',
-    label: 'Subagent spawn depth',
-    description: 'Maximum Claude subagent nesting depth.',
-    type: 'integer',
-    min: 0,
-  },
-  CODEX_API_KEY: {
-    key: 'CODEX_API_KEY',
-    label: 'Codex API key',
-    description: 'Codex-specific credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  CODEX_CONTEXT_WINDOW: {
-    key: 'CODEX_CONTEXT_WINDOW',
-    label: 'Context window',
-    description: 'Context window written into the Codex model catalog.',
-    type: 'integer',
-    min: 1,
-  },
-  CODEX_MAX_CONTEXT_WINDOW: {
-    key: 'CODEX_MAX_CONTEXT_WINDOW',
-    label: 'Maximum context window',
-    description: 'Maximum context window written into the Codex catalog.',
-    type: 'integer',
-    min: 1,
-  },
-  CODEX_AUTO_COMPACT_TOKEN_LIMIT: {
-    key: 'CODEX_AUTO_COMPACT_TOKEN_LIMIT',
-    label: 'Auto-compact token limit',
-    description: 'Codex token threshold that triggers automatic compaction.',
-    type: 'integer',
-    min: 1,
-  },
-  CODEX_REASONING_EFFORT: {
-    key: 'CODEX_REASONING_EFFORT',
-    label: 'Reasoning effort',
-    description: 'Default Codex reasoning effort.',
-    type: 'choice',
-    choices: ['none', 'low', 'medium', 'high', 'max'],
-  },
-  CODEX_EXTERNAL_TOOLS: {
-    key: 'CODEX_EXTERNAL_TOOLS',
-    label: 'External tools',
-    description:
-      'Enable Codex apps/plugins; may exceed the gateway tool limit.',
-    type: 'choice',
-    choices: ['false', 'true'],
-  },
-  OPENCODE_API_KEY: {
-    key: 'OPENCODE_API_KEY',
-    label: 'OpenCode API key',
-    description: 'OpenCode-specific credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  OPENCODE_CONTEXT_LIMIT: {
-    key: 'OPENCODE_CONTEXT_LIMIT',
-    label: 'Context limit',
-    description: 'OpenCode provider context limit used for compaction.',
-    type: 'integer',
-    min: 1,
-  },
-  OPENCODE_OUTPUT_LIMIT: {
-    key: 'OPENCODE_OUTPUT_LIMIT',
-    label: 'Output limit',
-    description: 'Maximum output tokens advertised to OpenCode.',
-    type: 'integer',
-    min: 1,
-  },
-  CURSOR_API_KEY: {
-    key: 'CURSOR_API_KEY',
-    label: 'Cursor hook API key',
-    description: 'Cursor hook credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  COPILOT_API_KEY: {
-    key: 'COPILOT_API_KEY',
-    label: 'Copilot hook API key',
-    description: 'Copilot hook credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  COPILOT_MAX_INPUT_TOKENS: {
-    key: 'COPILOT_MAX_INPUT_TOKENS',
-    label: 'Maximum input tokens',
-    description: 'Input-token capacity advertised to VS Code.',
-    type: 'integer',
-    min: 1,
-  },
-  COPILOT_MAX_OUTPUT_TOKENS: {
-    key: 'COPILOT_MAX_OUTPUT_TOKENS',
-    label: 'Maximum output tokens',
-    description: 'Output-token capacity advertised to VS Code.',
-    type: 'integer',
-    min: 1,
-  },
-  VSCODE_APP: {
-    key: 'VSCODE_APP',
-    label: 'VS Code application',
-    description: 'Optional application override; blank enables auto-detection.',
-    type: 'choice',
-    choices: ['', 'Code', 'Code - Insiders', 'VSCodium'],
-  },
-  PI_API_KEY: {
-    key: 'PI_API_KEY',
-    label: 'Pi API key',
-    description: 'Pi-specific credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  PI_CONTEXT_WINDOW: {
-    key: 'PI_CONTEXT_WINDOW',
-    label: 'Context window',
-    description: 'Pi context window used to determine compaction.',
-    type: 'integer',
-    min: 1,
-  },
-  PI_MAX_TOKENS: {
-    key: 'PI_MAX_TOKENS',
-    label: 'Maximum output tokens',
-    description: 'Maximum output tokens advertised to Pi.',
-    type: 'integer',
-    min: 1,
-  },
-  DEEPSEEK_HARNESS_API_KEY: {
-    key: 'DEEPSEEK_HARNESS_API_KEY',
-    label: 'DeepSeek Harness API key',
-    description: 'DeepSeek Harness credential override; blank uses API_KEY.',
-    type: 'secret',
-  },
-  DEEPSEEK_HARNESS_CONTEXT_WINDOW: {
-    key: 'DEEPSEEK_HARNESS_CONTEXT_WINDOW',
-    label: 'Context window',
-    description: 'Context capacity advertised to DeepSeek Harness.',
-    type: 'integer',
-    min: 1,
-  },
-  DEEPSEEK_HARNESS_MAX_TOKENS: {
-    key: 'DEEPSEEK_HARNESS_MAX_TOKENS',
-    label: 'Maximum output tokens',
-    description: 'Output capacity advertised to DeepSeek Harness.',
-    type: 'integer',
-    min: 1,
-  },
-};
-
-const AGENT_SETTING_KEYS = {
-  'subconscious-code': ['SC_API_KEY'],
-  'claude-code': [
-    'CLAUDE_GATEWAY_URL',
-    'CLAUDE_CODE_API_KEY',
-    'CLAUDE_CODE_SUBAGENT_MODEL',
-    'CLAUDE_CODE_AUTO_COMPACT_WINDOW',
-    'CLAUDE_CODE_MAX_CONTEXT_TOKENS',
-    'MAX_CONCURRENT_SUBAGENTS',
-    'MAX_SUBAGENT_SPAWN_DEPTH',
-  ],
-  codex: [
-    'CODEX_API_KEY',
-    'CODEX_CONTEXT_WINDOW',
-    'CODEX_MAX_CONTEXT_WINDOW',
-    'CODEX_AUTO_COMPACT_TOKEN_LIMIT',
-    'CODEX_REASONING_EFFORT',
-    'CODEX_EXTERNAL_TOOLS',
-    'CODEX_STREAM_IDLE_TIMEOUT_MS',
-    'CODEX_MULTI_AGENT_VERSION',
-    'CODEX_SUBAGENT_REASONING_EFFORT',
-    'MAX_CONCURRENT_SUBAGENTS',
-  ],
-  opencode: [
-    'OPENCODE_API_KEY',
-    'OPENCODE_CONTEXT_LIMIT',
-    'OPENCODE_OUTPUT_LIMIT',
-  ],
-  cursor: ['CURSOR_API_KEY'],
-  copilot: [
-    'COPILOT_API_KEY',
-    'COPILOT_MAX_INPUT_TOKENS',
-    'COPILOT_MAX_OUTPUT_TOKENS',
-    'VSCODE_APP',
-  ],
-  pi: ['PI_API_KEY', 'PI_CONTEXT_WINDOW', 'PI_MAX_TOKENS'],
-  'deepseek-harness': [
-    'DEEPSEEK_HARNESS_API_KEY',
-    'DEEPSEEK_HARNESS_CONTEXT_WINDOW',
-    'DEEPSEEK_HARNESS_MAX_TOKENS',
-  ],
-};
-
-const GROUP_KEYS = [
-  {
-    id: 'shared',
-    label: 'Shared settings',
-    keys: ['GATEWAY_URL', 'API_KEY', 'MODEL'],
-  },
-  ...registry.agents
-    .filter((agent) => agent.cli !== false)
-    .map((agent) => ({
-      id: agent.id,
-      label: agent.name,
-      keys: AGENT_SETTING_KEYS[agent.id] || [],
-    })),
-];
-
-export const PROFILE_SETTING_GROUPS = GROUP_KEYS.map((group) => ({
-  ...group,
-  settings: group.keys.map((key) => SETTINGS[key]),
-}));
-
-export function profileSettingsForAgent(agentId) {
-  const shared = PROFILE_SETTING_GROUPS.find((group) => group.id === 'shared');
-  const agent = PROFILE_SETTING_GROUPS.find((group) => group.id === agentId);
-  return [...(shared?.settings || []), ...(agent?.settings || [])];
-}
-
-export function resolvedProfileValues(profile) {
-  return { ...RUNBOOK_DEFAULTS, ...(profile?.values || {}) };
-}
-
-function profileTemplate() {
-  const modelComments = SUPPORTED_MODELS.map((model) => `#   ${model}`).join(
-    '\n',
-  );
-  return `# Subconscious coding-agent profile
-# Generated by subc. Extra KEY=value lines are passed through to launches.
-
-GATEWAY_URL={GATEWAY_URL}
-API_KEY={API_KEY}
-# Available models (MODEL=UNSET uses the first live catalog model):
-${modelComments}
-MODEL={MODEL}
-
-# Optional per-agent keys. Leave blank to use API_KEY above.
-SC_API_KEY={SC_API_KEY}
-CLAUDE_CODE_API_KEY={CLAUDE_CODE_API_KEY}
-CODEX_API_KEY={CODEX_API_KEY}
-OPENCODE_API_KEY={OPENCODE_API_KEY}
-CURSOR_API_KEY={CURSOR_API_KEY}
-COPILOT_API_KEY={COPILOT_API_KEY}
-PI_API_KEY={PI_API_KEY}
-DEEPSEEK_HARNESS_API_KEY={DEEPSEEK_HARNESS_API_KEY}
-
-# Claude Code
-# Leave CLAUDE_GATEWAY_URL blank to use GATEWAY_URL above.
-CLAUDE_GATEWAY_URL={CLAUDE_GATEWAY_URL}
-# CLAUDE_CODE_SUBAGENT_MODEL=UNSET follows MODEL above.
-CLAUDE_CODE_SUBAGENT_MODEL={CLAUDE_CODE_SUBAGENT_MODEL}
-CLAUDE_CODE_AUTO_COMPACT_WINDOW={CLAUDE_CODE_AUTO_COMPACT_WINDOW}
-CLAUDE_CODE_MAX_CONTEXT_TOKENS={CLAUDE_CODE_MAX_CONTEXT_TOKENS}
-MAX_CONCURRENT_SUBAGENTS={MAX_CONCURRENT_SUBAGENTS}
-MAX_SUBAGENT_SPAWN_DEPTH={MAX_SUBAGENT_SPAWN_DEPTH}
-
-# Codex
-CODEX_CONTEXT_WINDOW={CODEX_CONTEXT_WINDOW}
-CODEX_MAX_CONTEXT_WINDOW={CODEX_MAX_CONTEXT_WINDOW}
-CODEX_AUTO_COMPACT_TOKEN_LIMIT={CODEX_AUTO_COMPACT_TOKEN_LIMIT}
-CODEX_REASONING_EFFORT={CODEX_REASONING_EFFORT}
-CODEX_EXTERNAL_TOOLS={CODEX_EXTERNAL_TOOLS}
-
-# OpenCode
-OPENCODE_CONTEXT_LIMIT={OPENCODE_CONTEXT_LIMIT}
-OPENCODE_OUTPUT_LIMIT={OPENCODE_OUTPUT_LIMIT}
-
-# Pi
-PI_CONTEXT_WINDOW={PI_CONTEXT_WINDOW}
-PI_MAX_TOKENS={PI_MAX_TOKENS}
-
-# DeepSeek Harness
-DEEPSEEK_HARNESS_CONTEXT_WINDOW={DEEPSEEK_HARNESS_CONTEXT_WINDOW}
-DEEPSEEK_HARNESS_MAX_TOKENS={DEEPSEEK_HARNESS_MAX_TOKENS}
-
-# GitHub Copilot
-COPILOT_MAX_INPUT_TOKENS={COPILOT_MAX_INPUT_TOKENS}
-COPILOT_MAX_OUTPUT_TOKENS={COPILOT_MAX_OUTPUT_TOKENS}
-VSCODE_APP={VSCODE_APP}
-
-# Extra KEY=value lines are passed through to launches.
-`;
-}
-
 export function validateProfileName(name) {
   if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(name)) {
     throw new Error(
@@ -616,11 +211,21 @@ export async function clearProfileApiKey(name = DEFAULT_PROFILE) {
   return true;
 }
 
-function isSecretKey(key) {
+// PI_MAX_TOKENS=65536 is a budget, not a credential. Anything else under a
+// *_TOKENS name, such as a key pasted onto the wrong line, stays redacted.
+function isTokenBudget(key, value) {
+  return (
+    /_TOKENS$|_TOKEN_LIMIT$/i.test(key) &&
+    /^\d+$/.test(value) &&
+    Number.isSafeInteger(Number(value))
+  );
+}
+
+function isSecretKey(key, value) {
   const upper = key.toUpperCase();
   return (
     upper.endsWith('API_KEY') ||
-    upper.includes('TOKEN') ||
+    (upper.includes('TOKEN') && !isTokenBudget(key, value)) ||
     upper.includes('SECRET') ||
     upper.includes('PASSWORD') ||
     upper.includes('AUTH')
@@ -628,7 +233,7 @@ function isSecretKey(key) {
 }
 
 function redact(key, value) {
-  if (!isSecretKey(key) || !value) return value;
+  if (!value || !isSecretKey(key, value)) return value;
   return value.length <= 8
     ? '********'
     : `${value.slice(0, 4)}…${value.slice(-4)}`;
@@ -641,7 +246,7 @@ function redactEnvLine(line) {
   if (!match) return line;
   const [, prefix, key, raw] = match;
   const value = decodeValue(raw);
-  if (!isSecretKey(key) || !value) return line;
+  if (!value || !isSecretKey(key, value)) return line;
   return `${prefix}${key}=${redact(key, value)}`;
 }
 
@@ -950,7 +555,7 @@ export async function configCommand(
 
 export function modelsCommand(models = SUPPORTED_MODELS, options = {}) {
   const selectedModel =
-    options.selectedModel || models[0] || registry.defaults.model;
+    options.selectedModel || models[0] || RUNBOOK_DEFAULTS.MODEL;
   console.log(`\n  ${c.bold}Available models${c.reset}\n`);
   for (const model of models) {
     const suffix =

package/bin/runbook/README.md

@@ -1,25 +1,79 @@
 # Coding-agent integrations
 
-These scripts are part of `subc`. They launch or surgically install Claude Code,
-Subconscious Code, Codex, OpenCode, DeepSeek Harness, Cursor, Copilot, and Pi against the
-Subconscious gateway.
-
-`subc` reads `~/.subconscious/profiles/<name>.env` and injects those values into
-the scripts, so users do not need a sibling `.env` file. When a script is run
-directly, `SUBC_ENV_FILE` (or `bin/runbook/.env`) can supply the same keys.
-
-Included integrations:
-
-- `subconscious-code/install.sh` and `run.sh`
-- `claude-code/install.sh` and `run.sh`
-- `codex/install.sh`, `run.sh`, `hook.sh`, `hooks.json`, and `hooks-lib.sh`
-- `opencode/install.sh`, `run.sh`, and `subconscious-compaction.ts`
-- `cursor/install.sh`, `hook.sh`, and `hooks.json`
-- `copilot/install.sh`, `hook.sh`, and `hooks.json`
-- `pi/install.sh`, `run.sh`, and `subconscious-compaction.ts`
-- `deepseek-harness/run.sh`
-
-Each CLI-enabled entry in `agents/registry.json` points here with a `runbook`
-block. Persistent writes are merge/unmerge only: they never replace a user's
-`config.toml`, `opencode.json`, `models.json`, `hooks.json`, or VS Code
-provider list.
+Each directory here is one agent. Its `agent.json` is the only place that
+agent's data is written; the code reads it at runtime. `shared.json` lists the
+agents in menu order and holds what is truly shared: the packaged model list,
+the default gateway, model capabilities, and the settings every agent uses
+(`GATEWAY_URL`, `API_KEY`, `MODEL`, `MAX_CONCURRENT_SUBAGENTS`).
+
+| Agent | Launch | Setup |
+| --- | --- | --- |
+| `claude-code` | binary | `install.sh` (leftover status/uninstall) |
+| `codex` | `run.sh` | `install.sh` (hooks) |
+| `opencode` | binary | `install.sh` (leftover status/uninstall) |
+| `cursor` | none | `install.sh` (hooks) |
+| `copilot` | none | `install.sh` (provider and hooks) |
+| `pi` | `run.sh` | `install.sh` (provider and extensions) |
+| `deepseek-harness` | `run.sh` | none |
+
+## What `agent.json` holds and who reads it
+
+| Field | Read by |
+| --- | --- |
+| `id`, `command`, `aliases`, `name`, `description` | routing, `subc help`, the TUI menu |
+| `install` | the missing-agent message, agent help, and the upgrade warning (`minimum_version`); `{package}` fills in `commands` |
+| `runbook` | which script launches the agent (none means the binary is run directly) and which setup actions exist |
+| `help` | `subc <agent> help`; flags with a `help` text are added from `inputs` |
+| `sessions`, `launch.resume`, `launch.handoff` | `subc sessions resume` |
+| `launch.argv`, `launch.headless_argv`, `headless_stdin`, `headless_platforms` | every launch: subc builds the full argv and stdin from these |
+| `inputs` | profile settings and the TUI (`label`, `type`, `min`, `max`, `choices`), the new-profile template, launch flags (`flag`), and defaults (`default`, `aliases`, `keep_empty`) |
+| `env` | the env subc gives the agent: the first set `override`, otherwise `value` |
+| `config` | `cli-config` entries become `config_flag NAME=VALUE` (Codex `-c`) when `when` holds; other entries describe files the runbooks write |
+| `capabilities`, `prerequisites` | the harness manifest only |
+
+## Install data is display-only
+
+subc never installs an agent. When an agent's binary is missing, subc prints
+`install.commands` for the current OS and `install.url`, then exits with
+status 127. Windows never shows the Linux command. Rules for `install`, checked
+by `bin/agent-data.js` and `test/agent-install-policy.test.js`:
+
+- `url` is required: an `https://` link to the vendor's official install page.
+- `commands` is `null`, or an object keyed by `darwin`, `linux`, and `win32`.
+- A command is one the user can paste, such as `npm i -g {package}`. It never
+  pipes a downloaded script into a shell.
+
+Values may use `{baseUrl}`, `{baseUrlV1}`, `{apiKey}`, `{model}`, `{prompt}`,
+`{args}`, `{config}`, and `${NAME}` for another input or env entry.
+`subc harness-manifest --json` prints every agent file with `${NAME}` replaced
+by its default, so readers such as bench-runner parse JSON instead of these
+scripts.
+
+## The runbook contract
+
+subc starts a runbook as `bash run.sh ARGV...`, where `ARGV` is the agent's
+complete command line. The env already holds every input with its default,
+every `env` entry, `SUBC_MODEL_IDS` (launch model first, then the catalog),
+and `SUBC_VISION_MODELS`. A runbook does its own work, such as writing a
+temporary file, and ends with `subc_exec` from `lib.sh`, which replaces a
+`{tempFile}` placeholder in the template words and execs the agent. A runbook
+declares no defaults, flags, or argv of its own.
+
+Setup scripts (`install.sh`) get the same inputs and keep their own
+`install|status|uninstall` command line.
+
+## Adding or changing an agent
+
+1. Create `bin/runbook/<id>/agent.json` (copy the closest agent) and add the
+   id to `shared.json`.
+2. Add `run.sh` only if the launch must do work subc cannot express as data,
+   such as writing a file; otherwise leave `runbook.script` out.
+3. Run `npm test`. `test/agent-files.test.js` validates every agent file and
+   renders each launch template.
+
+To change a default, flag, env value, argv, or help text, edit the agent file.
+The launcher, profiles, help, Windows launcher, and manifest all read it. The
+contents of files a runbook writes (the Codex catalog, Pi's provider, the
+DeepSeek Harness overlay, Copilot's provider) live in that script, and on
+Windows in `bin/windows/launch.js` and `bin/windows/setup.js`, whose Codex
+`-c` list also differs from the one in `agent.json`.