Terret Cookbook
Worked, end-to-end recipes for building on Terret. Each one starts from
the kernel primitives (docs/hames-primer.md) and ends at a running
piece of a Terret: a real gem, real metadata, a real test. No recipe
stops at a snippet in isolation. Where a recipe touches a contract, it
points at the normative document for the contract and stays a how-to
itself.
-
adding-a-tool.md: an empty gem to a registered tool with honest mutating/approval/concurrency metadata and a test. The running example is
terret-fortune, afortunetool returning one line from a vendored list. Reference:docs/exec.md§5 (the roster and the metadata),gems/terret-core/lib/terret/tools.rb(the registry). -
adding-a-provider.md: implementing a sole-provider seam, using
ctx[:summarizer]as the model because Terret ships two implementations of it. Covers the seam contract, the sole-provider refusal, an injectable transport so tests need no network, and nil-on-failure discipline where it applies. Reference:gems/terret-morph(the worked provider),docs/lifecycle.md(compaction). -
adding-a-bundle.md: the gemspec metadata that declares a gem a bundle, the
bundle.ymlshape, the discovery mechanism (Composition.discover_bundles), and profile stacking. Reference and contract:docs/composition.md.
New to the kernel these build on? Read docs/hames-primer.md first. A
tool provider and a seam provider are both ordinary Hames services, and a
bundle is ordinary config rows.