Examples

This page is the catalog of worked examples: what each one demonstrates, which fixtures you can run today, and how to run them. Each example is a hank – a JSON program made of codons, the individual agent tasks – and the checked ones ship with captured runs so you can compare your own output against a known-good result. If you are new to Hankweave, start with minimal-single-provider below; if you already know the shape of a hank, scan the table for the example closest to your work.

Which example shows what you need?#

Choose a checked example close to the work you want to do. In the linked breakdowns, we inspect the files and configuration, run the hank, compare its outputs with a captured run, and work through the choices we can adapt. The configurations and transcripts come from the checked fixture files. For the full fixture inventory, failure fixtures, truth files, and capture manifests, see tutorial/fixtures.

The table is the fastest way to pick. Use the status column to distinguish what you can run now from a proposed example: "checked" means the fixture and its captured run are available at the pinned version, and "planned" means the catalog has a design description but no runnable fixture. The capture date, runtime version, and tracked cost columns tell you how current each capture is before you trust its numbers.

The sections below give each example a paragraph of context: what the hank does, which models it carries, and what its capture recorded.

quote-template-unification#

In quote-template-unification, we work with suppliers quoting against one fictional request for quotation in heterogeneous digitizer dialects. The hank normalizes those dialects, validates and repairs them against the RFQ contract, reconciles a unified table, and publishes a cited award brief plus an exception queue. Ambiguous cases remain visible for review instead of being silently resolved.

The shipped hank has seven codons. normalize-aster, normalize-beacon, normalize-cedar, and survey-and-extracts use the fixture-carried haiku model shortcut for mechanical extraction; validate-and-repair and reconcile use the fixture-carried pi/baseten/deepseek-ai/DeepSeek-V4-Pro spelling for judgment; award-brief uses haiku for rendering. A preflight rig runs before the codons, and the quality-observer sentinel is an event observer that observes completion events. The sentinel is not an artifact checker: file and row assertions come from the fixture's ordinary rigs and verification program.

The corpus is synthetic and carries the watermark FICTIONAL TRAINING FIXTURE — NOT CUSTOMER DATA. The tutorial builds the same hank through independently runnable checkpoints from baseline through break/resume/inspect. The anchor's golden capture completed all seven codons, produced 40 supplier-part data rows and eight exception rows across eight hazard types, and recorded $0.88303367 in tracked codon cost; provider health checks and sentinel calls are separate. See the anchor breakdown, tutorial tour, and fixture inventory.

minimal-single-provider#

Start with minimal-single-provider if you want the smallest useful hank: one summarize-notes codon, the ANTHROPIC_API_KEY provider key, and one summary.md output file. For a guided walkthrough and help reading its expected captures, follow start/quickstart.

Its 2026-09-06 capture uses the published 0.10.0 artifact, has actual_service_output: true, uses the fixture-carried haiku shortcut, and records $0.01394590 in tracked codon cost. The minimal-single-provider breakdown explains the configuration; the operational commands are also shown in the run section below.

plan-review-update#

In plan-review-update, we pass a plan through a checked build-review loop. A plan codon writes plan.md; then three iterations pair a fresh haiku reviewer with a fresh haiku updater. continuationMode: "fresh" makes each handoff travel through files rather than conversation history.

Its measured 2026-09-03 capture completed seven codons – one plan, three reviews, and three updates – and recorded $0.272. Read the plan-review-update breakdown for the loop configuration and the build-review method's owner, author/patterns/reliability.

connector-build-test#

Use connector-build-test when we can hold a connector specification fixed and check the implementation with a deterministic bun test suite. The checked polymorphic build proceeds through research, build iterations, and documentation. Each iteration starts fresh and reads failing test output from disk. The example carries forward the Polymorphic Connectors pattern from the former use-cases page.

Its measured 2026-09-03 capture completed five codons – research, three implementation iterations, and document – and recorded $0.125. The connector-build-test breakdown owns the run details; its transferable method belongs to author/patterns/composition.

docs-maintenance#

docs-maintenance is the hank set used by the docs-forge pipeline that maintains these docs. Its stages are named C1 (skeleton, preservation, and briefs), C2 (writing and validation), and B (publishing). By 2026-09-02, the forge record had written 39 pages and 39 briefs with $128.87 tracked spend and recorded 16+ runtime findings – 14 drafted into 10 paste-ready upstream issue drafts plus four checklist notes, with filing pending.

The shipped fixture is an excerpt captured 2026-09-04: it contains hank/hank-polish.json, the stage compiler and runner excerpts, a ten-check acceptance script with no model calls, and start_here.md. It is not a runnable C1/C2/B hank with expected captures, which is why the table marks its service output as "excerpt". The pipeline's internals belong to contribute/documentation-pipeline; the docs-maintenance breakdown explains the excerpt.

statement-unifier#

statement-unifier is planned as a brokerage-statement variant that would demonstrate re-templating the anchor for a second domain. No fixture or run command is listed until a checked directory, README, expected captures, and truth oracle exist. See author/patterns/gallery for the pattern index.

Product and provider terms#

The examples above mix product, pipeline, and provider names, so it helps to fix the vocabulary before reading the captures. Hankweave is the runtime published as hankweave@0.10.0. "docs-forge" or "forge" names the internal pipeline that uses Hankweave. Pi and Zai name the embedded Pi SDK catalog and the pi/zai/* provider family. Claude/Anthropic names the Anthropic-backed harness; fixture-carried shortcuts include haiku. Historical forge model choices such as glm-5.3, Kimi-K3, and gpt-5.6-luna/terra are dated docs-forge-internal choices, not Hankweave features; pi/baseten/deepseek-ai/DeepSeek-V4-Pro appears here only as the anchor fixture's carried spelling. See model resolution for how model strings are resolved.

Anchor count and shipped truth#

Because the anchor's design notes predate its shipped form, two counts are worth stating plainly. The shipped anchor contains seven codons: five use haiku, and two use pi/baseten/deepseek-ai/DeepSeek-V4-Pro. Their per-codon caps sum to $9.00 (0.5×3 + 1.5 + 3.0 + 2.0 + 1.0); that is a configured ceiling, not a predicted bill. Hankweave's --init starter hank contains four codons.

Its golden output covers eight suppliers across five BOM parts: 40 data rows plus a CSV header. The fixture's historical design notes still contain "six codons," "sonnet," and "3×5 grid" language; the shipped hank.json and golden capture are the current contract. For the current measured result, use the dated tracked-codon capture above rather than treating the cap as a price promise.

Run a checked example yourself#

The checked fixtures are runnable, and this section walks through two of them end to end: the minimal fixture first, then the anchor. Run a fixture from its own root – the directory containing its hank.json. The commands below use Bun as the package launcher, but the package's Node entrypoint requires Node >=22.19.0; a Node/npm user can use npx hankweave@0.10.0 instead of bunx hankweave@0.10.0. The exact entry directories are supplied by the versioned fixture bundle, hankweave-fixtures-0.10.0.tar.gz. For the anchor recipe shown here, install Bun and Git and run as a non-root user with writable execution and output directories. Individual bundle files are available under /fixtures/0.10.0/files/<relative-file>. The archive already contains one top-level hankweave-fixtures-0.10.0/ directory; extract it in the archive's parent, then enter the fixture directory.

tar -xzf hankweave-fixtures-0.10.0.tar.gz
cd hankweave-fixtures-0.10.0/minimal-single-provider

minimal-single-provider#

From the extracted minimal-single-provider/ directory, validate first and then start a new headless (non-interactive) execution. Set ANTHROPIC_API_KEY before the run. Validation checks configuration and paths; it does not prove that the startup credentials will pass the separate runtime self-test.

bunx hankweave@0.10.0 hank.json data/ --validate
bunx hankweave@0.10.0 hank.json data/ --headless --start-new -o out

A successful validation prints the GOOD TO RUN! box. The captured run shows the Hankweave v0.10.0 banner, and out/summary.md is the copied output. If ANTHROPIC_API_KEY is unset, startup fails before a codon runs with authentication: ✗ No authentication found (set ANTHROPIC_API_KEY).

quote-template-unification#

The anchor needs more preparation because it uses two providers and a held-out answer key. From the extracted anchor-hank/ directory, export both keys before running: ANTHROPIC_API_KEY for the haiku codons and BASETEN_API_KEY for the two pi/baseten/deepseek-ai/DeepSeek-V4-Pro codons. The bundle places verify.py and quote-template-unification/ beside anchor-hank/; run the preparation command from anchor-hank/, where it writes task-data/. Prepare task-only inputs first; the held-out truth/ directory must not be visible to prompts.

python3 ../verify.py prepare-data ../quote-template-unification task-data
bunx hankweave@0.10.0 hank.json task-data --validate
bunx hankweave@0.10.0 hank.json task-data --headless --start-new --execution exec --max-cost 9 --shim-idle-timeout 1800 --overwrite-output -o out
python3 ../verify.py anchor out

Read the four commands as prepare, validate, run, verify. The preparation step leaves truth/, the generator, and planted failure fixtures outside task-data/. The corpus is mounted inside the execution as read_only_data_source/. The final verification compares unified-records.csv with the held-out expected CSV and checks the exception output against truth. The command sequence also keeps the answer key out of the run being evaluated.

Where outputs and failures appear#

Whichever fixture you run, the outputs land in the same places. A new run creates an execution directory under ~/.hankweave-executions/{id}/. Outputs remain in its agentRoot/ unless -o/--output copies them elsewhere; there is no default hankweave-results/ directory. Data is symlinked into the execution directory by default, and --copy switches to copying. The anchor's prompts still read the mounted path as read_only_data_source/.

The anchor preflight rig checks corpus checksums, shape, and watermark before codons spend tokens. A corrupted or hash-mismatched corpus exits nonzero with preflight: N check(s) failed -- see preflight-report.json, and the first codon does not start. For measured-cost comparisons, use dated fixture captures only: the anchor's tracked codon cost is $0.88303367, and the minimal fixture's is $0.01394590.

What happened to the data-codebook example?#

Readers of earlier docs may remember a data-codebook example. examples/data-codebook.mdx is retired and its URL redirects here. It could not run as documented: its quality gate ran bun run typecheck from project even though package.json lived in src/, and bun test with zero test files exited 0 without enforcing the promised data check. Its expected-output tree also promised a hankweave-results/ directory that does not exist by default. Its $0.06–0.20 total-cost table was never measured and is not carried forward.

The retirement removed the broken instructions, not the design ideas. We keep: observe → generate → validate → document; specific output locations and structures in prompts; the TypeScript-template rig pattern; narrator and cost-tracker sentinel configurations; the beforeCopy quality-gate concept; and the allow-failure loop concept. We do not carry forward the old || true plus allowFailure wiring. To adapt these ideas, use the author/patterns/gallery index; for loop and sentinel variations, see concepts/loops and concepts/sentinels.

The retirement rule was to wait for the anchor tutorial's fixtures to pass. This fixture-backed catalog and the tutorial keep a working example available alongside the redirect.