lyman 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42c4c9146ed53714fa0725775e91ffcbc599e485d652e84d483dedca2f47e047
+  data.tar.gz: e17d5dde1e338e8bae43cb97f5633b0cd4e24e06d66535bafdd2ff74319c9764
+SHA512:
+  metadata.gz: 48c20fb9bb06c5f685b47491cc3d96cf33e7835b7b44bc1723bd87feec82a75d334b923a38c5d5838595bba31697e958e150dad4a5305e113edb454bcfd53e17
+  data.tar.gz: 26e9984e59ddc9722cb50bac1a3567cf9c424367c8dbed5e48bbf6b47fe3051052c59cd9e24a83fd5c7b49a81f056b2b256de89dda000c92798d536e072a8d5f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joel Helbling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# Lyman
+
+**A composable agentic harness — and a framework for building harnesses — in
+Ruby, built on [shifty](https://github.com/joelhelbling/shifty).**
+
+Lyman is for people building agentic workflows on models they run themselves:
+open-weight models on Ollama, LM Studio, vLLM, llama.cpp — or models they've
+trained. If that's you, you start with less data, less tooling maturity, and
+less margin for error than the frontier labs. Your one real edge is
+**iteration speed**. Lyman exists to maximize it.
+
+> *Lyman*, as in the Lyman series — a nod to the physicist, and to
+> **redshift**, which is in turn a nod to **Ruby** and the **shifty** gem. A
+> series is also, fittingly, a sequence of discrete lines — like the stages of
+> a pipeline.
+
+## The idea
+
+An agent harness is a pipeline. Not as a metaphor — literally:
+
+```ruby
+pipeline =
+  source_worker { rounds.shift }                                             |
+  Lyman::Workers.chat_completion(base_url:, model:, tools:)                  |
+  relay_worker { |c| c.finish! if c.pending_tool_calls.empty?; c }           |
+  Lyman::Workers.tool_execution(handlers)                                    |
+  side_worker { |c| rounds << c unless c.finished? }                         |
+  filter_worker { |c| c.finished? }
+```
+
+That's not pseudocode — it's the working heart of [`harness/chat.rb`](harness/chat.rb),
+a tool-using chat agent for local models. Every stage is a plain
+[shifty](https://github.com/joelhelbling/shifty) worker. Want logging? Splice
+in a `side_worker` — anywhere. Want a guardrail? A `filter_worker`. Want to
+swap Ollama for vLLM, or native tool-calling for prompt-and-parse emulation on
+a model that lacks it? Replace one worker; nothing else changes. There are
+**no hooks**, because there's nothing to hook *into* — the whole loop is
+already open.
+
+Two principles drive every design decision:
+
+1. **Legibility.** One paradigm — a pipeline of workers — applied everywhere,
+   at every level.
+2. **Guts on the outside.** Nothing important happens anywhere you can't see,
+   name, or splice into. This is deliberately the opposite of the frontier-SDK
+   ethos, where the agent loop is a black box you configure from the edges.
+
+And a razor for when they're in tension with convenience: **favor whatever
+lets a user see and change behavior faster.** For a data-poor tinkerer,
+transparency isn't an aesthetic — it's what makes fast iteration possible.
+
+## Quick start
+
+You'll need Ruby (see [`mise.toml`](mise.toml)) and a local model server
+speaking the OpenAI-compatible API — [Ollama](https://ollama.com) and
+[LM Studio](https://lmstudio.ai) both work. Use a model with native tool
+support (e.g. `qwen3.5`, `gemma4`, `mistral`).
+
+```sh
+bundle install
+bundle exec ruby harness/chat.rb
+```
+
+```
+lyman ⇢ gemma4:latest @ http://localhost:11434/v1
+
+you> what time is it?
+  ⚙ current_time {}
+
+gemma4:latest> It's 9:25 PM on Friday, July 3rd.
+```
+
+That `⚙` line is a side worker showing you the model calling a tool — and the
+reply after it means two model round-trips completed inside a single pull on
+the pipeline. Point it elsewhere with `LYMAN_BASE_URL` and `LYMAN_MODEL`.
+
+## How it works, briefly
+
+- **The item is the conversation.** What flows through the pipeline is a
+  `Conversation` — the full message history plus the control data workers
+  consult (`finished?`, `pending_tool_calls`). A turn carries its whole
+  conversation with it; that's what makes it a conversation.
+- **State lives in the shell.** The enclosing scope — the *shell* — is just
+  state plus a process: the conversation, a queue, and a deliberately boring
+  loop. A human REPL is one shell; an autonomous email-triager is another.
+  Lyman is turn-shaped, not chat-shaped.
+- **The agentic loop is a circuit, not a special construct.** Shifty pipelines
+  are strictly linear, so the model⇄tool cycle is built from stock parts: a
+  source reading from a queue, a side worker re-enqueueing unfinished rounds,
+  and a filter at the tail that only lets finished turns escape. Demand does
+  the rest — N model⇄tool rounds happen inside one `shift`, with no loop
+  written anywhere. Full reasoning in
+  [docs/design/circuit-pattern.md](docs/design/circuit-pattern.md).
+- **Dependencies stay inside the workers that need them.** The HTTP client
+  lives in exactly one file. Use your favorite gems — in such a way that only
+  the worker requiring one knows it exists.
+
+The longer story — mission, principles, architecture decisions, open
+questions — is in [docs/vision.md](docs/vision.md).
+
+## Is lyman a good fit for you?
+
+**Probably yes, if:**
+
+- You're building a **narrow, purpose-built agent** — an email triager, a log
+  summarizer, a domain-specific assistant — tailored to specific problems and
+  specific models, and you want to iterate on it *fast*.
+- You run models **locally or self-hosted** and want to build a harness that
+  treats that as the primary case, not an afterthought.
+- You want to **understand and modify your whole agent loop**, not configure
+  the edges of someone else's.
+- You like Ruby, or at least like the idea of an agent harness you can read
+  top to bottom in a single coding session.
+
+**Probably not, if:**
+
+- You want a no-code / low-code agent builder. Lyman is a developer's tool.
+- You want feature parity with frontier-model harnesses and popular coding
+  agents. Lyman isn't chasing checklists — it's chasing the shortest path
+  from "what if the workflow did *this*?" to finding out.
+- You want a batteries-included platform with every integration bundled.
+  Lyman's bet is that shifty makes those things easy enough to build yourself
+  that shipping them all would be beside the point.
+
+## The generator
+
+Lyman is delivered as a **pure generator**, in the spirit of shadcn/ui: the
+gem's whole job is to plant legible, manifest-tracked modules into *your*
+project, individually upgradeable and yours to extend — or eject and adopt
+outright. No runtime framework to call into; your harness's only runtime
+dependency is shifty. "Guts on the outside" extends to whose tree the code
+lives in. The reasoning is written down in
+[docs/design/deployment.md](docs/design/deployment.md).
+
+```sh
+lyman new my-agent      # scaffold a project: harness, workers, manifest
+lyman list              # what lyman installs, and this project's status
+lyman update            # refresh pristine modules; halt (never clobber) on modified ones
+lyman diff conversation # your changes, and upstream's since you planted
+lyman eject conversation# take ownership; lyman stops managing it
+lyman doctor            # smoke-test the pipeline against a stub transport
+```
+
+`.lyman/manifest.yml` records what was planted, at which version, with which
+content hash — so `update` knows pristine from modified, ejected modules get
+upstream-change advisories instead of merges, and your harness script is never
+touched at all: it's yours from day one.
+
+## Status
+
+Early and moving. What exists today: the vision, circuit-pattern, and
+deployment design docs, the core `Conversation` item, chat-completion and
+tool-execution workers, a working tool-using chat harness against live local
+models, and the generator CLI (`new` / `add` / `update` / `eject` / `diff` /
+`doctor` / `list`) with a Minitest suite behind it. Not yet published to
+rubygems.org — for now, run it from a checkout. On deck: publishing the gem,
+tool-call fan-out, and a one-shot (non-REPL) harness.
+
+## License
+
+[MIT](LICENSE)

data/docs/design/circuit-pattern.md

@@ -0,0 +1,167 @@
+# Design note: cycles in a linear pipeline — the circuit pattern
+
+**Status:** accepted direction (pre-implementation)
+**Resolves:** open question #1 in [../vision.md](../vision.md)
+
+## The problem
+
+The agentic core of a conversation turn is a cycle: assemble request → call
+model → *if the model called tools* → execute tools → append results → call
+model again → … until the model answers without tool calls (or a guard trips).
+The number of round trips is unknown at wire-up time; the model decides it at
+runtime, per turn.
+
+Shifty, however, is a strictly **linear, demand-driven pull chain**:
+
+- Every worker has exactly one `supply`. `pipeline.shift` asks the *last*
+  worker for a value, which pulls from its supply, and so on up to the source.
+  Data flows down only because demand flows up.
+- `Gang` is a list; composition is concatenation. There is no fan-in, no
+  fan-out, and no back-edge.
+
+A naive back-edge (wiring the tool executor's output in as the model caller's
+supply) cannot work: in a pull model, a topological cycle isn't a loop — it's
+demand chasing its own tail. Shifty's linearity is load-bearing.
+
+The values tension: the model⇄tool cycle is *the workshop* — where most
+tinkering happens. "Guts on the outside" demands the loop be visible and
+splice-able, but shifty's natural escape hatch (a `while` loop hidden inside
+one fat worker's closure) buries exactly the thing we most want exposed.
+
+## Shapes considered
+
+| Shape | Verdict |
+|---|---|
+| **A. Fat worker** — one worker with an internal `while` loop doing model calls and tool dispatch | Rejected. The entire workshop becomes one opaque node; no splice points. Fails the design razor hard. |
+| **B. Queue-mediated pseudo-cycle** — linear topology; a source reads from a queue; a tail worker re-enqueues unfinished items | Rejected *as originally conceived* (queue hidden inside the pipeline) — but see below: with the queue moved into the shell's scope, this objection dissolves. |
+| **C. Unrolled N passes** — wire model→tool→model… a fixed K times | Rejected. K is a lie; the runtime iteration count is the model's decision. |
+| **D. Loop lives in the enclosing scope** — linear inner pipeline; a small loop in coordinating scope re-feeds rounds | Right control-location instinct, but as first sketched it implied a new primitive. |
+
+**The resolution is B + D combined:** the queue-mediated shape, with the queue
+living in the shell's enclosing scope — declared in the one legible wiring
+script, right next to the conversation state. Not smuggled; on the table.
+
+## The circuit pattern
+
+Stock shifty parts only. Illustrative pseudocode — **not committed API**:
+
+```ruby
+rounds = []   # the queue: shell scope, visible in the wiring script
+
+inner = source_worker { rounds.shift }                                    \
+      | relay_worker    { |c| call_model(c) }                             \
+      | splitter_worker { |c| c.pending_tool_calls.any? ? c.split_tool_calls : [c] } \
+      | relay_worker    { |c| c.tool_call? ? execute(c) : c }             \
+      | batch_worker    { |c, batch| c.round_complete?(batch) }           \
+      | relay_worker    { |batch| merge_round(batch) }                    \
+      | side_worker     { |c| rounds << c unless c.finished? }            \
+      | filter_worker   { |c| c.finished? }
+```
+
+**The loop needs no loop.** When the shell calls `inner.shift`, the tail
+`filter_worker` pulls until it receives a *finished* turn. Each time an
+unfinished round reaches the tail, the `side_worker` has already re-enqueued
+it; the filter rejects it and pulls again; demand propagates back up to the
+source, which finds the re-enqueued item waiting. **N model⇄tool rounds happen
+inside a single `shift` call, driven entirely by shifty's own demand
+semantics.**
+
+Role assignments:
+
+- **`source_worker`** — reads from the queue; the only worker that knows where
+  items originate.
+- **`splitter_worker` / `batch_worker`** — tool-call fan-out/fan-in: one model
+  response with three tool calls → three items → three executions → gathered
+  back into a round.
+- **`side_worker`** — the back-edge: re-enqueues unfinished rounds.
+- **`filter_worker`** — the loop condition: only finished turns escape.
+
+Every stage is an ordinary, visible, spliceable worker.
+
+### No third primitive
+
+The cycle is a **pattern, not a primitive**. Shifty keeps exactly `Worker` and
+`Gang`; lyman ships the circuit as a documented, scaffolded pattern made of
+stock parts. This is "keeping shifty shifty" in the strongest sense.
+
+## The shell
+
+The enclosing scope is called the **shell** (formerly "conductor" in early
+discussion). A shell is **state + a process** — an environment holding the
+conversation and the queue, plus a driving process that is usually just a
+`while` loop (or no loop at all, for a one-shot agent that takes a single
+input, runs, and terminates).
+
+The shell is *deliberately boring*. Other than setting up state, it does
+nothing interesting — and that is a feature. If a shell is getting
+interesting, something in it probably belongs in a worker.
+
+Whether repetition happens via an unsatisfied filter at the tail or via
+`while pipe.shift do ... end` in the shell, the shell remains just environment
+plus process. A human REPL is one shell; an autonomous email triager is
+another; same architecture, different shells.
+
+**A TUI is not a shell.** A TUI is much more interesting than a shell, and
+should run in parallel with the pipeline (so it isn't blocked while the
+pipeline works). This keeps UI concerns from colonizing the shell.
+
+## Item-as-control, and its discipline
+
+The conversation item both *is mutated by* workers and *directs their
+behavior* (e.g. `finished?`, `tool_call?`, pending tool calls). This is the
+mechanism that keeps the pattern in stock shifty — but it is a spectrum with a
+poisoned end:
+
+- **Pass-through-if-not-mine** — a worker acts only when the item is in its
+  jurisdiction, else hands it along unchanged. Fine; same move
+  `filter_worker` already makes. The topology still tells the truth.
+- **Multi-way dispatch** — a worker that inspects item state and does one of
+  several different jobs. A hidden pipeline folded into one worker; the
+  diagram lies. **Named anti-pattern.**
+
+**The discipline:** *an item may tell a worker **whether** to act, never
+**which of several things** to do. If you're switching, you're missing a stage
+(or a splitter).*
+
+## Control granularity: filter-in by default
+
+- **Filter-in** (as sketched): the shell's `shift` returns once per *turn*;
+  all rounds happen inside the call.
+- **Filter-out**: drop the tail filter; `shift` returns once per *round*, and
+  the shell does its own re-enqueueing.
+
+Observability is a non-question either way — logs, TUI updates, and traces are
+side workers, spliceable anywhere, and the shell can always inspect the queue
+in its own scope. The real difference is **intervention**: with filter-out,
+the shell can act between rounds (e.g. human approval of tool calls).
+
+But intervention doesn't require control to return to the shell. A worker
+*closes over the shell's scope* (the shifty README's "wormhole effect"), so an
+approval gate can be a side worker that calls out to whatever collaborator the
+shell scope provides, blocking until answered.
+
+**Scaffold default: filter-in.** The turn is the natural unit at the spine;
+rounds are the circuit's internal rhythm. Round-granularity access is a
+legitimate *rewiring* — same parts, different wiring — which is the
+kit-of-parts promise kept.
+
+## Known sharp edges (must be handled in scaffold + docs)
+
+1. **The nil footgun.** In shifty, a source returning `nil` means *end of
+   stream, forever*. An empty queue naturally returns `nil` from
+   `rounds.shift` — so a shell that pulls at the wrong moment doesn't get an
+   error; it permanently kills the pipeline. The scaffold must handle this
+   deliberately (shell only shifts after enqueueing, or the source
+   blocks/guards), and the docs must explain why.
+2. **Runaway turns.** A model that never stops calling tools would cycle
+   forever inside one `shift`. Guard: the item carries a round counter; a
+   small guard worker marks the turn finished-with-error past a limit.
+   Control data riding on the item — consistent with the discipline above.
+
+## What the visualization shows
+
+The circuit is depicted as a single node annotated with its loop condition
+("loops until: no tool calls"); drilling in reveals a plain linear pipeline
+with a marked back-edge (the re-enqueueing side worker) and exit (the filter).
+A loop *annotation* on a node can be depicted honestly; an actual graph cycle
+in a pull model cannot.

data/docs/design/deployment.md

@@ -0,0 +1,195 @@
+# Design note: deployment — lyman as a pure generator
+
+**Status:** accepted direction (pre-implementation)
+
+## The problem
+
+Lyman scaffolds *other projects*; it is not itself the thing users run. That
+makes it rails-shaped at first glance: a globally installed gem used to create
+and embellish client projects. But the rails analogy bundles two roles that
+don't have to travel together:
+
+1. **Generator** — `rails new`, the scaffolding tool.
+2. **Runtime dependency** — the framework the app calls into forever.
+
+The second role is in tension with lyman's core value. If
+`Lyman::Workers.chat_completion` lives inside a gem, its guts are back inside
+a box: users can read the source, but they can't casually splice into it the
+way they can with code sitting in their own tree. "Guts on the outside" is a
+claim about *whose tree the code lives in*, not just whether the source is
+public.
+
+## Shapes considered
+
+| Shape | Verdict |
+|---|---|
+| **A. Conventional framework gem** — gem is both generator and runtime; client projects `require "lyman"` forever | Rejected. Every worker that lives in the gem is a seam that got harder to splice. The transparency promise erodes one convenience at a time. |
+| **B. Template repository** — clone/fork a starter repo, no gem at all | Rejected. No upgrade story, no incremental `add`, no tooling seam for guidance. Fine for a demo; not a deployment model. |
+| **C. Pure generator (the shadcn/ui model)** — the gem is a CLI that copies legible source into the client project, which the user then owns | **Accepted.** The framework is delivered as code you own — the deployment-shaped version of the design razor. |
+
+Under shape C, the client project's only runtime dependency is `shifty`. There
+is little or no `require "lyman"` at runtime; the lyman gem exists to plant,
+diff, and update artifacts.
+
+## The unit of upgrade is the unit of extraction
+
+Copy-in's known trade-off is that copied code can't be `bundle update`d. The
+answer is granularity: lyman plucks *modules* from its own codebase and plants
+them as individual files, each tracked and upgraded independently.
+
+This creates a forcing function that happens to point the same direction as an
+existing principle. "The shell stays boring" was already the rule; now it has
+teeth:
+
+> Anything living inside the harness script is frozen the moment the user
+> edits that script — and the user editing the harness is the *expected case*;
+> it's their wiring diagram. Every behavior with any chance of shipping an
+> improvement (a think-filter, `wire_messages`, a streaming printer) belongs
+> in a planted module the harness merely references.
+
+The harness script should asymptotically contain nothing but wiring: state
+declarations, worker instantiation, the driving loop. If a module upgrade
+would be blocked by a harness edit, the module was extracted at the wrong
+boundary. Two design pressures — legibility and upgradeability — enforcing the
+same rule is a sign the architecture is right.
+
+The harness itself is **owned from day one**: planted once at `lyman new`,
+marked owned in the manifest, never a target of `lyman update`. If a new
+lyman version has a better harness shape, that ships as an advisory ("a new
+example harness is available; see diff"), never a merge.
+
+## The manifest
+
+Comments in planted files ("managed by lyman — extend, don't modify") are
+social signaling; the mechanism is a manifest written at plant time —
+`.lyman/manifest.yml` — recording each managed artifact's source version and
+content hash. `lyman update` then has three cheap cases per file:
+
+- **Hash matches** — pristine; replace silently. Smooth sailing, verified
+  rather than hoped-for.
+- **Hash differs** — modified; halt with a message. Because lyman knows
+  exactly which version it planted, it can show a real three-way diff
+  (pristine-as-planted → user's copy, pristine-as-planted → new pristine)
+  instead of "something changed."
+- **Not in manifest** — user-owned; never touched.
+
+Every entry also records the artifact's planted `path`. Artifact names are
+logical identities (the changelog speaks in module names, and a name survives
+upstream relocating a file); the path is where *this project's* copy lives.
+Recording it keeps each entry self-describing — an entry for an artifact some
+future lyman release renamed or dropped still names its file — and lets
+lifecycle commands operate from the manifest alone, consulting the registry
+only for what the current release would plant. The pristine cache mirrors the
+planted tree (`.lyman/pristine/lib/lyman/…`), so neither store depends on
+artifact names staying collision-free forever. When a release's destination
+disagrees with the manifest's path, `update` halts rather than guessing which
+references a move would break.
+
+Per-artifact versioning falls out of the manifest for free: the changelog can
+speak in terms of named modules ("`think_filter` 0.3 → 0.4: constructor now
+takes…"), and `update` emits deprecation notices only for modules the project
+actually has. Breaking changes to any planted artifact are therefore a
+first-class release concern — a halt with a clear, specific message is the
+contract that lets the programmer (and their coding agent) resolve breakage
+before proceeding.
+
+Namespacing reinforces the boundary visibly: `Lyman::` = managed, the
+project's own namespace = owned. The line is legible in every constant
+reference.
+
+## Eject-to-own
+
+"Don't modify, extend" must not read as glass over the guts. The guidance is
+reframed from prohibition to **ownership transfer**: modifying a managed
+module is legitimate — it means you've adopted it, and lyman stops managing
+it. `lyman eject think_filter` makes the transfer an explicit verb rather than
+a hash mismatch discovered later.
+
+Ejection leaves a **tombstone record**, not a deleted entry:
+
+```yaml
+think_filter:
+  status: ejected                  # was: managed
+  ejected_at: 0.3.0                # lyman version when the dev took ownership
+  path: lib/lyman/think_filter.rb  # where it was planted; the fork lives here
+  pristine_hash: abc123            # hash of the pristine copy at ejection time
+```
+
+The tombstone buys three things a bare deletion can't:
+
+1. **Advisories.** `lyman update` gains a third message tier: managed files
+   upgrade, unknown files are ignored, ejected files get an informational
+   notice — "`think_filter` (ejected at 0.3.0) has upstream changes in 0.5.0;
+   run `lyman diff think_filter` to compare." No action, no halt; the dev or
+   agent decides whether the upstream improvement is worth porting into their
+   fork.
+2. **A meaningful diff.** `ejected_at` is the fork point. Without it the only
+   diff available is "upstream vs. your file," which mixes upstream's changes
+   with the dev's. With it, `lyman diff` shows *only what upstream changed
+   since the fork* — the same reason git tracks merge bases.
+3. **Collision safety.** A later `lyman add think_filter` knows there's
+   history and asks rather than clobbers.
+
+Heritage lives in the manifest, not in the file's identity. Renaming or
+re-namespacing an ejected file would sever exactly the thread that makes the
+advisory possible, and break every reference in the harness for no gain. The
+file stays where it is, named what it is; ejection changes only who the
+manifest says maintains it.
+
+Open detail (decide when the command exists): advisories should probably fire
+once per new upstream version (a `notified:` field) rather than on every
+`update`, so a long-lived fork doesn't nag forever.
+
+## Guidance for coding agents
+
+Deployment includes deploying *understanding* — shifty and lyman are not
+complicated once you know how to use them, but how to use them is not obvious.
+Three channels, ordered by reach:
+
+1. **Scaffolded into the project.** `lyman new` emits a `CLAUDE.md` (or
+   `AGENTS.md`) as a first-class artifact carrying the load-bearing facts: the
+   nil-source footgun, the runaway-turn guard, item-as-control discipline,
+   wire-vs-conversation separation. Highest-value channel: works with any
+   coding agent, zero install steps, travels with the code.
+2. **A Claude plugin marketplace** in the `joelhelbling/lyman` repo, for
+   richer *procedures* — e.g. a skill that knows how to wire a new tool worker
+   correctly, or how to read a stalled pipeline. Skills earn their keep when
+   there's a procedure; facts belong in the scaffolded doc.
+3. **Published docs / `llms.txt`** for indexing, so agents that installed
+   nothing still find accurate usage docs rather than hallucinating a shifty
+   API.
+
+## Ruby without a type checker
+
+Copy-in plus extension-over-modification is where statically typed languages
+would catch contract drift at compile time. What replaces the compiler here:
+
+1. **A tiny contract surface.** A shifty worker's interface is "take an item,
+   yield an item." The real contract is the item shape — `Conversation` and
+   its string-keyed messages. One class; most breaking changes will be changes
+   to it, so compatibility care concentrates there.
+2. **Errors designed for agents.** `lyman update` failures must be structured
+   and specific ("`think_filter` modified since 0.3.0; pristine copy at …;
+   diff: …") the way a compiler error names file, line, and expectation. A
+   good error message is a type checker with one-round-trip latency.
+3. **A runnable check.** `lyman doctor`: run the project's pipeline against a
+   stub model transport and assert a well-formed `Conversation` comes out the
+   other end. A smoke-level contract test `update` can run automatically
+   post-upgrade — the closest thing to "it compiles" a duck-typed pipeline can
+   offer.
+
+Honest caveat: the manifest catches modified *files*, not broken *extensions*.
+A subclass of a managed module can break when the parent changes even though
+every hash matches. `doctor` is the backstop, and it's another reason managed
+modules keep their public surfaces deliberately small and dull.
+
+## Practical notes
+
+- The `lyman` gem name is unclaimed on rubygems.org as of 2026-07-04; register
+  early, even as a placeholder.
+- No runtime `lyman chat` command. The moment the CLI *runs* harnesses rather
+  than *generating* them, the shell stops being the user's visible loop.
+- This repo pins Ruby via `mise.toml`; scaffolded projects should declare a
+  looser constraint, and install docs should assume a user starting from zero
+  Ruby tooling (the target user is "person with Ollama running," not
+  necessarily a Rubyist).