argsbarg 6.1.10 → 6.2.2

package/docs/mcp.md

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

package/docs/output-schema.md

@@ -198,7 +198,7 @@ Handlers keep using runtime types; only discovered roots (and their type graph)
 
 ## Tests
 
-In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example/`.
+In argsbarg: `src/cli-tool/schemagen/schemagen.test.ts` locks discovery and generation against `examples/full-example-json/`.
 
 Per consumer repo (optional):
 
@@ -212,9 +212,9 @@ 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/`](../examples/full-example/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
+**Reference implementation:** [`examples/full-example-json/`](../examples/full-example-json/) in this repo — `@sg` on command types, `__generated__/`, and `status` leaf with `StatusJsonOutputSchema`.
 
 ## Out of scope
 

package/examples/formats.ts

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

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/README.md

@@ -1,16 +1,16 @@
 # full-example
 
-Argsbarg copy template / reference app (not a kitchen-sink product).
+Argsbarg **CLI copy template** — production shell without schemagen (not a kitchen-sink product).
+
+For `@sg` schemagen, JSON Schema validation, and REST CRUD patterns, use `examples/full-example-json/` or `argsbarg create --template json`.
 
 ## What's in this app
 
-- **Builtins enabled:** CLI, shell completion, `docs`, MCP, HTTP API, `configure` (wizard available; no default `appConfig` in the template)
+- **Builtins enabled:** CLI, shell completion, `docs`, MCP, HTTP API, `configure`, agent skills
 - **Commands:**
-  - `echo` — simple flags/positionals
-  - `render-json` — `kind: "json"` leaf, schemagen `inputSchema`, `ctx.inputsAs`
-  - `status` — schemagen `outputSchema`, `--json`
-  - `workspaces` — REST CRUD, `:id` param routers, verb leaves, schemagen input schemas
-- **Tooling:** `@sg` schemagen, `just docgen`, Homebrew/just dev workflow
+  - `echo` — simple flags/positionals (MCP-friendly)
+  - `status` — app version with optional `--json` (no `outputSchema`)
+- **Tooling:** `just docgen`, Homebrew/just dev workflow (no schemagen)
 
 ## Quick start
 
@@ -19,68 +19,6 @@ From a git checkout at this directory (requires [Homebrew](https://brew.sh), [ju
 ```bash
 brew install just bun
 just setup
-just schemagen   # after changing @sg types in src/
 just run status --json
 just run docs readme
 ```
-
-## Install
-
-Requires [Homebrew](https://brew.sh).
-
-### End users
-
-Private GitHub release downloads require [GitHub CLI](https://cli.github.com/) authentication. Run once before `brew install` or `brew upgrade`:
-
-```bash
-brew install gh   # skip if already installed
-gh auth login     # skip if already authenticated
-```
-
-Install:
-
-```bash
-brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
-brew install bdombro/bun-argsbarg/full-example
-```
-
-Upgrade:
-
-```bash
-brew upgrade full-example
-```
-
-Shell completions install during `brew install`. See [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
-
-### Developers
-
-Requires [Homebrew](https://brew.sh), [just](https://just.systems), and [Bun](https://bun.sh). From the repository root (this directory — the folder with `justfile` and `Formula/`):
-
-```bash
-brew install just bun
-just setup
-just install              # build + local dev formula
-just reinstall-local      # fast binary swap during development
-just install-production   # remote tap install (requires gh auth login)
-just test-release
-```
-
-Undo a local dev install: `just uninstall` (formula + agent artifacts), `just uninstall-config` (app config only, without uninstalling the formula).
-
-## Schemagen (`@sg`)
-
-Mark schema-facing types with `/** @sg */` immediately above the declaration (no blank line). Run `argsbarg schemagen` (via `just schemagen` or `just setup`).
-
-| Type | Generated artifact | Import |
-| --- | --- | --- |
-| `RenderJsonInput` | `RenderJsonInputSchema.json` | `RenderJsonInputSchema` from `./__generated__` |
-| `StatusJsonOutput` | `StatusJsonOutputSchema.json` | `StatusJsonOutputSchema` from `./__generated__` |
-| `WorkspaceNameInput` | `WorkspaceNameInputSchema.json` | `WorkspaceNameInputSchema` from `./__generated__` |
-
-## Consumer docs
-
-Regenerate committed reference docs under `docs/` (see [docs/README.md](docs/README.md)):
-
-```bash
-just docgen
-```

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 |