Agent-First Data Blog
Updates, deep-dives, and release notes for Agent-First Data.
Design
Release notes
Agent-First Data v0.34.0: The Success That Had Not Finished
An error has to explain itself; a success says nothing and is believed. This release is mostly one shape repeated — an operation that returned success while part of what it promised had not happened — found in an install, an uninstall, a borrowed terminal, and a rule the tool wrote for everyone but itself.
ReleaseAgent-First Data v0.33.0: A Refusal That Stops the Verb
Quoting decides how a string reaches a command, never whether the string is a disaster. This release adds a guard for the values that flow into rm and mv — and, because a correct refusal that the shell discards is not a guard at all, the two verbs that carry its verdict.
ReleaseAgent-First Data v0.32.0: Where the Value Comes From
A credential on argv is in the process table, the shell history, and the audit log. Every CLI eventually grows a private answer to that. This release makes where a value comes from part of what an argument declares, so help, validation, and reading all agree.
ReleaseAgent-First Data v0.31.0: An Error With Nowhere to Go
A dispatch method returned `Option` for a condition no caller could reach, so every caller had to invent an error it could not honestly describe. The fix was not a better `Option` — it was making the failure impossible to express.
ReleaseAgent-First Data v0.29.0: One Address, Read and Written
Markdown becomes addressable, and an array element can be named by its content instead of its position. Both landed on the read path first — which is how we found that `paths` was emitting addresses afdata's own write verbs refused.
ReleaseAgent-First Data v0.28.1: One Path, Many Nodes
Reading one field across a collection took three steps, and the middle one was sed against afdata's own output. A path may now contain `*`. Because `*` is a legal JSON key, the grammar gains `\*` to keep such documents addressable — which makes this a breaking change to path spelling.
ReleaseAgent-First Data v0.28.0: The Addresses It Would Not Read
afdata printed paths that afdata then refused to parse. The empty string is a legal key — npm writes one into every package-lock.json — and the path grammar rejected it, so `paths` emitted addresses no other command would accept. v0.28.0 closes that, and adds `values` for reading many paths from a single parse.
ReleaseAgent-First Data v0.27.0: If It Isn't Registered, It Doesn't Run
A CLI that accepts each flag individually will accept combinations that mean nothing, and then discovers that at runtime — or doesn't. v0.27.0 replaces the help layer with a closed-world compiler: one registry decides argv parsing, legal combinations, output contracts, and help, and an invocation runs only when it matches exactly one registered shape.
ReleaseAgent-First Data v0.26.2: Which Mode Is This Command?
The CLI Event Framing spec defined two consumption modes but never said how to tell which one a command is in — so two spores independently shipped caller-needed data onto the diagnostic stream. v0.26.2 adds the missing test: a command producing more than one caller-needed output over time is an event stream, defaults to stdout, and refuses split.
ReleaseAgent-First Data v0.26: One Surface, Three Formats
`--output` selects a format. It was also selecting a different set of commands and arguments: Markdown help was the one format that bypassed the help model and handed each command back to the argument parser's own writer, so `afdata lint` listed two arguments in JSON and plain and three in Markdown, and all 23 commands re-advertised a `-h` flag removed two releases earlier. v0.26 renders Markdown from the same model the JSON help uses, so the formats cannot disagree by construction, and puts a gate check behind it. v0.26.1 fixes the mirror image in `afdata lint`, which read a JSON Schema as though it were data — and so rejected `duration_ms: {"type": "integer"}`, a property that satisfies the very suffix rule the lint exists to enforce.
ReleaseAgent-First Data v0.25: One Spelling Per Concept
v0.24 made help a normal result. v0.25 is the follow-through: every remaining second spelling is gone. `--json` was `--output json` typed differently — it bought an agent nothing and cost applications a flag name, hijacking `--json <FILE>` and misreading its value as a subcommand. The help model also stopped saying things that weren't true: defaults an author had hidden, empty strings the project's own validator rejected, and a positional that contradicted its own usage line. Plus `redact_argv`, so a CLI can record its own invocation without writing a credential to its log.
ReleaseAgent-First Data v0.24: Help Is a Result, Not an Exception
Every output of an AFDATA CLI is structured — except the one an agent reads first. `--help` has always answered in 80-column prose no matter what the tool's output contract said. v0.24 makes help a normal result: it inherits the CLI's own `--output` default, so `afdata --help` returns a protocol-v1 envelope with `result.code:"help"`, and `--output plain` is how a human asks for text. The model is deliberately small — no long-form prose, no repeated inherited globals, no eagerly embedded version values — and the shape is pinned by `cli-help-v1.schema.json`, validated in the test gate against real output from all four SDKs.
ReleaseAgent-First Data v0.23: The Shell Speaks Protocol Too
AFDATA's structured log/result/error protocol was available to anything that linked an SDK or called the CLI — except the layer where agent tooling actually runs: the Bash script that invokes cargo, npm, and wrangler. v0.23 fixes that with `afdata emit` (one protocol event from shell-safe scalar arguments) and `afdata shell bash`, a sourceable Bash 3.2+ authoring kit embedded in the binary. It gives a plain script AFDATA-style argument parsing, config reads, and structured events — under one firm rule: structure your own words, and pass everything else through untouched. `afdata_run` wraps a child without touching its stdout, stderr, TTY, colors, or exit status; `afdata_call` keeps one script the sole owner of the terminal result even when scripts orchestrate scripts.
ReleaseAgent-First Data v0.22: What the Four Languages Actually Share
v0.22 redraws the four-language line. Skill admin and stream redirection shipped in all four SDKs but only Rust ever used them — dead parity weight that could rot silently, and did: `afdata skill install` was dropping the references/ files next to SKILL.md. v0.22 fixes the installer to bundle the whole skill as first-class assets, then removes skill admin and stream redirection from the Go, Python, and TypeScript SDKs. The four languages now synchronize on exactly the convention plus the CLI helpers — the shared contract, and nothing else.
ReleaseAgent-First Data v0.21: Even `--version` Speaks the Protocol
v0.21 turns the last bespoke line of CLI output into the protocol. `--version` no longer prints `tool 1.2.3` as human text — it always answers with a structured protocol-v1 version event, JSON by default, carrying name, version, and optional display_name/build. The pre-parser that intercepts it before your argument parser now recognizes your own value-taking global flags, so `tool --stdout-file x --version` still works. Shipped identically across Rust, Go, Python, and TypeScript.
ReleaseAgent-First Data v0.20: Editing, Unwelded From Files
v0.20 finishes what the source-preserving editor started: editing no longer requires a file. The set/unset/add/remove verbs now live on an in-memory Document, DocumentFile is a thin file adapter over it, and edits stage until a single atomic save() — so you can batch changes and validate the result before a byte is written. The editor also grows sparse and nested documents in place, and unset is now idempotent.
ReleaseAgent-First Data v0.19: Cleaner Output, Safer Edits
v0.19 sharpens both ends of afdata. On the way out: a one-shot CLI puts its result on stdout and every diagnostic on stderr, --output-to overrides it, and finish() maps outcomes to broken-pipe-safe exit codes. On the way in: afdata now reads and edits a Markdown page's +++/--- frontmatter by dot-path, and reading a secret-bearing config no longer risks leaking the file into an error.
ReleaseAgent-First Data v0.18: afdata Reads and Edits Your Config
v0.18 gives afdata a document CLI and library: read and safely edit JSON, TOML, YAML, dotenv, and INI files by dot-path — show/get/value to read, set/unset/add/remove to edit — with source-preserving atomic writes, symlink/hardlink guards, and secrets that stay redacted even on a direct read.
ReleaseAgent-First Data v0.17: Units in the Key, Structure in the Tag
v0.17 removes the _size config suffix and the parse_size helper — a byte count is a number, and its unit belongs in the field name — and finishes the lint sweep: _bcp47 and _rfc3339 structure are validated, _url must be a single URL, and duration and currency suffixes are checked to be numbers.
ReleaseAgent-First Data v0.16: One Protocol, Builders Everywhere
v0.16 is the convergence release: a single builders-only API, a finite protocol-v1 event stream with semantic emitters, a machine-readable suffix registry shipped offline, and a sub-cent currency suffix for metered pricing.
ReleaseAgent-First Data v0.15: Stdout and Stderr File Destinations
v0.15 adds one CLI convention across Rust, Go, Python, and TypeScript: --stdout-file and --stderr-file redirect the process streams to append-only files before normal parsing starts.
ReleaseAgent-First Data v0.14: Workspace Scope and Hermes
The skill installer's second scope was called 'project' but it meant 'current directory'. v0.14 renames it to workspace, lifts the Codex restriction that followed from the wrong name, and adds Hermes as the fourth agent target.
ReleaseAgent-First Data v0.13: Redaction Fails Closed
v0.10 scrubbed secrets inside URLs; v0.11 made redaction a policy. v0.13 closes the seams where a secret could still slip through — a marked container that leaked its non-secret siblings, a key collision that reverted to raw values, a schemeless connection string that no longer looked like a URL. When redaction is unsure, it now redacts.
ReleaseAgent-First Data v0.12: Help Scope and Format Are Two Knobs, Not One
v0.7 made --help expand the whole command tree so agents could read a CLI in one call. That conflated two decisions — how much to show and how to render it. v0.12 splits them: --recursive controls scope, --output controls format, and the two compose. Same model across Rust, Go, Python, and TypeScript.
ReleaseAgent-First Data v0.11: The Skill Installer, in Four Languages
A tool can ship its own Agent Skill — but getting that SKILL.md into Codex, Claude Code, opencode, and Hermes is fiddly, per-agent filesystem work. v0.11 adds run_skill_admin: install, uninstall, and status for an embedded skill, with the same behavior and byte-identical output across Rust, Go, Python, and TypeScript.
ReleaseAgent-First Data v0.10: Secrets Inside URLs
The _secret suffix hides a whole field. But secrets also hide inside values — a token in a query string, a password in a connection URL. v0.10 adds a _url suffix that scrubs them, by convention, without scanning anything.
ReleaseAgent-First Data v0.8: Redaction Became a Policy
The v0.8 line expanded redaction from the _secret suffix into explicit policies, JSON-safe redacted values, and exact secret-name lists for legacy payloads.
ReleaseAgent-First Data v0.7: Help Output Should Be Complete
The v0.7 help-rendering work made --help an agent-readable map of the whole CLI, including subcommands, flags, and markdown docs generation.
ReleaseAgent-First Data v0.6: The CLI Contract Got Actionable
The v0.6 update turned the CLI examples into a practical agent contract: output formats, log filters, dry-run previews, JSON errors, and actionable hints.
ReleaseAgent-First Data v0.5: Logs Became Protocol Events
The v0.5 update made logging part of the same agent-readable contract as output: structured events, span context, secret redaction, and stdout-only channel discipline.
ReleaseAgent-First Data First Release: Building APIs that Agents Can Read
The first Agent-First Data release: a field-naming convention and output layer that lets agents infer units, timestamps, and secrets without extra documentation.