getsentry · gricha · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -15,14 +15,17 @@ See `specs/SPEC.md` for the full design.
 ```
 src/
 ├── index.ts              # Library entry point
+├── scope.ts              # Project/user scope resolution
 ├── cli/
 │   ├── index.ts          # CLI entry point, command routing
-│   └── commands/         # init, install, add, remove, update, sync, list
+│   └── commands/         # init, install, add, remove, update, sync, list, mcp
+├── agents/               # Agent definitions, MCP/hook config writers
 ├── config/               # agents.toml schema, loader, writer
 ├── lockfile/             # agents.lock schema, loader, writer
 ├── skills/               # SKILL.md loader, discovery, resolver
 ├── sources/              # git.ts, local.ts, cache.ts
 ├── symlinks/             # Symlink creation/management
+├── trust/                # Trust policy validation
 ├── gitignore/            # .agents/.gitignore generation
 └── utils/                # exec.ts, hash.ts, fs.ts
 ```
@@ -53,6 +56,10 @@ New functionality requires tests, but only tests that are functionally additive.
 - Add regression tests for bugs
 - Mock external services, use real-world fixtures
 
+## Documentation
+
+When changes affect CLI behavior, command interfaces, or user-facing semantics (flags, error messages, default behavior), update the relevant documentation: `README.md`, `specs/SPEC.md`, `docs/public/llms.txt`, and `--help` output. Code and docs ship together.
+
 ## Verifying Changes
 
 ```bash

diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ A package manager for `.agents` directories. Declare agent skill dependencies in
 
 **Shareable.** Skills are just directories with a `SKILL.md`. Host them in any git repo, discover them automatically, install with one command.
 
-**Multi-agent.** Configure Claude, Cursor, Codex, VS Code, and OpenCode from a single `agents.toml` -- skills, MCP servers, and hooks.
+**Multi-agent.** Configure Claude, Cursor, Codex, VS Code, OpenCode, and Pi from a single `agents.toml` -- skills, MCP servers, and hooks.
 
 ## Quick Start
 
@@ -19,7 +19,10 @@ A package manager for `.agents` directories. Declare agent skill dependencies in
 npx @sentry/dotagents init
 
 # Add a skill from a GitHub repo
-npx @sentry/dotagents add getsentry/skills --name find-bugs
+npx @sentry/dotagents add getsentry/skills find-bugs
+
+# Add multiple skills at once
+npx @sentry/dotagents add getsentry/skills find-bugs code-review commit
 
 # Or add all skills from a repo
 npx @sentry/dotagents add getsentry/skills --all
@@ -47,12 +50,13 @@ And a lockfile (`agents.lock`) pinning the exact commit and integrity hash.
 | Command | Description |
 |---------|-------------|
 | `init` | Create `agents.toml` and `.agents/skills/` |
-| `add <source>` | Add a skill dependency |
+| `add <source> [skills...]` | Add skill dependencies |
 | `remove <name>` | Remove a skill |
 | `install` | Install all dependencies from `agents.toml` |
 | `update [name]` | Update skills to latest versions |
 | `list` | Show installed skills and their status |
 | `sync` | Reconcile gitignore, symlinks, and verify state |
+| `mcp` | Manage MCP server declarations |
 
 All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project.
 
@@ -75,10 +79,31 @@ Use `--frozen` in CI to fail if the lockfile is missing or out of sync. Use `--f
 ### add
 
 ```bash
-dotagents add <source> [--name <name>] [--ref <ref>] [--all]
+dotagents add <source> [<skill>...] [--skill <name>...] [--ref <ref>] [--all]
+```
+
+Add one or more skills and install them. Specify skill names as positional arguments or with `--skill` flags.
+
+```bash
+# Add a single skill
+dotagents add getsentry/skills find-bugs
+
+# Add multiple skills
+dotagents add getsentry/skills find-bugs code-review commit
+
+# Equivalent using --skill flags
+dotagents add getsentry/skills --skill find-bugs --skill code-review
+
+# Pin to a ref
+dotagents add getsentry/skills find-bugs --ref v1.0.0
+
+# Add all skills as a wildcard entry
+dotagents add getsentry/skills --all
 ```
 
-Add a skill and install it. When a repo has one skill, it's added automatically. When multiple are found, use `--name` to pick one or `--all` to add them all as a wildcard entry.
+When a repo has one skill, it's added automatically. When multiple are found and no names are given, interactive mode shows a picker.
+
+When adding multiple skills, any that already exist in `agents.toml` are skipped with a warning. The rest are added normally.
 
 ### remove
 
@@ -112,6 +137,24 @@ dotagents sync
 
 Adopts orphaned skills, regenerates gitignore, verifies integrity, repairs symlinks and configs.
 
+### mcp
+
+Manage MCP server declarations from the CLI.
+
+```bash
+# Add a stdio server
+dotagents mcp add github --command npx --args -y @modelcontextprotocol/server-github --env GITHUB_TOKEN
+
+# Add an HTTP server
+dotagents mcp add remote-api --url https://mcp.example.com/sse
+
+# Remove a server
+dotagents mcp remove github
+
+# List declared servers
+dotagents mcp list [--json]
+```
+
 ## Source Formats
 
 ```toml
@@ -163,16 +206,7 @@ agents = ["claude", "cursor"]
 
 ### Pi
 
-[Pi](https://github.com/badlogic/pi-mono) discovers skills from `.pi/skills/`. It is not listed as an `agents` target, so instead add a symlink target to your `agents.toml`:
-
-```toml
-[symlinks]
-targets = [".pi"]
-```
-
-After running `dotagents install`, Pi will read skills from `.pi/skills/ -> .agents/skills/`.
-
-Pi does not use dotagents for MCP configuration. If you use an MCP extension with Pi, configure it separately via `.pi/mcp.json`.
+[Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. No agent target or symlink configuration is needed -- install skills with dotagents and Pi picks them up automatically.
 
 ## MCP Servers
 
@@ -186,14 +220,16 @@ command = "npx"
 args = ["-y", "@modelcontextprotocol/server-github"]
 env = ["GITHUB_TOKEN"]
 
-# HTTP transport (OAuth)
+# HTTP transport
 [[mcp]]
 name = "remote-api"
 url = "https://mcp.example.com/sse"
 ```
 
 Each server uses either `command` (stdio) or `url` (HTTP), not both.
 
+You can also manage MCP servers from the CLI with `dotagents mcp add` and `dotagents mcp remove`.
+
 ## Hooks
 
 Declare hooks once and dotagents writes the correct hook config for each agent that supports them (Claude, Cursor, VS Code).

diff --git a/docs/public/llms.txt b/docs/public/llms.txt
@@ -14,7 +14,10 @@ Run without installing: `npx @sentry/dotagents <command>`
 npx @sentry/dotagents init
 
 # Add a single skill from GitHub
-npx @sentry/dotagents add getsentry/skills --name find-bugs
+npx @sentry/dotagents add getsentry/skills find-bugs
+
+# Add multiple skills at once
+npx @sentry/dotagents add getsentry/skills find-bugs code-review commit
 
 # Add all skills from a repo
 npx @sentry/dotagents add getsentry/skills --all
@@ -247,18 +250,21 @@ Install all dependencies from `agents.toml`. Resolves sources, copies skills, wr
 ### add
 
 ```
-dotagents add <source> [--name <name>] [--ref <ref>] [--all]
+dotagents add <source> [<skill>...] [--skill <name>...] [--ref <ref>] [--all]
 ```
 
-Add a skill dependency and install it. Auto-discovers skills in the repo.
+Add one or more skill dependencies and install them. Specify skill names as positional arguments or with `--skill` flags.
 
 | Flag | Description |
 |------|-------------|
-| `--name <name>` | Specify which skill to add (alias: `--skill`) |
+| `<skill>...` | Positional skill names to add |
+| `--skill <name>` | Specify which skill(s) to add (repeatable, alias: `--name`) |
 | `--ref <ref>` | Pin to a specific tag, branch, or commit |
 | `--all` | Add all skills from the source as a wildcard entry (`name = "*"`) |
 
-When a repo has one skill, it is added automatically. When multiple skills are found without `--name` or `--all`, they are listed with instructions to pick one.
+When a repo has one skill, it is added automatically. When multiple skills are found without names or `--all`, interactive mode shows a picker (TTY) or lists them (non-TTY).
+
+When adding multiple skills, any that already exist in `agents.toml` are skipped with a warning. The command only fails if all specified skills already exist. Positional names and `--skill` flags cannot be mixed.
 
 ### remove
 
@@ -344,7 +350,9 @@ Skills from wildcard entries are marked with a wildcard indicator.
 | `vscode` | VS Code Copilot | `.vscode` | (reads `.agents/skills/` natively) | `.vscode/mcp.json` | `.claude/settings.json` |
 | `opencode` | OpenCode | `.claude` | (reads `.agents/skills/` natively) | `opencode.json` | Not supported |
 
-Claude and Cursor use symlinks from their config directory to `.agents/skills/`. Codex, VS Code, and OpenCode read `.agents/skills/` directly.
+Claude and Cursor use symlinks from their config directory to `.agents/skills/`. Codex, VS Code, OpenCode, and Pi read `.agents/skills/` directly.
+
+[Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. No agent target or symlink configuration needed.
 
 ## Scopes
 

diff --git a/specs/SPEC.md b/specs/SPEC.md
@@ -149,6 +149,16 @@ MCP server declarations. Each entry defines an MCP server that dotagents will co
 
 A server must have either `command` (stdio) or `url` (HTTP), but not both.
 
+#### `[[hooks]]`
+
+Hook declarations. Each entry defines a hook that dotagents will configure for agents that support hooks (Claude, Cursor, VS Code).
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `event` | Yes | Hook event: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, or `Stop`. |
+| `matcher` | No | Tool name to match (e.g. `Bash`). Only for `PreToolUse` and `PostToolUse`. |
+| `command` | Yes | Shell command to execute when the hook fires. |
+
 #### Supported Agents
 
 | ID | Tool | Config Dir | MCP File | MCP Format |
@@ -344,34 +354,43 @@ dotagents install [--frozen] [--force]
 
 ### `dotagents add <specifier>`
 
-Add a skill dependency.
+Add one or more skill dependencies.
 
 ```
-dotagents add <specifier> [--ref <ref>] [--name <name>]
+dotagents add <specifier> [<skill>...] [--skill <name>...] [--ref <ref>] [--all]
 ```
 
 **Examples:**
 ```bash
-dotagents add getsentry/skills --name find-bugs
-dotagents add getsentry/warden --name warden-skill --ref v1.0.0
+dotagents add getsentry/skills find-bugs
+dotagents add getsentry/skills find-bugs code-review commit
+dotagents add getsentry/skills --skill find-bugs --skill code-review
+dotagents add getsentry/warden warden-skill --ref v1.0.0
+dotagents add getsentry/skills --all
 dotagents add path:../shared-skills/my-skill
 dotagents add myorg/single-skill-repo   # auto-detects if repo has one skill
 ```
 
 **Behavior:**
-1. Parse specifier to determine source type
-2. Clone/fetch repo to cache
-3. Discover skill(s) in the repo
-   - If `--name` is given, look for that specific skill
+1. Validate source against trust policy before any network operations
+2. Parse specifier to determine source type
+3. Clone/fetch repo to cache
+4. Discover skill(s) in the repo
+   - If skill names are given (positional or `--skill`), verify each exists in the source
+   - If `--all`, add a wildcard entry for the entire source
    - If repo has exactly one skill, use it automatically
-   - If repo has multiple skills and no `--name`, list them and ask user to pick
-4. Add `[[skills]]` entry to `agents.toml`
-5. Run install to fetch and place the skill
-6. Update `agents.lock`
+   - If repo has multiple skills and no names given, show interactive picker (TTY) or list them (non-TTY)
+5. When adding multiple skills, skip any that already exist in `agents.toml` (with a warning). Error only if all specified skills already exist.
+6. Add `[[skills]]` entry to `agents.toml` for each new skill
+7. Run install to fetch and place the skills
+8. Update `agents.lock`
 
 **Flags:**
 - `--ref <ref>`: Pin to a specific tag/branch/commit
-- `--name <name>`: Specify which skill to add from a multi-skill repo
+- `--skill <name>` (repeatable): Specify which skill(s) to add. Alternative to positional arguments.
+- `--all`: Add all skills from the source as a wildcard entry
+
+Positional skill names and `--skill` flags cannot be mixed.
 
 ### `dotagents remove <name>`
 
@@ -414,12 +433,29 @@ dotagents sync
 ```
 
 **Behavior:**
-1. Regenerate `.agents/.gitignore`
-2. Create/verify/repair symlinks (legacy and agent-specific)
-3. Warn if orphaned skills exist (installed but not in agents.toml)
-4. Warn if declared skills are missing (in agents.toml but not installed)
-5. Verify integrity hashes, warn on local modifications
+1. Adopt orphaned skills (installed but not in `agents.toml`) into config
+2. Regenerate `.agents/.gitignore`
+3. Check for missing skills (in `agents.toml` but not installed)
+4. Verify integrity hashes, warn on local modifications
+5. Create/verify/repair symlinks
 6. Verify and repair MCP config files for declared agents
+7. Verify and repair hook config files for declared agents
+
+### `dotagents mcp`
+
+Manage MCP server declarations.
+
+```
+dotagents mcp add <name> --command <cmd> [--args <a>...] [--env <VAR>...]
+dotagents mcp add <name> --url <url> [--header <Key:Value>...] [--env <VAR>...]
+dotagents mcp remove <name>
+dotagents mcp list [--json]
+```
+
+**Behavior:**
+- `add`: Append an `[[mcp]]` entry to `agents.toml` and run install to generate agent configs. Each server uses either `--command` (stdio) or `--url` (HTTP), not both.
+- `remove`: Remove the named `[[mcp]]` entry from `agents.toml` and run install.
+- `list`: Show declared MCP servers with transport type, target, and environment variables.
 
 ### `dotagents list`
 
@@ -588,6 +624,7 @@ dotagents/
     SPEC.md                # This file
   src/
     index.ts               # Library entry point (re-exports all modules)
+    scope.ts               # Project/user scope resolution
     cli/
       index.ts             # CLI entry point, command routing
       commands/
@@ -598,15 +635,20 @@ dotagents/
         update.ts
         sync.ts
         list.ts
+        mcp.ts
     agents/
       types.ts             # McpDeclaration, AgentDefinition interfaces
       registry.ts          # Agent registry (claude, cursor, codex, vscode, opencode)
+      definitions/         # Per-agent definitions (claude.ts, cursor.ts, etc.)
       mcp-writer.ts        # MCP config file generation per agent
+      hook-writer.ts       # Hook config file generation per agent
+      paths.ts             # Agent config path resolution
+      errors.ts            # Agent-specific error types
       index.ts             # Re-exports
     config/
       schema.ts            # Zod schemas for agents.toml
       loader.ts            # TOML parse + validate
-      writer.ts            # TOML modification (add/remove skills)
+      writer.ts            # TOML modification (add/remove skills, MCP, hooks)
       index.ts             # Re-exports
     lockfile/
       schema.ts            # Zod schemas for agents.lock
@@ -626,6 +668,9 @@ dotagents/
     symlinks/
       manager.ts           # Create/verify/repair symlinks, directory migration
       index.ts             # Re-exports
+    trust/
+      validator.ts         # Trust policy enforcement
+      index.ts             # Re-exports
     gitignore/
       writer.ts            # Generate .agents/.gitignore
       index.ts             # Re-exports
@@ -645,6 +690,7 @@ dotagents/
 | `smol-toml` | TOML parsing and serialization |
 | `zod` | Runtime schema validation (v4, imported as `zod/v4`) |
 | `chalk` | Terminal colors |
+| `@clack/prompts` | Interactive CLI prompts |
 
 ### Dev