argsbarg 6.2.2 → 6.3.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ 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
@@ -903,7 +915,8 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.2.2...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

package/README.md

@@ -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.
 
@@ -385,7 +385,7 @@ This refreshes the argsbarg-managed section in `AGENTS.md` while preserving your
 
 ### 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,10 +9,10 @@ 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` |

package/docs/ai-skills.md

@@ -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
 
@@ -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

@@ -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/` (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).
+- **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).
 
@@ -582,7 +582,7 @@ If you maintain argsbarg from a sibling checkout, `just consumers-dev` / `just c
 
 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. `AGENTS.md` 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
 
@@ -70,35 +70,35 @@ Non-interactive / CI: pass **`--yes`** (or **`--json`**, **`--sync`**, **`--remo
 | 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` (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 |
+| 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,6 +26,10 @@ 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`):
@@ -33,7 +37,7 @@ 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 `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-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.
@@ -55,7 +59,7 @@ Breaking changes (no backward compat). See [CHANGELOG.md](../CHANGELOG.md) `[Unr
 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 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/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
+      }
+    ]
+  }
+}

package/examples/full-example/Formula/full-example.rb

@@ -11,7 +11,7 @@ class FullExample < Formula
   end
 
   def post_install
-    system bin/"full-example", "configure", "--sync", "--yes"
+    system bin/"full-example", "configure", "--refresh", "--yes"
   end
 
   def uninstall

package/examples/full-example/docs/cli-schema.json

@@ -21,10 +21,10 @@
         {
           "key": "configure",
           "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --sync --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --refresh --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
           "options": [
             {
-              "name": "sync",
+              "name": "refresh",
               "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
               "kind": "presence"
             },
@@ -40,7 +40,7 @@
             },
             {
               "name": "yes",
-              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
               "kind": "presence",
               "shortName": "y"
             },
@@ -261,10 +261,10 @@
         {
           "key": "configure",
           "description": "Set up agent skills and MCP config for this app (binary via Homebrew).",
-          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --sync --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
+          "notes": "Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).\n\nHomebrew post_install runs:\n  full-example configure --refresh --yes\n\nInteractive setup (per target):\n  full-example configure\n\nUpgrade:\n  brew upgrade full-example\n\nShell completions are installed by Homebrew during brew install.\nSee: https://docs.brew.sh/Shell-Completion\n\nSee what is installed:\n  full-example configure --status\n\nUninstall:\n  brew uninstall <tap>/full-example\n\nThe formula uninstall hook runs `configure --remove-all --yes` (skills, MCP, and app config).\n\nUse --dry to preview changes without writing files.\nUse --json for machine-readable output.",
           "options": [
             {
-              "name": "sync",
+              "name": "refresh",
               "description": "Refresh installed skills and MCP. Used by Homebrew post_install.",
               "kind": "presence"
             },
@@ -280,7 +280,7 @@
             },
             {
               "name": "yes",
-              "description": "Skip confirmation (required for --sync, --remove-all, --remove-config).",
+              "description": "Skip confirmation (required for --refresh, --remove-all, --remove-config).",
               "kind": "presence",
               "shortName": "y"
             },

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

@@ -44,7 +44,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example configure --sync --yes
+>   full-example configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example configure
@@ -72,10 +72,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 
@@ -263,7 +263,7 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 > Set up agent artifacts after the binary is installed via Homebrew (see README for tap install).
 > 
 > Homebrew post_install runs:
->   full-example configure --sync --yes
+>   full-example configure --refresh --yes
 > 
 > Interactive setup (per target):
 >   full-example configure
@@ -291,10 +291,10 @@ Set up agent skills and MCP config for this app (binary via Homebrew).
 
 | Option | Type | Required | Format / default | Description |
 | --- | --- | --- | --- | --- |
-| `--sync` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
+| `--refresh` | flag | optional | — | Refresh installed skills and MCP. Used by Homebrew post_install. |
 | `--remove-all` | flag | optional | — | Remove all detected agent artifacts (skills and MCP). |
 | `--status` | flag | optional | — | Print what is currently installed (read-only). |
-| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --sync, --remove-all, --remove-config). |
+| `--yes` (`-y`) | flag | optional | — | Skip confirmation (required for --refresh, --remove-all, --remove-config). |
 | `--dry` | flag | optional | — | Show what would change without writing files. |
 | `--json` | flag | optional | — | Print changed paths or status JSON on stdout. |
 

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

@@ -8,12 +8,12 @@ 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 https://dotagentsprotocol.com.
+When `mcpServer.enabled` is set, `configure --refresh` 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`).
 
 ```bash
-full-example configure --sync --yes
+full-example configure --refresh --yes
 ```
 
 Writes or updates `~/.agents/mcp.json` with a `mcpServers` entry for this app.

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

@@ -36,7 +36,7 @@ For full detail, open `reference.md` in this skill directory (same as `full-exam
 
 Install follows the https://dotagentsprotocol.com:
 
-- Auto-install: `full-example configure --sync --yes` when `skill.enabled` → `~/.agents/skills/full-example/`
+- Auto-install: `full-example configure --refresh --yes` when `skill.enabled` → `~/.agents/skills/full-example/`
 - Cursor and most coding agents read `~/.agents/skills/` natively
 
 **Claude Code (manual):** symlink or copy into Claude's skill directory:

package/examples/full-example/justfile

@@ -67,16 +67,16 @@ http:
 install: install-local
 
 # Refresh skills and MCP without reinstalling the formula
-sync-artifacts:
-    just run configure --sync --yes
+refresh-artifacts:
+    just run configure --refresh --yes
 
 # Dev install: build, stage dev formula, brew install, restore release formula
 install-local: build
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     bun scripts/dev-formula.ts install
-    brew install --formula {{tap}}/{{cli_key}}
+    brew install --force --formula {{tap}}/{{cli_key}}
     bun scripts/dev-formula.ts reset
     @echo ""
     @echo "Next: {{cli_key}} configure"
@@ -121,10 +121,10 @@ release *ARGS:
 
 # Install release formula from tap and run formula test
 test-release:
-    brew untap {{tap}} 2>/dev/null || true
+    NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
     brew install --formula {{tap}}/{{cli_key}}
     brew test {{cli_key}}
 
@@ -145,15 +145,15 @@ uninstall-config:
 
 # Remove formula and untap
 uninstall-formula:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true
 
 # Remove release formula (does not untap)
 uninstall-release:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
 
 # Remove release formula and untap
 uninstall-release-tap:
-    @brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @brew untap {{tap}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
+    @NONINTERACTIVE=1 brew untap {{tap}} 2>/dev/null || true

package/examples/full-example/scripts/formula-shared.ts

@@ -20,7 +20,7 @@ export const formulaInstallRuby = `def install
   end`;
 
 export const formulaPostInstallRuby = `def post_install
-    system bin/"${key}", "configure", "--sync", "--yes"
+    system bin/"${key}", "configure", "--refresh", "--yes"
   end`;
 
 export const formulaUninstallRuby = `def uninstall