argsbarg 6.1.8 → 6.1.10

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [6.1.10] - 2026-07-29
+
+### Changed
+
+- Update docs
+
+## [6.1.9] - 2026-07-27
+
+### Added
+
+- **ECS Logging–compatible JSON logs** — default JSON output includes `ecs.version`, nested `labels`, canonical HTTP fields (`http.request.method`, `url.path`, `http.response.status_code`, `event.duration` in nanoseconds), and W3C `trace.id` / `span.id` when `traceparent` is present on HTTP requests.
+- **`program.log.enrich`** — additive hook for custom JSON fields (cannot override ECS baseline keys).
+- **`program.log.serialize`** — optional full-line JSON formatter that bypasses the built-in ECS formatter.
+
+### Changed
+
+- **HTTP trace propagation** — parses incoming `traceparent`, logs trace/span ids, and echoes an updated `traceparent` on responses.
+- **CLI log-format help** — describes JSON as ECS Logging, not generic ECS.
+- **Docs** — new [logging.md](logging.md) (`program.log`, `enrich`, `serialize`, examples); `http-server.md` links there.
+
 ## [6.1.8] - 2026-07-27
 
 ### Changed
@@ -865,7 +885,9 @@ 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.1.8...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.10...HEAD
+[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
 [6.1.8]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.8
 [6.1.7]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.7
 [6.1.6]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.6

package/README.md

@@ -5,32 +5,48 @@ Logo
 [npm version](https://www.npmjs.com/package/argsbarg)
 [Bun](https://bun.sh)
 
-Build beautiful, well-behaved CLI+MCP+HTTP apps with Bun — **no third-party runtime dependencies**. 
+Build beautiful, well-behaved, production-grade CLIs, HTTP REST services, MCP Servers for Bun from a single, unified schema. All with only 2 modest dependencies.
 
-Why another CLI parser?
+Why ArgsBarg?
 
-*Schema-first* — define your entire CLI’s structure, commands, options, and help in a single, explicit data model, making the command-line interface auto-validated, centralized, clear, and self-describing upfront.
+*Schema-first & Auto-validated* — Define your entire command structure, options, description, and inputs once. ArgsBarg compiles this into type-safe option accessors, command-line routing, and validation schemas, keeping your code and interfaces perfectly aligned.
 
-*AI Friendly* — Generate and install rich skills, mcp server, docs based on the schema.
+*Automated Schemagen & Docgen* — Maintain single-source truth by decorating standard TypeScript types (`/** @sg */ interface...`) to automatically compile them into runtime validation schemas (`argsbarg schemagen`). Easily export standard-compliant API documentation, full CLI reference markdown, OpenAPI 3.1 definitions, and agent skill sheets directly from your code (`docs --save` command) using introspection.
 
-*Beautiful* `-h` *screens* — scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+*Production REST Server* — Instantly expose your commands as HTTP REST endpoints (`POST /v1/some-command`) with built-in Kubernetes-compliant `/health/liveness` and `/health/readiness` probes, ECS structured JSON logging to `stderr`, and auto-generated OpenAPI 3.1 specs with an interactive Swagger UI.
 
-*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate scripts consumed by Homebrew during formula `install` (`generate_completions_from_executable`). See [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
+*First-Class Homebrew Distribution* — Exposes robust native support for packaging and distributing compiled binaries and shell completions cleanly via a standard tap-from-repo Homebrew model. Includes built-in completion script generators (`completion bash`/`zsh`/`fish`) consumed by Homebrew's standard `generate_completions_from_executable` command out of the box, ensuring friction-free installations and updates for your developers.
+
+*High-Performance & Light Footprint* — Optimized specifically for Bun. Executes TypeScript and TSX source files directly with no transpile or bundling steps required, leveraging `Bun.serve` for rapid startup and low memory usage. Ships with only two production dependencies (`@cfworker/json-schema` and `ts-json-schema-generator`).
 
-*Bun-optimized* — built from the ground up for Bun and TypeScript, leveraging Bun’s performance and modern JavaScript features without any extra dependencies.
+*Beautiful* `-h` *screens* — Scoped help at any routing depth, rendered in rounded UTF-8 boxes with tables, terminal-width wrapping, and color when stdout is a TTY. Errors print in red with contextual help on stderr.
+
+*Shell completions* — `completion bash`, `completion zsh`, and `completion fish` built-ins generate scripts consumed by Homebrew during formula `install` (`generate_completions_from_executable`). See [docs/distribution-homebrew.md](docs/distribution-homebrew.md).
 
 Also checkout ArgsBarg for [cpp](https://github.com/bdombro/cpp-argsbarg), [nim](https://github.com/bdombro/nim-argsbarg), and [swift](https://github.com/bdombro/swift-argsbarg)!
 
 Halps! -->
 help-preview.png
+[help-preview.png](docs/help-preview.png)
+
 
 Sub-level Halps! -->
 help-l2-preview.png
+[help-l2-preview.png](docs/help-l2-preview.png)
 
 Shell completions! -->
 completions-preview.png
+[completions-preview.png](docs/completions-preview.png)
+
+Production-grade HTTP Server! -->
+```sh
+$ myapp http
+{"@timestamp":"2026-07-29T10:23:59.094Z","message":"HTTP API listening on http://127.0.0.1:13000",...}
+{"@timestamp":"2026-07-29T10:23:59.194Z","message":"GET /health/liveness","ecs.version":"8.11.0",...}
+{"@timestamp":"2026-07-29T10:23:59.195Z","message":"server stopping","ecs.version":"8.11.0",...}
+```
 
-## Usage
+## Basic Usage
 
 ```typescript
 import { Cli, type CliProgram, CliOptionKind } from "argsbarg";
@@ -85,83 +101,123 @@ Everything you need for a first-class CLI:
 - **Rich help**: rounded UTF-8 boxes, tables, terminal width detection (`process.stdout.columns`), colors when stdout/stderr is a TTY
 - **TypeScript-native**: Typed option accessors (`ctx.typedOpt<T>`) and `async/await` handler support.
 
+## Getting Started
 
+You can either quickly bootstrap a complete, feature-rich project skeleton using our CLI creator or manually integrate ArgsBarg into an existing codebase.
 
-## Built-ins
+### Option A: Bootstrap a New Project (Recommended)
 
-Every app gets:
+ArgsBarg provides an interactive project generator to scaffold a new repository fully equipped with TypeScript, Biome, automated schemagen/docgen, standard testing, and Homebrew integration rules:
 
-- `-h` / `--help` at any routing depth (scoped help).
-- `completion bash` **/** `completion zsh` **/** `completion fish` — print shell completion scripts to stdout (injected by `Cli.run()`).
-- `version` — print `CliProgram.version` (`myapp version`).
-- `mcp` — when `mcpServer.enabled` is `true`, run as an MCP stdio server (`myapp mcp`).
-- `http` — when `httpServer.enabled` is `true`, run as an HTTP tool server (`myapp http`).
-- `docs` — print bundled markdown topics, schema JSON, CLI markdown, and generated skill content (`myapp docs cli`, `myapp docs cli-schema`, `myapp docs skill`, …). Enabled by default; opt out with `docs: { enabled: false }`. See [docs/bundled-docs.md](docs/bundled-docs.md).
-- `configure` — manage agent skills, MCP config, and app config (`myapp configure --sync --yes` after Homebrew install). See [docs/configure.md](docs/configure.md).
+```bash
+# Interactive setup (prompts for naming and git configurations)
+bunx argsbarg create my-app
 
-Do not declare a top-level command named `completion`, `version`, or `configure` — they are reserved.
-When `mcpServer.enabled` is `true`, do not declare a top-level command named `mcp` — it is reserved for the MCP built-in.
-When `httpServer.enabled` is `true`, do not declare a top-level command named `http` — it is reserved for the HTTP built-in.
-When docs is enabled (default), do not declare a top-level command named `docs` — it is reserved for the docs built-in. Opt out with `docs: { enabled: false }` if needed.
+# Non-interactive / Headless setup
+bunx argsbarg create my-app \
+  --key my-cli --release-repo org/my-cli --yes
+```
 
-### MCP (AI agents)
+Edit `scripts/create-identity.ts` in the new repository to set your description. The `create` command copies the full-featured template, runs `bun install`, bootstraps a git repository (if standalone), and runs initial validation tests.
 
-Opt in on the program root with `mcpServer: { enabled: true }`, then run `myapp mcp` for a stdio MCP server. Each leaf command becomes a tool; the CLI tree is available as resource `<sanitized-key>://schema` (same as `myapp docs cli-schema`). Handlers can read `ctx.invocation`; use `cli.invoke(argv)` for headless testing.
+#### What the bootstrapped template includes:
 
-See **[docs/mcp.md](docs/mcp.md)** for configuration, env bootstrapping, custom resources, Cursor setup, and protocol details. See **[docs/cli-program.md](docs/cli-program.md)** for schema authoring (consumer apps: run `bunx argsbarg create` or refresh with `bun scripts/merge-cli-program-rule.ts .` from the argsbarg package).
+| Area                  | Files / wiring                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| All built-ins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`       |
+| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`          |
+| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`          |
+| Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
+| Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                       |
+| MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled   |
+| 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`                                |
 
-### HTTP tool server
+*Tip: Verify an existing tree or template setup with `bunx argsbarg create --check .`*
 
-Opt in on the program root with `httpServer: { enabled: true }`, then run `myapp http` for an HTTP REST server (default `http://127.0.0.1:3000`). Nested CLI paths map to REST routes at the server root by default (e.g. `/workspaces`); set `httpServer.pathPrefix: "/api"` to prefix all user routes. Discover routes via `GET /openapi.json`.
+### Option B: Manual Installation (For Existing Projects)
 
-See **[docs/http-server.md](docs/http-server.md)** for endpoints, curl examples, and response shapes.
+To manually integrate ArgsBarg into your existing Bun application: `bun add argsbarg`.
 
-### Configure CLI
 
-Ship via **Homebrew** (tap-from-repo). The formula installs the binary and shell completions; `post_install` runs agent artifact refresh. Private taps require `gh auth login` — see [docs/distribution-homebrew.md](docs/distribution-homebrew.md#end-user-install).
+## Built-in Commands
 
-```bash
-brew install gh
-gh auth login
-brew tap <org>/<repo> git@github.com:<org>/<repo>.git
-brew install <tap>/myapp
-myapp configure    # interactive per-target setup; opt-in app config wizard
-```
+ArgsBarg automatically integrates several core features into your application. These are divided into stable core capabilities and optional experimental integrations:
+
+### Core Capabilities (Stable)
+
+- `-h` / `--help` — Highly-formatted, terminal-width scoped help at any routing depth.
+- `version` — Print the program's version (e.g., `myapp version`).
+- `http` — Launch the high-performance HTTP REST server (injected when `httpServer.enabled` is `true`).
+- `completion bash` / `zsh` / `fish` — Generate shell completion scripts to stdout for deployment and packaging.
+- `docs` — Print bundled markdown topics, schema JSON, or CLI reference markdown (`myapp docs cli`, `myapp docs cli-schema`, etc.). Enabled by default; see [docs/bundled-docs.md](docs/bundled-docs.md).
+- `configure get` / `set` — Query and update application-level configurations non-interactively (active when `program.appConfig` contains configuration schema entries).
+
+### Experimental Integrations (Opt-in)
 
-See **[docs/distribution-homebrew.md](docs/distribution-homebrew.md)** for formula patterns and `bunx argsbarg create`. See **[docs/configure.md](docs/configure.md)** for `configure`, `--sync`, `--remove-all`, and `--status`.
+- `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).
 
-### Shell completions
+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.
 
-Homebrew installs completion scripts during `brew install` via `generate_completions_from_executable`. The CLI still exposes generation for formula authors:
+## HTTP REST Server
+
+By opting in with `httpServer: { enabled: true }` on your program root, running your app with the `http` subcommand launches a high-performance HTTP REST server powered natively by `Bun.serve`. This is ideal for sidecars, microservices, and micro-container deployments (such as in Kubernetes).
+
+Nested command paths map directly to standard REST paths (e.g., `v1 invoices render` maps to `POST /v1/invoices/render`).
+
+```typescript
+const cli = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "My service.",
+  httpServer: { enabled: true, port: 3000 },
+  commands: [/* ... */],
+} satisfies CliProgram;
+```
 
 ```bash
-myapp completion bash
-myapp completion zsh
-myapp completion fish
+myapp http --port 3000
 ```
 
-Users configure their shell per [Homebrew Shell Completion](https://docs.brew.sh/Shell-Completion).
 
-## Quick Start
+
+### Key HTTP Features:
+
+- **Built-in Health Checks** — Automatic `/health/liveness` (responds 200 when online) and `/health/readiness` (responds 200 when online and config validation passes) probes out of the box, compliant with container orchestrators.
+- **OpenAPI 3.1 Spec & Swagger UI** — Serves standard `/openapi.json` and a `/swagger` interactive API browser generated directly from your command schema and JSDoc metadata.
+- **Pre-Handler Schema Validation** — Incoming request payloads are validated against the compile-time JSON Schema (`inputSchema`) on leaf commands before your handler ever runs.
+- **ECS Structured Logging** — Access and error logs are automatically structured as Elastic Common Schema (ECS) JSON objects and written to `stderr` (e.g., for Datadog or ELK collection).
+- **W3C Distributed Tracing** — Automatically parses, propagates, and echoes `traceparent` headers for distributed tracing pipelines.
+
+See **[docs/http-server.md](docs/http-server.md)** for details on endpoints and response shapes, and **[docs/logging.md](docs/logging.md)** for log configurations.
+
+## Distribution & Packaging (Homebrew)
+
+ArgsBarg is built to distribute the compiled binary and shell completions cleanly through Homebrew via a standard **tap-from-repo** model.
+
+### Installation & Post-Install Setup:
 
 ```bash
-bun add argsbarg
+brew tap <org>/<repo> git@github.com:<org>/<repo>.git
+brew install <tap>/myapp
 ```
 
+During installation, Homebrew registers the built-in generated shell completions automatically via `generate_completions_from_executable` (see [docs/distribution-homebrew.md](docs/distribution-homebrew.md)).
 
+### Shell Completions:
 
-### Cursor / AI agents
-
-Argsbarg ships authoring docs in `node_modules/argsbarg/docs/`. Agents do not load them unless your repo points there — copy the thin Cursor rule after install (it tells agents to **read** `cli-program.md`, not duplicate it):
+Completion scripts can also be output directly at any time for manual setups or formula auditing:
 
 ```bash
-mkdir -p .cursor/rules
-mkdir -p .cursor/rules
-bun scripts/merge-cli-program-rule.ts . \
-  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+myapp completion bash
+myapp completion zsh
+myapp completion fish
 ```
 
-Add app-specific conventions in a second rule if needed. Copy the rule from the template, then add a `**<your-app> conventions:**` block at the bottom (see **Cursor rule** in [docs/cli-program.md](docs/cli-program.md)). Documentation map: **[docs/README.md](docs/README.md)**.
+
 
 ## How it works
 
@@ -230,7 +286,7 @@ Check the `examples/` directory for full working scripts:
 | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
 | `ArgsBargMinimal`     | `examples/minimal.ts`    | String + presence flags, `MissingOrUnknown` fallback.                                             |
 | `ArgsBargNested`      | `examples/nested.ts`     | Nested command tree, positional tails, async handlers.                                            |
-| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                  |
+| `ArgsBargFormats`     | `examples/formats.ts`    | `CliValueFormat`, `default`, `ctx.inputs`.                                                        |
 | `ArgsBargFullExample` | `examples/full-example/` | **Copy template:** all builtins, schemagen, Homebrew justfile, `outputSchema`, `from "argsbarg"`. |
 
 
@@ -266,21 +322,21 @@ To refresh Cursor rules in an existing consumer: `bun scripts/merge-cli-program-
 ### What the full-example template includes
 
 
-| Area                  | Files / wiring                                                                         |
-| --------------------- | -------------------------------------------------------------------------------------- |
-| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`      |
-| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`         |
-| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`         |
+| Area                  | Files / wiring                                                                           |
+| --------------------- | ---------------------------------------------------------------------------------------- |
+| All builtins          | `completion`, `version`, `configure`, `docs`, `mcp`, `http`, `configure get`/`set`       |
+| `@sg` schemagen       | `/** @sg */` on types in `src/**/*.ts` → `{TypeName}Schema` in `__generated__/`          |
+| `outputSchema`        | `src/commands/status/types.ts` → `StatusJsonOutputSchema` from `__generated__/`          |
 | Schemagen             | `just schemagen` → `argsbarg schemagen` (justfile exports `node_modules/.bin` on `PATH`) |
-| Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                     |
-| MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled |
-| 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`                              |
+| Command layout        | `src/commands/<name>/command.ts`; registration in `src/program.ts`                       |
+| MCP doc topics        | `docs.topics` auto-exposed as `<key>://docs/<topic>` resources when docs + MCP enabled   |
+| 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`                                |
 
 
-When changing builtins or the template, run `just check-full-example` from the argsbarg repo root.
+When changing builtins or the template, run `just example-full-check` from the argsbarg repo root.
 
 ```bash
 export PATH="$PATH:$(pwd)/examples"
@@ -301,6 +357,42 @@ just run status --json
 
 
 
+## [Experimental] AI Agent & Copilot Integrations
+
+ArgsBarg includes optional experimental features designed to make your CLI and services easily discoverable and executable by modern developer AI agents (such as Cursor, Claude Code, and standard MCP clients). These are entirely opt-in and do not affect the footprint, performance, or stability of the core CLI and HTTP layers.
+
+### 1. Model Context Protocol (MCP) Server
+
+Opt in by setting `mcpServer: { enabled: true }` on your program root. Running `myapp mcp` starts a JSON-RPC 2.0 stdio server.
+
+- **Automatic Tool Exposure** — Every leaf command in your CLI tree becomes an executable MCP tool with inputs automatically generated from your CLI options.
+- **Documentation Resources** — Your CLI structure, JSON schemas, and bundled `docs.topics` are automatically exposed to agents as resources (e.g., `<key>://schema`).
+- **Context-Aware Invocations** — Handlers can read `ctx.invocation` to distinguish between direct CLI, HTTP requests, or headless MCP calls.
+
+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)
+
+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:
+
+```bash
+mkdir -p .cursor/rules
+bun scripts/merge-cli-program-rule.ts . \
+  node_modules/argsbarg/examples/full-example/.cursor/rules/cli-program.mdc
+```
+
+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).
+
+### 3. Generated Skills & Workspace Configuration
+
+Running `myapp configure` launches an interactive setup wizard that can automatically write compact `SKILL.md` index files and full-reference markdown files (`reference.md`) directly into your global IDE directories (e.g., `~/.cursor/skills/` or `~/.claude/skills/`).
+
+See **[docs/configure.md](docs/configure.md)** and **[docs/ai-skills.md](docs/ai-skills.md)** for developer setup and automated Homebrew pipeline integration.
+
+---
+
+
+
 ## Public API overview
 
 The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you need to define a schema and run it. Parsing, completion script generation, help rendering, and schema pre-validation live in other modules under `src/` for tests and advanced integrations.
@@ -311,8 +403,8 @@ The package root (`argsbarg` / `src/index.ts`) exports the types and runtime you
 | `CliProgram`, `CliOption`, `CliPositional`, `CliHandler`          | Schema and handler types.                                                                                                                      |
 | `CliOptionKind`, `CliValueFormat`, `CliFallbackMode`              | Option kinds, value formats (`duration`, `comma-list`, `date`, `date-time`), and root fallback behavior.                                       |
 | `CliSchemaValidationError`                                        | Thrown when the static command tree violates schema rules.                                                                                     |
-| `CliContext`                                                      | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.inputs`, `ctx.invocation`, …).                                |
-| `CliLeafInputs`                                                   | Record type returned by `ctx.inputs` — coerced option/positional values keyed by schema name.                                            |
+| `CliContext`                                                      | Handler context (`ctx.hasFlag`, `ctx.stringOpt`, `ctx.durationOpt`, `ctx.inputs`, `ctx.invocation`, …).                                        |
+| `CliLeafInputs`                                                   | Record type returned by `ctx.inputs` — coerced option/positional values keyed by schema name.                                                  |
 | `Cli`                                                             | Runtime: validate + freeze program, `run()`, `invoke()`, `serveMcp()`, `appConfig` getter, `exportCommandSchema()`, `exportAppConfigSchema()`. |
 | `CliInvokeResult`, `CliInvokeKind`                                | Result types from `cli.invoke()`.                                                                                                              |
 | `CliAppConfig`, `CliAppConfigEntry`                               | App config block on the program root (`entries` metadata overlay + optional `jsonSchema`).                                                     |

package/docs/README.md

@@ -11,6 +11,7 @@ Start here to pick the right guide.
 | **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` |
 | **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` |
 | **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 |

package/docs/cli-program.md

@@ -41,6 +41,8 @@ const cli = {
 
 `httpServer` and `mcpServer` are independent. Tool exposure uses the same rules (`mcpTool.enabled: false` hides from MCP and HTTP). See [http-server.md](http-server.md).
 
+**Logging** — HTTP and MCP server logs go to stderr (JSON by default). Configure `program.log` on the program root; use **`enrich`** to add fields or **`serialize`** for a fully custom line. See **[logging.md](logging.md)**.
+
 ## Inline schema by default
 
 ArgsBarg is **schema-first** — the program tree is the product. **Keep `CliProgram` and leaf fields inline** (`key`, `description`, `options`, `positionals`, `handler`) so a reader sees the full command contract in one place.

package/docs/decisions.md

@@ -1,40 +1,96 @@
-# Decisions
+# Architecture Decision Records (ADRs)
 
-This doc tracks big architectural decisions so that we can avoid re-hashing the same decisions over and over.
+This document records the key architectural decisions made during the design and implementation of ArgsBarg.
 
-## HTTP REST vs flat `/tools/:name`
+---
 
-Decision: **nested `/api/...` REST** (7.0)
+## ADR 1: Exclusively Support Bun as the JavaScript/TypeScript Runtime
+
+### Status
+
+Accepted
 
 ### Context
 
-- v6 exposed tools as `POST /tools/:flat-name` with hyphen-joined paths
-- Nested resources (e.g. `workspaces/{id}`) and verb-specific methods need a route model aligned with the CLI tree
+We evaluated whether to build ArgsBarg as a dual-runtime library supporting both Node.js and Bun, or to target Bun exclusively. 
+
+Supporting Node.js requires maintaining complex build steps (transpilation, bundlers, CommonJS vs ESM dual-packaging, polyfills for HTTP serving) and limits the features we can offer to both the library and its consumers.
+
+### Decision
+
+Exclusively support Bun as the sole runtime for ArgsBarg and its consumer applications.
+
+### Consequences
+
+- **Pros:**
+  - **Zero-Build, Source-First Architecture:** Because Bun executes TypeScript and TSX directly from source, consumers can run their source code directly in production without any transpile or bundling steps (no Babel, Webpack, `ts-node`, or `tsx` required).
+  - **High-Performance Native HTTP (**`Bun.serve`**):** ArgsBarg's HTTP REST server is built directly on top of Bun's native, ultra-fast HTTP stack, offering millisecond-range startup times and massive throughput out of the box with zero boilerplate.
+  - **Native File and Text Imports:** ArgsBarg leverages Bun's native import attributes (e.g., `import readmeText from "./README.md" with { type: "text" }`) to bundle documentation and schemas at compile-time without reading the filesystem at runtime or requiring custom bundler plugins.
+  - **Unified, Lightweight Toolchain:** Both the framework and consumers benefit from Bun's native, ultra-fast package manager, built-in test runner (`bun test`), and zero-config TypeScript support, keeping the project's footprint and developer friction incredibly low.
+- **Cons (What We Lose):**
+  - **Loss of Node-Only Enterprise Tooling:** We lose out-of-the-box integration with legacy enterprise APMs (Application Performance Monitoring like Datadog, New Relic) and security/compliance scanners that are strictly compiled for Node.js runtimes or depend on Node's internal V8 debugging APIs.
+  - **Serverless Platform Friction:** Standard serverless platforms (e.g., AWS Lambda, Google Cloud Functions) have optimized native runtimes for Node.js, whereas running Bun on these platforms requires deploying custom layers or heavier Docker containers.
+  - **Reduced Addressable Library Adoption:** By locking out standard Node.js environments, we lose a significant portion of the mainstream Node.js developer base who cannot adopt Bun due to rigid corporate policies, legacy infrastructure, or strict compliance guidelines.
+  - **100% Node API Compatibility Guarantee:** While Bun's Node compatibility layer is exceptionally high, we lose the 100% absolute guarantee that legacy CommonJS packages or complex native C++ addons (N-API) will run flawlessly without minor polyfill adjustments.
+  - **No Node.js Execution Path:** Applications cannot run on standard Node.js without a separate bundling/transpilation layer, making ArgsBarg a Bun-exclusive framework.
+
+---
 
-### Rationale
 
-1. Command tree already encodes hierarchy — REST paths mirror `http.segment ?? key` plus `:param` routers
-2. Verb leaves (`get`, `post`, …) map to HTTP methods without duplicating path segments
-3. OpenAPI paths match real URLs clients call; query/body binding matches MCP flat args
-4. Hard break on `/tools/*` is acceptable pre-7.0-ship
 
-## Validation: JSON-SCHEMA vs Zod, etc
+## ADR 2: Schema-Driven Contracts via JSON Schema (vs Zod)
 
-Decision: JSON-SCHEMA
+
+
+### Status
+
+Accepted
 
 ### Context
-- JSON-SCHEMA is an open standard to capture a schema in json
-- Zod is the leading Typescript schema management library
-- Others are similar or less good than Zod
 
-### Rational
-Zod may actually cause more complexity and little/no gain for consumers. 
+We evaluated schema management and runtime validation libraries—specifically comparing the TypeScript-first library **Zod** against the industry-standard **JSON Schema** specification—for input and configuration contracts.
+
+### Decision
+
+Adopt JSON Schema (using `@cfworker/json-schema` and `ts-json-schema-generator`) as the core validation format.
+
+### Consequences
+
+- **Pros:**
+  - **Dynamic Manipulation:** Allows ArgsBarg to dynamically slice, patch, and transform schemas at runtime for different targets (CLI parser, MCP tools, OpenAPI JSON, and app configuration). This is far more complex to do with Zod.
+  - **Tooling Parity:** Integrates cleanly with a "write TypeScript, compile to schema" developer workflow.
+  - **Better IntelliSense:** Users write plain TypeScript interface definitions rather than chained Zod schemas, resulting in cleaner code and zero-abstraction IntelliSense.
+  - **Interop:** Consumers who prefer Zod can still use it and convert their schemas via `zod-to-json-schema` before passing them to ArgsBarg.
+- **Cons:**
+  - Fewer expressive, runtime-only custom validation features (like refinements and transformations) built into the framework core.
+
+---
+
+
+
+## ADR 3: Structured Logging (ECS-Compatible JSON)
+
+
+
+### Status
+
+Accepted (v6.1.9)
+
+### Context
+
+HTTP and MCP servers require standard, trace-correlated, and easily digestible access and error logging for production pipelines (such as Datadog, Elasticsearch, and GCP logs). We wanted to deliver first-class, standard-compliant logs out of the box without introducing heavy third-party observability libraries or proprietary schemas.
+
+### Decision
+
+Emit server access and error logs to `stderr` formatted as Elastic Common Schema (ECS)-compatible NDJSON by default, with optional `program.log.enrich` and `program.log.serialize` hooks.
+
+### Consequences
 
-Yes Zod implements some features we do custom for JSON-SCHEMA, but is opinionated, less flexible, and would actually explode complexity in some situations. Zod could be a win for consumers if they require substantial, complex validation -- but then that may not convert well to json-schema anyways and json-schema generation is a big win.
+- **Pros:**
+  - **Industry Standard:** ECS-compatible fields (`ecs.version`, `log.level`, etc.) play perfectly with all standard log collectors (ELK, Fluent Bit, Datadog).
+  - **Twelve-Factor Native:** Writing structured JSON to `stderr` keeps `stdout` clean for CLI command payloads and output redirects.
+  - **Distributed Tracing:** Standard W3C `traceparent` headers are automatically parsed and propagated without proprietary metadata layouts.
+  - **Zero Heavy Dependencies:** Avoids bundling heavy OpenTelemetry SDKs or other binary telemetry clients in the core open-source library.
+- **Cons:**
+  - Requires minor log collector or format mapper adjustments if the deployment environment is strictly standardized on a non-ECS log layout.
 
-1. Argsbarg does a lot of schema patching/manipulation to create different schemas per target (cli-schema.json, MCP contract, openapi.json). This would be harder with Zod
-2. Consumers can use Zod by converting to JSON Schema (`zod-to-json-schema`, `z.toJSONSchema()`) and passing the result to `inputSchema` / `appConfig.jsonSchema`. Argsbarg resolves the validator draft from each schema’s `$schema` (Draft-07 default; 2019-09 / 2020-12 when set).
-3. For uses like API pass-through, proxy, dynamic schemas, Zod may actually explode complexity for consumers.
-4. Our TS->json-schema approach is actually easier and better in many cases
-  - Just write plain typescript, done.
-  - Better intellisense -- substantially less abstraction/inference, much better control

package/docs/developing.md

@@ -70,7 +70,7 @@ Exclude `examples/full-example/node_modules/` from the npm tarball via [`.npmign
 [`examples/full-example/`](../examples/full-example/) must enable every builtin (`capabilities.test.ts`). After builtin or schemagen doc changes:
 
 ```bash
-just full-example-schemagen
+just example-full-schemagen
 just test
 ```