argsbarg 6.1.10 → 6.2.2

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.2.2] - 2026-08-07
+
+### Changed
+
+- **Agent instructions (`AGENTS.md`)** — replace `.cursor/rules/*.mdc` with inlined `AGENTS.md` + `CLAUDE.md` (`@AGENTS.md`) in copy templates and consumer sync. `scripts/merge-agents-md.ts` replaces `merge-cli-program-rule.ts` and `merge-code-rule.ts`. Argsbarg maintainer repo uses root `AGENTS.md`.
+
+## [6.2.1] - 2026-08-07
+
+Chore
+
+## [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 +903,10 @@ 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.2...HEAD
+[6.2.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.2.2
+[6.2.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.2.1
+[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);
@@ -133,7 +133,7 @@ Edit `scripts/create-identity.ts` in the new repository to set your description.
 | 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`                                |
+| Agent instructions    | `AGENTS.md`, `CLAUDE.md` (`@AGENTS.md`)                                                 |
 
 *Tip: Verify an existing tree or template setup with `bunx argsbarg create --check .`*
 
@@ -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,37 +307,38 @@ 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 `AGENTS.md` and `CLAUDE.md`), 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`.
 
 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).
+To refresh agent instructions in an existing consumer: `bun scripts/merge-agents-md.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 `AGENTS.md` + `CLAUDE.md`.
 
-| 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"
@@ -371,21 +373,19 @@ Opt in by setting `mcpServer: { enabled: true }` on your program root. Running `
 
 See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor/Claude setup, and protocol details.
 
-### 2. IDE Copilot Rules (Cursor / Claude Code)
+### 2. Agent instructions (`AGENTS.md`)
 
-ArgsBarg ships authoring docs under `node_modules/argsbarg/docs/`. Because AI agents do not automatically read inside `node_modules/`, you can copy a thin custom rule into your project:
+ArgsBarg ships authoring docs under `node_modules/argsbarg/docs/`. Because AI agents do not automatically read inside `node_modules/`, each copy template includes an `AGENTS.md` with inlined argsbarg authoring rules and a `CLAUDE.md` bridge (`@AGENTS.md`).
 
 ```bash
-mkdir -p .cursor/rules
-bun scripts/merge-cli-program-rule.ts . \
-  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+bun scripts/merge-agents-md.ts .
 ```
 
-This acts as a "tripwire" that instructs AI agents in your workspace to read ArgsBarg's framework documentation before modifying your command definitions or schemas. See the **Cursor rule** section in [docs/cli-program.md](docs/cli-program.md).
+This refreshes the argsbarg-managed section in `AGENTS.md` while preserving your app-specific prefix and `**<app> conventions:**` footer. See **Agent instructions** in [docs/cli-program.md](docs/cli-program.md).
 
 ### 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

@@ -17,7 +17,7 @@ Start here to pick the right guide.
 | **Bundling `myapp docs` topics** | [bundled-docs.md](bundled-docs.md) — consumer docgen vs framework docs |
 | **Agent skills** | [ai-skills.md](ai-skills.md) — `configure`, `docs skill` |
 | **Maintaining the argsbarg repo** | [developing.md](developing.md) — release, consumers, npm `files` |
-| **Cursor / IDE agents in a consumer app** | `bunx argsbarg create` (includes rule) or `bun scripts/merge-cli-program-rule.ts .` from argsbarg checkout |
+| **IDE agents in a consumer app** | `bunx argsbarg create` (includes `AGENTS.md`) or `bun scripts/merge-agents-md.ts .` from argsbarg checkout |
 | **Runnable examples** (shipped in npm) | [examples/](examples/) — see table below |
 
 ## Examples (agents: read these)
@@ -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` |
+| **Agent instructions** | Inlined argsbarg authoring rules in `AGENTS.md` | `node_modules/argsbarg/examples/full-example-json/AGENTS.md` — 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.
+Agents do **not** load `node_modules/argsbarg/docs/` unless your repo references them (`AGENTS.md`, or an always-on 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 open standard at 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`** — 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/bundled-docs.md

@@ -8,7 +8,7 @@ Two documentation layers often coexist in a consumer repo:
 
 | Layer | Contents | How agents/humans get it |
 | --- | --- | --- |
-| **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wire via [full-example Cursor rule](../examples/full-example/.cursor/rules/cli-program.mdc) or `AGENTS.md` |
+| **Argsbarg framework** | How to author `CliProgram`, MCP varargs policy, headless patterns | `node_modules/argsbarg/docs/` — wired via consumer [`AGENTS.md`](../examples/full-example-json/AGENTS.md) |
 | **Your CLI (docgen)** | Your command tree, options, MCP tool list, install notes | `myapp docs cli`, `docs cli-schema`, `docs mcp` — save with `--save` to `./docs/` |
 
 `docs cli` and `docs cli-schema` embed each leaf’s `outputSchema` when set — see [output-schema.md](output-schema.md) for how to generate and wire schemas.

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/` (see 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).
 
@@ -554,21 +555,19 @@ See [config-schema.md](config-schema.md) for codegen, [configure.md](configure.m
 
 Do not declare user commands named `completion`, `configure`, `mcp`, `version`, or `docs` at the root — ArgsBarg injects these when configured. App config uses `configure get` / `configure set` subcommands (not a top-level `config` command).
 
-## Cursor rule for consumer repos
+## Agent instructions for consumer repos
 
-Argsbarg ships framework docs under `node_modules/argsbarg/docs/` (same files as this repo’s `docs/`). **This file is the authoritative guide** — the Cursor rule is a thin tripwire that tells agents to read it.
+Argsbarg ships framework docs under `node_modules/argsbarg/docs/` (same files as this repo’s `docs/`). **This file is the authoritative guide** — `AGENTS.md` inlines the tripwire rules that tell agents when to read it.
 
 Agents do **not** discover package docs automatically. Wire them in after `bun add argsbarg`:
 
-1. **Copy the Cursor rule** (recommended):
+1. **Use the copy template `AGENTS.md`** (recommended):
 
 ```bash
-mkdir -p .cursor/rules
-bun scripts/merge-cli-program-rule.ts . \
-  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+bun scripts/merge-agents-md.ts .
 ```
 
-The template is ~30 lines: when to read which doc, plus hard rules agents often get wrong. It does **not** duplicate this guide. `bunx argsbarg create` copies this file into new projects automatically.
+`bunx argsbarg create` copies `AGENTS.md` and `CLAUDE.md` (`@AGENTS.md`) into new projects automatically.
 
 2. **Add an app-specific block at the bottom** (recommended). Replace the template placeholder with a heading like `**myapp conventions:**` and short bullets — shared flag modules, `read*Flags` / `resolve*` paths, Ink vs JSON-only, etc. Example:
 
@@ -579,11 +578,11 @@ The template is ~30 lines: when to read which doc, plus hard rules agents often
 - Per command: `read*Flags` + `resolve*Input` in `commands/<name>/resolve.ts`.
 ```
 
-If you maintain argsbarg from a sibling checkout, `just consumer-dev` / `just consumers-sync` refresh the shared template and **keep** this footer (matched by the `**… conventions:**` heading). Commit `.cursor/rules/cli-program.mdc` in your repo.
+If you maintain argsbarg from a sibling checkout, `just consumers-dev` / `just consumers-sync` refresh the shared managed section and **keep** your prefix and conventions footer. Commit `AGENTS.md` in your repo.
 
-3. **Optional:** a separate rule (e.g. `.cursor/argsbarg.mdc` or `AGENTS.md`) for broader package API notes.
+3. **Optional:** add consumer-specific sections above the `<!-- argsbarg:managed -->` marker in `AGENTS.md` (project context, Ink patterns, domain 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. `AGENTS.md` 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` (see 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

@@ -32,15 +32,15 @@ Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_
 
 | Recipe | When | Effect |
 | --- | --- | --- |
-| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `.cursor/rules/cli-program.mdc` and `code.mdc` from template (keeps app-specific suffix) |
+| `just consumers-dev` | Before publish; hacking on argsbarg locally | `bun add argsbarg@file:<relative>`; refresh `AGENTS.md` from template (keeps app-specific prefix and conventions footer) |
 | `just consumers-sync` | After release | Sets `"argsbarg": "^<this package.json version>"`, `bun install`, merge **cli-program** + **code** Cursor rules, `just build`, `just docgen`, `just install-local` (Homebrew dev formula + agent artifacts; `just install` is an alias) |
 | `just consumers-schemagen` | After `@sg` type changes in consumers | Runs `argsbarg schemagen` in each `consumer_apps` path (fails if missing) |
 
 `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-agents-md.ts` copies the template from `examples/full-example-json/AGENTS.md` into each consumer, preserving any existing prefix and `**… 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.
+**Recommended in each consumer:** replace template placeholders with `**<app> conventions:**` bullets. Commit `AGENTS.md`; merges refresh the managed section, not your prefix or footer.
 
 ## Upgrading consumer apps to 7.0
 
@@ -52,10 +52,10 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 4. **HTTP:** use `/api/...` REST routes only (`POST /tools/*` removed).
 5. **Hooks:** remove manual `ctx.locals.requestId` in `beforeInvoke` — framework seeds it.
 6. **Exports:** stop importing `loadLeafInputs` / `CliHttpResponseConfig` from `argsbarg` (use `ctx.inputs`, leaf `http.successContentType`).
-7. **Cursor rules:** `just consumers-dev` merges `cli-program.mdc` + `code.mdc` (includes **Abstractions** needless-extraction rule).
+7. **Agent instructions:** `just consumers-dev` merges `AGENTS.md` + `CLAUDE.md` (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
 ```