agent-first-data 0.17.2 → 0.18.0

package/README.md

@@ -5,7 +5,7 @@ npm install agent-first-data
 ```
 
 ```typescript
-import { jsonResult, outputJson, outputPlain } from "agent-first-data";
+import { jsonResult, render } from "agent-first-data";
 
 const event = jsonResult({
   api_key_secret: "sk-123",
@@ -13,11 +13,11 @@ const event = jsonResult({
   db_url: "postgres://user:p@ss@db/app?token_secret=abc",
 }).build();
 
-console.log(outputJson(event.toJSON()));
-console.log(outputPlain(event.toJSON()));
+console.log(render(event.toJSON(), "json"));
+console.log(render(event.toJSON(), "plain"));
 ```
 
-Useful names use TypeScript casing: `outputJson`, `outputYaml`, `outputPlain`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `cliOutput`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
+Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
 
 Skill admin and stream redirection are not re-exported from the package root; import them from their own subpaths:
 
@@ -30,7 +30,7 @@ import { installStreamRedirectFromRawArgs } from "agent-first-data/stream-redire
 
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed and internal whitespace redacts the whole field.
-- YAML/plain quote and escape keys as well as values, sort by UTF-16 code unit order, and render nested objects in arrays as canonical JSON.
+- YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `buildCliError(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
 - Use `cliHandleVersionOrContinue()` before argument parsing so bare `--version` stays conventional and `--version --output json|yaml|plain` stays structured.

package/assets/skills/agent-first-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-first-data
-description: Apply Agent-First Data naming, redaction, formatting, protocol envelope, logging, and CLI lint/validate workflows when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, or CLI output in any language. Use proactively before adding, renaming, serializing, or changing public API, wire, database, or persistent field names that may need AFDATA suffixes.
+description: Apply and review the formal Agent-First Data specification using the Rust/Go/Python/TypeScript libraries or afdata CLI for naming, redaction, formatting, protocol envelopes, logging, linting, validation, and reading or safely editing structured JSON/TOML/YAML/dotenv/INI documents by dot-path. Use proactively when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, CLI output, compatibility-sensitive public and persistent field names, or when reading or editing a config/document file from the shell.
 ---
 
 <!-- Canonical source: skills/agent-first-data/SKILL.md.
@@ -11,12 +11,66 @@ description: Apply Agent-First Data naming, redaction, formatting, protocol enve
 
 Use AFDATA when naming fields or reviewing structured output. The contract is naming-based: suffixes communicate units, formatting, and redaction semantics without relying on free-text inference.
 
-## Read references as needed
+## Specification workflow
+
+Treat the formal specification as normative, not the skill summary or an
+example payload. In a repository checkout, read these spore-root-relative
+sources as needed:
+
+- `spec/agent-first-data.md` — complete cross-language naming, formatting,
+  redaction, protocol, logging, and CLI contract.
+- `spec/registry.json` — exact suffix metadata.
+- `spec/protocol-v1.schema.json` — protocol event schema.
+- `spec/fixtures/` — cross-language conformance cases.
+
+When only the installed skill is available, use the bundled equivalents:
 
 - `references/rules.md` — detailed suffix rules, output formatting, protocol templates, logging, CLI flags, and review checklist.
 - `references/registry.json` — machine-readable suffix registry; use this as the exact source for suffix metadata.
 - `references/protocol-v1.schema.json` — protocol event schema for `kind:"result"`, `kind:"error"`, `kind:"progress"`, and `kind:"log"` envelopes.
 
+If an example or README conflicts with the formal spec, follow the spec and
+report the discrepancy. Do not invent suffix meanings or reduce the protocol
+schema.
+
+## Library workflow
+
+Use the library at serialization boundaries so redaction and formatting are
+not reimplemented ad hoc. Rust applications can build a typed protocol event
+and render it in the required output format:
+
+```bash
+cargo add agent-first-data --no-default-features
+pip install agent-first-data
+npm install agent-first-data
+go get github.com/agentfirstkit/agent-first-data/go
+```
+
+```rust
+use agent_first_data::{json_result, render, OutputFormat, OutputOptions};
+use serde_json::json;
+
+let event = json_result(json!({
+    "latency_ms": 1280,
+    "api_key_secret": "sk-live-example",
+})).build();
+let rendered = render(event.as_value(), OutputFormat::Json, &OutputOptions::default());
+assert!(rendered.contains("\"api_key_secret\":\"***\""));
+```
+
+For a finite CLI execution implemented in Rust, create one `CliEmitter`, select
+`OutputFormat` through `cli_parse_output`, enable strict protocol, and emit one
+terminal result or error. Handle version before clap with
+`cli_handle_version_or_continue(raw_args, name, version)`.
+For non-CLI HTTP/MCP/SSE serialization, call `redacted_value()` or
+`redact_url_secrets()` explicitly at the boundary.
+
+The same library contract is available for Go, Python, and TypeScript. Use the
+runtime's native names while preserving the same builders, output formats,
+redaction behavior, registry, schema, and conformance fixtures; consult its
+root-level `go/README.md`, `python/README.md`, or `typescript/README.md` when
+working in that runtime.
+
 ## Naming and redaction decisions
 
 - Add unit suffixes to ambiguous numeric fields: `_ms`, `_s`, `_bytes`, `_percent`, `_sats`, `_msats`, currency suffixes, and timestamp suffixes.
@@ -28,32 +82,93 @@ Use AFDATA when naming fields or reviewing structured output. The contract is na
 ## Evaluation rules
 
 - Trigger this skill for field naming, structured output, configs, logs, CLI output, protocol events, MCP/HTTP/SSE payloads, database columns, wire fields, or persisted JSON. Do not wait for the user to say "AFDATA" when the work changes those surfaces.
-- Treat `references/registry.json` and `references/protocol-v1.schema.json` as authoritative. Do not replace them with invented suffix meanings, a reduced schema, or free-text interpretation.
+- In a repository checkout, treat `spec/agent-first-data.md`,
+  `spec/registry.json`, and `spec/protocol-v1.schema.json` as authoritative; in
+  an installed skill, use their bundled `references/` equivalents. Do not
+  replace them with invented suffix meanings, a reduced schema, or free-text
+  interpretation.
 - For secrets, fix the field name or serializer configuration. Use `_secret` or configured exact secret names; do not rely on scanning arbitrary strings or object debug output.
 - Run `afdata lint` on JSON/JSONL examples, JSON Schema, MCP schemas, or serialized samples when the CLI is available. Run `afdata validate` on finite protocol events/streams. If a check cannot run, report that explicitly.
 - Before modifying an external project's public API, wire format, database schema, or persisted field names, stop and report the compatibility impact; request approval before applying the change.
 
 ## Redaction behavior contract
 
-Fields named `_secret` or `_url` and values passing through AFDATA output formatters (`output_json`, `output_yaml`, `output_plain`) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
+Fields named `_secret` or `_url` and values passing through AFDATA output rendering (`render`, in any format) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
 
 ## Logging behavior contract
 
-One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `cli_output()` applies output formatting. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
+One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `render()` applies output formatting. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
 
 ## CLI workflow
 
-When the project has the `afdata` CLI available, use it for deterministic checks:
+Install `afdata` when a shell workflow needs validation, formatting, or skill
+administration without embedding a library:
 
 ```bash
-afdata lint <file-or-stdin>
-afdata validate <file-or-stdin>
+cargo install agent-first-data
+```
+
+Use it for deterministic checks:
+
+```bash
+afdata lint payload.json
+afdata validate events.jsonl
+afdata render payload.json --output yaml
+afdata skill validate skills/example-skill
 ```
 
 - Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, or MCP input/output schemas.
 - Run `afdata validate` for AFDATA protocol events or finite event streams.
+- Run `afdata render` to apply AFDATA redaction/formatting to arbitrary JSON or JSONL. Omit the input path to read stdin. `--output` accepts `json`, `yaml`, or
+  `plain`; JSON and YAML keep original keys/values (structure-preserving), Plain is the lossy human renderer.
 - Treat findings as contract issues unless the owning tool intentionally documents a non-AFDATA field.
 
+## Document workflow
+
+Use `show`/`get`/`value` to read a JSON, TOML, YAML, dotenv, or INI document
+and `set`/`add`/`remove`/`unset` to edit one in place, instead of `sed`,
+regular expressions, or a generic reserializer — those can reorder keys, drop
+comments, or change quoting/anchors in the rest of the file.
+
+- `show` returns the whole document as one AFDATA record; use it for batch
+  inspection, and pass every known sensitive legacy field name with
+  `--secret-name FIELD` (an exact field name, not a dot-path).
+- `get <KEY>` returns one dot-path value as an AFDATA record. A secret-named
+  leaf (`_secret`/`_SECRET`, or an exact `--secret-name` match) is still
+  redacted to `"***"` even though the caller targeted it directly — use
+  `value --reveal-secret` when the real value is genuinely needed.
+- `value <KEY>` writes only the raw scalar to stdout, with no AFDATA envelope
+  and no forced trailing newline, for direct use in shell substitution:
+  `value=$(afdata value server.host config.toml)` (KEY then FILE). Only
+  scalars are supported; an array or object errors with `path <KEY> is not a
+  scalar` (exit 1) — use `get`/`show` for a subtree. A secret-named leaf errors unless
+  `--reveal-secret` is passed — there is no default bypass for a targeted read.
+- Read commands (`show`/`get`/`value`) take a positional FILE or fall back to
+  piped stdin, defaulting to JSON and rejecting an interactive TTY rather than
+  blocking. Mutation commands (`set`/`add`/`remove`/`unset`) always require
+  `--input-file PATH` and never read stdin.
+- Escape a literal dot as `\.` and a literal backslash as `\\` in a dot-path;
+  every command shares this grammar, so an unrecognized escape or empty
+  segment is always an error, never a guess.
+- `add`/`remove` operate on a keyed list — an array of objects addressed by a
+  slug — and always require an explicit `--slug-field FIELD`; the CLI never
+  infers an identity field. Keyed editing is implemented for JSON and YAML
+  only; TOML, dotenv, and INI return a structured "not implemented" error, so
+  edit their list entries by writing the whole value another way.
+- For `set`, choose exactly one secret source instead of a positional value
+  when the value must not land in shell history or `ps`: `--value-secret
+  VALUE` (convenient, but visible to argv/process listings),
+  `--value-secret-stdin` (pipe), `--value-secret-prompt` (human, terminal echo
+  off), or `--value-secret-fd FD` (Unix automation that needs stdin for
+  something else).
+- Mutations preserve the rest of the source document — comments, key order,
+  unrelated formatting — and refuse to write through a symlink or (on Unix) a
+  multi-link hardlink target. Treat a failed mutation as leaving the original
+  file untouched rather than assuming a partial write, and reread before
+  retrying. A format backend that isn't compiled in, or input outside the
+  documented dotenv/INI dialect, is a structured error to report, not a cue to
+  hand-edit the file.
+
 ## Review checklist
 
 1. Numeric fields with units carry the right suffix and safe integer/string representation.

package/assets/skills/agent-first-data/references/rules.md

@@ -107,7 +107,7 @@ Sub-cent precision — `_{code}_micro`, integer millionths (10⁻⁶) of the maj
 | `_secret` | redact the entire value/subtree to `***` | `api_key_secret: "sk-or-v1-abc..."` |
 | `_url` | scrub secrets *inside* the URL value, keep the rest | `callback_url: "https://h/cb?code_secret=..."` |
 
-All CLI output formats (JSON, YAML, Plain) automatically redact `_secret` fields. Matching recognizes `_secret` and `_SECRET` only — no mixed case. The entire `_secret` value/subtree becomes `***`, including objects and arrays. For legacy fields that cannot be renamed, configure `OutputOptions.redaction` with `secret_names`/`secretNames` such as `["api_key", "authorization"]`; names match exact field names at any nesting level; no trim, case folding, hyphen/underscore normalization, globs, regex, or substring matching. AFDATA does not define named redaction profiles; use the default, `secret_names`, `RedactionTraceOnly`, or `RedactionNone` deliberately at the serialization boundary. Callers that need schema-preserving YAML/plain rendering can pass `OutputOptions` with the `Raw` output style.
+All CLI output formats (JSON, YAML, Plain) automatically redact `_secret` fields. Matching recognizes `_secret` and `_SECRET` only — no mixed case. The entire `_secret` value/subtree becomes `***`, including objects and arrays. For legacy fields that cannot be renamed, configure `OutputOptions.redaction` with `secret_names`/`secretNames` such as `["api_key", "authorization"]`; names match exact field names at any nesting level; no trim, case folding, hyphen/underscore normalization, globs, regex, or substring matching. AFDATA does not define named redaction profiles; use the default policy `All`, `secret_names`, `TraceOnly`, or `Off` deliberately at the serialization boundary. YAML is always schema-preserving, like JSON. Callers that need schema-preserving Plain rendering can pass `OutputOptions` with the `Raw` output style.
 
 `***` means only one thing: AFDATA redacted a sensitive value. Do not use it for serialization failure, truncation, unsupported types, or “maybe secret” guesses.
 
@@ -158,15 +158,17 @@ ORM struct fields preserve the suffix: `duration_ms: i64`, not `duration: i64`.
 
 ## Part 2: Output Processing
 
-Three output formats via `output_json()`, `output_yaml()`, `output_plain()`. Default YAML and Plain apply key stripping + value formatting. Optional `options` (Python/TS keyword arg; Rust/Go `_with_options` variant).
+Three output formats via one entry point `render(value, format, options)` (`format` = json/yaml/plain). JSON and YAML are both **structure-preserving**: original keys, scalar types, and numeric semantics survive after redaction. Plain is the one **lossy/human** renderer — it strips formatting suffixes and reformats values for scanning. `options` is an optional keyword arg in Python/TS; Rust/Go pass `OutputOptions` explicitly.
 
 ### Formats
 
 - **JSON** — single-line, original keys, raw values, no sorting (machine-readable), secrets redacted
-- **YAML** — multi-line, formatting suffixes stripped, values formatted, secrets redacted by default
+- **YAML** — multi-line, original keys, raw values (same semantics as JSON), keys sorted, secrets redacted by default
 - **Plain** — single-line logfmt, formatting suffixes stripped, values formatted, secrets redacted by default
 
-### Key stripping (YAML and Plain)
+Rust gates YAML output behind the `yaml` Cargo feature (on by default, along with the rest of the default feature set). With `default-features = false` and `yaml` not re-enabled, `OutputFormat::Yaml` does not exist and `--output yaml` is rejected with a feature-requirement error instead of silently falling back to another format.
+
+### Key stripping (Plain only)
 
 Remove recognized formatting suffix from key. Longest match first, exact lowercase or uppercase only:
 
@@ -176,9 +178,9 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 4. `_msats`, `_sats`, `_bytes`, `_percent`, `_secret`
 5. `_jpy`, `_ns`, `_us`, `_ms`, `_s`
 
-`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
+`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret. JSON and YAML never strip suffixes — every key renders exactly as written.
 
-### Value formatting (YAML and Plain)
+### Value formatting (Plain only)
 
 - `_ms` with absolute value < 1000 → `{n}ms`; absolute value ≥ 1000 → seconds (`1280` → `1.28s`, `-1500` → `-1.5s`)
 - `_s`, `_ns`, `_us` → append unit (`3600s`, `450000ns`, `830μs`)
@@ -192,7 +194,7 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 - `_secret` → `***` (the redaction phase already replaced the subtree)
 - `_bcp47`, `_utc_offset`, `_rfc3339_date`, `_rfc3339_time` → pass through unchanged
 
-**Type constraints**: `_bytes`/`_epoch_*` require integer. `_usd_cents`/`_eur_cents`/`_jpy`/`_{code}_cents`/`_{code}_micro` require non-negative integer. Duration/Bitcoin/`_percent` accept any number. Wrong type → raw value + original key.
+**Type constraints**: `_bytes`/`_epoch_*` require integer. `_usd_cents`/`_eur_cents`/`_jpy`/`_{code}_cents`/`_{code}_micro` require non-negative integer. Duration/Bitcoin/`_percent` accept any number. Wrong type → raw value + original key. JSON and YAML never format values — a value renders exactly as its JSON type (numbers stay numbers, strings stay quoted strings, no unit/date/currency formatting).
 
 ### Plain logfmt details
 
@@ -204,7 +206,11 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 
 ### Key ordering
 
-YAML and Plain sort keys (after stripping) by UTF-16 code unit order (JCS, RFC 8785). For ASCII keys this equals byte-order sorting.
+YAML sorts keys by UTF-16 code unit order (JCS, RFC 8785) without stripping suffixes. Plain sorts keys the same way, but after stripping. For ASCII keys this equals byte-order sorting.
+
+### `PlainStyle` (Plain only)
+
+`PlainStyle` (`Readable`/`Raw`) only affects Plain: `Readable` (default) strips suffixes and formats values; `Raw` keeps original keys/values (still redacted). YAML ignores `PlainStyle` entirely — it is always structure-preserving, matching JSON.
 
 ---
 
@@ -269,17 +275,17 @@ Use the local language README for installation and the full overview/spec for AP
 
 Required cross-language behavior to rely on:
 
-- Output helpers redact before formatting: `output_json()`, `output_yaml()`, `output_plain()` (with optional `options` in Python/TS).
-- Use `redacted_value()` for raw HTTP/MCP/SSE serialization paths that bypass `output_json()`.
+- The single output entry point `render(value, format, options)` redacts before formatting (with optional `options` in Python/TS).
+- Use `redacted_value()` for raw HTTP/MCP/SSE serialization paths that bypass `render()`.
 - Use `redact_url_secrets()` for URLs embedded in log messages or prose before interpolating them into output.
-- Use `cli_parse_output()`, `cli_parse_log_filters()`, `cli_output()`, `build_cli_error()`, and the version helper for CLI tools instead of custom parsing/error envelopes.
+- Use `cli_parse_output()`, `cli_parse_log_filters()`, `render()`, `build_cli_error()`, and the version helper for CLI tools instead of custom parsing/error envelopes.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Rust CLIs should call `cli_handle_version_or_continue()` before clap parsing so `--version --output json|yaml|plain` emits a structured `kind:"result"` event with `result.version` instead of clap's plain text. Use `VersionConfig::conventional_default()` so bare `--version` stays human text while explicit `--output` remains structured.
+- Rust CLIs should call `cli_handle_version_or_continue(raw_args, name, version)` before clap parsing so `--version --output json|yaml|plain` emits a structured `kind:"result"` event with `result.code == "version"` and `result.version` instead of clap's plain text. Bare `--version` always stays human `<name> <version>` text; explicit `--output` is always structured — there is no configuration.
 - Use the protocol reader `decode_protocol_event(text)` to parse and strict-validate a single JSON text line, receiving a typed decoded event.
 
 ## AFDATA Logging
 
-Long-running services and processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) use a logging init function to capture the full process. One-time CLI output uses `json_log()` + `cli_output()` or `CliEmitter`.
+Long-running services and processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) use a logging init function to capture the full process. One-time CLI output uses `json_log()` + `render()` or `CliEmitter`.
 
 ### Init (Rust only; pick one format per process)
 
@@ -312,7 +318,7 @@ Log redaction is **by field name** (the same `_secret`/`_url` rule as all output
 CLI tools that use AFDATA should support output and logging flags:
 
 ```
---output json|yaml|plain    # default is tool-defined (interactive → yaml, scripting/logging → json)
+--output json|yaml|plain    # default is tool-defined (structured/scripting → json or yaml, human scanning → plain)
 --log startup,request,progress,retry,redirect
 --verbose                   # shorthand for all log categories
 ```

package/dist/cli.d.ts

@@ -21,18 +21,22 @@ export declare class LogFilters {
     constructor(entries: readonly string[]);
     /**
      * Check if an event matches the filter set.
-     * Returns false for empty filters, true if "all" or "*" is present,
-     * otherwise checks if event.toLowerCase() starts with any filter.
+     *
+     * An empty filter set returns false (filtering is opt-in). The single
+     * wildcard word "all" returns true ("*" is not special — one wildcard
+     * spelling, not two). Otherwise returns true iff event.toLowerCase() starts
+     * with any filter (prefix match); a mistyped filter simply matches nothing
+     * and silently emits no output.
      *
      * @example
      * const lf = new LogFilters(["query", "error"]);
      * lf.enabled("QueryStarted") // → true (starts with "query")
      * lf.enabled("debug") // → false
      *
-     * const all = new LogFilters([]);
-     * all.enabled("anything") // → false (empty)
+     * const none = new LogFilters([]);
+     * none.enabled("anything") // → false (empty)
      *
-     * const wild = new LogFilters(["*"]);
+     * const wild = new LogFilters(["all"]);
      * wild.enabled("anything") // → true
      */
     enabled(event: string): boolean;
@@ -48,13 +52,15 @@ export declare class LogFilters {
  */
 export declare function cliParseLogFilters(entries: string[]): LogFilters;
 /**
- * Dispatch output formatting by OutputFormat, with optional explicit redaction and style.
- * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ * Single public render entry point: dispatch a value or Event to
+ * JSON/YAML/plain text by OutputFormat, with optional explicit redaction and
+ * style. `options.style` (PlainStyle) affects plain (logfmt) output only;
+ * JSON and YAML are structure-preserving and ignore it.
  *
  * @example
- * cliOutput(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
+ * render(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
  */
-export declare function cliOutput(value: JsonValue | Event, format: OutputFormat, options?: OutputOptions): string;
+export declare function render(value: JsonValue | Event, format: OutputFormat, options?: OutputOptions): string;
 export type CliEventWriter = (line: string) => void;
 /** Stateful emitter for finite structured CLI executions. */
 export declare class CliEmitter {
@@ -79,16 +85,30 @@ export declare function cliRenderVersion(name: string, version: string, format?:
 /**
  * Render version output if --version/-V is present; otherwise return undefined.
  * Throws for malformed version requests, for example `--version --output xml`.
+ *
+ * One blessed behavior, not configurable: a bare version request renders
+ * conventional "<name> <version>" text; `--json` or `--output <fmt>` /
+ * `--output=<fmt>` alongside it selects the structured AFDATA payload
+ * instead.
+ *
+ * Only a top-level version request is recognized: scanning stops at the first
+ * positional argument (the subcommand) or `--`, so `tool sub --version <value>`
+ * leaves `--version` for the subcommand's parser rather than printing the
+ * tool version.
  */
-export declare function cliHandleVersionOrContinue(rawArgs: string[], name: string, version: string, defaultOutput?: OutputFormat | null, outputFlag?: string, allowOutputFormat?: boolean): string | undefined;
+export declare function cliHandleVersionOrContinue(rawArgs: string[], name: string, version: string): string | undefined;
 /**
- * Build a standard CLI parse error value.
+ * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.
- * Print with outputJson and exit with code 2.
+ * Print with render and exit with code 2.
+ *
+ * Always returns a strict-valid `kind:"error"` event with code `"cli_error"`.
+ * An empty `message` is replaced with a generic placeholder so the returned
+ * event stays strict-valid without throwing.
  *
  * @example
  * const err = buildCliError("--output: invalid value 'xml'");
- * console.log(outputJson(err));
+ * console.log(render(err, "json"));
  * process.exit(2);
  */
 export declare function buildCliError(message: string, hint?: string): Event;

package/dist/cli.js

@@ -1,7 +1,7 @@
 /**
  * AFDATA CLI helpers — output format parsing, log filter normalization, error building.
  */
-import { Event, jsonError, jsonResult, outputJson, outputYaml, outputPlain, validateProtocolEvent, } from "./format.js";
+import { Event, jsonError, jsonResult, formatJsonValue, formatYamlValue, formatPlainValue, validateProtocolEvent, } from "./format.js";
 /**
  * Parse the --output flag value into an OutputFormat.
  * Throws on unknown values; catch and pass message to buildCliError.
@@ -33,24 +33,28 @@ export class LogFilters {
     }
     /**
      * Check if an event matches the filter set.
-     * Returns false for empty filters, true if "all" or "*" is present,
-     * otherwise checks if event.toLowerCase() starts with any filter.
+     *
+     * An empty filter set returns false (filtering is opt-in). The single
+     * wildcard word "all" returns true ("*" is not special — one wildcard
+     * spelling, not two). Otherwise returns true iff event.toLowerCase() starts
+     * with any filter (prefix match); a mistyped filter simply matches nothing
+     * and silently emits no output.
      *
      * @example
      * const lf = new LogFilters(["query", "error"]);
      * lf.enabled("QueryStarted") // → true (starts with "query")
      * lf.enabled("debug") // → false
      *
-     * const all = new LogFilters([]);
-     * all.enabled("anything") // → false (empty)
+     * const none = new LogFilters([]);
+     * none.enabled("anything") // → false (empty)
      *
-     * const wild = new LogFilters(["*"]);
+     * const wild = new LogFilters(["all"]);
      * wild.enabled("anything") // → true
      */
     enabled(event) {
         if (this.filters.length === 0)
             return false;
-        if (this.filters.includes("all") || this.filters.includes("*"))
+        if (this.filters.includes("all"))
             return true;
         const eventLower = event.toLowerCase();
         for (const filter of this.filters) {
@@ -74,19 +78,21 @@ export function cliParseLogFilters(entries) {
     return new LogFilters(entries);
 }
 /**
- * Dispatch output formatting by OutputFormat, with optional explicit redaction and style.
- * JSON ignores OutputStyle and preserves original keys and values after redaction.
+ * Single public render entry point: dispatch a value or Event to
+ * JSON/YAML/plain text by OutputFormat, with optional explicit redaction and
+ * style. `options.style` (PlainStyle) affects plain (logfmt) output only;
+ * JSON and YAML are structure-preserving and ignore it.
  *
  * @example
- * cliOutput(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
+ * render(jsonResult({ ok: true }).build(), "plain") // → "kind=result result.ok=true"
  */
-export function cliOutput(value, format, options = {}) {
+export function render(value, format, options = {}) {
     const jsonValue = value instanceof Event ? value.toJSON() : value;
     if (format === "yaml")
-        return outputYaml(jsonValue, options);
+        return formatYamlValue(jsonValue, options);
     if (format === "plain")
-        return outputPlain(jsonValue, options);
-    return outputJson(jsonValue, options);
+        return formatPlainValue(jsonValue, options);
+    return formatJsonValue(jsonValue, options);
 }
 /** Stateful emitter for finite structured CLI executions. */
 export class CliEmitter {
@@ -121,7 +127,7 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${cliOutput(jsonValue, this.format, this.outputOptions)}\n`);
+        this.writer(`${render(jsonValue, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
@@ -141,14 +147,14 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${cliOutput(value, this.format, this.outputOptions)}\n`);
+        this.writer(`${render(value, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
 }
 /** Build a standard CLI version value. */
 export function buildCliVersion(version) {
-    return jsonResult({ version }).build();
+    return jsonResult({ code: "version", version }).build();
 }
 /**
  * Render CLI version output.
@@ -156,14 +162,24 @@ export function buildCliVersion(version) {
  * conventional "<name> <version>" text.
  */
 export function cliRenderVersion(name, version, format = null) {
-    const rendered = format === null ? `${name} ${version}` : cliOutput(buildCliVersion(version), format);
+    const rendered = format === null ? `${name} ${version}` : render(buildCliVersion(version), format);
     return `${rendered.replace(/\n+$/u, "")}\n`;
 }
 /**
  * Render version output if --version/-V is present; otherwise return undefined.
  * Throws for malformed version requests, for example `--version --output xml`.
+ *
+ * One blessed behavior, not configurable: a bare version request renders
+ * conventional "<name> <version>" text; `--json` or `--output <fmt>` /
+ * `--output=<fmt>` alongside it selects the structured AFDATA payload
+ * instead.
+ *
+ * Only a top-level version request is recognized: scanning stops at the first
+ * positional argument (the subcommand) or `--`, so `tool sub --version <value>`
+ * leaves `--version` for the subcommand's parser rather than printing the
+ * tool version.
  */
-export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput = null, outputFlag = "--output", allowOutputFormat = true) {
+export function cliHandleVersionOrContinue(rawArgs, name, version) {
     let versionRequested = false;
     let outputFormat;
     let outputError;
@@ -171,12 +187,17 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
         const arg = rawArgs[i];
         if (arg === "--")
             break;
+        // The first positional argument marks the subcommand boundary. Past it,
+        // --version and -V belong to the subcommand's own parser, matching
+        // git/cargo/clap: this pre-parser only owns a top-level version request.
+        if (!arg.startsWith("-"))
+            break;
         if (arg === "--version" || arg === "-V") {
             versionRequested = true;
             i += 1;
             continue;
         }
-        if (allowOutputFormat && arg === "--json") {
+        if (arg === "--json") {
             if (outputFormat !== undefined && outputFormat !== "json") {
                 outputError = new Error("conflicting output formats: --json conflicts with previous output format");
             }
@@ -186,24 +207,24 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
             i += 1;
             continue;
         }
-        if (allowOutputFormat && (arg === outputFlag || arg.startsWith(`${outputFlag}=`))) {
+        if (arg === "--output" || arg.startsWith("--output=")) {
             let value;
             let step = 1;
-            if (arg.startsWith(`${outputFlag}=`)) {
-                value = arg.slice(outputFlag.length + 1);
+            if (arg.startsWith("--output=")) {
+                value = arg.slice("--output=".length);
             }
             else if (rawArgs[i + 1] !== undefined && !rawArgs[i + 1].startsWith("-")) {
                 value = rawArgs[i + 1];
                 step = 2;
             }
             if (value === undefined) {
-                outputError = new Error(`missing value for ${outputFlag}: expected json, yaml, or plain`);
+                outputError = new Error("missing value for --output: expected json, yaml, or plain");
             }
             else {
                 try {
                     const parsedOutput = cliParseOutput(value);
                     if (outputFormat !== undefined && outputFormat !== parsedOutput) {
-                        outputError = new Error(`conflicting output formats: ${outputFlag} ${value} conflicts with previous output format`);
+                        outputError = new Error(`conflicting output formats: --output ${value} conflicts with previous output format`);
                     }
                     else {
                         outputFormat = parsedOutput;
@@ -222,18 +243,23 @@ export function cliHandleVersionOrContinue(rawArgs, name, version, defaultOutput
         return undefined;
     if (outputError !== undefined)
         throw outputError;
-    return cliRenderVersion(name, version, allowOutputFormat && outputFormat !== undefined ? outputFormat : defaultOutput);
+    return cliRenderVersion(name, version, outputFormat ?? null);
 }
 /**
- * Build a standard CLI parse error value.
+ * Build a standard CLI parse error value. This function cannot fail.
  * Use when flag parsing fails or a flag value is invalid.
- * Print with outputJson and exit with code 2.
+ * Print with render and exit with code 2.
+ *
+ * Always returns a strict-valid `kind:"error"` event with code `"cli_error"`.
+ * An empty `message` is replaced with a generic placeholder so the returned
+ * event stays strict-valid without throwing.
  *
  * @example
  * const err = buildCliError("--output: invalid value 'xml'");
- * console.log(outputJson(err));
+ * console.log(render(err, "json"));
  * process.exit(2);
  */
 export function buildCliError(message, hint) {
-    return jsonError("cli_error", message).hintIfSome(hint).build();
+    const msg = message && message !== "" ? message : "unspecified error";
+    return jsonError("cli_error", msg).hintIfSome(hint).build();
 }

package/dist/format.d.ts

@@ -2,9 +2,10 @@
  * AFDATA output formatting and protocol templates.
  *
  * Public APIs include protocol event builders, redactedValue (covers _secret
- * and _url fields), output formatters, redactUrlSecrets,
- * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47,
- * RedactionPolicy, OutputStyle, and OutputOptions.
+ * and _url fields), redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date,
+ * isValidRfc3339Time, isValidRfc3339, isValidBcp47, RedactionPolicy,
+ * PlainStyle, and OutputOptions. The single render entry point (`render`)
+ * lives in cli.ts and calls this module's internal JSON/YAML/plain formatters.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -28,9 +29,9 @@ export declare class EventBuildError extends Error {
 export declare class JsonResultBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 export declare class JsonErrorBuilder {
@@ -56,17 +57,17 @@ export declare class JsonErrorBuilder {
 export declare class JsonProgressBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 export declare class JsonLogBuilder {
     private readonly payload;
     private traceValue;
-    private issues;
     constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
+    /** Build the event. This builder cannot fail. */
     build(): Event;
 }
 /** Fluent builder for result events. */
@@ -116,11 +117,13 @@ export declare class EventDecodeError extends Error {
  * return a typed decoded event.
  */
 export declare function decodeProtocolEvent(text: string): DecodedEvent;
+/** Which fields a redaction pass scrubs. The default is `All`. */
 export declare enum RedactionPolicy {
-    RedactionTraceOnly = "RedactionTraceOnly",
-    RedactionNone = "RedactionNone"
+    All = "All",
+    TraceOnly = "TraceOnly",
+    Off = "Off"
 }
-export declare enum OutputStyle {
+export declare enum PlainStyle {
     Readable = "Readable",
     Raw = "Raw"
 }
@@ -135,17 +138,33 @@ export type OutputOptions = {
          */
         secretNames?: readonly string[];
     };
-    /** Rendering style for YAML/plain output. Omitted means readable. */
-    style?: OutputStyle;
+    /** Rendering style for plain (logfmt) output only. Omitted means readable.
+     * JSON and YAML are structure-preserving and ignore this setting. */
+    style?: PlainStyle;
 };
 /** Convenience: build OutputOptions scoped to a RedactionPolicy. */
 export declare function outputOptionsForPolicy(policy: RedactionPolicy): OutputOptions;
-/** Format as single-line JSON. Secrets redacted, original keys, raw values. */
-export declare function outputJson(value: JsonValue | Event, options?: OutputOptions): string;
-/** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
-export declare function outputYaml(value: JsonValue | Event, options?: OutputOptions): string;
-/** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
-export declare function outputPlain(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as single-line JSON. Secrets redacted, original keys, raw values.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatJsonValue(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as multi-line YAML. Structure-preserving: like JSON, original keys,
+ * scalar types, and numeric semantics are kept after redaction; secrets are
+ * still redacted. `options.style` is ignored — YAML output does not vary by
+ * PlainStyle.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatYamlValue(value: JsonValue | Event, options?: OutputOptions): string;
+/**
+ * Format as single-line logfmt. Keys stripped, values formatted, secrets redacted.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export declare function formatPlainValue(value: JsonValue | Event, options?: OutputOptions): string;
 /** Return a JSON-safe copy with redaction options applied (default: full _secret redaction). */
 export declare function redactedValue(value: unknown, options?: {
     policy?: RedactionPolicy;

package/dist/format.js

@@ -2,9 +2,10 @@
  * AFDATA output formatting and protocol templates.
  *
  * Public APIs include protocol event builders, redactedValue (covers _secret
- * and _url fields), output formatters, redactUrlSecrets,
- * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47,
- * RedactionPolicy, OutputStyle, and OutputOptions.
+ * and _url fields), redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date,
+ * isValidRfc3339Time, isValidRfc3339, isValidBcp47, RedactionPolicy,
+ * PlainStyle, and OutputOptions. The single render entry point (`render`)
+ * lives in cli.ts and calls this module's internal JSON/YAML/plain formatters.
  */
 // ═══════════════════════════════════════════
 // Event type: opaque branded wrapper
@@ -46,25 +47,17 @@ export class EventBuildError extends Error {
 export class JsonResultBuilder {
     payload;
     traceValue = {};
-    issues = [];
     constructor(payload) {
         this.payload = payload;
     }
     trace(value) {
         if (value !== undefined) {
-            if (!isObject(value)) {
-                this.issues.push("trace must be a JSON object");
-            }
-            else {
-                this.traceValue = value;
-            }
+            this.traceValue = value;
         }
         return this;
     }
+    /** Build the event. This builder cannot fail. */
     build() {
-        if (this.issues.length > 0) {
-            throw new EventBuildError(`Failed to build result event: ${this.issues.join("; ")}`, this.issues);
-        }
         const m = { kind: "result", result: this.payload, trace: this.traceValue };
         return new Event(m);
     }
@@ -178,25 +171,17 @@ export class JsonErrorBuilder {
 export class JsonProgressBuilder {
     payload;
     traceValue = {};
-    issues = [];
     constructor(payload) {
         this.payload = payload;
     }
     trace(value) {
         if (value !== undefined) {
-            if (!isObject(value)) {
-                this.issues.push("trace must be a JSON object");
-            }
-            else {
-                this.traceValue = value;
-            }
+            this.traceValue = value;
         }
         return this;
     }
+    /** Build the event. This builder cannot fail. */
     build() {
-        if (this.issues.length > 0) {
-            throw new EventBuildError(`Failed to build progress event: ${this.issues.join("; ")}`, this.issues);
-        }
         const m = { kind: "progress", progress: this.payload, trace: this.traceValue };
         return new Event(m);
     }
@@ -204,25 +189,17 @@ export class JsonProgressBuilder {
 export class JsonLogBuilder {
     payload;
     traceValue = {};
-    issues = [];
     constructor(payload) {
         this.payload = payload;
     }
     trace(value) {
         if (value !== undefined) {
-            if (!isObject(value)) {
-                this.issues.push("trace must be a JSON object");
-            }
-            else {
-                this.traceValue = value;
-            }
+            this.traceValue = value;
         }
         return this;
     }
+    /** Build the event. This builder cannot fail. */
     build() {
-        if (this.issues.length > 0) {
-            throw new EventBuildError(`Failed to build log event: ${this.issues.join("; ")}`, this.issues);
-        }
         const m = { kind: "log", log: this.payload, trace: this.traceValue };
         return new Event(m);
     }
@@ -388,46 +365,58 @@ export function decodeProtocolEvent(text) {
     }
 }
 // ═══════════════════════════════════════════
-// Public API: Output Formatters
+// Internal: Output Formatters (called by render() in cli.ts)
 // ═══════════════════════════════════════════
+/** Which fields a redaction pass scrubs. The default is `All`. */
 export var RedactionPolicy;
 (function (RedactionPolicy) {
-    RedactionPolicy["RedactionTraceOnly"] = "RedactionTraceOnly";
-    RedactionPolicy["RedactionNone"] = "RedactionNone";
+    RedactionPolicy["All"] = "All";
+    RedactionPolicy["TraceOnly"] = "TraceOnly";
+    RedactionPolicy["Off"] = "Off";
 })(RedactionPolicy || (RedactionPolicy = {}));
-export var OutputStyle;
-(function (OutputStyle) {
-    OutputStyle["Readable"] = "Readable";
-    OutputStyle["Raw"] = "Raw";
-})(OutputStyle || (OutputStyle = {}));
+export var PlainStyle;
+(function (PlainStyle) {
+    PlainStyle["Readable"] = "Readable";
+    PlainStyle["Raw"] = "Raw";
+})(PlainStyle || (PlainStyle = {}));
 /** Convenience: build OutputOptions scoped to a RedactionPolicy. */
 export function outputOptionsForPolicy(policy) {
     return { redaction: { policy } };
 }
-/** Format as single-line JSON. Secrets redacted, original keys, raw values. */
-export function outputJson(value, options = {}) {
+/**
+ * Format as single-line JSON. Secrets redacted, original keys, raw values.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export function formatJsonValue(value, options = {}) {
     const unwrapped = value instanceof Event ? value.toJSON() : value;
     return JSON.stringify(redactedValue(unwrapped, options.redaction ?? {}));
 }
-/** Format as multi-line YAML. Keys stripped, values formatted, secrets redacted. */
-export function outputYaml(value, options = {}) {
+/**
+ * Format as multi-line YAML. Structure-preserving: like JSON, original keys,
+ * scalar types, and numeric semantics are kept after redaction; secrets are
+ * still redacted. `options.style` is ignored — YAML output does not vary by
+ * PlainStyle.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export function formatYamlValue(value, options = {}) {
     const unwrapped = value instanceof Event ? value.toJSON() : value;
     const redacted = redactedValue(unwrapped, options.redaction ?? {});
     const lines = ["---"];
-    if (options.style === OutputStyle.Raw) {
-        renderYamlRaw(redacted, 0, lines);
-    }
-    else {
-        renderYamlProcessed(redacted, 0, lines);
-    }
+    renderYamlRaw(redacted, 0, lines);
     return lines.join("\n");
 }
-/** Format as single-line logfmt. Keys stripped, values formatted, secrets redacted. */
-export function outputPlain(value, options = {}) {
+/**
+ * Format as single-line logfmt. Keys stripped, values formatted, secrets redacted.
+ * Internal: called by `render` in cli.ts, which is the single public render
+ * entry point. Not re-exported from index.ts.
+ */
+export function formatPlainValue(value, options = {}) {
     const unwrapped = value instanceof Event ? value.toJSON() : value;
     const redacted = redactedValue(unwrapped, options.redaction ?? {});
     const pairs = [];
-    if (options.style === OutputStyle.Raw) {
+    if (options.style === PlainStyle.Raw) {
         collectPlainPairsRaw(redacted, "", pairs);
     }
     else {
@@ -668,15 +657,15 @@ function applyRedactionOptions(value, redactionOptions) {
 }
 function applyRedactionPolicyWithContext(value, redactionPolicy, context) {
     switch (redactionPolicy) {
-        case RedactionPolicy.RedactionTraceOnly:
+        case RedactionPolicy.TraceOnly:
             if (isObject(value) && value.trace !== undefined) {
                 redactSecrets(value.trace, context);
             }
             break;
-        case RedactionPolicy.RedactionNone:
+        case RedactionPolicy.Off:
             break;
         default:
-            // Empty/unknown policy falls back to default full redaction.
+            // undefined or RedactionPolicy.All = full redaction (default).
             redactSecrets(value, context);
             break;
     }
@@ -1184,47 +1173,6 @@ function extractCurrencyCodeFromStem(stem) {
 // ═══════════════════════════════════════════
 // YAML Rendering
 // ═══════════════════════════════════════════
-function renderYamlProcessed(value, indent, lines) {
-    const prefix = "  ".repeat(indent);
-    if (!isObject(value)) {
-        lines.push(`${prefix}${yamlScalar(value)}`);
-        return;
-    }
-    for (const pf of processObjectFields(value)) {
-        if (pf.formatted !== null) {
-            lines.push(`${prefix}${yamlKey(pf.key)}: "${escapeYamlStr(pf.formatted)}"`);
-        }
-        else if (isObject(pf.value)) {
-            if (Object.keys(pf.value).length > 0) {
-                lines.push(`${prefix}${yamlKey(pf.key)}:`);
-                renderYamlProcessed(pf.value, indent + 1, lines);
-            }
-            else {
-                lines.push(`${prefix}${yamlKey(pf.key)}: {}`);
-            }
-        }
-        else if (Array.isArray(pf.value)) {
-            if (pf.value.length === 0) {
-                lines.push(`${prefix}${yamlKey(pf.key)}: []`);
-            }
-            else {
-                lines.push(`${prefix}${yamlKey(pf.key)}:`);
-                for (const item of pf.value) {
-                    if (isObject(item)) {
-                        lines.push(`${prefix}  -`);
-                        renderYamlProcessed(item, indent + 2, lines);
-                    }
-                    else {
-                        lines.push(`${prefix}  - ${yamlScalar(item)}`);
-                    }
-                }
-            }
-        }
-        else {
-            lines.push(`${prefix}${yamlKey(pf.key)}: ${yamlScalar(pf.value)}`);
-        }
-    }
-}
 function renderYamlRaw(value, indent, lines) {
     const prefix = "  ".repeat(indent);
     if (isObject(value)) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, OutputStyle, type OutputOptions, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
-export { type OutputFormat, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, PlainStyle, type OutputOptions, outputOptionsForPolicy, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
+export { type OutputFormat, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, OutputStyle, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
-export { CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, PlainStyle, outputOptionsForPolicy, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
+export { CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/skill.d.ts

@@ -6,7 +6,7 @@
  * supported coding agents (Codex, Claude Code, opencode, Hermes).
  *
  * The function performs the filesystem work and returns the protocol value (rendered by
- * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
+ * the caller with `render`) or throws a {@link SkillError}. It never writes to
  * stdout/stderr itself.
  */
 /**
@@ -67,7 +67,7 @@ export interface SkillUninstallStatus {
 }
 /**
  * The result of a skill action. Read fields off the discriminated union (narrow on
- * `code`), or pass it to `cliOutput` to serialize — every field is already JSON-shaped.
+ * `code`), or pass it to `render` to serialize — every field is already JSON-shaped.
  */
 export type SkillReport = {
     code: "skill_status";
@@ -90,7 +90,7 @@ export type SkillReport = {
 };
 /**
  * Install, uninstall, or report status of `spec`'s skill across the selected agent
- * target(s). Returns the protocol value (caller renders with `cliOutput`) or throws a
+ * target(s). Returns the protocol value (caller renders with `render`) or throws a
  * {@link SkillError}. Does not touch stdout/stderr.
  */
 export declare function runSkillAdmin(spec: SkillSpec, action: SkillAction, options: SkillOptions): SkillReport;

package/dist/skill.js

@@ -6,7 +6,7 @@
  * supported coding agents (Codex, Claude Code, opencode, Hermes).
  *
  * The function performs the filesystem work and returns the protocol value (rendered by
- * the caller with `cliOutput`) or throws a {@link SkillError}. It never writes to
+ * the caller with `render`) or throws a {@link SkillError}. It never writes to
  * stdout/stderr itself.
  */
 import * as fs from "node:fs";
@@ -26,7 +26,7 @@ export class SkillError extends Error {
 }
 /**
  * Install, uninstall, or report status of `spec`'s skill across the selected agent
- * target(s). Returns the protocol value (caller renders with `cliOutput`) or throws a
+ * target(s). Returns the protocol value (caller renders with `render`) or throws a
  * {@link SkillError}. Does not touch stdout/stderr.
  */
 export function runSkillAdmin(spec, action, options) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-first-data",
-  "version": "0.17.2",
-  "description": "A naming convention that lets AI agents understand your data without being told what it means.",
+  "version": "0.18.0",
+  "description": "A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.",
   "license": "MIT",
   "repository": {
     "type": "git",