argsbarg 6.1.10 → 6.2.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.2.0] - 2026-07-30
+
+### Changed
+
+- **Breaking: two `argsbarg create` templates** — default `cli` template (`examples/full-example`) is CLI-centric (MCP, HTTP, configure, skills; no schemagen). Schema-first template (`examples/full-example-json`) keeps `@sg` schemagen, `inputSchema`/`outputSchema`, REST CRUD, and in-memory SQLite. Interactive create shows an A/B template picker; `--template cli|json` for non-interactive use. `create-identity.ts` records `template` for `--check` drift detection.
+- **Experimental: agent skill install** — single opt-in target via `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` (no per-host skill targets). Brew `post_install` sync installs the skill when enabled. Removed `configure.agentIntegration` and per-host skill keys (`cursorSkill`, etc.).
+- **Experimental: .agents protocol–only agent install** — MCP configure install writes only `~/.agents/mcp.json` when `mcpServer.enabled` (included in `configure --sync` automatically, parallel to `skill.enabled`). Removed vendor MCP auto-install (Cursor, Claude, Codex, OpenCode, OpenClaw, ChatGPT). Removed `configure.targets.*Mcp`; use `mcpServer.enabled`. Skill bundle adds protocol `skill.md` (+ `SKILL.md` compatibility copy). Docs and generated `docs mcp` document manual Cursor/Claude/Desktop MCP setup and Claude Code skill symlink.
+
 ## [6.1.10] - 2026-07-29
 
 ### Changed
@@ -885,7 +893,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.10...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.2.0...HEAD
+[6.2.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.2.0
 [6.1.10]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.10
 [6.1.9]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.9
 [6.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.8

package/README.md

@@ -52,9 +52,23 @@ $ myapp http
 import { Cli, type CliProgram, CliOptionKind } from "argsbarg";
 
 const program = {
-  key: "helloapp",
-  version: "1.0.0",
   description: "Tiny demo.",
+  handler: async (ctx) => {
+    const name = ctx.args[0] ?? "world";
+    if (ctx.hasFlag("verbose")) { 
+      console.log("verbose mode"); 
+    }
+    console.log(`hello ${name}`);
+  },
+  key: "helloapp",
+  options: [
+    {
+      name: "verbose",
+      description: "Enable extra logging.",
+      kind: CliOptionKind.Presence,
+      shortName: "v",
+    },
+  ],
   positionals: [
     {
       name: "name",
@@ -64,21 +78,7 @@ const program = {
       argMax: 1,
     },
   ],
-  options: [
-    {
-      name: "verbose",
-      description: "Enable extra logging.",
-      kind: CliOptionKind.Presence,
-      shortName: "v",
-    },
-  ],
-  handler: async (ctx) => {
-    const name = ctx.args[0] ?? "world";
-    if (ctx.hasFlag("verbose")) { 
-      console.log("verbose mode"); 
-    }
-    console.log(`hello ${name}`);
-  },
+  version: "1.0.0",
 } satisfies CliProgram;
 
 const cli = new Cli(program);
@@ -170,11 +170,11 @@ Nested command paths map directly to standard REST paths (e.g., `v1 invoices ren
 
 ```typescript
 const cli = {
-  key: "myapp",
-  version: "1.0.0",
+  commands: [/* ... */],
   description: "My service.",
   httpServer: { enabled: true, port: 3000 },
-  commands: [/* ... */],
+  key: "myapp",
+  version: "1.0.0",
 } satisfies CliProgram;
 ```
 
@@ -284,19 +284,20 @@ Check the `examples/` directory for full working scripts:
 
 | Example               | File                     | Shows                                                                                             |
 | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
-| `ArgsBargMinimal`     | `examples/minimal.ts`    | String + presence flags, `MissingOrUnknown` fallback.                                             |
+| `ArgsBargMinimal`     | `examples/minimal.ts`    | Smallest embeddable CLI (not a copy template).                                                    |
 | `ArgsBargNested`      | `examples/nested.ts`     | Nested command tree, positional tails, async handlers.                                            |
 | `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                        |
-| `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
+| `ArgsBargFullExample` | `examples/full-example/` | **Default copy template:** all builtins, Homebrew justfile; options/flags only (no schemagen). |
+| `ArgsBargFullExampleJson` | `examples/full-example-json/` | **Schema-first copy template:** `@sg`, `inputSchema`/`outputSchema`, REST CRUD, SQLite. |
 
 
 Examples ship in the npm package under `node_modules/argsbarg/examples/`.
 
 ## Bootstrap a new CLI
 
-Copy the shipped `examples/full-example` template into a new directory:
+Copy a shipped template into a new directory (`cli` default, or `json` for schema-first):
 
-Interactive (TTY):
+Interactive (TTY) — pick template A/B, then key and release repo:
 
 ```bash
 bunx argsbarg create my-cli
@@ -306,12 +307,21 @@ Non-interactive:
 
 ```bash
 bunx argsbarg create my-cli \
+  --template cli \
   --key my-cli --release-repo org/my-cli --yes
 ```
 
+Schema-first (`@sg`, JSON schemas, REST CRUD demo):
+
+```bash
+bunx argsbarg create my-api \
+  --template json \
+  --key my-api --release-repo org/my-api --yes
+```
+
 Edit `scripts/create-identity.ts` in the new repo to set `desc` (used by `program.description` and the Homebrew formula).
 
-`create` copies the template (including `.cursor/rules/cli-program.mdc`), substitutes `{key}` / `{tap}` / `{releaseRepo}` placeholders in `README.md` and other files, runs `bun install`, schemagen, `bun test`, and `git init` + Initial commit when appropriate.
+`create` copies the template (including `.cursor/rules/cli-program.mdc`), substitutes `{key}` / `{tap}` / `{releaseRepo}` placeholders, runs `bun install`, `argsbarg schemagen` (json template only), `bun test`, and `git init` + Initial commit when appropriate.
 
 **Git bootstrap:** skipped when the target already has a `.git` directory, or when the target sits inside an existing git work tree (monorepo subfolder). Standalone new directories get an `Initial commit`.
 
@@ -319,24 +329,16 @@ Verify an existing tree: `bunx argsbarg create --check .`
 
 To refresh Cursor rules in an existing consumer: `bun scripts/merge-cli-program-rule.ts .` and `bun scripts/merge-code-rule.ts .` from an argsbarg checkout (or pass the npm package path to the template).
 
-### What the full-example template includes
+### What the copy templates include
 
+Both templates ship all builtins (`completion`, `version`, `configure`, `docs`, `mcp`, `http`), Homebrew `justfile` + formula scripts, and `.cursor/rules/`.
 
-| Area                  | Files / wiring                                                                           |
-| --------------------- | ---------------------------------------------------------------------------------------- |
-| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`       |
-| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`          |
-| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`          |
-| Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
-| Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                       |
-| MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled   |
-| Package import        | `from "argsbarg"` (not relative to argsbarg `src/`)                                      |
-| Homebrew distribution | `scripts/formula-shared.ts`, `scripts/dev-formula.ts`, `Formula/`, `justfile`            |
-| Dev tooling           | Biome (`just format` / `just lint`), TypeScript, colocated tests                         |
-| Cursor rules          | `.cursor/rules/cli-program.mdc`, `.cursor/rules/code.mdc`                                |
-
+| Template | Path | Adds beyond builtins |
+| --- | --- | --- |
+| **cli** (default) | `examples/full-example/` | `echo`, `status` — options/flags only; no schemagen |
+| **json** | `examples/full-example-json/` | `@sg` schemagen, `inputSchema`/`outputSchema`, `render-json`, `workspaces` REST CRUD, in-memory SQLite |
 
-When changing builtins or the template, run `just example-full-check` from the argsbarg repo root.
+Package import: `from "argsbarg"` (not relative to argsbarg `src/`).
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -385,7 +387,7 @@ This acts as a "tripwire" that instructs AI agents in your workspace to read Arg
 
 ### 3. Generated Skills & Workspace Configuration
 
-Running `myapp configure` launches an interactive setup wizard that can automatically write compact `SKILL.md` index files and full-reference markdown files (`reference.md`) directly into your global IDE directories (e.g., `~/.cursor/skills/` or `~/.claude/skills/`).
+Running `myapp configure --sync` installs a compact `SKILL.md` index and full-reference `reference.md` to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`.
 
 See **[docs/configure.md](docs/configure.md)** and **[docs/ai-skills.md](docs/ai-skills.md)** for developer setup and automated Homebrew pipeline integration.
 

package/docs/README.md

@@ -27,7 +27,8 @@ Examples are included in the npm tarball (`package.json` `files`). After `bun ad
 | Tier | Path | Use when |
 | --- | --- | --- |
 | Learn | [examples/minimal.ts](../examples/minimal.ts), [examples/nested.ts](../examples/nested.ts), [formats.ts](../examples/formats.ts) | One feature at a time |
-| **Copy** | [examples/full-example/](../examples/full-example/) | Bootstrapping a production CLI (all builtins + schemagen + Homebrew justfile) |
+| **Copy (CLI)** | [examples/full-example/](../examples/full-example/) | Default `create` template — all builtins, Homebrew justfile; no schemagen |
+| **Copy (JSON)** | [examples/full-example-json/](../examples/full-example-json/) | `create --template json` — `@sg`, schemas, REST CRUD, SQLite |
 
 ## Framework docs vs consumer docgen
 
@@ -35,6 +36,6 @@ Examples are included in the npm tarball (`package.json` `files`). After `bun ad
 | --- | --- | --- |
 | **Framework docs** | How argsbarg works; authoring conventions | This directory — shipped in `node_modules/argsbarg/docs/` after `bun add argsbarg` |
 | **Consumer docgen** | *Your* command tree, API, MCP guide for *your* app | `myapp docs cli`, `docs cli-schema`, `docs mcp` — written to `./docs/` with `--save` |
-| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc` — included by `create`; refresh with `merge-cli-program-rule.ts` |
+| **Cursor rule** | Thin tripwire telling agents to read framework docs | `node_modules/argsbarg/examples/full-example-json/.cursor/rules/cli-program.mdc` — merge default for consumers; `create` includes a template copy |
 
 Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (Cursor rule, `AGENTS.md`, or an `alwaysApply` project rule). Generated `./docs/cli.md` in a consumer repo describes **your** CLI, not argsbarg itself.

package/docs/ai-skills.md

@@ -2,29 +2,29 @@
 
 > This feature is experimental.
 
-ArgsBarg can generate Cursor and Claude Code skill directories (`SKILL.md` + `reference.md`) from your CLI schema.
+ArgsBarg can generate agent skill directories (`skill.md` + `reference.md`) from your CLI schema and install them to `~/.agents/skills/<key>/` per the [.agents protocol](https://dotagentsprotocol.com/).
 
-## Install via `configure` (recommended)
+## Enable on the program root
 
-Install skills to the user environment:
-
-```bash
-myapp configure --sync --yes
-# or interactive (accept skill targets when prompted):
-myapp configure
+```typescript
+export const program = {
+  key: "myapp",
+  skill: { enabled: true },
+  ...
+} satisfies CliProgram;
 ```
 
-Skills are written when the agent home or CLI exists:
+When `skill.enabled` is `true`, Homebrew `post_install` (`configure --sync --yes`) installs and refreshes the skill. When omitted or `enabled` is not `true`, no skill is installed.
 
-- Cursor: `~/.cursor/skills/<dir>/` when `~/.cursor` exists
-- Claude Code: `~/.claude/skills/<dir>/` when `~/.claude` exists
-- Codex: `~/.codex/skills/<dir>/` when `codex` is on PATH
-- OpenCode: `~/.config/opencode/skills/<dir>/`
-- OpenClaw: `~/.openclaw/skills/<dir>/` when `openclaw` is on PATH
+The skill directory name is the program `key` with `/`, `\`, and spaces replaced by `_` (e.g. `sqsp-qa`, `full-example`).
 
-The skill directory name defaults to the sanitized program `key` (e.g. `minimal.ts` → `minimal_ts`).
+## Install via `configure --sync`
+
+```bash
+myapp configure --sync --yes
+```
 
-Existing skill directories are removed and rewritten on each install.
+Skills are not prompted during interactive `configure` — install and uninstall are automatic when `skill.enabled` is set (brew install/uninstall and `--sync` / `--remove-all`).
 
 ## Programmatic install
 
@@ -32,28 +32,41 @@ Existing skill directories are removed and rewritten on each install.
 import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
 ```
 
-For library use, call `cliSkillInstall(root, "cursor" | "claude", { global: true, rimraf: true })` — it returns changed file paths.
+`cliSkillInstall(root, { global: true, rimraf: true })` returns changed file paths.
 
 ## Generated content
 
-- **`SKILL.md`** — YAML frontmatter, compact command index, pitfalls, and a pointer to `reference.md`
+- **`skill.md`** — [.agents protocol](https://dotagentsprotocol.com/) frontmatter (`id`, `name`, `description`, `enabled`), compact command index, pitfalls, client setup, and a pointer to `reference.md`
+- **`SKILL.md`** — compatibility copy of `skill.md` for tools that expect uppercase filenames
 - **`reference.md`** — full `docs cli` markdown reference
 
-Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after SKILL.md frontmatter and at the top of `reference.md`.
+Installed files include an HTML comment hint (`Generated by myapp configure; do not edit.`) after skill frontmatter and at the top of `reference.md`.
+
+## Client setup
+
+| Client | Skill path |
+| --- | --- |
+| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure --sync`) |
+| Claude Code | Manual symlink to `~/.claude/skills/<key>/` |
+
+```bash
+mkdir -p ~/.claude/skills
+ln -sf ~/.agents/skills/<key> ~/.claude/skills/<key>
+```
 
-Skills describe **shell invocation only** — no MCP setup, `mcp.json`, or `tools/call` guidance. Use **`myapp docs mcp`** (when `docs` and `mcpServer` are enabled) or connect the MCP server for agent execution.
+Skills describe **shell invocation only** — no MCP setup or `tools/call` guidance. Use **`myapp docs mcp`** (when `docs` and `mcpServer` are enabled) or connect the MCP server for agent execution.
 
 ## MCP vs skills vs docs
 
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`myapp configure`** (skill targets) | Persists optimized skill bundle (`SKILL.md` index + `reference.md` full API) |
+| **`program.skill.enabled`** + **`configure --sync`** | Persists optimized skill bundle at `~/.agents/skills/<key>/` |
 | **`myapp docs`** (requires `docs`) | Bundled markdown on stdout (`docs mcp` when MCP enabled) |
 
-`SKILL.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure` over `docs skill` for agents. See [cli-program.md](cli-program.md).
+`skill.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure --sync` over `docs skill` for installed agents. See [cli-program.md](cli-program.md).
 
-**Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `configure`. Use **`configure`** for persisted shell-oriented skills.
+**Claude Code plugin** (`mcpServer.claudePlugin: true` → `mcp bundle` writes `dist/claude-plugin/<name>.zip`) ships a separate MCP pointer skill (`SKILL.md` only) that routes agents to the bundled MCP server. This is a **dist artifact**, not installed via `configure`.
 
 See also:
 

package/docs/cli-program.md

@@ -8,10 +8,6 @@ ArgsBarg turns your schema into help, shell completions, MCP tools, and agent sk
 
 ```typescript
 const cli = {
-  key: "myapp",
-  version: "1.0.0",
-  description: "One-line summary of what the CLI does.",
-  mcpServer: { enabled: true },
   commands: [
     {
       key: "greet",
@@ -22,6 +18,10 @@ const cli = {
       handler: async (ctx) => { /* ... */ },
     },
   ],
+  description: "One-line summary of what the CLI does.",
+  key: "myapp",
+  mcpServer: { enabled: true },
+  version: "1.0.0",
 } satisfies CliProgram;
 ```
 
@@ -31,11 +31,11 @@ No `mcpTool` blocks required. Every leaf becomes an MCP tool; `inputSchema` come
 
 ```typescript
 const cli = {
-  key: "myapp",
-  version: "1.0.0",
+  commands: [/* ... */],
   description: "One-line summary of what the CLI does.",
   httpServer: { enabled: true }, // myapp api → http://127.0.0.1:3000
-  commands: [/* ... */],
+  key: "myapp",
+  version: "1.0.0",
 } satisfies CliProgram;
 ```
 
@@ -90,7 +90,7 @@ export const reserveCommand = {
 
 Use a **parameterized factory** only when the schema truly depends on inputs (e.g. `createUpsertCommand(deps)` for tests or injected config). A `reserveCommand()` that returns a static literal adds indirection without benefit.
 
-**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not.
+**`satisfies CliProgram`** on the root (or **`satisfies CliLeaf`** / router type on extracted modules) preserves type-checking whether inline or not. Keep **program-root fields in alphabetical order** (`appConfig`, `commands`, `description`, `docs`, `hooks`, `httpServer`, `key`, `mcpServer`, `readiness`, `skill`, `version`, …).
 
 ## Descriptions
 
@@ -541,8 +541,9 @@ await cli.run();
 - **Strict:** unknown keys rejected on load.
 - **CLI:** missing required config exits 1 before the leaf handler (TTY prompt when interactive). Built-in `docs` and `configure get`/`set` skip this exit.
 - **MCP:** server stays up; missing config returns `isError: true` at `tools/call`.
-- **Configure:** interactive `configure` runs the app config wizard; **`configure --sync`** refreshes agent artifacts.
-- **Agent integration:** `configure.agentIntegration` (`mcp` | `skill` | `both`) sets default sync targets; see [configure.md](configure.md#configuretargets).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure --sync`** refreshes agent artifacts to `~/.agents/` ([.agents protocol](https://dotagentsprotocol.com/)).
+- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure --sync`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
+- **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure --sync`; manual Cursor/Claude setup in [mcp.md](mcp.md).
 
 See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.md) (`configure.targets`), and [mcp.md](mcp.md).
 
@@ -583,7 +584,7 @@ If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just co
 
 3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
 
-**Not this file:** `myapp configure` writes the **app** skill (`SKILL.md` under `~/.cursor/skills/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
+- **Not this file:** `myapp configure --sync` writes the **app** skill (`SKILL.md` under `~/.agents/skills/<key>/`) from your command schema — how to *invoke* the CLI. The rule above is for *authoring* argsbarg schema.
 
 ## See also
 

package/docs/config-schema.md

@@ -224,9 +224,9 @@ Object/array/`$ref` properties require `--json` on `configure set` when comma-se
 
 | Example | Role |
 | --- | --- |
-| [`examples/full-example/`](../examples/full-example/) | **Copy template** — `@sg` schemagen, builtins; optional `program.appConfig` |
+| [`examples/full-example-json/`](../examples/full-example-json/) | **Schema-first copy template** — `@sg` schemagen, builtins; optional `program.appConfig` |
 
 ```bash
-cd examples/full-example && just setup && just schemagen
-FULL_EXAMPLE_API_TOKEN=dev just run configure get apiToken --json
+cd examples/full-example-json && just setup && just schemagen
+FULL_EXAMPLE_JSON_API_TOKEN=dev just run configure get apiToken --json
 ```

package/docs/configure.md

@@ -68,10 +68,8 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | --- | --- | --- |
 | Binary | skipped (read-only) | Homebrew formula `bin.install` |
 | Shell completions | skipped | Homebrew `generate_completions_from_executable` |
-| Cursor skill | Y/n prompt | `~/.cursor/skills/<dir>/` when `~/.cursor` exists |
-| Claude skill | Y/n prompt | `~/.claude/skills/<dir>/` when `~/.claude` exists |
-| Codex / OpenCode / OpenClaw skills | Y/n prompt | Agent-specific dirs when available |
-| MCP config | Y/n prompt when `mcpServer.enabled` | Cursor, Claude Code/Desktop, OpenCode, Codex, OpenClaw, ChatGPT desktop |
+| Agent skill | skipped (automatic) | `~/.agents/skills/<key>/` when `program.skill.enabled` |
+| MCP config | skipped (automatic) | `~/.agents/mcp.json` when `mcpServer.enabled` ([.agents protocol](https://dotagentsprotocol.com/)) |
 | App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--sync` bootstraps an empty file on install |
 
 ### Externally managed binary (Homebrew)
@@ -79,37 +77,35 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
 - **`configure --status`** shows `app: system (PATH)`
-- **`--sync`** refreshes skills and MCP; also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
+- **`configure --sync`** refreshes the agent skill (when `program.skill.enabled`) and merges MCP into `~/.agents/mcp.json` (when `mcpServer.enabled`); also creates `~/.local/lib/<key>/config.json` as `{}` when missing (all apps)
 
-MCP config uses the command name on **`PATH`**, not a Cellar path.
+MCP config uses the command name on **`PATH`**, not a Cellar path. For Cursor, Claude Code, and Claude Desktop, copy the `mcpServers` entry manually — see [mcp.md](mcp.md) and `docs mcp`.
 
 ### Interactive default
 
-Bare **`configure`** (TTY required) walks enabled install targets in order. For each target:
+Bare **`configure`** (TTY required) runs the app config wizard when `program.appConfig` has entries. Agent skills and MCP are **not** prompted — they install automatically via brew `post_install` / `--sync` when `program.skill.enabled` or `mcpServer.enabled` respectively.
 
-- **Not installed:** `[Y/n]` — default install; `n` skips.
-- **Installed:** `[y/N]` — default keep; `n` uninstalls.
-- **App config** (`program.appConfig` with entries): runs the config wizard automatically (no Y/n gate). Remove the config file with **`configure --remove-config --yes`**.
+Remove the config file with **`configure --remove-config --yes`**.
 
-The **`app`** target (binary on PATH) is shown in `--status` only — never mutated by `configure`.
+The **`app`** and **`skill`** / **`agentsMcp`** targets are shown in `--status` only — never mutated by interactive `configure` (use `--sync` / brew hooks).
 
 ### `configure.targets`
 
-Configure which artifacts participate in `--sync`:
+Optional gates for app binary status and app-config wizard participation in `--sync`:
 
 ```typescript
+skill: { enabled: true },
+mcpServer: { enabled: true },
 configure: {
-  agentIntegration: "mcp", // | "skill" | "both" — default from mcpServer.enabled
   targets: {
-    chatgptMcp: false,
-    cursorSkill: { includedInAll: true },
+    configure: { includedInAll: true }, // optional: app config wizard on --sync
   },
 },
 ```
 
 `ConfigureTargetSpec` is `boolean` or `{ enabled?: boolean; includedInAll?: boolean }`.
 
-Artifact keys: `chatgptMcp`, `claudeCodeMcp`, `claudeDesktopMcp`, `claudeSkill`, `codexMcp`, `codexSkill`, `configure`, `cursorMcp`, `cursorSkill`, `openclawMcp`, `openclawSkill`, `opencodeMcp`, `opencodeSkill`.
+Artifact keys: `app`, `configure`. Legacy `configure.targets.*Mcp` keys are rejected — MCP installs to `~/.agents/mcp.json` when `mcpServer.enabled`.
 
 ## App config (`program.appConfig`)
 

package/docs/developing.md

@@ -38,7 +38,7 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 `consumers-sync` reads the version from **this repo’s** `package.json` — not npm. Run it **after** `just release` so consumers pin a version that exists on the registry.
 
-**Argsbarg authoring rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
+**Argsbarg authoring rules** — `scripts/merge-cli-program-rule.ts` and `scripts/merge-code-rule.ts` copy templates from `examples/full-example-json/.cursor/rules/` into each consumer, preserving any existing `**… conventions:**` footer block.
 
 **Recommended in each consumer:** replace template placeholders with `**<app> conventions:**` bullets. Commit those files; merges refresh the shared top, not your footer.
 
@@ -55,7 +55,7 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 7. **Cursor rules:** `just consumers-dev` merges `cli-program.mdc` + `code.mdc` (includes **Abstractions** needless-extraction rule).
 8. **Verify:** `just test` and `just docgen` in each consumer repo.
 
-**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, which updates `~/.cursor/skills/<app>/` from that app’s schema — not the argsbarg framework rule.
+**Consumer app skill** — `just install-local` in each consumer (part of `consumers-sync`) runs Homebrew dev install then `myapp configure --sync --yes`, which updates `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.
 
 ## npm package contents
 
@@ -63,14 +63,14 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 
 When adding docs or examples intended for consumers, ensure they live under whitelisted paths (`docs/`, `examples/`, `src/`, etc.).
 
-Exclude `examples/full-example/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
+Exclude `examples/full-example/node_modules/` and `examples/full-example-json/node_modules/` from the npm tarball via [`.npmignore`](../.npmignore).
 
-## Full example
+## Copy templates
 
-[`examples/full-example/`](../examples/full-example/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
+Both [`examples/full-example/`](../examples/full-example/) (CLI) and [`examples/full-example-json/`](../examples/full-example-json/) (schema-first) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
-just example-full-schemagen
+just example-full-check
 just test
 ```
 

package/docs/mcp.md

@@ -44,86 +44,50 @@ bun run examples/nested.ts mcp
 
 ## Client setup
 
-### Cursor
+### `.agents` auto-install
 
-Add a server entry under `mcpServers` in your Cursor MCP config:
+When `mcpServer.enabled` is set, `configure --sync` merges a `mcpServers` entry into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/):
 
-```json
-{
-  "mcpServers": {
-    "myapp": {
-      "command": "bun",
-      "args": ["run", "myapp.ts", "ai", "mcp"]
-    }
-  }
-}
+```bash
+myapp configure --sync --yes
 ```
 
-Use your real binary or script path. For a compiled CLI, `command` can be the installed binary and `args` can be `["mcp"]`.
+### Manual client setup
 
-### Claude Code
-
-`configure` (MCP targets) merges into `~/.claude.json` under `mcpServers`.
-
-### Claude Desktop
-
-`configure` (MCP targets) also merges into Claude Desktop config when app data is present:
-
-| Platform | Path |
-| --- | --- |
-| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Linux | `~/.config/Claude/claude_desktop_config.json` |
-
-Restart Claude Desktop after config changes. You can also install a **`.mcpb`** bundle via **`mcp bundle`** (see [MCP Bundle](#mcp-bundle-mcp-bundle)).
-
-### OpenCode
-
-When `~/.config/opencode` exists, **`configure`** (MCP targets) merges a local server under the top-level **`mcp`** key (not `mcpServers`):
+Many clients do not read `~/.agents/mcp.json` yet. Copy the `mcpServers` entry from that file, or add:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
+  "mcpServers": {
     "myapp": {
-      "type": "local",
-      "command": ["myapp", "mcp"],
-      "enabled": true
+      "command": "myapp",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-OpenCode reads `opencode.jsonc`, `opencode.json`, or `config.json` in that directory. Argsbarg updates the first existing file, or creates `config.json`. JSON-with-comments (`.jsonc`) is not auto-edited — add the block manually or use a `.json` config file.
-
-### OpenAI Codex
-
-When **`codex`** is on PATH, **`configure`** (MCP targets) runs `codex mcp add <server> -- <binary> mcp`, which writes **`~/.codex/config.toml`**. Otherwise add manually:
-
-```toml
-[mcp_servers.myapp]
-command = "myapp"
-args = ["mcp"]
-```
-
-Use **`codex mcp`** to list/add/remove servers, or **Settings → MCP → Open config.toml** in the Codex app. CLI and IDE extension share the same file.
-
-### ChatGPT
+| Client | Config file |
+| --- | --- |
+| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
+| **Claude Code** | `~/.claude.json` under `mcpServers`, or project `.mcp.json` |
+| **Claude Desktop** | See platform paths below |
 
-**Web / Connectors (OpenAI’s documented path)** — **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL**. ChatGPT does not spawn local stdio binaries; bridge and tunnel local servers when needed.
+Restart Cursor or reload MCP after editing. Restart Claude Desktop after config changes.
 
-**Desktop JSON (gated auto-install)** — when ChatGPT app data exists, **`configure`** (MCP targets) also merges `mcpServers` into:
+**Claude Desktop** config paths:
 
 | Platform | Path |
 | --- | --- |
-| macOS | `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json` |
-| Windows | `%APPDATA%\OpenAI\ChatGPT\chatgpt_mcp_config.json` |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
 
-Local JSON support varies by desktop build. Prefer **Connectors** for ChatGPT web or when tools do not appear after install.
+You can also install a **`.mcpb`** bundle via **`mcp bundle`** (see [MCP Bundle](#mcp-bundle-mcp-bundle)).
 
 ### Other MCP hosts
 
-Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** starts the server.
+Copy the `mcpServers` entry from `~/.agents/mcp.json` into the host's native MCP config. Any host that spawns a subprocess and wires stdin/stdout works the same way: the **command** is your app, and **`mcp`** starts the server.
 
 ## Configuration
 

package/docs/output-schema.md

@@ -198,7 +198,7 @@ Handlers keep using runtime types; only discovered roots (and their type graph)
 
 ## Tests
 
-In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example/`.
+In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example-json/`.
 
 Per consumer repo (optional):
 
@@ -214,7 +214,7 @@ Per consumer repo (optional):
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md`.
 
-**Reference implementation:** [`examples/full-example/`](../examples/full-example/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
+**Reference implementation:** [`examples/full-example-json/`](../examples/full-example-json/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
 
 ## Out of scope
 

package/examples/formats.ts

@@ -15,12 +15,6 @@ import {
 } from "../src/index";
 
 const program = {
-  key: "formats.ts",
-  version: pkg.version,
-  description: "Value formats and ctx.inputs demo.",
-  fallbackCommand: "run",
-  fallbackMode: CliFallbackMode.MissingOnly,
-  mcpServer: { enabled: true },
   commands: [
     {
       key: "run",
@@ -67,6 +61,11 @@ const program = {
       },
     },
   ],
+  description: "Value formats and ctx.inputs demo.",
+  fallbackCommand: "run",
+  fallbackMode: CliFallbackMode.MissingOnly,
+  key: "formats.ts",
+  version: pkg.version,
 } satisfies CliProgram;
 
 const cli = new Cli(program);