argsbarg 6.1.9 → 6.2.0

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 [.agents protocol](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):
 
@@ -214,7 +214,7 @@ Per consumer repo (optional):
 
 Add a bullet under your app’s `**… conventions:**` block in `.cursor/rules/cli-program.mdc` 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/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
-```