@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/smidja-factory/skills/git-ops/sync_upstream.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# sync_upstream.sh — fetch, rebase, then land through the no-mistakes gate (git-ops).
+#
+# Pushing straight to origin skips the gate that reviews, tests, lints, documents
+# and opens the PR. This script pushes to the `no-mistakes` remote instead, so the
+# gate validates first and advances origin itself. When the gate is not installed
+# it falls back to a direct push and SAYS SO — a silent fallback here would mean
+# silently shipping unreviewed code.
+#
+# Usage:
+#   sync_upstream.sh [--check] [--direct] [--branch <name>]
+#     --check    fetch + report what landing would do; change nothing
+#     --direct   push straight to origin (bypasses the gate; reported)
+#
+# Exit: 0 landed, 1 blocked, 2 usage.
+set -u
+
+VERSION="1.0.0"
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { printf 'error: not a git repository\n' >&2; exit 1; }
+cd "$ROOT" || exit 1
+
+# no args means "land this branch"; only an explicit flag asks for help
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+CHECK=0; DIRECT=0; BRANCH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --check) CHECK=1; shift ;;
+    --direct) DIRECT=1; shift ;;
+    --branch) BRANCH=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\nhelp: sync_upstream.sh [--check|--direct|--branch <name>]\n' "$1" >&2; exit 2 ;;
+  esac
+done
+[ -n "$BRANCH" ] || BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+
+# a dirty tree cannot rebase safely, and rebasing over uncommitted work is how
+# changes get lost
+DIRTY=$(git status --porcelain | wc -l | tr -d ' ')
+if [ "$DIRTY" != 0 ]; then
+  printf 'sync[1]{branch,state,detail}:\n  "%s","blocked","%s uncommitted path(s) — commit them first (git-ops/safe_commit.sh)"\n' "$BRANCH" "$DIRTY"
+  exit 1
+fi
+
+git fetch -q origin 2>/dev/null || { printf 'sync[1]{state,detail}:\n  "blocked","could not fetch origin — check the network and gh auth"\n' >&2; exit 1; }
+DEFAULT="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+[ -n "$DEFAULT" ] || DEFAULT=main
+BEHIND=$(git rev-list --count "HEAD..origin/$DEFAULT" 2>/dev/null || echo 0)
+AHEAD=$(git rev-list --count "origin/$DEFAULT..HEAD" 2>/dev/null || echo 0)
+
+printf 'sync[1]{branch,base,behind,ahead}:\n  "%s","%s",%s,%s\n' "$BRANCH" "$DEFAULT" "$BEHIND" "$AHEAD"
+
+if [ "$CHECK" = 1 ]; then
+  printf 'plan[1]{step,detail}:\n'
+  [ "$BEHIND" -gt 0 ] && printf '  "rebase","onto origin/%s (%s behind)"\n' "$DEFAULT" "$BEHIND" || printf '  "rebase","already current"\n'
+  if git remote | grep -qx "no-mistakes" && [ "$DIRECT" = 0 ]; then
+    printf '  "land","push to the no-mistakes gate, then axi sync"
+'
+  else
+    printf '  "land","push directly to origin (gate not installed)"
+'
+  fi
+  exit 0
+fi
+
+# ── rebase onto the base ─────────────────────────────────────────────────────
+if [ "$BEHIND" -gt 0 ]; then
+  if ! git rebase -q "origin/$DEFAULT" 2>/dev/null; then
+    printf 'sync[1]{branch,state,detail}:\n  "%s","blocked","rebase conflict — resolve it, then re-run (git rebase --continue)"\n' "$BRANCH"
+    exit 1
+  fi
+  printf 'rebase[1]{onto,new_head}:\n  "origin/%s","%s"\n' "$DEFAULT" "$(git rev-parse --short HEAD)"
+fi
+
+# ── land ─────────────────────────────────────────────────────────────────────
+if git remote | grep -qx "no-mistakes" && [ "$DIRECT" = 0 ]; then
+  printf 'gate[1]{remote,detail}:\n  "no-mistakes","validating before origin — this is the clean-PR gate"\n'
+  if ! git push -q no-mistakes "$BRANCH" 2>/dev/null; then
+    printf 'sync[1]{branch,state,detail}:\n  "%s","blocked","the gate refused the push — run: no-mistakes axi status"\n' "$BRANCH"
+    exit 1
+  fi
+  if command -v no-mistakes >/dev/null 2>&1; then
+    printf 'axi[1]{action,detail}:\n  "sync","moving %s to the verified head"\n' "$BRANCH"
+    no-mistakes axi sync 2>&1 | tail -8
+  fi
+else
+  printf 'gate[1]{remote,detail}:\n  "origin","NO GATE — pushing unreviewed (no-mistakes remote absent or --direct)"\n'
+  git push -q origin "$BRANCH" 2>/dev/null || {
+    printf 'sync[1]{branch,state,detail}:\n  "%s","blocked","push to origin failed"\n' "$BRANCH"; exit 1; }
+fi
+printf 'landed[1]{branch,head}:\n  "%s","%s"\n' "$BRANCH" "$(git rev-parse --short HEAD)"
+exit 0

package/apps/smidja-factory/skills/how-to-run-agent-teams/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: how-to-run-agent-teams
+description: Run a FULL agent team with the smithy — Kaia (orchestrator) plus every role on the same model roster, chained through orchestrate. Use when the user wants to "send the team", "run everyone on <model>", "kaia should be that and everyone", or "make a workflow/chain to test a full team". Covers the nemotron-team mode (all agents + Kaia on Nemotron 3 Ultra Free via pi), the no-flash rule for Kaia, and project-anchoring with SMIDJA_PROJECT_DIR. Pairs with smidja-start / smidja-launcher (launch&watch) and smidja (internals).
+argument-hint: "[launch a team | nemotron-team | run everyone on a model | ...]"
+---
+
+# How to run agent teams (the smithy)
+
+A **team run** = a roster (which agents) × a chain (what they execute). The
+full-team play is **`orchestrate`**: Kaia is the `orchestrator` — she receives
+the WHOLE task first, dispatches sub-agents (scout → planner → builder →
+reviewer) via her `subagent_*` tools, tracks them, and reports every changed
+file. Do not pass the engineer's prompt straight to one builder; going through
+Kaia first is the point (she recalls project memory and plans the dispatch).
+
+This skill is the playbook for "send the team". For single-line launches and
+watching, load `smidja-launcher`; for picking teams/models `smidja-start`;
+for writing a crisp ask `smidja-instructions`; for the pipeline internals
+`smidja`. All smidja work is launched detached and observed — never implement
+in the team's place.
+
+## The one command
+
+```bash
+cd /home/<user>/CodeP/<project> && \
+SMIDJA_PROJECT_DIR=/home/<user>/CodeP/<project> \
+  $YMIR_ROOT/scripts/smidja run --mode nemotron-team <ask-path-or-string>
+```
+
+That runs the full 6-agent team (orchestrator/Kaia, planner, builder, scout,
+reviewer, documenter) — every one on **Nemotron 3 Ultra Free via pi**
+(`openrouter/nvidia/nemotron-3-ultra-550b-a55b:free`, 1M ctx), chained through
+`orchestrate`. Watch it with `smidja tail <smidja_id>` / `just ui`, audit with
+`smidja audit <smidja_id>`.
+
+## Rosters / modes relevant to a full team
+
+| Roster / mode | Agents | Surface | Chain | Use |
+|---|---|---|---|---|
+| `nemotron` | all 6 on Nemotron | opencode/ocrd | simple-sdlc | test roster, ocrd CLI |
+| `nemotron-pi` | all 6 on Nemotron | **pi** (`openrouter/…:free`) | simple-sdlc | same model via pi — thinking visible |
+| `nemotron-team` | all 6 on Nemotron | **pi** | **orchestrate** | THE full-team mode — Kaia dispatches everyone |
+| `cloud-reasoning` | cloud reasoning team | opencode | simple-sdlc | hard/long tasks |
+| `orchestrate` | orchestrator+reviewer | cloud-fast | orchestrate | Kaia dispatches (default roster) |
+
+`smidja modes` lists all 13 modes; `smidja rosters` resolves each stack and shows
+the surface per agent (a `✓ pi` column means it runs through the pi harness).
+
+## Golden rules (hard-won — breaking these caused real failures)
+
+1. **Kaia runs on the SAME model as the team — never flash.** Admission,
+   `smidja kaia`, and recovery default to `KAIA_CONFIG=smidja.cloud-fast`
+   (**deepseek-v4-flash**). A nemotron run MUST override it, or the admission
+   one-shot silently talks to flash while everyone else is on nemotron:
+   `nemotron*` modes now set `KAIA_CONFIG=smidja.nemotron-pi` automatically, so
+   only a stray `smidja kaia`/`smidja admit` elsewhere can drift — check with
+   `smidja kaia --memory` and the run's `kaia_notes.md`. The admission session id
+   is recorded in `session/kaia_admit.log` / `kaia_handoff.json`; verify its
+   `agent_map.json` model is nemotron, not `-flash`.
+
+2. **Anchor the run to the PROJECT repo with `SMIDJA_PROJECT_DIR`.** `smidja`
+   `cd`s to its own ROOT before launching, so cwd-based project detection
+   (git toplevel) fails — a wayoffactoy ask launched from anywhere lands in
+   `~/Ymir`'s data dir and agents work on the wrong repo. Always set
+   `SMIDJA_PROJECT_DIR=/home/<user>/CodeP/<project>` so sessions, the trace db,
+   and gates all live in the project (e.g. `…/wayoffactoy/smidja/smidja_data/`).
+   Confirm with the header of `session/*/raw_output.jsonl` — `"cwd"` must be
+   the project, and `kaia_handoff.json`'s `repo_root` must be the project.
+
+3. **The project repo must have the smidja's support dirs.** Modules import
+   from the smidja ROOT, but prompts/extensions resolve from the project cwd:
+   `smidja/smidja_data/prompt_engineering/` and `smidja/smidja_data/harness_engineering/`
+   must exist in the project. If missing, symlink them from `~/Ymir`:
+   `ln -s $YMIR_ROOT/smidja/smidja_data/{prompt_engineering,harness_engineering} smidja/smidja_data/`.
+
+4. **Thinking is only visible on the pi surface.** The opencode CLI
+   (`--format json`) does NOT stream reasoning/text parts into the NDJSON —
+   template streams show only step/tool events, so a phase reads "no thinking
+   text in the recorded stream". Nemotron via **pi** records
+   `content[].thinking` blocks (scan: `session/<agent>/pi_sessions/*.jsonl`).
+   For "see the team think", use `nemotron-pi` / `nemotron-team`, not `nemotron`.
+
+5. **Free-tier caveats.** Nemotron 3 Ultra Free via ocrd can 404 mid-run
+   (a fallback-on-fallback has no retry → phase fails). OpenRouter's
+   `…:550b-a55b:free` through pi is steadier and shows thinking. If a free run
+   dies, audit, don't relaunch blindly — it's usually the provider, not the ask.
+
+## How the team works (so you can report to the user)
+
+- `smidja/smidja_orchestrate.py` — chain: `request` (engineer) → `orchestrate`
+  (Kaia owns the whole task, MUST use `subagent_*` — gate
+  `orchestrator_dispatched`) → `review_N` (reviewer) → maybe `revise_N`
+  (Kaia closes findings), bounded by `MAX_REVISION_LOOPS`.
+- Every agent call streams events (tool_call, compact, thinking, model_error)
+  into the project's `smidja/smidja_data/smidja.db` (WAL — reads never block).
+- `smidja stop <smidja_id>` kills a misbehaving team (children first);
+  `scripts/smidja-emergency-stop.sh` is the persistent kill-switch.
+
+## Verify a team run landed correctly
+
+```bash
+smidja sessions | grep <smidja_id>            # status
+smidja phases <smidja_id>                     # per-phase status
+smidja tail <smidja_id>                       # live event tail
+python3 -c "import json;print([l for l in open('<proj>/smidja/smidja_data/sessions/<id>/agent_map.json')])"   # models pinned
+grep '"cwd"' <proj>/smidja/smidja_data/sessions/<id>/*/raw_output.jsonl        # right repo?
+cat <proj>/smidja/smidja_data/sessions/<id>/kaia_notes.md                      # Kaia admission notes
+```
+
+## Cross-references
+
+- Launch/watch/audit: `smidja-launcher` (`scripts/smidja`, `justfile`)
+- Picking teams/models + chain pick: `smidja-start` (`START_SMIDJA.md`)
+- Writing the ask file: `smidja-instructions`
+- Pipeline internals / smidja / configs: `smidja`
+- Roster/model definitions: `smidja/smidja_smidja_config/{roster,models}.yaml`
+- Nemotron fallback + surfaces: `START_SMIDJA.md` → "online models fallback"

package/apps/smidja-factory/skills/smidja-instructions/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: smidja-instructions
+description: "Turn a vague request into a great smidja instruction. Interview the user (ask questions), then write a request file the smithy can execute cleanly — with Where / Done means / Out of scope, and the right service/mode/chain. Use when the user asks to build/change/fix something and the ask is fuzzy, or when they want to 'send the smidja' / 'give it to the agents'. Write the ask, then hand it to smidja-start / smidja-launcher to launch."
+version: "1.0"
+allowed-tools: read, write, edit, bash, grep, glob
+---
+
+# Smíðja Instructions — ask first, then give the smidja something it can win
+
+## Sibling skills — load one if the task matches
+
+- **`smidja-start`** — how to actually launch the team you just picked
+  (rosters, local/online models, chains, orchestrator, detached-launch gotcha).
+- **`smidja-launcher`** — the one-command launcher (`scripts/smidja`): run, watch,
+  audit, stop, learn, missions.
+- **`smidja`** — smidja internals: cookbooks for install/create/update smidja and
+  roster config.
+- **`smidja`** — conventions when the work lands in `~/Ymir`.
+
+The smidja executes a request file (`requests/*.md`) through an smidja chain
+(builder, reviewer, orchestrator). A fuzzy ask produces a fuzzy run: agents
+guess, review rejects, and Kaia has to triage. This skill fixes the input end —
+**you interview the user, then write the instruction the smidja can execute
+without asking questions.**
+
+> The instruction file is what a builder with zero memory of this conversation
+> will follow. If you would not give it to a contractor you had never met, it is
+> not ready.
+
+## When to use
+
+- The user says: "build X", "add Y", "fix Z", "make the smidja do…",
+  "give this to the agents", "send the smidja".
+- The ask is a sentence or two — too thin for a builder.
+- The user is unsure themselves and benefits from being walked through it.
+
+## The workflow
+
+### 1. Interview — ask the user questions
+
+Do NOT start writing. Ask enough to fill these (most matter; skip only what the
+user genuinely has no answer for):
+
+| Question | Why it matters |
+|---|---|
+| **What exactly, in one sentence?** | The objective every agent and gate checks against. |
+| **Where does it live?** | Repo + paths. The request must say *which repo* and the exact files/dirs. |
+| **What does "done" look like?** | Verifiable: a build passes, a file exists with content X, a URL returns 200. Not vibes. |
+| **What must NOT change?** | Out of scope: other files, other services, other repos, existing tunnels/configs. |
+| **Any constraints?** | Stack, dependencies, no-new-deps, privacy, security, "don't touch prod". |
+| **How much autonomy?** | Recon only (scout), small build (sdlc), full plan→build→review→docs (simple-sdlc), orchestrator with sub-agents, review-only. Also: how deep should Kaia's presence be — **T0** (none, tiny/throwaway runs), **T1** (admission notes, default for real work), **T2** (Kaia orchestrates the whole run). |
+| **Which stack?** | Local (LM Studio/pi), cloud (opencode/ocrd), hybrid, free, or "you pick". This picks the service/roster. |
+
+Ask them as a short back-and-forth, not a wall. Stop when the request would be
+unambiguous to a stranger. One or two clarifying rounds is usually enough.
+
+### 2. Pick the chain + service
+
+Match the answer to the smidja surface (`smidja modes` / `smidja services`).
+Standing reference for the stack: `docs/software-smidja-run.md`
+(how to run) and `docs/SmidjaAgentsAndModels.md` (roster + model
+backends — the source of truth for which agents/models exist).
+
+**Key files (what they do):**
+- `smidja/smidja_smidja_config/roster.yaml` — **the ONE smidja config file**: teams
+  (named stacks: which agents + which model each runs + tools/writes;
+  `--roster <name>` / `SMIDJA_ROSTER=<name>` pick one), agent roles
+  (`role_defaults:`), and the model catalog (`tiers:` — role × backend tier;
+  swap surface for `--model`, `SMIDJA_*_MODEL`, `SMIDJA_MODEL_TIER`).
+- `justfile` — starter recipes from `~/Ymir`: `just scout/sdlc/simple-sdlc/orchestrate`
+  run chains; `just sessions/phases/tail` watch them. It resolves the same
+  `SMIDJA_CONFIG` / `SMIDJA_ROSTER` / `SMIDJA_MODEL_TIER` env vars.
+
+| Work | Chain | Service hint |
+|---|---|---|
+| Read-only recon, "where is X" | `scout` | `local` or `cloud` |
+| Small, well-understood change | `sdlc` | `local` (cheap) or `cloud` (reliable) |
+| Big / fuzzy / needs plan first | `simple-sdlc` | `cloud` or `local-planner` |
+| Review/audit an existing diff | `build-review` | `review` |
+| Multi-agent coordination | `orchestrate` | `orchestrate` |
+| Bench a model | `mission T1\|T2` | the roster under test |
+
+When the user has no preference, default to **`local`** (LM Studio, no keys;
+planner 35B / builder 9B / reviewer 12B) for cheap/air-gapped work and
+**`cloud`** (deepseek-v4-flash via `ocrd`) when reliability beats cost. Check
+`smidja modes` / `smidja services` for the exact presets — they are the current
+source of truth. Note the choice in the request so the run is reproducible.
+
+> **Before you launch: read the gotchas** in `smidja-start` (§7) and the
+> evidence in `tests/local-models/RESULTS.md` — mostly: launch long runs
+> detached (never through a short tool-call timeout), small local models may
+> skip strict JSON reports, and reviewers must stay read-only.
+
+### 3. Write the request file
+
+Save to `requests/<slug>.md`. Structure:
+
+```markdown
+# <Title> — what, in one line
+
+<1–3 sentence objective. The builder's contract.>
+
+## What to build
+1. <concrete, ordered steps; each verifiable>
+2. …
+
+## Where
+- Repo: <path>
+- Files/dirs it may touch: <exact paths>
+
+## Done means
+- <a check that can pass or fail, e.g. `npm run build` exits 0>
+- <a file exists with expected content>
+
+## Out of scope
+- <what must NOT change — other repos, services, tunnels, prod, secrets>
+```
+
+Rules that make smidja requests work (learned from real runs):
+
+1. **Every step is verifiable** — "write `repo-map.py`", not "make a tool".
+2. **Done means is mechanical** — exit codes, file existence, HTTP status.
+3. **Out of scope is explicit** — the builder's `writes` are wide; only the
+   request constrains it.
+4. **Name the repo absolutely** — the smidja runs from `~/Ymir`; a request
+   for `~/CodeP/courses` must say so.
+5. **Never put secrets in the request** — keys live in `.env`.
+6. **One objective** — a request that tries to do three things makes three
+   half-jobs. Split into separate requests if needed.
+
+### 4. Launch it (or hand it over)
+
+```bash
+smidja run --service cloud "requests/<slug>.md"          # or the chain/service chosen
+smidja run --mode local-planner "requests/<slug>.md" --kaia T2   # + Kaia orchestrates
+# or, for a whole-stack pick:
+smidja run --service <name> "requests/<slug>.md"
+```
+
+Default Kaia tier is **T1** (admission notes injected into every agent call —
+no run is blocked). Use `--kaia T0` for throwaway/recon runs, `--kaia T2` when
+the request is big enough that Kaia should orchestrate.
+
+If the user wanted *you* to drive, load the **`smidja-start`** skill for
+how to launch (detached tmux for long runs), watch (`smidja sessions` /
+`just sessions`), and report the `smidja_id` + first phase. If they want to launch
+themselves, tell them the exact command.
+
+## What good looks like
+
+The `requests/` files that produced clean smidja runs:
+
+- `courses-astro-site.md` — full site, absolute repo, done-means + out-of-scope.
+- `linuxcommand-tunnel.md` — infra task, ordered steps with the exact commands,
+  "Done means: curl returns 200", "Out of scope: do NOT touch other tunnels".
+
+Both were run start-to-finish by the smidja with no back-and-forth — that is
+the bar. **If you would not hand the file to a contractor you never met, keep
+asking.**
+
+## Golden rules
+
+1. **Ask before you write.** The interview is the product.
+2. **The objective is one sentence.** Everything else hangs off it.
+3. **Verifiable beats descriptive.** "exits 0" > "works correctly".
+4. **Never assume the repo or paths** — ask or state them.
+5. **Never commit secrets in a request** — they live in `~/Ymir/.env`.
+6. **Note the service/chain** so the run is reproducible by anyone.

package/apps/smidja-factory/skills/smidja-launcher/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: smidja-launcher
+description: Start and use the smithy from one command — converge the environment, run any chain or mode, watch, audit, stop, talk to Kaia, run bench missions. Use when the user wants to run the smidja, scout/sdlc/simple-sdlc/orchestrate work, audit a run, stop a misbehaving agent, check Kaia's memory, or bench local/cloud models. Pair with smidja-start (how to pick teams/models) and smidja-instructions (how to write the ask).
+allowed-tools: read, write, edit, bash, grep, glob
+---
+
+# smidja-launcher — the one command for the smidja
+
+`scripts/smidja` is the single entry point for any agent (opencode, claude, pi,
+herdr, human) to start, watch, audit, and mission the smithy (Smíðja). You never
+do smidja work yourself — you launch and observe.
+
+## Sibling skills — load one if the task matches
+
+- **`smidja-start`** — exactly how to start agents for work: which team
+  (roster), local/online/hybrid models, chains, orchestrator, **gotchas**
+  (incl. detached-launch rule below).
+- **`smidja-instructions`** — turn a fuzzy ask into a request file first.
+- **`smidja`** — internals: cookbooks for install/create/update smidja + configs.
+- **`smidja`** — conventions when working inside `~/Ymir`.
+
+Deep-reference docs for the smidja live in **`docs/`**:
+`software-smidja.md` (overview), `software-smidja-run.md` (how to run),
+`software-smidja-pi.md` / `software-smidja-opencode.md` (coding-agent
+setups), `software-smidja-visualizer.md` (the trace UI this launcher starts),
+`SmidjaAgentsAndModels.md` (roster + model backends source of truth).
+
+## The command
+
+```bash
+scripts/smidja up                         # converge env (LM Studio + visualizer + tunnel)
+scripts/smidja run <chain> "<ask>"        # prompt|scout|plan|plan-build|build-review|orchestrate|sdlc|simple-sdlc
+scripts/smidja run --mode <name> "<ask>"  # mode = roster + chain preset
+scripts/smidja run --service <name> "<ask>" # one pick = provider × agent × chain
+scripts/smidja services                    # list the 9 whole-stack presets
+scripts/smidja sessions [N]               # last N runs
+scripts/smidja phases <smidja_id>
+scripts/smidja tail <smidja_id>
+scripts/smidja procs <smidja_id>
+scripts/smidja stop <smidja_id>              # kill children-first (misbehaving agents)
+scripts/smidja pause <smidja_id>             # hold a run (SIGSTOP agents) so you can steer
+scripts/smidja resume <smidja_id>            # continue a paused run
+scripts/smidja steer <smidja_id> "msg"       # inject engineer guidance into a running session
+scripts/smidja admit <smidja_id>            # refresh handoff + re-ask Kaia for admission notes
+scripts/smidja recover <smidja_id>          # watchdog ticket → Kaia's ONE recovery decision (prints apply cmd)
+scripts/smidja watch                     # watchdog loop in tmux (auto-started by smidja up)
+scripts/smidja emergency-stop            # circuit breaker: kill-switch + kill-9 a runaway smidja
+scripts/smidja audit <smidja_id>             # gates + tool-call evidence per agent
+scripts/smidja diagnose <smidja_id>          # WHY it failed + the fix to apply (self-improving)
+scripts/smidja learn <smidja_id>             # write the audit+diagnosis into Kaia's memory
+scripts/smidja kaia "<msg>"               # talk to Kaia (traced, memory-backed)
+scripts/smidja memory <project>           # what Kaia has learned for a project
+scripts/smidja mission <T1|T2> [--config <roster>]   # bench a model, then audit+learn
+scripts/smidja modes                      # list the 12 execution modes
+scripts/smidja rosters                    # list + validate rosters/models
+scripts/smidja team list|new|show|smoke  # make a team (stacks: block in roster.yaml)
+scripts/smidja model set|pin             # change a model (stack override or shared tier)
+scripts/smidja doctor [--stack <name>]   # spawn-readiness check — must be green
+```
+
+Run from the repo root (`~/Ymir/`). Everything is idempotent; reads never
+block a running run (WAL db).
+
+The files that define what this launcher runs:
+
+- `smidja/smidja_smidja_config/roster.yaml` — the ONE file: teams (named stacks of
+  agents with their models/tools/writes; `--roster <name>` / `SMIDJA_ROSTER=<name>`
+  pick one), agent roles (`role_defaults:`), and the model catalog (`tiers:` —
+  every role × backend tier: local · local-agile · local-max · local-ui · cloud ·
+  cloud-free · cloud-reasoning · hybrid-plan-local · hybrid-build-local · review).
+  Swap surface: `--model`, `SMIDJA_<ROLE>_MODEL`, `SMIDJA_MODEL_TIER`.
+- **Nemotron 3 Ultra Free is the always-available primary fallback** — `nemotron`
+  and `nemotron-pi` rosters/modes (plus `nemotron-team`: the full team on
+  Nemotron via **pi** with Kaia orchestrating), and an automatic one-retry
+  fallback whenever an agent's model fails to resolve or produces no output
+  (surface-aware: `SMIDJA_FALLBACK_MODEL_PI` / `SMIDJA_FALLBACK_MODEL_OPENCODE`).
+  Missions default to the `nemotron` roster (`SMIDJA_MISSION_CONFIG` to bench a
+  different team).
+- `justfile` — the `just` recipes (same engine): `just scout/sdlc/simple-sdlc/`
+  `orchestrate` to launch chains, `just sessions/phases/tail` to watch; it
+  honors the same `SMIDJA_CONFIG` / `SMIDJA_ROSTER` / `SMIDJA_MODEL_TIER` order.
+
+## Rules
+
+1. **Converge first.** `smidja run` runs `smidja up` first — it reloads a
+   not-loaded LM Studio model with a tiny completion, so a run never starts on
+   a half-warm environment. If `up` refuses, fix the warnings, don't run anyway.
+2. **Never do the work yourself.** Launch the chain and watch it. The smidja's
+   agents own the implementation; you own launching, observing, and reporting.
+3. **Stop, don't wait.** An agent that misbehaves or a run that hangs is a
+   `smidja stop <smidja_id>` (or the UI Stop button). Children die first, the trace
+   finalizes as `fail`.
+4. **Audit before believing.** `smidja audit` shows tool-call evidence per agent.
+   Zero tool calls on a claimed build = hallucinated completion. When a run
+   fails, `smidja diagnose <smidja_id>` tells you WHY and the exact fix to apply
+   (stronger model, prompt hardening, redundant commit, stopped run). Then
+   `smidja learn` writes that outcome + diagnosis into Kaia's engram memory so
+   she recalls it and picks better next time — the self-improving loop.
+5. **Launch detached for anything that may outlive a tool-call timeout.** A
+   35B planner needs minutes per phase. Launching `smidja run` through a short
+   tool-call timeout SIGKILLs the subagents mid-generation (LM Studio:
+   "Client disconnected") and the run finalizes `fail` with **no** error events
+   — audit of `sdlc-4027` / `sdlc-4271` (2026-08-31). For long runs:
+   ```bash
+   tmux new-session -d -s ssf \
+     "SMIDJA_PROJECT_DIR=<target-repo> $YMIR_ROOT/scripts/smidja run sdlc '<ask>'"
+   # then watch with read-only calls:  smidja sessions / smidja tail <id>
+   ```
+6. **Cloud models are three.** deepseek-v4-flash (workhorse), big-pickle,
+   nemotron-3-ultra-free — under the `ocrd` opencode profile. Local models
+   (LM Studio, `lmstudio/*`) need no keys; local-model reliability evidence
+   lives in `tests/local-models/RESULTS.md` (JSON-discipline and read-only
+   reviewer gotchas).
+7. **Runaway? Emergency-stop, not stop.** A recursive/admission loop or
+   dozens of procs is a `scripts/smidja emergency-stop` (writes a
+   `.smidja-emergency` kill-switch — blocks auto-admission — kills every
+   smidja pattern, marks in-flight runs `aborted`). Resume after fixing:
+   `scripts/smidja up` clears the kill-switch. Infra (LM Studio / ogb / viz) is
+   never touched.
+
+## Modes (roster + chain presets)
+
+`recon` · `local-fast` · `local-planner` · `local-max` · `cloud-free` ·
+`cloud-fast` · `cloud-reasoning` · `hybrid-plan-local` · `hybrid-build-local` ·
+`review-gate` · `orchestrate` (Kaia dispatches sub-agents).
+
+Pick the mode that fits the work kind; `smidja run --mode <name> "<ask>"` sets
+roster + chain for you. `--model <provider/model>` overrides the model for one
+run; the `tiers:` catalog in `smidja/smidja_smidja_config/roster.yaml` is the standing
+swap surface.
+
+## Services (whole-stack presets)
+
+`smidja run --service <name> "<ask>"` picks **everything at once** — the provider
+every model runs on, the coding agent (pi | opencode), and the smidja chain:
+
+`local` · `local-planner` · `cloud` · `cloud-free` · `cloud-reasoning` ·
+`hybrid-plan-local` · `hybrid-build-local` · `review` · `orchestrate`.
+
+Any part can be overridden with `--config` / `--chain` / `--model` /
+`--profile`. `smidja services` lists all nine with their roster/chain/model.
+
+## Observing
+
+- `smidja sessions` → recent runs. `smidja phases <id>` → phase statuses.
+- Visualizer: `smidja ui` (tmux) → `http://localhost:4601` (sessions + `#/memory`
+  for Kaia's engram UI), API on `:4600`.
+
+## Learn / memory
+
+- `smidja learn <smidja_id>` — the launcher writes objective audit fields
+  (outcome, gates, tool calls) into `smidja/smidja_data/kaia.engram`.
+- `smidja memory <project>` — hybrid-recall what worked for that project.
+- Kaia reads this before dispatching, so she biases toward what passed there
+  before instead of starting cold.