agent-first-data 0.18.0 → 0.19.0

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

@@ -1,6 +1,6 @@
 ---
 name: agent-first-data
-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.
+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 (and the +++/--- frontmatter block of a Markdown page) 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/Markdown-frontmatter file from the shell.
 ---
 
 <!-- Canonical source: skills/agent-first-data/SKILL.md.
@@ -97,7 +97,7 @@ Fields named `_secret` or `_url` and values passing through AFDATA output render
 
 ## Logging behavior contract
 
-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.
+One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `render()` applies output formatting. Construct the emitter in finite mode for a one-shot command (`result`→stdout, `error`/`progress`/`log`→stderr) or stream mode for an interleaved event stream (all events on one destination) — see the Output stream contract. 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
 
@@ -117,63 +117,164 @@ 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.
+- Every command's first positional is its input; `-` reads stdin explicitly.
+  There is no implicit stdin fallback, and omitting the input is always a
+  usage error that names the fix — never a hang.
+- Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, MCP input/output
+  schemas, or a structured document (`--input-format`/extension detection
+  picks TOML/YAML/dotenv/INI; JSON/JSONL stays the default dual-mode input).
 - 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.
+- Run `afdata render` to apply AFDATA redaction/formatting to arbitrary JSON
+  or JSONL. `--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.
+
+## Output stream contract
+
+AFDATA CLIs route protocol events by consumption mode, not by event shape.
+
+- A **finite one-shot command** (the default) puts `kind:"result"` on `stdout`
+  and `kind:"error"`/`progress`/`log` on `stderr`, so `x=$(tool …)` never
+  captures a failure as data, `tool … >/dev/null` never swallows a diagnostic,
+  and `tool … | next` never pipes an error envelope in as input. The exit
+  code — not the stream — is set by the terminal kind; routing follows `kind`,
+  not the exit code.
+- An **event stream** (interleaved events consumed in order) keeps every event,
+  including `error`, on one stream so ordering survives.
+- `afdata` and any CLI built on the library expose `--output-to
+  <split|stdout|stderr>` (default `split`). `stdout`/`stderr` collapse the whole
+  stream — errors included — onto one destination, for a consumer that would
+  rather read one stream and branch on `kind`. `--output` picks the format,
+  `--output-to` picks the destination. Send an event stream to a file by
+  collapsing it (`--output-to stdout`) and redirecting (`--stdout-file PATH`).
+- The raw-scalar readers (`value`/`paths`/`keys`) are intrinsically split (raw
+  data on `stdout`, error envelope on `stderr`) and reject a non-default
+  `--output-to`.
+- When building a CLI on the library, choose the mode by how the output is
+  consumed — do not reflexively pick finite. A plain one-shot shell command uses
+  **finite** mode (errors → stderr, so shell capture and pipelines stay safe). A
+  tool whose output is itself an event stream (interleaved `progress`/`log` then
+  a terminal `result`/`error` — e.g. streaming query rows), or that is
+  agent-facing and wants the caller to read a single structured channel and
+  branch on `kind`, uses **stream/unified** mode (every event, errors included,
+  on `stdout`). A stream's terminal error MUST stay on the stream, so such a tool
+  keeps even its usage errors on `stdout` for one consistent channel. Never write
+  to `stderr` ad hoc — route every diagnostic through the emitter so redaction
+  and framing still apply.
+- Emit a terminal event with the emitter's `finish` / `finish_result` helpers,
+  which map the write outcome to a broken-pipe-safe process exit code (success →
+  the given code, a hung-up reader → 0, any other write failure → a nonzero
+  output-failure code) instead of hand-rolling that dance — they work in either
+  mode (the emitter's mode decides the stream; `finish` only maps the outcome).
+  Construct an error with the error builder (`json_error(code, message)` with
+  `hint`/`retryable`/extra fields as needed) — that builder *is* the error type —
+  and pass the built event to `finish`; there is no separate error-emitting
+  convenience.
 
 ## 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
+Use `get`/`value`/`paths`/`keys` 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. Every
+document command's first positional is `FILE` (or `-` for stdin on a read
+command); mutation commands never read stdin and reject `-` as a usage error.
+To edit only the metadata block of a Markdown page, pass `--input-format
+toml-frontmatter` (a `+++` block) or `yaml-frontmatter` (a `---` block): the
+same read/mutate commands then address dot-paths inside the frontmatter and
+leave the Markdown body byte-for-byte untouched. Frontmatter is never
+auto-detected — the format must be named explicitly, since extension detection
+only ever resolves to a whole-file format — so reach for it deliberately
+instead of `sed`-ing a page's `+++`/`---` header.
+
+- `get FILE` returns the whole document as one AFDATA record
+  (`code:"document"`); `get FILE KEY` narrows it to one dot-path value in the
+  same shape. Pass every known sensitive legacy field name with
+  `--secret-name FIELD` (an exact field name, not a dot-path). 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.
+  redacted to `"***"` even when directly targeted — use `value
+  --reveal-secret` when the real value is genuinely needed.
+- `value FILE 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 config.toml server.host)`. Only scalars
+  are supported; a container errors (`document_not_scalar`) — use `get` for a
+  subtree. A secret-named leaf errors (`document_secret_redacted`) unless
+  `--reveal-secret` is passed. On any failure `value`'s stdout is always
+  empty — the error envelope goes to stderr instead — so
+  `port=$(afdata value config.toml server.port)` never captures a JSON error
+  as data. `--default VAL` prints `VAL` instead of erroring when the path is
+  absent or the value is `null` (an empty string is a real value and does not
+  trigger it), collapsing the common "read or fall back" shell idiom into one
+  call with no `2>/dev/null` guard needed.
+- `paths FILE [KEY]` and `keys FILE [KEY]` enumerate a container's immediate
+  children, one per line, with the same empty-stdout-on-failure contract as
+  `value`. **`paths` output feeds back into afdata** (full grammar-escaped
+  dot-paths from the root — pipe straight into `value`/`get`/`unset` or
+  extend with `"$p.field"`); **`keys` output goes to external tools** (raw,
+  unescaped key names/array indices — what a package manager or another CLI
+  expects). Never use `paths`'s output as a literal name, or `keys`'s output
+  as a dot-path — they only diverge on a key containing a dot or space, so
+  the wrong one works until it silently doesn't. A scalar target errors
+  (`document_not_container`); `--missing-ok` turns a missing KEY specifically
+  into empty output + exit 0 (other errors still fail). Path grammar does not
+  escape spaces or other IFS characters, so the only correct consumption
+  shape is a `while IFS= read -r` loop, never `for x in $(...)`:
+
+  ```sh
+  while IFS= read -r p; do
+      afdata value config.toml "$p.slug"
+  done < <(afdata paths config.toml extra.tools)
+  ```
 - 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.
+  every command shares this grammar (`paths`'s escaped output re-parses
+  through the exact same rules it was emitted from), 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).
+  edit their list entries by writing the whole value another way. Adding a
+  slug that already exists, or removing/unsetting one that does not, is
+  always an error (`document_slug_exists`/`document_slug_not_found`/
+  `document_path_not_found`) — never a silent no-op; wrap the call yourself
+  when idempotence is wanted.
+- `set`'s bare VALUE (and `add`'s `FIELD=VALUE`) is always a plain string —
+  no shape-guessing, so a leading-zero ID or SHA never gets reinterpreted as
+  a number. Writing an exact type goes through `--value-type
+  string|number|bool|null|json` instead; `json` is the only entry point for
+  an array or object. Overwriting an *existing* scalar of a different kind
+  with a bare VALUE is a usage error that names both escape hatches (keep the
+  type with `--value-type <kind>`, or convert explicitly with `--value-type
+  string`) — a brand-new key never needs `--value-type`.
+- For `set`, choose `--secret-from stdin|prompt|fd:<N>|env:<VAR>` instead of a
+  positional value when the value must not land in shell history or `ps`:
+  `stdin` (pipe), `prompt` (human, terminal echo off), `fd:N` (Unix
+  automation that needs stdin for something else), or `env:VAR` (already in
+  the process environment). There is no inline `--secret-from=VALUE`-style
+  argv source — that would defeat the point.
 - 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.
+  hand-edit the file. A successful mutation's result carries the `path`
+  actually written, for confirming which file changed when scripting several.
+- Branch on `error.code`, not the message text: document errors use stable
+  codes (`document_path_not_found`, `document_type_mismatch`,
+  `document_slug_not_found`, `document_slug_exists`, `document_parse_failed`,
+  `document_io_failed`, and a few narrower ones), while a malformed
+  invocation (`--input-format`, `--value-type`, `FIELD=VALUE`, a mutation
+  given `-`, …) is always `document_usage_error` at exit 2 — distinct from
+  every runtime document error, which exits 1.
 
 ## Review checklist
 
 1. Numeric fields with units carry the right suffix and safe integer/string representation.
 2. Timestamps use `_epoch_s`, `_epoch_ms`, decimal-string `_epoch_ns`, or `_rfc3339`.
 3. Secrets use `_secret` or configured exact secret names; no fallback path leaks them.
-4. CLI output uses AFDATA helpers for JSON/YAML/plain formatting and structured errors.
+4. CLI output uses AFDATA helpers for JSON/YAML/plain formatting and structured errors, and routes by consumption mode (finite: `result`→stdout, `error`→stderr; stream: one destination) rather than writing to stderr ad hoc.
 5. Logs use AFDATA structured logging or equivalent field-name redaction.
 6. Transport payloads preserve the protocol envelope when AFDATA compliance is claimed.

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

@@ -41,6 +41,8 @@ Integer vs string is not uniform across siblings: `_epoch_s` and `_epoch_ms` are
 
 `_rfc3339` needs a **mandatory** offset: `YYYY-MM-DDThh:mm:ss[.fff]` followed by `Z` or `±HH:MM`. A bare `2026-02-14T10:30:00` (no offset), a space instead of `T`, or a trailing IANA name (`...Asia/Shanghai`) is rejected by `afdata lint`. `afdata lint` also type-checks the numeric suffixes (durations `_s`/`_ms`/…, currency `_cents`/`_micro`/`_jpy`) and rejects a `_url` with internal whitespace or bare `user:pass@host` credentials.
 
+A `null` value is exempt from every suffix type constraint above: `null` means the field is absent/unset, not present-with-the-wrong-type, so `law_repeal_at_epoch_s: null` is not a `suffix_type_mismatch`. Absence may be written as an omitted key or as an explicit `null` — both are valid. The constraint applies only once a value is present and non-null.
+
 ### Strict string formats
 
 | Suffix | Format | Example |
@@ -225,22 +227,24 @@ Every protocol event uses `kind` plus one same-named payload:
 | `"result"` | Terminal success |
 | `"error"` | Terminal error with non-empty `error.code` and `error.message` |
 
-Channel policy:
-- `stdout` is the only protocol/log stream for machine-readable events
-- runtime protocol events MUST NOT be emitted on `stderr`
-- `stderr` is reserved for unrecoverable pre-protocol startup failures only
+Channel policy — the stream follows the consumption mode, not the event shape:
+- **Finite one-shot command (default):** `result` → `stdout`; `error`/`progress`/`log` → `stderr`. Routing follows `kind`, not the exit code, so `stdout` carries only successful payloads (`x=$(tool …)`, `tool | next`, and `tool >/dev/null` all stay safe).
+- **Event stream (interleaved events consumed in order):** every event, including `error`, stays on one stream so ordering survives; do not split it across `stdout`/`stderr`.
+- `--output-to <split|stdout|stderr>` (default `split`) selects the mode: `stdout`/`stderr` collapse the whole stream onto one destination. `--output` selects format, `--output-to` selects destination.
+- Raw-scalar readers (`value`/`paths`/`keys`) are intrinsically split and reject a non-default `--output-to`.
+- Choose the mode by how the output is consumed, not reflexively: a plain one-shot shell command uses **finite**; a tool whose output is itself an event stream (streaming rows, interleaved progress/log) or that is agent-facing and wants one structured channel uses **stream/unified** (all on `stdout`, errors included — a stream's terminal error must stay on the stream). When building a CLI on the library, emit terminal events with the emitter's `finish`/`finish_result` helpers (success → the given code, broken pipe → 0, other write failure → a nonzero output-failure code); build errors with the `json_error` builder (the error *type*, carrying hint/retryable/fields) and pass the event to `finish` — the helpers work in either mode.
 
 Optional stream redirection:
-- use `--stdout-file <PATH>` to redirect stdout bytes to a file
-- use `--stderr-file <PATH>` to redirect stderr bytes to a file
-- keep `--output` reserved for stdout format selection (`json`, `yaml`, `plain`, and help-specific `markdown`)
-- do not convert stderr diagnostics to JSON; Rust panics, Python tracebacks, and runtime errors stay native stderr bytes
+- use `--stdout-file <PATH>` / `--stderr-file <PATH>` to redirect a stream's bytes to a file (process-level, beneath the channel routing above)
+- send an event stream to a file by collapsing it (`--output-to stdout`) and redirecting (`--stdout-file <PATH>`); there is no separate events-file flag
+- native panics/tracebacks stay raw `stderr` bytes; in finite mode `stderr` also carries the formatted AFDATA `error`/`progress`/`log` envelopes, so a reader parses JSON lines and tolerates interleaved native bytes
 - treat this as stream destination control, not a second protocol stream and not stream copying
 - do not implement application-level rotation
 
 Recommended enforcement:
-- Rust: enable clippy `print_stderr = "deny"` and disallow `std::eprintln` / `std::io::stderr`
-- Go/Python/TypeScript: add source-policy tests that fail if runtime sources reference stderr APIs
+- route every `stderr` write through the emitter's diagnostic/error path; no ad-hoc stderr that bypasses the formatter in runtime code
+- Rust: keep native panic output as the only unstructured `stderr` (no stray `eprintln!` / `std::io::stderr`)
+- Go/Python/TypeScript: source-policy tests that fail on ad-hoc stderr APIs in runtime code, with the emitter's own sink as the sanctioned exception
 
 ### Templates
 
@@ -263,7 +267,7 @@ Startup payload fields are tool-defined; `config` is recommended, while `version
 | MCP tool | JSON |
 | SSE stream | JSONL |
 
-All use `kind` plus the same-named payload and optional `trace`. Do not split protocol events across `stdout` and `stderr`.
+All use `kind` plus the same-named payload and optional `trace`. An event stream keeps its events on one stream (never split); a finite one-shot command splits by `kind` (`result` → stdout, `error` → stderr) — see Channel policy.
 
 Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event and `retryable` on every error. Log and progress payloads remain tool-defined in both profiles. Use strict validation before claiming compliance with all recommendations.
 
@@ -351,4 +355,4 @@ Use this checklist when the skill is evaluating a change, not just documenting c
 7. Environment variables follow `UPPER_SNAKE_CASE` with the same suffixes
 8. One-time CLI output uses `json_log()`/`CliEmitter` + output helpers; long-running services use `afdata_tracing::try_init()` (Rust) to capture via tracing; other languages emit log events explicitly via builders
 9. Database columns use AFDATA suffixes on generic types (`duration_ms INTEGER`, not `duration INTEGER`); native types like `TIMESTAMPTZ` don't need suffixes
-10. CLI flag parsing uses `cli_parse_output()`/`cli_parse_log_filters()`/`build_cli_error()`/version helpers — not custom reimplementations; uses `try_parse()` not `parse()` in Rust so clap errors go to stdout as JSONL
+10. CLI flag parsing uses `cli_parse_output()`/`cli_parse_log_filters()`/`build_cli_error()`/version helpers — not custom reimplementations; uses `try_parse()` not `parse()` in Rust so a clap/usage error becomes a structured `kind:"error"` envelope (routed to stderr under the default split, exit 2), never raw clap text

package/dist/cli.d.ts

@@ -62,17 +62,108 @@ export declare function cliParseLogFilters(entries: string[]): LogFilters;
  */
 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. */
+/**
+ * Where a CliEmitter sends its events, selected by `--output-to`.
+ *
+ * The stream an event lands on follows the program's consumption mode, not the
+ * event's shape (see the spec's CLI Event Framing):
+ *
+ * - "split" (the default) is finite one-shot mode: `result` → stdout, while
+ *   `error`/`progress`/`log` → stderr. stdout therefore carries only successful
+ *   payloads, so a shell capture or pipe never mistakes a failure for data.
+ * - "stdout" / "stderr" are event-stream mode: every event, including `error`,
+ *   is collapsed onto that one stream so a consumer reading it in order
+ *   (branching on `kind`) sees preserved ordering.
+ */
+export type OutputTo = "split" | "stdout" | "stderr";
+/**
+ * Parse an `--output-to` value into an OutputTo: "split" (default), "stdout", or
+ * "stderr". Throws on unknown values; catch and pass the message to
+ * buildCliError.
+ *
+ * @example
+ * parseOutputTo("split") // → "split"
+ * parseOutputTo("both")  // throws Error
+ */
+export declare function parseOutputTo(value: string): OutputTo;
+/**
+ * Stateful emitter for structured CLI executions.
+ *
+ * Routing follows the consumption mode (OutputTo):
+ *
+ * - Finite one-shot (`CliEmitter.finite` / `finiteWith` /
+ *   `fromOutputTo("split")`): `result` → the primary writer (stdout);
+ *   `error`/`progress`/`log` → the diagnostic writer (stderr). The recommended
+ *   default for a one-shot CLI, so shell capture and pipelines never treat a
+ *   failure as data.
+ * - Event stream (`new CliEmitter(...)` / `CliEmitter.stream` /
+ *   `fromOutputTo("stdout"|"stderr")`): every event, including `error`, goes to
+ *   the single writer, preserving interleaved ordering.
+ */
 export declare class CliEmitter {
     private readonly writer;
     private readonly format;
     private readonly outputOptions;
     private terminalEmitted;
     private logFieldsProvider?;
+    private diagnostic?;
+    /**
+     * Create an event-stream emitter: every event, including `error`, goes to the
+     * single `writer`. Use CliEmitter.finite for a one-shot command that should
+     * split `result`/`error` across stdout/stderr.
+     */
     constructor(writer: CliEventWriter, format: OutputFormat, outputOptions?: OutputOptions);
+    /**
+     * Create an event-stream emitter: every event goes to `writer`, preserving
+     * interleaved ordering. Pick this when the consumer reads one ordered stream
+     * and branches on `kind`. Alias for the constructor's unified form.
+     */
+    static stream(writer: CliEventWriter, format: OutputFormat, outputOptions?: OutputOptions): CliEmitter;
+    /**
+     * Create a finite one-shot emitter with explicit sinks: `result` goes to
+     * `resultWriter`, while `error`/`progress`/`log` go to `diagnostic`.
+     */
+    static finiteWith(resultWriter: CliEventWriter, diagnostic: CliEventWriter, format: OutputFormat, outputOptions?: OutputOptions): CliEmitter;
+    /**
+     * Create a finite one-shot emitter wired to the process streams: `result` →
+     * stdout, `error`/`progress`/`log` → stderr. The recommended default for a
+     * one-shot CLI.
+     */
+    static finite(format: OutputFormat, outputOptions?: OutputOptions): CliEmitter;
+    /**
+     * Build an emitter from a parsed OutputTo selector, wired to the process
+     * streams: "split" is finite mode (`result` → stdout, everything else →
+     * stderr); "stdout"/"stderr" are event-stream mode onto that one stream.
+     */
+    static fromOutputTo(selector: OutputTo, format: OutputFormat, outputOptions?: OutputOptions): CliEmitter;
     withLogFields(provider: () => Record<string, JsonValue>): this;
+    /**
+     * Select the sink for an event by `kind`. Finite mode (a diagnostic sink is
+     * present) keeps `result` on the primary writer (stdout) and routes
+     * `error`/`progress`/`log` to the diagnostic writer (stderr). Event-stream
+     * mode (no diagnostic sink) keeps every event on the single writer.
+     */
+    private sinkFor;
     emit(event: Event): void;
     emitValidatedValue(value: JsonValue): void;
+    private static isBrokenPipe;
+    /**
+     * Emit `event` as the terminal event and resolve the outcome to a process
+     * exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.
+     *
+     * A successful write returns `successCode`; a broken pipe (the reader hung up)
+     * returns `0`; any other write or validation failure returns `4`. A library
+     * never calls process.exit itself — return this code and let the caller exit.
+     */
+    finish(event: Event, successCode: number): number;
+    /**
+     * Convenience over finish: emit a `result` payload and return `0` on success.
+     *
+     * Errors — simple or rich — go through the builder instead: construct the event
+     * with jsonError(code, message).hint(...)…build() (the builder is the error
+     * "type", so it scales to `retryable`/extra fields) and call finish(event, code).
+     */
+    finishResult(payload: JsonValue): number;
 }
 /** Build a standard CLI version value. */
 export declare function buildCliVersion(version: string): Event;

package/dist/cli.js

@@ -94,22 +94,114 @@ export function render(value, format, options = {}) {
         return formatPlainValue(jsonValue, options);
     return formatJsonValue(jsonValue, options);
 }
-/** Stateful emitter for finite structured CLI executions. */
+/**
+ * Parse an `--output-to` value into an OutputTo: "split" (default), "stdout", or
+ * "stderr". Throws on unknown values; catch and pass the message to
+ * buildCliError.
+ *
+ * @example
+ * parseOutputTo("split") // → "split"
+ * parseOutputTo("both")  // throws Error
+ */
+export function parseOutputTo(value) {
+    if (value === "split" || value === "stdout" || value === "stderr") {
+        return value;
+    }
+    throw new Error(`invalid --output-to '${value}': expected split, stdout, or stderr`);
+}
+/** Event writer bound to the process stdout stream. */
+const processStdoutWriter = (line) => {
+    process.stdout.write(line);
+};
+/**
+ * Event writer bound to the process stderr stream. This is the CliEmitter's
+ * blessed diagnostic sink: stderr is sanctioned here, and only here, precisely
+ * because output flows through the emitter rather than an ad-hoc write. The
+ * `stderr-sink` marker is what no_stderr_policy.test.ts allows through.
+ */
+const processStderrWriter = (line) => {
+    process.stderr.write(line); // stderr-sink: CliEmitter diagnostic channel
+};
+/**
+ * Stateful emitter for structured CLI executions.
+ *
+ * Routing follows the consumption mode (OutputTo):
+ *
+ * - Finite one-shot (`CliEmitter.finite` / `finiteWith` /
+ *   `fromOutputTo("split")`): `result` → the primary writer (stdout);
+ *   `error`/`progress`/`log` → the diagnostic writer (stderr). The recommended
+ *   default for a one-shot CLI, so shell capture and pipelines never treat a
+ *   failure as data.
+ * - Event stream (`new CliEmitter(...)` / `CliEmitter.stream` /
+ *   `fromOutputTo("stdout"|"stderr")`): every event, including `error`, goes to
+ *   the single writer, preserving interleaved ordering.
+ */
 export class CliEmitter {
     writer;
     format;
     outputOptions;
     terminalEmitted = false;
     logFieldsProvider;
+    diagnostic;
+    /**
+     * Create an event-stream emitter: every event, including `error`, goes to the
+     * single `writer`. Use CliEmitter.finite for a one-shot command that should
+     * split `result`/`error` across stdout/stderr.
+     */
     constructor(writer, format, outputOptions = {}) {
         this.writer = writer;
         this.format = format;
         this.outputOptions = outputOptions;
     }
+    /**
+     * Create an event-stream emitter: every event goes to `writer`, preserving
+     * interleaved ordering. Pick this when the consumer reads one ordered stream
+     * and branches on `kind`. Alias for the constructor's unified form.
+     */
+    static stream(writer, format, outputOptions = {}) {
+        return new CliEmitter(writer, format, outputOptions);
+    }
+    /**
+     * Create a finite one-shot emitter with explicit sinks: `result` goes to
+     * `resultWriter`, while `error`/`progress`/`log` go to `diagnostic`.
+     */
+    static finiteWith(resultWriter, diagnostic, format, outputOptions = {}) {
+        const emitter = new CliEmitter(resultWriter, format, outputOptions);
+        emitter.diagnostic = diagnostic;
+        return emitter;
+    }
+    /**
+     * Create a finite one-shot emitter wired to the process streams: `result` →
+     * stdout, `error`/`progress`/`log` → stderr. The recommended default for a
+     * one-shot CLI.
+     */
+    static finite(format, outputOptions = {}) {
+        return CliEmitter.finiteWith(processStdoutWriter, processStderrWriter, format, outputOptions);
+    }
+    /**
+     * Build an emitter from a parsed OutputTo selector, wired to the process
+     * streams: "split" is finite mode (`result` → stdout, everything else →
+     * stderr); "stdout"/"stderr" are event-stream mode onto that one stream.
+     */
+    static fromOutputTo(selector, format, outputOptions = {}) {
+        if (selector === "split")
+            return CliEmitter.finite(format, outputOptions);
+        const writer = selector === "stdout" ? processStdoutWriter : processStderrWriter;
+        return CliEmitter.stream(writer, format, outputOptions);
+    }
     withLogFields(provider) {
         this.logFieldsProvider = provider;
         return this;
     }
+    /**
+     * Select the sink for an event by `kind`. Finite mode (a diagnostic sink is
+     * present) keeps `result` on the primary writer (stdout) and routes
+     * `error`/`progress`/`log` to the diagnostic writer (stderr). Event-stream
+     * mode (no diagnostic sink) keeps every event on the single writer.
+     */
+    sinkFor(kind) {
+        return kind !== "result" && this.diagnostic ? this.diagnostic : this.writer;
+    }
     emit(event) {
         const jsonValue = event.toJSON();
         validateProtocolEvent(jsonValue);
@@ -127,7 +219,7 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${render(jsonValue, this.format, this.outputOptions)}\n`);
+        this.sinkFor(kind)(`${render(jsonValue, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
@@ -147,10 +239,40 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.writer(`${render(value, this.format, this.outputOptions)}\n`);
+        this.sinkFor(kind)(`${render(value, this.format, this.outputOptions)}\n`);
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
+    static isBrokenPipe(err) {
+        return (typeof err === "object" && err !== null && err.code === "EPIPE");
+    }
+    /**
+     * Emit `event` as the terminal event and resolve the outcome to a process
+     * exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.
+     *
+     * A successful write returns `successCode`; a broken pipe (the reader hung up)
+     * returns `0`; any other write or validation failure returns `4`. A library
+     * never calls process.exit itself — return this code and let the caller exit.
+     */
+    finish(event, successCode) {
+        try {
+            this.emit(event);
+            return successCode;
+        }
+        catch (err) {
+            return CliEmitter.isBrokenPipe(err) ? 0 : 4;
+        }
+    }
+    /**
+     * Convenience over finish: emit a `result` payload and return `0` on success.
+     *
+     * Errors — simple or rich — go through the builder instead: construct the event
+     * with jsonError(code, message).hint(...)…build() (the builder is the error
+     * "type", so it scales to `retryable`/extra fields) and call finish(event, code).
+     */
+    finishResult(payload) {
+        return this.finish(jsonResult(payload).build(), 0);
+    }
 }
 /** Build a standard CLI version value. */
 export function buildCliVersion(version) {

package/dist/format.d.ts

@@ -6,6 +6,14 @@
  * 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.
+ *
+ * Number literal fidelity: decodeProtocolEvent parses with `lossless-json`
+ * instead of JSON.parse, so a number's exact source literal (arbitrary
+ * precision integers, high-precision floats, exponent forms, "-0") survives
+ * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
+ * rendering path here treats it as an opaque scalar leaf (never destructured
+ * as a plain object) and re-emits its exact literal text. This is internal —
+ * LosslessNumber is never part of the public JsonValue type or exports.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;

package/dist/format.js

@@ -6,7 +6,16 @@
  * 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.
+ *
+ * Number literal fidelity: decodeProtocolEvent parses with `lossless-json`
+ * instead of JSON.parse, so a number's exact source literal (arbitrary
+ * precision integers, high-precision floats, exponent forms, "-0") survives
+ * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
+ * rendering path here treats it as an opaque scalar leaf (never destructured
+ * as a plain object) and re-emits its exact literal text. This is internal —
+ * LosslessNumber is never part of the public JsonValue type or exports.
  */
+import { parse as losslessParse, stringify as losslessStringify, isLosslessNumber } from "lossless-json";
 // ═══════════════════════════════════════════
 // Event type: opaque branded wrapper
 // ═══════════════════════════════════════════
@@ -320,7 +329,11 @@ const ERROR_RESERVED_FIELDS = new Set(["code", "message", "hint", "retryable"]);
 export function decodeProtocolEvent(text) {
     let parsed;
     try {
-        parsed = JSON.parse(text);
+        // lossless-json instead of JSON.parse: preserves each number's exact
+        // source literal (see module-level fidelity note) instead of collapsing
+        // it through float64. isSyntaxError-compatible: throws the same
+        // SyntaxError shape JSON.parse would.
+        parsed = losslessParse(text);
     }
     catch (e) {
         throw new EventDecodeError(`invalid JSON: ${e.message}`);
@@ -390,7 +403,20 @@ export function outputOptionsForPolicy(policy) {
  */
 export function formatJsonValue(value, options = {}) {
     const unwrapped = value instanceof Event ? value.toJSON() : value;
-    return JSON.stringify(redactedValue(unwrapped, options.redaction ?? {}));
+    return canonicalJsonString(redactedValue(unwrapped, options.redaction ?? {}));
+}
+/**
+ * Compact JSON serialization, byte-identical to `JSON.stringify(value)` for
+ * every value that contains no LosslessNumber, and additionally correct for
+ * values that do: `JSON.stringify` cannot serialize a LosslessNumber (it has
+ * no `toJSON` and isn't a boxed Number, so it would fall back to serializing
+ * its internal `{value, isLosslessNumber}` fields as if they were user data).
+ * lossless-json's `stringify` recognizes LosslessNumber and re-emits its
+ * exact literal text unquoted, and matches native JSON.stringify's escaping
+ * and formatting for everything else.
+ */
+function canonicalJsonString(value) {
+    return losslessStringify(value) ?? "null";
 }
 /**
  * Format as multi-line YAML. Structure-preserving: like JSON, original keys,
@@ -865,6 +891,10 @@ function decimalIntText(value) {
         return value;
     if (isInt(value))
         return String(value);
+    if (isLosslessNumber(value)) {
+        const text = value.toString();
+        return /^-?\d+$/.test(text) ? text : null;
+    }
     return null;
 }
 function epochNsToMs(value) {
@@ -891,11 +921,24 @@ function isNum(value) {
 }
 function tryProcessField(key, value) {
     let stripped;
+    // Plain-format suffix processing below does real arithmetic (division,
+    // modulo, Math.floor/abs) that only works on a native JS number. A decoded
+    // LosslessNumber is normalized to one here via Number() \u2014 which never
+    // throws, unlike LosslessNumber's own valueOf() (documented to throw for
+    // values it can't safely represent as number/bigint) \u2014 so an ordinary
+    // decoded value (e.g. duration_ms: 42) keeps formatting exactly as before,
+    // and an exotic decoded value degrades gracefully (loses precision here,
+    // same as it always would for a >2^53 native number) rather than crashing.
+    // This is Plain's documented lossy/human path; JSON/YAML stay exact via
+    // yamlScalar/plainScalar/canonicalJsonString, and decimalIntText below
+    // (msats/sats/epoch_ns) keeps exactness by reading `value` directly instead
+    // of `numeric`.
+    const numeric = isLosslessNumber(value) ? Number(value.toString()) : value;
     // Group 1: compound timestamp suffixes
     stripped = stripSuffixCI(key, "_epoch_ms");
     if (stripped !== null) {
-        if (isInt(value)) {
-            const formatted = formatRfc3339Ms(value);
+        if (isInt(numeric)) {
+            const formatted = formatRfc3339Ms(numeric);
             if (formatted !== null)
                 return [stripped, formatted];
         }
@@ -903,8 +946,8 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_epoch_s");
     if (stripped !== null) {
-        if (isInt(value)) {
-            const formatted = formatRfc3339Ms(value * 1000);
+        if (isInt(numeric)) {
+            const formatted = formatRfc3339Ms(numeric * 1000);
             if (formatted !== null)
                 return [stripped, formatted];
         }
@@ -923,28 +966,28 @@ function tryProcessField(key, value) {
     // Group 2: compound currency suffixes
     stripped = stripSuffixCI(key, "_usd_cents");
     if (stripped !== null) {
-        if (isInt(value) && value >= 0)
-            return [stripped, `$${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`];
+        if (isInt(numeric) && numeric >= 0)
+            return [stripped, `$${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")}`];
         return null;
     }
     stripped = stripSuffixCI(key, "_eur_cents");
     if (stripped !== null) {
-        if (isInt(value) && value >= 0)
-            return [stripped, `\u20ac${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")}`];
+        if (isInt(numeric) && numeric >= 0)
+            return [stripped, `\u20ac${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")}`];
         return null;
     }
     const gc = tryStripGenericCents(key);
     if (gc !== null) {
         const [gcStripped, code] = gc;
-        if (isInt(value) && value >= 0)
-            return [gcStripped, `${Math.floor(value / 100)}.${String(value % 100).padStart(2, "0")} ${code.toUpperCase()}`];
+        if (isInt(numeric) && numeric >= 0)
+            return [gcStripped, `${Math.floor(numeric / 100)}.${String(numeric % 100).padStart(2, "0")} ${code.toUpperCase()}`];
         return null;
     }
     const gm = tryStripGenericMicro(key);
     if (gm !== null) {
         const [gmStripped, code] = gm;
-        if (isInt(value) && value >= 0)
-            return [gmStripped, `${Math.floor(value / 1_000_000)}.${String(value % 1_000_000).padStart(6, "0")} ${code.toUpperCase()}`];
+        if (isInt(numeric) && numeric >= 0)
+            return [gmStripped, `${Math.floor(numeric / 1_000_000)}.${String(numeric % 1_000_000).padStart(6, "0")} ${code.toUpperCase()}`];
         return null;
     }
     // Group 3: multi-char suffixes
@@ -956,20 +999,20 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_minutes");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)} minutes`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)} minutes`];
         return null;
     }
     stripped = stripSuffixCI(key, "_hours");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)} hours`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)} hours`];
         return null;
     }
     stripped = stripSuffixCI(key, "_days");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)} days`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)} days`];
         return null;
     }
     // Group 4: single-unit suffixes
@@ -989,46 +1032,46 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_bytes");
     if (stripped !== null) {
-        if (isInt(value) && value >= 0)
-            return [stripped, formatBytesHuman(value)];
+        if (isInt(numeric) && numeric >= 0)
+            return [stripped, formatBytesHuman(numeric)];
         return null;
     }
     stripped = stripSuffixCI(key, "_percent");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)}%`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)}%`];
         return null;
     }
     // Group 5: short suffixes (last to avoid false positives)
     stripped = stripSuffixCI(key, "_jpy");
     if (stripped !== null) {
-        if (isInt(value) && value >= 0)
-            return [stripped, `\u00a5${formatWithCommas(value)}`];
+        if (isInt(numeric) && numeric >= 0)
+            return [stripped, `\u00a5${formatWithCommas(numeric)}`];
         return null;
     }
     stripped = stripSuffixCI(key, "_ns");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)}ns`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)}ns`];
         return null;
     }
     stripped = stripSuffixCI(key, "_us");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)}\u03bcs`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)}\u03bcs`];
         return null;
     }
     stripped = stripSuffixCI(key, "_ms");
     if (stripped !== null) {
-        const fv = formatMsValue(value);
+        const fv = formatMsValue(numeric);
         if (fv !== null)
             return [stripped, fv];
         return null;
     }
     stripped = stripSuffixCI(key, "_s");
     if (stripped !== null) {
-        if (isNum(value))
-            return [stripped, `${plainScalar(value)}s`];
+        if (isNum(numeric))
+            return [stripped, `${plainScalar(numeric)}s`];
         return null;
     }
     return null;
@@ -1258,7 +1301,11 @@ function yamlScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
-    return `"${escapeYamlStr(JSON.stringify(sortJsonValue(value)))}"`;
+    // Decoded number: emit the exact source literal unquoted, matching JSON's
+    // structure-preserving fidelity contract for YAML too.
+    if (isLosslessNumber(value))
+        return value.toString();
+    return `"${escapeYamlStr(canonicalJsonString(sortJsonValue(value)))}"`;
 }
 // ═══════════════════════════════════════════
 // Plain Rendering (logfmt)
@@ -1314,11 +1361,16 @@ function plainScalar(value) {
         return value.toString();
     if (typeof value === "number")
         return value.toString();
-    return JSON.stringify(sortJsonValue(value));
+    // Decoded number: emit the exact source literal (Plain is documented lossy
+    // for arithmetic-derived formatting, but a bare pass-through scalar still
+    // gets its exact digits, not a mangled float64 round-trip).
+    if (isLosslessNumber(value))
+        return value.toString();
+    return canonicalJsonString(sortJsonValue(value));
 }
 function plainScalarRaw(value) {
     if (isObject(value) || Array.isArray(value)) {
-        return JSON.stringify(sortJsonValue(value));
+        return canonicalJsonString(sortJsonValue(value));
     }
     return plainScalar(value);
 }
@@ -1365,6 +1417,11 @@ function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
         return "<unsupported:function>";
     if (t === "symbol")
         return "<unsupported:symbol>";
+    // A LosslessNumber (from decodeProtocolEvent) is typeof "object" but must
+    // stay opaque: the generic object branch below would otherwise flatten it
+    // into its internal {value, isLosslessNumber} fields via Object.entries.
+    if (isLosslessNumber(value))
+        return value;
     if (value instanceof Error)
         return value.message;
     if (value instanceof Date)
@@ -1392,7 +1449,13 @@ function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
     return "<unsupported:unknown>";
 }
 function isObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+    // isLosslessNumber excludes decoded numbers: a LosslessNumber is
+    // typeof "object" but is an opaque scalar leaf, never a plain JSON object —
+    // every object-walking function below (redaction, YAML/plain rendering,
+    // sortJsonValue, validation) funnels through this check, so excluding it
+    // here is the single choke point that keeps LosslessNumber from being
+    // destructured into its internal {value, isLosslessNumber} fields.
+    return typeof value === "object" && value !== null && !Array.isArray(value) && !isLosslessNumber(value);
 }
 function sortedObjectKeys(obj) {
     return Object.keys(obj).sort(jcsCompare);

package/dist/index.d.ts

@@ -2,4 +2,4 @@
  * 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, 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";
+export { type OutputFormat, type OutputTo, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/index.js

@@ -2,4 +2,4 @@
  * 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, 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";
+export { CliEmitter, LogFilters, cliParseOutput, parseOutputTo, cliParseLogFilters, render, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.18.0",
+  "version": "0.19.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": {
@@ -38,5 +38,8 @@
     "@types/node": "^26.1.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "lossless-json": "^4.3.0"
   }
 }