Plan: Rename --agents flag to --targets

AGENTS.md

@@ -20,7 +20,7 @@ Project-specific guidance for AI coding agents working in this codebase.
 
 ## Commits
 
-- **Use conventional commits.** Format: `<type>: <description>` (e.g., `feat: add --agents flag`, `fix: dry-run skip lock write`, `docs: update CLI reference`, `test: add list --help tests`, `refactor: extract help into per-command functions`, `chore: remove generated license file`).
+- **Use conventional commits.** Format: `<type>: <description>` (e.g., `feat: add --targets flag`, `fix: dry-run skip lock write`, `docs: update CLI reference`, `test: add list --help tests`, `refactor: extract help into per-command functions`, `chore: remove generated license file`).
 
 ## File Size Limits
 

README.md

@@ -11,7 +11,7 @@ Requires Node.js 18+ (or Bun/Deno).
 
 <!-- agent-list:start -->
 
-Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](docs/supported-agents.md).
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](docs/supported-targets.md).
 
 <!-- agent-list:end -->
 
@@ -32,8 +32,8 @@ dotai solves this with **canonical authoring**: write a single `RULES.md`,
 `PROMPT.md`, or `AGENT.md` and dotai transpiles it into every target agent's
 native format automatically.
 
-- **Write once** — one canonical file fans out to all target agents
-- **40+ agents** — Copilot, Claude Code, Cursor, Windsurf, Cline, and more
+- **Write once** — one canonical file fans out to all targets
+- **40+ targets** — Copilot, Claude Code, Cursor, Windsurf, Cline, and more
 - **Team sharing** — `npx dotai add owner/repo` gives every teammate the same context
 - **No lock-in** — canonical files are plain markdown with YAML frontmatter
 
@@ -50,8 +50,8 @@ npx dotai                   # run without installing
 # Add context from a GitHub repo
 npx dotai add owner/repo
 
-# Target specific coding agents
-npx dotai add owner/repo --agents copilot,claude,cursor
+# Limit to specific targets
+npx dotai add owner/repo --targets copilot,claude,cursor
 
 # Install specific rules or skills
 npx dotai add owner/repo --rule code-style --skill db-migrate
@@ -62,12 +62,12 @@ repo and transpiles them for your selected targets.
 
 ## What dotai installs
 
-| Layer   | Canonical file | Install behavior                     |
-| ------- | -------------- | ------------------------------------ |
-| Skills  | `SKILL.md`     | Passthrough (symlink or copy)        |
-| Rules   | `RULES.md`     | Transpile per target agent           |
-| Prompts | `PROMPT.md`    | Transpile per supported target agent |
-| Agents  | `AGENT.md`     | Transpile per supported target agent |
+| Layer   | Canonical file | Install behavior               |
+| ------- | -------------- | ------------------------------ |
+| Skills  | `SKILL.md`     | Passthrough (symlink or copy)  |
+| Rules   | `RULES.md`     | Transpile per target           |
+| Prompts | `PROMPT.md`    | Transpile per supported target |
+| Agents  | `AGENT.md`     | Transpile per supported target |
 
 See [Source repo layout](docs/cli-reference.md#source-repo-layout) for where to place these files in your repo so dotai discovers them.
 
@@ -118,18 +118,18 @@ npx dotai add ./my-local-context                        # local path
 
 </details>
 
-Skill installs target [41 agents](docs/supported-agents.md). **GitHub Copilot**, **Claude Code**, and **OpenCode** are actively tested; other agents follow the [Agent Skills specification](https://agentskills.io) but are not individually verified.
+Skill installs target [41 targets](docs/supported-targets.md). **GitHub Copilot**, **Claude Code**, and **OpenCode** are actively tested; other targets follow the [Agent Skills specification](https://agentskills.io) but are not individually verified.
 
 ## Reference
 
 - [CLI Reference](docs/cli-reference.md) — all commands, flags, options, and authoring format
-- [Supported Agents](docs/supported-agents.md) — full list of skill install targets
+- [Supported Targets](docs/supported-targets.md) — full list of skill install targets
 
 ## Fork Lineage
 
 dotai started as a fork of [vercel-labs/skills](https://github.com/vercel-labs/skills) / [skills.sh](https://skills.sh).
 The inherited skills install pipeline remains first-class. dotai extends it with
-transpilation of rules, prompts, and agent definitions to multiple target agents.
+transpilation of rules, prompts, and agent definitions to multiple targets.
 
 ## Acknowledgements
 

docs/cli-reference.md

@@ -4,47 +4,47 @@ Full option tables, examples, and authoring format for `dotai`. For a quick over
 
 ## add command options
 
-| Option                      | Description                                                                  |
-| --------------------------- | ---------------------------------------------------------------------------- |
-| `-g, --global`              | Install to user directory instead of project                                 |
-| `-t, --type <types...>`     | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
-| `-s, --skill <skills...>`   | Install specific skills by name (repeatable; supports `'*'`)                 |
-| `-r, --rule <rules...>`     | Install specific canonical rules by name (repeatable)                        |
-| `-p, --prompt <prompts...>` | Install specific canonical prompts by name (repeatable)                      |
-| `--custom-agent <names...>` | Install specific canonical custom agents by name (repeatable)                |
-| `-a, --agents <agents...>`  | Target agents (comma-separated; use `'*'` for all)                           |
-| `--copy`                    | Copy files instead of symlinking skills                                      |
-| `--dry-run`                 | Preview writes without making changes                                        |
-| `--force`                   | Overwrite conflicting managed/unmanaged outputs                              |
-| `--append`                  | Append rules to `AGENTS.md`/`CLAUDE.md` instead of per-rule files            |
-| `--gitignore`               | Add transpiled output paths to `.gitignore` (managed section)                |
-| `--full-depth`              | Search all subdirectories even when a root `SKILL.md` exists                 |
-| `-y, --yes`                 | Skip confirmation prompts                                                    |
-| `--all`                     | Shorthand for `--skill '*' --agents '*' -y`                                  |
-
-> **`--agents`:** A single flag for both skill install targets and transpilation targets. For skills, any of the 41 supported agents (e.g., `--agents cursor,claude-code`). For rules, prompts, and agents, the 6 transpilation targets: copilot, claude, cursor, windsurf, cline, opencode. When omitted, all detected agents are used for skills and all 6 transpilation targets for rules/prompts/agents.
+| Option                       | Description                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `-g, --global`               | Install to user directory instead of project                                 |
+| `-t, --type <types...>`      | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
+| `-s, --skill <skills...>`    | Install specific skills by name (repeatable; supports `'*'`)                 |
+| `-r, --rule <rules...>`      | Install specific canonical rules by name (repeatable)                        |
+| `-p, --prompt <prompts...>`  | Install specific canonical prompts by name (repeatable)                      |
+| `--custom-agent <names...>`  | Install specific canonical custom agents by name (repeatable)                |
+| `-a, --targets <targets...>` | Targets (comma-separated; use `'*'` for all)                                 |
+| `--copy`                     | Copy files instead of symlinking skills                                      |
+| `--dry-run`                  | Preview writes without making changes                                        |
+| `--force`                    | Overwrite conflicting managed/unmanaged outputs                              |
+| `--append`                   | Append rules to `AGENTS.md`/`CLAUDE.md` instead of per-rule files            |
+| `--gitignore`                | Add transpiled output paths to `.gitignore` (managed section)                |
+| `--full-depth`               | Search all subdirectories even when a root `SKILL.md` exists                 |
+| `-y, --yes`                  | Skip confirmation prompts                                                    |
+| `--all`                      | Shorthand for `--skill '*' --targets '*' -y`                                 |
+
+> **`--targets`:** A single flag for both skill install targets and transpilation targets. For skills, any of the 41 supported targets (e.g., `--targets cursor,claude-code`). For rules, prompts, and agents, the 6 transpilation targets: copilot, claude, cursor, windsurf, cline, opencode. When omitted, all detected targets are used for skills and all 6 transpilation targets for rules/prompts/agents.
 
 > **Zero-flag mode:** Running `dotai add owner/repo` with no type-specific flags discovers all content types (skills, rules, prompts, agents) and presents an interactive grouped selection. Use `dotai find owner/repo` for a non-interactive preview.
 
-> **`--append`:** Instead of writing individual rule files (e.g., `.github/instructions/code-style.instructions.md`), rules are appended as marker-delimited sections into `AGENTS.md` (Copilot) and `CLAUDE.md` (Claude Code). Useful for projects that prefer a single monolithic instruction file. Only applies to Copilot and Claude Code targets; other agents always get individual files.
+> **`--append`:** Instead of writing individual rule files (e.g., `.github/instructions/code-style.instructions.md`), rules are appended as marker-delimited sections into `AGENTS.md` (Copilot) and `CLAUDE.md` (Claude Code). Useful for projects that prefer a single monolithic instruction file. Only applies to Copilot and Claude Code targets; other targets always get individual files.
 
 > **`--gitignore`:** Adds transpiled output file paths to a managed `# dotai:start` / `# dotai:end` section in `.gitignore`. Use when transpiled outputs should not be committed — only the canonical source files and `.dotai-lock.json` are checked in, and teammates run `dotai add` to regenerate outputs locally.
 
 <!-- agent-names:start -->
 
-Supported agent aliases include values such as `claude-code` and `codex`. See [Supported Agents](supported-agents.md).
+Supported target aliases include values such as `claude-code` and `codex`. See [Supported Targets](supported-targets.md).
 
 <!-- agent-names:end -->
 
 ## remove command options
 
-| Option                     | Description                                                                  |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| `-g, --global`             | Remove from global scope                                                     |
-| `-a, --agents <agents...>` | Remove from specific agents (use `'*'` for all agents)                       |
-| `-t, --type <types...>`    | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
-| `-y, --yes`                | Skip confirmation prompts                                                    |
-| `--all`                    | Remove all installed items                                                   |
+| Option                       | Description                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `-g, --global`               | Remove from global scope                                                     |
+| `-a, --targets <targets...>` | Remove from specific targets (use `'*'` for all targets)                     |
+| `-t, --type <types...>`      | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
+| `-y, --yes`                  | Skip confirmation prompts                                                    |
+| `--all`                      | Remove all installed items                                                   |
 
 ## find command
 
@@ -145,11 +145,11 @@ Convert native agent-specific rule files into canonical `RULES.md` format.
 
 ## list command options
 
-| Option                     | Description                                                                  |
-| -------------------------- | ---------------------------------------------------------------------------- |
-| `-g, --global`             | List global context (default: project)                                       |
-| `-a, --agents <agents...>` | Filter by specific agents                                                    |
-| `-t, --type <types...>`    | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
+| Option                       | Description                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `-g, --global`               | List global context (default: project)                                       |
+| `-a, --targets <targets...>` | Filter by specific targets                                                   |
+| `-t, --type <types...>`      | Filter by context type (`skill`, `rule`, `prompt`, `agent`; comma-separated) |
 
 ## Installation Scope
 
@@ -185,8 +185,8 @@ npx dotai add owner/repo --prompt review-code --rule code-style
 # Install a custom agent
 npx dotai add owner/repo --custom-agent architect
 
-# Install agents targeting specific transpilation agents
-npx dotai add owner/repo --custom-agent architect --agents copilot,claude
+# Install agents targeting specific transpilation targets
+npx dotai add owner/repo --custom-agent architect --targets copilot,claude
 
 # Force replace an existing unmanaged target file
 npx dotai add owner/repo --rule code-style --force
@@ -198,7 +198,7 @@ npx dotai add owner/repo --rule code-style --append
 npx dotai add owner/repo --rule code-style --gitignore
 
 # CI-friendly non-interactive install
-npx dotai add owner/repo --all --agents copilot,claude,cursor,windsurf,cline,opencode -y
+npx dotai add owner/repo --all --targets copilot,claude,cursor,windsurf,cline,opencode -y
 ```
 
 ## Team Sharing
@@ -215,16 +215,16 @@ npx dotai add owner/repo --prompt review-code -y
 # Share all rules and prompts from a repo
 npx dotai add owner/repo --type rule,prompt -y
 
-# CI-friendly: install everything, skip prompts, target specific agents
-npx dotai add owner/repo --all --agents copilot,claude,cursor -y
+# CI-friendly: install everything, skip prompts, limit to specific targets
+npx dotai add owner/repo --all --targets copilot,claude,cursor -y
 ```
 
 ## How transpilation works
 
 When you write a canonical file (`RULES.md`, `PROMPT.md`, `AGENT.md`), dotai splits it into two parts:
 
 - **Frontmatter** (metadata like `activation`, `globs`, `model`, `tools`) is **mapped per-agent** into each target's native format.
-- **Body** (everything after the frontmatter) is **passed verbatim** to all target agents. No content is filtered, adapted, or rewritten.
+- **Body** (everything after the frontmatter) is **passed verbatim** to all targets. No content is filtered, adapted, or rewritten.
 
 This means canonical bodies should contain **agent-agnostic instructions** — describe _what_ to do, not _how_ to do it with a specific agent's tools. For example, "run the tests before committing" is portable; "use the Bash tool to run tests" is Claude Code-specific and will land unchanged in Cursor, Windsurf, Copilot, and Cline where it won't make sense.
 
@@ -241,7 +241,7 @@ dotai also discovers **native agent-specific files** in source repos and passes
 | Windsurf       | `.windsurf/rules/*.md`                   | `.windsurf/workflows/*.md`    | —                           |
 | Cline          | `.clinerules/*.md`                       | —                             | —                           |
 
-A single source repo can contain both canonical and native files. Canonical files fan out to all target agents; native files go only to their matching agent.
+A single source repo can contain both canonical and native files. Canonical files fan out to all targets; native files go only to their matching agent.
 
 | Use case                                        | Approach              |
 | ----------------------------------------------- | --------------------- |

docs/supported-agents.md → docs/supported-targets.md

@@ -1,15 +1,15 @@
-# Supported Agents
+# Supported Targets
 
-dotai installs `SKILL.md` files into the config directories of 41 agents. **GitHub Copilot**, **Claude Code**, and **OpenCode** are actively tested; other agents follow the [Agent Skills specification](https://agentskills.io) but are not individually verified.
+dotai installs `SKILL.md` files into the config directories of 41 targets. **GitHub Copilot**, **Claude Code**, and **OpenCode** are actively tested; other targets follow the [Agent Skills specification](https://agentskills.io) but are not individually verified.
 
 Rules, prompts, and agent definitions use a separate set of [transpilation targets](../README.md#supported-targets) (Copilot, Claude Code, Cursor, Windsurf, Cline, OpenCode). OpenCode is both a skill install target and a transpilation target.
 
 <details>
-<summary>Full agent table</summary>
+<summary>Full target table</summary>
 
 <!-- supported-agents:start -->
 
-| Agent                                 | `--agents`                               | Project Path           | Global Path                     |
+| Target                                | `--targets`                              | Project Path           | Global Path                     |
 | ------------------------------------- | ---------------------------------------- | ---------------------- | ------------------------------- |
 | Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/`      | `~/.config/agents/skills/`      |
 | Antigravity                           | `antigravity`                            | `.agent/skills/`       | `~/.gemini/antigravity/skills/` |

scripts/sync-agents.ts

@@ -7,17 +7,17 @@ import { agents } from '../src/agents.ts';
 
 const ROOT = join(import.meta.dirname, '..');
 const README_PATH = join(ROOT, 'README.md');
-const AGENTS_DOC_PATH = join(ROOT, 'docs', 'supported-agents.md');
+const AGENTS_DOC_PATH = join(ROOT, 'docs', 'supported-targets.md');
 const PACKAGE_PATH = join(ROOT, 'package.json');
 
 function generateAgentList(): string {
   const agentList = Object.values(agents);
   const count = agentList.length;
-  return `Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [${count - 4} more](docs/supported-agents.md).`;
+  return `Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [${count - 4} more](docs/supported-targets.md).`;
 }
 
 function generateAgentNames(): string {
-  return 'Target specific agents (e.g., `claude-code`, `codex`). See [Supported Agents](docs/supported-agents.md)';
+  return 'Limit to specific targets (e.g., `claude-code`, `codex`). See [Supported Targets](docs/supported-targets.md)';
 }
 
 function generateAvailableAgentsTable(): string {
@@ -56,7 +56,7 @@ function generateAvailableAgentsTable(): string {
     return `| ${names} | ${keys} | \`${group.skillsDir}/\` | ${globalPath} |`;
   });
   return [
-    '| Agent | `--agent` | Project Path | Global Path |',
+    '| Target | `--targets` | Project Path | Global Path |',
     '|-------|-----------|--------------|-------------|',
     ...rows,
   ].join('\n');
@@ -112,7 +112,7 @@ function main() {
   agentsDoc = replaceSection(agentsDoc, 'skill-discovery', generateSkillDiscoveryPaths());
 
   writeFileSync(AGENTS_DOC_PATH, agentsDoc);
-  console.log('docs/supported-agents.md updated');
+  console.log('docs/supported-targets.md updated');
 
   const pkg = JSON.parse(readFileSync(PACKAGE_PATH, 'utf-8'));
   pkg.keywords = generateKeywords();