argsbarg 7.0.10 → 7.1.0

package/examples/full-example-json/justfile

@@ -1,24 +1,19 @@
+# bash (not sh); -e bail on errors, -u error on unset vars, pipefail fails pipelines when any stage fails
 set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
 
 export PATH := justfile_directory() + "/node_modules/.bin:" + env_var("PATH")
 
-cli_key := `bun scripts/print-identity.ts key`
-tap_org := `bun scripts/print-identity.ts tapOrg`
-tap_repo := `bun scripts/print-identity.ts tapRepo`
-tap := `bun scripts/print-identity.ts tap`
-release_repo := `bun scripts/print-identity.ts releaseRepo`
-tap_git_url := "git@github.com:" + release_repo + ".git"
 brew_prefix := `brew --prefix`
-tap_parent := brew_prefix + "/Library/Taps/" + tap_org
-tap_path := tap_parent + "/homebrew-" + tap_repo
+tap_parent := brew_prefix + "/Library/Taps/{tapOrg}"
+tap_path := tap_parent + "/homebrew-{tapRepo}"
 
 # List available recipes (default)
 _:
     @just --list
 
-# Compile the CLI binary to dist/full-example
+# Compile the CLI binary to dist/full-example-json
 build:
-    bun build ./src/index.ts --compile --outfile=dist/{{cli_key}}
+    bun build ./src/index.ts --compile --outfile=dist/full-example-json
     @rm -f .*.bun-build
 
 # Apply SQL migrations in src/db/migrations/ to a SQLite database file
@@ -44,11 +39,11 @@ demo-http:
 
 # demo a CLI command
 demo-cli:
-    @just run {{cli_key}} status
+    @just run full-example-json status
 
 # demo a CLI command
 demo-help:
-    @just run {{cli_key}} --help
+    @just run full-example-json --help
 
 # Run the CLI from source with optional args; restarts on file changes
 dev *ARGS:
@@ -80,26 +75,26 @@ install-local: uninstall build
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
     bun scripts/dev-formula.ts install
-    HOMEBREW_NO_ASK=1 brew reinstall --formula {{tap}}/{{cli_key}} || HOMEBREW_NO_ASK=1 brew install --force --formula {{tap}}/{{cli_key}}
+    HOMEBREW_NO_ASK=1 brew reinstall --formula bdombro/bun-argsbarg/full-example-json || HOMEBREW_NO_ASK=1 brew install --force --formula bdombro/bun-argsbarg/full-example-json
     bun scripts/dev-formula.ts reset
-    {{cli_key}} configure install
+    full-example-json configure install
 
 # Remove local dev install, then install from GitHub tap (requires gh auth login)
 install-production: uninstall
-    brew tap {{release_repo}} {{tap_git_url}}
-    brew install --formula {{release_repo}}/{{cli_key}}
-    {{cli_key}} configure install
+    brew tap bdombro/bun-argsbarg git@github.com:bdombro/bun-argsbarg.git
+    brew install full-example-json
+    full-example-json configure install
 
 # Alias for backward compatibility
 reinstall: reinstall-local
 
 # Rebuild binary and swap into Cellar (run install-local first; run `just refresh` for skills/MCP)
 reinstall-local: build
-    install -m 755 dist/{{cli_key}} "$(brew --prefix {{cli_key}})/bin/{{cli_key}}"
+    install -m 755 dist/full-example-json "$(brew --prefix full-example-json)/bin/full-example-json"
 
 # Refresh agent skills/MCP without reinstalling the binary
 refresh:
-    {{cli_key}} configure install
+    full-example-json configure install
 
 # Lint sources without writing
 lint:
@@ -129,12 +124,12 @@ release *ARGS:
 
 # Install release formula from tap and run formula test
 test-release:
-    HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
+    HOMEBREW_NO_ASK=1 brew untap bdombro/bun-argsbarg 2>/dev/null || true
     mkdir -p {{tap_parent}}
     ln -sfn '{{justfile_directory()}}' {{tap_path}}
-    HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    brew install --formula {{tap}}/{{cli_key}}
-    brew test {{cli_key}}
+    HOMEBREW_NO_ASK=1 brew uninstall --formula bdombro/bun-argsbarg/full-example-json 2>/dev/null || true
+    brew install --formula bdombro/bun-argsbarg/full-example-json
+    brew test full-example-json
 
 # Typecheck without emitting build artifacts
 typecheck:
@@ -142,7 +137,7 @@ typecheck:
 
 # Undo dev/Homebrew install (remove agent artifacts, then keg + untap)
 uninstall:
-    @{{cli_key}} configure uninstall --yes 2>/dev/null || just run configure uninstall --yes
-    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}} 2>/dev/null || true
-    @HOMEBREW_NO_ASK=1 brew uninstall --formula {{tap}}/{{cli_key}}-local 2>/dev/null || true
-    @HOMEBREW_NO_ASK=1 brew untap {{tap}} 2>/dev/null || true
+    @full-example-json configure uninstall --yes 2>/dev/null || just run configure uninstall --yes
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula bdombro/bun-argsbarg/full-example-json 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew uninstall --formula bdombro/bun-argsbarg/full-example-json-local 2>/dev/null || true
+    @HOMEBREW_NO_ASK=1 brew untap bdombro/bun-argsbarg 2>/dev/null || true

package/examples/mcp-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "mcp-plugin",
+  "version": "1.0.0",
+  "description": "Argsbarg MCP plugin template for Cursor and Claude Code marketplaces",
+  "author": {
+    "name": "Brian Dombrowski"
+  },
+  "homepage": "https://github.com/bdombro/bun-argsbarg",
+  "repository": "https://github.com/bdombro/bun-argsbarg",
+  "skills": ["skills/mcp-plugin"]
+}

package/examples/mcp-plugin/.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/mcp-plugin/.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/mcp-plugin/.cursor-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "mcp-plugin",
+  "displayName": "McpPlugin",
+  "description": "Argsbarg MCP plugin template for Cursor and Claude Code marketplaces",
+  "version": "1.0.0",
+  "author": {
+    "name": "Brian Dombrowski"
+  },
+  "homepage": "https://github.com/bdombro/bun-argsbarg",
+  "repository": "https://github.com/bdombro/bun-argsbarg",
+  "skills": ["skills/mcp-plugin"]
+}

package/examples/mcp-plugin/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "mcp-plugin": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs", "mcp"]
+  }
+}

package/examples/mcp-plugin/AGENTS.md

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

package/examples/mcp-plugin/CLAUDE.md

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

package/examples/mcp-plugin/README.md

@@ -0,0 +1,70 @@
+# mcp-plugin
+
+Argsbarg MCP plugin template for Cursor and Claude Code marketplaces (@sg schemagen, JSON schemas, in-repo manifests).
+
+## Overview
+
+`mcp-plugin` packages an MCP server and agent skills directly for Cursor and Claude Code marketplaces:
+
+- **Cursor Plugin**: `.cursor-plugin/plugin.json` and `mcp.json` running `${CURSOR_PLUGIN_ROOT}/scripts/mcp.mjs` via `node`.
+- **Claude Code Plugin**: `.claude-plugin/plugin.json` and `.mcp.json` running `${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs` via `node`.
+- **In-repo skills**: `skills/mcp-plugin/SKILL.md` discovered and loaded by agent platforms.
+- **Standalone runner**: `bun build --target=node src/index.ts --outfile scripts/mcp.mjs` creates an inlined, zero-npm-install script.
+
+## Development
+
+```bash
+# Install dependencies and generate schemas
+just setup
+
+# Build standalone MCP bundle
+just build
+
+# Test MCP server directly with node
+node ./scripts/mcp.mjs mcp
+
+# Link into local Cursor plugins for live testing
+just install-plugin-cursor
+```
+
+## Commands
+
+- `mcp-plugin echo` — Echo text back to stdout or inspect flags.
+- `mcp-plugin render-json` — Process structured JSON payloads with schema validation.
+- `mcp-plugin status` — Show application version with schemagen output schema (`--json`).
+- `mcp-plugin workspaces` — Manage workspace resources (REST CRUD with in-memory SQLite).
+
+### Built-in commands
+
+- `mcp-plugin completion` — Install or inspect shell tab completions (bash, zsh, fish).
+- `mcp-plugin configure` — Manage agent artifacts (skills, MCP, application configuration).
+- `mcp-plugin docs` — Browse bundled documentation topics (`cli`, `mcp`, `http`, `readme`).
+- `mcp-plugin mcp` — Start the Model Context Protocol (stdio) server for AI coding agents.
+- `mcp-plugin version` — Display version information.
+
+## Distribution & Marketplaces
+
+### Cursor
+
+- **Local Development / Testing**: Run `just install-plugin-cursor` to link the repo into `~/.cursor/plugins/local/mcp-plugin`. Reload the Cursor window to activate.
+- **Team Marketplace**: In Cursor Dashboard → **Settings → Plugins → Team Marketplaces → Import**, enter your GitHub repository URL.
+- **Official Cursor Marketplace**: Submit your repository URL at [cursor.com/marketplace/publish](https://cursor.com/marketplace/publish). Once approved, users can install directly via `/add-plugin mcp-plugin` or from the Customize sidebar.
+
+### Claude Code
+
+- **Direct Git Install**: Users can add your repository without central registration:
+  ```bash
+  /plugin marketplace add <owner>/<repo>
+  /plugin install mcp-plugin
+  /reload-plugins
+  ```
+- **Official Directory**: Submit a pull request to [anthropics/claude-plugins-official](https://github.com/anthropics/claude-plugins-official) under `external_plugins/`. Once merged, users can install directly via `/plugin install mcp-plugin@claude-plugins-official`.
+
+## Documentation
+
+| Need | Resource |
+| --- | --- |
+| CLI reference | [docs/cli.md](docs/cli.md) or `mcp-plugin docs cli` |
+| MCP tools | [docs/mcp.md](docs/mcp.md) or `mcp-plugin docs mcp` |
+| HTTP API | [docs/http.md](docs/http.md) or `mcp-plugin docs http` |
+| OpenAPI 3.1 | [docs/openapi.json](docs/openapi.json) |

package/examples/mcp-plugin/biome.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "lineWidth": 120
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.json"]
+    }
+  ]
+}

package/examples/mcp-plugin/bun.lock

@@ -0,0 +1,48 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "consumer-app-example",
+      "dependencies": {
+        "argsbarg": "file:../..",
+      },
+      "devDependencies": {
+        "@biomejs/biome": "^2.5.0",
+        "@types/bun": "^1.3.12",
+        "typescript": "^5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@2.5.1", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.1", "@biomejs/cli-darwin-x64": "2.5.1", "@biomejs/cli-linux-arm64": "2.5.1", "@biomejs/cli-linux-arm64-musl": "2.5.1", "@biomejs/cli-linux-x64": "2.5.1", "@biomejs/cli-linux-x64-musl": "2.5.1", "@biomejs/cli-win32-arm64": "2.5.1", "@biomejs/cli-win32-x64": "2.5.1" }, "bin": { "biome": "bin/biome" } }, "sha512-IXWLCxKmae+rI7LOHS1B3EbVisQ6GRAWbhN9msa6KjNCyFWrvKZWR4oUdinaNssrV852OrSHuSPa95h1GPJc7Q=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.1", "", { "os": "darwin", "cpu": "arm64" }, "sha512-npqDzvqv7vFaWRiNN1Te71siRgPaqS9MpqgYCdP/CrUbkJ7ApezaeaKjueKHRN/JH/6lRjJQAHi8acQDCAz22w=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.1", "", { "os": "darwin", "cpu": "x64" }, "sha512-RgwTqPAM8g2tn1j+b5oRjF/DbSBX8a4gwojtuG9XuhfK7GgomvZ9+T+tqjXiVbjLEeGJOoL6VEk8mvRTVeSybw=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-yhV35CzZh38VyMvTEXi3JTjxZBs++oCKK9KG8vB6VI5+uvQvZNR3BFWEKKzuOmx9DJJj7sQpZ4LQJcmbGTs3+Q=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.1", "", { "os": "linux", "cpu": "arm64" }, "sha512-WMcvMLgByyTqVxGlq918NBBYliq9FRR9GAQVETHb+VjGVqXCZFfHlZHC1FX4ibuYY/Hg6TJE3rHU0xVrdJXNRw=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-J/7uHSX7NfoYDI7HijAkd8lnQIOrRb2W7j3X+tw4R+N5ExvXGsyXFiGdQcfcxfOmNQmZVSQOCDk757fwpzqQcg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.1", "", { "os": "linux", "cpu": "x64" }, "sha512-ANTowtlLmPYm5yeMckWY8Xzb9Ix+JJP3tgHR/n6xRj1VWyIzzWtfRfih9hv9VmClwadpBvZduISZIbBsIlYG3A=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.1", "", { "os": "win32", "cpu": "arm64" }, "sha512-zgXnKNgWPC4iPF7Y1lR3STUeCUuZRpD6IiOrC7TZTlh0Lx6FiVUT05myuMQHQ9D+1cc7uyMldi4forE6lp0ivQ=="],
+
+    "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.1", "", { "os": "win32", "cpu": "x64" }, "sha512-6uxpR9hvaglANkZemeSiN/FhYgkGasrEGn267eXIWvjrjJ2LhDlk251IhjVJq6MXzkV2/bcXwLwSroLyPtqRZg=="],
+
+    "@types/bun": ["@types/bun@1.3.14", "", { "dependencies": { "bun-types": "1.3.14" } }, "sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw=="],
+
+    "@types/node": ["@types/node@26.0.0", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-vf2YFi1iY9lHGwNJMs01biZFbKJkrZR1T6/MlzjhJLPdntOHLhTrDSnSVcdtvjihi4VQNlrFRIxLsDBlQpAipA=="],
+
+    "argsbarg": ["argsbarg@file:../..", { "devDependencies": { "@biomejs/biome": "^2.5.0", "@types/bun": "^1.3.12", "typescript": "^5.9.3" }, "bin": { "argsbarg": "src/index.ts" } }],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}

package/examples/mcp-plugin/bunfig.toml

@@ -0,0 +1,3 @@
+[install]
+# fetch package.json deps on first `bun src/index.ts` without manual `bun install`.
+auto = "fallback"

package/examples/mcp-plugin/docs/README.md

@@ -0,0 +1,27 @@
+# full-example documentation
+
+Reference template for argsbarg consumer docgen. Every builtin is enabled in `src/program.ts`.
+
+| If you are… | Read |
+| --- | --- |
+| **Using the CLI** | [../README.md](../README.md) |
+| **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 |
+| **Full command tree (JSON)** | [cli-schema.json](cli-schema.json) — generated |
+| **OpenAPI 3.1** | [openapi.json](openapi.json) — generated |
+| **Agent skill router** | [../skills/full-example-json/SKILL.md](../skills/full-example-json/SKILL.md) — scaffolded from template |
+
+## Framework docs vs this directory
+
+| Layer | Contents |
+| --- | --- |
+| **Argsbarg framework** | How to author `CliProgram`, MCP, HTTP API | `node_modules/argsbarg/docs/` |
+| **This `docs/` folder** | *full-example* command tree and guides | `just docgen` |
+
+Do not hand-edit generated files. Refresh with:
+
+```bash
+just docgen
+```