argsbarg 6.1.7 → 6.1.9

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **JSON Schema validation** — `inputSchema` and `program.appConfig` validation uses `@cfworker/json-schema`; draft is resolved from each schema’s `$schema` (default Draft-07). Hand-written schemas may opt into 2019-09 or 2020-12 (`$defs` supported). Docs updated for multi-draft and Zod interop.
+
 ## [6.1.7] - 2026-07-24
 
 ### Changed
@@ -859,7 +879,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.7...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v6.1.9...HEAD
+[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
 [6.1.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v6.1.5

package/docs/README.md

@@ -8,9 +8,10 @@ Start here to pick the right guide.
 | **Authoring a `CliProgram`** (humans or agents) | [cli-program.md](cli-program.md) — schema, formats, headless, `read*Flags` |
 | **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 subset (validation)** | [json-schema-subset.md](json-schema-subset.md) — supported keywords for config and `inputSchema` |
+| **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.
@@ -111,7 +113,7 @@ Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated
 - For shape discovery: HTTP agents load **`docs openapi`** or `GET /openapi.json`; MCP agents use **`docs cli-schema`**; load full **`docs cli`** only when prose is needed.
 - Skill **`reference.md`** uses a compact CLI guide (no inline `outputSchema` JSON) — see [bundled-docs.md](bundled-docs.md#agent-artifact-contract).
 
-Validation keywords: [json-schema-subset.md](json-schema-subset.md).
+Validation: [json-schema-subset.md](json-schema-subset.md) (Draft-07 default; 2019-09 / 2020-12 when `$schema` is set — including Zod-generated schemas).
 
 ## Well-known option names
 
@@ -293,7 +295,7 @@ For nested tool bodies (e.g. invoice template data), declare a matching property
 
 **Precedence:** if `--invoice` is set, the flag value wins and stdin is not read.
 
-Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same JSON Schema subset as `program.appConfig`); `ctx.inputs` returns the cached result.
+Use **`ctx.jsonOpt("invoice")`**, **`ctx.inputs`**, or **`ctx.inputsAs<MyInput>()`** — all synchronous. Argsbarg reads piped stdin before calling the handler when a `pipable` Json flag is omitted. When `leaf.inputSchema` is set, argsbarg validates merged inputs **before the handler runs** (same engine as `program.appConfig`; draft from `$schema` on the schema object); `ctx.inputs` returns the cached result.
 
 At most one `pipable` Json option per leaf. Json option names must appear in `inputSchema.properties` when a custom `inputSchema` is set.
 
@@ -321,7 +323,7 @@ When the entire tool body is JSON (no CLI flags), set **`kind: "json"`** on the
 
 Example CLI: `jq '{format:"pdf", invoice:.}' data.json | myapp render-invoice`
 
-See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for supported schema keywords.
+See [output-schema.md](output-schema.md) for schemagen `inputType`, [http-server.md](http-server.md) for HTTP tool bodies, and [json-schema-subset.md](json-schema-subset.md) for validation drafts, Zod interop, and keyword notes.
 
 `CliLeafInputs` is intentionally untyped at the framework level. Narrow in your app (`read*Flags(ctx)` returning a typed struct) rather than expecting inference from `satisfies CliLeaf`.
 

package/docs/config-schema.md

@@ -48,7 +48,7 @@ await cli.run();
 
 **`_bindings`** — reserved top-level metadata: `{ "_bindings": { "apiToken": "env" } }`. Set via wizard (Enter to use env), `configure set --from-env`, or `ctx.appConfig.set` (marks `file`). Optional keys can be bound to `skip`.
 
-**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema ([supported subset](json-schema-subset.md)). Partial writes (bindings only, single-key updates) skip required-property checks.
+**Validation at runtime** — argsbarg validates the config file and `configure set` / `ctx.appConfig.set` against the effective JSON Schema ([validation](json-schema-subset.md)). Draft is chosen from `jsonSchema.$schema` (default Draft-07). Partial writes (bindings only, single-key updates) skip required-property checks.
 
 See [cli-program.md — Configuration](cli-program.md#configuration-programappconfig) for resolution order, bootstrap timing, and `configure get`/`set`.
 
@@ -67,7 +67,7 @@ export interface CliAppConfigEntry {
 
 export interface CliAppConfig {
   commands?: boolean | { enabled?: boolean; mcpSet?: boolean };
-  jsonSchema?: Record<string, unknown>;  // draft-07 block schema
+  jsonSchema?: Record<string, unknown>;  // JSON Schema block; include $schema to opt into 2019-09 / 2020-12
   entries: Record<string, CliAppConfigEntry>;
 }
 ```
@@ -155,7 +155,7 @@ flowchart LR
   end
   subgraph runtime [Runtime]
     Program["program.appConfig.jsonSchema"]
-    Validate["argsbarg runtime subset validator"]
+    Validate["@cfworker/json-schema (draft from $schema)"]
   end
   src --> Script --> Gen --> Json
   Gen --> Index --> Program --> Validate
@@ -180,16 +180,19 @@ export interface AppConfig {
 
 Wire on the program root: `import { AppConfigSchema } from "./config/__generated__"`.
 
-### Supported AppConfig shapes (argsbarg runtime validator)
+### Supported AppConfig shapes (runtime validation)
 
-| Supported (v1) | Deferred |
+Validation is [@cfworker/json-schema](https://www.npmjs.com/package/@cfworker/json-schema) with draft from `$schema` (default Draft-07). See [json-schema-subset.md](json-schema-subset.md) for drafts, Zod interop, and limits.
+
+| Commonly used | Notes |
 | --- | --- |
-| `type`, `properties`, `required`, `additionalProperties` | remote `$ref` |
-| `enum`, `const`, `default` | complex `if`/`then`/`else` |
-| local `#/definitions` + `$ref` | full draft-2020-12 |
-| `anyOf` / `oneOf` (basic) | |
+| `type`, `properties`, `required`, `additionalProperties` | |
+| `enum`, `const` | `default` is not applied at validation time |
+| local `#/definitions` + `$ref` (Draft-07) or `#/$defs` + `$ref` (2020-12) | remote `$ref` not supported |
+| `anyOf` / `oneOf` / `allOf` | |
 | `items`, `minItems`, `maxItems` | |
 | `minimum`, `maximum`, `minLength`, `maxLength`, `pattern` | |
+| `format` | includes argsbarg `comma-list` |
 
 ## Minimal example (no schemagen)
 

package/docs/decisions.md

@@ -33,8 +33,27 @@ Zod may actually cause more complexity and little/no gain for consumers.
 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.
 
 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 already use zod if they want by using Zod's to-json-schema features to convert when passing to Argsbarg. So we aren't actually alienating / thwarting consumers from using Zod anyways.
+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
+  - Better intellisense -- substantially less abstraction/inference, much better control
+
+## Structured logging (ECS Logging)
+
+Decision: **ECS Logging–compatible NDJSON to stderr** (default), with optional `enrich` / `serialize` hooks
+
+### Context
+
+- HTTP/MCP servers need access logs, error logs, and trace correlation in production log pipelines
+- Consumers may need custom fields (team labels, vendor-specific shapes) without baking proprietary formats into argsbarg core
+- OpenTelemetry log export is out of scope for the framework runtime (no third-party observability SDK dependency)
+
+### Rationale
+
+1. **ECS Logging** is an open standard (NDJSON, `ecs.version`, canonical field names) — works with Elasticsearch, Datadog, GCP log agents, etc.
+2. **stderr + JSONL** keeps stdout free for CLI output and matches twelve-factor log collection
+3. **W3C Trace Context** (`traceparent`) enables cross-service correlation without vendor-specific field layouts
+4. **`program.log.enrich`** — additive hook for consumer-specific fields; cannot override the ECS baseline
+5. **`program.log.serialize`** — escape hatch for full custom lines in consumer repos (argsbarg does not endorse that output as ECS)
+6. **No Tyson / OTel SDK in core** — proprietary or heavy observability stacks belong in consumer config or infra (Fluent Bit remapping), not in the open-source framework

package/docs/http-server.md

@@ -49,7 +49,9 @@ Set `httpServer` on the **program root only**. Validation rejects `httpServer` o
 
 `httpServer` and `mcpServer` are independent — enable either or both.
 
-Program-level `program.log` controls ECS JSON vs human text on stderr (and optional file tee). See [docs/decisions.md](decisions.md).
+## Logging
+
+Server logs (access lines, errors, startup) go to **stderr** as JSON by default. See **[logging.md](logging.md)** for `program.log`, **`enrich`**, **`serialize`**, trace headers, and examples.
 
 ## REST routes
 

package/docs/json-schema-subset.md

@@ -1,39 +1,65 @@
-# JSON Schema subset
+# JSON Schema validation
 
-Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with a **custom Draft-07 subset** in [`src/config/validate.ts`](../src/config/validate.ts). There is no runtime dependency on a full JSON Schema validator.
+Argsbarg validates `program.appConfig`, leaf `inputSchema`, and related documents with [**@cfworker/json-schema**](https://www.npmjs.com/package/@cfworker/json-schema). The validator draft is chosen from each schema’s `$schema` URI (default **Draft-07** when omitted). Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
 
-Use this page when authoring schemas for config files, `inputSchema` on leaves, or `@sg` schemagen output.
+## Schema draft
+
+| `$schema` (examples) | Validator draft |
+| --- | --- |
+| *(omitted)* | Draft-07 (schemagen default) |
+| `http://json-schema.org/draft-07/schema#` | Draft-07 |
+| `https://json-schema.org/draft/2019-09/schema` | 2019-09 |
+| `https://json-schema.org/draft/2020-12/schema` | 2020-12 |
+
+Hand-written schemas may use **2020-12** with `$defs` and `#/$defs/...` `$ref`s. Schemagen (`ts-json-schema-generator`) still emits Draft-07 with `definitions`.
+
+## From Zod (or other generators)
+
+You can pass JSON Schema from **`zod-to-json-schema`**, Zod v4 **`z.toJSONSchema()`**, or any tool that emits a root schema with `$schema`:
+
+| Source | Typical `$schema` | Works with argsbarg |
+| --- | --- | --- |
+| `zod-to-json-schema` (default) | Draft-07 | Yes — matches default when `$schema` omitted |
+| `z.toJSONSchema()` (default) | 2020-12 | Yes — draft resolved from `$schema` |
+| argsbarg schemagen | Draft-07 | Yes |
+
+Set the result on `leaf.inputSchema` or `program.appConfig.jsonSchema`. Validation uses the schema object and its `$schema` URI; not every Zod feature survives JSON Schema conversion (refinements, transforms, etc.).
 
 ## Supported constructs
 
+Validation uses [@cfworker/json-schema](https://www.npmjs.com/package/@cfworker/json-schema) for the draft declared by `$schema`. Schemas from schemagen and typical Zod exports commonly use:
+
 | Feature | Notes |
 | --- | --- |
 | `type` | `object`, `array`, `string`, `integer`, `number`, `boolean`, `null` |
 | `properties` / `required` | Object keys; `additionalProperties: false` enforced when set |
 | `items` | Homogeneous arrays; comma-separated CLI strings coerced when `items` is a primitive |
 | `enum` / `const` | Exact value checks |
-| `anyOf` / `oneOf` | First matching branch wins; errors surface when none match |
-| `$ref` | **Local only** — `#/definitions/Name` resolved within the same root document |
-| `definitions` | Companion to local `$ref` |
-| `format` | `date`, `date-time`, `duration`, `comma-list` (and related string coercions) |
+| `anyOf` / `oneOf` / `allOf` | Combinators (validator-native) |
+| `$ref` | **Local only** — `#/definitions/Name` (Draft-07) or `#/$defs/Name` (2019-09 / 2020-12) |
+| `definitions` / `$defs` | Companion to local `$ref` (draft-dependent) |
+| `format` | Built-ins include `date`, `date-time`, `duration`; argsbarg registers `comma-list` |
 | `minimum` / `maximum` | Numbers and integers |
 | `minLength` / `maxLength` | Strings |
 | `pattern` | String regex (ECMAScript) |
 
 ## Partial validation
 
-`validateConfigDocumentPartial` validates **present keys only** — root `required` is skipped. Used for `configure set` partial writes and bootstrap flows.
+`validateConfigDocumentPartial` validates **present keys only** — all `required` arrays are stripped before validation. Used for `configure set` partial writes and bootstrap flows.
 
 Leaf `inputSchema` validation uses full validation (including `required`) before the handler runs.
 
-## Not supported (today)
+## Argsbarg-specific behavior
+
+- Framework keys (`_bindings`, etc.) are omitted before config validation when `additionalProperties: false`.
+- CLI `configure set` still coerces comma-separated primitives, booleans, and numbers before validation (`parseConfigSetValue`).
+
+## Not guaranteed
 
 - Remote `$ref` (`http://…`, other files)
-- `allOf`, conditional (`if`/`then`/`else`), `not`
-- Unevaluated / dynamic references
 - `default` application at validation time (defaults come from CLI option `default` or config bindings)
 
-If schemagen emits an unsupported keyword, simplify the TypeScript type or post-process the generated JSON Schema.
+If schemagen emits keywords the validator rejects, simplify the TypeScript type or post-process the generated JSON Schema.
 
 ## Where validation runs
 

package/docs/logging.md

@@ -0,0 +1,149 @@
+# Server logging
+
+When you run `myapp http` or `myapp mcp`, Argsbarg writes **server logs to stderr** — not to stdout (handlers and CLI output stay on stdout).
+
+By default each log line is **one JSON object** (NDJSON), shaped for the [ECS Logging](https://github.com/elastic/ecs-logging) convention. That plays nicely with Datadog, Elasticsearch, GCP Logging, and similar collectors.
+
+For local development, switch to plain text with `--log-format text` or `program.log.format: "text"`.
+
+## What gets logged
+
+| Event | When | `event.action` |
+| --- | --- | --- |
+| Server start | HTTP/MCP process listens | `http.server.start` / `server.start` |
+| Access | After each HTTP request or MCP JSON-RPC message | `http.access` / `mcp.access` |
+| Invoke error | After `formatError` → `onError`, before the client sees the error | `invoke.error` |
+
+Toggle access or error lines with `program.log.access` and `program.log.errors` (both default to `true`).
+
+## Example line (default JSON)
+
+After `GET /workspaces` returns 200 in 45ms:
+
+```json
+{
+  "@timestamp": "2026-07-27T14:00:00.000Z",
+  "log.level": "info",
+  "message": "GET /workspaces",
+  "ecs.version": "8.11.0",
+  "service.name": "myapp",
+  "service.version": "1.0.0",
+  "event.action": "http.access",
+  "http.request.method": "GET",
+  "url.path": "/workspaces",
+  "http.response.status_code": 200,
+  "event.duration": 45000000,
+  "labels": { "request_id": "…" }
+}
+```
+
+`event.duration` is in **nanoseconds** (ECS convention). Durations in hook callbacks (`durationMs`) stay in milliseconds.
+
+When the client sends a W3C **`traceparent`** header, lines also include `trace.id` and `span.id`, and the response echoes an updated `traceparent`.
+
+## `program.log` options
+
+Set on the **program root** (same level as `httpServer` / `mcpServer`):
+
+```typescript
+const program = {
+  key: "myapp",
+  version: "1.0.0",
+  description: "…",
+  log: {
+    format: "json",   // "text" for human-readable stderr
+    file: "server.log", // optional tee; relative paths → app config dir
+    access: true,     // HTTP/MCP access lines
+    errors: true,     // invoke error lines
+  },
+  // …
+} satisfies CliProgram;
+```
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `format` | `"json"` | `"json"` = ECS Logging NDJSON; `"text"` = `INFO [http.access]: GET /path` |
+| `file` | — | Append the same lines to this path |
+| `access` | `true` | Emit one line per HTTP request / MCP message |
+| `errors` | `true` | Emit when a user command fails on HTTP/MCP |
+| `enrich` | — | Add custom fields to each JSON line (see below) |
+| `serialize` | — | Replace the built-in formatter entirely (see below) |
+
+CLI overrides on `myapp http` and `myapp mcp serve`: `--log-format`, `--log-file`, `--no-access-log` (HTTP only), `--dev` (print full stacks to stderr on errors).
+
+## `program.log.enrich` — add fields
+
+Use **`enrich`** when you want **extra JSON fields** on top of the default ECS line — for example a team label, deployment cell, or a shape your log pipeline expects.
+
+`enrich` is **additive only**. It cannot change `@timestamp`, `log.level`, `message`, `ecs.version`, `service.name`, `service.version`, or any field Argsbarg already set on that line.
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    enrich: (ctx: LogEnrichContext) => {
+      // Always available:
+      // ctx.level, ctx.message, ctx.action, ctx.service.name, ctx.service.version
+      // ctx.requestId, ctx.traceId, ctx.spanId (when present)
+      // ctx.labels, ctx.error (on error lines)
+
+      // On access logs (http.access / mcp.access):
+      // ctx.http.method, ctx.http.path, ctx.http.status, ctx.http.durationMs, ctx.http.clientIp
+
+      return {
+        deployment: "prod",
+      };
+    },
+  },
+} satisfies CliProgram;
+```
+
+Return a flat object of field names → values. Argsbarg merges each key onto the log line unless that key is already set. To add team metadata inside ECS `labels`, put it in `event.labels` via hooks rather than fighting merge order — or use `serialize` for full control.
+
+## `program.log.serialize` — own the whole line
+
+Use **`serialize`** when the default ECS line is not what you need — for example a legacy JSON schema used only in your organization.
+
+When `serialize` is set, Argsbarg **does not** run the ECS formatter. Your function receives the same `LogEnrichContext` as `enrich` and must return the **full line text without a trailing newline** (Argsbarg adds `\n`).
+
+```typescript
+import type { LogEnrichContext } from "argsbarg";
+
+const program = {
+  // …
+  log: {
+    format: "json",
+    serialize: (ctx: LogEnrichContext) =>
+      JSON.stringify({
+        message: ctx.message,
+        level: ctx.level.toUpperCase(),
+        contextMap: {
+          ...(ctx.traceId ? { trace_id: ctx.traceId } : {}),
+          ...(ctx.spanId ? { span_id: ctx.spanId } : {}),
+        },
+      }),
+  },
+} satisfies CliProgram;
+```
+
+Do **not** set both `enrich` and `serialize` expecting both to apply — `serialize` wins and `enrich` is ignored.
+
+Prefer **`enrich`** when you only need a few extra fields. Reserve **`serialize`** for fully custom output.
+
+## Trace correlation (HTTP)
+
+If an upstream service (gateway, sidecar, mesh) sends a standard **`traceparent`** header:
+
+1. Argsbarg parses it and logs `trace.id` / `span.id`.
+2. The HTTP response includes an updated `traceparent` for this hop.
+
+No configuration required. If the header is missing, Argsbarg does not invent a trace id.
+
+## Related
+
+- [http-server.md](http-server.md) — HTTP server setup and endpoints
+- [mcp.md](mcp.md) — MCP server (same `program.log` applies)
+- [decisions.md](decisions.md#structured-logging-ecs-logging) — why ECS Logging and hooks instead of a bundled observability SDK

package/docs/output-schema.md

@@ -29,7 +29,7 @@ export const status = {
 
 **Set on the leaf only** — not under `mcpTool`.
 
-**Draft version** — argsbarg accepts any JSON Schema object (`type`, `properties`, `definitions`, etc.). Generators may emit draft-07 or draft 2020-12; docgen embeds the object as-is.
+**Draft version** — for **`inputSchema`** and **`appConfig.jsonSchema`**, argsbarg validates using the draft declared in `$schema` (default Draft-07 when omitted). Schemas from schemagen, `zod-to-json-schema`, or `z.toJSONSchema()` may use Draft-07 or 2020-12. **`outputSchema`** is embedded in docs/MCP/OpenAPI as-is and is not runtime-validated.
 
 See [cli-program.md — Structured stdout](cli-program.md#structured-stdout) for when to use `outputSchema` vs `notes`, and [mcp.md](mcp.md) for how MCP returns parsed JSON as `structuredContent`.
 

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

@@ -161,7 +161,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -215,7 +215,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -394,7 +394,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -448,7 +448,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -649,7 +649,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -703,7 +703,7 @@
             },
             {
               "name": "log-format",
-              "description": "Log format: json (ECS) or text.",
+              "description": "Log format: json (ECS Logging) or text.",
               "kind": "enum",
               "choices": [
                 "json",
@@ -886,7 +886,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -940,7 +940,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1119,7 +1119,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1173,7 +1173,7 @@
                 },
                 {
                   "name": "log-format",
-                  "description": "Log format: json (ECS) or text.",
+                  "description": "Log format: json (ECS Logging) or text.",
                   "kind": "enum",
                   "choices": [
                     "json",
@@ -1356,7 +1356,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1410,7 +1410,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1589,7 +1589,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1643,7 +1643,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1822,7 +1822,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -1876,7 +1876,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2055,7 +2055,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",
@@ -2109,7 +2109,7 @@
                     },
                     {
                       "name": "log-format",
-                      "description": "Log format: json (ECS) or text.",
+                      "description": "Log format: json (ECS Logging) or text.",
                       "kind": "enum",
                       "choices": [
                         "json",