argsbarg 6.2.0 → 6.3.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.3.0] - 2026-08-07
+
+### Added
+
+- **Cursor `stop` hook** — `.cursor/hooks.json` runs `just test` after agent edits to `justfile` or `*.{ts,tsx,js,jsx}` (excluding `node_modules/`, `dist/`, `.cursor/`); test failures auto-submit up to 20 follow-ups. Shipped in copy templates and argsbarg repo root (Cursor-only; not in `AGENTS.md`).
+- **`configure` lifecycle hooks** — `program.configure.afterRefresh` and `program.configure.beforeRemoveAll` for app-specific agent artifact setup/teardown around `configure --refresh` and `configure --remove-all`.
+
+### Changed
+
+- **Breaking: `configure --sync` → `configure --refresh`** — renames the non-interactive agent-artifact refresh flag (skills, MCP, config bootstrap). `just sync-artifacts` → `just refresh-artifacts`. No `--sync` alias.
+- **Copy-template justfiles** — `install-local` uses `brew install --force`; uninstall/untap recipes prefix `NONINTERACTIVE=1` so agents and CI skip Homebrew confirm prompts (including post-uninstall untap). `install-production` unchanged.
+
+## [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 +915,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.2.0...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.3.0...HEAD
+[6.3.0]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.3.0
+[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 .`*
 
@@ -158,7 +158,7 @@ ArgsBarg automatically integrates several core features into your application. T
 ### Experimental Integrations (Opt-in)
 
 - `mcp` — Run as a Model Context Protocol stdio-based agent server (injected when `mcpServer.enabled` is `true`). See [docs/mcp.md](docs/mcp.md).
-- `configure` (`--sync` / `--status` / `--remove-all`) — Interactive environment setup and developer agent credentials sync (enabled by default; opt out with `configure: { enabled: false }`). See [docs/configure.md](docs/configure.md).
+- `configure` (`--refresh` / `--status` / `--remove-all`) — Interactive environment setup and developer agent credentials sync (enabled by default; opt out with `configure: { enabled: false }`). See [docs/configure.md](docs/configure.md).
 
 Do not declare top-level commands named `completion`, `version`, or `docs` as they are reserved by default. If their respective features are enabled, `http`, `mcp`, and `configure` are also reserved.
 
@@ -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,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 --sync` installs a compact `SKILL.md` index and full-reference `reference.md` to `~/.agents/skills/<key>/` when `program.skill: { enabled: true }`.
+Running `myapp configure --refresh` 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

@@ -9,15 +9,15 @@ Start here to pick the right guide.
 | **JSON stdout / `outputSchema`** | [output-schema.md](output-schema.md) — codegen pipeline, JSDoc, narrowing |
 | **App config / `program.appConfig`** | [config-schema.md](config-schema.md) — flat JSON file, `ctx.appConfig`, codegen |
 | **JSON Schema validation** | [json-schema-subset.md](json-schema-subset.md) — Draft-07 / 2019-09 / 2020-12 (`$schema` on each schema; default Draft-07) |
-| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --sync` |
+| **Exposing MCP tools** | [mcp.md](mcp.md) — stdio server, `inputSchema`, varargs, `configure --refresh` |
 | **HTTP tool server** | [http-server.md](http-server.md) — `myapp http`, endpoints, curl examples |
 | **Server logging** (`program.log`, `enrich`, `serialize`) | [logging.md](logging.md) — ECS JSON lines, trace headers, custom formats |
-| **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --sync` |
+| **Shipping configure / agent artifacts** | [configure.md](configure.md) — Homebrew + `myapp configure --refresh` |
 | **Homebrew tap-from-repo distribution** | [distribution-homebrew.md](distribution-homebrew.md) — formula pattern, `argsbarg create` |
 | **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
 
@@ -14,17 +14,17 @@ export const program = {
 } satisfies CliProgram;
 ```
 
-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.
+When `skill.enabled` is `true`, Homebrew `post_install` (`configure --refresh --yes`) installs and refreshes the skill. When omitted or `enabled` is not `true`, no skill is installed.
 
 The skill directory name is the program `key` with `/`, `\`, and spaces replaced by `_` (e.g. `sqsp-qa`, `full-example`).
 
-## Install via `configure --sync`
+## Install via `configure --refresh`
 
 ```bash
-myapp configure --sync --yes
+myapp configure --refresh --yes
 ```
 
-Skills are not prompted during interactive `configure` — install and uninstall are automatic when `skill.enabled` is set (brew install/uninstall and `--sync` / `--remove-all`).
+Skills are not prompted during interactive `configure` — install and uninstall are automatic when `skill.enabled` is set (brew install/uninstall and `--refresh` / `--remove-all`).
 
 ## Programmatic install
 
@@ -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
 
@@ -46,7 +46,7 @@ Installed files include an HTML comment hint (`Generated by myapp configure; do
 
 | Client | Skill path |
 | --- | --- |
-| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure --sync`) |
+| Cursor, Codex, Copilot, most agents | `~/.agents/skills/<key>/` (auto via `configure --refresh`) |
 | Claude Code | Manual symlink to `~/.claude/skills/<key>/` |
 
 ```bash
@@ -61,10 +61,10 @@ Skills describe **shell invocation only** — no MCP setup or `tools/call` guida
 | Mechanism | Role |
 | --- | --- |
 | **`myapp mcp`** (requires `mcpServer`) | Runtime tool execution over MCP |
-| **`program.skill.enabled`** + **`configure --sync`** | Persists optimized skill bundle at `~/.agents/skills/<key>/` |
+| **`program.skill.enabled`** + **`configure --refresh`** | 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 --sync` over `docs skill` for installed agents. See [cli-program.md](cli-program.md).
+`skill.md` is the routing index; `reference.md` matches `docs cli`. Prefer `configure --refresh` 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`.
 

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.
@@ -97,11 +97,11 @@ By default (unless `docs.enabled: false`):
 
 - **`docs cli-schema`** — same JSON as the former root `--schema` flag (handlers omitted; built-in subtrees included for leaf roots).
 - **`docs cli`** — markdown rendering of the same command tree (options, positionals, subcommands, fallback routing).
-- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure --sync --yes` for agents (persists index + full API in `reference.md`).
+- **`docs skill`** — prints the compact `SKILL.md` index. Prefer `configure --refresh --yes` for agents (persists index + full API in `reference.md`).
 
 ## MCP guide (`docs mcp`)
 
-When both docs (default) and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --sync`, and protocol notes.
+When both docs (default) and `mcpServer.enabled` are `true`, ArgsBarg injects a **`docs mcp`** topic with an auto-generated guide: tool list, `program.appConfig`, schema resource URI, `configure --refresh`, and protocol notes.
 
 There is no override API in v1 — customize behavior via `mcpTool.description` on leaf commands.
 

package/docs/cli-program.md

@@ -541,9 +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 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).
+- **Configure:** interactive `configure` runs the app config wizard; **`configure --refresh`** refreshes agent artifacts to `~/.agents/` (see https://dotagentsprotocol.com). Optional `configure.afterRefresh` / `configure.beforeRemoveAll` for app-specific agent setup; see [configure.md](configure.md).
+- **Agent skill:** `program.skill: { enabled: true }` installs to `~/.agents/skills/<key>/` on `configure --refresh`; see [configure.md](configure.md) and [ai-skills.md](ai-skills.md).
+- **MCP install:** `mcpServer: { enabled: true }` merges into `~/.agents/mcp.json` on `configure --refresh`; 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).
 
@@ -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 --refresh` 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

@@ -35,13 +35,13 @@ just build
 just install-local    # same formula as production; temporary file:// URL during brew install (`just install` is an alias)
 ```
 
-Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> configure --sync --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just sync-artifacts` to refresh agent artifacts without touching the binary.
+Dev flow matches release: formula `install` copies the binary and generates completions; `post_install` runs `<key> configure --refresh --yes` for skills/MCP. Use `just reinstall-local` to swap the binary into Cellar during tight edit cycles (skips completions and `post_install`). Use `just refresh-artifacts` to refresh agent artifacts without touching the binary.
 
 ## Quick reference
 
 ```bash
 # Refresh skills/MCP after upgrade (Homebrew post_install runs this automatically)
-<key> configure --sync --yes
+<key> configure --refresh --yes
 
 # See what is installed
 <key> configure --status
@@ -60,7 +60,7 @@ Dev flow matches release: formula `install` copies the binary and generates comp
 <key> configure set <key> <value> [--json] [--from-env]
 ```
 
-Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
+Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--refresh`**, **`--remove-all`**, **`--remove-config`**) — see [Confirmation](#confirmation).
 
 ## What gets configured
 
@@ -69,36 +69,36 @@ 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/)) |
-| App config | auto-runs wizard | Interactive wizard may update `~/.local/lib/<key>/config.json` when values change; `--sync` bootstraps an empty file on install |
+| 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; `--refresh` bootstraps an empty file on install |
 
 ### Externally managed binary (Homebrew)
 
 When **`PATH`** resolves the program key to the **running executable** (e.g. after `brew install`):
 
 - **`configure --status`** shows `app: system (PATH)`
-- **`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)
+- **`configure --refresh`** 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. 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) 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.
+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` / `--refresh` when `program.skill.enabled` or `mcpServer.enabled` respectively.
 
 Remove the config file with **`configure --remove-config --yes`**.
 
-The **`app`** and **`skill`** / **`agentsMcp`** targets are shown in `--status` only — never mutated by interactive `configure` (use `--sync` / brew hooks).
+The **`app`** and **`skill`** / **`agentsMcp`** targets are shown in `--status` only — never mutated by interactive `configure` (use `--refresh` / brew hooks).
 
 ### `configure.targets`
 
-Optional gates for app binary status and app-config wizard participation in `--sync`:
+Optional gates for app binary status and app-config wizard participation in `--refresh`:
 
 ```typescript
 skill: { enabled: true },
 mcpServer: { enabled: true },
 configure: {
   targets: {
-    configure: { includedInAll: true }, // optional: app config wizard on --sync
+    configure: { includedInAll: true }, // optional: app config wizard on --refresh
   },
 },
 ```
@@ -107,15 +107,37 @@ configure: {
 
 Artifact keys: `app`, `configure`. Legacy `configure.targets.*Mcp` keys are rejected — MCP installs to `~/.agents/mcp.json` when `mcpServer.enabled`.
 
+### Lifecycle hooks
+
+Optional callbacks on `program.configure` for app-specific agent setup beyond the `.agents` protocol (e.g. Cursor or Claude Desktop config). Framework artifacts are installed/refreshed first; hooks extend or retract custom files.
+
+```typescript
+configure: {
+  afterRefresh: async (ctx) => {
+    if (ctx.dry) return;
+    // e.g. symlink skill, merge Cursor mcp.json — ctx.paths has agentsSkillDir, agentsMcpPath, mcpName
+  },
+  beforeRemoveAll: async (ctx) => {
+    if (ctx.dry) return;
+    // undo custom installs before framework removes ~/.agents/ artifacts
+  },
+},
+```
+
+| Hook | When |
+| --- | --- |
+| `afterRefresh` | After `configure --refresh` installs framework artifacts |
+| `beforeRemoveAll` | Before `configure --remove-all` removes framework artifacts (not `--remove-config`) |
+
 ## App config (`program.appConfig`)
 
-Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure --sync`** (Homebrew `post_install`), even without `program.appConfig`.
+Every app gets `~/.local/lib/<sanitized-key>/config.json` on first **`configure --refresh`** (Homebrew `post_install`), even without `program.appConfig`.
 
 When `program.appConfig` is set, ArgsBarg manages schema-driven values in that file.
 
 | Mode | Description |
 | --- | --- |
-| `configure --sync` | Bootstraps `config.json` as `{}` when missing |
+| `configure --refresh` | Bootstraps `config.json` as `{}` when missing |
 | Interactive `configure` | Config wizard when `entries` is non-empty; re-prompts every entry (Enter keeps current); writes only when values or `_bindings` change |
 | `--status` | Shows config path, required keys (`set` / `missing`), and binding hints (`env`, `file`, `skip`) |
 | `--remove-config --yes` | Removes the config directory |
@@ -132,7 +154,7 @@ Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 | Flag | Description |
 | --- | --- |
 | `--status` | Read-only inventory |
-| `--sync` | Refresh installed agent artifacts; bootstrap `config.json` when missing (Homebrew `post_install`; greenfield → full sync plan) |
+| `--refresh` | Refresh installed agent artifacts; bootstrap `config.json` when missing (Homebrew `post_install`; greenfield → full install plan) |
 | `--remove-all` | Remove all detected agent artifacts |
 | `--remove-config` | Remove app config directory only |
 
@@ -146,7 +168,7 @@ Export helpers from `argsbarg`: `resolveAppConfigPath`, `displayAppConfigPath`.
 
 ## Confirmation
 
-Interactive `configure` prints a **`{app} Setup`** banner and per-target prompts. Non-interactive modes (`--sync`, `--remove-all`, `--remove-config`) require **`--yes`** unless `--dry`.
+Interactive `configure` prints a **`{app} Setup`** banner and per-target prompts. Non-interactive modes (`--refresh`, `--remove-all`, `--remove-config`) require **`--yes`** unless `--dry`.
 
 ## MCP merge behavior
 
@@ -164,7 +186,7 @@ Release formulae should run:
 
 ```ruby
 def post_install
-  system bin/"myapp", "configure", "--sync", "--yes"
+  system bin/"myapp", "configure", "--refresh", "--yes"
 end
 ```
 

package/docs/developing.md

@@ -26,21 +26,25 @@ The release script bumps `package.json`, promotes `[Unreleased]` in `CHANGELOG.m
 
 Update `CHANGELOG.md` under `[Unreleased]` before releasing.
 
+## Cursor test hook (optional)
+
+Copy templates and the argsbarg repo root include `.cursor/hooks.json` plus `.cursor/hooks/run-tests-on-stop.ts`. On agent **stop** (completed turn), when git shows changes to `justfile` or `*.{ts,tsx,js,jsx}` (excluding `node_modules/`, `dist/`, `.cursor/`), the hook runs `just test`. Failures return a `followup_message` (up to **20** auto-retries via `loop_limit`). Requires [Cursor hooks](https://cursor.com/docs/hooks); not part of `AGENTS.md`. New projects get hooks via `argsbarg create`.
+
 ## Local consumer apps
 
 Sibling consumer repos (machine-specific paths in the root `justfile` `consumer_apps` variable, e.g. `~/dev/ss/sqsp-workspaces`):
 
 | 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-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-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 `AGENTS.md`, `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,10 +56,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 `~/.agents/skills/<app>/` when `program.skill.enabled` — 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 --refresh --yes`, which updates `~/.agents/skills/<app>/` when `program.skill.enabled` — not the argsbarg framework rule.
 
 ## npm package contents
 
@@ -95,7 +99,7 @@ import { runSchemagen } from "argsbarg/schemagen";
 | `schema.ts`, `parse.ts`, `context.ts` | Transport-agnostic CLI core |
 | `http/` | HTTP tool server (`httpServer` capability) |
 | `mcp/` | MCP stdio server and bundle (`mcpServer` capability) |
-| `configure/artifacts/` | Agent artifact sync (`configure` capability) |
+| `configure/artifacts/` | Agent artifact install/refresh (`configure` capability) |
 | `docs/` | Built-in documentation generators |
 
 Capabilities are declared on `CliProgram`; builtins wire them in [`src/builtins/`](../src/builtins/).

package/docs/distribution-homebrew.md

@@ -11,7 +11,7 @@ ArgsBarg maps the lifecycle of your application directly to standard Homebrew ho
 | Layer | Mechanism | Role in Lifecycle |
 | --- | --- | --- |
 | **Binary & Autocompletions** | Formula `install` block | Installs compiled binary and registers native shell autocompletions. |
-| **Telemetry & Agent Synclinks** | Formula `post_install` | Automatically runs `{key} configure --sync --yes` to bootstrap configuration files and sync developer tools. |
+| **Agent artifacts** | Formula `post_install` | Automatically runs `{key} configure --refresh --yes` to bootstrap configuration files and refresh agent artifacts. |
 | **Application Configuration** | User-facing `{key} configure` | Runs an interactive TTY setup wizard (only when `program.appConfig` defines required parameters). |
 | **Clean Uninstall** | Formula `uninstall` | Automatically runs `{key} configure --remove-all --yes` to clean up local configurations and symlinks. |
 
@@ -87,7 +87,7 @@ class Myapp < Formula
 
   def post_install
     # Non-interactive bootstrap of config files and developer links
-    system bin/"myapp", "configure", "--sync", "--yes"
+    system bin/"myapp", "configure", "--refresh", "--yes"
   end
 
   def uninstall

package/docs/mcp.md

@@ -46,10 +46,10 @@ 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 --refresh` merges a `mcpServers` entry into `~/.agents/mcp.json` per the https://dotagentsprotocol.com:
 
 ```bash
-myapp configure --sync --yes
+myapp configure --refresh --yes
 ```
 
 ### Manual client setup
@@ -381,7 +381,7 @@ The bundled `SKILL.md` is an **MCP routing stub** — it tells Claude to use the
 
 Load locally with `claude --plugin-dir ./dist/claude-plugin/myapp.zip`.
 
-Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure` MCP targets and MCP hosts). Use **`configure --sync --yes`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
+Bare **`myapp mcp`** still runs the stdio MCP server (unchanged for `configure` MCP targets and MCP hosts). Use **`configure --refresh --yes`** for Cursor, Claude Code, Claude Desktop, and OpenCode JSON config.
 
 ## Hidden commands and options
 

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/.cursor/hooks/run-tests-on-stop.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+/* Cursor stop hook: run `just test` on agent completion; follow up if it fails. */
+
+try {
+  const empty = () => {
+    console.log("{}");
+    process.exit(0);
+  };
+
+  const input = JSON.parse(await Bun.stdin.text()) as {
+    status?: string;
+    loop_count?: number;
+    workspace_roots?: string[];
+  };
+
+  if (input.status !== "completed") empty();
+
+  const cwd = input.workspace_roots?.[0] ?? process.cwd();
+  if (!(await Bun.file(`${cwd}/justfile`).exists())) empty();
+
+  const diff = Bun.spawnSync(["git", "diff", "--name-only", "HEAD"], { cwd, stdout: "pipe" });
+  const CODE_FILE = /\.(t|j)sx?$/i;
+  const SKIP_PREFIX = /^(node_modules|dist|\.cursor)\//;
+  const changed = new TextDecoder()
+    .decode(diff.stdout)
+    .split("\n")
+    .some(
+      (path) =>
+        path &&
+        (path === "justfile" || (CODE_FILE.test(path) && !SKIP_PREFIX.test(path))),
+    );
+  if (!changed) empty();
+
+  const proc = Bun.spawnSync(["just", "test"], {
+    cwd,
+    env: { ...process.env, FORCE_COLOR: "0" },
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const output =
+    new TextDecoder().decode(proc.stdout) + new TextDecoder().decode(proc.stderr);
+
+  if (proc.exitCode === 0) empty();
+
+  const lines = output.trimEnd().split("\n");
+  const tail = lines.length > 80 ? lines.slice(-80).join("\n") : output.trimEnd();
+  const n = (input.loop_count ?? 0) + 1;
+
+  console.log(
+    JSON.stringify({
+      followup_message: `Tests failed (auto-retry ${n}/20). Fix and ensure \`just test\` passes.\n\n\`\`\`\n${tail}\n\`\`\``,
+    }),
+  );
+} catch {
+  console.log("{}");
+}

package/examples/full-example/.cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "stop": [
+      {
+        "command": "bun .cursor/hooks/run-tests-on-stop.ts",
+        "loop_limit": 20,
+        "timeout": 180
+      }
+    ]
+  }
+}