From 39a96de536db4da5e8296041f96b79ee426b46c9 Mon Sep 17 00:00:00 2001 From: Andrew Buchkovich Date: Wed, 15 Jul 2026 00:32:33 -0400 Subject: [PATCH 1/2] docs: add CLI usage section to README The release archives bundle README.md alongside the binary, but the only usage example (Quick start) assumes a full clone (examples/helio, dist/) that isn't present in the zip. Add a self-contained command reference so someone who only downloaded the release archive knows how to run the binary against their own source. --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index bf1e0ca..eb59ce0 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,41 @@ with a `SHA256SUMS` file — unpack one binary and put it on `PATH`; there is no installer to run. The release process is documented in [docs/release-checklist.md](docs/release-checklist.md). +## Using the CLI + +If you downloaded a release archive instead of building from source, unpack +`typeference` (`typeference.exe` on Windows) onto `PATH` and confirm it runs: + +```sh +typeference version +``` + +`` in every command below is a directory of your own typed agent +definitions (`schemaVersion: 3` YAML, shaped like the example above) — clone +this repository to point it at the bundled `examples/helio/` corpus instead. + +```text +typeference validate [--trust-config path] +typeference build [--target all|neutral|codex|copilot|cursor] [--out dist] + [--emit-ard --publisher-domain example.com] [--trust-config path] + [--trust-signatures signatures.json] [--allow-unsigned-trust] +typeference inspect [--source path] +typeference diff --against [--target all] + [--emit-ard --publisher-domain example.com] [--trust-config path] + [--trust-signatures signatures.json] [--json] [--allow-unsigned-trust] +typeference eval --scenarios [--live] [--model id] [--out dir] +typeference equivalence pack --scenarios --out + [--target all|[,...]] +typeference equivalence score [--live] [--model id] +``` + +`validate` checks composition and structural typing without writing anything. +`build` compiles to native target artifacts. `diff` recompiles and byte-compares +against an already-built directory — see [Quick start](#quick-start) above for +what "No differences." means. `eval` and `equivalence` are covered in +[Behavioral evals](#behavioral-evals) below; both default to a dry run that +never makes a network call. + ## Two implementations, one specification The C# implementation under `src/` is the reference implementation; the Go From cf03d0c082a086cdf0e9dcd3d1d50f7c4d5470d0 Mon Sep 17 00:00:00 2001 From: Andrew Buchkovich Date: Wed, 15 Jul 2026 00:38:20 -0400 Subject: [PATCH 2/2] chore: bump version to 0.0.4 for the CLI usage docs Per docs/release-checklist.md: doc changes that ship in the release archive (README.md is bundled alongside the binary) warrant their own tagged release rather than silently reusing v0.0.3's bytes. --- CHANGELOG.md | 10 ++++++++++ Directory.Build.props | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d3ad2db..84e32f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ versioning. Tool versions (this file) are independent of the typed-resource TypeFerence is an experimental reference implementation; pre-1.0 versions make no compatibility promises between minor versions. +## [0.0.4] - 2026-07-15 + +### Added + +- **CLI usage section** in `README.md` — a self-contained command reference + (`validate`, `build`, `inspect`, `diff`, `eval`, `equivalence pack`/`score`, + `version`) for anyone running the binary from a release archive rather than + a full clone; `README.md` ships in every release archive alongside the + binary. + ## [0.0.3] - 2026-07-15 First tagged release. Everything before this version was unversioned development. diff --git a/Directory.Build.props b/Directory.Build.props index b53ad15..1a31f06 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -6,6 +6,6 @@ latest true true - 0.0.3 + 0.0.4