argsbarg 6.2.0 → 6.2.2

package/CHANGELOG.md

@@ -7,6 +7,16 @@ 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
@@ -893,7 +903,9 @@ 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.2.0...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

package/README.md

@@ -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 .`*
 
@@ -321,17 +321,17 @@ bunx argsbarg create my-api \
 
 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, runs `bun install`, `argsbarg schemagen` (json template only), `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 copy templates include
 
-Both templates ship all builtins (`completion`, `version`, `configure`, `docs`, `mcp`, `http`), Homebrew `justfile` + formula scripts, and `.cursor/rules/`.
+Both templates ship all builtins (`completion`, `version`, `configure`, `docs`, `mcp`, `http`), Homebrew `justfile` + formula scripts, and `AGENTS.md` + `CLAUDE.md`.
 
 | Template | Path | Adds beyond builtins |
 | --- | --- | --- |
@@ -373,17 +373,15 @@ 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
 

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)
@@ -36,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-json/.cursor/rules/cli-program.mdc` — merge default for consumers; `create` includes a template copy |
+| **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,7 +2,7 @@
 
 > This feature is experimental.
 
-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/).
+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/.
 
 ## Enable on the program root
 
@@ -36,7 +36,7 @@ import { cliSkillInstall } from "argsbarg/skill/install"; // internal module
 
 ## Generated content
 
-- **`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`** — 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
 

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

@@ -541,7 +541,7 @@ 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 to `~/.agents/` ([.agents protocol](https://dotagentsprotocol.com/)).
+- **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).
 
@@ -555,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:
 
@@ -580,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 --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.
+- **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/configure.md

@@ -69,7 +69,7 @@ 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` |
 | 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/)) |
+| 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)

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-json/.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,7 +52,7 @@ 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 `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.

package/docs/mcp.md

@@ -46,7 +46,7 @@ bun run examples/nested.ts mcp
 
 ### `.agents` auto-install
 
-When `mcpServer.enabled` is set, `configure --sync` merges a `mcpServers` entry into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/):
+When `mcpServer.enabled` is set, `configure --sync` merges a `mcpServers` entry into `~/.agents/mcp.json` per the https://dotagentsprotocol.com:
 
 ```bash
 myapp configure --sync --yes

package/docs/output-schema.md

@@ -212,7 +212,7 @@ Per consumer repo (optional):
 4. `just docgen` / `myapp docs cli --save` — refresh consumer docs.
 5. Document which commands use which roots in **your** `docs/architecture.md` (argsbarg does not maintain per-app tables).
 
-Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` pointing at `node_modules/argsbarg/docs/output-schema.md`.
+Add a bullet under your app’s `**… conventions:**` block in `AGENTS.md` pointing at `node_modules/argsbarg/docs/output-schema.md`.
 
 **Reference implementation:** [`examples/full-example-json/`](../examples/full-example-json/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
 

package/examples/full-example/AGENTS.md

@@ -0,0 +1,75 @@
+# full-example
+
+## Tooling
+
+- Bun only (`bun`, `bunx`, `bun test`). No Node/npm/pnpm.
+
+## Documentation
+
+- `README.md` — user-facing install/commands
+- `docs/architecture.md` — maintainer internals (create if missing)
+- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `docs/skill.md`
+
+<!-- argsbarg:managed -->
+
+## Argsbarg schema
+
+When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
+
+1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
+2. MCP tools, varargs → `node_modules/argsbarg/docs/mcp.md`.
+3. JSON stdout / `outputSchema` and `@sg` schemagen → `node_modules/argsbarg/docs/output-schema.md` and `examples/full-example-json/`.
+4. App config / `program.appConfig` → `node_modules/argsbarg/docs/config-schema.md`.
+5. `configure`, Homebrew distribution → `node_modules/argsbarg/docs/configure.md` and `distribution-homebrew.md`.
+6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
+   - **CLI copy template** (this repo) — builtins only, no schemagen
+   - **Schema-first copy template** — `@sg`, `inputSchema`/`outputSchema`, REST CRUD → `examples/full-example-json/`
+
+**Hard rules** (details and examples are in the docs above — do not contradict them):
+
+- Reserved root commands: `completion`, `configure`, `mcp`, `version`, `docs`.
+- `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
+- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`) or an irreducible wire limit — fix schema and headless handlers first.
+- Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
+- String options: `format` / `default` / `pattern` per `cli-program.md`.
+- Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
+
+## Code conventions
+
+### JSDoc
+
+Add doc comments for exported surfaces that are not obvious from the name alone. Skip comments on short test callbacks and pure re-export files.
+
+### Names
+
+Use names that describe the domain role, not generic placeholders like `data` or `handler`, except in very small scopes.
+
+### Structure
+
+After imports, put **exported** symbols first (alphabetical within each kind), then **module-private** helpers at the bottom. Use `~/…` only where you would otherwise use `../` (or deeper) to reach another module under `src/`. Same-directory (`./`) and child (`./foo/…`) imports stay relative. Use `.ts` extensions.
+
+### Module boundaries
+
+| Path | Owns | Must not |
+| --- | --- | --- |
+| `src/index.ts` | Thin entry: `new Cli(program).run()` | Inline leaf handlers, business logic |
+| `src/types/` | Global type declarations (e.g. `md.d.ts`) | Runtime logic |
+| `src/program.ts` | `CliProgram` assembly: `docs`, `commands: […]` | Inline leaf handlers, business logic |
+| `src/commands/<name>/` | One user-facing command: `command.ts` | Shared helpers unrelated to the command |
+| `scripts/` | Dev tooling (formula helpers) | Production command paths |
+
+When adding commands: `src/commands/<name>/command.ts`; register in `program.ts` **alphabetically by command key**.
+
+**Argsbarg schema:** see Argsbarg schema section above.
+
+### Execution
+
+- **CLI:** `bun ./src/index.ts …` or `just run …`
+- **Tests:** `just test` (after `just check`)
+
+<!-- /argsbarg:managed -->
+
+**full-example conventions:**
+
+Replace with app-specific bullets.

package/examples/full-example/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/examples/full-example/docs/README.md

@@ -5,7 +5,7 @@ Reference template for argsbarg consumer docgen. Every builtin is enabled in `sr
 | If you are… | Read |
 | --- | --- |
 | **Using the CLI** | [../README.md](../README.md) |
-| **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see `.cursor/rules/cli-program.mdc` |
+| **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see [`AGENTS.md`](../AGENTS.md) |
 | **HTTP API / curl** | [http.md](http.md) — generated; or run `full-example docs http` |
 | **MCP tools** | [mcp.md](mcp.md) — generated; or run `full-example docs mcp` |
 | **Full command tree (markdown)** | [cli.md](cli.md) — generated |

package/examples/full-example/docs/mcp.md

@@ -8,7 +8,7 @@ full-example exposes an MCP server with features similar to the CLI.
 
 ### `.agents` auto-install
 
-When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).
+When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.
 
 Install the CLI first so `full-example` is on your PATH (e.g. `brew install full-example`).
 

package/examples/full-example/docs/skill.md

@@ -34,7 +34,7 @@ For full detail, open `reference.md` in this skill directory (same as `full-exam
 
 ## Install location
 
-Install follows the [.agents protocol](https://dotagentsprotocol.com/):
+Install follows the https://dotagentsprotocol.com:
 
 - Auto-install: `full-example configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example/`
 - Cursor and most coding agents read `~/.agents/skills/` natively

package/examples/full-example-json/AGENTS.md

@@ -0,0 +1,86 @@
+# full-example-json
+
+## Tooling
+
+- Bun only (`bun`, `bunx`, `bun test`). No Node/npm/pnpm.
+
+## Documentation
+
+- `README.md` — user-facing install/commands
+- `docs/architecture.md` — maintainer internals (create if missing)
+- Generated: `just docgen` → `docs/cli.md`, `docs/cli-schema.json`, `docs/skill.md`
+
+<!-- argsbarg:managed -->
+
+## Argsbarg schema
+
+When adding or changing argsbarg schema, leaf handlers, or MCP exposure:
+
+1. **Read** `node_modules/argsbarg/docs/cli-program.md` (required — authoritative guide).
+2. MCP tools, varargs, `inputSchema` → also `node_modules/argsbarg/docs/mcp.md`.
+3. JSON stdout / `outputSchema` guide and codegen → `node_modules/argsbarg/docs/output-schema.md`.
+4. App config / `program.appConfig` guide and codegen → `node_modules/argsbarg/docs/config-schema.md`.
+5. `configure`, `configure.targets`, Homebrew distribution → `node_modules/argsbarg/docs/configure.md` and `distribution-homebrew.md`.
+6. Bundled `docs` built-in → `node_modules/argsbarg/docs/bundled-docs.md`.
+7. **Examples** (shipped under `node_modules/argsbarg/examples/`):
+   - **Copy template** (all builtins, `@sg` schemagen, Homebrew justfile, `outputSchema`) → `examples/full-example/`
+
+**Hard rules** (details and examples are in the docs above — do not contradict them):
+
+- Reserved root commands: `completion`, `configure`, `mcp`, `version`, `docs`.
+- `satisfies CliProgram` / `CliLeaf`; action-oriented `description` on root, commands, options, and positionals.
+- Omit `mcpTool` unless genuinely CLI-only (`enabled: false`) or an irreducible wire limit — fix schema and headless handlers first.
+- Interactive leaves: one headless path for MCP, non-TTY CLI, and `--yes` / `--dry-run` / `--json` (`shouldRunHeadless*`, `requireYesInNonTty`); not raw `isTTY`.
+- String options: `format` / `default` / `pattern` per `cli-program.md`; `readLeafInputs()` for multi-flag leaves.
+- Varargs (`argMax: 0`): CLI space-separated; MCP JSON array only — no comma-splitting positionals.
+- Multi-surface leaves (Ink + headless + MCP): one **`read*Flags(ctx)`** per command (or shared family helper + extensions); one **`resolve*Input(flags)`** for cross-field rules — handler reads ctx once, all paths share the struct.
+- JSON stdout: `import { StatusJsonOutputSchema } from "./__generated__"` — declare `/** @sg */` on the type in `types.ts`; handlers import types from the same module.
+- App config (optional): `import { AppConfigSchema } from "./config/__generated__"` — `/** @sg */` on `AppConfig` in `src/config/types.ts`.
+
+## Code conventions
+
+### JSDoc
+
+Add doc comments for exported surfaces that are not obvious from the name alone: JSON output schemas, public types, and non-trivial algorithms. Skip comments on short test callbacks and pure re-export files.
+
+### Names
+
+Use names that describe the domain role, not generic placeholders like `data` or `handler`, except in very small scopes.
+
+### Structure
+
+After imports, put **exported** symbols first (alphabetical within each kind), then **module-private** helpers at the bottom. Use `~/…` only where you would otherwise use `../` (or deeper) to reach another module under `src/`. Same-directory (`./`) and child (`./foo/…`) imports stay relative. Use `.ts` extensions.
+
+### Module boundaries
+
+| Path | Owns | Must not |
+| --- | --- | --- |
+| `src/index.ts` | Thin entry: `new Cli(program).run()` | Inline leaf handlers, business logic |
+| `src/types/` | Global type declarations and module augmentations (e.g. `argsbarg.d.ts`, `md.d.ts`) | Runtime logic, imports from outside `types/` |
+| `src/program.ts` | `CliProgram` assembly: `docs`, `commands: […]` | Inline leaf handlers, business logic |
+| `src/db/` | `AppDb` (SQLite connect, migrate, domain access), `migrate.ts`, `migrations/*.sql` | Command handlers |
+| `src/commands/<name>/` | One user-facing command: `command.ts`, optional `types.ts` with `/** @sg */` | Shared helpers (lift to `src/db/`) |
+| `src/**/__generated__/` | Generated JSON Schema + `index.ts` re-exports | Hand-edited generated files |
+| `scripts/` | Dev tooling (formula helpers) | Production command paths |
+
+When adding commands: `src/commands/<name>/command.ts` + `types.ts` when schemas are needed; register in `program.ts` **alphabetically by command key**.
+
+**Argsbarg schema:** see Argsbarg schema section above.
+
+### Execution
+
+- **Runtime:** Bun (`just test`, `just dev`).
+- **Tests:** colocate `*.test.ts` next to the module.
+- **Schemagen:** after changing `/** @sg */` types in `src/`, run `just schemagen` (`__generated__/` is gitignored).
+
+### Abstractions
+
+Avoid needless extraction: keep single-use helpers in the calling file by default. Split only when reused elsewhere, the caller is large or hard to follow, or extraction clarifies a substantial unit. Do not create tiny one-off helpers.
+- ❌ `utils/formatX.ts` — 60-line helper used by one command
+- ✅ inline helper in that command file
+
+<!-- /argsbarg:managed -->
+
+**full-example-json conventions:**
+
+Replace with app-specific bullets.

package/examples/full-example-json/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/examples/full-example-json/docs/README.md

@@ -5,7 +5,7 @@ Reference template for argsbarg consumer docgen. Every builtin is enabled in `sr
 | If you are… | Read |
 | --- | --- |
 | **Using the CLI** | [../README.md](../README.md) |
-| **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see `.cursor/rules/cli-program.mdc` |
+| **Authoring argsbarg schema** | `node_modules/argsbarg/docs/cli-program.md` — see [`AGENTS.md`](../AGENTS.md) |
 | **HTTP API / curl** | [http.md](http.md) — generated; or run `full-example docs http` |
 | **MCP tools** | [mcp.md](mcp.md) — generated; or run `full-example docs mcp` |
 | **Full command tree (markdown)** | [cli.md](cli.md) — generated |

package/examples/full-example-json/docs/mcp.md

@@ -8,7 +8,7 @@ full-example-json exposes an MCP server with features similar to the CLI.
 
 ### `.agents` auto-install
 
-When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).
+When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.
 
 Install the CLI first so `full-example-json` is on your PATH (e.g. `brew install full-example-json`).
 

package/examples/full-example-json/docs/skill.md

@@ -41,7 +41,7 @@ For full detail, open `reference.md` in this skill directory (same as `full-exam
 
 ## Install location
 
-Install follows the [.agents protocol](https://dotagentsprotocol.com/):
+Install follows the https://dotagentsprotocol.com:
 
 - Auto-install: `full-example-json configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example-json/`
 - Cursor and most coding agents read `~/.agents/skills/` natively

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "6.2.0",
+  "version": "6.2.2",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/docs/mcp-guide.ts

@@ -81,7 +81,7 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "### `.agents` auto-install",
     "",
-    "When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).",
+    "When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the https://dotagentsprotocol.com.",
     "",
   ];
 

package/src/skill/generate.ts

@@ -152,7 +152,7 @@ function buildSkillMd(root: CliProgram, dirName: string): string {
     "",
     "## Install location",
     "",
-    "Install follows the [.agents protocol](https://dotagentsprotocol.com/):",
+    "Install follows the https://dotagentsprotocol.com:",
     "",
     `- Auto-install: \`${root.key} configure --sync --yes\` when \`skill.enabled\` → \`~/.agents/skills/${dirName}/\``,
     `- Cursor and most coding agents read \`~/.agents/skills/\` natively`,