@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/smidja-factory/cookbooks/create_config.md

@@ -0,0 +1,61 @@
+# Create Config
+
+Generate `smidja.config.yaml` — the agent roster for a target repo.
+
+## Generate it
+
+```bash
+uv run .claude/skills/smidja/scripts/make_config.py
+```
+
+Writes `smidja/smidja_smidja_config/smidja.config.yaml` — creating the directory if needed — with the starter agents (planner, builder, scout, reviewer, documenter) wired to the prompt files `/smidja install` stamped into `smidja/smidja_data/prompt_engineering/`. That path is the default every smidja and the justfile look for; `--config` overrides it. `make_config.py` refuses to overwrite an existing config unless you pass `--force`, so retuning an existing roster is a hand edit — see `update_config.md`.
+
+## The rule
+
+**One agent, one prompt, one purpose.** An entry defines who an agent *is*: its coding agent, model, thinking level, and exactly one system prompt plus one user prompt. How it gets *used* — the output type, a per-call user prompt override — lives at the smidja call site, never here.
+
+## Schema
+
+```yaml
+defaults:
+  coding_agent: pi                 # v1: pi only (claude_code is specced, stubbed until v2)
+  model: google/gemini-3.6-flash   # ALWAYS provider/model-id — a bare id is ambiguous
+  thinking: medium                 # off | minimal | low | medium | high | xhigh | max
+  harness_engineering: []          # pi extension names
+  data_dir: smidja/smidja_data          # runtime home: {data_dir}/sessions/{smidja_id}/{agent_name}/
+
+observability:
+  db: smidja/smidja_data/smidja.db        # tracer writes here; the UI polls it
+  poll_ms: 500                     # visualizer live-poll cadence
+
+agents:
+  - name: planner                  # smidja scripts name agents, never models
+    coding_agent: pi
+    model: google/gemini-3.6-flash
+    thinking: high
+    color: "#a78bfa"               # optional hex — this agent's lane color in the visualizer
+    purpose: Turn a request into a plan the builder can implement without asking questions.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/planner/system.md
+      user: smidja/smidja_data/prompt_engineering/planner/user.md
+
+  - name: scout
+    thinking: high                 # unset keys fall through to defaults
+    purpose: Find and report where things live; change nothing.
+    prompt_engineering:
+      system: smidja/smidja_data/prompt_engineering/scout/system.md
+      user: smidja/smidja_data/prompt_engineering/scout/user.md
+    tools:                         # optional allowlist — omit the key entirely for all tools
+      - read
+      - bash
+```
+
+Every agent entry merges over `defaults`, so an entry only states what differs. Pi's builtin tools are `read`, `bash`, `edit`, `write` — a read-only recon agent gets `[read, bash]`; a builder omits `tools` altogether.
+
+## After generating
+
+1. Each agent needs its prompt pair to exist on disk: `smidja/smidja_data/prompt_engineering/{name}/system.md` and `user.md`. `agents.validate()` fails the run at startup if either is missing.
+2. Write `purpose` as one sentence and make the system prompt say the same thing — the two should not drift.
+3. Validate by running the smallest smidja that names your agents; a bad entry fails fast, before anything spawns.
+
+Full field-by-field spec, thinking-level mapping, and model resolution: `references/config.md`. Retuning an existing roster: `update_config.md`.

package/apps/smidja-factory/cookbooks/create_smidja.md

@@ -0,0 +1,120 @@
+# Create smidja
+
+Compose a new smidja script — a thin, deterministic Python workflow over agents already in the config. Design the chain first, then generate or hand-write it.
+
+## Step 1 — Design the chain
+
+Answer four questions, in order:
+
+1. **What agents, in what order?** Pick from the roster (`smidja/smidja_smidja_config/smidja.config.yaml`). The starter six cover most chains:
+
+| Agent | Use when | Output type | Typical gates |
+|---|---|---|---|
+| `scout` | you need to FIND something first — read-only recon | `ScoutOutput` | `artifacts_exist` |
+| `planner` | the work needs a plan before code changes | `PlanOutput` | `artifacts_exist`, `files_non_empty` |
+| `builder` | code must change | `BuildOutput` | `diff_matches_claims` |
+| `reviewer` | the change must be confirmed to BE what was asked for | `ReviewOutput` | `artifacts_exist`, `verdict_consistent` |
+| *(no tester)* | verifying that it RUNS is a `kind="code"` phase over `quality.py`, not an agent | `QualityResult` → `as_envelope` | the exit code is the check |
+| `documenter` | finished work needs a write-up (runs after a build, off the diff) | `DocumentOutput` | `artifacts_exist`, `files_non_empty` |
+| any agent, generic ask | one-off prompt, no special shape | `GenericOutput` | as needed |
+
+   A new kind of agent needs a config entry + prompt pair + output type first — see `update_config.md`.
+
+   **The suite and the reviewer answer different questions.** "Does it run" is a test, and code can ask that. "Is this the thing that was asked for" is a review, and only an agent can. A green suite over a feature nobody requested is still a failed request, and neither one covers for the other.
+
+2. **Where does code act?** Git branch/commit, migrations, deploys each get their own `kind="code"` phase — never buried inside an agent phase.
+
+   **Running the suite is one of these — there is no tester agent.** The command is written down in `quality.py`, so a `kind="code"` phase runs it (`quality.run_tests(run)` → `quality.as_envelope(result, "tests")` back into the builder) and the bounded repair loop is unchanged. An agent rediscovering `bun test` on every run buys nothing a subprocess does not already know. Capturing what changed is one of these: `changes.capture(run, ChangeCapture(base="main"))` diffs the working tree against a resolved base, writes `context_handoff/changes.diff`, and `changes.as_envelope(...)` hands it to the next agent. A diff is two git commands, not a judgement call.
+
+3. **Does anything loop?** Test-fix cycles are bounded fix loops (see `update_adw.md`), not phase retries.
+
+4. **What does each call need to prove?** Pick gates per call from `gates.py`: `artifacts_exist`, `files_non_empty`, `json_parses`, `diff_matches_claims`, `tests_pass("cmd")` — or an inline one-off.
+
+## Step 2 — Ownership rules (the swim lanes depend on these)
+
+- `kind="agent"` → `owner` MUST be an agent name from the config — it selects the harness (model, thinking, tools, prompts) AND the lane. `ph.call()` runs whoever owns the phase.
+- `kind="engineer"` → `owner=run.engineer`. Every smidja opens with the engineer request phase — it is the system input record.
+- `kind="code"` → `owner` is a short actor label (`"git"`, `"db"`); all code phases share the code lane.
+- Phase `name` must be unique within the run (`plan`, `build`, `test_1`, `fix_1`, …) — the UI keys blocks on it.
+- **`description` is required and must earn its place.** The name identifies the phase; the description explains it — what this phase does and why, in one sentence. It rides the `phase_start` event and is the only line of intent the trace, the console, and the phase block ever show. `PhaseParams` raises at construction on a blank description *or* one that merely restates the name (`commit_plan: "Commit the plan"`), so the rule fails before the phase opens rather than leaving an unreadable run in the db. Write `"Put the spec on record before any code exists to blur it"` instead.
+- `retries=N` on an **agent** phase = extra gate-correction rounds re-sent into the same session (pi's `--session-id` creates-or-continues, so context stays intact). Code-phase re-execution is not implemented in v1.
+
+## Step 3 — Generate or write it
+
+```bash
+uv run .claude/skills/smidja/scripts/make_adw.py --name review_docs --agents scout,builder
+```
+
+Writes `smidja/smidja_review_docs.py`: one agent phase per name, chained by `previous=`, starter agents mapped to their output types, unknown agents to `GenericOutput`. It does NOT create config entries or prompt files — do that first (`update_config.md`), or `agents.validate()` will stop the run and tell you what's missing.
+
+## The canonical skeleton
+
+Every `smidja_*.py`, generated or hand-written, is a `uv` single-file script with this shape:
+
+```python
+#!/usr/bin/env -S uv run
+# /// script
+# dependencies = ["pydantic", "python-dotenv", "pyyaml", "rich"]
+# ///
+"""smidja Plan Build — plan the request, then implement the plan."""
+
+import argparse
+import sys
+
+from smidja_modules import agents, gates, git_helper, session, utils
+from smidja_modules.data_types import AgentCall, BuildOutput, PhaseParams, PlanOutput
+
+REQUIRED_AGENTS = ["planner", "builder"]        # names, never models
+
+
+def main(prompt: str, config: str = "smidja/smidja_smidja_config/smidja.config.yaml", smidja_id: str | None = None) -> int:
+    cfg = agents.load_config(config)            # 1. point to config
+    agents.validate(cfg, REQUIRED_AGENTS)       # 2. fail fast — nothing spawns on a half-valid config
+    run = session.ensure(cfg, smidja_id)           # 3. pin-or-create the session → the Run object
+
+    with run.phase(PhaseParams(name="request", kind="engineer", owner=run.engineer,
+                               description="Capture the incoming ask")) as ph:
+        ph.log(input=prompt)
+
+    with run.phase(PhaseParams(name="plan", kind="agent", owner="planner",
+                               description="Turn the request into an implementable plan")) as ph:
+        plan = ph.call(AgentCall(output_type=PlanOutput, prompt=prompt,
+                                 gates=[gates.artifacts_exist, gates.files_non_empty]))
+
+    with run.phase(PhaseParams(name="build", kind="agent", owner="builder", retries=1,
+                               description="Implement the plan exactly")) as ph:
+        build = ph.call(AgentCall(output_type=BuildOutput, prompt=prompt, previous=plan,
+                                  gates=[gates.diff_matches_claims]))
+
+    with run.phase(PhaseParams(name="commit", kind="code", owner="git",
+                               description="Commit the working tree")) as ph:
+        message = build.commit_message or f"smidja({run.smidja_id}): {build.summary}"
+        ph.log(sha=git_helper.commit_all(message), message=message)
+
+    return run.finish()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("prompt", help="inline text or a path to a prompt file")
+    parser.add_argument("--config", default="smidja/smidja_smidja_config/smidja.config.yaml")
+    parser.add_argument("--smidja-id", default=None, help="join or pin an existing session")
+    args = parser.parse_args()
+    sys.exit(main(utils.resolve_prompt(args.prompt), args.config, args.smidja_id))
+```
+
+## Non-negotiables
+
+- **`REQUIRED_AGENTS` + `agents.validate()`** — declare every agent name the script uses and validate before the first phase.
+- **Every agent call declares a concrete output type** from `data_types.py`. No untyped handoffs.
+- **`previous=` carries the chain** — the upstream envelope lands in the next agent's `user.md` as `{{previous_envelope}}`; bulky context moves through `context_handoff/` files the envelope references.
+- **The engineer request phase comes first**, always.
+- **Four-param rule** — `run.phase()` and `ph.call()` each take exactly one object; new helpers with >4 params get a data type.
+- **Stay thin** — sequencing and acceptance only; real logic goes in `smidja_modules/` (`update_modules.md`).
+- **Committing is a code phase, and it needs a fallback.** `PlanOutput`, `BuildOutput`, and `DocumentOutput` each carry a `commit_message` the agent writes **for its own work product** — the spec, the code, the write-up. It defaults to empty, so always `envelope.commit_message or <fallback>`, and commit each product with the message of the agent that made it (`smidja_simple_sdlc.py` commits three times and never crosses them). `git_helper.commit_all(message)` stages everything, commits, and returns the short sha; it raises a clear error when the cwd isn't a git repo or nothing changed, and that raise fails the phase.
+
+## Before you ship it
+
+1. `uv run smidja/smidja_<name>.py "a tiny real request"` — watch it go green end to end.
+2. Check the trace: `sqlite3 smidja/smidja_data/smidja.db "select seq,name,kind,owner,status from phases where smidja_id='<id>' order by seq;"`
+3. Read the final `envelope.json` — is the output type earning its fields, or should it be sharper?

package/apps/smidja-factory/cookbooks/how_to_prompt_for_the_eng.md

@@ -0,0 +1,110 @@
+# How to Prompt for the Engineering
+
+Read this **before every smidja launch**. The prompt you pass is what the whole chain reads: the planner plans from it, the builder builds from it, the reviewer judges against it. Your prompt might run through 10s or 100s of agents. A sloppy prompt is not a small tax; it is paid again by every agent in the chain.
+
+## Purpose
+
+Turn what the engineer said into the prompt the smidja receives: **clearer, not different.** You are a translator, not a redesigner.
+
+## The one rule
+
+**The intent is theirs. The precision is yours.**
+
+| You MAY | You MAY NOT |
+|---|---|
+| Carry every constraint forward, verbatim | Quietly drop a requirement because it looks hard or odd |
+| Fix grammar, cut rambling, order the steps | Soften a strong ask ("rewrite" → "refactor a bit") |
+| Change the language used to better communicate the idea | Research the codebase for exact file names, never go into the app |
+
+If you catch yourself improving the *idea* rather than the *sentence*, stop. Raise the concern to the engineer in your own message and launch what they asked for.
+
+## You never touch the application, you prompt, monitor, observe, and report.
+
+Outside of understanding the smidja, you never research, touch, or dive into the codebase thats being operated on.
+
+Your role is to simply kick off the workflow. There are entire teams of agents inside these smidja built to do the work.
+
+Your job is to kick it off, monitor, observe, report. Not interact with the application layer. You operate only on the agentic layer, the smidja, the smithy.
+
+## The shape
+
+Four lines. Nothing else earns its tokens.
+
+```
+<the ask — one imperative sentence, their words where they were specific>
+Where: <files or dirs you verified>
+Done means: <the observable result — a response shape, a passing test, a rendered element>
+Out of scope: <what you were tempted to add, named so nobody adds it>
+```
+
+**Before** (what the engineer said):
+
+> can we get tags on posts, sorted by popularity
+
+**After** (what the smidja receives):
+
+```
+Add a GET /api/tags endpoint returning {tags: [{tag, count}]} — the distinct tags
+across all posts with how many posts carry each, sorted by count descending then
+tag ascending.
+Where: src/server.ts (routes), src/server.test.ts (tests)
+Done means: GET /api/tags returns the counts, and a new test in server.test.ts covers it.
+Out of scope: tag editing UI, tag filtering on the post list.
+```
+
+Same idea, same scope. What changed is that "popularity" became a sort order, the files are named, and nobody has to guess where it stops.
+
+## Which smidja
+
+**If the engineer named one, launch that one.** Their call stands — no second-guessing, no "upgrading" them to a longer chain. If you think another fits better, say so in your own message and launch what they asked for.
+
+**If they did not, read what this repo actually has and choose from that.**
+
+```bash
+ls smidja/smidja_*.py                       # the menu
+head -20 smidja/smidja_<name>.py            # every smidja opens with its `Phases:` line — the chain in one line
+```
+
+Chains are the engineer's to add, rename, and rewire, so **the files on disk are the only authority**. Never launch from memory or from a name you saw in a doc; read the docstrings, then match by shape:
+
+| The work | Look for a chain that |
+|---|---|
+| Changes code, and the shape is not obvious — new behaviour, more than one file, anything you would want a plan for | goes end to end: plans, builds, verifies, reviews, and documents |
+| Changes code, one well-understood edit | plans, builds, and verifies |
+| Implements a plan this session already produced (`--smidja-id`) | starts at build and verifies |
+| Confirms built work is what was asked for | ends in a review phase |
+| Writes up work already shipped | captures the diff and documents it |
+| Is a question, and nothing should change | is a single read-only agent — the one case where one phase is right |
+
+**Never a single-agent chain when the engineer asked for work to be done.** One-phase smidja answer questions and run one-offs; they do not deliver.
+
+**The more complex the ask, the more complete the chain.** Complexity means: more than one file, a behaviour you cannot describe in one sentence, anything touching data or an interface others call, or any request where you had to guess. When two chains both fit, take the longer one — a phase you did not need costs cents, while a change nobody planned, verified, reviewed, or wrote up costs an afternoon.
+
+If nothing on disk fits the shape you need, say so and offer to compose one (`create_adw.md`) rather than forcing the work into a chain that skips the phase it needed.
+
+## Workflow
+
+1. **Read it twice.** Mark every noun that could point at two things.
+2. **Verify before you write.** Every path, route, and symbol you put in the prompt must exist — check it. A wrong path costs a whole build phase.
+3. **Draft the four lines.**
+4. **Diff against the original.** Every specific thing they said, still there? Anything in your draft they did not say? Delete it.
+5. **Ask at most one question**, only when two readings would produce different code. Otherwise state your assumption in the prompt and say so when you report.
+6. **Launch** the chain from *Which smidja* above; `run_adw.md` covers the mechanics and the watching. Inline for a short ask; for anything longer, write `requests/<slug>.md` and pass the path — every smidja takes either.
+
+## Rules that do not bend here
+
+- **Do not write the plan.** Your prompt says WHAT and DONE MEANS. HOW belongs to the planner — unless the engineer specified how, and then you carry it word for word.
+- **Do not address the harness in the prompt.** "Use the reviewer", "retry twice", "then commit" are chain choices, and the chain is chosen by which smidja you launch, not by prose the agents will read.
+- **Do not pad.** No preamble, no restating the repo, no encouragement. Gates check claims, not prose.
+- **Their exact words survive.** When the engineer was specific — a name, a number, a format, a file — quote it rather than paraphrasing.
+
+## Report back
+
+After launching, show the engineer three things so a bad translation dies in seconds rather than at the commit phase:
+
+1. **The prompt you actually sent** — verbatim.
+2. **The smidja you chose**, and the one-line reason — or that you used the one they named.
+   If they named a roster (a config, a model tier), say which one you ran on; if they did not, you ran the default, and switching that is their call, not yours (`run_adw.md`).
+3. **The `smidja_id`**, so they can watch it (`just phases <smidja_id>`).
+
+Then observe and report per `run_adw.md`. You run the system; you do not do the work inside it.

package/apps/smidja-factory/cookbooks/install.md

@@ -0,0 +1,56 @@
+# Install
+
+`/smidja install` — stamp the entire smidja out of the skill and into the current working directory.
+
+## Run it
+
+```bash
+uv run .claude/skills/smidja/scripts/install.py
+```
+
+Run from the **target repo root** — the cwd is where everything lands. If the skill lives in your user scope, the path is `~/.claude/skills/smidja/scripts/install.py`.
+
+## What gets stamped
+
+`install.py` copies `templates/` into the cwd:
+
+| Stamped | From | Tracked? |
+|---|---|---|
+| `smidja/smidja_smidja_config/smidja.config.yaml` | `templates/smidja.config.yaml` | yes — the agent roster |
+| `.env.sample` | `templates/env.sample` | yes |
+| `smidja/smidja_*.py` | `templates/smidja/` | yes — the twelve starter smidja |
+| `smidja/smidja_modules/` | `templates/smidja/smidja_modules/` | yes — all low-level logic |
+| `smidja/smidja_data/prompt_engineering/{planner,builder,scout,reviewer,documenter}/` | `templates/prompt_engineering/` | yes — **the user-owned home for prompts** |
+| `smidja/smidja_data/harness_engineering/` | `templates/harness_engineering/` | yes — **the user-owned home for pi extensions** |
+| `justfile` | `templates/justfile` | yes — starter recipes: `just demo`, the workflows, the trace reads, `just obs` |
+| `smidja/smidja_data/sessions/`, `smidja/smidja_data/smidja.db` | created at runtime | no — gitignored |
+
+The two `*_engineering` dirs mirror the two config keys of the same name: `prompt_engineering` is what an agent is told, `harness_engineering` is what its harness can do. Both are yours the moment they are stamped. Edit them in `smidja/smidja_data/`, never back inside the skill.
+
+`harness_engineering/` ships with `subagents.ts` — the pi extension backing `subagent_create` / `_continue` / `_list` / `_remove`, wired to the planner and scout in the starter roster.
+
+## Idempotency
+
+Re-running is safe. `install.py` skips **every** file that already exists — your config, your prompts, and previously stamped code alike — and reports what it skipped, so a second run doubles as a drift check. To refresh stamped code (`smidja_modules/`, the starter `smidja_*.py`) to the skill's current version, run with `--force` — but know that `--force` overwrites ALL existing stamped files, including `smidja.config.yaml` and `prompt_engineering/`, so commit or back up user-owned edits first.
+
+## Post-install checklist
+
+1. **Env** — `cp .env.sample .env`, then set `OPENROUTER_API_KEY` in `.env`. (v1 runs Pi; `ANTHROPIC_API_KEY` / `CLAUDE_CODE_PATH` are only needed once Claude Code lands in v2.)
+2. **Pi is installed and on PATH** — `pi --version`. Set `PI_PATH` in `.env` if it is not.
+3. **The model resolves** — the config's default `gemini-3.6-flash` must be a registered id in `~/.pi/agent/models.json`. Check with `pi --list-models` or read the file directly; see `references/config.md` for model resolution.
+4. **Gitignore** — `install.py` appends `smidja/smidja_data/sessions/`, `smidja/smidja_data/smidja.db*`, and `.env` for you; confirm they landed. All three are runtime or secrets and must never be committed.
+5. **Git repo** — smidja that end in a commit phase call `git_helper.commit_all`, which raises if the cwd is not a git repository. Run `git init` and make a first commit before using `smidja_plan_build.py`, `smidja_plan_build_test.py`, or `smidja_simple_sdlc.py`. `smidja_document.py` needs one too: it measures the change with `git diff` against a base ref (`main` by default, `--base` to override).
+6. **Smoke test** — `just demo` runs two cheap read-only workflows back to back, or run the smallest smidja directly:
+
+```bash
+just demo                                                    # both, end to end
+uv run smidja/smidja_prompt.py "reply with a one-line summary of this repo"   # the raw form
+```
+
+Green means the whole path works: config validated, session minted, Pi ran, envelope parsed, events landed in `smidja/smidja_data/smidja.db`. Verify the trace exists before trusting anything larger:
+
+```bash
+sqlite3 smidja/smidja_data/smidja.db "select smidja_id, status from sessions order by started_at desc limit 1;"
+```
+
+If the smoke test fails, fix it before composing chains — every multi-agent smidja rides on this exact path.

package/apps/smidja-factory/cookbooks/run_smidja.md

@@ -0,0 +1,122 @@
+# Run smidja
+
+Run a workflow and report on it. **You run and observe — you never step into the process or do the work yourself.**
+
+## Step 0 — translate the request
+
+**Read [how_to_prompt_for_the_eng.md](how_to_prompt_for_the_eng.md) before you launch anything.** The prompt you pass is read by every agent in the chain, so it gets written deliberately: same intent, sharper words, verified paths, and a stated "done means". That cookbook is the whole procedure; this one starts once you have the prompt.
+
+## The orchestrator's posture
+
+The smidja is the worker. Your job is to launch it, watch the trace, and tell the engineer what happened. Do not read the agent's target files and "help", do not fix the code an agent was supposed to fix, do not edit an envelope. If a run fails, report the failing phase and its violations — the fix is a config, prompt, or smidja change, made deliberately, and then a re-run.
+
+## Launch
+
+Which chain to launch is decided in `how_to_prompt_for_the_eng.md`, and the short version is: **the smidja the engineer named, or else the most complete composed chain the work justifies — never a single-agent one.** Read `ls smidja/smidja_*.py` and the `Phases:` line in each docstring to see what this repo has; the names below are shape, not a menu.
+
+```bash
+uv run smidja/<end-to-end-chain>.py "add a /health endpoint"
+uv run smidja/<plan-build-verify-chain>.py requests/health.md
+uv run smidja/<build-first-chain>.py "implement the plan" --smidja-id a1b2c3d4
+uv run smidja/<recon-chain>.py "where is auth handled" --config path/to/other.config.yaml
+```
+
+The prompt is inline text or a file path. Launch in the background so you can poll while it works; the `smidja_id` is printed on startup — capture it, everything else keys off it.
+
+### Listen for the roster
+
+The chain says *what runs*; the config says *who runs it*. **If the engineer references a roster, a config, or a model tier, pass it — do not fall through to the default.**
+
+```bash
+just rosters                            # every roster on disk, and the model each agent runs
+```
+
+That prints the path to pass and who is in it, in one read:
+
+```
+smidja/smidja_smidja_config/smidja.config.yaml
+    planner     fireworks/accounts/fireworks/models/kimi-k3
+    builder     google/gemini-3.6-flash (inherited)
+smidja/smidja_smidja_config/smidja.frontier.config.yaml
+    planner     anthropic/claude-opus-5
+```
+
+Read those from disk every time. Rosters are the engineer's to add, rename, and retune, so a name you remember from a doc is a guess.
+
+They will rarely say `--config`. Treat any of these as naming a roster, then resolve it to a file:
+
+| What they say | What it means |
+|---|---|
+| "run it on the frontier config", "use the frontier roster" | the roster file whose name matches |
+| "run this with the big models", "use the sota roster" | the non-default roster — confirm which if there is more than one. Each config's header comment lists the names it answers to, so `head -3` on the file settles it |
+| "have opus plan this one" | a roster whose planner is that model; if none exists, say so rather than editing the config mid-request |
+| nothing about models at all | the default, `smidja/smidja_smidja_config/smidja.config.yaml` |
+
+`--config` takes the path directly; the justfile recipes read `SMIDJA_CONFIG` instead:
+
+```bash
+uv run smidja/<chain>.py "<prompt>" --config smidja/smidja_smidja_config/smidja.frontier.config.yaml
+SMIDJA_CONFIG=smidja/smidja_smidja_config/smidja.frontier.config.yaml just <recipe> "<prompt>"
+```
+
+Two things that bite:
+
+- **Never swap rosters on your own.** A different roster is a different cost and a different result. If the default's model looks wrong for the work, say so and let the engineer choose.
+- **Switching rosters mid-session breaks resumption.** `agent_map.json` records the model each coding-agent session was created with, so a joined run (`--smidja-id`) whose config now names a different model starts that agent **fresh** instead of resuming its context window. That is deliberate — a bad resume is worse — but it means "plan on the frontier roster, then build on the default" costs the builder its accumulated context. Say so when you report it.
+
+`--smidja-id` is optional on **every** smidja. Given one, the run joins that session if it exists or creates it pinned to exactly that id: same `sessions/{smidja_id}/` dirs, same `context_handoff/`, envelopes appended, and each agent resumes its existing coding-agent context window via `agent_map.json`. That is how you chain smidja — plan under one id, then build under the same id.
+
+## Observe
+
+The trace db is `smidja/smidja_data/smidja.db`. It is WAL, so reads never block the running writers — poll it as often as you like.
+
+```bash
+# where the run stands
+sqlite3 smidja/smidja_data/smidja.db \
+  "select seq, name, kind, owner, status, attempt from phases where smidja_id='a1b2c3d4' order by seq;"
+
+# the live tail — cursor on rowid, same query the visualizer polls
+sqlite3 smidja/smidja_data/smidja.db \
+  "select rowid, type, name, started_at from events where smidja_id='a1b2c3d4' and rowid > 0 order by rowid limit 50;"
+
+# why a phase failed
+sqlite3 smidja/smidja_data/smidja.db \
+  "select attempt, gate, passed, checks_json from gate_results where smidja_id='a1b2c3d4';"
+
+# session-level status
+sqlite3 smidja/smidja_data/smidja.db \
+  "select smidja_id, request, status, total_tokens from sessions order by started_at desc limit 5;"
+
+# what an agent actually did, slowest tool calls first
+sqlite3 smidja/smidja_data/smidja.db \
+  "select name, tokens, started_at, ended_at from events
+   where smidja_id='a1b2c3d4' and type='tool_call' order by ended_at desc limit 20;"
+```
+
+Poll on a cursor: keep the highest `rowid` you have seen and query `where rowid > ?`. Don't re-read the whole table each pass.
+
+`tool_call` rows carry a real span, so durations come off the columns — see `references/observability.md` for which fields each event type populates.
+
+The smidja also narrates to stdout, and every line it prints is written to the db as a `log` event — terminal and swim lane tell the same story by construction, so tailing the background process is a valid second view rather than a competing source of truth.
+
+Files are the raw record if you need more than the db shows: `smidja/smidja_data/sessions/{smidja_id}/{agent}/raw_output.jsonl` (full coding-agent stream), `envelope.json` (the parsed final response), `prompts/` (exactly what was sent), and `context_handoff/` (what agents wrote for each other).
+
+## When a run is stuck
+
+A hung coding agent produces no events at all, so the trace goes quiet rather than red. Read it in this order:
+
+```bash
+just phases <smidja_id>     # which phase is still `running`
+just procs <smidja_id>      # what that phase is actually running, with pids
+just kill <smidja_id>       # stop it — children first, then the workflow
+```
+
+`processes` rows with `ended_at IS NULL` are the live ones. If `procs` shows a pi child but the phase has produced no `tool_call` events and its `raw_output.jsonl` is empty, the agent never got started properly — check the model resolves and that nothing is blocking the subprocess, rather than waiting it out. `just kill` verifies each pid still matches the command that was recorded before signalling, because pids get recycled.
+
+A killed run marks itself `fail` and closes its process rows, so the trace never claims work is in flight that is already dead.
+
+## Report
+
+Tell the engineer, in order: which chain and which roster you launched (name the config whenever it was not the default), which phase is running now (or which failed), phase statuses in sequence, and for a failure the gate violations or the error verbatim. Remember **every phase defaults to `fail`** — a phase showing `fail` may simply never have completed; `queued` means it never started. Don't dress up a partial run as a success.
+
+For a visual live view, the visualizer app in the skill (`just obs`, or tmux sessions viz-api :4600 + viz-ui :4601) polls this same db — sessions as cards, runs as swim lanes, phases and tool calls drill-in. The sqlite queries above remain the headless equivalent.

package/apps/smidja-factory/cookbooks/smidja_overview.md

@@ -0,0 +1,88 @@
+# smidja Overview
+
+The system map the orchestrator reads on startup — what smidja is, how a stamped repo is laid out, and which cookbook to load next.
+
+## What smidja is
+
+Smíðja builds repeatable **agents plus code** workflows. Deterministic Python (an smidja script) owns sequencing, retries, and acceptance; agents are bounded nodes inside that graph. Agent proposes, code disposes.
+
+Your job as orchestrator: **run the system, observe the system, help the engineer interact with it.** You do not do the work an smidja exists to do.
+
+## Layout of a stamped repo
+
+```
+smidja/
+├── smidja_smidja_config/
+│   └── smidja.config.yaml         the agent roster — one agent, one prompt, one purpose
+├── smidja_prompt.py                smallest smidja: one agent, one prompt, traced end-to-end
+├── smidja_plan.py, smidja_scout.py, smidja_build.py, smidja_plan_build.py, smidja_build_test.py, smidja_plan_build_test.py
+├── smidja_build_review.py          build → review: is this what was asked for? (not testing)
+├── smidja_document.py              write up the work just done, from git diff vs main
+├── smidja_simple_sdlc.py           plan → build → test → review → document; commits each product
+├── smidja_modules/                 ALL low-level logic — smidja scripts stay thin
+│   ├── data_types.py            AgentCall, PhaseParams, Phase, Envelope + one output type per agent call
+│   ├── agents.py                load_config, validate, resolve entry → interface + model + thinking
+│   ├── runner.py                the Run object: run.phase(PhaseParams) → ph.call(AgentCall)
+│   ├── agent_pi.py              Pi interface (v1)   ·   agent_cc.py  Claude Code (v2, stubbed)
+│   ├── gates.py                 gate(envelope, run) -> GateReport — one check per item verified
+│   ├── changes.py               git diff vs a resolved base → ChangeSet → envelope for the documenter
+│   ├── prompts.py, session.py, tracer.py, console.py, git_helper.py, utils.py
+└── smidja_data/
+    ├── prompt_engineering/{agent}/{system.md,user.md}   tracked — edit prompts HERE, never in the skill
+    │                                planner · builder · scout · reviewer · documenter
+    ├── sessions/{smidja_id}/                               gitignored runtime
+    │   ├── agent_map.json       agent → coding-agent session_id + model
+    │   ├── context_handoff/     the one place agents write files for the agents that follow
+    │   └── {agent}/{prompts/, raw_output.jsonl, envelope.json}
+    └── smidja.db                  gitignored SQLite trace db the visualizer polls
+```
+
+**v1 runs Pi only.** `coding_agent: pi`, default model `gemini-3.6-flash`, thinking `medium`. `claude_code` is specced in the config and stubbed in the interface — it lands in v2.
+
+## The phase model
+
+Every smidja run is a sequence of **phases**, each one `with run.phase(PhaseParams(...))`. Three kinds, three swim lanes:
+
+- **engineer** — the human lane; today the system-input phase (who asked, and for what).
+- **agent** — `ph.call(AgentCall(...))`: prompt in → typed envelope out → gates verified.
+- **code** — deterministic steps that stand alone (git branch, git commit, migrate). Never buried inside an agent phase.
+
+**Success must be earned — every phase defaults to `fail`.** A clean exit flips it to success; agent phases additionally require the envelope to parse and all gates to come back green. A raise keeps it failed, records an error event, and aborts the run. `retries=N` on an agent phase buys extra gate-correction rounds through the same session before that raise happens.
+
+## Envelopes
+
+Agents have exactly two output channels: reference files written into `context_handoff/`, and a **final valid-JSON response** parsed against the output type the call declared. Code persists it as `envelope.json` and injects it into the next agent's `user.md` via `{{previous_envelope}}`. Bad JSON is never a restart — the harness re-prompts the *same session, context intact*, until it parses (bounded). See `references/handoff.md`.
+
+**The output contract is a synced triad**: the type in `data_types.py` ↔ the `## Report` JSON example in the agent's `user.md` ↔ `output_type=` at the call site. Editing any one of the three means editing all three in the same change — drift between them taxes every call with correction retries.
+
+## Running an smidja
+
+```bash
+uv run smidja/smidja_plan.py "add a /health endpoint"
+uv run smidja/smidja_plan_build.py requests/health.md --smidja-id a1b2c3d4
+```
+
+The prompt is inline text or a file path. `--smidja-id` is optional on every smidja: given one, the run joins that session (same dirs, same `context_handoff/`, agents resume their existing context windows); omitted, a fresh id is minted and printed.
+
+## When you have finished reading this
+
+You are done with startup. List the smidja (`ls smidja/smidja_*.py`, plus each `Phases:` docstring line) as a table, and **wait for the engineer's request.**
+
+Do not survey anything else — not the trace db, not the config, not past runs, not the repo tree. You do not yet know what the request is, so anything you gather now is a guess about what will matter, spent from the context the real work needs. Every cookbook and reference below is lazy-loaded, one per request, and that is the whole design.
+
+## Where to go next
+
+Load one cookbook per request — this overview is the only one you read up front.
+
+| Request | Cookbook |
+|---|---|
+| Turn a request into the prompt an smidja gets | `how_to_prompt_for_the_eng.md` — **read before every launch** |
+| Set the system up in a repo | `install.md` |
+| Write a new smidja script | `create_adw.md` |
+| Change an existing smidja chain | `update_adw.md` |
+| Generate `smidja.config.yaml` | `create_config.md` |
+| Add or retune an agent | `update_config.md` |
+| Add low-level logic or a gate | `update_modules.md` |
+| Run and monitor a workflow | `how_to_prompt_for_the_eng.md`, then `run_adw.md` |
+
+References, loaded when you need the spec: `references/config.md` (full config schema), `references/handoff.md` (envelope + session layout), `references/observability.md` (events, db tables, polling).