diff --git a/.agents/skills/boxel-development/references/dev-fitted-formats.md b/.agents/skills/boxel-development/references/dev-fitted-formats.md
index bc30ff5f4f4..7eeeeb89be8 100644
--- a/.agents/skills/boxel-development/references/dev-fitted-formats.md
+++ b/.agents/skills/boxel-development/references/dev-fitted-formats.md
@@ -1,42 +1,152 @@
-## Fitted Format Essentials
+# Fitted Format — Container-Query Standard
 
-**Four sub-formats strategy:**
+Distilled from the boxel-workspaces `container-query-fitted-layout.md`
+standard (the full 1000-line guide with worked examples). Everything here
+is CSS-only — no JS modifiers, no ResizeObserver.
 
-- **Badge** (≤150px width, <170px height) - Exportable graphics
-- **Strip** (>150px width, <170px height) - Dropdown/chooser panels
-- **Tile** (<400px width, ≥170px height) - Grid viewing
-- **Card** (≥400px width, ≥170px height) - Full layout
+## The contract: the parent owns the cell size
 
-**Container query skeleton:**
+A fitted card never imposes its own size. The host wraps every fitted
+template in `.field-component-card.fitted-format` with
+`width: 100%; height: 100%; overflow: hidden; container-type: size;
+container-name: fitted-card`.
+
+**Query the host's `fitted-card` container. NEVER create your own
+container on the root.** (An older version of this reference prescribed a
+local `container-type: size` wrapper — that is WRONG and superseded: a
+container cannot be styled by its own queries, so grid-template/padding
+switches on your root silently stop working.)
+
+The template root is a single `.fit` grid that fills the host wrapper:
 
 ```css
-.fitted-container {
-  container-type: size;
-  width: 100%;
+.fit {
+  width: 100%; /* the ONE sanctioned sizing declaration on the root */
   height: 100%;
+  display: grid;
 }
-
-/* Hide all by default */
-.badge,
-.strip,
-.tile,
-.card {
-  display: none;
-  padding: clamp(0.25rem, 2%, 0.5rem);
+@container fitted-card (max-height: 80px) {
+  .fit {
+    grid-template-rows: auto;
+  } /* queries against the HOST container style your root fine */
 }
+```
+
+Keep OFF the root: fixed/min/max dimensions, `border`, `border-radius`,
+`box-shadow`, `container-type`, `container-name` — the host owns all of
+them. Background/foreground pairing from the theme is fine
+(`background-color: var(--card); color: var(--card-foreground)`).
+
+## Prefer `<FittedCard>` for standard compositions
+
+For the standard composition — image/placeholder + eyebrow + title +
+subtitle + meta + footer + badges — use the `FittedCard` component from
+`@cardstack/boxel-ui/components` instead of hand-rolling. It implements
+this whole standard internally (host-container queries, aspect-ratio
+layout switching) and exposes `--fc-*` custom properties for tuning:
+
+```gts
+import { FittedCard } from '@cardstack/boxel-ui/components';
+
+<FittedCard @imageUrl={{@model.imageUrl}} @imageAlt={{@model.title}}>
+  <:placeholder><BookOpen width='24' height='24' /></:placeholder>
+  <:eyebrow>Non-fiction</:eyebrow>
+  <:title><@fields.cardTitle /></:title>
+  <:subtitle><@fields.cardDescription /></:subtitle>
+  <:meta><span>150 mins</span></:meta>
+  <:footer><span>320 pages</span><span>2024</span></:footer>
+</FittedCard>
+```
+
+No-media card types: omit `@imageUrl`, `:image`, AND `:placeholder` — the
+image column disappears and content switches to its no-image layout.
+Tune with `--fc-*` variables and `@container fitted-card (...)` overrides
+from your scoped CSS; don't fork the layout.
+
+**Hand-roll only special templates** (a dark terminal ticker, a ticket
+stub, a boarding pass with an SVG flight path) — then follow the rest of
+this reference.
+
+## Size classification — plan content per quantum BEFORE writing CSS
+
+Height quanta (what the host uses each size for):
+
+| Quantum | Range     | Visible regions                    | Host usage              |
+| ------- | --------- | ---------------------------------- | ----------------------- |
+| h40     | ≤50px     | head only                          | badges, inline mentions |
+| h65     | 50–80px   | head + meta                        | chooser dropdowns       |
+| h105    | 80–130px  | head + body + meta                 | strips, search results  |
+| h170    | 130–200px | head + body + [tags] + meta        | tiles                   |
+| h275    | 200–320px | hero + head + body + [tags] + meta | large tiles, cards      |
+| h445    | >320px    | all, spacious                      | expanded cards          |
 
-/* Activate by size - NO GAPS! */
-@container (max-width: 150px) and (max-height: 169px) {
-  .badge {
-    display: flex;
+Width classes:
+
+| Class  | Range     | Behavior                                                       |
+| ------ | --------- | -------------------------------------------------------------- |
+| narrow | ≤170px    | hide tags, clamp meta to 1 line, hide subhead at small heights |
+| medium | 170–260px | hide tags, clamp meta to 1 line                                |
+| wide   | >260px    | show tags; horizontal thumbnails at h40/h65/h105               |
+
+Tags hide below 260px because wrapping pills consume unpredictable
+height. Write the **content matrix first** — for each quantum, decide
+which fields appear — then implement it as `@container fitted-card`
+rules. A fitted view that only looks right at one size is a defect.
+
+```css
+@container fitted-card (max-height: 50px) {
+  /* h40: head only */
+}
+@container fitted-card (min-height: 50.1px) and (max-height: 80px) {
+  /* h65 */
+}
+@container fitted-card (min-height: 80.1px) and (max-height: 130px) {
+  /* h105 */
+}
+@container fitted-card (min-height: 130.1px) and (max-height: 200px) {
+  /* h170 */
+}
+@container fitted-card (min-height: 200.1px) {
+  /* h275+: hero appears */
+}
+@container fitted-card (max-width: 260px) {
+  .r-tags {
+    display: none;
   }
 }
 ```
 
-**Content priority:**
+## Overflow discipline (every region, no exceptions)
+
+- Body/content rows: `minmax(0, 1fr)` — never `auto` (auto rows grow
+  with content and blow the cell).
+- `overflow: hidden` on every region.
+- Text clamps: `display: -webkit-box; -webkit-box-orient: vertical;
+-webkit-line-clamp: N; overflow: hidden`.
+- `min-height: 0` on any nested flex/grid child that must shrink.
+
+## Container-query units caveat
+
+`cqw`/`cqh`/`cqmin` only resolve against an actual container. Inside a
+fitted template they resolve against the host's `fitted-card` container —
+fine. On other surfaces (isolated/embedded) they silently fall back to
+the VIEWPORT unless you establish a container on that surface with
+`container-type: inline-size` first.
+
+## Parent-side note
+
+When a parent embeds fitted children (`<@fields.x @format='fitted' />`),
+the parent sizes the cell (e.g. a grid of `160px × 180px` tiles) and may
+need `@displayContainer={{false}}` to suppress double chrome — see
+`dev-delegated-rendering.md`.
+
+## Media fields (cardinal rule, applies to ALL formats)
 
-1. Title/Name
-2. Image
-3. Short ID
-4. Key info
-5. Status badges
+An image on a card is `@field image = linksTo(() => ImageDef)` (or
+FileDef) pointing at a real realm file — write the binary into the
+workspace and reference it. NEVER design a field that stores
+`data:`/base64/blob strings in JSON attributes, not even "just a
+placeholder" — inline media bytes in instance JSON are a hard rule
+violation that corrupts diffs, bloats the index, and breaks the file's
+identity. No-media-yet instances leave the link empty and the template
+renders a placeholder block/icon.
diff --git a/.agents/skills/boxel-workspace-cardinal-rules/SKILL.md b/.agents/skills/boxel-workspace-cardinal-rules/SKILL.md
new file mode 100644
index 00000000000..e1d1ed175d0
--- /dev/null
+++ b/.agents/skills/boxel-workspace-cardinal-rules/SKILL.md
@@ -0,0 +1,96 @@
+# Boxel cardinal rules — silent-failure traps
+
+Rules discovered the hard way in a downstream Boxel workspace: each one passes lint and
+often passes indexing too, then breaks silently — corrupting the realm's index,
+crashing at render, or dropping data with no error. Check every card/field you write
+against this list before finishing an issue.
+
+## 1. DateField vs DateTimeField value format
+
+`DateField` values are `YYYY-MM-DD` (no `T`). `DateTimeField` values are full ISO
+datetimes (`2026-07-16T14:30:00.000Z`, with `T`). Putting a datetime string in a
+`DateField` (or vice versa) passes lint and indexes fine, then **crashes at render**
+with `RangeError: Invalid time value` when a user actually opens the card. Naming
+convention to follow when picking the field type: a `*At` suffix (`createdAt`,
+`publishedAt`) means `DateTimeField`; a `*Date`/`*On` suffix or bare `dob` means
+`DateField`.
+
+## 2. Never put an external URL in `relationships.<field>.links.self`
+
+If a `linksTo`/`linksToMany` field's JSON `links.self` points at a URL the indexer
+can't parse as a card (an external website, an image CDN URL, anything not a card
+resource), **the failed parse poisons the JSONB write and rolls back the WHOLE
+REALM's indexing transaction** — every other file in the same push silently fails to
+index too, with no error pointing at the actual bad file. For an external image/URL,
+use the pair pattern instead: `linksTo(ImageDef)` (or a similar file/media field) +
+`contains(UrlField)` as two separate fields, never one relationship pointing straight
+at an external URL.
+
+## 3. `linksToMany` JSON uses indexed top-level keys, never an array
+
+Correct:
+
+```json
+"relationships": {
+  "items.0": { "links": { "self": "../foo" } },
+  "items.1": { "links": { "self": "../bar" } }
+}
+```
+
+Wrong (rejected outright — "instance ... is not a card resource document"):
+
+```json
+"relationships": {
+  "items": { "links": { "self": ["../foo", "../bar"] } }
+}
+```
+
+## 4. Never inline media or binary bytes in card JSON
+
+No `data:` URIs, `blob:` URIs, base64, or raw media bytes in any JSON string field or
+attribute. Store media as a realm file linked via `linksTo(FileDef)` (or a FileDef
+subtype: `ImageDef`, `CsvFileDef`, etc.) instead — never embed the bytes directly in
+the instance JSON.
+
+## 5. Every query needs a realm scope, and don't start it before the realm is known
+
+A card-owned query with a missing or empty `realm` argument silently falls back to
+searching **every realm the server can see**, not just the current one. Always scope
+queries to the current card's own realm, and don't kick off the query before that
+realm URL is actually resolved. Cap general-purpose result sets (~100) rather than
+pulling unbounded result sets.
+
+## 6. Query-filter shape: `type` selects instances, `on` only scopes predicates
+
+To select every instance of a type, filter on `{ type: <ref> }` directly — never wrap
+it in `{ on: <ref> }` alone (`on` only scopes _other_ predicates like `eq`/`contains`;
+a bare `{ on: ref }` with nothing else matches nothing). Build refs with a `codeRef()`
+helper, not a manually-constructed object.
+
+## 7. Don't push more than ~30 files through one atomic batch to a fresh realm
+
+Large atomic pushes (30+ files via a single bulk-write endpoint) can report success
+while silently dropping some files' indexing jobs. For bulk kit/asset installs, push
+in smaller batches and verify each batch's expected file count actually shows up in a
+realm search before pushing the next batch.
+
+## 8. NEVER curl / HTTP-GET a `https://cardstack.com/base/*` module URL to inspect a base card
+
+Base card module URLs (`https://cardstack.com/base/theme`, `.../base/card-api`,
+`.../base/cards/structured-theme`, etc.) are **loader-resolved module references, not
+fetchable HTTP resources.** `cardstack.com` is a marketing site — a direct GET or a
+realm op (`_mtimes`, `boxel file read`) against `cardstack.com/base/...` returns a
+generic Webflow **404 HTML page** (`data-wf-domain=... %%PUBLISH_URL_REPLACEMENT%%`),
+NOT the card. Do not keep retrying it — that page will never become the schema. To
+learn a base card's fields/shape, use the **`get_card_schema` tool** (it resolves
+through the realm server), or read an existing instance of that card already in the
+target realm. Same rule for any published `*.boxel.site` / `*.boxel.build` URL: those
+are Webflow-published sites, not realms — never point realm operations at them.
+
+Also: many base cards are **default exports**, so the schema ref is `name: "default"`,
+NOT the class name. The base **Theme** card is the default export of
+`https://cardstack.com/base/theme` (the module is `export default Theme`) — query it as
+module `https://cardstack.com/base/theme`, name `default` (querying `#Theme` fails).
+`StructuredTheme` is likewise the default export of `base/structured-theme`. When a
+`get_card_schema` call fails with "named export is a CardDef", retry with `name:
+"default"` before assuming the card is unreachable — do NOT fall back to curling the URL.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/SKILL.md b/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/SKILL.md
new file mode 100644
index 00000000000..659a6a7fb01
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: boxel-delegated-render-control
+description: Controlling child-card renders from the parent — fitted vs embedded format choice, the host-injected CardContainer chrome, and the plural-field/atom/stagger/divider traps. Use when embedding cards via <@fields.X @format='...' /> or when an embedded/fitted child looks wrong (empty boxes, collapsed grids, double borders, invisible atoms).
+---
+
+# Delegated Render Control
+
+When a parent card renders a child via `<@fields.X @format='...' />`, the
+host wraps the child in a `CardContainer` with chrome you didn't write
+(rounded corners, 1px halo, light background, `overflow: hidden`). Two
+decisions dominate the outcome: **which format** you pick, and **who owns
+the chrome**. The full mechanics — exact injected DOM/CSS, override layers,
+recipes, and the child-side contract — live in
+`references/delegated-render-control.md`.
+
+## Format choice = who owns the cell size (decide BEFORE styling)
+
+| Format     | Who controls the box size?                                                                      | Use when                                                                                               |
+| ---------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `embedded` | **The child.** Width fluid, height = the card's natural content.                                | Vertical lists, feeds, roster rows, variable-height items.                                             |
+| `fitted`   | **The parent.** Child fills the box you give it (`width/height: 100%`, `container-type: size`). | Uniform tile grids (calendar cells, portraits, badge strips) where you deliberately set the cell size. |
+
+**The single most common rendering bug:** picking `fitted` for a list of
+variable-height cards — short content leaves a big empty box below each row.
+The fix is the format choice, upstream of any CSS. Decision rule: _did you
+set the cell size?_ Yes → `fitted` (+ `min-height`/`aspect-ratio` on the
+cell). No → `embedded`.
+
+## Who owns the chrome — three override layers (pick the lowest that works)
+
+1. **Theme cascade** — if the linked card has `cardInfo.theme`, the theme's
+   `--background`, `--foreground`, `--border`, `--radius` flow into the
+   wrapper. Cleanest, but only when the child instance actually has a theme.
+2. **`:deep()` from the parent's `<style scoped>`** — the workhorse.
+   Target `:deep(.boxel-card-container)` for radius/background,
+   `:deep(.boxel-card-container--boundaries)` for the 1px halo.
+3. **`@displayContainer={{false}}`** — kills the chrome entirely
+   (`display: contents`); pair with a parent-owned wrapper element.
+
+## The high-frequency traps
+
+1. **Plural-field wrapper.** Rendering a plural field with one tag
+   (`<@fields.items @format='fitted' />`) inserts wrapper divs between your
+   grid and the cards — the grid sees ONE child and collapses to a single
+   column. Fix: `:deep(> .plural-field) { display: contents; }` plus
+   `:deep(.linksToMany-itemContainer), :deep(.containsMany-item) { display:
+contents; }`. Targeting only `.containsMany-field` is the most common
+   bug — `linksToMany` ships `.linksToMany-field`, which never matches.
+2. **Atoms on dark backgrounds disappear.** The atom chip's own near-white
+   background + halo win over your `color: inherit`. Fix: either
+   `@displayContainer={{false}}` (plain inline text), or keep the chip and
+   recolor via `:deep(.field-component-card.atom-format) { background:
+transparent; box-shadow: none; color: var(--accent); }`.
+3. **Stagger through `display: contents`.** `:nth-child` on the cards
+   themselves always resolves to 1 (each is the only child of its wrapper).
+   Set `--stagger-d` on `:deep(.linksToMany-itemContainer:nth-child(N))` /
+   `:deep(.containsMany-item:nth-child(N))` and read
+   `animation-delay: var(--stagger-d)` on `.field-component-card` — custom
+   properties inherit through `display: contents`.
+4. **Divider strategy — parent draws OR child halo, never both.** Either
+   the parent draws dividers and kills the child halo
+   (`:deep(.boxel-card-container--boundaries) { box-shadow: none; }`), or
+   the halo IS the boundary and the parent adds no borders. Leaving both
+   yields the "drop shadow fighting a thin border" double-rule. When
+   switching strategies, DELETE the stale rule — same-selector CSS resolves
+   by source order.
+
+## Don't override
+
+`width/height: 100%` on `.fitted-format`, or `container-type` /
+`container-name` on embedded/fitted — the child's container queries depend
+on them. Style chrome (radius, background, border, shadow, padding), not
+layout primitives.
+
+## The child-side contract
+
+The child draws ONLY inside the box; host or parent draws the box. No
+`border-radius`, `border`, `box-shadow`, `overflow`, or size properties on
+any format's outermost element — see the reference for the per-format table
+and self-check.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/references/delegated-render-control.md b/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/references/delegated-render-control.md
new file mode 100644
index 00000000000..11da6e9e382
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-delegated-render-control/references/delegated-render-control.md
@@ -0,0 +1,850 @@
+# Delegated Render Control — Styling `<@fields.X />` From the Parent
+
+When a parent card renders a linked or compound field via
+`<@fields.X @format='...' />`, the host wraps the child render in chrome you
+didn't write. Default chrome looks like "shadcn neutral card": rounded
+corners, soft border, white-ish background, `overflow: hidden`, padding for
+atoms. If your parent's design language disagrees (an editorial design wants
+`--radius: 0` and sharp corners), the chrome fights it.
+
+This file documents EXACTLY what the host injects and EXACTLY how the parent
+overrides it. Source: `packages/base/field-component.gts` +
+`packages/boxel-ui/addon/src/components/card-container/index.gts` in the
+Boxel monorepo.
+
+**Related but distinct concern — Host-mode click-through.** When you render
+a result list via `@context.searchResultsComponent` inside an app card that
+publishes to Host mode, the rendered tiles need an explicit anchor overlay
+to be clickable. The in-app `@context.cardComponentModifier` machinery only
+fires in Interact / Code mode. See the `boxel-live-surfaces` skill →
+"Host-mode click-through" for the overlay pattern.
+
+**Also distinct — content matrix per format.** What FIELDS render in fitted
+vs embedded vs atom is a planning decision (the per-format content matrix),
+not a styling decision. If a fitted child renders data-empty, the parent's
+`:deep()` won't fix it — the child's `static fitted` template needs to
+consult its CardDef's content matrix.
+
+## Interaction ownership — live embed or stack navigation
+
+Decide whether the child is a live task surface or a read-only preview
+before adding click-through.
+
+- Live child (form, wizard, or controls): render it embedded and leave
+  pointer and keyboard interaction untouched. Put a small explicit
+  `Open ↗` control in parent-owned chrome when full-card inspection is
+  useful.
+- Read-only preview: a stretched transparent button or anchor over a
+  positioned wrapper may open the card in the stack.
+- Never place a stretched overlay over inputs, buttons, or wizards. It
+  intercepts interaction and turns an inline task into accidental
+  navigation.
+
+## What the host injects per format
+
+When you write `<@fields.featured @format='<F>' />`, the rendered DOM is:
+
+```html
+<div
+  class="boxel-card-container
+            field-component-card
+            <F>-format                          /* isolated-format | embedded-format | fitted-format | atom-format */
+            display-container-<true|false>      /* depends on @displayContainer arg */
+            boxel-card-container--boundaries    /* present unless @displayContainer={{false}} */
+            boxel-card-container--themed"
+  data-boxel-card-container
+  data-boxel-card-id="…"
+  data-boxel-card-format="<F>"
+>
+  <!-- the linked card's static <F> template renders here -->
+</div>
+```
+
+## Default CSS the host applies (every parent inherits this)
+
+```css
+/* From card-container/index.gts — global so it can be styled anywhere */
+:global(.boxel-card-container) {
+  position: relative;
+  background-color: var(--background, var(--boxel-light));
+  border-radius: var(--_boxel-radius);
+  color: var(--foreground, var(--boxel-dark));
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+  z-index: 0;
+}
+:global(.boxel-card-container--boundaries) {
+  box-shadow: 0 0 0 1px var(--border, var(--boxel-border-color));
+}
+
+/* From field-component.gts — per-format additions */
+.field-component-card.embedded-format {
+  container-name: embedded-card;
+  container-type: inline-size;
+  overflow: hidden;
+}
+.field-component-card.fitted-format {
+  width: 100%;
+  height: 100%;
+  min-height: 40px;
+  max-height: 600px;
+  container-name: fitted-card;
+  container-type: size;
+  overflow: hidden;
+}
+.field-component-card.atom-format.display-container-true {
+  display: inline-block;
+  width: auto;
+  height: auto;
+  padding: var(--boxel-sp-4xs) var(--boxel-sp-xs);
+}
+.field-component-card.atom-format.display-container-false {
+  display: contents; /* no chrome at all */
+}
+.field-component-card.atom-format > :deep(*) {
+  vertical-align: middle; /* baseline default for inline children */
+}
+```
+
+**The five most common consequences:**
+
+1. **Rounded corners on every embedded child** — `border-radius:
+var(--_boxel-radius)` is the Boxel default (`0.5rem`-ish). Sharp-corner
+   designs need to override this.
+2. **A 1px halo around the chrome** — `box-shadow: 0 0 0 1px var(--border)`
+   when `--boundaries` is on (default).
+3. **Cream/white background** — `--background` defaults to
+   `var(--boxel-light)`. If your parent's paper color differs, the embedded
+   child looks pasted on.
+4. **Images clipped at corners** — `overflow: hidden` is hardcoded. Hero
+   images that should bleed past the corner get clipped.
+5. **Atoms are inline-block with padding** — they sit as little chips, not
+   as raw inline content. They get `vertical-align: middle`, which doesn't
+   always align with surrounding prose baseline.
+
+## Override layers — pick the lowest one that works
+
+### Layer 0 — theme cascade (the cleanest)
+
+If the linked card has `cardInfo.theme` AND the theme sets the variables,
+the cascade carries values into the wrapper without `:deep()`:
+
+| Token the theme sets | Effect on the wrapper                                            |
+| -------------------- | ---------------------------------------------------------------- |
+| `--background`       | wrapper background                                               |
+| `--foreground`       | text color inside                                                |
+| `--border`           | the 1px halo color (only visible if `--boundaries` is on)        |
+| `--radius`           | cascades into `--_boxel-radius` IF the card has `--themed` class |
+
+Caveat: the wrapper's `--themed` class is only added when `hasTheme(card)`
+is true on the _linked_ card. If your performer / venue / listing instances
+DON'T have `cardInfo.theme`, the wrapper won't pick up your `--radius: 0`
+from the parent.
+
+### Layer 1 — `:deep()` from the parent's `<style scoped>` (the workhorse)
+
+`:deep()` pierces scoping so the parent's CSS can target descendant
+elements. The CardContainer is `:global(.boxel-card-container)`, so
+`:deep()` works for it too.
+
+```css
+/* In the PARENT card's <style scoped> */
+
+/* Square corners on every embedded child inside .prg-listings-grid */
+.prg-listings-grid :deep(.boxel-card-container) {
+  border-radius: 0;
+  background: var(--paper);
+}
+
+/* Kill the halo selectively */
+.prg-listings-grid :deep(.boxel-card-container--boundaries) {
+  box-shadow: none;
+}
+
+/* Let images bleed past the chrome */
+.prg-hero :deep(.field-component-card.embedded-format) {
+  overflow: visible;
+}
+
+/* Target by format via data-attribute (more readable for some) */
+.prg-listings-grid :deep([data-boxel-card-format='embedded']) {
+  border-radius: 0;
+  box-shadow: none;
+}
+```
+
+### Layer 2 — `@displayContainer={{false}}` (kill the chrome entirely)
+
+For atoms especially, often you want NO chrome — just the linked card's
+content inline, as if it were raw text. The arg works for any format the
+field-component supports:
+
+```gts
+<@fields.headliner @format='atom' @displayContainer={{false}} />
+```
+
+This causes the wrapper to render as `display: contents` — the container
+disappears, only the children layout. **The class on the wrapper still
+exists** (`field-component-card atom-format display-container-false`) but
+it's transparent to layout.
+
+Pair this with a sibling element styled by the parent to provide the visual
+chip:
+
+```gts
+<span class='prg-bill-chip'>
+  <@fields.headliner @format='atom' @displayContainer={{false}} />
+</span>
+```
+
+```css
+.prg-bill-chip {
+  display: inline-flex;
+  align-items: baseline;
+  padding: 4px 10px;
+  border: 1px solid var(--ink);
+  border-radius: 0; /* sharp corners */
+  background: transparent;
+}
+.prg-bill-chip :deep(*) {
+  vertical-align: baseline; /* override the host's vertical-align: middle */
+}
+```
+
+Now the chip is YOURS — borders, padding, alignment all under parent
+control, and the child's atom content renders inside without competing
+chrome.
+
+## Plural fields — the wrapper trap (HIGH-FREQUENCY BUG)
+
+When the parent renders a plural field with one tag —
+`<@fields.topSwimmers @format='fitted' />`,
+`<@fields.participatingClubs @format='embedded' />`,
+`<@fields.recentResults @format='embedded' />` — the host inserts a wrapper
+_between_ your grid container and each card. Your `display: grid` sees ONE
+child (the wrapper), the wrapper contains all the cards, and the layout
+collapses to a single column.
+
+### What the host actually inserts
+
+```html
+<!-- linksToMany -->
+<div class="plural-field linksToMany-field <format>-format">
+  <div class="linksToMany-itemContainer">
+    <div class="linksToMany-item">
+      <div class="boxel-card-container field-component-card <format>-format …">
+        …
+      </div>
+    </div>
+  </div>
+  <div class="linksToMany-itemContainer">…</div>
+  …
+</div>
+
+<!-- containsMany (compound field with @format) -->
+<div class="plural-field containsMany-field <format>-format">
+  <div class="containsMany-item">
+    <div class="boxel-card-container field-component-card …">…</div>
+  </div>
+  …
+</div>
+```
+
+Note the differences: `linksToMany` has an extra
+`.linksToMany-itemContainer` wrapper (one per item), AND another
+`.linksToMany-item` inside it. `containsMany` is shallower — just
+`.containsMany-item` per item. Both share the outer `.plural-field` class —
+that's the only class common to both shapes.
+
+### The fix — collapse every wrapper so the grid sees the actual cards
+
+```css
+.swm-swimmers {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 14px;
+}
+/* The outer plural wrapper — covers both linksToMany and containsMany */
+.swm-swimmers :deep(> .plural-field) {
+  display: contents;
+}
+/* The per-item wrappers — different between linksToMany and containsMany,
+   but harmless to list both since unused ones simply don't match */
+.swm-swimmers :deep(.linksToMany-itemContainer),
+.swm-swimmers :deep(.containsMany-item) {
+  display: contents;
+}
+```
+
+Now the grid sees `.field-component-card` instances as its direct children
+and lays them out properly.
+
+⚠️ **Targeting only `.containsMany-field` is the most common bug.** Older
+patterns (and the host's own legacy class) sometimes show only that class —
+but `linksToMany` ships with `.linksToMany-field`, which never matches
+`:deep(> .containsMany-field)`. Use `.plural-field` for the outer wrapper.
+
+### Staggered animations through `display: contents` wrappers
+
+`:nth-child` resolves against the DOM, not the visual flow — so
+`.field-component-card:nth-child(N)` matches whatever sits inside the
+per-item wrapper (always the only child of its parent → always
+`:nth-child(1)`). Staggered delays applied directly to the cards collapse to
+a single delay value.
+
+Use CSS custom-property inheritance — values pass through
+`display: contents` because they're inherited:
+
+```css
+.swm-stagger :deep(.linksToMany-itemContainer:nth-child(1)),
+.swm-stagger :deep(.containsMany-item:nth-child(1)) {
+  --stagger-d: 80ms;
+}
+.swm-stagger :deep(.linksToMany-itemContainer:nth-child(2)),
+.swm-stagger :deep(.containsMany-item:nth-child(2)) {
+  --stagger-d: 160ms;
+}
+/* …etc, or use :nth-child(n+8) to cap the cascade */
+
+.swm-stagger {
+  --stagger-d: 0ms; /* base value — items past the stagger cap animate immediately */
+}
+.swm-stagger :deep(.field-component-card) {
+  opacity: 0;
+  transform: translateY(12px);
+  animation: rise 600ms cubic-bezier(0.2, 0.7, 0, 1) forwards;
+  animation-delay: var(--stagger-d);
+}
+```
+
+The `:nth-child` runs on the wrapper (whose DOM-position is stable,
+1-indexed across the plural field), the `--stagger-d` value inherits down
+through the per-item wrapper to `.field-component-card`, and the animation
+reads it directly.
+
+### Singular linksTo / contains is fine — no wrapper
+
+`<@fields.featuredEvent @format='embedded' />` renders the
+`.field-component-card` directly, no plural wrapper. The existing
+`:deep(.boxel-card-container) { … }` overrides apply as-written.
+
+## Atom alignment — the dedicated pattern
+
+Atoms default to `display: inline-block; vertical-align: middle; padding:
+var(--boxel-sp-4xs) var(--boxel-sp-xs)`. That makes them sit as floating
+chips. To align with surrounding text (baseline, not middle), or to
+layout-grid them into a parent's structure:
+
+```css
+/* In the parent's <style scoped> */
+
+/* Make atoms baseline-align with surrounding prose */
+.prg-bill :deep(.field-component-card.atom-format) {
+  vertical-align: baseline;
+}
+
+/* If atom is in a grid cell, center it vertically */
+.prg-bill-row :deep(.field-component-card.atom-format) {
+  align-self: center;
+}
+
+/* Strip the default padding when you want raw text inside your own chip */
+.prg-bill-chip :deep(.field-component-card.atom-format) {
+  padding: 0;
+}
+
+/* The host's :deep(*) vertical-align rule on atom children — override on demand */
+.prg-bill-chip :deep(.field-component-card.atom-format > *) {
+  vertical-align: baseline;
+}
+```
+
+For a row of atoms (e.g. "01 Headlining: [Big Thief]"), the cleanest pattern
+is **`@displayContainer={{false}}`** + a parent-owned chip span. Then the
+parent decides everything (sharp corners, ink-on-paper background, baseline
+alignment) and the atom's actual content (the linked card's name) sits
+inside.
+
+### ⚠️ Atoms on dark backgrounds disappear by default
+
+The default atom render is `inline-block` with `padding`, the global
+`.boxel-card-container` background (`var(--background, var(--boxel-light))`
+— a near-white), AND a `--boundaries` box-shadow ring. Inside the chrome,
+`DefaultAtomViewTemplate` renders the linked card's `cardTitle` as a
+`<span>`. If your parent context has a dark background and you set
+`color: inherit` on the atom chip, the chip's _own_ near-white background
+still wins — and you get a gray pill with invisible text.
+
+**Two fixes, pick one:**
+
+```gts
+{{!-- A) Strip the chrome entirely — atom renders as plain inline text --}}
+<@fields.swimmer @format='atom' @displayContainer={{false}} />
+
+{{!-- B) Keep the chrome but recolor it from the parent --}}
+<@fields.swimmer @format='atom' />
+```
+
+```css
+/* If you went with (B), inside the parent's scoped style: */
+.dark-header :deep(.field-component-card.atom-format) {
+  background: transparent; /* drop the near-white surface */
+  box-shadow: none; /* drop the boundaries ring */
+  color: var(--accent); /* and set foreground explicitly */
+}
+.dark-header :deep(.boxel-card-container--boundaries) {
+  box-shadow: none; /* in case --boundaries is the variant in use */
+}
+```
+
+(A) is the right call inside running text or label/value rows where you
+don't want chip chrome at all. (B) is the right call when you DO want a
+visible chip — you just want it to match your dark surface.
+
+## Picking the divider strategy — parent draws OR child halo, never both
+
+The second-most-common bug after "wrong format for the cell size" is the
+**double-rule trap**: the parent adds its own divider lines between cards
+(`border-bottom`, `border-right`, an outer `border` on a grid), and _also_
+leaves the host's default `.boxel-card-container--boundaries`
+`box-shadow: 0 0 0 1px var(--border)` in place. At every boundary, two lines
+render at slightly different weights or colors — the user sees this as a
+drop shadow fighting a thin border.
+
+You always have to pick one of two strategies. There is no in-between.
+
+### Strategy A — parent draws dividers (newspaper grid, list rows)
+
+```css
+.event-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 0; /* no gap — rows touch */
+  border-top: 1px solid var(--ink); /* parent owns the rules */
+}
+.event-list :deep(.boxel-card-container--boundaries) {
+  box-shadow: none; /* MUST kill the child halo */
+}
+.event-list :deep(.field-component-card.embedded-format) {
+  border-bottom: 1px solid var(--rule-soft); /* parent draws between */
+}
+```
+
+Use for: vertical lists, editorial newspaper grids, table-style rosters,
+anywhere the design is "cards as data rows separated by hairlines."
+
+### Strategy B — child halo is the boundary (gap-spaced tile grid)
+
+```css
+.event-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 16px; /* gap is the breathing room */
+}
+.event-grid :deep(.boxel-card-container--boundaries) {
+  box-shadow: 0 0 0 1px var(--ink); /* keep / recolor the child halo */
+}
+/* DON'T add border-bottom / border-right on the cards — that's the double rule */
+```
+
+Use for: card-style tile grids, dashboards with floating "objects," anywhere
+each card should feel like a separate UI element with airspace around it.
+
+### Decision
+
+| What you want                                      | Strategy                                                          |
+| -------------------------------------------------- | ----------------------------------------------------------------- |
+| Rows touching, single 1px line between them        | A — parent draws, kill child halo                                 |
+| Tiles with gaps and their own visible boundary     | B — keep child halo, no parent borders                            |
+| Tiles with gaps and NO boundaries (cards on paper) | B — but `box-shadow: none` on `--boundaries` too                  |
+| Heavy outer frame + inner thin dividers            | A — both outer border AND inner divider on parent, child halo OFF |
+
+### Switching strategies mid-build
+
+When you change a section from Strategy B (halo IS the boundary) to
+Strategy A (parent draws dividers), you MUST find and DELETE the old halo
+rule. Don't just add a `box-shadow: none` override later in the file.
+Same-selector / same-specificity CSS resolves by source order — the stale
+rule further down wins, and your "fix" silently does nothing.
+
+```css
+/* ❌ Two rules, same selector — the LAST one wins. Your fix is invisible. */
+.event-list :deep(.boxel-card-container--boundaries) {
+  box-shadow: none; /* line 200 */
+}
+/* … 30 lines of unrelated rules … */
+.event-list :deep(.boxel-card-container--boundaries) {
+  box-shadow: 0 0 0 1px var(--ink); /* line 230 — stale, but wins */
+}
+
+/* ✅ Delete the stale rule entirely. One source of truth per selector. */
+.event-list :deep(.boxel-card-container--boundaries) {
+  box-shadow: none;
+}
+```
+
+Audit step before declaring a chrome change done:
+`grep -c "boundaries" your-file.gts` should return one rule per section. If
+a section has two, one is stale.
+
+### The failure mode
+
+Looks like: every card has a slight drop-shadow halo plus a thin border line
+between them. The user calls it "drop shadow fighting with thin border."
+It's NOT a shadow vs. border — it's the host's `--boundaries` 1px shadow
+rendered on top of (or under) the parent's own 1px border.
+
+Other tell-tales:
+
+- Top and bottom of the list look "doubled" — the parent's `border-top`
+  lands at the same pixel as the first card's halo.
+- A horizontal rule at the boundary is darker / lighter in two places
+  (because the halo is `var(--border)` and the parent's rule is
+  `var(--rule-soft)`).
+- Hover lift transforms the card +2px and you suddenly see the parent's
+  static border line where the card used to be.
+
+## Picking the format — fitted vs embedded (decide BEFORE you style)
+
+The single most common rendering bug: the parent picks `@format='fitted'`
+for a list of cards, the cards have short content, and each cell becomes a
+huge box with empty space below the content. The user calls it out: _"the
+box is bigger than the actual format."_
+
+The fix is upstream of CSS — it's the format choice. The two formats have
+fundamentally different layout contracts:
+
+| Format     | Who controls the box size?                                                                                                                                                                                                           | Use when                                                                                                                                                                              |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `embedded` | **The child.** `container-type: inline-size` only — width is fluid, height is whatever the card's content + padding adds up to.                                                                                                      | A vertical list (event lineup, results feed, clubs roster), variable-height items, anything where the card's natural content should dictate the row height.                           |
+| `fitted`   | **The parent.** `width: 100%; height: 100%; container-type: size`. The card fills whatever box you give it. Inside, the card's own `static fitted` uses container queries to pick a layout based on the box dimensions you supplied. | A uniform tile grid (calendar cells, swimmer portraits, badge strip), thumbnail toolbar, anywhere you've _deliberately set the cell size_ and want every card to fill it identically. |
+
+### The decision rule
+
+**Did you set the cell size?**
+
+- _Yes — I want all cells the same height/aspect for visual rhythm_ →
+  `fitted`, and set `min-height` / `aspect-ratio` on the cell.
+- _No — let the content decide_ → `embedded`, and don't set `min-height` on
+  the cell.
+
+### Anti-patterns
+
+```gts
+{{!-- 🚫 fitted into a flex column with no height — empty white box --}}
+<div class='event-list'>
+  <@fields.events @format='fitted' />
+</div>
+```
+
+```css
+.event-list {
+  display: flex;
+  flex-direction: column;
+}
+.event-list :deep(.fitted-format) {
+  min-height: 160px; /* fitted now forces 160px; short content leaves 80px empty */
+}
+```
+
+```gts
+{{!-- ✅ embedded — each event row hugs its own height --}}
+<div class='event-list'>
+  <@fields.events @format='embedded' />
+</div>
+```
+
+```css
+.event-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  border-top: 1px solid var(--ink);
+}
+.event-list :deep(.field-component-card.embedded-format) {
+  border-bottom: 1px solid var(--rule-soft); /* divider, not a forced height */
+}
+```
+
+### When the child has both formats, the child decides what each one is for
+
+If the `Event` card's `static embedded` is designed as a one-line list row
+(icon + name + meta), use it for lists. If its `static fitted` is designed
+as a 220×160 calendar-style tile, use it for calendar grids. Don't pick the
+format you _want_ the layout to be — pick the format the child _implements_
+as that layout.
+
+When in doubt, read the child's `static embedded` and `static fitted`
+source — they advertise their intended sizes.
+
+## Format-specific recipes
+
+### Embedded — for grids of related cards (listings, performers, venues)
+
+```gts
+<div class='prg-listings-grid'>
+  {{#each @fields.currentListings as |Listing|}}
+    <Listing @format='embedded' />
+  {{/each}}
+</div>
+```
+
+```css
+.prg-listings-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 24px;
+}
+.prg-listings-grid :deep(.boxel-card-container) {
+  border-radius: 0;
+  background: transparent;
+  box-shadow: none; /* if the parent owns the divider rules */
+}
+.prg-listings-grid :deep(.field-component-card.embedded-format) {
+  overflow: visible; /* if image bleeds matter */
+}
+```
+
+### Fitted — for compact card thumbnails in toolbars / pickers
+
+```gts
+<@fields.featured @format='fitted' />
+```
+
+```css
+.toolbar :deep(.boxel-card-container.fitted-format) {
+  border-radius: 4px;
+  /* DON'T override width/height — fitted needs the host's 100%/100% for its own container queries */
+}
+```
+
+⚠️ **Don't override `width: 100%; height: 100%` on `.fitted-format`** — the
+child's container queries depend on those. Stick to chrome (radius,
+background, border, shadow) and let the layout primitives stay.
+
+### Isolated — when embedding a full card surface inside another (rare; e.g. dashboard preview)
+
+```css
+.preview :deep(.boxel-card-container.isolated-format) {
+  /* isolated takes height: 100% — make sure the parent provides height */
+}
+```
+
+### Atom — when inline with prose or in compact rows
+
+Best practice: `@displayContainer={{false}}` + parent-owned chip span. See
+"Atom alignment" above.
+
+## Cross-cutting concerns
+
+### Don't break the child's container queries
+
+Embedded cards declare `container-type: inline-size; container-name:
+embedded-card`. Fitted declares `container-type: size; container-name:
+fitted-card`. These are the child's basis for responsive layout. Overriding
+them from the parent (via `:deep`) breaks the child's design. Style the
+chrome (`border`, `background`, `border-radius`, `box-shadow`, `padding`),
+not the layout primitives.
+
+### Theme tokens cascade INTO `:deep()` overrides
+
+When you write `:deep(.boxel-card-container) { background: var(--paper); }`,
+the `var(--paper)` resolves in the PARENT'S scope. Themes set the token; the
+override applies the token. This is the right way — don't hardcode hex
+inside `:deep()` blocks if a theme token captures the value.
+
+### Test the override after a theme change
+
+If you set `--radius: 0` on the parent's theme, then in a `:deep()` override
+write `border-radius: 0`, you have two sources of truth. When the theme
+later changes to `--radius: 4px`, the `:deep()` block still says `0`.
+Prefer:
+
+```css
+.prg-listings-grid {
+  --child-radius: var(
+    --radius,
+    0
+  ); /* one declaration: theme wins, sharp fallback */
+}
+.prg-listings-grid :deep(.boxel-card-container) {
+  border-radius: var(--child-radius);
+}
+```
+
+## Quick-reference cheat sheet
+
+| Need                                                                  | Tool                                                                                                                                       |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Vertical list of cards with natural row heights                       | `@format='embedded'`, NOT fitted                                                                                                           |
+| Uniform tile grid where every card fills a fixed box                  | `@format='fitted'` + parent sets `min-height` / `aspect-ratio`                                                                             |
+| Plural grid (linksToMany or containsMany) lays out correctly          | `:deep(> .plural-field) { display: contents; }` + `:deep(.linksToMany-itemContainer), :deep(.containsMany-item) { display: contents; }`    |
+| Stagger per-item animation delays                                     | Set `--stagger-d` on `:deep(.linksToMany-itemContainer:nth-child(N))`; read `animation-delay: var(--stagger-d)` on `.field-component-card` |
+| Override embedded child's `border-radius`                             | `:deep(.boxel-card-container) { border-radius: 0; }`                                                                                       |
+| Override embedded child's `background`                                | `:deep(.boxel-card-container) { background: var(--paper); }`                                                                               |
+| Kill the 1px halo                                                     | `:deep(.boxel-card-container--boundaries) { box-shadow: none; }`                                                                           |
+| Let images bleed past corners                                         | `:deep(.field-component-card.embedded-format) { overflow: visible; }`                                                                      |
+| Target by format                                                      | `:deep([data-boxel-card-format="embedded"]) { ... }`                                                                                       |
+| Kill chrome entirely (atom)                                           | `<@fields.X @format='atom' @displayContainer={{false}} />`                                                                                 |
+| Atom visible on dark background                                       | `@displayContainer={{false}}`, OR `:deep(.field-component-card.atom-format) { background: transparent; box-shadow: none; }`                |
+| Atom baseline-align with prose                                        | `:deep(.field-component-card.atom-format) { vertical-align: baseline; }`                                                                   |
+| Atom padding match parent's chip                                      | `:deep(.field-component-card.atom-format) { padding: 0; }`                                                                                 |
+| Override atom child element alignment                                 | `:deep(.field-component-card.atom-format > *) { vertical-align: baseline; }`                                                               |
+| Preserve an interactive embedded task while allowing stack inspection | Leave the child unobstructed and add an explicit `Open ↗`; use stretched overlays only for read-only previews                              |
+
+## What NOT to override
+
+- `width: 100%; height: 100%` on `.field-component-card.fitted-format` —
+  child container queries depend on this.
+- `container-type` / `container-name` on embedded/fitted — child layout
+  depends on this.
+- `display: contents` on `atom-format.display-container-false` — that's the
+  whole mechanism for "no chrome".
+
+---
+
+## The flip side — what the CHILD card MUST NOT do (contract)
+
+Everything above is how the PARENT overrides the host's chrome. The contract
+has a second half: **the child card's formats must leave the outer chrome to
+the host (and to any consuming parent).** When a child decorates its own
+outermost element, it competes with the wrapper and breaks the parent's
+ability to override.
+
+### The simple rule
+
+**The child draws ONLY inside the box. The host or parent draws the box.**
+
+```gts
+{{!-- ❌ Child's isolated decorates its outer element --}}
+<article class='news-isolated'>
+  ...
+</article>
+<style scoped>
+  .news-isolated {
+    border-radius: 12px;                       /* wrapper already sets radius */
+    border: 1px solid #e5e7eb;                 /* competes with --boundaries halo */
+    box-shadow: 0 4px 12px rgba(0,0,0,0.1);    /* same competition */
+    background: white;                         /* blocks --background cascade */
+    overflow: hidden;                          /* wrapper already clips */
+  }
+</style>
+
+{{!-- ✅ Child outer is clean; design lives inside --}}
+<article class='news-isolated'>
+  ...
+</article>
+<style scoped>
+  .news-isolated {
+    color: var(--ink);            /* OK — inner concern */
+    padding: 48px;                /* OK — inner concern */
+    display: grid;                /* OK — inner layout */
+    gap: 32px;                    /* OK — inner concern */
+    /* NO border-radius, NO border, NO box-shadow, NO opaque background */
+  }
+</style>
+```
+
+### Per format — what's safe and what isn't on the outermost element
+
+`CardContainer` — which wraps every card render, not just field embeds —
+already applies the theme's `background-color`, `color`, `font-family` (the
+theme's `--font-sans`, falling back to the Boxel sans stack), and body
+`font-size` on its root; templates inherit all of them for free. Don't
+declare any of these on the root unless you're deviating: `font-family` only
+when the whole card should use something other than `--font-sans` (such as
+`--font-serif`); `background-color`/`color` only when a pairing other than
+the theme's main background/foreground is preferred. `fitted` and `embedded`
+card templates MAY make that switch (e.g. `background-color: var(--card);
+color: var(--card-foreground)`); `isolated` and CardDef `edit` templates
+keep the theme's pair.
+
+| Format     | OK on outermost                                                                                                                                 | NOT OK on outermost (host/parent owns)                                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `isolated` | inner padding, inner grid/flex layout, `min-height` for content                                                                                 | `border-radius`, `border`, `box-shadow`, `overflow`, background/foreground overrides (use the theme's)                                           |
+| `embedded` | same as isolated — plus MAY use a different background/foreground pairing from the theme (e.g. `--card` + `--card-foreground`)                  | `border-radius`, `border`, `box-shadow`, `overflow`, `width`/`height`/`max-width`                                                                |
+| `fitted`   | a background/foreground pairing different from the theme's (e.g. `--card` + `--card-foreground`), inner padding, inner grid template, inner gap | `border-radius`, `border`, `box-shadow`, `width`, `height`, `min-height`, `max-height`, `container-type`, `container-name` (the host sets these) |
+| `atom`     | inline content only (text node, small inline icon)                                                                                              | `padding` (host provides), `border`, `border-radius`, `background`, any `display` other than inline-by-default                                   |
+| `edit`     | form field spacing, internal stack/grid layout                                                                                                  | outer chrome same as isolated (keep the theme's background/foreground)                                                                           |
+
+**Compound-field templates are the exception to the edit/embedded rows:** a
+FieldDef's `embedded` and `edit` templates render nested _inside_ a card
+surface, so they may choose a different background/foreground combo to
+distinguish themselves from the surrounding card — `--card` +
+`--card-foreground` is the usual choice.
+
+### When your design genuinely demands a specific outer treatment
+
+Put it on the **Theme card**, not the child's format CSS. The
+CardContainer's `--themed` cascade picks up `--radius`, `--background`,
+`--border`, `--foreground` from the theme and applies them at the wrapper.
+Every card linked to that theme inherits the outer treatment without
+competing with the host.
+
+An editorial sharp-corner aesthetic, for example:
+
+```
+Theme/<name>.json cssVariables:
+  --radius: 0;                /* ← wrapper picks up via --_boxel-radius */
+  --background: #f4eee1;      /* ← wrapper background = brand paper */
+  --border: #1a1814;          /* ← halo when --boundaries on = brand ink */
+```
+
+Every card linked to that theme renders with sharp corners + paper
+background + ink halo, automatically. No format CSS needed.
+
+### Why this matters — the failure mode
+
+When the parent (e.g., a showcase card) embeds your card:
+
+- **Contract honored:** parent's `:deep(.boxel-card-container) {
+border-radius: 0; background: var(--paper); }` overrides cleanly. Sharp
+  corners, brand paper, no double-borders.
+- **Contract violated:** child's own `border-radius: 12px` on
+  `.news-isolated` competes with parent's `:deep` override. Specificity
+  wars. Or child's `box-shadow` stacks under the halo creating a
+  double-border. Or child's `background: white` blocks the parent's
+  `--paper` cascade — embedded child looks pasted on instead of integrated.
+
+The single most common symptom in agent-generated cards is rounded-corner
+embedded children inside a sharp-corner parent. Cause: every child added
+`border-radius: 8px` to its outer because "cards have rounded corners." Fix:
+strip the outer decoration; trust the wrapper.
+
+### Self-check before declaring a format done
+
+Before any `static isolated|embedded|fitted|atom|edit = class { ... }` is
+considered complete:
+
+1. Does the outermost element have `border-radius`, `border`, or
+   `box-shadow`? If yes — move that decision to the Theme card, or remove
+   it. For `isolated` and CardDef `edit`, also don't override the theme's
+   background/foreground; `fitted` and `embedded` may use a different
+   pairing (e.g. `--card` + `--card-foreground`).
+2. For `fitted`: does the outermost element set `width`, `height`,
+   `min/max-height`, `container-type`, or `container-name`? If yes — remove.
+   The host sets these on `.field-component-card.fitted-format`.
+   (`background-color` paired with `color` is fine on a fitted root —
+   boxel-ui's `FittedCard` sets both.)
+3. For `atom`: is the outermost element doing anything more than inline text
+   - maybe one inline icon? If yes — restructure. Atoms are inline content,
+     not chips. (Chips are the parent's job; see `@displayContainer={{false}}`
+     recipes.)
+4. Open the card both standalone (in the stack) and embedded inside another
+   card. Does it look right in BOTH contexts? If only one, the child is
+   decorating the outer.
+
+Design the content; trust the wrapper.
+
+## Source files (verify before depending on details)
+
+In the Boxel monorepo:
+
+- `packages/boxel-ui/addon/src/components/card-container/index.gts` —
+  CardContainer + the global selector + `--themed` cascade
+- `packages/base/field-component.gts` — per-format classes +
+  `displayContainer` arg
+- `packages/catalog-realm/crm-app/contact.gts` — production examples of
+  `@displayContainer={{false}}` for atom
+- `packages/catalog-realm/sprint-planner/sprint-task.gts` — atom with custom
+  class + display:contents
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-fetch-contexts/SKILL.md b/packages/software-factory/.agents/skills-orchestrator/boxel-fetch-contexts/SKILL.md
new file mode 100644
index 00000000000..15ff03068ec
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-fetch-contexts/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: boxel-fetch-contexts
+description: Fetch contexts — who carries auth where in Boxel (card code vs prerenderer vs CLI/orchestrator), and why raw fetch() from card code 401s on private realms. Use when card code needs to load cards, files, or external APIs, or when a fetch returns 401/unauthenticated data.
+---
+
+# Fetch contexts — who carries auth where
+
+Boxel code runs in several different execution contexts, and each carries
+authentication differently. Most "my fetch returns 401" and "why is this
+data empty" bugs come from using the wrong data path for the context the
+code runs in.
+
+## 1. Card code in the host — use store APIs, not raw fetch
+
+Card code running inside the host (the Boxel app in the user's browser) has
+an **authenticated session** — but that auth lives in the store and host
+tools, not in the global `fetch`. Reach data through:
+
+- **CardContext store APIs** — `store.search`, `getCard` / `getCards` — for
+  loading and querying cards.
+- **Host tools** — `@cardstack/boxel-host/tools/*` (e.g. `search-cards`,
+  `fetch-card-json`, `authed-fetch`) — for app-level operations.
+
+Do NOT reach for raw `fetch()` to realm URLs from card code.
+
+## 2. Raw fetch() to a private realm URL returns 401
+
+Realm auth does **not** ride on naked `fetch`. A plain
+`fetch('https://…/my-realm/some-file.png')` from card code against a
+private realm returns **401** — there is no cookie or header magic attached
+for you. Use the store / `getCard` / host tools instead.
+
+For **external HTTP APIs**, use the realm server's request-forward proxy:
+`POST /_request-forward` with `{ url, method, headers, requestBody }`
+(surfaced in card code as `SendRequestViaProxyCommand` /
+`@cardstack/boxel-host/tools/send-request-via-proxy`). The proxy carries
+**server-side credentials for approved services** — this is also how
+OpenRouter access works in production.
+
+## 3. The prerenderer context — authed, but not interactive
+
+The prerenderer (screenshots, indexing) runs with **realm credentials**, so
+it can read what it needs — but it is **NOT an interactive session**. In
+particular, async renderers may not have painted when `'ready'` fires:
+anything that lazy-loads, animates in, or fetches after first render can be
+missing from screenshots and indexed HTML. Don't assume prerendered output
+equals what an interactive user sees.
+
+## 4. CLI / orchestrator contexts — the Boxel profile
+
+CLI and orchestrator tooling authenticates via the **Boxel profile** — a
+JWT obtained through `getRealmToken`. That JWT can also drive Playwright
+against the host when browser automation needs an authenticated session.
+
+## Rule of thumb
+
+| Situation                                 | Use                                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------- |
+| I'm in card code and need cards           | CardContext store APIs (`store.search`, `getCard`)                                      |
+| Card code needs an external API           | The request-forward proxy, via a host tool (`send-request-via-proxy`) or `authed-fetch` |
+| Card code needs file bytes from the realm | The file card's own component / host APIs — never raw `fetch` to the URL                |
+| Orchestrator / tooling                    | The boxel-cli client (profile JWT)                                                      |
+
+## Binary media — never inline it
+
+Regardless of context: binary media must **never** be inlined into card JSON
+(no `data:` / base64 bytes in attributes). Store media as a realm file —
+generated bytes go through `WriteBinaryFileCommand`
+(`@cardstack/boxel-host/tools/write-binary-file`), then link the file via
+`linksTo(FileDef / ImageDef / PngDef)`.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/SKILL.md b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/SKILL.md
new file mode 100644
index 00000000000..d33b3e29808
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/SKILL.md
@@ -0,0 +1,148 @@
+---
+name: boxel-live-surfaces
+description: Live, self-updating card lists via @context.searchResultsComponent — the SearchEntryWireQuery contract, query traps, clickable tiles, and live activity feeds. Use when a card needs to list other cards in the realm (home/dashboard sections, feeds, grids) or when a search section renders nothing.
+---
+
+# Boxel Live Surfaces
+
+`@context.searchResultsComponent` is the preferred way for a card to render
+a live list of other cards. It re-runs as the realm changes — new instances
+appear automatically, and the host prerenders each result so the card never
+loads every model into memory.
+
+Fuller worked examples live in `references/`:
+
+- `references/app-card-home-with-search.md` — the Home/app-card pattern (one live section per CardDef in a family).
+- `references/live-activity-feed-card.md` — append-only activity/log feed recipe.
+
+## The wire-query contract (get this wrong → silent empty render)
+
+`@context.searchResultsComponent` consumes a **WIRE query, not a plain
+`Query`**. Build it with `searchEntryWireQueryFromQuery(query)` from
+`@cardstack/runtime-common`, then attach:
+
+- `realms: [<realm url>]` — an **array**; there is no `realm` key.
+- the display format via `filter.eq.htmlQuery = { eq: { format: 'fitted' } }`.
+
+Invoke it in **block form** (`as |results|`), iterate `results.entries`, and
+render `<entry.component />` inside a parent-sized cell. **A plain Query
+passed to a self-closed `<@context.searchResultsComponent @query={{q}} />`
+renders NOTHING, silently.**
+
+```gts
+import { cached } from '@glimmer/tracking';
+import {
+  codeRef,
+  realmURL,                       // the Symbol — NEVER Symbol.for('realmURL')
+  searchEntryWireQueryFromQuery,
+  type Query,
+  type SearchEntryWireQuery,
+} from '@cardstack/runtime-common';
+
+// @ts-expect-error import.meta is supported by the Boxel host
+const here: string = import.meta.url;
+
+// inside the Component class:
+get taskRef() { return codeRef(here, './task', 'Task'); }
+get realms(): string[] {
+  const url = this.args.model?.[realmURL];
+  return url ? [url.href] : [];   // [] while loading — never query unscoped
+}
+get tasksQuery(): Query {
+  const ref = this.taskRef;
+  return {
+    filter: { type: ref },        // type, not bare `on` — see traps below
+    sort: [{ by: 'dueDate', on: ref, direction: 'asc' }],
+  };
+}
+@cached
+get tasksWireQuery(): SearchEntryWireQuery {
+  const q = searchEntryWireQueryFromQuery(this.tasksQuery);
+  return {
+    ...q,
+    realms: this.realms,
+    filter: {
+      ...q.filter,
+      eq: { ...q.filter?.eq, htmlQuery: { eq: { format: 'fitted' } } },
+    },
+  };
+}
+```
+
+```gts
+<ul class='cells'>
+  <@context.searchResultsComponent @query={{this.tasksWireQuery}} @mode='hover' as |results|>
+    {{#if results.isLoading}}<li>Loading…</li>{{/if}}
+    {{#each results.entries key='id' as |entry|}}
+      <li class='cell'><entry.component /></li>
+    {{else}}
+      <li>No tasks yet.</li>
+    {{/each}}
+  </@context.searchResultsComponent>
+</ul>
+```
+
+## The three query traps (each silently returns zero rows)
+
+1. **`filter: { type: ref }` to select all cards of a type.** Never
+   `filter: { on: ref }` — `on` is a scope for predicates, not a filter on
+   its own. `{ on: ref }` with no predicate returns zero rows.
+2. **Custom-field sorts require `on: ref`.** Only `lastModified`,
+   `createdAt`, and `cardURL` are valid sort keys without `on`. Sorting on
+   any custom field — the sort expression MUST include `on: ref`.
+3. **Use `codeRef(here, path, name)`, not raw URL construction.** And
+   import `realmURL` as a Symbol from `@cardstack/runtime-common` — don't
+   write `Symbol.for('realmURL')` (it produces a different Symbol that
+   doesn't match what the host injected).
+
+## Realm-scoped and bounded — always
+
+Every card-owned query MUST be realm-scoped and bounded. A missing or empty
+realm argument falls back to querying **every available realm**. Default to
+the current card's realm (via the `realmURL` Symbol), do not start the query
+until that realm is known (return `[]` and let `results.isLoading` show),
+and cap general-purpose hydration at a sensible page size.
+
+## Counts without hydration
+
+For KPI/funnel numbers, put `page: { size: 1 }` on the wire query and read
+`results.meta.page.total` — one row of HTML, full count.
+
+## `@cached` the wire-query getters
+
+Decorate wire-query getters with `@cached` so SearchResults keeps ONE live
+subscription per section instead of resubscribing on every re-render.
+
+## Making tiles clickable
+
+| Mode                         | What enables click                                                             | Mechanism                                       |
+| ---------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------- |
+| **Interact / Code** (in-app) | `{{@context.cardComponentModifier ...}}` on the tile's container               | Pushes the card onto the Boxel app's card stack |
+| **Host** (published site)    | `<a href={{entry.id}}>` transparent overlay inside a `position: relative` cell | Plain browser navigation                        |
+
+Always wire one of these — otherwise the tiles render beautifully and do
+nothing on click. Use the **overlay** pattern for Host mode, never
+`<a><entry.component /></a>` wrapping (the height-100% chain through the
+card chrome breaks silently and fitted cards collapse to zero height). In
+monitor-style cards use
+`this.args.viewCard(url, 'isolated', { openCardInRightMostStack: true })` —
+never `<a href>` (full-page navigation drops the surface).
+
+## Churn warning — live means LIVE
+
+Every live section re-runs on **EVERY index change in the realm** — any card
+created, edited, or deleted. A realm that is written every few seconds (sync
+loops, log writers, autosave-heavy edit forms) makes every section flash its
+loading state continuously. Keep high-frequency writers out of the realm the
+dashboard watches, prefer showing stale results over a loading state during
+revalidation, keep the number of live sections per card modest, and use
+`@mode='none'` (prerendered HTML, no hover hydration — cheaper) for
+read-only sections; `@mode='hover'` for browsable grids.
+
+## The store.search unhydrated-linksTo trap
+
+Cards returned by store search APIs have **unhydrated `linksTo` fields** —
+reading `card.someLink.title` gives you nothing. To reach a linked card's
+data from a search result, fetch the card-source JSON document and read
+`relationships.<field>.links.self` to get the linked card's URL, then load
+that card explicitly.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/app-card-home-with-search.md b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/app-card-home-with-search.md
new file mode 100644
index 00000000000..203de754a93
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/app-card-home-with-search.md
@@ -0,0 +1,431 @@
+# app-card-home-with-search — Every card family needs a home
+
+**What this gives you:** A `Home` CardDef (typically named after the brand)
+that sits at the top of a card family and uses
+`@context.searchResultsComponent` to dynamically list every Meet / Listing /
+Project / etc. in the realm. `prefersWideFormat = true` so it opens
+edge-to-edge. The user lands on it, sees the realm at a glance, drills in
+from there.
+
+**When to use:** Whenever you build a card _family_ — 2+ related CardDefs
+(Meet + Swimmer + Club, Project + Task + Person, Show + Listing + Venue,
+etc.). Building a single utility card? Skip this pattern. Building anything
+where the user will accumulate instances over time? Build the home.
+
+**Why it matters:**
+
+- **Discoverability.** A realm with 5 CardDefs and no home shows users an
+  `index.json` `CardsGrid` of mixed cards in adoption order. A home puts the
+  brand voice up front and arranges the suite the way the designer intended.
+- **Editorial framing.** The home is where you set the typography pairing,
+  the eyebrow voice, the color story. Children inherit through the theme
+  cascade.
+- **Live by construction.** `@context.searchResultsComponent` re-runs as the
+  realm changes — new instances appear automatically, no manual
+  relationship-wiring on the home.
+
+**Recipe shape:**
+
+```gts
+// surge.gts (or whatever the brand demands)
+import {
+  CardDef,
+  Component,
+  field,
+  contains,
+  linksTo,
+} from 'https://cardstack.com/base/card-api';
+import StringField from 'https://cardstack.com/base/string';
+import TextAreaField from 'https://cardstack.com/base/text-area';
+import {
+  codeRef,
+  realmURL,
+  searchEntryWireQueryFromQuery,
+  type Query,
+  type SearchEntryWireQuery,
+} from '@cardstack/runtime-common';
+import BoltIcon from '@cardstack/boxel-icons/bolt';
+import { Meet } from './meet';
+
+// @ts-expect-error import.meta is supported by the Boxel host
+const here: string = import.meta.url;
+
+export class Surge extends CardDef {
+  static displayName = 'Surge';
+  static icon = BoltIcon;
+  static prefersWideFormat = true; // ← edge-to-edge home
+
+  @field welcome = contains(StringField);
+  @field tagline = contains(TextAreaField);
+  @field headlineMeet = linksTo(() => Meet); // optional spotlight pin
+
+  @field cardTitle = contains(StringField, {
+    computeVia: function (this: Surge) {
+      return this.cardInfo?.name?.trim()?.length
+        ? this.cardInfo.name
+        : (this.welcome ?? 'SURGE');
+    },
+  });
+
+  static isolated = class Isolated extends Component<typeof Surge> {
+    // codeRef(here, relPath, ExportName) returns { module, name } — the canonical CodeRef
+    get meetRef() {
+      return codeRef(here, './meet', 'Meet');
+    }
+    get swimmerRef() {
+      return codeRef(here, './swimmer', 'Swimmer');
+    }
+    get realms(): string[] {
+      const url = this.args.model?.[realmURL];
+      return url ? [url.href] : [];
+    }
+    // filter: { type: ref } — match ALL cards of a type.
+    //   `on` would be wrong: `on` is a SCOPE inside a predicate, not a filter.
+    // Custom-field sorts require `on: ref` — only lastModified, createdAt, cardURL work without it.
+    get meetsQuery(): Query {
+      const ref = this.meetRef;
+      return {
+        filter: { type: ref },
+        sort: [{ by: 'dates.start', on: ref, direction: 'desc' }],
+      };
+    }
+    get swimmersQuery(): Query {
+      const ref = this.swimmerRef;
+      return {
+        filter: { type: ref },
+        sort: [{ by: 'lastName', on: ref, direction: 'asc' }],
+      };
+    }
+
+    // Each section wraps its Query in searchEntryWireQueryFromQuery, then
+    // attaches `realms` + the fitted display format via filter.eq.htmlQuery.
+    // This is what <@context.searchResultsComponent> consumes.
+    get meetsWireQuery(): SearchEntryWireQuery {
+      const q = searchEntryWireQueryFromQuery(this.meetsQuery);
+      return {
+        ...q,
+        realms: this.realms,
+        filter: {
+          ...q.filter,
+          eq: { ...q.filter?.eq, htmlQuery: { eq: { format: 'fitted' } } },
+        },
+      };
+    }
+    get swimmersWireQuery(): SearchEntryWireQuery {
+      const q = searchEntryWireQueryFromQuery(this.swimmersQuery);
+      return {
+        ...q,
+        realms: this.realms,
+        filter: {
+          ...q.filter,
+          eq: { ...q.filter?.eq, htmlQuery: { eq: { format: 'fitted' } } },
+        },
+      };
+    }
+
+    <template>
+      <article class='sg'>
+        <header class='sg-mast'>
+          <h1 class='sg-wordmark'>{{if
+              @model.welcome
+              @model.welcome
+              'SURGE'
+            }}</h1>
+          {{#if @model.tagline}}<p
+              class='sg-tagline'
+            >{{@model.tagline}}</p>{{/if}}
+        </header>
+
+        {{! Singular spotlight — no plural-field wrapper, simple :deep override }}
+        {{#if @model.headlineMeet}}
+          <section class='sg-featured'>
+            <@fields.headlineMeet @format='embedded' />
+          </section>
+        {{/if}}
+
+        {{! Dynamic section: every Meet in the realm, fitted, live }}
+        <section class='sg-section'>
+          <h2 class='sg-section-title'>The calendar</h2>
+          <ul class='sg-meets'>
+            <@context.searchResultsComponent
+              @query={{this.meetsWireQuery}}
+              @mode='hover'
+              as |results|
+            >
+              {{#if results.isLoading}}
+                <li class='sg-loading'>Loading…</li>
+              {{/if}}
+              {{#each results.entries key='id' as |entry|}}
+                <li class='sg-meets-cell'>
+                  <entry.component class='sg-card' />
+                </li>
+              {{else}}
+                <li class='sg-empty'>No meets yet.</li>
+              {{/each}}
+            </@context.searchResultsComponent>
+          </ul>
+        </section>
+
+        {{! Add one @context.searchResultsComponent section per CardDef in the family }}
+      </article>
+
+      <style scoped>
+        /* Outer chrome — leave radius / border / shadow / opaque bg to the host */
+        .sg {
+          background: var(--paper, #f5f8fa);
+          color: var(--ink, #0b1320);
+          font-family: var(--font-body, system-ui, sans-serif);
+          min-height: 100%;
+        }
+        .sg-meets {
+          list-style: none;
+          padding: 0;
+          margin: 0;
+          display: grid;
+          grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+          gap: 14px;
+        }
+        .sg-meets-cell {
+          min-height: 200px;
+        }
+        /* Chrome override on the prerendered cards */
+        .sg-section :deep(.boxel-card-container) {
+          border-radius: 0;
+          background: var(--card, #ffffff);
+        }
+        .sg-section :deep(.boxel-card-container--boundaries) {
+          box-shadow: 0 0 0 1px var(--ink, #0b1320);
+        }
+      </style>
+    </template>
+  };
+
+  static embedded = class Embedded extends Component<typeof Surge> {
+    /* brand card */
+  };
+  static fitted = class Fitted extends Component<typeof Surge> {
+    /* mini wordmark */
+  };
+}
+```
+
+```json
+// Surge/home.json — the canonical home instance
+{
+  "data": {
+    "type": "card",
+    "attributes": {
+      "welcome": "SURGE",
+      "tagline": "The youth swim meet platform.",
+      "cardInfo": { "name": "SURGE — Home", "summary": "Realm home." }
+    },
+    "relationships": {
+      "headlineMeet": {
+        "links": { "self": "../Meet/mid-atlantic-senior-sectionals-2026" }
+      },
+      "cardInfo.theme": { "links": { "self": "../Theme/surge" } }
+    },
+    "meta": { "adoptsFrom": { "module": "../surge", "name": "Surge" } }
+  }
+}
+```
+
+**`@context.searchResultsComponent` is live by construction — mind the cost
+on multi-section homes.**
+
+Each `@context.searchResultsComponent` section subscribes its query to realm
+change events. Every time ANY card in the realm is created, edited, or
+deleted, the matching sections re-fetch and re-render. For a Home with 4
+result-list sections, editing a single Swimmer somewhere else in the realm
+can fire re-fetches across every section whose query might be affected —
+even though only one section's data actually changed. With the host's
+autosave on each keystroke, this can make unrelated edit forms feel sluggish
+because the Home tab is consuming CPU on every reindex.
+
+There is no snapshot/live toggle to reach for — the surface is live by
+default. The lever you _do_ have is `@mode`: `'hover'` (default) hydrates
+each result so it can respond to hover; `'none'` renders the prerendered
+HTML with no per-result interactivity, which is cheaper for dense read-only
+sections.
+
+```gts
+{{!-- ✅ Default: hover-hydrated results. --}}
+<@context.searchResultsComponent @query={{this.q}} as |results|>
+  {{#each results.entries key='id' as |entry|}}<entry.component />{{/each}}
+</@context.searchResultsComponent>
+
+{{!-- ✅ Cheaper for dense, read-only sections — no per-result hover hydration. --}}
+<@context.searchResultsComponent @query={{this.q}} @mode='none' as |results|>
+  {{#each results.entries key='id' as |entry|}}<entry.component />{{/each}}
+</@context.searchResultsComponent>
+```
+
+Keep the number of live sections on a single Home modest, and prefer
+`@mode='none'` for sections the user only reads.
+
+**Why `@context.searchResultsComponent` (display) instead of `getCards`
+(instances):**
+
+| Use case                                                          | Pick                                         |
+| ----------------------------------------------------------------- | -------------------------------------------- |
+| Showing the cards as themselves (fitted/embedded HTML)            | `@context.searchResultsComponent`            |
+| Reading model values to compute aggregates (counts, sums, charts) | `getCards`                                   |
+| Both — list and aggregate                                         | `getCards`, then render with `<@fields ...>` |
+
+The home almost always wants the first. The host pre-renders each result on
+the realm side, so the home doesn't pay the cost of loading every model into
+memory. For a realm with hundreds of instances, this is the difference
+between snappy and unusable.
+
+**Critical — apply the chrome contract:**
+
+The home's outermost element (`.sg` in the example) MUST leave decoration to
+the host's CardContainer. No `border-radius`, no `border`, no `box-shadow`,
+no opaque `background` (`var(--paper)` is fine — the paper is the brand
+surface, not chrome), no `overflow`. Brand-specific outer treatment goes on
+the Theme card as `--radius`, `--background`, `--border`. See the
+`boxel-delegated-render-control` skill.
+
+**Critical — no plural-field wrapper for search-results output:**
+
+`@context.searchResultsComponent` does NOT wrap its yielded entries in
+`.plural-field / .containsMany-field / .linksToMany-field` — that wrapper
+only appears for `<@fields.plural @format='...' />` direct rendering. With
+the search-results surface, you own the `<ul>` / `<li>` shell yourself, so
+`display: grid` on the `<ul>` works without any `display: contents` tricks.
+The chrome `:deep()` overrides still apply because each result renders
+inside its own `.boxel-card-container`.
+
+**The three query traps:**
+
+1. **`filter: { type: ref }` to select all cards of a type.** Never
+   `filter: { on: ref }` — `on` is a scope for predicates, not a filter on
+   its own. Writing `{ on: ref }` with no predicate returns zero rows.
+2. **Custom-field sorts require `on: ref`.** Only `lastModified`,
+   `createdAt`, and `cardURL` are valid sort keys without `on` (the
+   `generalSortFields` list). Sorting on `lastName`, `dates.start`, anything
+   custom — the sort expression MUST include `on: ref`.
+3. **Use `codeRef(here, path, name)`, not raw URL construction.** And import
+   `realmURL` as a Symbol from `@cardstack/runtime-common` — don't write
+   `Symbol.for('realmURL')` (it produces a different Symbol that doesn't
+   match what the host injected).
+
+Query type definitions live at `packages/runtime-common/query.ts` in the
+Boxel monorepo.
+
+**Other gotchas:**
+
+- `import.meta.url` works in `.gts` at runtime but TS complains — declare
+  `const here: string = import.meta.url;` once at top with
+  `@ts-expect-error` on the line above.
+- Compound sort paths like `dates.start` work for fields-of-fields
+  (`DateRangeField.start`).
+- The home loads when `model.id` is undefined briefly — the realmURL getter
+  handles this by returning `[]` instead of throwing, and
+  `@context.searchResultsComponent` reports `results.isLoading` until realms
+  is non-empty.
+- If you want to open this card by default when someone visits the realm
+  root, rely on `index.json`'s `CardsGrid` showing this as the first card
+  (with a thumbnail + clear title).
+
+## Host-mode click-through — MANDATORY for any app card that publishes
+
+In the published Host mode, cards rendered from
+`@context.searchResultsComponent` entries do NOT click through to their
+isolated view by default. The host's in-app click-to-open machinery
+(`@context.cardComponentModifier`) doesn't run on the published static site.
+Visitors see beautifully rendered fitted tiles that do nothing on click.
+
+**Fix: wrap each rendered card in an `<a href={{entry.id}}>` overlay.** The
+overlay pattern keeps the underlying card render natural (no height-100%
+chain through component chrome) and just adds a transparent click target on
+top:
+
+```gts
+<@context.searchResultsComponent @query={{this.q}} as |results|>
+  {{#each results.entries key='id' as |entry|}}
+    <li class='project-cell'>
+      <entry.component class='project-card-inner' />
+      <a class='card-link' href={{entry.id}} aria-label='Open card'></a>
+    </li>
+  {{/each}}
+</@context.searchResultsComponent>
+```
+
+CSS:
+
+```css
+.project-cell {
+  position: relative;
+  transition:
+    transform 120ms ease,
+    box-shadow 120ms ease;
+}
+.project-cell:hover {
+  transform: translateY(-2px);
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.1);
+}
+.card-link {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  display: block;
+  text-decoration: none;
+  color: transparent;
+  cursor: pointer;
+  border-radius: 2px;
+}
+.card-link:focus-visible {
+  outline: 2px solid var(--primary);
+  outline-offset: 3px;
+}
+```
+
+### Why overlay, not wrap
+
+The first instinct is to wrap the card: `<a><entry.component /></a>`. That
+breaks fitted cards because the anchor needs
+`display: block; height: 100%; width: 100%;` and the height-100% chain has
+to propagate through the component's outer chrome (`boxel-card-container`).
+The chain breaks silently and the rendered card collapses to zero height.
+Use the overlay pattern.
+
+### The mode matrix
+
+| Mode                         | What enables click                                            | Mechanism                                       |
+| ---------------------------- | ------------------------------------------------------------- | ----------------------------------------------- |
+| **Interact / Code** (in-app) | `{{@context.cardComponentModifier ...}}` on a `CardContainer` | Pushes the card onto the Boxel app's card stack |
+| **Host** (published site)    | `<a href={{entry.id}}>` overlay                               | Plain browser navigation to the card's URL      |
+
+Complementary, not redundant. An app card that publishes AND is browsable
+in-app can stack both: the overlay anchor for Host clicks, the modifier on
+the inner CardContainer for in-app push. The anchor is inert in Interact
+mode (no navigation pane); the modifier is inert in Host (no Boxel app
+running).
+
+### Verification
+
+In Host mode, open dev tools, inspect a rendered tile. Look for an
+`<a href="https://.../<Type>/<slug>">` ancestor of the card's root element.
+If the only ancestors are `<li>` / `<div>`, the tile won't navigate. The
+`cards-grid` example in `boxel-catalog` (`components/grid.gts`) does NOT
+include this wrap — it's designed for Interact mode only. Don't copy from
+there directly for published-site app cards.
+
+## Advanced live-surface notes (from dashboard work)
+
+- **Counts without hydration:** KPI/funnel numbers via `page: { size: 1 }`
+  on the wire query + `results.meta.page.total` — one row of HTML, full
+  count.
+- **`@cached` the wire-query getters** so SearchResults keeps ONE live
+  subscription per section instead of resubscribing on every re-render.
+- **`@mode='none'`** keeps results on prerendered HTML (no hover
+  hydration) — right for dashboards; `@mode='hover'` for browsable grids.
+- **Tile clicks in monitor-style cards:** use
+  `this.args.viewCard(url, 'isolated', { openCardInRightMostStack: true })`
+  — never `<a href>` (full-page navigation drops the surface).
+- **Churn warning:** live sections re-run on EVERY realm index change. A
+  realm that is being written every few seconds (sync loops, log writers)
+  makes every section flash its loading state continuously — keep
+  high-frequency writers out of the realm the dashboard watches, and prefer
+  showing stale results over a loading state during revalidation.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/live-activity-feed-card.md b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/live-activity-feed-card.md
new file mode 100644
index 00000000000..2eece4e5dff
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-live-surfaces/references/live-activity-feed-card.md
@@ -0,0 +1,52 @@
+# live-activity-feed-card — A "more alive" activity/log card
+
+**What this gives you:** the working recipe for a live activity feed —
+status-gated motion, ticking clocks, append-only entries with per-entry
+linked cards/images, newest-first display. Proven live as a software-factory
+run-log live blog card.
+
+## The five load-bearing moves
+
+1. **Append-only `containsMany(EntryFieldDef)` with per-entry `linksTo`,
+   newest-first via CSS.** Entries append (stable `entries.N.card` /
+   `entries.N.image` indexed relationship keys); the template renders
+   `{{#each @fields.entries as |Entry|}}<Entry />{{/each}}` inside a
+   `display:flex; flex-direction:column-reverse` container. **NEVER
+   prepend** — index shifts rewrite every existing relationship key.
+   Never use the plural-field wrapper (`<@fields.entries />`) — it defeats
+   the reversal. `justify-content: flex-end` pins content to the visual
+   top when the container is taller than the feed. DOM-first children
+   render at the visual BOTTOM — put a static intro/explainer block before
+   the `{{#each}}` and it becomes the story's start.
+2. **All motion gated on a status attribute.**
+   `data-status={{@model.status}}` on the root; scan line / pulse /
+   arrival-wash CSS only under `[data-status='running']` (plus
+   `{{#if this.running}}` for extra DOM like a throbber). The card visibly
+   "goes quiet" when the run ends. Vocabulary: `softpulse` 2s opacity,
+   `scan` 2.4s gradient sweep (background-size 200% + background-position
+   keyframes), one-shot `animation: arrive 3s ease-out 1` on
+   `.feed > :last-child` (DOM-last = newest).
+3. **Ticking clocks**: `@tracked nowMs = Date.now()` + `setInterval` in the
+   component constructor + `registerDestructor(this, () =>
+clearInterval(...))`. Elapsed label derives from `startedAt` vs `nowMs`
+   while running, frozen at the last entry's timestamp when done. Per-entry
+   relative labels ("3m ago") use a 30s interval per entry component.
+4. **One `linksTo`, three renders.** The same `card` field renders
+   `@format='embedded'` for payoff moments (ship it!), a sized
+   `@format='fitted'` frame (~460×92, parent owns the box) for reference
+   moments, and `@format='atom'` chips for compact detail links — pick per
+   entry kind. Parent owns all chrome via `:deep(.boxel-card-container)`.
+   Entry images: `image = linksTo(() => FileDef)` — NEVER CardDef-typed.
+5. **CSS-only equalizer throbber**: three `<i>` bars, staggered
+   `animation-delay`, `scaleY` keyframes — reads as "working" next to the
+   NOW item without JS.
+
+Entry FieldDef shape that worked: `kind` (drives glyph + chip color via
+`data-kind`), `at` (DatetimeField), `who` (voice: orchestrator / executor /
+operator), `headline`, `body` (MarkdownField), `imageUrl` fallback +
+`image`/`card` links.
+
+**Writer-side caveat** (if an external process appends): the
+`/_atomic?waitForIndex=true` sync path strips containsMany FieldDef data —
+raw-write the instance (plain file write of the full JSON) after every such
+sync.
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/SKILL.md b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/SKILL.md
new file mode 100644
index 00000000000..45d72a1543e
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/SKILL.md
@@ -0,0 +1,112 @@
+---
+name: boxel-runtime-surfaces
+description: Map of everything Boxel card code can reach — base card-api, host tools, boxel-ui components/helpers, runtime-common, CardContext, AI services, BFM. Use when writing card code that needs an import you don't know the path for, or before reaching for raw fetch / a CDN / a hand-rolled capability.
+---
+
+# Boxel Runtime Surfaces
+
+Every capability a card (`.gts`) can reach, and where its import comes from.
+Before hand-rolling anything or importing from a CDN, check whether one of
+these surfaces already provides it.
+
+Two on-demand references carry the full detail:
+
+- `references/libraries.md` — the import-path catalogue (exact `import` lines per symbol).
+- `references/integration-surfaces.md` — the capability cheatsheet (what each surface lets you DO, plus realm-server endpoints, BFM features, and boxel-cli).
+
+## The capability groups
+
+### 1. Base card API (URL-pinned, always available)
+
+`https://cardstack.com/base/<module>` — `card-api` provides `CardDef`,
+`FieldDef`, `Component`, `field`, `contains`, `containsMany`, `linksTo`,
+`linksToMany`, plus the `realmURL` Symbol on models. Field types each live in
+their own module (`string`, `number`, `boolean`, `date`, `datetime`,
+`markdown`, `enum`, `color`, `url`, `email`, …). File-backed fields
+(`FileDef`, `ImageDef`, `PngDef`, `MarkdownDef`, `CsvFileDef`, …) come from
+the `*-file-def` modules and are used via `linksTo`. Base field modules are
+**default exports** (`import StringField from 'https://cardstack.com/base/string'`).
+
+### 2. Runtime APIs — `@cardstack/runtime-common`
+
+`getCards`, `getCard`, `Command`, `Query`/`Sort`/`TypedFilter` types,
+`codeRef()`, the `realmURL` Symbol (import it — **never**
+`Symbol.for('realmURL')`), `searchEntryWireQueryFromQuery` +
+`SearchEntryWireQuery` (the wire-query builder for
+`@context.searchResultsComponent`), JSON:API relationship helpers, logging.
+
+### 3. Host tools — `@cardstack/boxel-host/tools/<kebab-name>`
+
+Default-export `Command` classes, only available inside the running app:
+search-cards, save-card, patch-fields, show-card, switch-submode, ai-assistant,
+one-shot-llm-request, send-request-via-proxy, authed-fetch, write-binary-file,
+reindexing controls, catalog/listing operations, and more.
+
+> **Path rule:** the import root is `tools/`. The pre-rename
+> `@cardstack/boxel-host/commands/…` path NO LONGER EXISTS — imports of it
+> pass every static gate (lint, schema probe, evaluate, indexing) and fail
+> only when a user triggers the code path in the browser. LLMs trained
+> before the rename write `commands/` — correct it on sight.
+
+### 4. UI kit — `@cardstack/boxel-ui`
+
+- `/components` — `Button`, `Pill`, `Avatar`, `BoxelInput`, `BoxelSelect`,
+  `CardContainer`, `Modal`, `Drawer`, `Toast`, `FieldContainer`,
+  `KanbanPlane` (+ drag/drop helpers), and more.
+- `/helpers` — logic (`eq`, `cn`, `gt`, `and`, `or`, …), formatters
+  (`formatDateTime`, `formatNumber`, `formatCurrency`,
+  `formatRelativeTime`, …), `markdownEscape`.
+- `/icons/<name>` — curated icon set; broader set at `@cardstack/boxel-icons/<name>`.
+
+### 5. CardContext — `@context` in templates
+
+The host injects a context into every card component:
+`@context.searchResultsComponent` (live result lists — see the
+`boxel-live-surfaces` skill), `@context.cardComponentModifier` (makes
+rendered tiles clickable in-app), and a `commandContext` for running host
+commands from card code. Data access from card code goes through the
+store APIs (`getCard`, `getCards`, store search) — these carry the user's
+authenticated session; raw `fetch()` does not.
+
+### 6. AI services
+
+- **One-shot LLM** — `OneShotLlmRequestCommand`
+  (`tools/one-shot-llm-request`): single LLM call, no conversation, routed
+  through the host's OpenRouter credentials.
+- **Multi-turn** — `UseAiAssistantCommand` (`tools/ai-assistant`): opens an
+  AI room with a Skill card pre-loaded.
+- **Image generation** — `SendRequestViaProxyCommand` against
+  `https://openrouter.ai/api/v1/chat/completions` with
+  `modalities: ['image', 'text']`; default model
+  `google/gemini-2.5-flash-image`. Persist returned data-URL bytes with
+  `WriteBinaryFileCommand`, then link an `ImageDef`/`PngDef` — never inline
+  base64 into card JSON.
+- **Generic HTTP** — `SendRequestViaProxyCommand` (`/_request-forward` on
+  the realm server) for any external API; credentials are handled host-side.
+
+### 7. BFM — Boxel Flavored Markdown
+
+`MarkdownField` values render as rich markdown: CommonMark + GFM, plus card
+directives (`:card[<url>]` inline, `::card[<url>]` block), mermaid, LaTeX
+math, fenced data renderers (`csv`, `kanban`, `excalidraw`, `geojson`, …),
+and computed renderers (`toc`, `tasks`, `backlinks`, …). Spec:
+[bfm.boxel.site](https://bfm.boxel.site).
+
+### 8. ESM CDN (last resort for third-party libs)
+
+`https://esm.run/<pkg>` / `https://esm.sh/<pkg>` for libraries not covered
+above (Three.js, Leaflet, Tone.js, …). URL-pin the version and document it
+in a comment — there is no reproducible build.
+
+## Quick triage
+
+| I need to…                                            | Reach for                                                                |
+| ----------------------------------------------------- | ------------------------------------------------------------------------ |
+| Define schema / fields                                | Base card API (§1)                                                       |
+| Query or load cards from card code                    | CardContext store APIs / `getCards` (§2, §5) — never raw fetch           |
+| Run an app-level action (save, show, search, reindex) | Host tools (§3)                                                          |
+| Build UI                                              | boxel-ui (§4) + Glimmer/Ember primitives (see references/libraries.md)   |
+| Live, self-updating card lists                        | `@context.searchResultsComponent` — load the `boxel-live-surfaces` skill |
+| Call an LLM / generate an image / hit an external API | AI services (§6)                                                         |
+| Rich text content                                     | BFM (§7)                                                                 |
+| A third-party JS library                              | ESM CDN (§8), pinned                                                     |
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/integration-surfaces.md b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/integration-surfaces.md
new file mode 100644
index 00000000000..2d03256d961
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/integration-surfaces.md
@@ -0,0 +1,356 @@
+# Boxel Integration Surfaces — Cheatsheet
+
+Every place a Boxel card can reach for capability. Use this as a lookup when
+planning a build; load only the sections that match the task.
+
+> **Companion doc:** `libraries.md` covers import-path mechanics in more
+> detail. This file covers the _capability_ dimension — what each surface
+> lets you DO.
+
+---
+
+## 1. Base Card APIs (URL-pinned)
+
+The Boxel base realm. Always available. Imports live at
+`https://cardstack.com/base/<name>`.
+
+| Module                                                                                                                   | Provides                                                                                                                           | Use for                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `card-api`                                                                                                               | `CardDef`, `FieldDef`, `Component`, `Box`, `field`, `contains`, `containsMany`, `linksTo`, `linksToMany`, `instanceOf`, `realmURL` | Every CardDef and FieldDef in the system.                                                                |
+| `string`                                                                                                                 | `StringField`                                                                                                                      | Plain text.                                                                                              |
+| `number`                                                                                                                 | `NumberField`                                                                                                                      | Numeric values.                                                                                          |
+| `boolean`                                                                                                                | `BooleanField`                                                                                                                     | True/false.                                                                                              |
+| `date`                                                                                                                   | `DateField` (+ `date/year` for year-only)                                                                                          | Calendar dates.                                                                                          |
+| `datetime`                                                                                                               | `DatetimeField`                                                                                                                    | Date + time.                                                                                             |
+| `date-range-field`                                                                                                       | `DateRangeField`                                                                                                                   | Spans.                                                                                                   |
+| `email`                                                                                                                  | `EmailField`                                                                                                                       | Validated email.                                                                                         |
+| `url`                                                                                                                    | `UrlField`                                                                                                                         | Validated URLs (used by AI services for image refs).                                                     |
+| `markdown`                                                                                                               | `MarkdownField`                                                                                                                    | Rich markdown content (BFM) — renders as HTML in templates.                                              |
+| `rich-markdown`                                                                                                          | Variants of MarkdownField                                                                                                          | Extended BFM rendering.                                                                                  |
+| `enum`                                                                                                                   | `EnumField` and helpers                                                                                                            | Constrained-value dropdowns.                                                                             |
+| `color`                                                                                                                  | `ColorField`                                                                                                                       | CSS color values.                                                                                        |
+| `currency`                                                                                                               | `CurrencyField`                                                                                                                    | Currency codes (ISO).                                                                                    |
+| `amount-with-currency`                                                                                                   | Compound currency-typed amount                                                                                                     | Money values.                                                                                            |
+| `code-ref`                                                                                                               | `CodeRefField`, `AbsoluteCodeRefField`                                                                                             | References to other CardDefs/FieldDefs.                                                                  |
+| `image`                                                                                                                  | `ImageCard` (CardDef base)                                                                                                         | Image card base for custom image-card schemas. Prefer FileDef subtypes for stored media files.           |
+| `base64-image`                                                                                                           | `Base64ImageField` (legacy — avoid)                                                                                                | Inlined base64 image. **Don't use for new cards** — embeds binary in JSON. Use FileDef subtypes instead. |
+| `image-file-def`, `png-image-def`, `svg-image-def`, `gif-image-def`, `webp-image-def`, `avif-image-def`, `jpg-image-def` | `ImageDef`, `PngDef`, etc.                                                                                                         | File-backed image fields (use `linksTo`).                                                                |
+| `markdown-file-def`                                                                                                      | `MarkdownDef`                                                                                                                      | File-backed markdown asset (different from MarkdownField — that's a value, this is a file).              |
+| `text-file-def`, `ts-file-def`, `gts-file-def`, `json-file-def`, `csv-file-def`                                          | File-backed text-format assets                                                                                                     | Linked file assets.                                                                                      |
+| `file-api`                                                                                                               | `FileDef`                                                                                                                          | Generic file-backed field base.                                                                          |
+| `shared-state`                                                                                                           | `sharedState()`                                                                                                                    | Cross-component reactive state.                                                                          |
+| `skill`, `skill-plus`, `skill-set`                                                                                       | `Skill`, `SkillPlusMarkdown`, `SkillSet`, `SkillReference`                                                                         | Boxel skill cards.                                                                                       |
+| `spec`                                                                                                                   | `Spec`                                                                                                                             | Card/Field/App/Skill/Command specs.                                                                      |
+| `system-card`                                                                                                            | `SystemCard` and members                                                                                                           | System-level cards (model configuration, realm metas).                                                   |
+| `resources/command-data`                                                                                                 | `commandData<T>(this, CommandClass)`                                                                                               | Reactive resource that calls a host command.                                                             |
+| `command`                                                                                                                | `GetAllRealmMetasResult`, `RealmMetaField`, `ListingInstallInput`, etc.                                                            | Type definitions for host command results.                                                               |
+| `commands/search-card-result`                                                                                            | Result types                                                                                                                       | For search command typing.                                                                               |
+
+---
+
+## 2. Runtime APIs (`@cardstack/runtime-common`)
+
+The shared runtime layer. Available in any `.gts` or `.ts` in the realm.
+
+| Symbol                                                    | Use for                                                                                                                                                                                   |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Command<TInput, TResult>`                                | Base class for new Commands.                                                                                                                                                              |
+| `getCards`, `getCard`                                     | Query the realm for cards by filter.                                                                                                                                                      |
+| `getField`, `getFieldIcon`, `cardDefComputedFields`       | Field metadata for generic rendering.                                                                                                                                                     |
+| `searchResultsComponent`                                  | Preferred result-list surface for new work — the `<SearchResults>` component, used via `@context.searchResultsComponent` (entry-rooted query built with `searchEntryWireQueryFromQuery`). |
+| `prerenderedCardSearchComponent`                          | Older card-grid surface (via `@context.prerenderedCardSearchComponent`), superseded by `searchResultsComponent`.                                                                          |
+| `searchEntryWireQueryFromQuery`, `SearchEntryWireQuery`   | Build the entry-rooted query that `@context.searchResultsComponent` takes, from an ordinary `Query`.                                                                                      |
+| `getMenuItems`, `GetMenuItemParams`                       | Typed menu construction.                                                                                                                                                                  |
+| `baseRRI('<module>')`                                     | Canonical base-realm module URL.                                                                                                                                                          |
+| `Query`, `Sort`, `TypedFilter`                            | Query type primitives.                                                                                                                                                                    |
+| `ResolvedCodeRef`                                         | Strongly-typed code references.                                                                                                                                                           |
+| `Relationship`, `extractRelationshipIds`                  | JSON:API relationship helpers.                                                                                                                                                            |
+| `planModuleInstall`, `planInstanceInstall`, `PlanBuilder` | Atomic-install planning.                                                                                                                                                                  |
+| `isCardInstance`                                          | Type guard for command inputs.                                                                                                                                                            |
+| `logger('namespace:operation')`                           | Realm-side structured logging.                                                                                                                                                            |
+| `join`                                                    | URL join helper.                                                                                                                                                                          |
+| `loadCommandModule`, `CommandContext`, `Loader`           | Command-loading internals.                                                                                                                                                                |
+| `baseRealm`, `devSkillLocalPath`, `envSkillLocalPath`     | Base-realm constants.                                                                                                                                                                     |
+
+---
+
+## 3. Host Tools (`@cardstack/boxel-host/tools/<name>`)
+
+Available only inside the running Boxel app. Each is a default-export
+`Command` class.
+
+**Live audit:** verify tool names against the Boxel monorepo's
+`packages/host/app/tools/index.ts` shim list. `write-binary-file`,
+`screenshot-card`, and `generate-thumbnail` are present in current mainline;
+if something looks "missing," check the freshness of the checkout you
+audited before concluding the tool isn't live.
+
+| Path                                                                                                                    | Purpose                                                                                                                     |
+| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `ai-assistant`                                                                                                          | Open the AI room with a skill card + attached cards (the canonical "ask AI" recipe).                                        |
+| `create-ai-assistant-room`, `open-ai-assistant-room`, `send-ai-assistant-message`                                       | Lower-level AI room lifecycle primitives used by the host UI. Prefer `ai-assistant` unless you are matching app behavior.   |
+| `one-shot-llm-request`                                                                                                  | Single LLM call, no conversation. Routes via OpenRouter.                                                                    |
+| `set-active-llm`                                                                                                        | Pin the LLM model for the next conversation.                                                                                |
+| `sync-openrouter-models`                                                                                                | Refresh OpenRouter model cards into the configured OpenRouter realm.                                                        |
+| `send-request-via-proxy`                                                                                                | Arbitrary HTTP through the realm proxy (credentials handled host-side).                                                     |
+| `authed-fetch`                                                                                                          | Host-side fetch wrapper with authenticated realm access.                                                                    |
+| `save-card`                                                                                                             | Persist a CardDef instance to a realm.                                                                                      |
+| `patch-fields`                                                                                                          | Surgical field updates on an instance (requires approval).                                                                  |
+| `patch-card-instance`                                                                                                   | Full-card replace (use sparingly).                                                                                          |
+| `apply-markdown-edit`                                                                                                   | Targeted edits in long markdown fields (requires approval).                                                                 |
+| `write-text-file`                                                                                                       | Write a `.json` instance (requires approval). **Never use for `.gts`** — UI freezes.                                        |
+| `copy-card`, `copy-source`, `copy-file-to-realm`                                                                        | Duplicate a card, source file, or FileDef-backed asset (requires approval where applicable).                                |
+| `transform-cards`                                                                                                       | Bulk command-applied transform (requires approval).                                                                         |
+| `read-file-for-ai-assistant`, `read-card-for-ai-assistant`                                                              | Load file or card content into context.                                                                                     |
+| `search-cards`                                                                                                          | `SearchCardsByQueryCommand` (advanced) and `SearchCardsByTypeAndTitleCommand` (simple).                                     |
+| `search-google-images`                                                                                                  | Google Custom Search image lookup through `send-request-via-proxy`; returns image/result metadata, not a stored realm file. |
+| `search-and-choose`                                                                                                     | Search cards, ask the LLM to choose numbered options, and return selected ids/cards. Used by listing flows.                 |
+| `switch-submode`                                                                                                        | Toggle interact/code modes, create-file mode.                                                                               |
+| `show-card`, `show-file`                                                                                                | Display a card or source file in the current submode.                                                                       |
+| `preview-format`                                                                                                        | Open module + card preview side-by-side (code mode).                                                                        |
+| `update-code-path-with-selection`                                                                                       | Navigate the code editor.                                                                                                   |
+| `open-workspace`                                                                                                        | Switch workspace by URL.                                                                                                    |
+| `update-room-skills`                                                                                                    | Activate / deactivate skills in the AI room.                                                                                |
+| `execute-atomic-operations`                                                                                             | Run a transactional plan (used by listing-install).                                                                         |
+| `fetch-card-json`, `get-card`, `read-source`, `serialize-card`, `validate-realm`                                        | Realm-server primitives.                                                                                                    |
+| `get-card-type-schema`                                                                                                  | Introspect a CardDef's field shape.                                                                                         |
+| `get-all-realm-metas`, `get-available-realm-urls`, `get-default-writable-realm`                                         | Realm metadata and writable-realm discovery.                                                                                |
+| `get-catalog-realm-urls`, `get-realm-of-url`, `can-read-realm`                                                          | Catalog/realm lookups and access checks.                                                                                    |
+| `store-add`                                                                                                             | Add a card to the store.                                                                                                    |
+| `listing-create`, `listing-install`, `listing-remix`, `listing-use`, `listing-generate-example`, `listing-update-specs` | Catalog operations.                                                                                                         |
+| `listing-action-build`, `listing-action-init`                                                                           | Listing workflow setup/build actions.                                                                                       |
+| `create-and-open-submission-workflow-card`, `create-submission-workflow`                                                | Catalog submission flow.                                                                                                    |
+| `generate-example-cards`, `populate-with-sample-data`, `generate-readme-spec`, `generate-theme-example`                 | Code-mode/sample-data helpers used by app workflows. Treat as app affordances, not portable card patterns.                  |
+| `get-user-system-card`, `set-user-system-card`, `summarize-session`                                                     | User/system-card and session helper commands.                                                                               |
+| `reindex-realm`, `full-reindex-realm`, `cancel-indexing-job`, `invalidate-realm-identifiers`                            | Indexing control (requires write access).                                                                                   |
+| `sanitize-module-list`                                                                                                  | Validate a module list.                                                                                                     |
+
+### Realm-server underscored endpoints (called directly when scripting)
+
+These are the HTTP endpoints the host tools map to. Useful when scripting
+via `curl` or `boxel-cli`:
+
+OpenRouter calls go through `/_request-forward` to the external
+`https://openrouter.ai/api/v1/chat/completions` URL. There is no live
+`/_openrouter/chat/completions` or `/_screenshot-card` endpoint in the
+current monorepo.
+
+| Endpoint                                                             | Method | Purpose                                                                                         |
+| -------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
+| `/_federated-search`                                                 | QUERY  | Cross-realm search (used by `boxel search` + `SearchCardsByQueryCommand` when crossing realms). |
+| `/_federated-search-prerendered`                                     | QUERY  | Same with prerendered card results.                                                             |
+| `/_federated-info`                                                   | GET    | Cross-realm realm metadata.                                                                     |
+| `/_federated-types`                                                  | GET    | Cross-realm type info.                                                                          |
+| `/_request-forward`                                                  | POST   | Generic proxy endpoint (underlying `SendRequestViaProxyCommand`).                               |
+| `/_prerender-card`, `/_prerender-module`, `/_prerender-file-extract` | POST   | Prerenderer entry points.                                                                       |
+| `/_publish-realm`, `/_unpublish-realm`                               | POST   | Realm publishing controls.                                                                      |
+| `/_create-realm`, `/_delete-realm`                                   | POST   | Realm lifecycle.                                                                                |
+| `/_run-command`                                                      | POST   | Server-side host command execution (underlying `boxel run-command`).                            |
+| `/_realm-auth`                                                       | GET    | Realm auth metadata.                                                                            |
+| `/_queue-status`                                                     | GET    | Indexing queue state.                                                                           |
+| `/_catalog-realms`                                                   | GET    | List of catalog realms.                                                                         |
+| `/_standby`                                                          | GET    | Health check.                                                                                   |
+
+---
+
+## 4. Boxel UI (`@cardstack/boxel-ui`)
+
+UI kit. Three sub-paths.
+
+### `/components`
+
+`Button`, `BoxelButton`, `Pill`, `Avatar`, `BoxelInput`, `BoxelSelect`,
+`BoxelDropdown`, `Menu`, `ColorPalette`, `ColorPicker`, `Header`,
+`FieldContainer`, `CardContainer`, `Modal`, `Drawer`, `Toast`, `Accordion`,
+`FilterList`, `RadioInput`, `SkeletonPlaceholder`, `TabbedHeader`,
+`ViewSelector`, `ViewItem`, `BasicFitted`, `KanbanPlane`,
+`KanbanDragManager`, `KanbanColumnConfig`, `KanbanPlacement`,
+`autoPlaceKanban`, `cardsInColumn`, `kanbanColumnCount`, `resolveInsertion`.
+
+Use `KanbanPlane` for lane-based drag/drop boards instead of hand-rolled DOM
+drag code. Persist placements by stable card id + column key + sort order,
+map to `KanbanPlacement.index` only at render time, and render child cards
+through `@fields` at fitted format.
+
+### `/helpers`
+
+Logic: `eq`, `not`, `and`, `or`, `gt`, `gte`, `lt`, `lte`, `add`,
+`subtract`, `multiply`, `divide`.
+Templates: `cn` (class names), `cssVar`, `element` (dynamic tag),
+`optional`, `pick`.
+Format: `formatDateTime`, `formatNumber`, `formatCurrency`,
+`formatRelativeTime`, `formatDuration`, `formatCountdown`, `formatFileSize`,
+`formatList`, `formatNames`, `formatOrdinal`, `formatPeriod`, `formatAge`,
+`currencyFormat` (legacy), `dayjsFormat` (deprecated).
+Markdown: `markdownEscape`.
+Menus: `MenuItem`, `MenuItemOptions`.
+
+### `/icons`
+
+Boxel UI's curated icon set. Imported as
+`import IconName from '@cardstack/boxel-ui/icons/<name>'`. Also
+`@cardstack/boxel-icons/<name>` for the broader Lucide/Tabler-style set used
+in catalog.
+
+---
+
+## 5. Ember / Glimmer tools
+
+| Module                           | Provides                                                               | Notes                            |
+| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
+| `@glimmer/component`             | `GlimmerComponent` (default), `Component`                              | Class-based components.          |
+| `@glimmer/tracking`              | `tracked` decorator                                                    | Reactive state.                  |
+| `@ember/component/template-only` | `TemplateOnlyComponent<Sig>`                                           | Pure-render components.          |
+| `@ember/component`               | `setComponentTemplate`                                                 | Low-level template attachment.   |
+| `@ember/template`                | `htmlSafe`, `precompileTemplate`                                       | Safe-string + dynamic templates. |
+| `@ember/template-compilation`    | `precompileTemplate`                                                   | Compile-time templates.          |
+| `@ember/modifier`                | `on` modifier                                                          | Event listeners.                 |
+| `@ember/helper`                  | `fn`, `hash`, `array`, `get`, `concat`                                 | Template helpers.                |
+| `@ember/object`                  | `action` decorator                                                     | Method binding.                  |
+| `@ember/owner`                   | `Owner` type                                                           | Component owner.                 |
+| `@ember/service`                 | Service decorator                                                      | Ember services.                  |
+| `@ember/destroyable`             | `registerDestructor`                                                   | Lifecycle cleanup.               |
+| `ember-concurrency`              | `task`, `restartableTask`, `dropTask`, `enqueueTask`, `keepLatestTask` | Async coordination.              |
+| `ember-resources`                | `Resource`, `resource()`, `use`                                        | Reactive resources.              |
+| `ember-modifier`                 | `modifier()`                                                           | DOM-lifecycle modifiers.         |
+
+---
+
+## 6. AI services
+
+### `OneShotLlmRequestCommand` — via OpenRouter
+
+Single LLM call, no conversation. Routes through the host's OpenRouter
+credentials.
+
+Common models: `anthropic/claude-haiku-4.5`, `anthropic/claude-sonnet-4.6`,
+`openai/gpt-4.1-nano`, `openai/gpt-5`.
+
+### `UseAiAssistantCommand` — multi-turn
+
+Card kicks off an AI conversation with a Skill card pre-loaded. For
+interactive flows.
+
+Path: `@cardstack/boxel-host/tools/ai-assistant` (newer than the older
+`commands/use-ai-assistant`).
+
+### OpenRouter Image Generation
+
+Preferred image generation surface. Use `SendRequestViaProxyCommand` against
+`https://openrouter.ai/api/v1/chat/completions` with
+`modalities: ['image', 'text']`.
+
+Default to `google/gemini-2.5-flash-image`. Use ChatGPT/OpenAI image models,
+such as `openai/gpt-5.4-image-2` or `openai/gpt-5-image-mini`, when
+requested.
+
+Generated images arrive as data URLs in `choices[0].message.images`. Persist
+the bytes with `WriteBinaryFileCommand`, then link `ImageDef` / `PngDef` /
+`FileDef`.
+
+### Generated Image FileDef
+
+Write generated image bytes to the realm with `WriteBinaryFileCommand`.
+
+The command returns `fileIdentifier`; assign a new `ImageDef` / `PngDef`
+with `id`, `url`, and `sourceUrl` set to that identifier, then save the
+owning card. Legacy image-card persistence is deprecated for new work.
+
+### `SendRequestViaProxyCommand` — generic HTTP
+
+Underlying primitive for any API. Use when OneShot or a specific API recipe
+does not cover your shape.
+
+---
+
+## 7. ESM CDN libraries
+
+Direct browser ESM imports for libraries Boxel realms don't bundle.
+
+| URL pattern                                        | Use for                                                                  |
+| -------------------------------------------------- | ------------------------------------------------------------------------ |
+| `https://esm.run/three@<ver>`                      | Three.js — 3D / WebGL (also Babylon.js, raw WebGL — same modifier shape) |
+| `https://esm.sh/leaflet@<ver>`                     | Leaflet — maps                                                           |
+| `https://esm.run/chess.js@<ver>` + `cm-chessboard` | Chess engine + board                                                     |
+| `https://esm.run/tone@14`                          | Tone.js — music toolkit (synths, transports, effects)                    |
+| `https://esm.sh/<any-package>`                     | Any npm package as ESM                                                   |
+
+**Built-in audio** doesn't need a CDN: `AudioContext`, `OscillatorNode`, and
+friends live in the browser — UI sound feedback, drum machines, tone
+generators.
+
+**Trade-off:** No reproducible build. URL-pin versions and document the
+choice.
+
+---
+
+## 8. BFM (Boxel Flavored Markdown) features
+
+The dialect Boxel reads and writes. See
+[bfm.boxel.site](https://bfm.boxel.site) for the spec.
+
+### CommonMark + GFM baseline
+
+Headings, lists, code fences, tables, alerts (`> [!NOTE]`), task lists,
+strikethrough, footnotes, extended autolinks.
+
+### Boxel extensions
+
+- **Card directives** — `:card[<url>]` inline embed, `::card[<url>]` block
+  embed, `::card[<url> | size]` sized block embed.
+- **Mermaid** — ` ```mermaid ` fenced diagrams.
+- **Math** — `$...$` (inline) / `$$...$$` (block) LaTeX via KaTeX.
+- **Wiki links / embeds** — `[[name]]` and `![[name]]` (Obsidian
+  compatibility).
+- **Highlights** — `==text==`.
+- **Block references** — `^block-id`.
+- **Heading IDs** — `# Heading {#custom-id}`.
+- **Code highlighting** — Monaco for any ` ```language ` block.
+
+### Fenced renderers (data-in)
+
+- `mermaid` — diagrams.
+- `geojson`, `topojson` — maps.
+- `stl` — 3D model viewer.
+- `math` — LaTeX.
+- `csv` — auto-rendered table.
+- `slides` — markdown slide deck.
+- `excalidraw` — whiteboard.
+- `kanban` — board.
+
+### Computed renderers (data-from-document)
+
+- `toc` / `table-of-contents`.
+- `comments` — comment summary.
+- `tasks` — task rollup.
+- `backlinks`, `outlinks` — link views.
+- `graph` — connection map.
+- `tags` — tag summary.
+
+### Card layout renderers
+
+- `canvas` — JSON canvas with positioned card frames.
+- `timeline`, `gallery`, `chart`, `embed`.
+
+### Tools
+
+- `markdownEscape` from `@cardstack/boxel-ui/helpers` — escape user input.
+- `markdown-helpers` module (`@cardstack/...`) — pre-escaped formatters for
+  dates, links, images, card embeds.
+
+---
+
+## Index by intent
+
+| If you want to…                     | Look here                                                                          |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| Define a card schema                | §1 (base APIs) + §2 (runtime types)                                                |
+| Render a UI                         | §4 (Boxel UI) + §5 (Ember/Glimmer)                                                 |
+| Build a drag/drop kanban board      | §4 (`KanbanPlane`)                                                                 |
+| Add a file/image field              | §1 (FileDef subtypes)                                                              |
+| Call an LLM                         | §3 (host tools) + §6 (AI services)                                                 |
+| Generate an AI image                | §6 (OpenRouter image generation); write output bytes with `WriteBinaryFileCommand` |
+| Hit a third-party HTTP API          | §3 (`send-request-via-proxy`) + §6                                                 |
+| Embed Three.js / Leaflet / chess.js | §7 (ESM CDN)                                                                       |
+| Render or write BFM                 | §8 (BFM features)                                                                  |
+| Drive the live Boxel app            | §3 (host tools)                                                                    |
diff --git a/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/libraries.md b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/libraries.md
new file mode 100644
index 00000000000..a9094d99e28
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/boxel-runtime-surfaces/references/libraries.md
@@ -0,0 +1,241 @@
+# Available Libraries — Where Imports Come From
+
+Boxel cards (`.gts` files) can import from three portable tiers of source.
+Use this lookup to find the **current** import path for any symbol you need.
+
+---
+
+## Tier 1 — Boxel base (host-provided)
+
+URL-pinned imports from the Boxel base realm. Always available, no install.
+
+```ts
+// Core API — CardDef, FieldDef, field decorators, Component, contains, linksTo
+import {
+  CardDef,
+  FieldDef,
+  field,
+  contains,
+  containsMany,
+  linksTo,
+  linksToMany,
+  Component,
+  Box,
+} from 'https://cardstack.com/base/card-api';
+
+// Built-in field types — each in its own module (DEFAULT exports)
+import StringField from 'https://cardstack.com/base/string';
+import NumberField from 'https://cardstack.com/base/number';
+import BooleanField from 'https://cardstack.com/base/boolean';
+import DateField from 'https://cardstack.com/base/date';
+import DatetimeField from 'https://cardstack.com/base/datetime';
+import MarkdownField from 'https://cardstack.com/base/markdown';
+
+// Code reference field (for codeRef-typed values)
+import { CodeRefField } from 'https://cardstack.com/base/code-ref';
+import { AbsoluteCodeRefField } from 'https://cardstack.com/base/code-ref';
+
+// Shared state across components
+import { sharedState } from 'https://cardstack.com/base/shared-state';
+
+// Skill / SkillSet / SkillPlusMarkdown
+import { Skill, SkillReference } from 'https://cardstack.com/base/skill';
+import { SkillPlusMarkdown } from 'https://cardstack.com/base/skill-plus';
+import { SkillSet } from 'https://cardstack.com/base/skill-set';
+```
+
+---
+
+## Tier 2 — npm packages (resolved by the host)
+
+Standard Ember / Glimmer ecosystem. No special setup needed.
+
+### `@cardstack/runtime-common` — runtime APIs
+
+```ts
+import { getCards, getCard } from '@cardstack/runtime-common';
+import { getField, getFieldIcon } from '@cardstack/runtime-common';
+import { cardDefComputedFields } from '@cardstack/runtime-common';
+import { Command } from '@cardstack/runtime-common/commands';
+// Preferred result-list surface for new work — build its query with searchEntryWireQueryFromQuery,
+// then render via @context.searchResultsComponent.
+import { searchEntryWireQueryFromQuery } from '@cardstack/runtime-common';
+import type { SearchEntryWireQuery } from '@cardstack/runtime-common';
+// Older surface, superseded by the above (still available via @context.prerenderedCardSearchComponent):
+import { prerenderedCardSearchComponent } from '@cardstack/runtime-common/prerendered-card-search';
+```
+
+### `@cardstack/boxel-ui` — UI components, helpers, icons
+
+```ts
+// Components
+import {
+  Button,
+  Pill,
+  Avatar,
+  BoxelSelect,
+  ColorPalette,
+  ColorPicker,
+  Header,
+  FieldContainer,
+  CardContainer,
+  Modal,
+  Drawer,
+  Toast,
+  KanbanPlane,
+  autoPlaceKanban,
+  type KanbanColumnConfig,
+  type KanbanPlacement,
+} from '@cardstack/boxel-ui/components';
+
+// Helpers (template helpers — used as {{eq ...}}, {{cn ...}}, etc.)
+import {
+  eq,
+  cn,
+  gt,
+  gte,
+  lt,
+  lte,
+  not,
+  and,
+  or,
+  multiply,
+  add,
+} from '@cardstack/boxel-ui/helpers';
+import {
+  formatDateTime,
+  formatNumber,
+  formatCurrency,
+  formatDuration,
+  formatRelativeTime,
+} from '@cardstack/boxel-ui/helpers';
+
+// Icons (drop into templates as <IconName />)
+import IconCheck from '@cardstack/boxel-ui/icons/check';
+import IconArrowUp from '@cardstack/boxel-ui/icons/arrow-up';
+```
+
+Formatter helpers in `@cardstack/boxel-ui/helpers`: `formatDateTime`,
+`formatNumber`, `formatCurrency`, `currencyFormat` (legacy),
+`formatRelativeTime`, `formatDuration`, `formatCountdown`, `formatFileSize`,
+`formatList`, `formatNames`, `formatOrdinal`, `formatPeriod`, `formatAge`,
+`dayjsFormat` (deprecated). These are the canonical display formatters;
+older formatter libraries in catalog realms should not be treated as the
+source of truth.
+
+Kanban helpers in `@cardstack/boxel-ui/components`: `KanbanPlane`,
+`KanbanDragManager`, `KanbanColumnConfig`, `KanbanPlacement`,
+`autoPlaceKanban`, `cardsInColumn`, `kanbanColumnCount`, `resolveInsertion`.
+Use these for lane-based drag/drop boards instead of hand-rolled DOM drag
+code.
+
+### `@cardstack/boxel-host` — host-side tools (only available inside the running app)
+
+> **Path rule:** host tool imports are `@cardstack/boxel-host/tools/<kebab-name>`.
+> The pre-rename `@cardstack/boxel-host/commands/…` path NO LONGER EXISTS —
+> imports of it pass every static gate (lint, schema probe, evaluate,
+> indexing) and fail only when a user triggers the code path in the
+> browser. LLMs trained before the rename write `commands/` — correct it
+> on sight.
+
+```ts
+import UseAiAssistantCommand from '@cardstack/boxel-host/tools/ai-assistant';
+import SetActiveLLMCommand from '@cardstack/boxel-host/tools/set-active-llm';
+import SwitchSubmodeCommand from '@cardstack/boxel-host/tools/switch-submode';
+import ShowCardCommand from '@cardstack/boxel-host/tools/show-card';
+import SearchCardsByQueryCommand from '@cardstack/boxel-host/tools/search-cards';
+import SearchCardsByTypeAndTitleCommand from '@cardstack/boxel-host/tools/search-cards';
+import ReadFileForAiAssistantCommand from '@cardstack/boxel-host/tools/read-file-for-ai-assistant';
+import PatchFieldsCommand from '@cardstack/boxel-host/tools/patch-fields';
+import ApplyMarkdownEditCommand from '@cardstack/boxel-host/tools/apply-markdown-edit';
+import WriteTextFileCommand from '@cardstack/boxel-host/tools/write-text-file';
+import CopyCardCommand from '@cardstack/boxel-host/tools/copy-card';
+import CopySourceCommand from '@cardstack/boxel-host/tools/copy-source';
+import TransformCardsCommand from '@cardstack/boxel-host/tools/transform-cards';
+import UpdateRoomSkillsCommand from '@cardstack/boxel-host/tools/update-room-skills';
+import OpenWorkspaceCommand from '@cardstack/boxel-host/tools/open-workspace';
+import PreviewFormatCommand from '@cardstack/boxel-host/tools/preview-format';
+import UpdateCodePathWithSelectionCommand from '@cardstack/boxel-host/tools/update-code-path-with-selection';
+import ReindexRealmCommand from '@cardstack/boxel-host/tools/reindex-realm';
+import FullReindexRealmCommand from '@cardstack/boxel-host/tools/full-reindex-realm';
+import CancelIndexingJobCommand from '@cardstack/boxel-host/tools/cancel-indexing-job';
+import InvalidateRealmIdentifiersCommand from '@cardstack/boxel-host/tools/invalidate-realm-identifiers';
+```
+
+### Glimmer / Ember primitives
+
+```ts
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import { on } from '@ember/modifier';
+import { fn, hash, array, get, concat } from '@ember/helper';
+import { action } from '@ember/object';
+import { htmlSafe } from '@ember/template';
+import { registerDestructor } from '@ember/destroyable';
+import { setComponentTemplate } from '@ember/component';
+import { precompileTemplate } from '@ember/template-compilation';
+```
+
+### Async / Resources / Modifiers
+
+```ts
+import {
+  task,
+  restartableTask,
+  dropTask,
+  enqueueTask,
+  keepLatestTask,
+} from 'ember-concurrency';
+import { Resource, resource, use } from 'ember-resources';
+import { modifier } from 'ember-modifier';
+```
+
+### Utility
+
+```ts
+import { startCase, kebabCase, debounce, throttle, isEqual } from 'lodash';
+```
+
+---
+
+## Tier 3 — ESM CDN imports (for one-off third-party libs)
+
+When you need a library outside the above tiers, import directly from a CDN:
+
+```ts
+// esm.run (jsdelivr-backed) — recommended for stable libraries
+import * as THREE from 'https://esm.run/three';
+import { Chess } from 'https://esm.run/chess.js';
+import * as Tone from 'https://esm.run/tone@14';
+
+// esm.sh — alternative
+import L from 'https://esm.sh/leaflet@1.9.4';
+```
+
+**Trade-off:** No reproducible build — version pinning is by URL. Acceptable
+for demos and self-contained cards; document the pinned version in a comment.
+
+Audio cards can also reach for the browser's built-in `AudioContext`
+directly — no library load required (drums, tones, UI sound feedback via
+`OscillatorNode` and friends).
+
+---
+
+## Lookup index
+
+| I want to use…                                            | Tier | Import                                             |
+| --------------------------------------------------------- | ---- | -------------------------------------------------- |
+| `CardDef`, `FieldDef`, `Component`                        | 1    | `https://cardstack.com/base/card-api`              |
+| `StringField`, `NumberField`, etc.                        | 1    | `https://cardstack.com/base/<type>`                |
+| `getCards`, `Command`                                     | 2    | `@cardstack/runtime-common`                        |
+| `Button`, `Pill`, helpers, icons                          | 2    | `@cardstack/boxel-ui/{components,helpers,icons/*}` |
+| `KanbanPlane`, `KanbanPlacement`, drag/drop board helpers | 2    | `@cardstack/boxel-ui/components`                   |
+| Any host tool (`ai-assistant`, `switch-submode`, etc.)    | 2    | `@cardstack/boxel-host/tools/<name>`               |
+| `restartableTask`                                         | 2    | `ember-concurrency`                                |
+| `Resource`, `resource()`                                  | 2    | `ember-resources`                                  |
+| `modifier()`                                              | 2    | `ember-modifier`                                   |
+| `tracked`, `GlimmerComponent`                             | 2    | `@glimmer/*`                                       |
+| Three.js, chess.js, etc.                                  | 3    | `https://esm.run/<pkg>`                            |
+| Tone.js (music toolkit)                                   | 3    | `https://esm.run/tone@14` (pin major)              |
+| Raw `AudioContext` (no library)                           | n/a  | Built-in browser API                               |
diff --git a/packages/software-factory/.agents/skills-orchestrator/software-factory-operations-v2/SKILL.md b/packages/software-factory/.agents/skills-orchestrator/software-factory-operations-v2/SKILL.md
new file mode 100644
index 00000000000..0f5d4cd4894
--- /dev/null
+++ b/packages/software-factory/.agents/skills-orchestrator/software-factory-operations-v2/SKILL.md
@@ -0,0 +1,171 @@
+---
+name: software-factory-operations-v2
+description: Lean V2 factory loop — design-first workflow, on-demand skills, no tests until hardening. Use when implementing cards in a target realm through the V2 factory execution loop.
+---
+
+# Software Factory Operations (V2 — lean, design-first)
+
+You operate inside the factory execution loop. Workspace files live in a
+**local mirror of the target realm** that the orchestrator syncs back
+between iterations; your working directory is that mirror, so
+realm-relative paths (`song.gts`, `Song/one.json`) resolve directly with
+the native `Read` / `Write` / `Edit` / `Glob` / `Grep` / `Bash` tools.
+
+This skill is deliberately small. Most knowledge loads **on demand**,
+two equivalent ways:
+
+- **Files (preferred for discovery): the full skill catalog lives at
+  `.claude/skills/<name>/` in your workspace** — SKILL.md overviews plus
+  `references/*.md` deep docs. `Glob`/`Grep`/`Read` them like any
+  project: `Grep -ri 'fitted' .claude/skills` finds the doc you didn't
+  know existed. When unsure whether guidance exists for something you're
+  about to build, grep here FIRST.
+- **Tools**: `list_skills` for the catalog, `read_skill({ name })` /
+  `read_skill({ name, reference })` for targeted loads.
+
+Load what the current work touches, nothing more.
+
+## When you need X, read Y
+
+| Need                                                                                        | read_skill                                                 |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| Card/field authoring, CardDef/FieldDef syntax, formats                                      | `boxel-development` (then specific `dev-*.md` references)  |
+| Fitted-format layout rules                                                                  | `boxel-development` reference `dev-fitted-formats.md`      |
+| Theme tokens / design-system CSS                                                            | `boxel-development` reference `dev-theme-design-system.md` |
+| Search query syntax (`boxel search --query`)                                                | `boxel-api`                                                |
+| Host commands via `boxel run-command`                                                       | `boxel-command`                                            |
+| File-backed fields (images, files, csv)                                                     | `boxel-file-def`                                           |
+| Catalog Spec conventions                                                                    | `boxel-development` reference `dev-spec-usage.md`          |
+| Reusable UI components before hand-rolling any UI                                           | `boxel-ui-component-discovery`                             |
+| What card code can reach (host tools, boxel-ui, runtime-common, AI services) + import paths | `boxel-runtime-surfaces`                                   |
+| Search-driven home/app cards, `searchResultsComponent` wire-query contract, live feeds      | `boxel-live-surfaces`                                      |
+| Embedding child cards (`<@fields.X @format=… />`), format choice, container chrome          | `boxel-delegated-render-control`                           |
+| fetch/auth from card code (store APIs vs raw fetch vs request-forward proxy)                | `boxel-fetch-contexts`                                     |
+
+Host-tool imports: the authoritative catalogue is the generated
+`host-tools-import-manifest` skill already in your context — never guess
+an import path; the `imports` validation step fails phantom ones.
+
+## Required flow (design-first)
+
+1. **Ground**: inspect workspace + target realm (`boxel search` via Bash);
+   read precedent `.gts`; `read_skill` what the issue touches.
+2. **DESIGN**: write `design/<slug>.html` — plain HTML+CSS mockup with
+   hard-coded realistic sample copy showing the isolated view (mobile),
+   fitted badge/strip/card tiles, and an embedded row. Then
+   `screenshot_html({ path })`, `Read` the PNG, critique it (name the
+   defects), revise, re-screenshot. At least one full crit pass. The
+   accepted mockup is the binding spec for step 3.
+3. **BUILD**: translate the mockup into the `.gts` card (isolated +
+   embedded + fitted templates), sample instances (same data as the
+   mockup), and a Catalog Spec (`Spec/<slug>.json`, adoptsFrom
+   `https://cardstack.com/base/spec#Spec`, `linkedExamples` →
+   instances). **MANDATORY before writing any fitted template:
+   `read_skill({ name: 'boxel-development', reference:
+'dev-fitted-formats.md' })`** — it is the container-query standard
+   (host `fitted-card` container, height quanta h40→h445, FittedCard
+   component, overflow discipline). A fitted view that ignores it — one
+   layout for all sizes, a local container on the root — fails review. The Spec MUST populate its catalog-facing `title` (display
+   name) and `description` (one sentence) attributes in addition to the
+   readMe — a Spec with empty title/description renders as an unnamed
+   card in the catalog UI. Call `get_card_schema` before writing any
+   card JSON whose shape you don't know (Spec, tracker cards).
+4. **VERIFY**: `run_lint({ path })` per file, then `run_parse()`,
+   `run_evaluate()`, `run_instantiate()`. Fix what they report. These
+   return in-memory results; each one syncs your workspace to the realm
+   first. Zero-coverage passes come back as errors — never treat them
+   as green. **Never curl/HTTP-poll the realm for files you just wrote**
+   — your writes only reach the realm when a `run_*` tool syncs them;
+   a 404 from curl before that means nothing. Verify through the
+   `run_*` tools. **Prefer `{ path }`-scoped checks on the file you're
+   fixing** — whole-realm results include pre-existing failures in files
+   you didn't write; note those with `post_update` and move on, never
+   fix files outside your issue.
+5. **Done**: `signal_done()`. If validation feedback comes back, fix and
+   signal again. If truly blocked, `request_clarification({ message })`.
+6. **Review**: after your signal_done, the issue enters REVIEW — a
+   product-manager reviewer judges the rendered output. If it comes back
+   with "Review feedback (rework requested)" in your context, those are
+   the exact, complete required changes: make them with surgical
+   `Edit`s (nothing more — improvements beyond the list belong to
+   follow-up issues the reviewer files), then `signal_done` again.
+
+## Hard rules
+
+- **Live-blog with `post_update`.** The operator watches a live run-log
+  card. Post at every meaningful moment — design kickoff, what each
+  critique round found, decisions and tradeoffs, starting to code,
+  recovering from a failed check. First person, 1–3 sentences, concrete.
+  Never work silently for more than a few minutes; the commentary channel
+  is as important as the artifacts.
+- **NO `.test.gts` files.** Tests belong to a separate hardening phase
+  invoked later over artifacts that earned them. This loop ships zero
+  tests by design; do not "helpfully" add any.
+- **Media fields are links to realm files, never inline bytes.** An
+  image/file on a card is `@field x = linksTo(() => ImageDef)` (or
+  FileDef) pointing at a real file in the workspace. NEVER design a
+  field or FieldDef that stores `data:`/base64/blob strings in JSON —
+  not even a 1×1 placeholder "just for the demo." A no-media-yet
+  instance leaves the link empty and the template renders a placeholder
+  block; the field's SHAPE stays correct.
+- **Host command imports are `@cardstack/boxel-host/tools/<name>`** (e.g.
+  `tools/write-binary-file`, `tools/save-card`). There is NO
+  `@cardstack/boxel-host/commands/` path — imports from it fail only at
+  runtime, after every static gate passes.
+- **`@context.searchResultsComponent` consumes a WIRE query, not a plain
+  Query.** Build it with `searchEntryWireQueryFromQuery(query)` from
+  `@cardstack/runtime-common`, then attach `realms: [<realm url>]` (array
+  — there is no `realm` key) and the display format via
+  `filter.eq.htmlQuery = { eq: { format: 'fitted' } }`. Invoke in BLOCK
+  form (`as |results|`, iterate `results.entries`, render
+  `<entry.component />` inside a parent-sized cell). A plain Query
+  self-closed renders NOTHING, silently.
+- **Drag-and-drop intake must read `dataTransfer.items` as a fallback**
+  when `dataTransfer.files` is empty (Photos.app-style drags deliver file
+  promises), and every drop must paint visible feedback — a silent no-op
+  drop is a defect.
+- **Never write to the source realm**; all artifacts go to the target
+  realm via the workspace.
+- **Stay inside the workspace.** Native fs tools are structurally scoped
+  to it; treat `Bash` as read-only inspection (`ls`, `grep`,
+  `boxel search`, `boxel read-transpiled`) — never sync/push yourself.
+- **Issue invariants**: `description` is immutable — append progress to
+  the `comments` array instead (Read the issue JSON, append, Write back).
+  You may set `status` only to `"blocked"` or `"backlog"`; `done` /
+  `in_progress` are orchestrator-owned.
+- **Fix with `Edit`, never re-`Write` an existing file.** After a file's
+  initial `Write`, every subsequent change to it — bug fixes, check
+  failures, small revisions — MUST be a surgical `Edit` (smallest
+  search/replace span that fixes the problem). Re-emitting a whole
+  `.gts` costs 1–2 minutes of generation per attempt vs seconds for an
+  `Edit`; it is the single biggest time sink in a build turn. Only
+  re-`Write` when more than half the file is changing.
+- **Two identical check failures = stop rewriting, start reading.** If
+  the same `run_*` check fails twice with the same error on your file,
+  do NOT emit a third fix attempt on intuition — `read_skill` the
+  matching reference from the table above, diagnose against the doc,
+  then fix once with `Edit`.
+- **Decorators fail inside class EXPRESSIONS.** `@tracked` (or any
+  decorator) on a field of `static isolated = class ... {}` fails
+  `run_parse` with "Decorators are not valid here". Hoist the component
+  to a named top-level class declared ABOVE the card class
+  (`class FooIsolated extends Component<typeof Foo> { ... }` then
+  `static isolated = FooIsolated;`), and type a constructor's `owner`
+  param as `Owner` (or `any`) — `unknown` fails against Component.
+- **Write idiomatic source, never compiled output.** When an eval/
+  instantiate error cites a line/column it refers to the transpiled JS —
+  `boxel read-transpiled <path> --realm <url>` to map it back, then fix
+  the `.gts` source.
+- **Fields are an API.** Other cards compose with your card via its
+  fields, its embedded/fitted surfaces, and its linksTo graph. Name
+  fields for consumers; prefer FieldDefs for recurring shapes; keep
+  per-format content matrices in mind (what does a consumer get at each
+  size?).
+- **Stay inside your issue's declared scope — never gold-plate.** Read
+  `Knowledge Articles/build-plan.json` (how this issue fits the whole
+  build) and your issue's "In scope (this pass)" list. Deliver EXACTLY
+  that scope, polished. Items under "Deferred (second pass)" are OUT of
+  scope — they have their own pass-2 issue; building them now wastes the
+  budget and duplicates future work. Small-and-polished beats
+  broad-and-rough. If you spot something important that no pass covers,
+  note it via `post_update` — do not build it.
diff --git a/packages/software-factory/.agents/workspace-CLAUDE.md b/packages/software-factory/.agents/workspace-CLAUDE.md
new file mode 100644
index 00000000000..4667f56583a
--- /dev/null
+++ b/packages/software-factory/.agents/workspace-CLAUDE.md
@@ -0,0 +1,72 @@
+# Boxel card development — project conventions
+
+You are building Boxel cards in this workspace: a local mirror of the
+target realm. `.gts` files are card definitions (Glimmer TypeScript);
+`<Type>/<id>.json` files are card instances (JSON:API). Schema, behavior,
+and rendering live together on each card.
+
+**The full skill catalog is at `.claude/skills/<name>/`** — SKILL.md
+overviews plus `references/*.md` deep guides. When unsure whether
+guidance exists for what you're about to build, `Grep -ri <topic>
+.claude/skills` FIRST. Key deep references:
+`boxel/references/container-query-fitted-layout.md` (the fitted
+standard), `boxel/references/design-playbook.md` (mockup → tokens →
+derive formats), `boxel-ui-guidelines/references/delegated-render-control.md`
+(embedding child cards).
+
+## Conventions (binding)
+
+- **Three formats minimum.** Every CardDef ships `isolated`, `embedded`,
+  AND `fitted` templates.
+- **CQ fitted layout is mandatory for every fitted template.** Query the
+  host-provided `fitted-card` size container — never create your own
+  container on the root. Single root `.fit` grid at 100%×100%, content
+  matrix per height quantum, `minmax(0, 1fr)` body rows, `overflow:
+hidden` discipline. Prefer the `FittedCard` component from
+  `@cardstack/boxel-ui/components` for standard compositions. Read the
+  container-query-fitted-layout reference before writing fitted CSS.
+- **Theme variables only** — templates reference `var(--*)` tokens; no
+  hard-coded colors.
+- **Format choice = who owns the cell size.** `@format='embedded'` lets
+  the child decide its height (lists, feeds, rows); `@format='fitted'`
+  fills a parent-controlled box (uniform tile grids). Read
+  delegated-render-control before embedding child cards.
+- **One CardDef per file.** FieldDefs and helpers can co-locate.
+- **Override `cardTitle` when there's a primary field**: respect
+  `cardInfo.name` first, then the primary field, then
+  `Untitled <DisplayName>`.
+- **Include `attributes.cardInfo` on instances** (even all-null) so
+  name/summary/theme stay user-editable.
+- **Fields are an API.** Other cards compose via your fields, embedded/
+  fitted surfaces, and linksTo graph — name fields for consumers, prefer
+  FieldDefs for recurring shapes.
+
+## Cardinal rules (silent-failure traps — violations pass lint, then break)
+
+- **`DateField` value = `YYYY-MM-DD` (no `T`); `DateTimeField` = ISO
+  datetime with `T`.** Mismatch crashes at render. `*At` → DateTimeField;
+  `*Date`/`*On`/`dob` → DateField.
+- **Never put an external URL in `relationships.<field>.links.self`** —
+  it poisons the whole realm's indexing transaction. External images use
+  the pair pattern: `linksTo(ImageDef)` + `contains(UrlField)`.
+- **`linksToMany` JSON uses indexed top-level keys**
+  (`"items.0": { "links": { "self": "../foo" } }`), never an array.
+- **Never inline media/binary in card JSON.** No `data:`/base64/blob
+  strings in any attribute — not even a placeholder. Media fields are
+  `linksTo(FileDef/ImageDef)` pointing at a real realm file; a
+  no-media-yet instance leaves the link empty and the template renders a
+  placeholder block.
+- **Query filters: `filter: { type: ref }` selects all cards of a type;
+  a bare `{ on: ref }` only scopes predicates and silently returns
+  nothing.** Every card-owned query is realm-scoped and bounded.
+- **Base fields are default exports** in base modules; there is no
+  `ImageDef` in `/base/image`.
+
+## Working style
+
+- **Fix with `Edit`, never re-`Write` an existing file** — surgical
+  search/replace on the failing lines. Re-emitting a whole `.gts` costs
+  minutes; only re-`Write` when more than half the file changes.
+- Read before writing; keep changes scoped to the card you own.
+- Design before schema on user-facing cards: mockup with real sample
+  copy, critique, then translate (design-playbook reference).
diff --git a/packages/software-factory/docs/factory-v2-v3-overview.md b/packages/software-factory/docs/factory-v2-v3-overview.md
new file mode 100644
index 00000000000..5ee867f7225
--- /dev/null
+++ b/packages/software-factory/docs/factory-v2-v3-overview.md
@@ -0,0 +1,301 @@
+# `factory-v2-experiment` — what this branch changes vs `main`
+
+This document explains what the `factory-v2-experiment` branch adds on top of
+`main`, why, and how each piece works. It is written for a reviewer deciding
+whether/how to merge, and for anyone operating the factory who needs to know
+what changed.
+
+`main` ships the factory as originally documented in [`README.md`](../README.md):
+an issue-driven agentic loop that takes a **brief card**, bootstraps a Project +
+Issues, and builds a Boxel card family with a 5-step validation pipeline
+(parse · lint · evaluate · instantiate · test).
+
+This branch keeps that skeleton and layers on three things:
+
+1. **v2 — a lean, design-first build loop** that produces cards good enough to
+   ship, with a live "run log" the operator watches.
+2. **v3 — a control/product realm split, a GitHub-repo port flow, and
+   render-gated acceptance** so a run can start from a real app and be judged on
+   pixels, not claims.
+3. **Operational hardening** — resume-safe restarts, cheaper agent turns through
+   session reuse, a bug-fix fast path, and a run log that behaves like a real
+   activity feed.
+
+---
+
+## The aim
+
+The one-line goal: **turn "here is an app (or a brief)" into a coherent,
+inspectable Boxel card family, unattended, and let a human watch and trust the
+process.** Everything below serves one of three sub-goals:
+
+- **Quality** — cards that look designed and compose cleanly (design-first loop,
+  phase-split budgets, render gate).
+- **Trust & observability** — the operator can see, at any moment, what the
+  factory is doing and why (the run log, RunMonitor, activity entries).
+- **Robustness & cost** — a run survives interruption, doesn't redo finished
+  work, and doesn't burn tokens re-reading what it already read (resume guard,
+  session reuse, control/product split).
+
+---
+
+## Area 1 — v2: the lean, design-first build loop
+
+**What.** A `--v2` mode for `factory:go` that reorders each implementation turn
+to **design first**: the agent writes a single self-contained HTML mockup with
+realistic sample copy, screenshots it, critiques and revises it, and only then
+translates the accepted mockup into a `.gts` card. v2 also drops the QUnit/test
+requirement from the build loop (tests are a later hardening phase).
+
+**Why.** The pre-v2 loop produced schema-correct but pedestrian cards — fitted
+views drowning in chrome, weak hierarchy. Deciding the look _before_ writing
+templates, on a cheap HTML surface, is where taste lives.
+
+**How.** `issue-implement-v2` / `issue-design-v2` / `issue-build-v2` prompts; a
+`screenshot_html` tool that renders a workspace HTML file in headless Chromium
+and returns a PNG the agent then `Read`s and critiques; on-demand skill loading
+(next section) so the agent pulls only the skills an issue actually touches.
+
+### On-demand skill discovery & loading
+
+**What.** The executor agent doesn't get every skill front-loaded. It
+**discovers and loads skills as it needs them** — the same way it would in a
+`boxel-workspaces` checkout — through two complementary paths:
+
+- **MCP tools.** `list_skills` returns every available skill as name +
+  one-line summary; `read_skill` pulls one on demand. The system prompt
+  front-loads only a core set; the agent reads the rest (design, fitted
+  formats, theming, file fields, queries…) as the task touches them.
+- **Native `.claude/skills` materialization** (`workspace-skills.ts`). Before a
+  run, the factory copies its skill catalog into
+  `<workspace>/.claude/skills/<name>/` — the exact layout Claude Code and the
+  `boxel-workspaces` repo use — and drops a factory-adapted `CLAUDE.md`. With
+  `settingSources: ['project']` on the agent (`claude-code.ts`), the SDK harness
+  discovers those skills natively, so the agent can `Grep 'fitted'
+.claude/skills` and `Read` the standard it didn't know existed.
+
+**Why.** The MCP `read_skill` path is a bespoke lookup the model has no trained
+instinct for, and it can't _search_ across skills — so an agent can't find a
+standard it doesn't already know the name of. That is the unknown-unknown
+failure mode that shipped a non-standard fitted view (wardrobe, 2026-07-17).
+Models are heavily conditioned to explore `.claude/*` with native Glob/Grep/Read;
+putting the catalog on disk leans into that instinct instead of fighting it. The
+realm sync skips every dotfile/dotdir, so `.claude/` never reaches the realm, and
+the `read_skill` tool stays available for backends that don't do native
+discovery.
+
+## Area 2 — the run log (live activity feed)
+
+The run log is a Boxel card in the realm that the operator opens to watch a run
+unfold. It went through the largest evolution on this branch.
+
+**What & why.** A live "blog" of the run — every milestone (design round,
+validation, card shipped, issue picked/done), the agent's own `post_update`
+commentary, and orchestrator narration — streamed onto a card as it happens, so
+a long agent turn never leaves the operator staring at silence.
+
+**How it works now (the current model):**
+
+- **Query-backed Posts, not a `containsMany` array.** Each entry is its own
+  `RunLogEntry` card; the isolated view is a `@context.searchResultsComponent`
+  query (`sort seq desc`), and count tiles are `page:{size:1}` queries reading
+  `results.meta.page.total`. This stops run-log churn from invalidating the
+  product realm's index and scales past the array model's limits.
+- **Reveal-on-scroll feed** (the `workspace.gts` activity-feed pattern): one
+  100-cap query, the template reveals 20 rows at a time as a bottom
+  `IntersectionObserver` sentinel scrolls into view — light initial DOM, no
+  re-query per reveal.
+- **Non-shifting live updates.** New entries arrive at the head of a live run;
+  rendering them would shove the reader's content down. Instead they are
+  _buffered_ (held out of the DOM) behind a subtle sticky "↑ N new" pill and
+  only revealed on click (or automatically when the reader is already at the
+  top). Because buffered entries are never rendered, nothing on screen moves.
+- **Comment + status-change entries.** In the `containsMany` days, issue
+  comments and status transitions were just pushed onto the array. The query
+  model's equivalent is to **emit one `RunLogEntry` per event** — so agent
+  comments (`post_update`), orchestrator/reviewer comments (`emitComment`), and
+  every state transition (`emitStatusChange`, plus the bespoke `issue-picked` /
+  `issue-done` / `blocked` milestones) show in the feed. Status _history_ has to
+  be captured at emit time because the Issue card stores only its current
+  status.
+- **Rich links.** `post_update` bodies render as Boxel Flavored Markdown; the
+  agent references a card by its workspace path and picks the form (inline atom
+  `:card[…]`, embedded `::card[…]`, or a sized `fitted` tile), and the run log
+  resolves the path to a live card URL with the right (control vs product) realm
+  routing. Entries link their issue via a light atom chip.
+- **Durable design history.** HTML mockups the agent writes to scratch `design/`
+  are copied into `design-history/` alongside the flattened PNG, so a run-log
+  entry's image link survives the agent tidying up `design/`.
+
+## Area 3 — per-turn model/effort budget + phase-split
+
+**What.** An orchestrator-owned policy that assigns a model + reasoning-effort
+budget per turn _type_, and a phase-split that runs the DESIGN turn on the
+flagship model and the BUILD (translation) turn on a cheaper one, forked from
+the design session.
+
+**Why.** Taste work (design) deserves the strong model; mechanical translation
+and later fix iterations don't. Spending flagship tokens on every turn is waste.
+
+**How.** `modelPolicy` (bootstrap / build / fix budgets); on iteration 1 of a
+non-meta issue, a DESIGN turn then a BUILD turn that resumes the design turn's
+session so the accepted design carries over without re-reading.
+
+## Area 4 — context forking & inner-loop session reuse
+
+**What.** A run primes one session (skills + design language + precedent) and
+**forks** it for every implementation turn, so the expensive static context is
+read once and served from the provider prompt cache. On top of that, the inner
+fix loop **chains**: after iteration 1, a fix turn resumes the _prior
+iteration's_ session instead of re-forking prime.
+
+**Why.** Two different wins. Forking prime shares the cached static prefix.
+Chaining keeps the _working_ files the agent already read in context, so a fix
+iteration is "here's what validation flagged, fix it" — no re-read, no
+re-orient. That was the dominant cost in the 3–4-minute fix turns.
+
+**How.** `decideSessionStrategy` makes the call per turn: **continue** the prior
+session while the fix is converging; go **fresh** (re-fork prime) when the same
+failure repeats with no progress, or after a chain-length cap — bounding context
+growth, anchoring risk, and keeping the resumed prefix inside the cache window.
+Progress is measured by a `failureFingerprint` (which validation steps failed +
+total error count).
+
+## Area 5 — v3: control/product realm split
+
+**What.** With `--control-realm`, one local workspace syncs to **two** realms:
+the **product** realm (the built cards — the deliverable) and the **control**
+realm (issues, board, knowledge, validation artifacts, and the run log).
+
+**Why.** Run-log/validation churn was invalidating the product realm's index
+(the live-surface "flashing Loading…" failure), and product `.gts` edits were
+nuking the loader under the run-log/issue cards the operator was watching.
+Separating them makes each side stable. Control-plane cards also sync via raw
+per-file writes, which never go through `/_atomic?waitForIndex=true` (a platform
+path that silently strips `containsMany` FieldDef data), so the control plane is
+structurally immune to that corruption.
+
+**How.** `control-plane-sync.ts` owns the control paths; a factory-managed
+`.boxelignore` keeps them out of the product atomic sync (and refreshes a stale
+managed block when the control-path set changes).
+
+## Area 6 — v3: GitHub-repo port flow
+
+**What.** `--repo-url` points the factory at a real GitHub app instead of a
+brief card. A **PORT-ANALYSIS** issue runs _before_ bootstrap: it clones the
+repo, reads its README/media **and its code**, and writes two Knowledge
+Articles — a product view (features, screens, flows, a "better than the
+original" rubric, proposed card-family mapping) and an engineering view
+(architecture, dependency map with Boxel-side answers, specialized logic incl.
+verbatim AI prompts, the real data model, and a ported test contract).
+Bootstrap then plans the card family from those articles.
+
+**Why.** Porting an app well means understanding how it actually works, not just
+skimming a README — including what its tests pin down and what fixtures they use.
+
+## Area 7 — v3: render gate + acceptance walkthrough
+
+**What.** After an issue ships, the orchestrator screenshots the real host
+render of the cards it produced, and a verifier turn judges every acceptance
+criterion **against the pixels** — a criterion passes only on a visible, working
+affordance. Failures are filed as `defect` issues.
+
+**Why.** "The command class exists" is not shipping a feature. Judging on real
+renders closes the gap between "code written" and "capability the user can see."
+
+## Area 8 — v3: host-import manifest gate
+
+**What.** A generated catalogue of the host tools/imports available in this
+checkout, fed to both the agent's context and a static `imports` validation
+step, so agent code can't drift from the real host contract.
+
+## Area 9 — RunMonitor (orchestrator narration)
+
+**What.** An orchestrator-side monitor that authors its own run-log entries —
+stall narration, scheduler notes, watchdog observations, and per-turn
+cost/duration telemetry — so the feed reflects orchestration decisions, not just
+the agent's voice.
+
+## Area 10 — restart & resume safety (this batch)
+
+**What.** Two fixes so a restarted run picks up where it left off instead of
+redoing finished work.
+
+- **Seed resume guard.** On restart the control realm is pulled first, so seeds
+  a prior run completed are present as `done`. The seeder now _leaves a done
+  seed intact_ when it belongs to the current brief (matched by the brief's
+  source/repo URL), instead of re-arming it to `backlog`. A changed brief still
+  re-arms (the sequential multi-brief pass). This stopped the factory from
+  re-running the PORT-ANALYSIS repo study on every restart.
+- **Authoritative-status reconciliation.** The scheduler picks from the realm
+  _index_, which lags the control-plane's raw writes. Before running a picked
+  issue, the loop re-reads its status from the authoritative local workspace
+  file (`readLocalStatus`); if the file says `done`, the index was stale — skip
+  it. A genuinely interrupted issue reads `in_progress` locally too, so real
+  resumable work is never skipped.
+
+## Area 11 — bug-fix fast path (this batch)
+
+**What.** Defect/bug issues skip the design round entirely.
+
+**Why.** A defect on a card that already shipped needs a diagnose-and-fix turn,
+not a fresh HTML-mockup-and-critique design round. A restart was observed
+running a full design round on a render-crash defect — wasted work.
+
+**How.** `isBugFixIssue` (matches `defect`/`bug`/`regression`/`hotfix`/`fix`)
+excludes the issue from the phase-split DESIGN turn and routes it to a dedicated
+`issue-fix-v2` prompt: reproduce → locate → root cause → minimal fix → verify,
+with an explicit "do NOT run a design round" instruction.
+
+## Area 12 — infrastructure hardening
+
+- **Content-hash workspace fingerprint** (`validation-run-cache.ts`). The sync
+  gate keyed on `size|mtime`; a bidirectional pull rewrites identical files with
+  a fresh mtime, so every run did full no-op syncs. Hashing file _content_
+  instead gives a stable fingerprint → unchanged content skips the sync.
+- **Per-turn agent tool telemetry** (`agent-tool-telemetry.ts`). One terse line
+  per tool call plus a per-turn waste summary (duplicate reads, whole-file
+  rewrites, screenshot thrash, mutating shell) so wasteful agent behavior is
+  visible.
+- **Transient-agent-error classification** (`transient-agent-error.ts`) so a
+  network/API blip is retried rather than failing the run.
+- **Instance discovery** (`instance-discovery.ts`) — newest product instances on
+  disk, used as a render-gate fallback when a turn wrote no instances.
+
+---
+
+## Testing
+
+Every area ships unit tests (node's test runner / QUnit). Current status of the
+touched suites, all green:
+
+| Suite                                                                                                                         | Focus                                                                        |
+| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `issue-loop`                                                                                                                  | session chaining, `decideSessionStrategy`, reconciliation, bug-fix gating    |
+| `factory-seed`                                                                                                                | resume guard (fresh / same-brief / changed-brief)                            |
+| `issue-scheduler`                                                                                                             | `readLocalStatus`, blockedBy resolution, type filter                         |
+| `run-log`                                                                                                                     | Posts model, migration/pruning, BFM directive resolution, HTML preservation  |
+| `factory-prompt-loader`                                                                                                       | `isBugFixIssue`, fix-vs-design prompt routing                                |
+| `control-plane-sync`                                                                                                          | hash-gated push, selective pull, stale-block refresh (run via `node --test`) |
+| `validation-run-cache`                                                                                                        | content-hash fingerprint stability                                           |
+| `workspace-skills`                                                                                                            | `.claude/skills` materialization + factory `CLAUDE.md`                       |
+| `agent-tool-telemetry`, `instance-discovery`, `transient-agent-error`, `factory-context-builder`, `factory-agent-claude-code` | supporting infra                                                             |
+
+Note: `control-plane-sync.test.ts` uses the `node:test` runner; run it with
+`node --test` (running it under the qunit harness reports a spurious global
+failure while node:test reports pass).
+
+## Where things live
+
+| Concern                                                                   | File(s)                                                                                 |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Loop, phase-split, session reuse, bug-fix gating, comment/status emit     | `src/issue-loop.ts`                                                                     |
+| Prompt routing, `isBugFixIssue`                                           | `src/factory-prompt-loader.ts`, `prompts/*`                                             |
+| Seed resume guard                                                         | `src/factory-seed.ts`                                                                   |
+| Scheduler, `readLocalStatus`                                              | `src/issue-scheduler.ts`                                                                |
+| Run-log card + feed + BFM resolver                                        | `src/run-log.ts`                                                                        |
+| Agent invocation, forking, caching                                        | `src/factory-agent/claude-code.ts`                                                      |
+| Tools (post_update BFM teaching, screenshot_html, list_skills/read_skill) | `src/factory-tool-builder.ts`                                                           |
+| On-demand skill discovery (`.claude/skills` materialization)              | `src/workspace-skills.ts`, `src/factory-skill-loader.ts`, `.agents/workspace-CLAUDE.md` |
+| Control/product split                                                     | `src/control-plane-sync.ts`, `src/factory-entrypoint.ts`                                |
+| Sync fingerprint                                                          | `src/validation-run-cache.ts`                                                           |
diff --git a/packages/software-factory/docs/run-trace.md b/packages/software-factory/docs/run-trace.md
new file mode 100644
index 00000000000..8c6420ee350
--- /dev/null
+++ b/packages/software-factory/docs/run-trace.md
@@ -0,0 +1,68 @@
+# Run trace — where a factory run's time goes
+
+Every `factory:go` run writes a span trace to
+`<workspace>/.factory-trace/run-<timestamp>.ndjson` (the path is printed at
+startup on the `run-trace` log channel). The file answers "where did the
+hour go" with one tagged, timed span per significant phase — the input for
+the timing visualization and for quick command-line triage.
+
+## Format
+
+NDJSON: one self-contained JSON object per line, append-only (a killed run
+keeps every span that finished — an _unclosed_ span writes nothing, so a
+crash shows up as a gap, never a fabricated duration).
+
+- header — first line: `{"v":1,"c":"run","n":"meta","t":…,` run tags
+  (`targetRealm`, `controlRealm`, `brief`, `v2`)`}`
+- span — `{"t":<epoch-ms start>,"d":<duration-ms>,"c":<category>,"n":<name>,` tags`}`
+- instant event — same, without `"d"`
+
+Nesting is recovered by interval containment (`[t, t+d]`); there are no
+begin/end pairs to match. `d` comes from the monotonic clock; `t` is
+wall-clock so lines cross-reference the debug log.
+
+## Categories (`c`) and names (`n`)
+
+| c             | n                                                                                                                  | one span per                                                                      |
+| ------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `run`         | `meta`, `issue-loop`                                                                                               | run                                                                               |
+| `startup`     | `load-brief`, `bootstrap-target-realm`, `pull-target-realm`, `pull-control-realm`                                  | run                                                                               |
+| `seed`        | `create-seed`                                                                                                      | run                                                                               |
+| `skills`      | `materialize` (run), `load` (turn)                                                                                 | —                                                                                 |
+| `manifest`    | `host-imports`                                                                                                     | run                                                                               |
+| `scheduler`   | `load-issues`, `skip-stale-done`                                                                                   | occurrence                                                                        |
+| `issue`       | issue slug                                                                                                         | outer cycle; tags `exitReason`, `iterations`, `agentMs`, `validationMs`, `syncMs` |
+| `iteration`   | issue slug                                                                                                         | inner pass; tag `iteration`                                                       |
+| `context`     | `build-for-issue`                                                                                                  | agent-context build                                                               |
+| `inference`   | turn type (`design`, `build`, `fix`, `implement`, `review`, `bootstrap`, `analysis`, `design-foundation`, `prime`) | agent turn; tags `model`, `effort`, `status`, `toolCalls`, `tokensIn`/`tokensOut` |
+| `tool`        | tool name                                                                                                          | factory MCP tool execution inside a turn                                          |
+| `sync`        | `workspace` (composite), `product`, `control`                                                                      | sync                                                                              |
+| `validation`  | `pipeline` (composite), step name (`lint`, `parse`, `evaluate`, `instantiate`, `imports`, `test`)                  | validation                                                                        |
+| `render-gate` | `capture`                                                                                                          | gate capture                                                                      |
+
+Steps inside `validation`/`pipeline` run concurrently: treat the pipeline
+span as wall-clock cost, the step spans as attribution. Same for `tool` and
+`sync` spans inside an `inference` span — tool time is part of the turn's
+wall clock, so "model thinking time" ≈ inference `d` minus contained `tool`
+spans.
+
+## Quick triage without the visualization
+
+Total per category, descending:
+
+```sh
+jq -rs 'map(select(.d)) | group_by(.c) | map({c: .[0].c, s: (map(.d) | add)}) | sort_by(-.s) | .[] | "\(.s/1000 | floor)s\t\(.c)"' run-*.ndjson
+```
+
+Ten slowest spans:
+
+```sh
+jq -rs 'map(select(.d)) | sort_by(-.d) | .[:10] | .[] | "\(.d/1000|floor)s\t\(.c)/\(.n)\t\(.issue // "")"' run-*.ndjson
+```
+
+Perfetto/chrome-tracing view (no custom viz needed):
+
+```sh
+jq -s '[.[] | select(.d) | {name: .n, cat: .c, ph: "X", ts: (.t*1000), dur: (.d*1000), pid: 1, tid: 1, args: .}]' run-*.ndjson > trace.json
+# open https://ui.perfetto.dev and load trace.json
+```
diff --git a/packages/software-factory/prompts/acceptance-walkthrough.md b/packages/software-factory/prompts/acceptance-walkthrough.md
new file mode 100644
index 00000000000..b2dfcbba8c3
--- /dev/null
+++ b/packages/software-factory/prompts/acceptance-walkthrough.md
@@ -0,0 +1,165 @@
+# Review turn — you are the product manager
+
+An agent just finished an issue and it is now IN REVIEW. You are the
+reviewer: a product manager with final say over whether this ships. You
+do NOT write or fix product code in this turn. You judge the OUTPUT with
+evidence, decide ship / send-back, and steward the backlog.
+
+# The PM heuristics (how to think)
+
+1. **Bias to ship.** Your default verdict is APPROVE. Shipped-and-
+   improvable beats blocked-and-perfect. Hold the release ONLY for:
+   a broken core flow, a schema that would corrupt data or violate a
+   cardinal rule, or output so incoherent with the brand guide it must
+   not merge. Ask: "would a good PM hold the release for this?" If not —
+   approve.
+2. **Nitpicks become backlog, not blockage.** Anything worth fixing that
+   doesn't meet the bar above → file a FOLLOW-UP ISSUE (see below) and
+   still approve. Polish is a queue, not a veto.
+3. **Send back at most ONCE, and only when it's cheap.** Request rework
+   only when an acceptance criterion is demonstrably unmet AND the fix
+   is small and precisely describable (you must say exactly what to
+   change). If this issue was already reworked once, do not bounce it
+   again — approve and file follow-ups.
+4. **Steward the backlog like a PM.** You may: adjust `priority` and
+   `order` of BACKLOG issues (never in_progress/review/done) when the
+   evidence changes what matters next; close duplicate backlog issues
+   (status `done` + a comment saying which issue supersedes them); and
+   file new issues. Explain every backlog change in a `post_update`.
+5. **Evidence over inference.** Judge from the screenshots and the
+   workspace files. Source code existing is never proof a user can do
+   something; a visible, working affordance is.
+6. **Judge against the DECLARED pass scope, not the platonic card.**
+   Read the issue's "In scope (this pass)" / "Deferred (second pass)"
+   lists and `Knowledge Articles/build-plan.json`. An explicitly
+   deferred item is NOT a gap — do not fail it, do not file a follow-up
+   duplicating an existing pass-2 issue. Hold the small scope to a HIGH
+   bar instead. You maintain the build plan: when the build's reality
+   changes what should happen next, update the build-plan KA and the
+   backlog together, and say so in a `post_update`.
+
+# The issue under review
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+
+Description (the acceptance criteria live in here):
+{{issue.description}}
+
+{{#if issue.checklist}}
+Checklist:
+{{#each issue.checklist}}
+- [ ] {{.}}
+{{/each}}
+{{/if}}
+
+# Render evidence
+
+The orchestrator captured real host-rendered screenshots of the cards
+this issue shipped ({{renderSummary}}). Read EVERY one with your native
+`Read` tool — they are PNG files in your workspace:
+
+{{#each screenshots}}
+- `{{outputPath}}` — {{cardPath}}, {{format}} format{{#if suspectBlank}} — ⚠ SUSPECTED BLANK RENDER (tiny file){{/if}}
+{{/each}}
+
+{{#if failedCaptures}}
+These surfaces FAILED to render at all (that is itself strong evidence of
+a defect — a card that errors in the prerenderer usually errors for
+users too):
+
+{{#each failedCaptures}}
+- {{cardPath}} ({{format}}): {{error}}
+{{/each}}
+{{/if}}
+
+**When NO screenshots were captured at all** ("no card surfaces were
+captured"): that is a gap in the orchestrator's capture step, NOT
+evidence about the product. Absence of screenshots never proves a card
+fails to render. Check the workspace directly — if the issue's `.gts`
+(with isolated/embedded/fitted templates) and instance JSONs exist,
+treat render-dependent criteria as unverifiable (note it) and judge the
+rest; never file a "no renderable surface" / "zero screenshots" defect.
+
+# How to judge
+
+For EACH acceptance criterion: decide what visible evidence would prove
+it, look for it in the screenshots (you may also `Read` the `.gts`,
+instance JSONs, and the brand guide / `design/tokens.css` to judge
+coherence), and verdict it PASS / FAIL / NEEDS-HUMAN-VERIFY
+(interactive/stateful criteria that a static render can't prove — never
+guess these as PASS).
+
+# What to produce
+
+1. **Post your verdict** via `post_update` (kind: `decision`): headline
+   `Review: APPROVED — <n> pass / <n> follow-ups filed` or
+   `Review: REWORK — <short reason>`, body listing each criterion with
+   its verdict and one line of evidence.
+
+2. **If (and only if) sending back**: write
+   `.factory-scratch/review-verdict.json` with your native `Write` tool:
+
+```json
+{
+  "verdict": "rework",
+  "feedback": "<numbered list of the exact, small changes required — file, template, what to change. The builder gets ONE fix pass from this text alone.>"
+}
+```
+
+   APPROVE needs no verdict file — approval is the default.
+
+3. **File follow-up issues** for improvements that shouldn't block:
+   `Issues/<product-slug>-<short-slug>.json` via `Write`. JSON:API shape:
+
+```json
+{
+  "data": {
+    "type": "card",
+    "attributes": {
+      "issueId": "<projectCode>-<N>",
+      "title": "<symptom-first title>",
+      "summary": "<same as title>",
+      "description": "<what the evidence shows vs what it should be; name the file and template to fix; reference the screenshot path>",
+      "status": "backlog",
+      "priority": "<high for real defects, medium/low for polish>",
+      "issueType": "defect",
+      "order": 99,
+      "cardInfo": { "name": "<title>" }
+    },
+{{#if project}}
+    "relationships": {
+      "project": { "links": { "self": "{{project.id}}" } }
+    },
+{{else}}
+    "relationships": {},
+{{/if}}
+    "meta": {
+      "adoptsFrom": { "module": "{{darkfactoryModuleUrl}}", "name": "Issue" }
+    }
+  }
+}
+```
+
+   **Every issue gets a sequential `issueId`.** Read the existing
+   `Issues/*.json` to find the project code (e.g. `WR`) and the highest
+   number in use, and continue the sequence — an unnumbered issue is
+   invisible in board summaries and unreferenceable in comments.
+
+   **Before filing, dedupe.** List `Issues/` and `Read` existing issues
+   for the same card. If one already covers the same root cause — in ANY
+   status, including done — do not file another (no `-v2`/`-v3`
+   variants); a done defect for the same symptom means it was addressed,
+   and re-filing creates an infinite chain. One issue per distinct root
+   cause, not per criterion.
+
+4. **Backlog adjustments** (optional, PM authority): edit `priority` /
+   `order` attributes of BACKLOG issue JSONs when your evidence changes
+   what matters next; close duplicates. Every change gets a one-line
+   `post_update` explaining why.
+
+5. **For every NEEDS-HUMAN-VERIFY**, post a `post_update` (kind:
+   `decision`) with headline `NEEDS HUMAN VERIFY: <criterion>` and a body
+   telling the operator exactly what to try and what success looks like.
+
+Call `signal_done` when your review is complete.
diff --git a/packages/software-factory/prompts/bootstrap-implement-v2.md b/packages/software-factory/prompts/bootstrap-implement-v2.md
new file mode 100644
index 00000000000..9fff1defb91
--- /dev/null
+++ b/packages/software-factory/prompts/bootstrap-implement-v2.md
@@ -0,0 +1,214 @@
+# Bootstrap: Process Brief and Create Project Artifacts
+
+You are processing a bootstrap issue. Your job is to read the brief, then
+create all the project artifacts needed to begin implementation.
+
+## Brief
+
+**Source:** {{briefUrl}}
+
+(The source is a Boxel brief card — our authored content — OR, for
+inspired-by ports, the GitHub repository itself standing in lieu of a
+wiki entry. Either way the full brief content is inlined in the issue
+description below; do NOT fetch this URL as a card. Port runs
+additionally carry the port-background and port-code-analysis Knowledge
+Articles via `relatedKnowledge` — those are the authoritative source.)
+
+## Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+
+Description:
+{{issue.description}}
+
+## What to Create
+
+Create the following artifacts in the target realm by calling the
+**`Write`** tool to produce each `.json` file. The cwd is the local
+workspace mirror of the target realm; file paths below are
+workspace-relative. Use **`Read`** / **`Glob`** to inspect existing
+state before creating anything, and **`Bash`** to shell out to
+`boxel search` if you need to query the realm. Do not describe what
+you would write — call `Write` to actually create each file.
+
+### 1. Project Card
+
+Write a Project card to `Projects/<slug>.json` where `<slug>` is derived
+from the brief title (lowercase, hyphens for spaces/punctuation).
+
+Required attributes:
+
+- `projectCode` — 2-4 uppercase letters derived from title initials (e.g., "Sticky Note" → "SN")
+- `projectName` — `"<brief title>"`
+- `projectStatus` — `"active"`
+- `objective` — brief content summary
+- `scope` — full brief content organized by sections
+- `technicalContext` — `"Generated by factory:go from brief at <briefUrl>"`
+- `successCriteria` — derived from brief section headings
+
+Relationships:
+
+- `knowledgeBase.0` → `../Knowledge Articles/<slug>-<article-slug>` (one per article)
+
+adoptsFrom: the darkfactory `Project` type.
+
+### 2. Issue Tracker Board
+
+Create one IssueTracker card at `Boards/<slug>.json`.
+
+Required attributes:
+
+- `boardTitle` — `"<brief title> Board"`
+- `hideEmptyColumns` — `false`
+
+Relationships:
+
+- `project` → `../Projects/<slug>`
+
+adoptsFrom: the darkfactory `IssueTracker` type.
+
+### 3. Knowledge Articles
+
+Create Knowledge Article cards in `Knowledge Articles/`. Always create at
+least these two:
+
+- **Brief Context** (`<slug>-brief-context`) — the full brief content and background, `articleType: "context"`
+- **Agent Onboarding** (`<slug>-agent-onboarding`) — instructions for how to work on this project, `articleType: "onboarding"`
+
+Add more articles as the brief warrants — for example, a detailed visual
+design section could become its own article, or deep domain knowledge could
+be split out for clarity. Keep each article cohesive with a clear guiding
+principle.
+
+Each article should have:
+
+- `articleTitle` — a descriptive title (e.g., `"<brief title> — Brief Context"`, `"<brief title> — Data Model"`)
+- `articleType` — one of `"context"`, `"onboarding"`, `"reference"`, `"decision"`
+- `content` — the article body in markdown
+- `tags` — relevant tags for skill resolution
+- `updatedAt` — ISO timestamp
+
+adoptsFrom: the darkfactory `KnowledgeArticle` type.
+
+Link all articles from the Project card's `knowledgeBase` relationship, and
+from the implementation issues' `relatedKnowledge` relationships.
+
+### 4. Implementation Issues
+
+Organize implementation issues around **entry-point cards** — the top-level
+cards that users interact with directly and that should be discoverable in the
+Boxel catalog. Create **one issue per entry-point card**. Use judgment based on
+the brief to identify which cards are entry points vs interior/support cards.
+
+Each issue should cover the full scope of its entry-point card:
+
+- The card definition (`.gts`) and any interior/support cards it depends on
+- HTML-first design artifacts under `design/` (mockup + screenshot + critique pass) — **NO `.test.gts` files**: this is the design-first loop; tests belong to a separate hardening phase. Never put tests in a description or acceptance criteria.
+- A Catalog Spec (`Spec/<card-name>.json`) with realistic example instances linked via `linkedExamples`
+
+Interior cards (field cards, helper cards, linked supporting cards) are
+implemented as part of their entry-point card's issue — they do not need
+their own catalog specs or separate issues.
+
+**Dependency ordering:** If one entry-point card depends on another (e.g.,
+card B uses card A as a field type or linked card), the depended-upon card's
+issue must come first. Set `order` so that dependency cards are processed
+before their consumers, and wire `blockedBy` so the consuming card's issue
+cannot start until the dependency card's issue is done. (`blockedBy` means
+"depends on the DONE-ness of" — normal sequencing, not blockage.)
+
+**Scope each issue as an MVP pass — breadth and depth are budgets, not
+defaults.** The coding agent does NOT know the big picture; if an issue
+reads open-ended it will gold-plate every surface and burn hours doing a
+full project's work. So plan two passes up front:
+
+- **First-pass issues (the ones described above)**: the description MUST
+  contain an explicit `**In scope (this pass)**` list — the minimal
+  subset done WELL (e.g., "isolated view; fitted TILE ~200×180 only;
+  3 core fields; happy path") — and a `**Deferred (second pass)**` list
+  naming what is intentionally out (wide/strip fitted variants, edge
+  states, secondary fields, bulk flows). Small and polished beats broad
+  and rough.
+- **Second-pass issues, created NOW**: for each card with meaningful
+  deferred scope, also create `Issues/<slug>-<card-name-slug>-pass-2.json`
+  — same format, `issueType` `"enhancement"`, priority `"low"`, `order`
+  AFTER every first-pass issue, `blockedBy` its first-pass issue, and a
+  description that IS the deferred list. These run only if the build
+  moves forward; the operator can cancel them wholesale. Never fold
+  second-pass scope into a first-pass issue.
+
+**Build-plan Knowledge Article** — write
+`Knowledge Articles/build-plan.json`: the big picture the coding agents
+lack. Cover: the card-family map (what links to what and why), the pass
+sequencing (which issues are first-pass MVPs, which are second-pass
+polish, the dependency chains), and what "good enough" means per pass.
+Wire it into EVERY issue's `relatedKnowledge` (next free index) so every
+agent turn sees where its issue fits the whole. This document is
+maintained: the reviewer updates it as the build's reality evolves.
+
+**Issue format** — for each entry-point card, create an issue named after the card at `Issues/<slug>-<card-name-slug>.json` (e.g., `Issues/sticky-note.json` for a "Sticky Note" card):
+
+- `issueId` — `"<projectCode>-<N>"` (sequential, dependency-first ordering)
+- `summary` — `"Implement <card name> card"` (named after the entry-point card, e.g., "Implement Sticky Note card")
+- `description` — describe the card to create, its fields, any interior/support cards, the design-first flow (mockup → critique → code), and what the catalog spec should contain. Do NOT ask for tests.
+- `issueType` — `"feature"`
+- `status` — `"backlog"`
+- `priority` — `"high"` for the first, `"medium"` for subsequent
+- `order` — sequential, respecting dependency order (cards with no dependencies first)
+- `acceptanceCriteria` — checklist covering design artifacts, card definition (3 formats), spec with populated title/description, and examples. Validation gates are `run_lint`, `run_parse`, `run_evaluate`, `run_instantiate` — the v2 pipeline runs NO tests; never list `.test.gts` or `run_tests`.
+- Relationships:
+  - `project` → `../Projects/<slug>`
+  - `relatedKnowledge.0` → `../Knowledge Articles/<slug>-brief-context`
+  - `relatedKnowledge.1` → `../Knowledge Articles/<slug>-agent-onboarding`
+  - `blockedBy.0` → `../Issues/design-foundation-seed` on EVERY
+    implementation issue — the design-foundation issue (runs right after
+    this bootstrap) establishes the brand guide, tokens, and family
+    coherence sheet that all card designs consume; no card may design
+    ahead of it
+  - further `blockedBy.N` → issues for any entry-point cards this card
+    depends on
+
+adoptsFrom: the darkfactory `Issue` type.
+
+If the brief describes only one card, create one issue. If it describes multiple
+entry-point cards, create one issue per entry-point card ordered so that
+dependency cards are implemented before cards that consume them.
+
+## Instructions
+
+**Step 0 (MANDATORY before any `Write`).** Fetch the live schema for
+each card type you're about to write. Without this you will guess
+field names and array shapes and produce cards that fail to render
+with `Expected array for field value <X>` runtime errors:
+
+```
+get_card_schema({ module: "<darkfactoryModuleUrl from system prompt>", name: "Project" })
+get_card_schema({ module: "<darkfactoryModuleUrl from system prompt>", name: "IssueTracker" })
+get_card_schema({ module: "<darkfactoryModuleUrl from system prompt>", name: "KnowledgeArticle" })
+get_card_schema({ module: "<darkfactoryModuleUrl from system prompt>", name: "Issue" })
+```
+
+The returned `{ attributes, relationships? }` JSON Schema names every
+field, its type (`string`, `number`, `boolean`, `array` for
+`containsMany` / `linksToMany`, etc.), and any enum values
+(`status`, `priority`, `articleType`, `projectStatus`, `issueType`).
+Use those exact names, types, and enum values.
+
+Then create the artifacts in order so relationship targets exist
+when referenced:
+
+1. The brief content is included verbatim in the issue description above. Do not fetch the URL — read the description.
+2. Derive the slug and project code from the brief title.
+3. Call `Write` to create the **Project card** at `Projects/<slug>.json`.
+4. Call `Write` to create the **IssueTracker card** at `Boards/<slug>.json` and link it to the Project card.
+5. Call `Write` to create the **Knowledge Article cards** in `Knowledge Articles/` (at least brief context + agent onboarding).
+6. Identify entry-point cards from the brief — these are the top-level cards users interact with.
+7. Call `Write` to create **one implementation Issue per entry-point card** at `Issues/<slug>-<card-name-slug>.json`, with all relationships wired.
+8. Call **`signal_done`** (factory MCP tool) — the orchestrator manages issue status transitions. Do NOT set the issue status yourself.
+
+**You must actually call the `Write` tool for each file. Calling
+`signal_done` without writing the artifacts is a failure.**
+
+Create artifacts in the order listed — Project first, then IssueTracker, then Knowledge Articles,
+then Issues — so that relationship targets exist when referenced.
diff --git a/packages/software-factory/prompts/issue-analysis.md b/packages/software-factory/prompts/issue-analysis.md
new file mode 100644
index 00000000000..f459a101203
--- /dev/null
+++ b/packages/software-factory/prompts/issue-analysis.md
@@ -0,0 +1,117 @@
+# Port analysis
+
+You are the RESEARCH agent for an inspired-by port. Another team of agents
+will build a Boxel-native version of an existing application; your job is
+to give them the background a great port needs — grounded in what the
+original app ACTUALLY looks like, does, and HOW ITS CODE WORKS, not just
+what its README claims.
+
+# The issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+
+{{issue.description}}
+
+# Ground rules for this turn
+
+- This is a research turn: you write NO product code, no `.gts` files, no
+  card templates. Your deliverables are two Knowledge Article JSONs + one
+  relationship edit.
+- **Network + scratch space granted for this turn only**: you may use
+  `Bash` (`git`, `curl -sL`, `ffmpeg`) to clone and download, writing ONLY
+  under `.factory-scratch/` in the workspace (it is sync-ignored — nothing
+  in it reaches any realm). Do not write outside that directory except the
+  Knowledge Article JSONs and the bootstrap-issue edit.
+- Live-blog as you go: `post_update` when the clone lands, when the media
+  or code analysis yields something surprising, and when each article
+  lands.
+- Skip the `run_*` validation tools — there is nothing to validate.
+
+# Protocol
+
+1. **Clone the repo.**
+   `git clone --depth 1 <repo url> .factory-scratch/repo`
+   Read the README fully, then walk the file tree. Identify the stack,
+   the entry points, and where the domain logic lives.
+
+2. **Media analysis.** Collect every image, GIF, and video referenced by
+   the README (and `docs/` / `screenshots/` dirs). Download anything not
+   already in the clone into `.factory-scratch/media/`. Then:
+   - PNG/JPG/WebP: `Read` each one and describe the screen — layout,
+     affordances, states, empty states, typography mood.
+   - GIF/MP4/WebM: extract frames (`ffmpeg -i in.gif -vf fps=1/2
+     .factory-scratch/media/frame-%02d.png`) and `Read` them. If no
+     extractor is available, record the URL under "Unviewed media — human
+     should watch" with what the README claims it shows.
+   Every visual claim in your background must trace to a file you read.
+
+3. **Get INTO the code.** This is what separates a port from a re-skin:
+   - **Dependencies**: read the manifest(s) (`package.json`,
+     `requirements.txt`, etc.). For each meaningful dependency — skip
+     framework boilerplate — record: what the app uses it for, and the
+     Boxel-side answer (a host tool, the AI proxy / one-shot LLM /
+     image-generation surface, boxel-ui, plain TS carried into the card
+     module, or NEEDS-HUMAN-DECISION when nothing maps).
+   - **Specialized logic**: locate the algorithms and domain logic that
+     make the app work — image pipelines, prompt templates sent to AI
+     services (capture these VERBATIM; they are product IP you can carry
+     straight into the port), scoring/matching/transform functions, state
+     machines. For each: file path, what it does, and whether it ports
+     directly (pure TS → card module) or needs re-architecture for cards.
+   - **Tests and fixtures**: find the test files and sample data. Tests
+     are the original's behavioral contract — mine them:
+     - What behaviors do they pin down? List the assertions worth
+       carrying, grouped by feature.
+     - What fixtures/sample data do they use? These become the port's
+       sample card instances — real shapes, real edge cases, not invented
+       lorem ipsum.
+     - Which tests translate to card-level checks (computed fields,
+       transforms — portable near-verbatim) vs UI/integration behavior
+       (becomes acceptance criteria for the walkthrough instead)?
+     If there are no tests, say so and derive the behavioral contract
+     from the code paths you read.
+
+4. **Write TWO Knowledge Articles** (adoptsFrom `{{darkfactoryModuleUrl}}`
+   name `KnowledgeArticle`; call `get_card_schema` first if unsure of the
+   fields):
+
+   **`Knowledge Articles/port-background.json`** — the product view:
+   - What the app is (two paragraphs, in your own words after the media pass)
+   - Feature inventory (core / secondary / skip-for-v1)
+   - Screen catalogue (one entry per distinct view seen in the media)
+   - UX flows (the 2–4 defining journeys, step by step)
+   - "Better than the original" rubric — 5–10 measurable criteria the
+     Boxel port must beat (weaknesses of the original + what card-native
+     enables: linked data, live search surfaces, theming, AI assists)
+   - Boxel port mapping — the proposed card family: each CardDef with
+     fields, `linksTo`/`linksToMany` edges, and which original screen each
+     isolated/embedded/fitted format covers
+   - Unviewed media / open questions
+
+   **`Knowledge Articles/port-code-analysis.json`** — the engineering view:
+   - Architecture sketch: how the original is put together (modules,
+     data flow, where state lives)
+   - Dependency map: each meaningful dependency → role → Boxel answer
+     (flag NEEDS-HUMAN-DECISION items prominently)
+   - Specialized logic inventory: path + summary + port strategy for each
+     algorithm; AI prompt templates captured verbatim
+   - Data model AS IMPLEMENTED: the real entities/fields/types from the
+     code (not just inferred from screenshots)
+   - **Ported test contract**: per feature, the assertions carried from
+     the original's tests; fixture data (inline the useful samples) to
+     seed the port's sample instances; which checks are card-level vs
+     acceptance-walkthrough-level. Implementation issues should quote
+     from this when writing acceptance criteria.
+
+5. **Link both to bootstrap.** Edit `Issues/bootstrap-seed.json` adding
+   under `relationships` (keep existing keys; linksToMany uses indexed
+   top-level keys — never an array):
+   ```json
+   "relatedKnowledge.0": { "links": { "self": "../Knowledge Articles/port-background" } },
+   "relatedKnowledge.1": { "links": { "self": "../Knowledge Articles/port-code-analysis" } }
+   ```
+
+6. `post_update` a closing summary (features found, screens catalogued,
+   dependencies mapped, tests mined, rubric headline), then call
+   `signal_done`.
diff --git a/packages/software-factory/prompts/issue-build-v2.md b/packages/software-factory/prompts/issue-build-v2.md
new file mode 100644
index 00000000000..27287be8cf6
--- /dev/null
+++ b/packages/software-factory/prompts/issue-build-v2.md
@@ -0,0 +1,109 @@
+# Project
+
+{{project.objective}}
+
+{{#if project.successCriteria}}
+Success criteria:
+{{#each project.successCriteria}}
+- {{.}}
+{{/each}}
+{{/if}}
+
+# Knowledge
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+{{/each}}
+
+# Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+Status: {{issue.status}}
+Priority: {{issue.priority}}
+
+Description:
+{{issue.description}}
+
+{{#if issue.checklist}}
+Checklist:
+{{#each issue.checklist}}
+- [ ] {{.}}
+{{/each}}
+{{/if}}
+
+{{#if toolResults}}
+
+# Tool Results
+
+You previously invoked the following tools. Use these results to inform your implementation.
+
+{{#each toolResults}}
+
+## {{tool}} (exit code: {{exitCode}})
+
+```{{outputFormat}}
+{{output}}
+```
+
+{{/each}}
+{{/if}}
+
+# Instructions — BUILD TURN
+
+This is the **build half** of a phase-split issue. The design turn already
+produced accepted mockups and notes under `design/` (you may remember making
+them — this session is forked from that turn). Design decisions are MADE;
+this is a translation task. Do not redesign, do not re-screenshot mockups.
+
+**Live-blog as you go.** Call `post_update` when you start each file, on any
+non-obvious translation decision, and when recovering from a failed check.
+
+## 1. Load the contract
+
+- `Read` `design/<card-slug>-NOTES.md` and the accepted `design/<card-slug>.html`
+  (+ its PNG). These are authoritative — follow them exactly.
+
+## 2. BUILD — translate the accepted mockup
+
+- Write the card definition (`.gts`) with `isolated`, `embedded`, AND
+  `fitted` templates reproducing the accepted mockup. Use theme CSS
+  variables (`var(--*)`) per the notes' token mapping.
+- Fields are an API other cards compose with: name them for consumers,
+  prefer FieldDefs for shapes that recur (the notes name them).
+- Write sample card instances (`.json`) using the SAME sample data as the
+  mockup.
+- Write a Catalog Spec card (`Spec/<card-slug>.json`, adoptsFrom
+  `https://cardstack.com/base/spec#Spec`) linking sample instances via
+  `linkedExamples`, with `title` and one-sentence `description` populated.
+
+## 3. VERIFY
+
+- `run_lint({ path })` each file; then `run_parse()`, `run_evaluate()`,
+  `run_instantiate()` for the whole realm. Fix what they report.
+- **Fix with `Edit`, not `Write`.** Once a file exists, every fix is a
+  surgical search/replace `Edit` on the failing lines — re-emitting the
+  whole file costs 1–2 minutes of generation per attempt and is the main
+  reason build turns run long. Failures in files you didn't write this
+  turn are pre-existing: note them via `post_update` and move on.
+- **Do NOT write any `.test.gts` files** — tests belong to a later
+  hardening phase.
+
+## 4. Done
+
+- Call `signal_done`. The orchestrator validates automatically. Calling it
+  without the card, an instance, and a Spec is a failure.
+
+## After you finish (v3 render gate)
+
+The orchestrator will screenshot the cards you shipped (real host
+renders) and a verifier agent will judge every acceptance criterion
+against the PIXELS — a criterion only passes on a visible, working
+affordance. "The command class exists" fails. So: every capability the
+issue promises must be reachable through something the user can SEE
+(a button, a populated list, a rendered value), and your sample
+instances must make each surface render with real content, never an
+empty state.
diff --git a/packages/software-factory/prompts/issue-design-foundation.md b/packages/software-factory/prompts/issue-design-foundation.md
new file mode 100644
index 00000000000..b184aee344f
--- /dev/null
+++ b/packages/software-factory/prompts/issue-design-foundation.md
@@ -0,0 +1,87 @@
+# Project
+
+{{project.objective}}
+
+# Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+
+Description:
+{{issue.description}}
+
+{{#if knowledge}}
+
+# Knowledge Articles
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+
+{{/each}}
+{{/if}}
+
+# Instructions — DESIGN FOUNDATION TURN
+
+You are establishing the design language for this entire build, BEFORE
+any card is designed in detail. Coherence first; detail later. Every
+future design and build turn will treat your artifacts as binding.
+
+Work strictly top-down:
+
+## 1. Look & feel
+
+Read the project Knowledge Articles above (port background / brief
+context) and the issue backlog (`Issues/*.json` — the card family). Then
+decide the overall visual direction:
+
+- What should this app FEEL like? Name the mood in 3–5 guiding words
+  (e.g. "quiet instrument", "editorial warmth", "utility bench").
+- What are the reference points (products, print, materials)?
+- What is the ONE visual signature this family owns (a rule, a texture,
+  a typographic move — something recognizable across every card)?
+
+Post your direction via `post_update` (kind: `decision`) before writing
+any files.
+
+## 2. Brand guide + tokens
+
+Write TWO artifacts:
+
+- **`Knowledge Articles/brand-guide.json`** — a KnowledgeArticle whose
+  content carries: the guiding words (with one sentence each on what
+  they permit and forbid), the palette (with usage roles, not just
+  swatches), the typographic scale and families, spacing/radius/shadow
+  rules, and 3–5 explicit dos/don'ts. This is prose a future agent reads
+  to make decisions you didn't anticipate.
+- **`design/tokens.css`** — the same decisions as CSS custom properties:
+  `--*` variables for every color role, type size/weight/family,
+  spacing step, radius, and shadow. Every future mockup links this file;
+  every future `.gts` template mirrors these variables. Comment each
+  group with its guiding word.
+
+## 3. Family coherence sheet
+
+Write **`design/family-sheet.html`** — one page, linking `tokens.css`,
+showing a SIMPLE version of EVERY card in the domain side-by-side (one
+representative surface each — a tile or row per card type, with real
+sample copy from the domain). This is NOT detailed design: no fitted
+quanta, no per-format matrices. It answers one question: **do these
+cards look like one family?**
+
+Then `screenshot_html({ path })`, `Read` the PNG, and critique for
+coherence — same visual weight? same voice? does the signature carry?
+Name the defects, revise ONCE, re-screenshot. Post the round via
+`post_update`.
+
+## 4. Done
+
+Detailed per-card design (fitted sub-formats, per-format content
+matrices, mockup crit rounds) happens in each card's own design turn —
+they will read your brand guide, tokens, and family sheet as binding
+context. Do NOT do detailed design here.
+
+Call `signal_done` when the brand guide, tokens.css, and the critiqued
+family sheet are all written.
diff --git a/packages/software-factory/prompts/issue-design-v2.md b/packages/software-factory/prompts/issue-design-v2.md
new file mode 100644
index 00000000000..f631635b3f6
--- /dev/null
+++ b/packages/software-factory/prompts/issue-design-v2.md
@@ -0,0 +1,105 @@
+# Project
+
+{{project.objective}}
+
+{{#if project.successCriteria}}
+Success criteria:
+{{#each project.successCriteria}}
+- {{.}}
+{{/each}}
+{{/if}}
+
+# Knowledge
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+{{/each}}
+
+# Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+Status: {{issue.status}}
+Priority: {{issue.priority}}
+
+Description:
+{{issue.description}}
+
+{{#if issue.checklist}}
+Checklist:
+{{#each issue.checklist}}
+- [ ] {{.}}
+{{/each}}
+{{/if}}
+
+{{#if toolResults}}
+
+# Tool Results
+
+You previously invoked the following tools. Use these results to inform your implementation.
+
+{{#each toolResults}}
+
+## {{tool}} (exit code: {{exitCode}})
+
+```{{outputFormat}}
+{{output}}
+```
+
+{{/each}}
+{{/if}}
+
+# Instructions — DESIGN TURN
+
+This is the **design half** of a phase-split issue. Your ONLY deliverables
+are accepted HTML mockups and design notes — a separate build turn (running
+on a cheaper budget, forked from this session) will translate them into
+card code. Do NOT write any `.gts`, `.json` instance, or Spec in this turn.
+
+**Live-blog as you go.** Call `post_update` at every meaningful moment —
+design kickoff, what each critique round found (name the defects), the
+decision that resolved it. First person, 1–3 sentences.
+
+## 1. Ground yourself
+
+- **Scope check FIRST**: read `Knowledge Articles/build-plan.json` and
+  your issue's "In scope (this pass)" list. Mock ONLY the in-scope
+  surfaces at the in-scope sizes — if this pass says "fitted tile only,"
+  do not design the wide strip or expanded card (a pass-2 issue owns
+  those). Depth over breadth: make the small scope excellent.
+- **BINDING design language — read it FIRST when it exists:**
+  `Knowledge Articles/brand-guide.json` (guiding words, palette, rules),
+  `design/tokens.css` (the CSS variables — your mockup MUST link this
+  file and use its `--*` variables, never invent new colors/type), and
+  `design/family-sheet.html` (what the family looks like — your card
+  must read as a sibling of those, not a new style). Deviating from the
+  brand guide is a defect; if the guide genuinely can't express this
+  card, post the tension via `post_update` and extend the tokens rather
+  than fork them.
+- `Read` / `Glob` the workspace; `Bash` + `boxel search --realm <target-realm-url>` for cards already in the target realm.
+- Call `list_skills`, then `read_skill` the skills this issue touches.
+  Read precedent: if a similar card exists in the workspace, read its `.gts`.
+
+## 2. DESIGN — mock, screenshot, critique, revise
+
+- Write `design/<card-slug>.html`: **ONE page** — plain HTML+CSS mockup with
+  **hard-coded, realistic sample copy** (never lorem ipsum). Every surface on
+  that one page, labeled: isolated (mobile; wide variant if the card prefers
+  wide), fitted tiles (badge / strip / card), an embedded row.
+- `screenshot_html({ path })`, `Read` the PNG, and **critique it**: name
+  concrete defects (hierarchy, wrapping, spacing, color, copy) against the
+  design language. Revise and re-screenshot. At least one full
+  crit-and-revise pass; stop when you would show it to a designer.
+
+## 3. Hand off
+
+- Write `design/<card-slug>-NOTES.md`: the accepted design's intent in
+  build-ready terms — schema fields implied by the mockup (names + types +
+  which are FieldDefs), the CQ breakpoints used, theme-token mapping for
+  every hard-coded color/size in the mockup, and any traps the builder must
+  not miss. This file is the build turn's contract; write it like a spec.
+- `post_update` a `decision` summarizing the accepted design.
+- Call `signal_done`. Do NOT set issue status; do NOT write card code.
diff --git a/packages/software-factory/prompts/issue-fix-v2.md b/packages/software-factory/prompts/issue-fix-v2.md
new file mode 100644
index 00000000000..26bfb929b03
--- /dev/null
+++ b/packages/software-factory/prompts/issue-fix-v2.md
@@ -0,0 +1,115 @@
+# Project
+
+{{project.objective}}
+
+{{#if project.successCriteria}}
+Success criteria:
+{{#each project.successCriteria}}
+- {{.}}
+{{/each}}
+{{/if}}
+
+# Knowledge
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+{{/each}}
+
+# Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+Status: {{issue.status}}
+Priority: {{issue.priority}}
+
+Description:
+{{issue.description}}
+
+{{#if issue.checklist}}
+Checklist:
+{{#each issue.checklist}}
+- [ ] {{.}}
+{{/each}}
+{{/if}}
+
+{{#if toolResults}}
+
+# Tool Results
+
+You previously invoked the following tools. Use these results to inform your fix.
+
+{{#each toolResults}}
+
+## {{tool}} (exit code: {{exitCode}})
+
+```{{outputFormat}}
+{{output}}
+```
+
+{{/each}}
+{{/if}}
+
+# Instructions
+
+This is a **bug fix on an existing card**, not a new build. The card and its
+design already exist and shipped; something is broken. Your job is to find the
+root cause and fix it with the smallest change that resolves the defect —
+**not** to redesign the card.
+
+**Do NOT run a design round.** No HTML mockups, no `screenshot_html`, no
+design critique. The look is already decided; you are correcting behavior.
+Preserve the existing templates, theme, fields, and sample data except for
+what the bug requires you to change.
+
+**Live-blog as you go.** The operator watches this run on a live run-log card.
+Call `post_update` at every meaningful moment — the root cause once you find
+it, the fix and why it works, recovering from a failed check. First person,
+concrete, 1–3 sentences. Never work silently for more than a few minutes.
+
+## 1. Reproduce & locate
+
+- Read the issue above: the symptom, any error message, and the repro path.
+- `Read` the offending `.gts` (and any card it composes with or links to).
+  The error usually names the surface — an isolated/embedded/fitted template,
+  a computed field, or a query. A `Cannot read properties of undefined`
+  crash is almost always a template or computed reading a field that can be
+  null/absent for the failing instance.
+- `read_skill` only the skills the fix actually touches (the failing
+  template/format, the field type involved) — skip the general design skills.
+
+## 2. Diagnose the root cause
+
+- State the actual cause, not just the symptom: which value is undefined,
+  on which code path, for which instance shape. Confirm it against the code
+  you read — don't guess. `post_update` the root cause.
+
+## 3. Fix minimally
+
+- Make the smallest change that resolves it: guard the undefined access,
+  correct the field/query, fix the computed. Keep every unrelated line intact.
+- If the bug is that a sample instance is missing data the card needs, fix the
+  instance — but do not restyle the card.
+- Only add a Spec or new instance if the issue explicitly calls for one.
+
+## 4. Verify
+
+- `run_lint({ path })` each file you changed; then `run_parse()`,
+  `run_evaluate()`, and `run_instantiate()` for the whole realm. Fix what
+  they report.
+- **Do NOT write any `.test.gts` files** — tests belong to a separate phase.
+
+## 5. Done
+
+- Call `signal_done` (factory MCP tool). The orchestrator validates
+  parse/lint/eval/instantiate automatically. Do NOT set the issue status
+  yourself.
+
+## After you finish (v3 render gate)
+
+The orchestrator will screenshot the affected card (a real host render) and a
+verifier agent will judge the fix against the PIXELS — the defect only counts
+as fixed when the surface it broke renders correctly with real content. Make
+sure the instance that exposed the bug now renders cleanly.
diff --git a/packages/software-factory/prompts/issue-implement-v2.md b/packages/software-factory/prompts/issue-implement-v2.md
new file mode 100644
index 00000000000..126a355c941
--- /dev/null
+++ b/packages/software-factory/prompts/issue-implement-v2.md
@@ -0,0 +1,131 @@
+# Project
+
+{{project.objective}}
+
+{{#if project.successCriteria}}
+Success criteria:
+{{#each project.successCriteria}}
+- {{.}}
+{{/each}}
+{{/if}}
+
+# Knowledge
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+{{/each}}
+
+# Current Issue
+
+ID: {{issue.id}}
+Summary: {{issue.summary}}
+Status: {{issue.status}}
+Priority: {{issue.priority}}
+
+Description:
+{{issue.description}}
+
+{{#if issue.checklist}}
+Checklist:
+{{#each issue.checklist}}
+- [ ] {{.}}
+{{/each}}
+{{/if}}
+
+{{#if toolResults}}
+
+# Tool Results
+
+You previously invoked the following tools. Use these results to inform your implementation.
+
+{{#each toolResults}}
+
+## {{tool}} (exit code: {{exitCode}})
+
+```{{outputFormat}}
+{{output}}
+```
+
+{{/each}}
+{{/if}}
+
+# Instructions
+
+You are building a **user-facing card**. A card is judged by how it looks and
+reads in its formats, and by how cleanly other cards can compose with it —
+not by ceremony. Work design-first, in this order:
+
+**Live-blog as you go.** The operator watches this run on a live run-log
+card. Call `post_update` at every meaningful moment — kicking off a design,
+what a critique round found (name the defects), a decision and its tradeoff,
+starting to translate the mockup to code, recovering from a failed check.
+First person, concrete, 1–3 sentences, social-media energy. This commentary
+channel is as important as the artifacts: it steers orchestration during the
+run and is the record after it. Never work silently for more than a few
+minutes.
+
+## 1. Ground yourself (context before code)
+
+- `Read` / `Glob` the workspace; `Bash` + `boxel search --realm <target-realm-url>` for cards already in the target realm.
+- Call `list_skills`, then `read_skill` the skills this issue actually touches
+  (design, fitted formats, theming, file fields, queries — whatever applies).
+  Read precedent: if a similar card exists in the workspace, read its `.gts`.
+
+## 2. DESIGN — HTML mockup before any schema
+
+- Write `design/<card-slug>.html`: **ONE page** — a plain HTML+CSS mockup of
+  the card with **hard-coded, realistic sample copy** (real names, real
+  numbers — never lorem ipsum). Put every surface on that one page, labeled:
+  the isolated view (mobile width; add a wide variant section if the card
+  prefers wide format), the fitted tiles (badge / strip / card), and an
+  embedded list row. One file, one screenshot, one crit pass covers
+  everything — do NOT write a separate HTML file per surface.
+- Call `screenshot_html({ path: "design/<card-slug>.html" })`, then `Read`
+  the returned PNG and **critique it**: name concrete defects (hierarchy,
+  wrapping, spacing, color, copy) against the design language in the
+  Knowledge section. Revise the HTML and re-screenshot. Do at least one
+  full crit-and-revise pass; stop when you would show it to a designer.
+
+## 3. BUILD — translate the accepted mockup
+
+- Write the card definition (`.gts`) with `isolated`, `embedded`, AND
+  `fitted` templates that reproduce the accepted mockup. Design decisions
+  were made in step 2 — this is a translation task. Use theme CSS variables
+  (`var(--*)`) rather than hard-coded colors where a theme exists.
+- Fields are an API other cards compose with: name them for consumers,
+  and prefer FieldDefs for shapes that will recur.
+- Write at least one sample card instance (`.json`) using the SAME sample
+  data as the mockup.
+- Write a Catalog Spec card (`Spec/<card-slug>.json`, adoptsFrom
+  `https://cardstack.com/base/spec#Spec`) linking the sample instances via
+  `linkedExamples`, with its catalog-facing `title` and one-sentence
+  `description` attributes populated (never left empty).
+
+## 4. VERIFY
+
+- `run_lint({ path })` each file you wrote; then `run_parse()`,
+  `run_evaluate()`, and `run_instantiate()` for the whole realm.
+- Fix what they report. **Do NOT write any `.test.gts` files** — tests
+  belong to a separate hardening phase that runs later; this loop ships
+  zero tests by design.
+
+## 5. Done
+
+- Call `signal_done` (factory MCP tool). The orchestrator validates
+  parse/lint/eval/instantiate automatically. Do NOT set the issue status
+  yourself. Calling `signal_done` without the design artifacts, the card,
+  an instance, and a Spec is a failure.
+
+## After you finish (v3 render gate)
+
+The orchestrator will screenshot the cards you shipped (real host
+renders) and a verifier agent will judge every acceptance criterion
+against the PIXELS — a criterion only passes on a visible, working
+affordance. "The command class exists" fails. So: every capability the
+issue promises must be reachable through something the user can SEE
+(a button, a populated list, a rendered value), and your sample
+instances must make each surface render with real content, never an
+empty state.
diff --git a/packages/software-factory/prompts/issue-iterate.md b/packages/software-factory/prompts/issue-iterate.md
index a95119c3e0a..b86d9f134f8 100644
--- a/packages/software-factory/prompts/issue-iterate.md
+++ b/packages/software-factory/prompts/issue-iterate.md
@@ -54,7 +54,10 @@ All validation steps passed.
 Fix the validation failures shown above. You have the same tools available. You can:
 
 - Use **`Read`** / **`Glob`** to inspect the current state of your implementation
-- Use **`Write`** or **`Edit`** to update implementation or test files
+- Use **`Edit`** to fix the failing lines — surgical search/replace on the
+  smallest span, never a whole-file re-`Write` (re-emitting a full `.gts`
+  costs 1–2 minutes of generation; an `Edit` costs seconds). Reach for
+  **`Write`** only when more than half the file is changing
 - Use **`Bash`** + `boxel search` to check what cards exist in the realm
 - If a lint violation is in your code, fix the code to pass lint
 - If the test expectation is wrong, fix the test
diff --git a/packages/software-factory/prompts/prime.md b/packages/software-factory/prompts/prime.md
new file mode 100644
index 00000000000..4df067e65ac
--- /dev/null
+++ b/packages/software-factory/prompts/prime.md
@@ -0,0 +1,34 @@
+# Project
+
+{{project.objective}}
+
+# Knowledge
+
+{{#each knowledge}}
+
+## {{title}}
+
+{{content}}
+{{/each}}
+
+# Priming turn — build shared context, do NOT implement anything
+
+This turn primes a session that later implementation turns will fork from.
+Everything you read now is inherited by every fork; anything you skip will
+have to be re-read in each fork. Prime thoroughly, then stop.
+
+1. Call `list_skills`, then `read_skill` the skills and reference files this
+   project will need across ALL of its work items: card authoring patterns,
+   fitted formats, template patterns, theme/design-system guidance, spec
+   usage, and the boxel-ui component-discovery skill.
+2. `Glob`/`Read` the workspace for precedent: existing `.gts` card
+   definitions, the design-language and sample-data knowledge articles'
+   source files, any existing theme.
+3. Write `design/DESIGN-NOTES.md` in the workspace: a compact design-system
+   brief for this project — palette values, type scale, spacing/hairline
+   rules, per-surface layout intents (isolated / fitted badge/strip/card /
+   embedded), and the sample-data facts every card must stay consistent
+   with. Future forks treat this file as binding.
+4. Do NOT write any `.gts`, instances, Specs, or mockup HTML for specific
+   work items. Do NOT call `signal_done` or `request_clarification`. When
+   the notes file is written, end your turn with a one-line summary.
diff --git a/packages/software-factory/src/control-plane-sync.ts b/packages/software-factory/src/control-plane-sync.ts
new file mode 100644
index 00000000000..3d4194a4a77
--- /dev/null
+++ b/packages/software-factory/src/control-plane-sync.ts
@@ -0,0 +1,329 @@
+/**
+ * Control-plane sync — the control half of the v3 control/product realm
+ * split.
+ *
+ * With `--control-realm` set, the factory keeps ONE local workspace but
+ * two realm destinations:
+ *
+ * - **Product realm** (`--target-realm`): the built card defs and
+ *   instances. Synced by the existing atomic workspace sync, with the
+ *   control-plane paths excluded via a factory-managed `.boxelignore`.
+ * - **Control realm** (`--control-realm`): issues, project/board/knowledge
+ *   tracker cards, validation artifacts, and the run log. Synced HERE, by
+ *   individual raw `client.write` calls.
+ *
+ * Why this shape:
+ * - Run-log/validation churn stops invalidating the product realm's index
+ *   (the live-surface "flashing Loading…" failure), and product `.gts`
+ *   updates stop nuking the loader under the run-log/issue cards the
+ *   operator is watching.
+ * - Raw per-file writes never go through `/_atomic?waitForIndex=true`,
+ *   which strips `containsMany` FieldDef data from card sources (critical
+ *   platform bug, report filed 2026-07-16) — so the entire control plane
+ *   is structurally immune to the strip, not just healed after the fact.
+ *
+ * Limitations (documented, acceptable for the control plane):
+ * - Text files only (`client.write` sends card-source MIME as a string).
+ *   Design PNGs therefore stay on the product sync.
+ * - No deletion propagation — control-plane cards are append/update-only
+ *   in practice (issues get status flips, never deletes).
+ */
+
+import { createHash } from 'node:crypto';
+import { readdir, readFile, mkdir, writeFile, stat } from 'node:fs/promises';
+import { dirname, join, relative, sep } from 'node:path';
+
+import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
+
+import { logger } from './logger.ts';
+
+const log = logger('control-plane-sync');
+
+// ---------------------------------------------------------------------------
+// Control-plane path ownership
+// ---------------------------------------------------------------------------
+
+/**
+ * Workspace directories owned by the control plane. Everything under these
+ * goes to the control realm; everything else is product.
+ *
+ * `Spec/` is deliberately NOT here: Catalog Spec cards are part of the
+ * product (they make the built cards catalog-discoverable), and the
+ * instantiate validation's spec discovery searches the product realm — a
+ * control-routed Spec is invisible to it, so validation can never pass.
+ */
+export const CONTROL_DIRS = [
+  'Issues',
+  'Projects',
+  'Boards',
+  'Knowledge Articles',
+  'Validations',
+  'Runs',
+  'RunLogEntries',
+] as const;
+
+/** Root-level files owned by the control plane (the run-log CardDef). */
+export const CONTROL_ROOT_FILES = ['run-log.gts'] as const;
+
+const IGNORE_MARKER = '# software-factory control-plane split';
+
+/** True when a workspace-relative path belongs to the control plane. */
+export function isControlPath(relPath: string): boolean {
+  if ((CONTROL_ROOT_FILES as readonly string[]).includes(relPath)) {
+    return true;
+  }
+  return CONTROL_DIRS.some(
+    (dir) => relPath === dir || relPath.startsWith(`${dir}/`),
+  );
+}
+
+/**
+ * Write (or refresh) the factory-managed `.boxelignore` that keeps
+ * control-plane paths out of the PRODUCT realm's atomic sync. The sync
+ * engine reads `.boxelignore` with gitignore semantics; entries are
+ * anchored to the workspace root. Idempotent: an existing file that
+ * already carries the marker block is left alone; a user-authored file
+ * without it gets the block appended.
+ */
+export async function ensureControlPlaneIgnoreFile(
+  workspaceDir: string,
+): Promise<void> {
+  let ignorePath = join(workspaceDir, '.boxelignore');
+  let block = [
+    IGNORE_MARKER,
+    ...CONTROL_DIRS.map((dir) => `/${dir}/`),
+    ...CONTROL_ROOT_FILES.map((file) => `/${file}`),
+    '/.boxelignore',
+    '',
+  ].join('\n');
+
+  let existing = '';
+  try {
+    existing = await readFile(ignorePath, 'utf8');
+  } catch {
+    // No ignore file yet.
+  }
+  // Already exactly current — nothing to do.
+  if (existing.includes(block)) {
+    return;
+  }
+  // A stale block is present (an older CONTROL_DIRS set — e.g. before
+  // RunLogEntries was added). Strip the old managed block (its marker line
+  // plus the consecutive `/…` path lines it owns) and re-append the fresh
+  // one, so a CONTROL_DIRS change propagates to existing workspaces instead
+  // of leaving control paths leaking into the product atomic sync.
+  let markerRe = new RegExp(
+    `^${IGNORE_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n(?:/.*\\n?)*`,
+    'm',
+  );
+  let stripped = existing.replace(markerRe, '');
+  let content = stripped.trim()
+    ? `${stripped.replace(/\n?$/, '\n')}\n${block}`
+    : block;
+  await writeFile(ignorePath, content, 'utf8');
+  log.info(
+    `Wrote control-plane .boxelignore (${CONTROL_DIRS.length} dirs excluded from product sync)`,
+  );
+}
+
+const SCRATCH_MARKER = '# software-factory local scratch';
+
+/**
+ * Keep `.factory-scratch/` (the analysis turn's download area — repo
+ * files, media, extracted video frames) out of EVERY sync. Written for
+ * all v2+ runs, split or not; same marker-block mechanics as the
+ * control-plane ignore.
+ */
+export async function ensureScratchIgnoreFile(
+  workspaceDir: string,
+): Promise<void> {
+  let ignorePath = join(workspaceDir, '.boxelignore');
+  let block = [SCRATCH_MARKER, '/.factory-scratch/', '/.boxelignore', ''].join(
+    '\n',
+  );
+  let existing = '';
+  try {
+    existing = await readFile(ignorePath, 'utf8');
+  } catch {
+    // No ignore file yet.
+  }
+  if (existing.includes(SCRATCH_MARKER)) {
+    return;
+  }
+  let content = existing
+    ? `${existing.replace(/\n?$/, '\n')}\n${block}`
+    : block;
+  await writeFile(ignorePath, content, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// The syncer
+// ---------------------------------------------------------------------------
+
+export interface ControlPlaneSyncOptions {
+  client: BoxelCLIClient;
+  /** Control realm URL (trailing slash). */
+  controlRealm: string;
+  /** The shared local workspace (same one the product sync uses). */
+  workspaceDir: string;
+}
+
+export interface ControlPlaneSyncResult {
+  ok: boolean;
+  error?: string;
+  pushed: string[];
+}
+
+export interface ControlPlanePullResult {
+  ok: boolean;
+  error?: string;
+  pulled: number;
+}
+
+export class ControlPlaneSync {
+  private client: BoxelCLIClient;
+  private controlRealm: string;
+  private workspaceDir: string;
+  /** relPath → sha1 of the content last confirmed on the control realm. */
+  private lastPushed = new Map<string, string>();
+
+  constructor(opts: ControlPlaneSyncOptions) {
+    this.client = opts.client;
+    this.controlRealm = opts.controlRealm;
+    this.workspaceDir = opts.workspaceDir;
+  }
+
+  /**
+   * Pull the control realm's control-plane files into the workspace —
+   * selective (control paths only), so the control realm's own
+   * `index.json` never clobbers the product one in the shared mirror.
+   * Seeds the hash map so the first `sync()` doesn't re-push unchanged
+   * files. Local files win on conflict (prefer-local, matching the
+   * product sync's stance).
+   */
+  async pull(): Promise<ControlPlanePullResult> {
+    try {
+      let listing = await this.client.listFiles(this.controlRealm);
+      if (listing.error) {
+        log.warn(`control-plane pull failed: ${listing.error}`);
+        return { ok: false, error: listing.error, pulled: 0 };
+      }
+      let paths = (listing.filenames ?? []).filter(isControlPath);
+      let pulled = 0;
+      for (let relPath of paths) {
+        let localPath = join(this.workspaceDir, relPath);
+        let localExists = await fileExists(localPath);
+        let read = await this.client.read(this.controlRealm, relPath);
+        if (!read.ok || typeof read.content !== 'string') {
+          continue;
+        }
+        this.lastPushed.set(relPath, sha1(read.content));
+        if (!localExists) {
+          await mkdir(dirname(localPath), { recursive: true });
+          await writeFile(localPath, read.content, 'utf8');
+          pulled++;
+        }
+      }
+      if (pulled > 0) {
+        log.info(`Pulled ${pulled} control-plane file(s) from control realm`);
+      }
+      return { ok: true, pulled };
+    } catch (error) {
+      let message = error instanceof Error ? error.message : String(error);
+      log.warn(`control-plane pull failed: ${message}`);
+      return { ok: false, error: message, pulled: 0 };
+    }
+  }
+
+  /**
+   * Push changed control-plane files to the control realm as individual
+   * raw writes. Hash-gated: only files whose content differs from the
+   * last confirmed push go over the wire.
+   */
+  async sync(): Promise<ControlPlaneSyncResult> {
+    let pushed: string[] = [];
+    let errors: string[] = [];
+    let files: string[];
+    try {
+      files = await this.listLocalControlFiles();
+    } catch (error) {
+      let message = error instanceof Error ? error.message : String(error);
+      return { ok: false, error: message, pushed };
+    }
+    for (let relPath of files) {
+      try {
+        let content = await readFile(join(this.workspaceDir, relPath), 'utf8');
+        let hash = sha1(content);
+        if (this.lastPushed.get(relPath) === hash) {
+          continue;
+        }
+        let result = await this.client.write(
+          this.controlRealm,
+          relPath,
+          content,
+        );
+        if (!result.ok) {
+          errors.push(`${relPath}: ${result.error ?? 'unknown write error'}`);
+          continue;
+        }
+        this.lastPushed.set(relPath, hash);
+        pushed.push(relPath);
+      } catch (error) {
+        errors.push(
+          `${relPath}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    if (pushed.length > 0) {
+      log.info(
+        `Control-plane sync: pushed ${pushed.length} file(s) to control realm`,
+      );
+    }
+    if (errors.length > 0) {
+      log.warn(`Control-plane sync errors: ${errors.join('; ')}`);
+      return { ok: false, error: errors.join('; '), pushed };
+    }
+    return { ok: true, pushed };
+  }
+
+  private async listLocalControlFiles(): Promise<string[]> {
+    let results: string[] = [];
+    for (let rootFile of CONTROL_ROOT_FILES) {
+      if (await fileExists(join(this.workspaceDir, rootFile))) {
+        results.push(rootFile);
+      }
+    }
+    for (let dir of CONTROL_DIRS) {
+      let dirPath = join(this.workspaceDir, dir);
+      if (!(await fileExists(dirPath))) continue;
+      let entries = await readdir(dirPath, {
+        recursive: true,
+        withFileTypes: true,
+      });
+      for (let entry of entries) {
+        if (!entry.isFile()) continue;
+        let abs = join(entry.parentPath, entry.name);
+        let rel = relative(this.workspaceDir, abs).split(sep).join('/');
+        results.push(rel);
+      }
+    }
+    return results;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sha1(content: string): string {
+  return createHash('sha1').update(content).digest('hex');
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/packages/software-factory/src/factory-agent/agent-tool-telemetry.ts b/packages/software-factory/src/factory-agent/agent-tool-telemetry.ts
new file mode 100644
index 00000000000..4d4abab3e31
--- /dev/null
+++ b/packages/software-factory/src/factory-agent/agent-tool-telemetry.ts
@@ -0,0 +1,160 @@
+/**
+ * Always-on, lightweight audit trail of an agent turn's tool usage.
+ *
+ * The orchestrator otherwise logs only "Agent returned N tool calls" — which
+ * hides exactly the waste we care about (re-reading the same file, rewriting
+ * a whole `.gts` instead of an `Edit`, screenshot thrash, mutating Bash). The
+ * per-tool detail existed only behind `--debug`. This records every tool_use
+ * block as it streams, prints one terse line per call, and emits a
+ * per-turn waste summary — without needing `--debug`.
+ *
+ * It is observation only: it never blocks, mutates, or fails a run. Every
+ * heuristic is a flag for a human, not a gate.
+ */
+
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { logger } from '../logger.ts';
+
+let log = logger('agent-tools');
+
+/**
+ * Bash is meant to be read-only inspection in the factory loop (ls, grep,
+ * boxel search, read-transpiled). Anything that writes, deletes, moves, or
+ * pushes is a smell — the agent should mutate via native Write/Edit (synced
+ * by the loop), never shell out around the sync path.
+ */
+const MUTATING_BASH =
+  /(^|\s)(rm|mv|cp|touch|mkdir|rmdir|chmod|chown|dd|truncate|ln)\s|>>?[^&]|\b(boxel)\s+(file\s+)?(write|delete|push|ingest-card|realm)\b/;
+
+function strOf(v: unknown): string | undefined {
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+/** One short, human-scannable descriptor of a tool call's primary argument. */
+export function describeToolArg(
+  tool: string,
+  input: Record<string, unknown>,
+): string | undefined {
+  if (tool === 'Read' || tool === 'Write' || tool === 'Edit') {
+    let p = strOf(input.file_path);
+    return p ? basename(p) : undefined;
+  }
+  if (tool === 'Bash') {
+    let cmd = strOf(input.command);
+    return cmd ? cmd.slice(0, 60) : undefined;
+  }
+  if (tool === 'Glob' || tool === 'Grep') {
+    return strOf(input.pattern);
+  }
+  if (tool.endsWith('screenshot_html')) {
+    let p = strOf(input.path);
+    return p ? basename(p) : undefined;
+  }
+  // MCP factory tools (run_lint, get_card_schema, …) — surface a path/name
+  // if one is present, else nothing.
+  return strOf(input.path) ?? strOf(input.name) ?? strOf(input.module);
+}
+
+export interface TurnWasteSummary {
+  totalCalls: number;
+  breakdown: string;
+  concerns: string[];
+}
+
+export class TurnToolTelemetry {
+  private counts = new Map<string, number>();
+  private reads = new Map<string, number>();
+  private wholeFileRewrites: string[] = [];
+  private screenshots = 0;
+  private mutatingBash: string[] = [];
+  private workspaceDir: string | undefined;
+
+  constructor(workspaceDir?: string) {
+    this.workspaceDir = workspaceDir;
+  }
+
+  /** Record one streamed tool_use block. Prints a terse per-call line. */
+  record(tool: string, input: Record<string, unknown>): void {
+    this.counts.set(tool, (this.counts.get(tool) ?? 0) + 1);
+    let arg = describeToolArg(tool, input);
+    log.info(`tool_use(${tool})${arg ? ` ${arg}` : ''}`);
+
+    if (tool === 'Read') {
+      let p = strOf(input.file_path);
+      if (p) this.reads.set(p, (this.reads.get(p) ?? 0) + 1);
+    } else if (tool === 'Write') {
+      // A Write whose target already exists on disk is a whole-file rewrite —
+      // the single biggest time sink in a build turn (1–2 min of regeneration
+      // vs seconds for an Edit). tool_use streams before the SDK executes the
+      // write, so existsSync here reflects the pre-write state.
+      let p = strOf(input.file_path);
+      if (p && this.fileExists(p)) this.wholeFileRewrites.push(basename(p));
+    } else if (tool === 'Bash') {
+      let cmd = strOf(input.command);
+      if (cmd && MUTATING_BASH.test(cmd)) {
+        this.mutatingBash.push(cmd.slice(0, 60));
+      }
+    } else if (tool.endsWith('screenshot_html')) {
+      this.screenshots += 1;
+    }
+  }
+
+  private fileExists(rel: string): boolean {
+    if (!this.workspaceDir) return false;
+    try {
+      return existsSync(join(this.workspaceDir, rel));
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Build the end-of-turn summary and log it — a `warn` with the concern
+   * list when anything is flagged, an `info` "no waste flags" otherwise.
+   * Returns the structured summary (for tests / callers).
+   */
+  finish(): TurnWasteSummary {
+    let totalCalls = 0;
+    for (let n of this.counts.values()) totalCalls += n;
+    let breakdown = [...this.counts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([t, n]) => `${t}:${n}`)
+      .join(' ');
+
+    let concerns: string[] = [];
+    let dupReads = [...this.reads.entries()].filter(([, n]) => n > 1);
+    if (dupReads.length > 0) {
+      concerns.push(
+        `${dupReads.length} file(s) re-read (${dupReads
+          .map(([p, n]) => `${basename(p)}×${n}`)
+          .join(', ')})`,
+      );
+    }
+    if (this.wholeFileRewrites.length > 0) {
+      concerns.push(
+        `${this.wholeFileRewrites.length} whole-file Write over an existing file — prefer Edit (${this.wholeFileRewrites.join(', ')})`,
+      );
+    }
+    if (this.screenshots > 4) {
+      concerns.push(`${this.screenshots} screenshots in one turn`);
+    }
+    if (this.mutatingBash.length > 0) {
+      concerns.push(
+        `${this.mutatingBash.length} mutating Bash call(s) — Bash should be read-only inspection`,
+      );
+    }
+
+    if (concerns.length > 0) {
+      log.warn(
+        `turn waste check — ${totalCalls} tool calls [${breakdown}] · ⚠ ${concerns.join('; ')}`,
+      );
+    } else if (totalCalls > 0) {
+      log.info(
+        `turn tool summary — ${totalCalls} tool calls [${breakdown}] · no waste flags`,
+      );
+    }
+    return { totalCalls, breakdown, concerns };
+  }
+}
diff --git a/packages/software-factory/src/factory-agent/claude-code.ts b/packages/software-factory/src/factory-agent/claude-code.ts
index 9a9aa80b5b6..ca044483811 100644
--- a/packages/software-factory/src/factory-agent/claude-code.ts
+++ b/packages/software-factory/src/factory-agent/claude-code.ts
@@ -58,9 +58,11 @@ import {
   type FactoryTool,
   type ToolCallEntry,
 } from '../factory-tool-builder.ts';
+import { TurnToolTelemetry } from './agent-tool-telemetry.ts';
 import { deriveCatalogRealmUrl } from '../factory-catalog-realm.ts';
 import { jsonSchemaToZodShape } from '../factory-tool-schema-adapter.ts';
 import { logger } from '../logger.ts';
+import { startSpan, traceEvent } from '../run-trace.ts';
 
 const MCP_SERVER_NAME = 'factory';
 const MAX_TOOL_USE_TURNS = 100;
@@ -130,11 +132,28 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
     let userPrompt = this.buildUserPrompt(context);
 
     let toolCallLog: ToolCallEntry[] = [];
+    let telemetry = new TurnToolTelemetry(this.config.workspaceDir);
+    let sessionId: string | undefined;
+    let usage: AgentRunResult['usage'];
+    // Running totals from per-assistant-message usage. The terminal
+    // `result` message is the authoritative source, but our signal-capture
+    // path aborts the query the moment the agent calls signal_done — the
+    // result message never arrives on ANY successful turn, so without this
+    // fallback every telemetry entry ships with no token counts at all.
+    let streamedUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 };
+    let sawStreamedUsage = false;
     let captured: CapturedSignal | undefined;
     let abortController = new AbortController();
 
     let sdkTools = buildSdkToolsFromFactoryTools(mcpFactoryTools, {
-      onToolCall: (entry) => toolCallLog.push(entry),
+      onToolCall: (entry) => {
+        toolCallLog.push(entry);
+        try {
+          context.onToolCall?.(entry);
+        } catch {
+          // Live-blog streaming must never break the run.
+        }
+      },
       onSignal: (signal) => {
         captured = signal;
         abortController.abort();
@@ -177,6 +196,15 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
     let options: Options = {
       systemPrompt,
       mcpServers: { [MCP_SERVER_NAME]: mcpServer },
+      // Per-turn model/thinking budget from the orchestrator's policy
+      // (fix iterations don't need the flagship model at full effort).
+      // Absent fields inherit the session default.
+      ...(context.modelBudget?.model
+        ? { model: context.modelBudget.model }
+        : {}),
+      ...(context.modelBudget?.effort
+        ? { effort: context.modelBudget.effort }
+        : {}),
       // When `workspaceDir` is configured, expose the SDK's native fs /
       // shell tools so the model can work on workspace files directly
       // (`Read` / `Write` / `Edit`) and run inspection helpers (`Bash`,
@@ -217,10 +245,25 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
       // relative-path commands (`cat sticky-note.gts`) inside the
       // workspace by default.
       ...(workspaceDir ? { cwd: workspaceDir } : {}),
-      // Isolate from the host user's Claude Code settings — we want
-      // deterministic agent behavior regardless of whose machine this
-      // runs on.
-      settingSources: [],
+      // Load PROJECT-level settings only: the factory materializes its
+      // skill catalog into `<workspace>/.claude/skills/` at run start
+      // (workspace-skills.ts), and 'project' lets the harness discover
+      // those the same way Claude Code discovers any project's skills —
+      // the model's trained lookup path. Deliberately NOT 'user'/'local':
+      // still isolated from the host user's own Claude settings, and the
+      // workspace lives under os.tmpdir() so no parent .claude can leak
+      // in. Without a workspaceDir there is no cwd to load from — keep
+      // the empty (fully isolated) behavior.
+      settingSources: workspaceDir ? ['project'] : [],
+      // Context forking (v2): resume a primed session, branching to a new
+      // session id so every fork inherits the primed conversation as a
+      // shared (provider-cached) prefix without mutating the original.
+      ...(context.resumeSession
+        ? {
+            resume: context.resumeSession.sessionId,
+            forkSession: context.resumeSession.fork !== false,
+          }
+        : {}),
       abortController,
       debug: this.config.debug === true,
     };
@@ -236,15 +279,113 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
         // once per factory run, guarded by `this.modelLogged`. Matches
         // the openrouter path's `Agent backend: openrouter (model=…)`
         // format for a single consistent log line across backends.
+        // Non-init system messages are SDK lifecycle overhead — compaction
+        // boundaries especially, which have shown up as multi-minute silent
+        // gaps inside turns. Mark them so the trace can attribute that time
+        // to SDK overhead rather than model work.
+        if (message.type === 'system') {
+          let subtype = (message as { subtype?: string }).subtype;
+          if (subtype && subtype !== 'init') {
+            traceEvent('inference', `sdk-${subtype}`);
+          }
+        }
         if (
-          !this.modelLogged &&
           message.type === 'system' &&
           (message as { subtype?: string }).subtype === 'init'
         ) {
-          let modelName = (message as { model?: string }).model;
-          if (modelName) {
-            log.info(`Agent backend: claude (model=${modelName})`);
-            this.modelLogged = true;
+          let initSessionId = (message as { session_id?: string }).session_id;
+          if (initSessionId) {
+            sessionId = initSessionId;
+          }
+          if (!this.modelLogged) {
+            let modelName = (message as { model?: string }).model;
+            if (modelName) {
+              log.info(`Agent backend: claude (model=${modelName})`);
+              this.modelLogged = true;
+            }
+          }
+        }
+        // Capture token/cost usage from the terminal result message so the
+        // orchestrator's turn telemetry can report what the turn cost.
+        if (message.type === 'result') {
+          let r = message as {
+            total_cost_usd?: number;
+            usage?: {
+              input_tokens?: number;
+              output_tokens?: number;
+              cache_read_input_tokens?: number;
+            };
+          };
+          usage = {
+            inputTokens: r.usage?.input_tokens,
+            outputTokens: r.usage?.output_tokens,
+            cacheReadTokens: r.usage?.cache_read_input_tokens,
+            costUsd: r.total_cost_usd,
+          };
+        }
+        // Accumulate per-call usage from each assistant message: summed
+        // input/cache-read reflects total billed tokens across the turn's
+        // API calls; summed output is total generated. Kept as a fallback
+        // for signal-aborted turns (see streamedUsage above).
+        if (message.type === 'assistant') {
+          let u = (
+            message as {
+              message?: {
+                usage?: {
+                  input_tokens?: number;
+                  output_tokens?: number;
+                  cache_read_input_tokens?: number;
+                };
+              };
+            }
+          ).message?.usage;
+          if (u) {
+            sawStreamedUsage = true;
+            streamedUsage.inputTokens += u.input_tokens ?? 0;
+            streamedUsage.outputTokens += u.output_tokens ?? 0;
+            streamedUsage.cacheReadTokens += u.cache_read_input_tokens ?? 0;
+          }
+        }
+        // Coarse activity heartbeat (v3 RunMonitor): every complete
+        // assistant message resets the stall clock. Silence between
+        // messages = the model is generating.
+        if (context.onActivity && message.type === 'assistant') {
+          try {
+            context.onActivity(
+              summarizeAssistantMessage(
+                message as { message: { content?: unknown } },
+              ).slice(0, 120),
+            );
+          } catch {
+            // Monitoring must never break the run.
+          }
+        }
+        // Record every streamed tool_use for the always-on waste audit, and
+        // stream native Write/Edit sightings to the live-blog hook as they
+        // land (MCP factory tools stream via buildSdkToolsFromFactoryTools).
+        if (message.type === 'assistant') {
+          try {
+            let content = (message as { message?: { content?: unknown } })
+              .message?.content;
+            if (Array.isArray(content)) {
+              for (let block of content) {
+                let b = block as {
+                  type?: string;
+                  name?: string;
+                  input?: Record<string, unknown>;
+                };
+                if (b?.type !== 'tool_use' || !b.name) continue;
+                telemetry.record(b.name, b.input ?? {});
+                if (
+                  context.onToolCall &&
+                  (b.name === 'Write' || b.name === 'Edit')
+                ) {
+                  context.onToolCall({ tool: b.name, args: b.input ?? {} });
+                }
+              }
+            }
+          } catch {
+            // Telemetry / live-blog streaming must never break the run.
           }
         }
         if (this.config.debug) {
@@ -255,17 +396,46 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
     } catch (error) {
       // An intentional abort from our signal-capture path is not an error.
       if (!captured) {
+        telemetry.finish();
         throw error;
       }
     }
 
+    // Always-on per-turn waste audit (re-reads, whole-file rewrites,
+    // screenshot thrash, mutating Bash). Emitted once per turn regardless of
+    // how the turn ended.
+    telemetry.finish();
+
+    // Signal-aborted turns never see the terminal result message — fall
+    // back to the streamed running totals so telemetry still gets tokens.
+    if (!usage && sawStreamedUsage) {
+      usage = streamedUsage;
+    }
+
+    // The terminal result message's usage and the per-assistant-message
+    // sums can differ (the terminal number has undercounted in practice).
+    // Emit both so the trace shows real token/cache traffic per turn.
+    if (sawStreamedUsage) {
+      traceEvent('inference', 'usage', {
+        sumIn: streamedUsage.inputTokens,
+        sumOut: streamedUsage.outputTokens,
+        sumCacheRead: streamedUsage.cacheReadTokens,
+        termIn: usage?.inputTokens,
+        termOut: usage?.outputTokens,
+        termCacheRead: usage?.cacheReadTokens,
+        costUsd: usage?.costUsd,
+      });
+    }
+
     if (captured?.kind === 'done') {
-      return { status: 'done', toolCalls: toolCallLog };
+      return { status: 'done', toolCalls: toolCallLog, sessionId, usage };
     }
     if (captured?.kind === 'clarification') {
       return {
         status: 'blocked',
         toolCalls: toolCallLog,
+        sessionId,
+        usage,
         message: captured.message,
       };
     }
@@ -276,6 +446,8 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
     return {
       status: toolCallLog.length > 0 ? 'done' : 'needs_iteration',
       toolCalls: toolCallLog,
+      sessionId,
+      usage,
     };
   }
 
@@ -382,6 +554,48 @@ export class ClaudeCodeFactoryAgent implements LoopAgent {
 
   private buildUserPrompt(context: AgentContext): string {
     let issueType = (context.issue as Record<string, unknown>).issueType;
+    if (context.primeTurn === true) {
+      return this.promptLoader.load('prime', {
+        project: context.project,
+        knowledge: context.knowledge,
+      });
+    }
+    if (context.acceptanceTurn) {
+      return this.promptLoader.load('acceptance-walkthrough', {
+        issue: context.issue,
+        // Only a real project card (URL id) is linkable from a defect
+        // issue — the 'bootstrap-pending' stub would serialize as a
+        // dangling relative link.
+        project: context.project?.id?.startsWith('http')
+          ? context.project
+          : undefined,
+        darkfactoryModuleUrl: requireDarkfactoryModuleUrl(context),
+        renderSummary: context.acceptanceTurn.renderSummary,
+        screenshots: context.acceptanceTurn.screenshots,
+        failedCaptures:
+          context.acceptanceTurn.failedCaptures.length > 0
+            ? context.acceptanceTurn.failedCaptures
+            : undefined,
+      });
+    }
+    if (issueType === 'design') {
+      // Design-foundation turn (hierarchical design): look & feel →
+      // brand guide + tokens.css → family coherence sheet. Runs once,
+      // after bootstrap, before every implementation issue.
+      return this.promptLoader.load('issue-design-foundation', {
+        issue: context.issue,
+        project: context.project,
+        knowledge: context.knowledge,
+      });
+    }
+    if (issueType === 'analysis') {
+      // Port-analysis research turn (v3 GitHub-port flow): study the
+      // source repo + media, write the port-background Knowledge Article.
+      return this.promptLoader.load('issue-analysis', {
+        issue: context.issue,
+        darkfactoryModuleUrl: requireDarkfactoryModuleUrl(context),
+      });
+    }
     if (issueType === 'bootstrap' && context.briefUrl) {
       return assembleBootstrapPrompt({
         context,
@@ -451,9 +665,17 @@ export function buildSdkToolsFromFactoryTools(
         let start = Date.now();
         let typedArgs = args as Record<string, unknown>;
         let result: unknown;
+        // Trace at the MCP dispatch point: this is where the claude
+        // backend's factory tools actually execute, so these spans carve
+        // in-turn tool time out of the surrounding `inference` span.
+        let endToolSpan = startSpan('tool', factoryTool.name);
         try {
           result = await factoryTool.execute(typedArgs);
+          endToolSpan({
+            ok: !(result && typeof result === 'object' && 'error' in result),
+          });
         } catch (error) {
+          endToolSpan({ ok: false });
           result = {
             error: error instanceof Error ? error.message : String(error),
           };
diff --git a/packages/software-factory/src/factory-agent/opencode.ts b/packages/software-factory/src/factory-agent/opencode.ts
index 48c0d4c1474..dfadf4e0bd3 100644
--- a/packages/software-factory/src/factory-agent/opencode.ts
+++ b/packages/software-factory/src/factory-agent/opencode.ts
@@ -54,6 +54,7 @@ import {
 } from '../factory-tool-builder.ts';
 import { deriveCatalogRealmUrl } from '../factory-catalog-realm.ts';
 import { logger } from '../logger.ts';
+import { startSpan } from '../run-trace.ts';
 import {
   assembleBootstrapPrompt,
   assembleImplementPrompt,
@@ -390,7 +391,12 @@ export class OpencodeFactoryAgent implements LoopAgent {
           body: {
             model: {
               providerID: FACTORY_PROVIDER_ID,
-              modelID: this.config.model,
+              // Per-turn budget override from the orchestrator's policy —
+              // any OpenRouter model id works here (e.g. `openai/gpt-5.2`,
+              // `moonshotai/kimi-k2`). `effort` has no opencode per-prompt
+              // equivalent yet, so only the model half of the budget
+              // applies on this backend.
+              modelID: context.modelBudget?.model ?? this.config.model,
             },
             system: systemPrompt,
             // Trim opencode's default tool catalog to only what the
@@ -570,9 +576,14 @@ async function startFactoryMcpServer(
     let typedArgs = (args ?? {}) as Record<string, unknown>;
     let start = Date.now();
     let result: unknown;
+    let endToolSpan = startSpan('tool', name);
     try {
       result = await tool.execute(typedArgs);
+      endToolSpan({
+        ok: !(result && typeof result === 'object' && 'error' in result),
+      });
     } catch (error) {
+      endToolSpan({ ok: false });
       result = {
         error: error instanceof Error ? error.message : String(error),
       };
diff --git a/packages/software-factory/src/factory-agent/types.ts b/packages/software-factory/src/factory-agent/types.ts
index 7d60327fc50..c1201514d2b 100644
--- a/packages/software-factory/src/factory-agent/types.ts
+++ b/packages/software-factory/src/factory-agent/types.ts
@@ -151,6 +151,7 @@ export interface TestResult {
 
 /** Steps in the post-iteration validation pipeline. */
 export type ValidationStep =
+  | 'imports'
   | 'parse'
   | 'lint'
   | 'evaluate'
@@ -249,6 +250,85 @@ export interface AgentContext {
    * See CS-10527.
    */
   enableBoxelUiDiscovery?: boolean;
+  /**
+   * V2 lean/design-first mode — implementation issues use the
+   * `issue-implement-v2` prompt (HTML-mockup design phase, no tests) and
+   * the lean skill core with on-demand `read_skill` loading.
+   */
+  v2?: boolean;
+  /**
+   * Context forking (v2): when set, the backend resumes this session —
+   * branching to a new session id when `fork` is true (the default) — so
+   * the turn inherits the primed conversation as a shared, provider-cached
+   * prefix instead of rebuilding context.
+   */
+  resumeSession?: { sessionId: string; fork?: boolean };
+  /**
+   * Prime turn (v2 context forking): use the `prime` prompt template —
+   * read the design language, skills, and precedent once; the session id
+   * captured from this turn seeds every subsequent fork.
+   */
+  primeTurn?: boolean;
+  /**
+   * Live streaming hook (v2 live blog): invoked for every factory MCP tool
+   * result as it lands, and for native Write/Edit tool_use blocks as they
+   * stream (result undefined for those). Must never throw — callers wrap
+   * it defensively, but keep handlers cheap and fire-and-forget.
+   */
+  onToolCall?: (entry: {
+    tool: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    durationMs?: number;
+  }) => void;
+  /**
+   * Coarse activity heartbeat (v3 RunMonitor): invoked with a short
+   * description for every backend stream event that isn't already an
+   * onToolCall — e.g. each complete assistant message on the Claude
+   * backend. Used only to reset the stall clock; silence between calls
+   * means the model is generating. Must never throw.
+   */
+  onActivity?: (desc: string) => void;
+  /**
+   * Phase-split (v2): which half of a split issue this turn is. 'design'
+   * turns produce accepted mockups + design notes only; 'build' turns
+   * translate them into card code, forked from the design session.
+   * Unset = the combined single-turn v2 flow.
+   */
+  phase?: 'design' | 'build';
+  /**
+   * Acceptance walkthrough (v3): when set, this turn is a post-completion
+   * VERIFIER pass, not an implementation turn — the agent reads the render
+   * gate's screenshots, verdicts each acceptance criterion (visible
+   * affordance required), files defect issues for gaps, and posts
+   * needs-human-verify items. Selects the `acceptance-walkthrough` prompt.
+   */
+  acceptanceTurn?: {
+    renderSummary: string;
+    screenshots: {
+      cardPath: string;
+      format: string;
+      outputPath: string;
+      suspectBlank?: boolean;
+    }[];
+    failedCaptures: {
+      cardPath: string;
+      format: string;
+      error: string;
+    }[];
+  };
+  /**
+   * Model/thinking budget for THIS turn, chosen by the orchestrator's
+   * policy (turn type — prime / bootstrap / build / fix), not by the
+   * issue. Undefined fields inherit the session default. Note: provider
+   * prompt cache is per-model, so a budget that switches model re-ingests
+   * a forked prime prefix uncached (usually still cheaper on a smaller
+   * model).
+   */
+  modelBudget?: {
+    model?: string;
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  };
 }
 
 export interface AgentAction {
@@ -296,6 +376,20 @@ export interface AgentRunResult {
   toolCalls: LoopToolCallEntry[];
   /** Clarification message when status is 'blocked'. */
   message?: string;
+  /** Backend session id for this turn (claude backend) — fork seed for v2 context forking. */
+  sessionId?: string;
+  /**
+   * Token/cost usage for this turn when the backend reports it (the Claude
+   * SDK's terminal `result` message). Absent when the turn was aborted by
+   * a control signal before the result message arrived. Consumed by the
+   * v3 RunMonitor's turn-telemetry entries.
+   */
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    costUsd?: number;
+  };
 }
 
 /**
diff --git a/packages/software-factory/src/factory-brief.ts b/packages/software-factory/src/factory-brief.ts
index 5d86ca1a1f1..395a697198c 100644
--- a/packages/software-factory/src/factory-brief.ts
+++ b/packages/software-factory/src/factory-brief.ts
@@ -23,6 +23,17 @@ export interface FactoryBrief {
    * `sourceCardUrl` attribute (see `realm/wiki.gts`).
    */
   sourceCardUrl?: string;
+  /**
+   * Set when `--brief-url` pointed at a GitHub repository instead of a
+   * Boxel brief card (v3 port flow). The brief is synthesized from the
+   * repo's metadata + README, and the seed step adds a PORT-ANALYSIS
+   * issue ahead of bootstrap: a research turn that pulls the repo's
+   * README, screenshots, and demo media, reads them, and writes the
+   * "port background" Knowledge Article (feature inventory, screen
+   * catalogue, data model, better-than-the-original rubric) that
+   * bootstrap then plans the card family from.
+   */
+  githubRepoUrl?: string;
 }
 
 interface BoxelBriefCardInfo {
@@ -55,10 +66,125 @@ export class FactoryBriefError extends Error {
   }
 }
 
+/**
+ * Parse a GitHub repository URL (`https://github.com/<owner>/<repo>[/...]`).
+ * Returns undefined for anything else — including GitHub URLs that aren't
+ * repo roots we can analyze (gists keep their own flow via a normal brief).
+ */
+export function parseGitHubRepoUrl(
+  sourceUrl: string,
+): { owner: string; repo: string } | undefined {
+  let url: URL;
+  try {
+    url = new URL(sourceUrl);
+  } catch {
+    return undefined;
+  }
+  if (url.hostname !== 'github.com' && url.hostname !== 'www.github.com') {
+    return undefined;
+  }
+  let [owner, repo] = url.pathname.split('/').filter(Boolean);
+  if (!owner || !repo) {
+    return undefined;
+  }
+  return { owner, repo: repo.replace(/\.git$/, '') };
+}
+
+/** Keep synthesized briefs bounded — a monster README isn't a better brief. */
+const GITHUB_README_MAX_CHARS = 30_000;
+
+/**
+ * Synthesize a FactoryBrief from a GitHub repository: repo metadata (name,
+ * description) via the GitHub API plus the README raw content. Anonymous
+ * fetches — public repos only; a private repo surfaces as a brief error.
+ */
+export async function loadGitHubBrief(
+  sourceUrl: string,
+  options?: FactoryBriefLoadOptions,
+): Promise<FactoryBrief> {
+  let parsed = parseGitHubRepoUrl(sourceUrl);
+  if (!parsed) {
+    throw new FactoryBriefError(`Not a GitHub repository URL: ${sourceUrl}`);
+  }
+  let { owner, repo } = parsed;
+  let fetchFn = options?.fetch ?? globalThis.fetch;
+  let repoUrl = `https://github.com/${owner}/${repo}`;
+
+  let description: string | undefined;
+  let repoName = repo;
+  try {
+    let metaResponse = await fetchFn(
+      `https://api.github.com/repos/${owner}/${repo}`,
+      { headers: { accept: 'application/vnd.github+json' } },
+    );
+    if (metaResponse.ok) {
+      let meta = (await metaResponse.json()) as {
+        name?: string;
+        description?: string | null;
+      };
+      if (meta.name) repoName = meta.name;
+      if (meta.description) description = meta.description;
+    }
+  } catch {
+    // Metadata is best-effort; the README and the analysis issue carry the run.
+  }
+
+  let readme = '';
+  try {
+    let readmeResponse = await fetchFn(
+      `https://api.github.com/repos/${owner}/${repo}/readme`,
+      { headers: { accept: 'application/vnd.github.raw+json' } },
+    );
+    if (readmeResponse.ok) {
+      readme = (await readmeResponse.text()).slice(0, GITHUB_README_MAX_CHARS);
+    }
+  } catch {
+    // A repo with no reachable README still ports — the analysis issue digs.
+  }
+
+  let title = repoName
+    .split(/[-_]+/g)
+    .filter(Boolean)
+    .map((segment) => segment[0].toUpperCase() + segment.slice(1))
+    .join(' ');
+  let contentSummary =
+    description ?? `Port of the ${repoUrl} application to Boxel.`;
+  let content = [
+    `# Port ${title} to Boxel`,
+    '',
+    `Source repository: ${repoUrl}`,
+    description ? `\n${description}\n` : '',
+    '## Repository README',
+    '',
+    readme ||
+      '(README could not be fetched — the port-analysis issue must recover it.)',
+  ].join('\n');
+
+  return {
+    title: `Port: ${title}`,
+    sourceUrl,
+    content,
+    contentSummary,
+    tags: ['github-port'],
+    githubRepoUrl: repoUrl,
+  };
+}
+
 export async function loadFactoryBrief(
   sourceUrl: string,
   options?: FactoryBriefLoadOptions,
 ): Promise<FactoryBrief> {
+  // Briefs are OUR authored content (Boxel wiki cards). A GitHub repo is
+  // source material for an inspired-by port — a different input with its
+  // own flag. Catch the mix-up here with a pointer instead of a JSON
+  // parse error.
+  if (parseGitHubRepoUrl(sourceUrl)) {
+    throw new FactoryBriefError(
+      `${sourceUrl} is a GitHub repository, not a brief card. ` +
+        `Use --repo-url for inspired-by ports of a GitHub project.`,
+    );
+  }
+
   let headers = { accept: SupportedMimeType.CardSource };
   let response: Response;
 
diff --git a/packages/software-factory/src/factory-context-builder.ts b/packages/software-factory/src/factory-context-builder.ts
index 5979201be50..286b1fd92ec 100644
--- a/packages/software-factory/src/factory-context-builder.ts
+++ b/packages/software-factory/src/factory-context-builder.ts
@@ -14,6 +14,11 @@ import {
   type SkillLoaderInterface,
   type SkillResolver,
 } from './factory-skill-loader.ts';
+import { buildHostToolsSkill } from './host-import-manifest.ts';
+import { logger } from './logger.ts';
+import { startSpan } from './run-trace.ts';
+
+let log = logger('factory-context-builder');
 
 // ---------------------------------------------------------------------------
 // Issue relationship loader
@@ -50,6 +55,16 @@ export interface ContextBuilderConfig {
    * See CS-10527.
    */
   enableBoxelUiDiscovery?: boolean;
+  /** V2 lean/design-first mode — carried onto every AgentContext. */
+  v2?: boolean;
+  /**
+   * Valid `@cardstack/boxel-host/tools/<name>` module names derived from
+   * the host build (v3 import gate). When set, every built context gains
+   * a generated `host-tools-import-manifest` skill so the agent writes
+   * imports against the real catalogue instead of its prior — the
+   * `commands/`→`tools/` rename failure class.
+   */
+  hostToolImports?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -62,6 +77,8 @@ export class ContextBuilder {
   private maxSkillTokens: number | undefined;
   private issueLoader: IssueRelationshipLoader | undefined;
   private enableBoxelUiDiscovery: boolean;
+  private v2: boolean;
+  private hostToolImports: string[] | undefined;
 
   constructor(config: ContextBuilderConfig) {
     this.skillResolver = config.skillResolver;
@@ -69,6 +86,20 @@ export class ContextBuilder {
     this.maxSkillTokens = config.maxSkillTokens;
     this.issueLoader = config.issueLoader;
     this.enableBoxelUiDiscovery = config.enableBoxelUiDiscovery === true;
+    this.v2 = config.v2 === true;
+    this.hostToolImports = config.hostToolImports;
+  }
+
+  /**
+   * The generated host-tools manifest skill, appended AFTER the budget
+   * trim: it's the authoritative import catalogue and must never be the
+   * thing the token budget drops.
+   */
+  private withGeneratedSkills(skills: ResolvedSkill[]): ResolvedSkill[] {
+    if (!this.hostToolImports || this.hostToolImports.length === 0) {
+      return skills;
+    }
+    return [...skills, buildHostToolsSkill(this.hostToolImports)];
   }
 
   /**
@@ -102,7 +133,9 @@ export class ContextBuilder {
     );
 
     // Step 3: Enforce token budget if configured
-    skills = enforceSkillBudget(skills, this.maxSkillTokens);
+    skills = this.withGeneratedSkills(
+      enforceSkillBudget(skills, this.maxSkillTokens),
+    );
 
     // Step 4: Assemble the context
     let context: AgentContext = {
@@ -112,6 +145,7 @@ export class ContextBuilder {
       skills,
       targetRealm,
       enableBoxelUiDiscovery: this.enableBoxelUiDiscovery,
+      v2: this.v2,
       ...(darkfactoryModuleUrl ? { darkfactoryModuleUrl } : {}),
     };
 
@@ -149,25 +183,62 @@ export class ContextBuilder {
       );
     }
 
+    let endContextSpan = startSpan('context', 'build-for-issue', {
+      issue: String(params.issue.id).split('/').filter(Boolean).pop(),
+    });
+    try {
+      return await this.#buildForIssueInner(params);
+    } finally {
+      endContextSpan();
+    }
+  }
+
+  async #buildForIssueInner(params: {
+    issue: IssueData;
+    targetRealm: string;
+    darkfactoryModuleUrl?: string;
+    validationResults?: ValidationResults;
+    validationContext?: string;
+    briefUrl?: string;
+  }): Promise<AgentContext> {
     let { issue, targetRealm, darkfactoryModuleUrl } = params;
 
+    // Re-assert for the type system — the public wrapper already threw if
+    // the loader is missing.
+    let issueLoader = this.issueLoader;
+    if (!issueLoader) {
+      throw new Error(
+        'buildForIssue() requires an issueLoader in ContextBuilderConfig',
+      );
+    }
+
     // Step 1: Traverse issue relationships
     let [project, knowledge] = await Promise.all([
-      this.issueLoader.loadProject(issue),
-      this.issueLoader.loadKnowledge(issue),
+      issueLoader.loadProject(issue),
+      issueLoader.loadKnowledge(issue),
     ]);
 
     if (!project) {
-      // Bootstrap issues have no project yet — the agent creates it.
-      // Supply a minimal stub so AgentContext.project stays required.
+      // A missing project link is normal on several paths — bootstrap
+      // (the agent creates the Project), PORT-0 analysis (runs ahead of
+      // bootstrap by blockedBy design), and agent-authored issues like
+      // the acceptance walkthrough's auto-filed defects, whose JSON may
+      // omit relationships entirely. Throwing here killed a whole run
+      // over one unlinked defect issue (wardrobe, 2026-07-17); the
+      // project is orientation context, not a correctness requirement,
+      // so degrade to a stub and log instead. AgentContext.project stays
+      // required.
       let issueType = (issue as Record<string, unknown>).issueType;
-      if (issueType === 'bootstrap') {
-        project = { id: 'bootstrap-pending' };
-      } else {
-        throw new Error(
-          `Issue "${issue.id}" has no linked project — cannot build context`,
+      if (
+        issueType !== 'bootstrap' &&
+        issueType !== 'analysis' &&
+        issueType !== 'design'
+      ) {
+        log.warn(
+          `Issue "${issue.id}" has no linked project — building context with a stub`,
         );
       }
+      project = { id: 'bootstrap-pending' };
     }
 
     // Step 2: Resolve and load skills
@@ -178,7 +249,9 @@ export class ContextBuilder {
     );
 
     // Step 3: Enforce token budget if configured
-    skills = enforceSkillBudget(skills, this.maxSkillTokens);
+    skills = this.withGeneratedSkills(
+      enforceSkillBudget(skills, this.maxSkillTokens),
+    );
 
     // Step 4: Assemble the context
     let context: AgentContext = {
@@ -188,6 +261,7 @@ export class ContextBuilder {
       skills,
       targetRealm,
       enableBoxelUiDiscovery: this.enableBoxelUiDiscovery,
+      v2: this.v2,
       ...(darkfactoryModuleUrl ? { darkfactoryModuleUrl } : {}),
     };
 
diff --git a/packages/software-factory/src/factory-entrypoint.ts b/packages/software-factory/src/factory-entrypoint.ts
index e93736d877b..df36ea774f1 100644
--- a/packages/software-factory/src/factory-entrypoint.ts
+++ b/packages/software-factory/src/factory-entrypoint.ts
@@ -2,17 +2,27 @@ import { parseArgs as parseNodeArgs } from 'node:util';
 
 import { BoxelCLIClient } from '@cardstack/boxel-cli/api';
 
+import {
+  ControlPlaneSync,
+  ensureControlPlaneIgnoreFile,
+  ensureScratchIgnoreFile,
+} from './control-plane-sync.ts';
 import {
   linkBoardToRealmIndex,
   writeRealmDashboardCard,
   type LinkBoardToRealmIndexOptions,
 } from './factory-realm-index.ts';
 import { inferDarkfactoryModuleUrl } from './factory-seed.ts';
+import { initRunTrace, withSpan } from './run-trace.ts';
 import {
   parseAgentFlag,
   type FactoryAgentProvider,
 } from './factory-agent/index.ts';
-import { loadFactoryBrief, type FactoryBrief } from './factory-brief.ts';
+import {
+  loadFactoryBrief,
+  loadGitHubBrief,
+  type FactoryBrief,
+} from './factory-brief.ts';
 import { FactoryEntrypointUsageError } from './factory-entrypoint-errors.ts';
 import {
   assertAgentProviderImplemented,
@@ -49,8 +59,26 @@ let log = logger('factory-entrypoint');
 const BOOTSTRAP_LINK_SEARCH_RETRIES = 5;
 
 export interface FactoryEntrypointOptions {
-  briefUrl: string;
+  /**
+   * A Boxel brief card URL — OUR authored content describing what to
+   * build. Exactly one of `briefUrl` / `repoUrl` is required.
+   */
+  briefUrl?: string;
+  /**
+   * A GitHub repository URL for an inspired-by port (v3). The factory
+   * synthesizes the brief from the repo and seeds a PORT-ANALYSIS issue
+   * that digs into the repo's code — dependencies, specialized logic,
+   * tests and fixtures — before bootstrap plans anything.
+   */
+  repoUrl?: string;
   targetRealm: string | null;
+  /**
+   * Control realm (v3 split): issues, tracker cards, validations, and the
+   * run log live here; the target realm keeps only the built product.
+   * Created if missing, like the target realm. Null = no split (v2
+   * behavior — everything in the target realm).
+   */
+  controlRealm?: string | null;
   realmServerUrl: string | null;
   agent: FactoryAgentProvider;
   /** Only set when agent === 'openrouter' and the flag carried a `=<id>` suffix. */
@@ -77,6 +105,42 @@ export interface FactoryEntrypointOptions {
    * Set via `--enable-boxel-ui-discovery` on the CLI.
    */
   enableBoxelUiDiscovery?: boolean;
+  /** V2 lean/design-first mode (see factory-issue-loop-wiring). */
+  v2?: boolean;
+  /** Context forking: prime once per brief, fork every implementation turn. */
+  forkContext?: boolean;
+  /**
+   * Model for fix iterations (inner iterations ≥ 2 — mechanical lint/parse
+   * fix-ups). Defaults to `claude-sonnet-5` under --v2; pass `inherit` to
+   * keep the session model for every turn.
+   */
+  fixModel?: string;
+  /** Effort for fix iterations (low|medium|high|xhigh|max). Default `medium` under --v2. */
+  fixEffort?: string;
+  /**
+   * Phase-split: run each implementation issue as a DESIGN turn
+   * (flagship budget) + a BUILD turn (cheap budget) forked from the
+   * design session. DEFAULT ON under --v2 (v3); `--no-phase-split`
+   * opts out. Explicit `--phase-split` forces it on.
+   */
+  phaseSplit?: boolean;
+  /**
+   * Render gate + acceptance walkthrough (v3 P0): post-issue screenshot
+   * capture via `_screenshot-card` and a verifier turn that reads the
+   * PNGs, verdicts acceptance criteria, and files defect issues. Default
+   * on under --v2; `--no-render-gate` opts out.
+   */
+  renderGate?: boolean;
+  /** Model for phase-split build turns. Default `claude-sonnet-5`; `inherit` keeps the session model. */
+  buildModel?: string;
+  /** Effort for phase-split build turns. Default `medium`. */
+  buildEffort?: string;
+  /**
+   * Orchestrator monitor level (v3, requires --v2): quiet | normal |
+   * verbose. Default `normal` — stall narration, per-turn telemetry,
+   * scheduler notes, and sync failures on the run log.
+   */
+  monitorLevel?: 'quiet' | 'normal' | 'verbose';
 }
 
 export interface FactoryEntrypointAction {
@@ -187,13 +251,26 @@ export function getFactoryEntrypointUsage(): string {
   return [
     'Usage:',
     '  pnpm factory:go --brief-url <url> --target-realm <realm> [options]',
+    '  pnpm factory:go --repo-url <github url> --target-realm <realm> [options]',
     '',
-    'Required:',
-    '  --brief-url <url>           Absolute URL for the source brief card',
+    'Required (exactly one of --brief-url / --repo-url, plus --target-realm):',
+    '  --brief-url <url>           Absolute URL for the source brief card (your authored content)',
+    '  --repo-url <url>            GitHub repository URL for an inspired-by port. Seeds a',
+    '                              PORT-ANALYSIS issue ahead of bootstrap that clones the repo,',
+    '                              reads its media AND code (dependencies, specialized logic,',
+    '                              tests + fixtures), and writes the port background + code',
+    '                              analysis Knowledge Articles bootstrap plans from.',
     '  --target-realm <realm>      Target realm (URL form, e.g. http://localhost:4201/me/realm/)',
     '',
     'Options:',
     '  --realm-server-url <url>   Realm server URL (default: from active Boxel profile)',
+    '  --control-realm <realm>     Control realm for the v3 control/product split. Issues,',
+    '                              tracker cards, validation artifacts, and the run log live',
+    '                              here (raw-written, immune to the atomic FieldDef strip);',
+    '                              the target realm keeps only the built product — so product',
+    '                              .gts updates never invalidate the run log the operator is',
+    '                              watching, and control churn never re-runs product queries.',
+    '                              Created if missing. Omit for v2 single-realm behavior.',
     '  --no-retry-blocked          Skip retrying blocked issues (by default, blocked issues are reset to backlog)',
     '  --agent <provider>          LLM backend: "claude" (default, uses Claude Code Agent SDK),',
     '                              "codex" (not yet implemented),',
@@ -207,6 +284,16 @@ export function getFactoryEntrypointUsage(): string {
     '                              backend falls back to the realm server passthrough at',
     '                              `/_openrouter/chat/completions` — burns boxel tokens.',
     '  --debug                     Log LLM prompts and responses to stderr',
+    '  --no-phase-split            Disable the v3 default phase-split (DESIGN turn on the',
+    '                              flagship model + BUILD turn on claude-sonnet-5, forked).',
+    '                              Only meaningful with --v2, where phase-split is on by default.',
+    '  --no-render-gate            Skip the v3 render gate + acceptance walkthrough (post-issue',
+    '                              _screenshot-card captures and the verifier turn that reads',
+    '                              them, verdicts acceptance criteria, and files defect issues).',
+    '  --monitor-level <level>     Orchestrator monitor verbosity on the run log (requires --v2):',
+    '                              "quiet" (stalls + failures only), "normal" (default — adds',
+    '                              per-turn telemetry and scheduler notes), "verbose" (adds turn',
+    '                              starts, heals, and sync successes).',
     '  --enable-boxel-ui-discovery Make the agent search the catalog for @cardstack/boxel-ui',
     '                              component Spec cards before writing UI in a .gts template.',
     '                              When omitted, the agent has no awareness of boxel-ui',
@@ -239,9 +326,15 @@ export function parseFactoryEntrypointArgs(
         'brief-url': {
           type: 'string',
         },
+        'repo-url': {
+          type: 'string',
+        },
         'target-realm': {
           type: 'string',
         },
+        'control-realm': {
+          type: 'string',
+        },
         'realm-server-url': {
           type: 'string',
         },
@@ -263,6 +356,36 @@ export function parseFactoryEntrypointArgs(
         'enable-boxel-ui-discovery': {
           type: 'boolean',
         },
+        v2: {
+          type: 'boolean',
+        },
+        'fork-context': {
+          type: 'boolean',
+        },
+        'fix-model': {
+          type: 'string',
+        },
+        'fix-effort': {
+          type: 'string',
+        },
+        'phase-split': {
+          type: 'boolean',
+        },
+        'no-phase-split': {
+          type: 'boolean',
+        },
+        'no-render-gate': {
+          type: 'boolean',
+        },
+        'build-model': {
+          type: 'string',
+        },
+        'build-effort': {
+          type: 'string',
+        },
+        'monitor-level': {
+          type: 'string',
+        },
       },
     });
   } catch (error) {
@@ -276,7 +399,26 @@ export function parseFactoryEntrypointArgs(
     );
   }
 
-  let briefUrl = requireStringValue(parsed.values['brief-url'], '--brief-url');
+  let rawBriefUrl =
+    typeof parsed.values['brief-url'] === 'string' &&
+    parsed.values['brief-url'].trim() !== ''
+      ? parsed.values['brief-url']
+      : undefined;
+  let rawRepoUrl =
+    typeof parsed.values['repo-url'] === 'string' &&
+    parsed.values['repo-url'].trim() !== ''
+      ? parsed.values['repo-url']
+      : undefined;
+  if (!rawBriefUrl && !rawRepoUrl) {
+    throw new FactoryEntrypointUsageError(
+      'Missing required input: pass --brief-url <brief card> (your authored content) or --repo-url <github repo> (inspired-by port).',
+    );
+  }
+  if (rawBriefUrl && rawRepoUrl) {
+    throw new FactoryEntrypointUsageError(
+      '--brief-url and --repo-url are mutually exclusive — a run has one source.',
+    );
+  }
   let targetRealm = requireStringValue(
     parsed.values['target-realm'],
     '--target-realm',
@@ -307,17 +449,166 @@ export function parseFactoryEntrypointArgs(
   }
 
   return {
-    briefUrl: normalizeUrl(briefUrl, '--brief-url'),
+    briefUrl: rawBriefUrl
+      ? normalizeUrl(rawBriefUrl, '--brief-url')
+      : undefined,
+    repoUrl: rawRepoUrl ? normalizeUrl(rawRepoUrl, '--repo-url') : undefined,
     targetRealm: normalizeUrl(targetRealm, '--target-realm'),
+    controlRealm:
+      typeof parsed.values['control-realm'] === 'string'
+        ? normalizeUrl(parsed.values['control-realm'], '--control-realm')
+        : null,
     realmServerUrl,
     agent: parsedAgent.provider,
     openRouterModel: parsedAgent.openRouterModel,
     openRouterApiKey,
     debug: parsed.values.debug === true ? true : undefined,
     retryBlocked: parsed.values['no-retry-blocked'] === true ? false : true,
+    // V2 turns boxel-ui discovery on by default — the design-first loop
+    // must search the catalog before hand-rolling UI.
     enableBoxelUiDiscovery:
-      parsed.values['enable-boxel-ui-discovery'] === true ? true : undefined,
+      parsed.values['enable-boxel-ui-discovery'] === true ||
+      parsed.values.v2 === true
+        ? true
+        : undefined,
+    v2: parsed.values.v2 === true ? true : undefined,
+    forkContext: parsed.values['fork-context'] === true ? true : undefined,
+    fixModel:
+      typeof parsed.values['fix-model'] === 'string'
+        ? parsed.values['fix-model']
+        : undefined,
+    fixEffort:
+      typeof parsed.values['fix-effort'] === 'string'
+        ? parsed.values['fix-effort']
+        : undefined,
+    // Tri-state: --no-phase-split wins; explicit --phase-split forces on;
+    // otherwise undefined lets the v2 default (on) apply downstream.
+    phaseSplit:
+      parsed.values['no-phase-split'] === true
+        ? false
+        : parsed.values['phase-split'] === true
+          ? true
+          : undefined,
+    renderGate: parsed.values['no-render-gate'] === true ? false : undefined,
+    buildModel:
+      typeof parsed.values['build-model'] === 'string'
+        ? parsed.values['build-model']
+        : undefined,
+    buildEffort:
+      typeof parsed.values['build-effort'] === 'string'
+        ? parsed.values['build-effort']
+        : undefined,
+    monitorLevel: parseMonitorLevel(parsed.values['monitor-level']),
+  };
+}
+
+function parseMonitorLevel(
+  raw: unknown,
+): 'quiet' | 'normal' | 'verbose' | undefined {
+  if (typeof raw !== 'string') return undefined;
+  if (raw === 'quiet' || raw === 'normal' || raw === 'verbose') {
+    return raw;
+  }
+  throw new FactoryEntrypointUsageError(
+    `Invalid --monitor-level: "${raw}". Valid values: quiet, normal, verbose.`,
+  );
+}
+
+/**
+ * Turn the CLI's budget flags into the loop's model policy. Orchestrator-
+ * owned: budgets key off turn TYPE (prime/bootstrap/build/fix), never off
+ * issue content.
+ *
+ * Cache-family heuristic (why the default tunes EFFORT, not model):
+ * provider prompt cache is per-model. Switching a fork turn to another
+ * model re-ingests the whole primed prefix uncached — roughly
+ *   cost_switch ≈ prefix_tokens × input_price(new)
+ *   savings     ≈ turn_tokens × (price(old) − price(new))
+ * Fix turns are short (small turn_tokens) against a large primed prefix,
+ * so in-family effort reduction wins: same model keeps the cache hit AND
+ * effort='medium'/'low' cuts the thinking that dominated profiled turns.
+ * Cross-family switching only pays when the turn's output is large
+ * relative to the prefix (e.g. bulk BUILD emission) — that's an explicit
+ * `--fix-model <model>` opt-in, never the default.
+ *
+ * v2 default: fix iterations (mechanical lint/parse fix-ups) inherit the
+ * session model at effort='medium'. `--fix-effort low|...` tunes it;
+ * `--fix-model claude-sonnet-5` (or an OpenRouter id under the opencode
+ * backend) opts into a family switch; `--fix-model inherit --fix-effort
+ * high` effectively disables the policy.
+ */
+type TurnBudget = {
+  model?: string;
+  effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+};
+
+function normalizeEffort(
+  value: string | undefined,
+  fallback: 'low' | 'medium' | 'high' | 'xhigh' | 'max',
+): 'low' | 'medium' | 'high' | 'xhigh' | 'max' {
+  return value && ['low', 'medium', 'high', 'xhigh', 'max'].includes(value)
+    ? (value as 'low' | 'medium' | 'high' | 'xhigh' | 'max')
+    : fallback;
+}
+
+export function buildModelPolicy(options: {
+  v2?: boolean;
+  fixModel?: string;
+  fixEffort?: string;
+  phaseSplit?: boolean;
+  buildModel?: string;
+  buildEffort?: string;
+}):
+  | {
+      design?: TurnBudget;
+      build?: TurnBudget;
+      fix?: TurnBudget;
+      acceptance?: TurnBudget;
+    }
+  | undefined {
+  if (options.v2 !== true) return undefined;
+
+  // Fix turns: short output vs a big primed prefix — in-family effort
+  // reduction wins (cache preserved); family switch is explicit opt-in.
+  let fixModel =
+    options.fixModel === 'inherit' || options.fixModel === undefined
+      ? undefined
+      : options.fixModel;
+  let policy: {
+    design?: TurnBudget;
+    build?: TurnBudget;
+    fix?: TurnBudget;
+    acceptance?: TurnBudget;
+  } = {
+    fix: {
+      ...(fixModel ? { model: fixModel } : {}),
+      effort: normalizeEffort(options.fixEffort, 'medium'),
+    },
+    // Review turn (PM gate): deliberately NOT budgeted — it inherits the
+    // session flagship. The reviewer makes taste + product judgments
+    // (ship / bounce / reprioritize the backlog) that the cheap tier
+    // shipped false verdicts on; a fresh unforked context has no
+    // cache-family concern either way. (Operator directive 2026-07-17:
+    // review is the powerful model's job.)
   };
+
+  // Phase-split build turns: LARGE output (the .gts emissions) — the one
+  // turn type where a family switch beats the cache re-ingest cost, so
+  // the default IS a switch (claude-sonnet-5 @ medium). DESIGN keeps the
+  // session flagship (taste turn) unless a future --design-* flag says
+  // otherwise.
+  if (options.phaseSplit === true) {
+    let buildModel =
+      options.buildModel === 'inherit'
+        ? undefined
+        : (options.buildModel ?? 'claude-sonnet-5');
+    policy.build = {
+      ...(buildModel ? { model: buildModel } : {}),
+      effort: normalizeEffort(options.buildEffort, 'medium'),
+    };
+  }
+
+  return policy;
 }
 
 export function wantsFactoryEntrypointHelp(argv: string[]): boolean {
@@ -344,14 +635,48 @@ export async function runFactoryEntrypoint(
 
   let client = new BoxelCLIClient();
 
-  let brief = await loadFactoryBrief(options.briefUrl, {
-    client,
-    fetch: dependencies?.fetch,
-  });
+  // One source per run: a brief card (our authored content) or a GitHub
+  // repo (inspired-by port — the analysis issue does the deep reading).
+  let brief = await withSpan('startup', 'load-brief', undefined, () =>
+    options.repoUrl
+      ? loadGitHubBrief(options.repoUrl, { fetch: dependencies?.fetch })
+      : loadFactoryBrief(requireBriefSource(options), {
+          client,
+          fetch: dependencies?.fetch,
+        }),
+  );
+  // Downstream (run slug, loop config, bootstrap prompt) keys off one
+  // source URL regardless of which flag provided it.
+  let briefSourceUrl = brief.sourceUrl;
+
+  let targetRealm = await withSpan(
+    'startup',
+    'bootstrap-target-realm',
+    undefined,
+    () =>
+      (dependencies?.bootstrapTargetRealm ?? bootstrapFactoryTargetRealm)(
+        targetRealmResolution,
+      ),
+  );
 
-  let targetRealm = await (
-    dependencies?.bootstrapTargetRealm ?? bootstrapFactoryTargetRealm
-  )(targetRealmResolution);
+  // v3 control/product split: resolve + bootstrap the control realm the
+  // same way as the target (created if missing). A control realm equal to
+  // the target degenerates to the single-realm v2 flow.
+  let controlRealmUrl: string | undefined;
+  if (options.controlRealm) {
+    let controlResolution = (
+      dependencies?.resolveTargetRealm ?? resolveFactoryTargetRealm
+    )({
+      targetRealm: options.controlRealm,
+      realmServerUrl: options.realmServerUrl,
+    });
+    let controlRealm = await (
+      dependencies?.bootstrapTargetRealm ?? bootstrapFactoryTargetRealm
+    )(controlResolution);
+    if (controlRealm.url !== targetRealm.url) {
+      controlRealmUrl = controlRealm.url;
+    }
+  }
 
   let darkfactoryModuleUrl = inferDarkfactoryModuleUrl(targetRealm.url);
 
@@ -374,23 +699,70 @@ export async function runFactoryEntrypoint(
     log.info(`Workspace directory: ${workspaceDir}`);
   }
 
+  // Span-trace telemetry for the whole run (see run-trace.ts for the
+  // schema). Spans recorded before this point were buffered and flush now.
+  initRunTrace({
+    workspaceDir,
+    tags: {
+      targetRealm: targetRealm.url,
+      controlRealm: controlRealmUrl,
+      brief: briefSourceUrl,
+      v2: options.v2 === true,
+    },
+  });
+
   let pullTargetRealm = dependencies?.pullTargetRealm ?? defaultPullTargetRealm;
-  await pullTargetRealm(client, targetRealm.url, workspaceDir);
+  await withSpan('startup', 'pull-target-realm', undefined, () =>
+    pullTargetRealm(client, targetRealm.url, workspaceDir),
+  );
 
-  // For a realm the factory just created, replace the default CardsGrid
-  // index page with a RealmDashboard instance so the realm opens to the
-  // factory dashboard. A pre-existing realm keeps its current index page.
-  if (targetRealm.createdRealm) {
+  // `.factory-scratch/` (the port-analysis turn's download area) never
+  // syncs anywhere — always ignored, split or not.
+  await ensureScratchIgnoreFile(workspaceDir);
+
+  // Under the split: exclude control-plane paths from the product atomic
+  // sync (BEFORE the first sync below), then pull the control realm's
+  // control-plane files into the shared workspace so resume runs see
+  // prior issues/run logs.
+  let controlSync: ControlPlaneSync | undefined;
+  if (controlRealmUrl) {
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    controlSync = new ControlPlaneSync({
+      client,
+      controlRealm: controlRealmUrl,
+      workspaceDir,
+    });
+    await withSpan('startup', 'pull-control-realm', undefined, () =>
+      controlSync!.pull(),
+    );
+  }
+
+  // Legacy single-realm mode only: replace the default CardsGrid index
+  // with a RealmDashboard so the realm opens to the factory dashboard.
+  // Under the control/product split the PRODUCT realm keeps its stock
+  // index — the product realm is the user's deliverable, not a factory
+  // surface (operator directive 2026-07-17: no custom workspace/home
+  // card per build; the stock grid shows the product cards, and a
+  // future out-of-box workspace.gts with pinning/readme replaces
+  // per-build home customization). Tracking surfaces live in the
+  // control realm.
+  if (targetRealm.createdRealm && !controlRealmUrl) {
     let writeRealmIndex =
       dependencies?.writeRealmIndex ?? writeRealmDashboardCard;
     await writeRealmIndex(workspaceDir, targetRealm.url);
   }
 
   // Create the seed issue locally
-  let seedResult = await (dependencies?.createSeed ?? createSeedIssue)(brief, {
-    darkfactoryModuleUrl,
-    workspaceDir,
-  });
+  let seedResult = await withSpan('seed', 'create-seed', undefined, () =>
+    (dependencies?.createSeed ?? createSeedIssue)(brief, {
+      darkfactoryModuleUrl,
+      workspaceDir,
+      // v2: hierarchical design — a design-foundation issue (brand guide,
+      // tokens, family coherence sheet) runs between bootstrap and the
+      // implementation issues.
+      designFoundation: options.v2 === true,
+    }),
+  );
 
   // Push the freshly-written seed (and any other pre-existing workspace
   // state) to the realm. `defaultSyncWorkspaceToRealm` uses
@@ -402,6 +774,19 @@ export async function runFactoryEntrypoint(
     dependencies?.syncWorkspaceToRealm ?? defaultSyncWorkspaceToRealm;
   await syncWorkspaceToRealm(client, targetRealm.url, workspaceDir);
 
+  // Under the split the seed issue is a control-plane file — excluded from
+  // the product sync above — so push it to the control realm now. Raw
+  // writes don't wait for indexing; the loop wiring bounded-polls
+  // listIssues before starting.
+  if (controlSync) {
+    let controlPush = await controlSync.sync();
+    if (!controlPush.ok) {
+      throw new Error(
+        `Initial control-plane sync failed — the seed issue may not have reached the control realm: ${controlPush.error ?? 'unknown error'}`,
+      );
+    }
+  }
+
   // Wire the artifacts the bootstrap issue creates into the realm. The
   // bootstrap agent makes an IssueTracker board and a Project; the index card
   // and seed issue were both written before those existed, so they start with
@@ -420,9 +805,12 @@ export async function runFactoryEntrypoint(
     // result: the hook is the only wiring a run that stalls or is interrupted
     // before the backstop ever gets, so it can't afford to lose that race.
     let searchRetries = waitForIndex ? BOOTSTRAP_LINK_SEARCH_RETRIES : 0;
+    // Under the split the bootstrap agent's IssueTracker/Project land in
+    // the CONTROL realm: search there, and write the index card's board
+    // link as an absolute URL (index.json lives in the product realm).
     let linkArgs = {
       client,
-      realmUrl: targetRealm.url,
+      realmUrl: controlRealmUrl ?? targetRealm.url,
       workspaceDir,
       darkfactoryModuleUrl,
       searchRetries,
@@ -431,12 +819,22 @@ export async function runFactoryEntrypoint(
     // and share no state, so run them concurrently. When the realm has
     // neither card yet, each search otherwise burns its full retry budget in
     // turn; overlapping them halves the worst-case wait.
+    // Under the split the product realm keeps its STOCK index (no
+    // dashboard was written), so there is no board relationship to patch
+    // — skip linkBoard entirely; only the seed issue's project link (a
+    // control-plane file) still gets wired.
     let [boardLinked, projectLinked] = await Promise.all([
-      linkBoard(linkArgs),
+      controlRealmUrl
+        ? Promise.resolve(false)
+        : linkBoard({ ...linkArgs, absoluteLink: false }),
       linkSeedProject(linkArgs),
     ]);
     if (boardLinked || projectLinked) {
       await syncWorkspaceToRealm(client, targetRealm.url, workspaceDir);
+      // The seed issue's project link is a control-plane change.
+      if (controlSync) {
+        await controlSync.sync();
+      }
     }
   };
 
@@ -447,11 +845,17 @@ export async function runFactoryEntrypoint(
     seedResult,
   );
 
+  // v3: phase-split is the default economics under --v2 (design on the
+  // flagship, build on the cheap model, forked). --no-phase-split opts out.
+  let phaseSplit = options.phaseSplit ?? options.v2 === true;
+
   // Run the issue-driven loop
   let loopFn = dependencies?.runIssueLoop ?? runFactoryIssueLoop;
   let loopResult = await loopFn({
-    briefUrl: options.briefUrl,
+    briefUrl: briefSourceUrl,
     targetRealm: targetRealm.url,
+    controlRealm: controlRealmUrl,
+    controlSync,
     realmServerUrl: targetRealm.serverUrl,
     ownerUsername: targetRealm.ownerUsername,
     client,
@@ -462,6 +866,13 @@ export async function runFactoryEntrypoint(
     debug: options.debug,
     retryBlocked: options.retryBlocked,
     enableBoxelUiDiscovery: options.enableBoxelUiDiscovery,
+    v2: options.v2,
+    runTitle: brief.title,
+    forkContext: options.forkContext,
+    modelPolicy: buildModelPolicy({ ...options, phaseSplit }),
+    phaseSplit,
+    renderGate: options.renderGate,
+    monitorLevel: options.monitorLevel,
     // Wire the board and the seed issue's project the moment the bootstrap
     // issue finishes, rather than after the whole loop returns — so a run
     // whose later issues stall or get interrupted still ends up with the
@@ -628,6 +1039,15 @@ async function defaultSyncWorkspaceToRealm(
   }
 }
 
+function requireBriefSource(options: FactoryEntrypointOptions): string {
+  if (options.briefUrl) {
+    return options.briefUrl;
+  }
+  throw new FactoryEntrypointUsageError(
+    'Missing required input: pass --brief-url <brief card> or --repo-url <github repo>.',
+  );
+}
+
 function requireStringValue(
   value: string | boolean | undefined,
   flagName: string,
diff --git a/packages/software-factory/src/factory-issue-loop-wiring.ts b/packages/software-factory/src/factory-issue-loop-wiring.ts
index a2722d7aa96..486bb180cd4 100644
--- a/packages/software-factory/src/factory-issue-loop-wiring.ts
+++ b/packages/software-factory/src/factory-issue-loop-wiring.ts
@@ -33,6 +33,19 @@ import {
 import { ContextBuilder } from './factory-context-builder.ts';
 import { inferDarkfactoryModuleUrl } from './factory-seed.ts';
 import { DefaultSkillResolver, SkillLoader } from './factory-skill-loader.ts';
+import {
+  ControlPlaneSync,
+  ensureControlPlaneIgnoreFile,
+} from './control-plane-sync.ts';
+import {
+  defaultHostToolsDir,
+  deriveHostToolImports,
+} from './host-import-manifest.ts';
+import { retryWithPoll } from './retry-with-poll.ts';
+import { startSpan, withSpan } from './run-trace.ts';
+import { RenderGate } from './render-gate.ts';
+import { RunLogWriter } from './run-log.ts';
+import { RunMonitor, type MonitorLevel } from './run-monitor.ts';
 import {
   buildFactoryTools,
   type FactoryTool,
@@ -49,6 +62,7 @@ import {
 import { RealmIssueStore, type IssueStore } from './issue-scheduler.ts';
 import { RealmIssueRelationshipLoader } from './realm-issue-relationship-loader.ts';
 import { withStdoutRedirected } from './redirect-stdout.ts';
+import { materializeWorkspaceSkills } from './workspace-skills.ts';
 
 let log = logger('factory-issue-loop-wiring');
 
@@ -103,6 +117,75 @@ export interface IssueLoopWiringConfig {
    * awareness of boxel-ui components. See CS-10527.
    */
   enableBoxelUiDiscovery?: boolean;
+  /**
+   * V2 lean/design-first mode: lean skill core + on-demand read_skill,
+   * HTML-mockup design phase in the implement prompt, and no QUnit step
+   * in the validation pipeline (tests move to a later hardening phase).
+   * Also turns boxel-ui discovery on unless explicitly disabled upstream.
+   */
+  v2?: boolean;
+  /** Brief title — names the live-blog RunLog card (v2). */
+  runTitle?: string;
+  /** Context forking (v2): prime once, fork every implementation turn. */
+  forkContext?: boolean;
+  /** Per-turn model/effort budget policy (orchestrator-owned; see IssueLoopConfig). */
+  modelPolicy?: {
+    prime?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    bootstrap?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    design?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    build?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    fix?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    acceptance?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+  };
+  /** Phase-split (v2): design turn + build turn per issue (see IssueLoopConfig). */
+  phaseSplit?: boolean;
+  /**
+   * Orchestrator monitor level (v3). Applies only under v2 (needs the run
+   * log). 'normal' (default) posts stall narration, turn telemetry,
+   * scheduler notes, and sync failures; 'verbose' adds turn starts, heals,
+   * and sync successes; 'quiet' keeps stalls + failures only.
+   */
+  monitorLevel?: MonitorLevel;
+  /**
+   * Control realm (v3 split): issues, tracker cards, validation artifacts,
+   * and the run log live here; the product (`targetRealm`) keeps only the
+   * built defs + instances. When set (and different from the target
+   * realm), control-plane paths are excluded from the product atomic sync
+   * via `.boxelignore` and raw-written to this realm instead — which also
+   * makes the entire control plane immune to the /_atomic FieldDef strip.
+   * Unset = v2 behavior (everything in the target realm).
+   */
+  controlRealm?: string;
+  /**
+   * Share the entrypoint's ControlPlaneSync (with its pushed-hash state)
+   * instead of constructing a fresh one — avoids re-pushing every control
+   * file at loop start. Only meaningful when `controlRealm` is set.
+   */
+  controlSync?: ControlPlaneSync;
+  /**
+   * Render gate + acceptance walkthrough (v3 P0). On by default under
+   * `v2`; pass false to skip the post-issue screenshot capture and the
+   * verifier turn (e.g. deployments without a prerenderer).
+   */
+  renderGate?: boolean;
   /**
    * Invoked once, right after the bootstrap issue completes. The entrypoint
    * uses this to link the realm index's `board` relationship as soon as the
@@ -124,15 +207,52 @@ export async function runFactoryIssueLoop(
   let client = config.client;
   let workspaceDir = config.workspaceDir;
 
-  // 1. Issue store
+  // v3 control/product split: when a distinct control realm is configured,
+  // issues / tracker / validations / run log live there and are raw-written
+  // (never atomic-synced); the target realm keeps only the product.
+  let controlRealm = config.controlRealm
+    ? ensureTrailingSlash(config.controlRealm)
+    : targetRealm;
+  let split = controlRealm !== targetRealm;
+  let controlSync: ControlPlaneSync | undefined;
+  if (split) {
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    controlSync =
+      config.controlSync ??
+      new ControlPlaneSync({ client, controlRealm, workspaceDir });
+    log.info(`Control/product split active: control realm=${controlRealm}`);
+  }
+
+  // Materialize the skill catalog into `<workspace>/.claude/skills/` so
+  // agents can look skills up the way Claude Code does — native
+  // Glob/Grep/Read over real files (searchable, instinct-aligned) —
+  // instead of only through the read_skill MCP tool. Dotdirs never sync
+  // to the realm. Best-effort by design.
+  await withSpan('skills', 'materialize', undefined, () =>
+    materializeWorkspaceSkills(workspaceDir),
+  );
+
+  // 1. Issue store — reads/writes the control realm under the split.
   let darkfactoryModuleUrl = inferDarkfactoryModuleUrl(targetRealm);
   let issueStore = new RealmIssueStore({
-    realmUrl: targetRealm,
+    realmUrl: controlRealm,
     darkfactoryModuleUrl,
     client,
     workspaceDir,
   });
 
+  // Under the split the seed issue reaches the control realm via raw
+  // writes, which don't wait for indexing — bounded-poll so the loop's
+  // first listIssues doesn't race the indexer and exit "all done, 0
+  // issues". (The non-split path pushes with waitForIndex instead.)
+  if (split) {
+    await retryWithPoll(
+      () => issueStore.listIssues(),
+      (issues) => issues.length === 0,
+      { totalWaitMs: 20_000, pollMs: 1_000 },
+    );
+  }
+
   // 1b. Retry blocked issues (default on, opt out with --no-retry-blocked)
   if (config.retryBlocked) {
     await retryBlockedIssues(issueStore);
@@ -141,15 +261,29 @@ export async function runFactoryIssueLoop(
   // 2. Context builder with issue relationship loader
   let issueLoader = new RealmIssueRelationshipLoader({
     workspaceDir,
-    realmUrl: targetRealm,
+    realmUrl: controlRealm,
   });
+  // v3 import gate: derive the host-tools catalogue from the host source
+  // in this checkout, once per run. Feeds BOTH sides of the gate — the
+  // generated manifest skill in every agent context, and the static
+  // `imports` validation step. Degrades to no gate when the host source
+  // isn't present (undefined).
+  let hostToolImports = await withSpan(
+    'manifest',
+    'host-imports',
+    undefined,
+    () => deriveHostToolImports(defaultHostToolsDir(PACKAGE_ROOT)),
+  );
   let contextBuilder = new ContextBuilder({
     skillResolver: new DefaultSkillResolver({
       enableBoxelUiDiscovery: config.enableBoxelUiDiscovery === true,
+      v2: config.v2 === true,
     }),
     skillLoader: new SkillLoader(),
     issueLoader,
     enableBoxelUiDiscovery: config.enableBoxelUiDiscovery === true,
+    v2: config.v2 === true,
+    hostToolImports,
   });
 
   // 3. Tool infrastructure
@@ -195,11 +329,72 @@ export async function runFactoryIssueLoop(
   // through this `syncWorkspace`, so the loop can read `getSyncElapsedMs()` to
   // attribute tool-triggered sync time to sync rather than agent time.
   let syncElapsedMs = 0;
+  // Every sync goes through the corrupting /_atomic?waitForIndex path,
+  // which strips containsMany FieldDef data from card sources — including
+  // the run-log instance whenever ANY sync uploads it (agent-triggered
+  // run_* tool syncs included, and conflict re-uploads after out-of-band
+  // raw writes). Set once the RunLogWriter exists; runs after every
+  // successful sync so the live blog can never stay stripped.
+  let postSyncHeal: (() => Promise<void>) | undefined;
+  // Set once the RunMonitor exists (v2 only) — watchdog notes for sync
+  // failures (normal level) and heals/successes (verbose).
+  let monitor: RunMonitor | undefined;
   let syncWorkspace = async () => {
     let start = Date.now();
+    let endSyncSpan = startSpan('sync', 'workspace');
     try {
-      return await syncGate.sync();
+      // Product sync (atomic; control paths excluded via .boxelignore under
+      // the split), then the control-plane raw-write sync. Both must land
+      // for the composite to report ok — the loop refuses to mark issues
+      // done on a failed sync, and that guarantee has to cover both realms.
+      let endProductSpan = startSpan('sync', 'product');
+      let result = await syncGate.sync();
+      endProductSpan({ ok: result.ok });
+      if (controlSync) {
+        let endControlSpan = startSpan('sync', 'control');
+        let controlResult = await controlSync.sync();
+        endControlSpan({ ok: controlResult.ok });
+        if (!controlResult.ok) {
+          result = {
+            ok: false,
+            error: [
+              result.ok ? undefined : result.error,
+              `control-plane sync: ${controlResult.error ?? 'unknown error'}`,
+            ]
+              .filter(Boolean)
+              .join('; '),
+          };
+        }
+      }
+      if (!result.ok) {
+        monitor?.noteWatchdog(
+          'sync-failed',
+          'Workspace sync to the realm failed',
+          {
+            body: `${result.error ?? 'unknown error'} — the loop retries on the next turn; the issue cannot be marked done until a sync lands.`,
+            failure: true,
+          },
+        );
+      }
+      // Heal is only needed when the run log rides the atomic sync path
+      // (no split). Under the split the run log is raw-written to the
+      // control realm and never exposed to the FieldDef strip.
+      if (result.ok && postSyncHeal && !split) {
+        try {
+          await postSyncHeal();
+          monitor?.noteWatchdog(
+            'heal',
+            'Run-log instance healed after sync (atomic FieldDef-strip workaround)',
+          );
+        } catch {
+          // Healing is best-effort; never fail a sync over it.
+        }
+      }
+      endSyncSpan({ ok: result.ok });
+      return result;
     } finally {
+      // Idempotent close: a throw path lands here with the span still open.
+      endSyncSpan({ error: true });
       syncElapsedMs += Date.now() - start;
     }
   };
@@ -263,11 +458,50 @@ export async function runFactoryIssueLoop(
       issueId,
       fetchFilenames: (realmUrl: string) => client.listFiles(realmUrl),
       cache: validationCache,
+      includeTestStep: config.v2 !== true,
+      hostToolImports,
     });
 
   // 6. Run issue loop
   log.info(`Starting issue loop: targetRealm=${targetRealm}`);
 
+  let runLog: RunLogWriter | undefined;
+  if (config.v2 === true) {
+    let runSlug = (config.briefUrl.split('/').pop() ?? 'factory-run')
+      .replace(/\.json$/i, '')
+      .toLowerCase();
+    runLog = new RunLogWriter({
+      workspaceDir,
+      targetRealm,
+      controlRealm,
+      runSlug,
+      runTitle: config.runTitle ?? runSlug,
+      syncWorkspace,
+      // Streamed appends raw-write straight to the realm that hosts the
+      // run log — the control realm under the split.
+      rawWriteFile: (relativePath, content) =>
+        client.write(controlRealm, relativePath, content),
+    });
+    let createdRunLog = runLog;
+    postSyncHeal = () => createdRunLog.healInstance();
+    monitor = new RunMonitor({
+      runLog,
+      level: config.monitorLevel ?? 'normal',
+    });
+  }
+
+  // Render gate (v3 P0): on by default under v2 — the runtime feedback
+  // loop is the point of v3, so skipping it is the explicit opt-out.
+  let renderGate: RenderGate | undefined;
+  if (config.v2 === true && config.renderGate !== false) {
+    renderGate = new RenderGate({
+      client,
+      realmServerUrl,
+      targetRealm,
+      workspaceDir,
+    });
+  }
+
   let issueLoopConfig: IssueLoopConfig = {
     agent,
     contextBuilder,
@@ -275,10 +509,17 @@ export async function runFactoryIssueLoop(
     issueStore,
     createValidator,
     targetRealm,
+    controlRealm,
     darkfactoryModuleUrl,
     workspaceDir,
     syncWorkspace,
     briefUrl: config.briefUrl,
+    runLog,
+    monitor,
+    renderGate,
+    modelPolicy: config.modelPolicy,
+    phaseSplit: config.phaseSplit === true,
+    forkContext: config.forkContext === true,
     maxIterationsPerIssue: config.maxIterationsPerIssue,
     maxOuterCycles: config.maxOuterCycles,
     debug: config.debug,
@@ -287,8 +528,10 @@ export async function runFactoryIssueLoop(
   };
 
   try {
+    monitor?.start();
     return await runIssueLoop(issueLoopConfig);
   } finally {
+    monitor?.stop();
     // Some agents (notably `OpencodeFactoryAgent`) hold persistent
     // backend state across iterations — long-lived opencode subprocess
     // + MCP server + JWT'd HTTP client. Tear that down here so a
diff --git a/packages/software-factory/src/factory-prompt-loader.ts b/packages/software-factory/src/factory-prompt-loader.ts
index cc3d0b7ea35..b31c436159e 100644
--- a/packages/software-factory/src/factory-prompt-loader.ts
+++ b/packages/software-factory/src/factory-prompt-loader.ts
@@ -423,6 +423,29 @@ export function assembleSystemPrompt(
  * Includes tool results when present (e.g., after invoke_tool actions
  * from a prior plan() call that returned tool invocations before implementation).
  */
+/**
+ * Issue types that FIX broken behavior on a card that already shipped
+ * (as opposed to building a new one). These skip the design round — no
+ * mockups, no critique — and use the diagnose-and-fix prompt. Defects filed
+ * by the acceptance walkthrough carry `defect`; the rest are defensive
+ * synonyms a bootstrap agent might emit.
+ */
+const BUG_FIX_ISSUE_TYPES = new Set([
+  'defect',
+  'bug',
+  'regression',
+  'hotfix',
+  'fix',
+]);
+
+/** True for a bug-fix issue — see BUG_FIX_ISSUE_TYPES. */
+export function isBugFixIssue(
+  issue: { issueType?: string } | undefined,
+): boolean {
+  let t = issue?.issueType;
+  return typeof t === 'string' && BUG_FIX_ISSUE_TYPES.has(t.toLowerCase());
+}
+
 export function assembleImplementPrompt(
   options: AssembleImplementPromptOptions,
 ): string {
@@ -430,7 +453,21 @@ export function assembleImplementPrompt(
 
   let toolResultsData = buildToolResultsData(context);
 
-  return loader.load('issue-implement', {
+  // Prompt selection. Bug-fix issues take a diagnose-and-fix prompt with no
+  // design round (the card already shipped; only its behavior is broken).
+  // Otherwise, phase-split (v2) gives the design and build turns dedicated
+  // prompts; an unsplit v2 turn keeps the combined design-first prompt.
+  let template =
+    context.v2 === true
+      ? isBugFixIssue(context.issue as { issueType?: string })
+        ? 'issue-fix-v2'
+        : context.phase === 'design'
+          ? 'issue-design-v2'
+          : context.phase === 'build'
+            ? 'issue-build-v2'
+            : 'issue-implement-v2'
+      : 'issue-implement';
+  return loader.load(template, {
     project: context.project,
     issue: context.issue,
     knowledge: context.knowledge,
@@ -448,10 +485,16 @@ export function assembleBootstrapPrompt(
 ): string {
   let { context, loader } = options;
 
-  return loader.load('bootstrap-implement', {
-    briefUrl: context.briefUrl,
-    issue: context.issue,
-  });
+  // v2's bootstrap variant strips the QUnit/test requirements — the v2
+  // pipeline runs no tests, and baking them into issue descriptions made
+  // agents write .test.gts despite the skill's no-tests hard rule.
+  return loader.load(
+    context.v2 === true ? 'bootstrap-implement-v2' : 'bootstrap-implement',
+    {
+      briefUrl: context.briefUrl,
+      issue: context.issue,
+    },
+  );
 }
 
 /**
diff --git a/packages/software-factory/src/factory-realm-index.ts b/packages/software-factory/src/factory-realm-index.ts
index 6e82bd5e2ca..8d0c3c310c1 100644
--- a/packages/software-factory/src/factory-realm-index.ts
+++ b/packages/software-factory/src/factory-realm-index.ts
@@ -129,6 +129,13 @@ export interface LinkBoardToRealmIndexOptions {
   searchRetries?: number;
   /** Delay between empty-result retries. Defaults to `SEARCH_RETRY_DELAY_MS`. */
   searchRetryDelayMs?: number;
+  /**
+   * Write the board link as an absolute card URL instead of a
+   * realm-relative `./path`. Required under the v3 control/product split:
+   * the index card lives in the product realm while the IssueTracker
+   * board lives in the control realm, so a relative link would dangle.
+   */
+  absoluteLink?: boolean;
 }
 
 /**
@@ -167,7 +174,10 @@ export async function linkBoardToRealmIndex(
         // board and the seed issue's project stay on the same generation.
         sort: [{ by: 'lastModified', direction: 'desc' as const }],
       }),
-    buildLink: (id, realm) => `./${toRealmRelativePath(id, realm)}`,
+    buildLink: (id, realm) =>
+      options.absoluteLink === true
+        ? id
+        : `./${toRealmRelativePath(id, realm)}`,
     log,
     searchRetries: options.searchRetries,
     searchRetryDelayMs: options.searchRetryDelayMs,
diff --git a/packages/software-factory/src/factory-seed.ts b/packages/software-factory/src/factory-seed.ts
index 6e0b027650d..de9df210f21 100644
--- a/packages/software-factory/src/factory-seed.ts
+++ b/packages/software-factory/src/factory-seed.ts
@@ -20,7 +20,11 @@ import {
   linkRelationshipToCard,
   toRealmRelativePath,
 } from './realm-operations.ts';
-import { readCard, writeCard } from './workspace-fs.ts';
+import {
+  readCard,
+  writeCard,
+  type WorkspaceReadResult,
+} from './workspace-fs.ts';
 
 /**
  * Infer the darkfactory module URL from a target realm URL.
@@ -50,6 +54,16 @@ export interface SeedIssueOptions {
    * issue loop starts picking issues.
    */
   workspaceDir: string;
+  /**
+   * v2/v3: also seed a DESIGN-FOUNDATION issue (blockedBy bootstrap,
+   * blocking every implementation issue) that establishes the shared
+   * design language BEFORE any card is designed: overall look & feel →
+   * brand guide with guiding words + CSS variables → a one-sheet simple
+   * pass over every card in the family. Coherence first, detail later
+   * (operator directive 2026-07-17); per-card design turns consume its
+   * artifacts as binding context.
+   */
+  designFoundation?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -58,6 +72,10 @@ export interface SeedIssueOptions {
 
 const SEED_ISSUE_PATH = 'Issues/bootstrap-seed';
 const SEED_ISSUE_FILE = `${SEED_ISSUE_PATH}.json`;
+const ANALYSIS_ISSUE_PATH = 'Issues/port-analysis-seed';
+const ANALYSIS_ISSUE_FILE = `${ANALYSIS_ISSUE_PATH}.json`;
+export const DESIGN_FOUNDATION_ISSUE_PATH = 'Issues/design-foundation-seed';
+const DESIGN_FOUNDATION_ISSUE_FILE = `${DESIGN_FOUNDATION_ISSUE_PATH}.json`;
 
 // ---------------------------------------------------------------------------
 // Main
@@ -75,26 +93,118 @@ export async function createSeedIssue(
   brief: FactoryBrief,
   options: SeedIssueOptions,
 ): Promise<SeedIssueResult> {
-  let { darkfactoryModuleUrl, workspaceDir } = options;
+  let { darkfactoryModuleUrl, workspaceDir, designFoundation } = options;
 
   // The factory entrypoint pulls the target realm into `workspaceDir`
   // before calling us, so a pre-existing seed shows up locally.
   let existing = await readCard(workspaceDir, SEED_ISSUE_FILE);
-  if (existing.ok) {
-    log.info(`Seed issue already exists at ${SEED_ISSUE_FILE}`);
-    return { issueId: SEED_ISSUE_PATH, status: 'existing' };
-  }
-
-  // Anything other than "file missing" is a real problem — surface it.
-  if (existing.status !== 404) {
+  // Anything other than "found" or "file missing" is a real problem — surface it.
+  if (!existing.ok && existing.status !== 404) {
     throw new Error(
       `Failed to check for existing seed issue: ${existing.error ?? 'unknown error'}`,
     );
   }
 
+  // Resume vs re-arm. On a restart the entrypoint pulls the control realm
+  // into this workspace FIRST, so a seed a prior turn already completed is
+  // sitting here at status `done`. Blindly re-writing it to `backlog` makes
+  // the loop redo finished work — the operator watched the PORT-ANALYSIS
+  // issue re-run a repo study whose Knowledge Articles were already written
+  // (2026-07-17). So: if a done seed belongs to the CURRENT brief, leave it
+  // intact and let the loop resume from the board. Still overwrite when the
+  // brief CHANGED — that's the sequential multi-brief pass the LOCAL PATCH
+  // note below is about (a done seed from a *different* brief must re-arm).
+  let bootstrapResume = seedMatchesAndDone(existing, brief.sourceUrl);
+
   let document = buildSeedIssueDocument(brief, darkfactoryModuleUrl);
 
-  log.info(`Creating seed issue at ${SEED_ISSUE_FILE}`);
+  // GitHub-port flow (v3): a PORT-ANALYSIS issue runs before bootstrap —
+  // it studies the source repo (README, screenshots, demo media, code
+  // layout) and writes the port-background Knowledge Article that
+  // bootstrap plans the card family from. Bootstrap is blockedBy it.
+  if (brief.githubRepoUrl) {
+    let existingAnalysis = await readCard(workspaceDir, ANALYSIS_ISSUE_FILE);
+    if (seedMatchesAndDone(existingAnalysis, brief.githubRepoUrl)) {
+      log.info(
+        `Port-analysis seed already done for ${brief.githubRepoUrl} — leaving it intact so the loop resumes from the board instead of re-running the repo study`,
+      );
+    } else {
+      let analysisDocument = buildAnalysisSeedIssueDocument(
+        brief,
+        darkfactoryModuleUrl,
+      );
+      let analysisWrite = await writeCard(
+        workspaceDir,
+        ANALYSIS_ISSUE_FILE,
+        JSON.stringify(analysisDocument, null, 2),
+      );
+      if (!analysisWrite.ok) {
+        throw new Error(
+          `Failed to create port-analysis seed issue: ${analysisWrite.error ?? 'unknown error'}`,
+        );
+      }
+      log.info(`Port-analysis seed issue created: ${ANALYSIS_ISSUE_PATH}`);
+    }
+  }
+
+  // Design-foundation phase (v2/v3): runs after bootstrap, before every
+  // implementation issue. Establishes the design language once so all
+  // per-card design turns inherit it — coherence first, detail later.
+  if (designFoundation) {
+    let existingFoundation = await readCard(
+      workspaceDir,
+      DESIGN_FOUNDATION_ISSUE_FILE,
+    );
+    // The foundation seed carries no brief token of its own, so tie its
+    // resume to bootstrap's: same brief + already done ⇒ keep it, don't
+    // re-arm. A changed brief re-arms bootstrap and the foundation with it.
+    if (bootstrapResume && isDone(existingFoundation)) {
+      log.info(
+        `Design-foundation seed already done — leaving it intact (resume, not re-arm)`,
+      );
+    } else {
+      let foundationDocument = buildDesignFoundationSeedIssueDocument(
+        brief,
+        darkfactoryModuleUrl,
+      );
+      let foundationWrite = await writeCard(
+        workspaceDir,
+        DESIGN_FOUNDATION_ISSUE_FILE,
+        JSON.stringify(foundationDocument, null, 2),
+      );
+      if (!foundationWrite.ok) {
+        throw new Error(
+          `Failed to create design-foundation seed issue: ${foundationWrite.error ?? 'unknown error'}`,
+        );
+      }
+      log.info(
+        `Design-foundation seed issue created: ${DESIGN_FOUNDATION_ISSUE_PATH}`,
+      );
+    }
+  }
+
+  // Bootstrap itself: a done seed for the current brief stays done so the
+  // loop picks up wherever the board left off.
+  if (bootstrapResume) {
+    log.info(
+      `Bootstrap seed already done for this brief — leaving it intact; the loop will resume from the board`,
+    );
+    return { issueId: SEED_ISSUE_PATH, status: 'existing' };
+  }
+
+  // LOCAL PATCH (CS-12192): the seed path is a realm-wide constant, so a
+  // second `factory:go` against an already-bootstrapped realm would find the
+  // *previous* run's stale seed here. We overwrite it with the current brief
+  // so each run bootstraps its own brief; `buildSeedIssueDocument` stamps
+  // status=backlog, re-arming a seed a prior brief left done/blocked. The
+  // resume guard above already spared a *matching-brief* done seed, so this
+  // path only fires for a new/changed brief or a never-completed seed. Not
+  // an upstream change.
+  log.info(
+    existing.ok
+      ? `Overwriting existing seed issue at ${SEED_ISSUE_FILE} with current brief`
+      : `Creating seed issue at ${SEED_ISSUE_FILE}`,
+  );
   let writeResult = await writeCard(
     workspaceDir,
     SEED_ISSUE_FILE,
@@ -107,7 +217,11 @@ export async function createSeedIssue(
     );
   }
 
-  log.info(`Seed issue created: ${SEED_ISSUE_PATH}`);
+  log.info(
+    existing.ok
+      ? `Seed issue overwritten: ${SEED_ISSUE_PATH}`
+      : `Seed issue created: ${SEED_ISSUE_PATH}`,
+  );
   return { issueId: SEED_ISSUE_PATH, status: 'created' };
 }
 
@@ -179,6 +293,34 @@ export async function linkProjectToSeedIssue(
   });
 }
 
+// ---------------------------------------------------------------------------
+// Resume guard
+// ---------------------------------------------------------------------------
+
+/** True when a pulled seed card is present and its status is `done`. */
+function isDone(read: WorkspaceReadResult): boolean {
+  if (!read.ok || !read.document) return false;
+  let attrs = (
+    read.document.data as { attributes?: Record<string, unknown> } | undefined
+  )?.attributes;
+  return attrs?.status === 'done';
+}
+
+/**
+ * True when a pulled seed is `done` AND belongs to the CURRENT brief. The
+ * identity token (the brief's source/repo URL) is embedded verbatim in the
+ * seed's summary/description, so a substring check distinguishes "resume this
+ * brief" (keep the done seed) from "a prior brief left a done seed here"
+ * (re-arm — the sequential multi-brief pass). An empty token never matches.
+ */
+function seedMatchesAndDone(
+  read: WorkspaceReadResult,
+  identityToken: string,
+): boolean {
+  if (!identityToken || !isDone(read)) return false;
+  return JSON.stringify(read.document).includes(identityToken);
+}
+
 // ---------------------------------------------------------------------------
 // Document builder
 // ---------------------------------------------------------------------------
@@ -208,7 +350,34 @@ function buildSeedIssueDocument(
     ? adjustSeedInstructions(brief)
     : greenfieldSeedInstructions();
 
-  let description = [...briefHeader, ...instructions].join('\n');
+  let port = Boolean(brief.githubRepoUrl);
+  let portNote = port
+    ? [
+        `## Port background (read first)`,
+        ``,
+        `A PORT-ANALYSIS issue ran before this one. Its output — TWO`,
+        `Knowledge Articles linked on this issue via \`relatedKnowledge\` —`,
+        `is the AUTHORITATIVE background for this port:`,
+        ``,
+        `- **port-background** — feature inventory, screen catalogue, UX`,
+        `  flows, the "better than the original" rubric, and the proposed`,
+        `  Boxel card-family mapping.`,
+        `- **port-code-analysis** — the original's architecture, dependency`,
+        `  map with Boxel-side answers, specialized logic inventory (incl.`,
+        `  verbatim AI prompt templates), the data model as implemented,`,
+        `  and the PORTED TEST CONTRACT (assertions + fixtures mined from`,
+        `  the original's tests).`,
+        ``,
+        `Plan the card family from THESE articles, not just the README`,
+        `excerpt above. Carry the rubric into the Project's success`,
+        `criteria; quote the ported test contract in each implementation`,
+        `issue's acceptance criteria; use the mined fixtures as the shapes`,
+        `for sample instances.`,
+        ``,
+      ]
+    : [];
+
+  let description = [...briefHeader, ...portNote, ...instructions].join('\n');
 
   return {
     data: {
@@ -220,6 +389,87 @@ function buildSeedIssueDocument(
         issueType: 'bootstrap',
         status: 'backlog',
         priority: 'critical',
+        order: port ? 1 : 0,
+        acceptanceCriteria,
+        createdAt: now,
+        updatedAt: now,
+      },
+      // Under the port flow, bootstrap waits for the analysis issue.
+      ...(port
+        ? {
+            relationships: {
+              'blockedBy.0': {
+                links: { self: `../${ANALYSIS_ISSUE_PATH}` },
+              },
+            },
+          }
+        : {}),
+      meta: {
+        adoptsFrom: {
+          module: darkfactoryModuleUrl,
+          name: 'Issue',
+        },
+      },
+    },
+  };
+}
+
+/**
+ * The PORT-ANALYSIS seed issue (v3 GitHub-port flow). The prompt template
+ * `issue-analysis.md` carries the full research protocol; the issue
+ * description carries the repo pointer and the acceptance contract.
+ */
+function buildAnalysisSeedIssueDocument(
+  brief: FactoryBrief,
+  darkfactoryModuleUrl: string,
+) {
+  let now = new Date().toISOString();
+  let description = [
+    `## Source application to analyze`,
+    ``,
+    `**Repository:** ${brief.githubRepoUrl}`,
+    `**Working title:** ${brief.title}`,
+    `**One-liner:** ${brief.contentSummary}`,
+    ``,
+    `Fully analyze this GitHub repository — clone it, read its media AND`,
+    `its code. Get INTO the source: how it works, what specialized logic`,
+    `and dependencies it relies on, what its tests pin down and what`,
+    `fixture data they use. Deliverables: TWO Knowledge Articles —`,
+    `\`Knowledge Articles/port-background.json\` (product view: features,`,
+    `screens, flows, better-than-the-original rubric, Boxel card-family`,
+    `mapping) and \`Knowledge Articles/port-code-analysis.json\``,
+    `(engineering view: architecture, dependency map with Boxel-side`,
+    `answers, specialized logic incl. verbatim AI prompts, real data`,
+    `model, ported test contract + fixtures) — both linked onto the`,
+    `bootstrap seed issue via \`relatedKnowledge\`.`,
+    ``,
+    `The full research protocol is in your turn instructions.`,
+  ].join('\n');
+
+  let acceptanceCriteria = [
+    '- [ ] Repository cloned; README and file tree analyzed (not just skimmed)',
+    '- [ ] Every screenshot/GIF/video referenced by the README downloaded and READ (or explicitly listed as unviewable with why)',
+    '- [ ] Feature inventory: every user-facing capability, named and described',
+    '- [ ] Screen catalogue: each view/screen with what it shows and its key affordances',
+    '- [ ] Dependency map: each meaningful dependency → its role → the Boxel-side answer (or NEEDS-HUMAN-DECISION)',
+    '- [ ] Specialized logic inventory: path + summary + port strategy per algorithm; AI prompt templates captured verbatim',
+    '- [ ] Data model as implemented in the code: entities, fields with types, relationships',
+    '- [ ] Ported test contract: assertions mined from the original tests per feature, fixture data captured for sample instances (or explicit "no tests" + contract derived from code)',
+    '- [ ] "Better than the original" rubric: measurable criteria the Boxel port must beat',
+    '- [ ] Boxel port mapping: proposed card family (CardDefs + links) with per-card format notes',
+    '- [ ] BOTH Knowledge Articles written and linked to the bootstrap issue via relatedKnowledge.0 / .1',
+  ].join('\n');
+
+  return {
+    data: {
+      type: 'card' as const,
+      attributes: {
+        issueId: 'PORT-0',
+        summary: `Analyze ${brief.githubRepoUrl} and write the port background`,
+        description,
+        issueType: 'analysis',
+        status: 'backlog',
+        priority: 'critical',
         order: 0,
         acceptanceCriteria,
         createdAt: now,
@@ -235,6 +485,77 @@ function buildSeedIssueDocument(
   };
 }
 
+/**
+ * Build the DESIGN-FOUNDATION seed issue: the hierarchical design phase
+ * that runs after bootstrap and before every implementation issue.
+ * Coherence first, detail later — the per-card design turns consume its
+ * brand guide + tokens + family sheet as binding context.
+ */
+function buildDesignFoundationSeedIssueDocument(
+  _brief: FactoryBrief,
+  darkfactoryModuleUrl: string,
+) {
+  let now = new Date().toISOString();
+
+  let description = [
+    `Establish the shared design language for this build BEFORE any card`,
+    `is designed in detail. Work top-down:`,
+    ``,
+    `1. **Look & feel** — read the project's Knowledge Articles (port`,
+    `   background / brief context) and decide the overall visual`,
+    `   direction: mood, references, what this app should feel like.`,
+    `2. **Brand guide** — write \`Knowledge Articles/brand-guide.json\``,
+    `   (guiding words, palette, type, spacing, dos/don'ts) AND`,
+    `   \`design/tokens.css\` (the CSS custom properties every mockup and`,
+    `   .gts template will use).`,
+    `3. **Family coherence sheet** — \`design/family-sheet.html\`: a`,
+    `   SIMPLE version of every card in the domain side-by-side, linking`,
+    `   tokens.css. Screenshot it, critique for coherence, revise once.`,
+    ``,
+    `Detailed per-card design (fitted quanta, per-format matrices) happens`,
+    `later in each card's own design turn — those turns consume your`,
+    `artifacts as binding context. The full protocol is in your turn`,
+    `instructions.`,
+  ].join('\n');
+
+  let acceptanceCriteria = [
+    "- [ ] Brand guide Knowledge Article written: guiding words, palette, typography, spacing, dos/don'ts",
+    '- [ ] design/tokens.css written: the CSS custom properties (--*) all future mockups and templates use',
+    '- [ ] design/family-sheet.html: a simple rendering of EVERY card in the domain on one sheet, using tokens.css',
+    '- [ ] Family sheet screenshotted, critiqued for coherence, and revised at least once',
+  ].join('\n');
+
+  return {
+    data: {
+      type: 'card' as const,
+      attributes: {
+        issueId: 'DESIGN-0',
+        summary:
+          'Establish the design language: brand guide, tokens, family sheet',
+        description,
+        issueType: 'design',
+        status: 'backlog',
+        priority: 'critical',
+        order: 2,
+        acceptanceCriteria,
+        createdAt: now,
+        updatedAt: now,
+      },
+      relationships: {
+        'blockedBy.0': {
+          links: { self: `../${SEED_ISSUE_PATH}` },
+        },
+      },
+      meta: {
+        adoptsFrom: {
+          module: darkfactoryModuleUrl,
+          name: 'Issue',
+        },
+      },
+    },
+  };
+}
+
 function greenfieldSeedInstructions(): {
   instructions: string[];
   acceptanceCriteria: string;
diff --git a/packages/software-factory/src/factory-skill-loader.ts b/packages/software-factory/src/factory-skill-loader.ts
index 73b996c19c7..f92fc0ac8b7 100644
--- a/packages/software-factory/src/factory-skill-loader.ts
+++ b/packages/software-factory/src/factory-skill-loader.ts
@@ -7,6 +7,7 @@ import type {
   ResolvedSkill,
 } from './factory-agent/index.ts';
 import { logger } from './logger.ts';
+import { startSpan } from './run-trace.ts';
 
 const log = logger('factory-skill-loader');
 
@@ -51,6 +52,15 @@ const DEFAULT_FALLBACK_DIRS = [
   join(PACKAGE_ROOT, '.agents', 'skills'),
 ];
 
+/**
+ * All skill search directories in precedence order (primary first). Exposed
+ * for the on-demand skill tools (`list_skills` / `read_skill`) so their
+ * catalog matches exactly what the loader can resolve.
+ */
+export function skillSearchDirs(): string[] {
+  return [DEFAULT_SKILLS_DIR, ...DEFAULT_FALLBACK_DIRS];
+}
+
 /** Approximate characters per token for budget estimation. */
 const CHARS_PER_TOKEN = 4;
 
@@ -151,13 +161,22 @@ export interface DefaultSkillResolverOptions {
    * See CS-10527.
    */
   enableBoxelUiDiscovery?: boolean;
+  /**
+   * V2 lean mode — front-load only a small core (the design-first V2
+   * operations skill + file structure + cardinal rules); every other
+   * skill is discoverable at runtime via the `list_skills` / `read_skill`
+   * tools. Bootstrap issues are unaffected.
+   */
+  v2?: boolean;
 }
 
 export class DefaultSkillResolver implements SkillResolver {
   private enableBoxelUiDiscovery: boolean;
+  private v2: boolean;
 
   constructor(options: DefaultSkillResolverOptions = {}) {
     this.enableBoxelUiDiscovery = options.enableBoxelUiDiscovery === true;
+    this.v2 = options.v2 === true;
   }
 
   /**
@@ -182,11 +201,54 @@ export class DefaultSkillResolver implements SkillResolver {
       return ['software-factory-bootstrap', 'boxel-file-structure'];
     }
 
+    // Port-analysis issues (v3 GitHub-port flow) are research turns — no
+    // card authoring, so the design-first operations skill would only
+    // mislead. File-structure covers the tracker JSON they do write.
+    if (issueType === 'analysis') {
+      return ['boxel-file-structure'];
+    }
+
+    // Design-foundation turns author a brand guide + tokens + family
+    // coherence sheet — taste work, not card code. File-structure covers
+    // the KA JSON; boxel-design carries the visual-language method (it
+    // resolves from the materialized catalog's fallback dirs).
+    if (issueType === 'design') {
+      return ['boxel-file-structure', 'boxel-design'];
+    }
+
+    // V2 lean mode: small always-on core; everything else on demand via
+    // the list_skills / read_skill tools. The design-first workflow and
+    // the "when you need X, read Y" pointer table live in the V2
+    // operations skill itself.
+    if (this.v2) {
+      let leanSkills = [
+        'software-factory-operations-v2',
+        'boxel-file-structure',
+        'boxel-workspace-cardinal-rules',
+      ];
+      for (let skillName of extractKnowledgeSkillTags(project, issue)) {
+        if (!leanSkills.includes(skillName)) {
+          leanSkills.push(skillName);
+        }
+      }
+      log.info(
+        `Resolved skills (v2 lean) for issue "${issue.id}": ${leanSkills.join(', ')}`,
+      );
+      return leanSkills;
+    }
+
     let skills: string[] = [
       'boxel-development',
       'boxel-file-structure',
       'boxel-api',
       'boxel-command',
+      // Local-only addition for this workspace's factory runs: hard-won,
+      // silent-realm-corrupting gotchas (DateField/DateTimeField mismatch,
+      // external URL in a relationships link poisoning the whole realm's
+      // indexing transaction, etc.) that upstream's boxel-development refs
+      // don't cover. Not an upstream change — lives in this checkout's
+      // .agents/skills/ only.
+      'boxel-workspace-cardinal-rules',
     ];
 
     if (this.enableBoxelUiDiscovery) {
@@ -273,6 +335,9 @@ export class SkillLoader implements SkillLoaderInterface {
     skillNames: string[],
     issue?: IssueData,
   ): Promise<ResolvedSkill[]> {
+    let endLoadSpan = startSpan('skills', 'load', {
+      skills: skillNames.join(','),
+    });
     let results: ResolvedSkill[] = [];
 
     for (let name of skillNames) {
@@ -288,6 +353,7 @@ export class SkillLoader implements SkillLoaderInterface {
       }
     }
 
+    endLoadSpan({ loaded: results.length });
     return results;
   }
 
diff --git a/packages/software-factory/src/factory-tool-builder.ts b/packages/software-factory/src/factory-tool-builder.ts
index 1ee5585f532..4a73b2cddc1 100644
--- a/packages/software-factory/src/factory-tool-builder.ts
+++ b/packages/software-factory/src/factory-tool-builder.ts
@@ -33,6 +33,12 @@ import {
   type RunParseInMemoryOptions,
   type RunParseResult,
 } from './parse-execution.ts';
+import {
+  captureHtmlScreenshot,
+  type ScreenshotHtmlOptions,
+  type ScreenshotHtmlResult,
+} from './screenshot-execution.ts';
+import { catalogSkills, readSkillOnDemand } from './skill-catalog.ts';
 import { runTestsInMemory } from './test-run-execution.ts';
 import type {
   RunTestsInMemoryOptions,
@@ -113,6 +119,10 @@ export interface ToolBuilderConfig {
   runInstantiateInMemory?: (
     options: RunInstantiateInMemoryOptions,
   ) => Promise<RunInstantiateResult>;
+  /** Injected for testing — defaults to captureHtmlScreenshot. */
+  captureHtmlScreenshot?: (
+    options: ScreenshotHtmlOptions,
+  ) => Promise<ScreenshotHtmlResult>;
 }
 
 export interface ToolCallEntry {
@@ -168,6 +178,10 @@ export function buildFactoryTools(
     buildRunEvaluateTool(config),
     buildRunParseTool(config),
     buildRunInstantiateTool(config),
+    buildListSkillsTool(),
+    buildReadSkillTool(),
+    buildScreenshotHtmlTool(config),
+    buildPostUpdateTool(),
     buildSignalDoneTool(),
     buildRequestClarificationTool(),
   ];
@@ -664,6 +678,211 @@ function buildRunInstantiateTool(config: ToolBuilderConfig): FactoryTool {
   };
 }
 
+function buildListSkillsTool(): FactoryTool {
+  return {
+    name: 'list_skills',
+    description:
+      'List every skill available to load on demand — name, one-line ' +
+      'description, and the reference files each one carries. Your system ' +
+      'prompt front-loads only a core skill set; when the task at hand ' +
+      'touches a topic that core does not cover (theming, fitted formats, ' +
+      'file-backed fields, commands, catalog specs, queries, …), call this ' +
+      'to find the right skill, then load it with read_skill. Cheap to ' +
+      'call; results are stable for the whole run.',
+    parameters: { type: 'object', properties: {} },
+    execute: async () => {
+      let skills = await catalogSkills();
+      return { ok: true, skills };
+    },
+  };
+}
+
+function buildReadSkillTool(): FactoryTool {
+  return {
+    name: 'read_skill',
+    description:
+      'Read a skill on demand by name. Without "reference", returns the ' +
+      "skill's SKILL.md body plus the list of its reference file names; " +
+      'pass "reference" to fetch one reference file. Load skills ' +
+      'progressively: SKILL.md first, then only the reference files the ' +
+      'current work actually needs. Do NOT re-read skills whose full text ' +
+      'is already in your system prompt. Use list_skills to discover ' +
+      'available names.',
+    parameters: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Skill name exactly as returned by list_skills.',
+        },
+        reference: {
+          type: 'string',
+          description:
+            'Optional reference file name (e.g. `dev-fitted-formats.md`) ' +
+            'from the skill\'s "references" list.',
+        },
+      },
+      required: ['name'],
+    },
+    execute: async (args) => {
+      let name = requireStringArg(args, 'name', 'read_skill');
+      let rawReference = args.reference;
+      let reference =
+        typeof rawReference === 'string' && rawReference.trim() !== ''
+          ? rawReference.trim()
+          : undefined;
+      try {
+        let result = await readSkillOnDemand(name, reference);
+        return { ok: true, ...result };
+      } catch (error) {
+        return {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}
+
+/**
+ * The agent's live-blog channel. The tool itself just acknowledges — the
+ * orchestrator observes the call through the tool-call stream
+ * (`AgentContext.onToolCall`) and fans the post out to the run-log card
+ * and the current issue's comments. Keeping the tool side-effect-free
+ * means it works identically in every wiring (tests, prime turns, forks).
+ */
+function buildPostUpdateTool(): FactoryTool {
+  return {
+    name: 'post_update',
+    description:
+      'Post a short, social-media-style update about what you are doing ' +
+      'right now and why — it appears live on the run-log card and as a ' +
+      'comment on the issue you are working. Post at every meaningful ' +
+      'moment: kicking off a design, what a critique found, a decision ' +
+      'and its tradeoff, starting to code, recovering from a failed ' +
+      'check. First person, concrete, 1-3 sentences. This commentary ' +
+      'channel is as important as the artifacts themselves.',
+    parameters: {
+      type: 'object',
+      properties: {
+        headline: {
+          type: 'string',
+          description:
+            'One-line update, e.g. "Critique round 2: the fitted tile ' +
+            'was drowning in chrome — stripping it back."',
+        },
+        body: {
+          type: 'string',
+          description:
+            'Optional 1-3 sentence elaboration: the why, the tradeoff, ' +
+            'what is next. Renders as Boxel Flavored Markdown. When you ' +
+            'mention a card you created or touched, reference it with a ' +
+            'card directive using its WORKSPACE PATH (e.g. ' +
+            '"Garment/tee.json" or "Knowledge Articles/port-background.json") ' +
+            '— the run log resolves the path to the live card and the right ' +
+            'realm for you. Choose the form by how much the reader should ' +
+            'see: inline `:card[Path]` renders a small atom pill, use it for ' +
+            'a card named in passing; block `::card[Path]` renders the card ' +
+            'embedded, use it to spotlight one just-shipped card; ' +
+            '`::card[Path | fitted strip]` (or `fitted tile`, `fitted ' +
+            '400x200`) renders a sized tile, use it for a compact visual. ' +
+            'Prefer one embedded spotlight over many; use atoms for the rest.',
+        },
+        kind: {
+          type: 'string',
+          enum: ['comment', 'progress', 'decision'],
+          description:
+            'comment = commentary/context; progress = milestone within ' +
+            'the task; decision = a choice you made and why.',
+        },
+      },
+      required: ['headline'],
+    },
+    execute: async (args) => {
+      let headline = String(args.headline ?? '').trim();
+      if (!headline) {
+        return { ok: false, error: 'headline is required' };
+      }
+      return { ok: true, note: 'posted to the run log' };
+    },
+  };
+}
+
+function buildScreenshotHtmlTool(config: ToolBuilderConfig): FactoryTool {
+  let execute = config.captureHtmlScreenshot ?? captureHtmlScreenshot;
+  return {
+    name: 'screenshot_html',
+    description:
+      'Render a workspace HTML file in headless Chromium and write a PNG ' +
+      "screenshot into the workspace. Returns the PNG's workspace-relative " +
+      'path — then use your native Read tool on that path to SEE the image ' +
+      'and critique it. This powers the HTML-first design loop: write a ' +
+      'plain HTML+CSS mockup of the card (mobile isolated view, fitted ' +
+      'badge/strip/card tiles, embedded row) with REAL sample copy, ' +
+      'screenshot it, look at it, name the defects, revise, and repeat — ' +
+      'seconds per iteration, no lint or realm round-trip. Iterate on the ' +
+      'mockup until it is right BEFORE writing any .gts template; then ' +
+      'translate the accepted mockup into the card templates. Mockups and ' +
+      'screenshots are design artifacts — keep them under a `design/` ' +
+      'folder in the workspace.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Workspace-relative path to the .html file to render.',
+        },
+        output_path: {
+          type: 'string',
+          description:
+            'Optional workspace-relative .png output path. Defaults to the ' +
+            'HTML path with the extension replaced by .png.',
+        },
+        width: {
+          type: 'number',
+          description: 'Viewport width in px (default 390 — mobile).',
+        },
+        height: {
+          type: 'number',
+          description: 'Viewport height in px (default 844 — mobile).',
+        },
+        full_page: {
+          type: 'boolean',
+          description:
+            'Capture the full scrollable page (default true) or just the viewport.',
+        },
+      },
+      required: ['path'],
+    },
+    execute: async (args) => {
+      let path = requireStringArg(args, 'path', 'screenshot_html');
+      let outputPath =
+        typeof args.output_path === 'string' && args.output_path.trim() !== ''
+          ? args.output_path.trim()
+          : undefined;
+      let result = await execute({
+        workspaceDir: config.workspaceDir,
+        path,
+        ...(outputPath ? { outputPath } : {}),
+        ...(typeof args.width === 'number' ? { width: args.width } : {}),
+        ...(typeof args.height === 'number' ? { height: args.height } : {}),
+        ...(typeof args.full_page === 'boolean'
+          ? { fullPage: args.full_page }
+          : {}),
+      });
+      if (result.ok) {
+        return {
+          ...result,
+          note:
+            `Screenshot written to ${result.outputPath}. Use the native ` +
+            'Read tool on that path to view the image and critique it.',
+        };
+      }
+      return result;
+    },
+  };
+}
+
 function buildSignalDoneTool(): FactoryTool {
   return {
     name: 'signal_done',
diff --git a/packages/software-factory/src/factory-tool-executor.ts b/packages/software-factory/src/factory-tool-executor.ts
index bc819a82104..20f81587122 100644
--- a/packages/software-factory/src/factory-tool-executor.ts
+++ b/packages/software-factory/src/factory-tool-executor.ts
@@ -3,6 +3,8 @@ import type { ToolRegistry } from './factory-tool-registry.ts';
 import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
 import { ensureTrailingSlash } from '@cardstack/runtime-common/paths';
 
+import { startSpan } from './run-trace.ts';
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -115,11 +117,13 @@ export class ToolExecutor {
     this.enforceRealmSafety(toolName, toolArgs);
 
     let start = Date.now();
+    let endToolSpan = startSpan('tool', toolName);
     let result: ToolResult;
 
     try {
       result = await this.executeRealmApi(toolName, toolArgs);
     } catch (error) {
+      endToolSpan({ ok: false });
       let durationMs = Date.now() - start;
       let errorMessage = error instanceof Error ? error.message : String(error);
 
@@ -148,6 +152,7 @@ export class ToolExecutor {
       };
     }
 
+    endToolSpan({ ok: result.exitCode === 0 });
     this.logExecution({
       tool: toolName,
       category: manifest.category,
diff --git a/packages/software-factory/src/host-import-manifest.ts b/packages/software-factory/src/host-import-manifest.ts
new file mode 100644
index 00000000000..1bc9d1873d4
--- /dev/null
+++ b/packages/software-factory/src/host-import-manifest.ts
@@ -0,0 +1,161 @@
+/**
+ * Host-import manifest — v3 contract-drift gate.
+ *
+ * Root cause of two of the five wardrobe-run field failures: agents (and
+ * the workspace skills they read) carried a stale memory of
+ * `@cardstack/boxel-host/commands/...` after the host renamed the
+ * directory to `tools/`. Every static gate passed — the import only
+ * exploded at runtime in the operator's browser.
+ *
+ * The fix is to stop hand-maintaining the catalogue: derive it from the
+ * host source that ships with this checkout (`packages/host/app/tools`),
+ * inject it into the agent's context as a generated skill, and statically
+ * fail any `@cardstack/boxel-host/tools|commands/...` import that isn't in
+ * it — at validation time, in-process, before anything reaches a browser.
+ */
+
+import { readdir } from 'node:fs/promises';
+import { join, relative, resolve, sep } from 'node:path';
+
+import type { ResolvedSkill } from './factory-agent/types.ts';
+import { logger } from './logger.ts';
+
+const log = logger('host-import-manifest');
+
+/** Default host tools source directory, relative to the factory package. */
+export function defaultHostToolsDir(packageRoot: string): string {
+  return resolve(packageRoot, '../host/app/tools');
+}
+
+/**
+ * Derive the list of valid `@cardstack/boxel-host/tools/<name>` module
+ * names from the host build's source tree. Recursive; nested entries
+ * come back as `subdir/name`. Returns undefined when the directory is
+ * unreadable (factory deployed without the host checkout) — callers
+ * degrade to no gate rather than failing the run.
+ */
+export async function deriveHostToolImports(
+  hostToolsDir: string,
+): Promise<string[] | undefined> {
+  try {
+    let entries = await readdir(hostToolsDir, {
+      recursive: true,
+      withFileTypes: true,
+    });
+    let names: string[] = [];
+    for (let entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.ts')) continue;
+      let abs = join(entry.parentPath, entry.name);
+      let rel = relative(hostToolsDir, abs)
+        .split(sep)
+        .join('/')
+        .replace(/\.ts$/, '');
+      names.push(rel);
+    }
+    names.sort();
+    log.info(`Derived host-tools manifest: ${names.length} modules`);
+    return names;
+  } catch (error) {
+    log.warn(
+      `Could not derive host-tools manifest from ${hostToolsDir}: ${String(error)} — import gate disabled`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * The generated skill injected into every agent context: the closed
+ * catalogue of host-tool import paths. Kills the phantom-import failure
+ * mode at the source — the model no longer has to remember whether it's
+ * `commands/` or `tools/`, or guess module names.
+ */
+export function buildHostToolsSkill(names: string[]): ResolvedSkill {
+  return {
+    name: 'host-tools-import-manifest',
+    content: [
+      '# Host tool imports (generated from the host build — authoritative)',
+      '',
+      'Host commands are imported from `@cardstack/boxel-host/tools/<name>`.',
+      'The `@cardstack/boxel-host/commands/...` path NO LONGER EXISTS — the',
+      'directory was renamed to `tools/`. Any import not in the list below',
+      'fails validation before your code reaches the realm.',
+      '',
+      'Valid module names:',
+      '',
+      ...names.map((n) => `- \`@cardstack/boxel-host/tools/${n}\``),
+      '',
+      'Each module default-exports the command class (e.g.',
+      "`import GetCardTypeSchemaCommand from '@cardstack/boxel-host/tools/get-card-type-schema';`).",
+    ].join('\n'),
+  };
+}
+
+export interface HostImportViolation {
+  /** The bad import specifier as written. */
+  specifier: string;
+  /** Actionable fix, when one can be inferred. */
+  suggestion?: string;
+}
+
+const HOST_IMPORT_RE =
+  /(?:from\s+|import\s*\(\s*)['"](@cardstack\/boxel-host\/[^'"]+)['"]/g;
+
+/**
+ * Scan one module source for `@cardstack/boxel-host` imports that don't
+ * resolve against the manifest. Only the `tools/` (and legacy
+ * `commands/`) namespaces are gated — other boxel-host subpaths pass
+ * untouched, so the gate can't false-positive on surfaces it doesn't
+ * catalogue.
+ */
+export function findHostImportViolations(
+  source: string,
+  manifest: ReadonlySet<string>,
+): HostImportViolation[] {
+  let violations: HostImportViolation[] = [];
+  for (let match of source.matchAll(HOST_IMPORT_RE)) {
+    let specifier = match[1];
+    let subpath = specifier.slice('@cardstack/boxel-host/'.length);
+    if (subpath.startsWith('commands/')) {
+      let name = subpath.slice('commands/'.length);
+      violations.push({
+        specifier,
+        suggestion: manifest.has(name)
+          ? `the host renamed commands/ to tools/ — use '@cardstack/boxel-host/tools/${name}'`
+          : `the commands/ directory no longer exists (renamed to tools/), and no tool named '${name}' exists either — check the host-tools-import-manifest skill for the valid list`,
+      });
+      continue;
+    }
+    if (subpath.startsWith('tools/')) {
+      let name = subpath.slice('tools/'.length);
+      if (!manifest.has(name)) {
+        let near = closestManifestEntry(name, manifest);
+        violations.push({
+          specifier,
+          suggestion: near
+            ? `no such host tool — did you mean '@cardstack/boxel-host/tools/${near}'?`
+            : `no such host tool — check the host-tools-import-manifest skill for the valid list`,
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/** Cheap nearest-name lookup: prefix/substring containment both ways. */
+function closestManifestEntry(
+  name: string,
+  manifest: ReadonlySet<string>,
+): string | undefined {
+  let lower = name.toLowerCase();
+  let best: string | undefined;
+  for (let entry of manifest) {
+    let e = entry.toLowerCase();
+    if (e === lower) return entry;
+    if (e.includes(lower) || lower.includes(e)) {
+      if (!best || entry.length < best.length) {
+        best = entry;
+      }
+    }
+  }
+  return best;
+}
diff --git a/packages/software-factory/src/instance-discovery.ts b/packages/software-factory/src/instance-discovery.ts
new file mode 100644
index 00000000000..ec36e53b0bf
--- /dev/null
+++ b/packages/software-factory/src/instance-discovery.ts
@@ -0,0 +1,84 @@
+/**
+ * Workspace-fallback discovery of instance card paths for the render
+ * gate.
+ *
+ * The gate's primary source is the stream handler's in-memory sightings
+ * of instance JSONs the agent WROTE this turn. That is empty for two
+ * legitimate turn shapes: a resumed issue after a factory restart (the
+ * agent verifies everything exists and signals done without writing),
+ * and a fix turn that patches a `.gts` via `Edit` without touching
+ * instances. Zero capture targets used to cascade into a false
+ * "no renderable surface" acceptance verdict — the verifier, seeing no
+ * screenshots, concluded the card doesn't render and filed a defect
+ * issue whose own fix turn repeated the cycle (the wardrobe
+ * defect-no-render → v2 → v3 chain, 2026-07-17).
+ *
+ * Fallback: scan the workspace's top-level `<Type>/<id>.json` instances
+ * whose `meta.adoptsFrom.module` points at a local module (a product
+ * card, not a tracker/base card), newest-modified first. The most
+ * recently written instances belong to the most recently built card
+ * family, so this approximates "this issue's cards" — and screenshots
+ * of real cards beat zero evidence even when the mix is imperfect.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** Control-plane and infra dirs that never hold product instances. */
+const EXCLUDED_DIRS = new Set([
+  'Issues',
+  'Projects',
+  'Boards',
+  'Knowledge Articles',
+  'Spec',
+  'Validations',
+  'Runs',
+  'RunLogEntries',
+  'design',
+  'design-history',
+]);
+
+export async function discoverRecentInstanceCardPaths(
+  workspaceDir: string,
+  limit = 4,
+): Promise<string[]> {
+  let found: { cardPath: string; mtimeMs: number }[] = [];
+  let entries;
+  try {
+    entries = await readdir(workspaceDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (let entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    if (EXCLUDED_DIRS.has(entry.name)) continue;
+    let dirPath = join(workspaceDir, entry.name);
+    let files;
+    try {
+      files = await readdir(dirPath);
+    } catch {
+      continue;
+    }
+    for (let file of files) {
+      if (!file.endsWith('.json')) continue;
+      let filePath = join(dirPath, file);
+      try {
+        let doc = JSON.parse(await readFile(filePath, 'utf8'));
+        let module = doc?.data?.meta?.adoptsFrom?.module;
+        // Local relative module (`../garment`) = a product card built in
+        // this realm. Absolute URLs are base/tracker/other-realm cards.
+        if (typeof module !== 'string' || !module.startsWith('.')) continue;
+        let { mtimeMs } = await stat(filePath);
+        found.push({
+          cardPath: `${entry.name}/${file.replace(/\.json$/, '')}`,
+          mtimeMs,
+        });
+      } catch {
+        continue; // unreadable/malformed JSON is not a candidate
+      }
+    }
+  }
+  found.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return found.slice(0, limit).map((f) => f.cardPath);
+}
diff --git a/packages/software-factory/src/instantiate-execution.ts b/packages/software-factory/src/instantiate-execution.ts
index c001a20f016..8286cd890a5 100644
--- a/packages/software-factory/src/instantiate-execution.ts
+++ b/packages/software-factory/src/instantiate-execution.ts
@@ -721,6 +721,31 @@ async function defaultSearchSpecs(
     let specCardUrl = new URL(specId, ensureTrailingSlash(realmUrl)).href;
     let moduleUrl = new URL(ref.module, specCardUrl).href;
 
+    // LOCAL PATCH (CS-12195): a Spec whose `ref.module` is itself
+    // cross-origin from the target realm (a bare instance of a base-realm
+    // card, no local subclass — e.g. a plain `Theme` instance, which some
+    // v0 briefs explicitly require: "no new CardDef, no subclass") can
+    // NEVER pass prerender instantiation — the prerender refuses
+    // cross-origin module loads unconditionally (see the same-named guard
+    // in `prepareExampleInstance` below). Every example would fail with
+    // the identical "adopts from a module … does not match target realm"
+    // error regardless of how correct the instance data is. Skip these the
+    // same way non-instantiable specTypes are skipped above: parse, eval,
+    // and lint already validate everything about the instance data that's
+    // actually this realm's responsibility; the base card class itself is
+    // validated by the base realm's own suite, not here.
+    let refModuleOrigin = new URL(moduleUrl).origin;
+    let targetRealmOrigin = new URL(realmUrl).origin;
+    if (refModuleOrigin !== targetRealmOrigin) {
+      log.info(
+        `Spec ${specId} refs a cross-origin base module (${moduleUrl}) with ` +
+          `no local subclass — prerender instantiation is structurally ` +
+          `impossible (cross-origin), skipping. parse/eval/lint already ` +
+          `cover this instance.`,
+      );
+      continue;
+    }
+
     let relationships = (card as Record<string, unknown>).relationships as
       | Record<string, unknown>
       | undefined;
diff --git a/packages/software-factory/src/issue-loop.ts b/packages/software-factory/src/issue-loop.ts
index 2eacecddb0b..08ae74736ca 100644
--- a/packages/software-factory/src/issue-loop.ts
+++ b/packages/software-factory/src/issue-loop.ts
@@ -12,8 +12,12 @@
  * Phase 1's runFactoryLoop() remains unchanged and coexists with this.
  */
 
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+
 import type {
   AgentContext,
+  AgentRunResult,
   IssueData,
   SchedulableIssue,
   ValidationResults,
@@ -26,7 +30,27 @@ import type { IssueStore } from './issue-scheduler.ts';
 
 import { IssueScheduler } from './issue-scheduler.ts';
 import { logger } from './logger.ts';
+import { startSpan, traceEvent } from './run-trace.ts';
+import { isBugFixIssue } from './factory-prompt-loader.ts';
+import {
+  type RunLogWriter,
+  createRunLogStreamHandler,
+  designEntriesFromToolCalls,
+  cardPathsFromToolCalls,
+  persistDesignScreenshot,
+} from './run-log.ts';
+import type { RunMonitor } from './run-monitor.ts';
+import {
+  type RenderGate,
+  type CardScreenshotResult,
+  summarizeRenderResults,
+} from './render-gate.ts';
+import { discoverRecentInstanceCardPaths } from './instance-discovery.ts';
 import { retryWithPoll } from './retry-with-poll.ts';
+import {
+  retryTransientAgentError,
+  errorMessage,
+} from './transient-agent-error.ts';
 
 let log = logger('issue-loop');
 
@@ -106,6 +130,13 @@ export interface IssueLoopConfig {
    */
   createValidator: (issueId: string) => Validator;
   targetRealm: string;
+  /**
+   * Control realm hosting issues / run log / validations under the v3
+   * split. Defaults to `targetRealm` (no split). Only used for run-log
+   * link targeting — the issue store and sync plumbing are wired to the
+   * right realms upstream.
+   */
+  controlRealm?: string;
   /**
    * Module URL for the tracker schema (Project / Issue / KnowledgeArticle).
    * Surfaced in the system prompt so the agent can hand-write the correct
@@ -130,6 +161,79 @@ export interface IssueLoopConfig {
    */
   syncWorkspace: () => Promise<{ ok: boolean; error?: string }>;
   briefUrl?: string;
+  /** Live-blog writer (v2): appends run events to Runs/<slug>.json in the target realm. */
+  runLog?: RunLogWriter;
+  /**
+   * Orchestrator monitor (v3): stall narration, per-turn telemetry,
+   * scheduler + watchdog notes onto the run log. The loop drives
+   * beginTurn/endTurn around every agent.run and feeds stream events
+   * into the stall clock; the wiring owns start()/stop().
+   */
+  monitor?: RunMonitor;
+  /**
+   * Render gate (v3 P0): after each non-bootstrap issue completes,
+   * screenshot the cards it shipped via the realm server's
+   * `_screenshot-card`, attach the renders to the run log, and — unless
+   * `acceptanceWalkthrough` is false — run a verifier turn that reads the
+   * PNGs and verdicts each acceptance criterion, filing defect issues for
+   * gaps. Both are best-effort: a gate failure never un-does the issue.
+   */
+  renderGate?: RenderGate;
+  /**
+   * Run the acceptance-walkthrough verifier turn after the render gate.
+   * Default true when `renderGate` is set.
+   */
+  acceptanceWalkthrough?: boolean;
+  /**
+   * Per-turn model/thinking budget policy, keyed by turn type. The
+   * ORCHESTRATOR owns this (turn type is deterministic here); issues
+   * don't carry budgets. `fix` applies to inner iterations ≥ 2 —
+   * mechanical lint/parse fix-ups that don't need the flagship model at
+   * full effort. Absent keys inherit the session default.
+   */
+  modelPolicy?: {
+    prime?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    bootstrap?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    design?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    build?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    fix?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+    acceptance?: {
+      model?: string;
+      effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    };
+  };
+  /**
+   * Phase-split (v2): run each implementation issue's first iteration as
+   * TWO turns — a design turn (mockups + notes, flagship budget) and a
+   * build turn (translation, cheap budget) forked from the design
+   * session. The economics: BUILD emits the big files, so that's where a
+   * cheaper model pays for its cache re-ingest; DESIGN is where taste
+   * lives, so it keeps the strong model.
+   */
+  phaseSplit?: boolean;
+  /**
+   * Context forking (v2): before the first implementation issue, run one
+   * priming turn (read skills/design-language/precedent, write
+   * design/DESIGN-NOTES.md) and fork every implementation issue's session
+   * from it — shared provider-cached prefix instead of per-issue context
+   * rebuilds.
+   */
+  forkContext?: boolean;
   /** Maximum inner-loop iterations per issue. Default: 8. */
   maxIterationsPerIssue?: number;
   /** Maximum outer-loop cycles (safety guard). Default: 50. */
@@ -219,6 +323,137 @@ function issueSummaryLabel(issue: SchedulableIssue): string {
   return summary ? `"${issue.id}" — "${summary}"` : `"${issue.id}"`;
 }
 
+/** Short stable issue identifier for trace tags (URL basename). */
+function issueSlug(issue: SchedulableIssue): string {
+  let id = String(issue.id);
+  let basename = id.split('/').filter(Boolean).pop();
+  return basename ?? id;
+}
+
+/** Realm-relative card path for an issue (for run-log show-me links). */
+function issueCardPath(
+  issue: SchedulableIssue,
+  targetRealm: string,
+): string | undefined {
+  if (typeof issue.id === 'string' && issue.id.startsWith(targetRealm)) {
+    return issue.id.slice(targetRealm.length).replace(/\.json$/, '');
+  }
+  return undefined;
+}
+
+/**
+ * Bootstrap, analysis, and design-foundation issues are meta-work: no
+ * product code, no validation pipeline, no design/build phase split, no
+ * render gate. (Design-foundation IS a design turn already — splitting
+ * it or screenshotting instances it never wrote makes no sense.)
+ */
+function isMetaIssue(issue: SchedulableIssue): boolean {
+  return (
+    issue.issueType === 'bootstrap' ||
+    issue.issueType === 'analysis' ||
+    issue.issueType === 'design'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Session-reuse decision (continuation vs fresh context)
+// ---------------------------------------------------------------------------
+
+/**
+ * After the maximum continued chain, reset to a fresh context. Bounds context
+ * growth across a long fix loop and the risk of the agent anchoring on an
+ * approach that isn't working — and keeps the resumed prefix inside the
+ * provider cache window.
+ */
+const MAX_CONTINUED_CHAIN = 3;
+
+/**
+ * A compact signature of a validation failure: which steps failed and how
+ * many total errors. Used to tell whether a fix iteration made progress
+ * (fewer errors / different steps) or stalled (same failure again).
+ */
+export interface FailureFingerprint {
+  steps: string;
+  errorCount: number;
+}
+
+export function failureFingerprint(
+  results?: ValidationResults,
+): FailureFingerprint {
+  if (!results || results.passed) return { steps: '', errorCount: 0 };
+  let failing = results.steps.filter((s) => !s.passed);
+  return {
+    steps: failing
+      .map((s) => s.step)
+      .sort()
+      .join(','),
+    errorCount: failing.reduce((n, s) => n + s.errors.length, 0),
+  };
+}
+
+export type SessionStrategy = 'fresh' | 'continue';
+
+/**
+ * Decide whether a follow-on turn should CONTINUE the prior iteration's
+ * session (its reads/edits stay in context — the agent fixes instead of
+ * re-reading) or start FRESH from the primed skills/design context.
+ *
+ * Continue while the fix is converging. Reset to fresh when either:
+ *  - the same failures repeat with no fewer errors (the chained frame isn't
+ *    helping — a clean context may break the agent out of a wrong approach), or
+ *  - the continued chain hit MAX_CONTINUED_CHAIN (bound context + cache window).
+ *
+ * The first turn (or any turn with no prior session) is always fresh.
+ */
+export function decideSessionStrategy(params: {
+  iteration: number;
+  hasPriorSession: boolean;
+  chainDepth: number;
+  previousFailure?: FailureFingerprint;
+  currentFailure?: FailureFingerprint;
+}): { strategy: SessionStrategy; reason: string } {
+  let {
+    iteration,
+    hasPriorSession,
+    chainDepth,
+    previousFailure,
+    currentFailure,
+  } = params;
+  if (iteration <= 1 || !hasPriorSession) {
+    return { strategy: 'fresh', reason: 'first turn' };
+  }
+  if (chainDepth >= MAX_CONTINUED_CHAIN) {
+    return {
+      strategy: 'fresh',
+      reason: `continued ${MAX_CONTINUED_CHAIN}× — resetting to a fresh context`,
+    };
+  }
+  if (
+    previousFailure &&
+    currentFailure &&
+    currentFailure.steps !== '' &&
+    currentFailure.steps === previousFailure.steps &&
+    currentFailure.errorCount >= previousFailure.errorCount
+  ) {
+    return {
+      strategy: 'fresh',
+      reason: 'same failures, no progress — fresh context to break the frame',
+    };
+  }
+  return {
+    strategy: 'continue',
+    reason: 'converging — keep the working context',
+  };
+}
+
+/** Human-facing issue title for the run log (no quoting/id noise). */
+function issueDisplayTitle(issue: SchedulableIssue): string {
+  let summary = issue.summary ?? (issue as Record<string, unknown>).title;
+  return typeof summary === 'string' && summary.trim() !== ''
+    ? summary
+    : issue.id;
+}
+
 function formatValidation(results: ValidationResults): string {
   if (results.passed) {
     let stepCount = results.steps.length;
@@ -272,8 +507,16 @@ export async function runIssueLoop(
     createValidator,
     targetRealm,
     darkfactoryModuleUrl,
+    workspaceDir,
     syncWorkspace,
     briefUrl,
+    runLog,
+    monitor,
+    renderGate,
+    acceptanceWalkthrough = true,
+    modelPolicy,
+    phaseSplit = false,
+    forkContext = false,
     maxIterationsPerIssue = DEFAULT_MAX_ITERATIONS_PER_ISSUE,
     maxOuterCycles = DEFAULT_MAX_OUTER_CYCLES,
     debug = false,
@@ -281,8 +524,127 @@ export async function runIssueLoop(
     onBootstrapComplete,
   } = config;
 
+  let controlRealm = config.controlRealm ?? targetRealm;
+
+  let endRunSpan = startSpan('run', 'issue-loop', { targetRealm });
+
   let scheduler = new IssueScheduler(issueStore);
+  let endLoadSpan = startSpan('scheduler', 'load-issues');
   await scheduler.loadIssues();
+  endLoadSpan();
+
+  // A crash/stop mid-review strands an issue at 'review' — a status the
+  // scheduler never picks. Reset stragglers to in_progress so a restart
+  // re-runs the work turn (idempotent for finished work: the agent sees
+  // everything exists, signals done, and re-enters review).
+  try {
+    for (let stranded of await issueStore.listIssues()) {
+      if (stranded.status === 'review') {
+        log.info(
+          `Resetting stranded in-review issue to in_progress: ${stranded.id}`,
+        );
+        await issueStore.updateIssue(stranded.id, { status: 'in_progress' });
+      }
+    }
+    await scheduler.loadIssues();
+  } catch (err) {
+    log.warn(
+      `Failed to reset stranded review issues: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // Run one agent turn under the monitor: begin/end telemetry plus the
+  // stall clock (tool events + coarse assistant-message activity). A
+  // no-op passthrough when no monitor is wired.
+  let runTurn = async (
+    context: AgentContext,
+    info: {
+      issueTitle: string;
+      turnType: string;
+      iteration?: number;
+      maxIterations?: number;
+    },
+  ): Promise<AgentRunResult> => {
+    let prevOnToolCall = context.onToolCall;
+    let prevOnActivity = context.onActivity;
+    if (monitor) {
+      context.onToolCall = (entry) => {
+        monitor.noteToolEvent(entry);
+        prevOnToolCall?.(entry);
+      };
+      context.onActivity = (desc) => monitor.noteActivity(desc);
+      monitor.beginTurn({
+        ...info,
+        model: context.modelBudget?.model,
+        effort: context.modelBudget?.effort,
+      });
+    }
+    let turnStartMs = Date.now();
+    let endTurnSpan = startSpan('inference', info.turnType, {
+      issue: info.issueTitle,
+      iteration: info.iteration,
+      model: context.modelBudget?.model ?? 'inherit',
+      effort: context.modelBudget?.effort ?? 'inherit',
+      resumed: Boolean(context.resumeSession),
+    });
+    try {
+      // Transient SDK/network faults (idle stream timeouts, connection
+      // resets) otherwise crash the whole multi-hour process — observed
+      // taking down a run 5 issues deep (wardrobe, 2026-07-17) on an SDK
+      // "Stream idle timeout" with no code defect involved. Retry the
+      // turn itself a couple of times before surfacing as a real failure;
+      // non-transient errors (agent logic, tool errors) still throw
+      // immediately on the first attempt.
+      let result = await retryTransientAgentError(
+        () => agent.run(context, tools),
+        (attempt, error) => {
+          log.warn(
+            `  Turn attempt ${attempt} hit a transient error, retrying: ${errorMessage(error)}`,
+          );
+          monitor?.noteWatchdog(
+            'agent-retry',
+            `Transient error, retrying turn (attempt ${attempt + 1})`,
+            { body: errorMessage(error) },
+          );
+        },
+      );
+      monitor?.endTurn({
+        status: result.status,
+        durationMs: Date.now() - turnStartMs,
+        usage: result.usage,
+      });
+      let usage = result.usage as
+        | {
+            inputTokens?: number;
+            outputTokens?: number;
+            cacheReadTokens?: number;
+            costUsd?: number;
+          }
+        | undefined;
+      endTurnSpan({
+        status: result.status,
+        toolCalls: result.toolCalls.length,
+        tokensIn: usage?.inputTokens,
+        tokensOut: usage?.outputTokens,
+        tokensCacheRead: usage?.cacheReadTokens,
+        costUsd: usage?.costUsd,
+      });
+      return result;
+    } catch (error) {
+      monitor?.endTurn({
+        status: 'error',
+        durationMs: Date.now() - turnStartMs,
+      });
+      endTurnSpan({ status: 'error' });
+      throw error;
+    } finally {
+      // Restore the un-wrapped hooks: a later turn may spread this context
+      // (phase-split's buildContext) and would otherwise double-wrap,
+      // double-counting every tool event in the monitor's stats.
+      context.onToolCall = prevOnToolCall;
+      context.onActivity = prevOnActivity;
+    }
+  };
 
   let issueResults: IssueIterationResult[] = [];
   let outerCycles = 0;
@@ -315,6 +677,7 @@ export async function runIssueLoop(
     let hasAnyIssues = scheduler.hasAnyIssues();
     if (hasAnyIssues) {
       log.info('All issues are blocked — nothing to do');
+      endRunSpan({ outcome: 'no_unblocked_issues' });
       return {
         outcome: 'no_unblocked_issues',
         outerCycles: 0,
@@ -322,6 +685,7 @@ export async function runIssueLoop(
       };
     }
     log.info('No issues found — nothing to do');
+    endRunSpan({ outcome: 'all_issues_done' });
     return { outcome: 'all_issues_done', outerCycles: 0, issueResults: [] };
   }
 
@@ -329,6 +693,61 @@ export async function runIssueLoop(
   // Outer loop: iterate over unblocked issues
   // -------------------------------------------------------------------------
 
+  if (runLog) {
+    await runLog.start();
+  }
+
+  // Materialize issue events as run-log entry cards so the query-backed feed
+  // unions them with the build entries (in the containsMany days these were
+  // pushed straight onto the array; the query model's equivalent is emitting
+  // one entry per event). Status TRANSITIONS especially have to be captured
+  // here — the Issue card stores only its current status, so a later query
+  // can't reconstruct the history. `issue-picked` (→in_progress pickup) and
+  // `issue-done` (→done) stay bespoke (they drive nowWorkingOn + the Issues-
+  // done facet); these cover every other transition and the agent comments.
+  // Both link the issue via `issueUrl` (a light atom chip), matching the
+  // post_update entries — NOT `cardPath`, which would embed the whole Issue
+  // card in every comment/status row (heavy and repetitive across one
+  // issue's lifecycle). `iss.id` is the issue's absolute URL.
+  let emitStatusChange = async (
+    iss: SchedulableIssue,
+    to: string,
+    from?: string,
+    detail?: string,
+  ): Promise<void> => {
+    if (!runLog) return;
+    let arrow = from ? `${from} → ${to}` : `→ ${to}`;
+    await runLog.append([
+      {
+        kind: 'status-change',
+        headline: `${issueDisplayTitle(iss)}: ${arrow}`,
+        body: detail,
+        issueUrl: iss.id,
+        who: 'orchestrator',
+      },
+    ]);
+  };
+  let emitComment = async (
+    iss: SchedulableIssue,
+    author: string,
+    body: string,
+  ): Promise<void> => {
+    if (!runLog) return;
+    await runLog.append([
+      {
+        kind: 'comment',
+        headline: `${author} commented on ${issueDisplayTitle(iss)}`,
+        body,
+        who: author,
+        issueUrl: iss.id,
+      },
+    ]);
+  };
+
+  // fork-context mode: undefined = not yet primed; null = priming failed
+  // (run without forking); string = fork seed session id.
+  let primeSessionId: string | null | undefined;
+
   while (
     scheduler.hasUnblockedIssues(exhaustedIssues) &&
     outerCycles < maxOuterCycles
@@ -343,12 +762,114 @@ export async function runIssueLoop(
       break;
     }
 
+    // Reconcile against the AUTHORITATIVE local workspace file before doing
+    // any work. `pickNextIssue` draws from `listIssues`, which reads the
+    // realm INDEX; under the control/product split the control-plane sync
+    // pushes raw writes that don't wait for indexing, so a seed the workspace
+    // has already marked `done` (a completed analysis/bootstrap issue on a
+    // resume) can still show `in_progress`/`backlog` in the index and get
+    // re-picked — the exact "PORT-0 re-runs the repo study on restart" waste.
+    // A local `done` means the index is just stale: skip and exclude it. A
+    // genuinely interrupted issue reads `in_progress` locally too, so this
+    // never skips real resumable work.
+    if (typeof issueStore.readLocalStatus === 'function') {
+      let localStatus = await issueStore.readLocalStatus(issue.id);
+      if (localStatus === 'done' && issue.status !== 'done') {
+        log.info(
+          `Outer cycle ${outerCycles}: skipping ${issueSummaryLabel(issue)} — workspace file says done, the realm index is stale (${issue.status})`,
+        );
+        traceEvent('scheduler', 'skip-stale-done', {
+          issue: issueSlug(issue),
+          cycle: outerCycles,
+        });
+        exhaustedIssues.add(issue.id);
+        continue;
+      }
+    }
+
+    if (runLog) {
+      let issueTitle = issueDisplayTitle(issue);
+      await runLog.append(
+        [
+          {
+            kind: 'issue-picked',
+            headline: `Started: ${issueTitle}`,
+            body:
+              issue.status !== 'in_progress'
+                ? 'Issue status: backlog → in progress'
+                : undefined,
+            cardPath: issueCardPath(issue, controlRealm),
+            cardRealm: 'control' as const,
+          },
+        ],
+        { nowWorkingOn: issueTitle },
+      );
+    }
+
+    if (monitor) {
+      let remaining = scheduler.unblockedCount(exhaustedIssues);
+      monitor.noteScheduler(
+        `Queue: picked "${issueDisplayTitle(issue)}" — ${remaining} unblocked issue${remaining === 1 ? '' : 's'} in the queue`,
+        `Priority ${issue.priority} · status ${issue.status} · up to ${maxIterationsPerIssue} iterations before this issue blocks.`,
+      );
+    }
+
+    // Context forking (v2): one priming turn before the first
+    // implementation issue. The prime reads skills + design language +
+    // precedent and writes design/DESIGN-NOTES.md; its session id seeds a
+    // fork for every implementation turn that follows.
+    if (forkContext && primeSessionId === undefined && !isMetaIssue(issue)) {
+      try {
+        log.info('Priming shared context session (fork-context mode)...');
+        let primeContext = await contextBuilder.buildForIssue({
+          issue,
+          targetRealm,
+          darkfactoryModuleUrl,
+        });
+        primeContext.primeTurn = true;
+        if (modelPolicy?.prime) {
+          primeContext.modelBudget = modelPolicy.prime;
+        }
+        let primeResult = await runTurn(primeContext, {
+          issueTitle: 'shared design context',
+          turnType: 'prime',
+        });
+        if (primeResult.sessionId) {
+          primeSessionId = primeResult.sessionId;
+          log.info(
+            `Prime session captured: ${primeSessionId} (${primeResult.toolCalls.length} tool calls)`,
+          );
+          if (runLog) {
+            await runLog.append([
+              {
+                kind: 'phase',
+                headline: 'Shared design context primed',
+                body: 'Skills, design language, and precedent loaded once — every card build forks from here.',
+              },
+            ]);
+          }
+        } else {
+          log.warn('Prime turn returned no session id — forking disabled');
+          primeSessionId = null;
+        }
+      } catch (error) {
+        log.warn(`Prime turn failed (${String(error)}) — forking disabled`);
+        primeSessionId = null;
+      }
+    }
+
     // Reset per-issue timing accumulators; `cycleStartMs` anchors this
     // issue's total wall clock and `cycleSyncStartMs` its sync baseline.
     cur = { agentMs: 0, validationMs: 0, syncMs: 0 };
     let cycleStartMs = Date.now();
     let cycleSyncStartMs = getSyncElapsedMs();
 
+    let endIssueSpan = startSpan('issue', issueSlug(issue), {
+      cycle: outerCycles,
+      issueType: issue.issueType ?? 'implementation',
+      priority: issue.priority,
+    });
+
     log.info(
       `Outer cycle ${outerCycles}: picked issue ${issueSummaryLabel(issue)} (status=${issue.status}, priority=${issue.priority})`,
     );
@@ -393,7 +914,14 @@ export async function runIssueLoop(
 
     // Create a fresh validator scoped to this issue so that artifacts
     // (e.g. TestRun cards) are named per-issue rather than shared.
-    let validator = createValidator(issue.id);
+    // Bootstrap issues create Project/Board/Knowledge-Article/Issue cards,
+    // never a Catalog Spec — so `instantiate` structurally can never pass
+    // for them (see CS-12185). Skip straight to NoOpValidator (already
+    // built for exactly this per its own docstring) instead of burning
+    // maxIterationsPerIssue on an unwinnable validation.
+    let validator = isMetaIssue(issue)
+      ? new NoOpValidator()
+      : createValidator(issue.id);
 
     // -----------------------------------------------------------------------
     // Inner loop: iterate on a single issue with validation
@@ -404,14 +932,223 @@ export async function runIssueLoop(
     let validationContext: string | undefined;
     let exitReason: IssueIterationResult['exitReason'] = 'max_iterations';
     let innerIterations = 0;
+    // Chained inner-loop session: after the first iteration, a fix iteration
+    // MAY resume the PRIOR iteration's session (below) so the files and edits
+    // it already read stay in context — the agent fixes what validation
+    // flagged instead of re-reading to re-orient. The orchestrator decides
+    // continue-vs-fresh per turn (decideSessionStrategy); chainDepth and
+    // prevFailure feed that decision. All reset per issue.
+    let iterationSessionId: string | undefined;
+    let chainDepth = 0;
+    let prevFailure: FailureFingerprint | undefined;
+
+    // Live blog: one stream handler per issue (state — seen writes, design
+    // rounds, instance paths — accumulates across iterations). Each
+    // iteration's context points at the same handler.
+    let streamHandler: ReturnType<typeof createRunLogStreamHandler> | undefined;
+    if (runLog) {
+      // Capture the id before the closure: `issue` is a mutable let the
+      // loop reassigns, so TS can't keep its narrowing inside a callback.
+      let streamIssueId = issue.id;
+      streamHandler = createRunLogStreamHandler({
+        runLog,
+        addIssueComment: (body: string) =>
+          issueStore.addComment(streamIssueId, {
+            body,
+            author: 'factory-agent',
+          }),
+        workspaceDir,
+        // Absolute issue-card URL so every streamed feed row links back to
+        // the issue it belongs to (issues live in the control realm).
+        issueUrl: streamIssueId.startsWith('http') ? streamIssueId : undefined,
+      });
+    }
+
+    // -----------------------------------------------------------------------
+    // PM review gate. A finished issue goes to 'review' and a fresh
+    // reviewer turn (flagship budget — taste judgment) judges the OUTPUT:
+    // render captures + acceptance criteria, product-manager style.
+    // Biased to ship; empowered to bounce ONCE with comments (rework),
+    // file follow-up issues, and reprioritize backlog issues. The
+    // verdict comes back through a scratch file the reviewer Writes
+    // (`.factory-scratch/review-verdict.json`) — no new tool plumbing,
+    // and the file never syncs (dotdir).
+    // -----------------------------------------------------------------------
+    let reviewBounces = 0;
+    let runReviewGate = async (): Promise<{
+      verdict: 'approve' | 'rework';
+      feedback?: string;
+    }> => {
+      // `issue` is a mutable outer binding; capture the narrowed value —
+      // the gate only runs from inside the inner loop where it's set.
+      let reviewIssue = issue;
+      if (!reviewIssue) return { verdict: 'approve' };
+      try {
+        let gateCardPaths = streamHandler?.instanceCardPaths() ?? [];
+        if (gateCardPaths.length === 0) {
+          gateCardPaths = cardPathsFromToolCalls(allToolCalls);
+        }
+        if (gateCardPaths.length === 0) {
+          // Resumed issues (post-restart, agent verifies + signals done
+          // without writing) and Edit-only fix turns produce zero
+          // sightings. Fall back to the newest product instances on disk
+          // so the reviewer judges real screenshots — zero captures
+          // previously cascaded into false "no renderable surface"
+          // defect chains (wardrobe defect-no-render → v2 → v3).
+          gateCardPaths = await discoverRecentInstanceCardPaths(workspaceDir);
+          if (gateCardPaths.length > 0) {
+            log.info(
+              `  Render gate: no instance writes this turn — falling back to newest workspace instances (${gateCardPaths.join(', ')})`,
+            );
+          }
+        }
+        let renderResults: CardScreenshotResult[] = [];
+        if (renderGate && gateCardPaths.length > 0) {
+          log.info(
+            `  Render gate: capturing ${Math.min(gateCardPaths.length, 4)} card(s)`,
+          );
+          let endGateSpan = startSpan('render-gate', 'capture', {
+            issue: issueSlug(reviewIssue),
+            cards: Math.min(gateCardPaths.length, 4),
+          });
+          renderResults = await renderGate.captureCards(gateCardPaths);
+          endGateSpan({ ok: renderResults.filter((r) => r.ok).length });
+          // Push the PNGs (design/render/ rides the product sync) so the
+          // run-log image links resolve.
+          await syncWorkspace();
+        }
+        if (runLog && renderResults.length > 0) {
+          let summary = summarizeRenderResults(renderResults);
+          let shotEntries = await Promise.all(
+            renderResults
+              .filter((r) => r.ok && r.format === 'isolated' && r.outputPath)
+              .slice(0, 3)
+              .map(async (r) => ({
+                kind: 'design' as const,
+                headline: `Render check: ${r.cardPath}${r.suspectBlank ? ' — SUSPECTED BLANK' : ''}`,
+                // design/render/ is BUILD-turn scratch the agent may clean
+                // up on a later issue; persist into design-history/ so this
+                // link survives — see persistDesignScreenshot's doc comment.
+                imageCardPath: await persistDesignScreenshot(
+                  workspaceDir,
+                  r.outputPath as string,
+                ),
+              })),
+          );
+          await runLog.append([
+            ...shotEntries,
+            {
+              kind: 'validation' as const,
+              headline: 'Render gate',
+              body: summary,
+            },
+          ]);
+          monitor?.noteScheduler(`Render gate: ${summary}`);
+        }
 
+        log.info('  Review turn starting');
+        let reviewContext = await contextBuilder.buildForIssue({
+          issue: reviewIssue,
+          targetRealm,
+          darkfactoryModuleUrl,
+        });
+        reviewContext.acceptanceTurn = {
+          renderSummary:
+            renderResults.length > 0
+              ? summarizeRenderResults(renderResults)
+              : 'no card surfaces were captured',
+          screenshots: renderResults
+            .filter(
+              (r): r is CardScreenshotResult & { outputPath: string } =>
+                r.ok && r.outputPath !== undefined,
+            )
+            .map((r) => ({
+              cardPath: r.cardPath,
+              format: r.format,
+              outputPath: r.outputPath,
+              ...(r.suspectBlank ? { suspectBlank: true } : {}),
+            })),
+          failedCaptures: renderResults
+            .filter((r) => !r.ok)
+            .map((r) => ({
+              cardPath: r.cardPath,
+              format: r.format,
+              error: r.error ?? 'unknown',
+            })),
+        };
+        if (modelPolicy?.acceptance) {
+          reviewContext.modelBudget = modelPolicy.acceptance;
+        }
+        if (streamHandler) {
+          reviewContext.onToolCall = streamHandler.handler;
+        }
+        let reviewResult = await runTurn(reviewContext, {
+          issueTitle: issueDisplayTitle(reviewIssue),
+          turnType: 'review',
+        });
+        allToolCalls.push(...reviewResult.toolCalls);
+        // Follow-up issues / backlog edits the reviewer filed are
+        // control-plane files — sync so the scheduler sees them.
+        await syncWorkspace();
+
+        // Read the reviewer's verdict file. Missing or malformed →
+        // bias to ship: approve.
+        let verdictPath = join(
+          workspaceDir,
+          '.factory-scratch',
+          'review-verdict.json',
+        );
+        try {
+          let raw = await readFile(verdictPath, 'utf8');
+          await rm(verdictPath, { force: true });
+          let parsed = JSON.parse(raw) as {
+            verdict?: string;
+            feedback?: string;
+          };
+          if (
+            parsed?.verdict === 'rework' &&
+            typeof parsed.feedback === 'string' &&
+            parsed.feedback.trim() !== ''
+          ) {
+            return { verdict: 'rework', feedback: parsed.feedback.trim() };
+          }
+        } catch {
+          // No verdict file — the prompt says APPROVE needs no file.
+        }
+        return { verdict: 'approve' };
+      } catch (error) {
+        log.warn(
+          `  Review gate failed — bias to ship, approving: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return { verdict: 'approve' };
+      }
+    };
+
+    // Iteration spans use a close-previous pattern: the body has several
+    // break/continue exits, so each span is closed when the next iteration
+    // opens (or after the loop). Inter-iteration overhead lands in the
+    // owning iteration's span, which is where it belongs.
+    let endIterationSpan: () => void = () => {};
     for (let iteration = 1; iteration <= maxIterationsPerIssue; iteration++) {
       innerIterations = iteration;
+      endIterationSpan();
+      endIterationSpan = startSpan('iteration', issueSlug(issue), {
+        iteration,
+      });
 
       log.info(
         `  Inner iteration ${iteration}/${maxIterationsPerIssue} for issue ${issueSummaryLabel(issue)}`,
       );
 
+      if (runLog && iteration > 1) {
+        await runLog.append([
+          {
+            kind: 'iteration',
+            headline: `Iteration ${iteration} of ${maxIterationsPerIssue} — revising after validation feedback`,
+          },
+        ]);
+      }
+
       // Build context — includes pre-formatted validation context from prior iteration
       let context = await contextBuilder.buildForIssue({
         issue,
@@ -422,23 +1159,189 @@ export async function runIssueLoop(
         briefUrl,
       });
 
+      // Session reuse — the orchestrator decides continue-vs-fresh per turn.
+      // CONTINUE resumes the prior iteration's session so its reads + edits
+      // stay in context (a fix turn becomes "here's what failed, fix it",
+      // no re-read). FRESH forks the primed skills/design/precedent session
+      // instead — used on the first turn, and as a circuit-breaker when the
+      // agent is stuck repeating a failure or the chain grew too deep. Both
+      // fork (fork: true) so the parent session is never mutated. Meta issues
+      // (bootstrap/analysis/design) run once, so they always go fresh.
+      let currentFailure = failureFingerprint(validationResults);
+      let decision = decideSessionStrategy({
+        iteration,
+        hasPriorSession: Boolean(iterationSessionId) && !isMetaIssue(issue),
+        chainDepth,
+        previousFailure: prevFailure,
+        currentFailure,
+      });
+      if (decision.strategy === 'continue' && iterationSessionId) {
+        context.resumeSession = { sessionId: iterationSessionId, fork: true };
+        chainDepth += 1;
+      } else {
+        if (typeof primeSessionId === 'string' && !isMetaIssue(issue)) {
+          context.resumeSession = { sessionId: primeSessionId, fork: true };
+        }
+        chainDepth = 0;
+      }
+      prevFailure = currentFailure;
+      if (iteration > 1 && !isMetaIssue(issue)) {
+        log.info(
+          `  Context strategy: ${decision.strategy} (${decision.reason})`,
+        );
+      }
+
+      // Live blog: stream design screenshots, .gts writes, failed checks,
+      // and the agent's own post_update commentary onto the run-log card
+      // (and issue comments) AS THEY HAPPEN — a long agent turn must never
+      // leave the run log silent.
+      if (streamHandler) {
+        context.onToolCall = streamHandler.handler;
+      }
+
+      // Model/thinking budget by turn type: bootstrap and first
+      // implementation iterations do design-taste work; iterations ≥ 2
+      // are mechanical fix-ups and run on the cheaper budget.
+      let turnBudget =
+        issue.issueType === 'bootstrap'
+          ? modelPolicy?.bootstrap
+          : issue.issueType === 'analysis' || issue.issueType === 'design'
+            ? undefined // research/taste turns inherit the flagship session
+            : iteration >= 2
+              ? modelPolicy?.fix
+              : modelPolicy?.build;
+      if (turnBudget) {
+        context.modelBudget = turnBudget;
+        log.info(
+          `  Turn budget: model=${turnBudget.model ?? 'inherit'}, effort=${turnBudget.effort ?? 'inherit'}`,
+        );
+      }
+
       // Run the agent — it calls tools during its turn. Realm-touching `run_*`
       // tools sync the workspace before executing, so subtract that tool-sync
       // time from the agent's wall clock: it's attributed to sync (via the
       // shared counter), not to the model.
       let agentStartMs = Date.now();
       let agentSyncStartMs = getSyncElapsedMs();
-      let result = await agent.run(context, tools);
+      let result: AgentRunResult;
+      if (
+        phaseSplit &&
+        !isMetaIssue(issue) &&
+        !isBugFixIssue(issue) &&
+        iteration === 1 &&
+        context.v2 === true
+      ) {
+        // Phase-split: DESIGN turn (taste — strong budget) then BUILD turn
+        // (translation — cheap budget) forked from the design session so
+        // the accepted design context carries over without re-reading.
+        // Bug-fix issues are excluded — a defect on a shipped card needs a
+        // diagnose-and-fix turn, not a fresh design round (issue-fix-v2).
+        context.phase = 'design';
+        // Unconditional: the turn-budget block above just stamped the BUILD
+        // budget (iteration 1 of a non-meta issue selects modelPolicy.build)
+        // onto this same context, and `modelPolicy.design` is intentionally
+        // unset (= inherit the session flagship). A conditional override
+        // could never fire, so the taste turn silently ran on the cheap
+        // translation model.
+        context.modelBudget = modelPolicy?.design;
+        log.info(
+          `  Phase-split: DESIGN turn starting (budget ${
+            modelPolicy?.design
+              ? `${modelPolicy.design.model ?? 'inherit'}/${modelPolicy.design.effort ?? 'inherit'}`
+              : 'inherit flagship session'
+          })`,
+        );
+        let designResult = await runTurn(context, {
+          issueTitle: issueDisplayTitle(issue),
+          turnType: 'design',
+          iteration,
+          maxIterations: maxIterationsPerIssue,
+        });
+        allToolCalls.push(...designResult.toolCalls);
+        if (designResult.status === 'blocked') {
+          result = designResult;
+        } else {
+          let buildContext: AgentContext = { ...context };
+          buildContext.phase = 'build';
+          buildContext.modelBudget = modelPolicy?.build;
+          if (designResult.sessionId) {
+            buildContext.resumeSession = {
+              sessionId: designResult.sessionId,
+              fork: true,
+            };
+          }
+          let buildBudgetLabel = modelPolicy?.build
+            ? `${modelPolicy.build.model ?? 'inherit'}/${modelPolicy.build.effort ?? 'inherit'}`
+            : 'inherit';
+          log.info(
+            `  Phase-split: BUILD turn starting (budget ${buildBudgetLabel})`,
+          );
+          if (runLog) {
+            await runLog.append(
+              [
+                {
+                  kind: 'phase',
+                  headline: 'Design accepted — handing off to the build turn',
+                  body: `Mockups + design notes locked; translation runs on the ${buildBudgetLabel} budget, forked from the design session.`,
+                },
+              ],
+              undefined,
+              { stream: true },
+            );
+          }
+          result = await runTurn(buildContext, {
+            issueTitle: issueDisplayTitle(issue),
+            turnType: 'build',
+            iteration,
+            maxIterations: maxIterationsPerIssue,
+          });
+        }
+      } else {
+        result = await runTurn(context, {
+          issueTitle: issueDisplayTitle(issue),
+          turnType:
+            issue.issueType === 'bootstrap'
+              ? 'bootstrap'
+              : issue.issueType === 'analysis'
+                ? 'analysis'
+                : issue.issueType === 'design'
+                  ? 'design-foundation'
+                  : isBugFixIssue(issue) || iteration >= 2
+                    ? 'fix'
+                    : 'implement',
+          iteration,
+          maxIterations: maxIterationsPerIssue,
+        });
+      }
       let toolSyncMs = getSyncElapsedMs() - agentSyncStartMs;
       let agentMs = Math.max(0, Date.now() - agentStartMs - toolSyncMs);
       cur.agentMs += agentMs;
       grand.agentMs += agentMs;
       allToolCalls.push(...result.toolCalls);
 
+      // Seed the next iteration's chain from this turn's session (the build
+      // turn's, in phase-split). Non-meta only — meta issues never chain.
+      if (result.sessionId && !isMetaIssue(issue)) {
+        iterationSessionId = result.sessionId;
+      }
+
       log.info(
         `  Agent returned ${result.toolCalls.length} tool call(s)${debug ? ` in ${fmtSecs(agentMs)}` : ''}`,
       );
 
+      // Post-turn design summary only when nothing streamed live (the
+      // stream handler already posted each design round as it happened).
+      if (runLog && !streamHandler?.sawDesign()) {
+        let designEntries = await designEntriesFromToolCalls(
+          result.toolCalls,
+          targetRealm,
+          workspaceDir,
+        );
+        if (designEntries.length > 0) {
+          await runLog.append(designEntries);
+        }
+      }
+
       // The agent itself reports "I cannot proceed" via two paths:
       // calling `request_clarification` (clarification.message), or
       // an unrecoverable backend error (e.g. session.error from
@@ -449,6 +1352,17 @@ export async function runIssueLoop(
         let blockMessage =
           result.message?.trim() || 'agent reported it could not proceed';
         log.info(`  Agent reported blocked: ${blockMessage}`);
+        if (runLog) {
+          await runLog.append([
+            {
+              kind: 'blocked',
+              headline: `Blocked: ${issueDisplayTitle(issue)}`,
+              body: blockMessage,
+              cardPath: issueCardPath(issue, controlRealm),
+              cardRealm: 'control' as const,
+            },
+          ]);
+        }
         try {
           await issueStore.updateIssue(issue.id, { status: 'blocked' });
           await syncWorkspace();
@@ -470,7 +1384,20 @@ export async function runIssueLoop(
       // Pass the iteration number so all steps use it as the sequence
       // number in artifact filenames (parse_slug-1, lint_slug-1, etc.)
       let validationStartMs = Date.now();
+      let endValidationSpan = startSpan('validation', 'pipeline', {
+        issue: issueSlug(issue),
+        iteration,
+      });
       validationResults = await validator.validate(targetRealm, iteration);
+      endValidationSpan({
+        passed: validationResults.passed,
+        steps: validationResults.steps.length,
+        failedSteps:
+          validationResults.steps
+            .filter((s) => !s.passed)
+            .map((s) => s.step)
+            .join(',') || undefined,
+      });
       let validationMs = Date.now() - validationStartMs;
       cur.validationMs += validationMs;
       grand.validationMs += validationMs;
@@ -513,19 +1440,119 @@ export async function runIssueLoop(
         }`,
       );
 
+      if (runLog && validationResults) {
+        // Link the most informative step's Validation card: the first
+        // failing step, else the last step that ran. Step cards are written
+        // by the pipeline at Validations/<step>_<issueId>-<iteration>
+        // ('evaluate' files as 'eval_'). The in-process 'imports' step
+        // writes no artifact card, so it can't be the linked focus.
+        let linkableSteps = validationResults.steps.filter(
+          (s) => s.step !== 'imports',
+        );
+        let focusStep =
+          linkableSteps.find((s) => !s.passed) ??
+          linkableSteps[linkableSteps.length - 1];
+        let stepFile =
+          focusStep?.step === 'evaluate' ? 'eval' : focusStep?.step;
+        await runLog.append([
+          {
+            kind: 'validation',
+            headline: validationResults.passed
+              ? 'Validation passed'
+              : 'Validation failed — revising',
+            body: formatValidation(validationResults),
+            ...(focusStep
+              ? {
+                  cardPath: `Validations/${stepFile}_${issue.id}-${iteration}`,
+                  cardRealm: 'control' as const,
+                }
+              : {}),
+          },
+        ]);
+      }
+
       // The loop owns issue status transitions. The agent signals
-      // completion via signal_done; the loop promotes to "done" only
-      // when signal_done is called, validation passes, AND the sync
+      // completion via signal_done; the loop promotes only when
+      // signal_done is called, validation passes, AND the sync
       // succeeded. A failed sync means the realm doesn't have the
       // agent's writes, so marking the issue done would claim
       // completion for work that isn't actually delivered.
+      //
+      // Reviewable issues go 'in_progress' → 'review' → (PM review turn)
+      // → 'done', or bounce back ONCE to 'in_progress' with the
+      // reviewer's comments as next-iteration context.
       let agentSignaledDone = result.toolCalls.some(
         (tc) => tc.tool === 'signal_done',
       );
 
+      let reworkFeedback: string | undefined;
       if (agentSignaledDone && validationResults?.passed && !syncFailed) {
+        let reviewable =
+          renderGate !== undefined &&
+          acceptanceWalkthrough &&
+          !isMetaIssue(issue) &&
+          // Never review a defect issue: the reviewer is what FILES
+          // defect issues, so reviewing defect fixes can chain
+          // (defect-v2 → v3 …, observed on wardrobe 2026-07-17).
+          issue.issueType !== 'defect';
+        if (reviewable) {
+          try {
+            await issueStore.updateIssue(issue.id, { status: 'review' });
+            await emitStatusChange(issue, 'review', 'in_progress');
+          } catch (err) {
+            log.warn(
+              `  Failed to mark issue in review: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+          let review = await runReviewGate();
+          if (review.verdict === 'rework' && reviewBounces === 0) {
+            reworkFeedback = review.feedback;
+          } else if (review.verdict === 'rework') {
+            log.info(
+              '  Reviewer requested rework again — bias to ship: approving; further improvements belong in follow-up issues',
+            );
+          }
+        }
+      }
+
+      if (reworkFeedback) {
+        reviewBounces++;
+        log.info('  Review verdict: rework — sending back with comments');
+        try {
+          await issueStore.addComment(issue.id, {
+            body: `**Review — rework requested**\n\n${reworkFeedback}`,
+            author: 'reviewer',
+          });
+          await issueStore.updateIssue(issue.id, { status: 'in_progress' });
+        } catch (err) {
+          log.warn(
+            `  Failed to record rework feedback: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+        // The next inner iteration runs as a fix turn with the review
+        // feedback in its validation-context slot.
+        validationContext = [
+          '# Review feedback (rework requested)',
+          '',
+          'The reviewer sent this issue back. Address the points below with',
+          'surgical Edits, then signal_done again.',
+          '',
+          reworkFeedback,
+        ].join('\n');
+        // Reopen (review → in_progress) with the reviewer's feedback as the
+        // entry body, so both the state change and the comment show in the feed.
+        await emitStatusChange(issue, 'in_progress', 'review', reworkFeedback);
+        await syncWorkspace();
+      } else if (
+        agentSignaledDone &&
+        validationResults?.passed &&
+        !syncFailed
+      ) {
         try {
           await issueStore.updateIssue(issue.id, { status: 'done' });
+          // The `issue-done` milestone entry (emitted below on exitReason
+          // === 'done') is the canonical done event in the feed, so no
+          // separate status-change entry here.
           // updateIssue writes the status flip to the local workspace.
           // refreshIssueState below queries the realm's search index, so
           // the flip has to reach the realm before the refresh — otherwise
@@ -563,7 +1590,10 @@ export async function runIssueLoop(
       // settle on the next pass. Other paths (sync failed, validation
       // failed) refresh once and trust whatever the index shows.
       let expectedDoneSync =
-        agentSignaledDone && validationResults?.passed && !syncFailed;
+        agentSignaledDone &&
+        validationResults?.passed &&
+        !syncFailed &&
+        !reworkFeedback;
       let currentIssue: SchedulableIssue = issue;
       issue = expectedDoneSync
         ? await retryWithPoll(
@@ -614,6 +1644,7 @@ export async function runIssueLoop(
             body: commentBody,
             author: 'orchestrator',
           });
+          await emitComment(issue, 'orchestrator', commentBody);
         } catch (err) {
           log.warn(
             `  Failed to add blocking comment to issue: ${err instanceof Error ? err.message : String(err)}`,
@@ -625,6 +1656,17 @@ export async function runIssueLoop(
             status: 'blocked',
           });
           exitReason = 'blocked';
+          if (runLog) {
+            await runLog.append([
+              {
+                kind: 'blocked',
+                headline: `Issue status: in progress → blocked (max iterations)`,
+                body: `Validation still failing after ${maxIterationsPerIssue} iterations — orchestrator comment added to the issue with the failure context.`,
+                cardPath: issueCardPath(issue, controlRealm),
+                cardRealm: 'control' as const,
+              },
+            ]);
+          }
         } catch (err) {
           log.warn(
             `  Failed to update issue status to blocked: ${err instanceof Error ? err.message : String(err)}`,
@@ -634,6 +1676,7 @@ export async function runIssueLoop(
 
       exhaustedIssues.add(issue.id);
     }
+    endIterationSpan();
 
     // All syncs during this issue (loop-owned + tool-triggered) accrued to the
     // shared counter; the delta is this issue's sync time.
@@ -645,9 +1688,41 @@ export async function runIssueLoop(
       totalMs: Date.now() - cycleStartMs,
     };
 
+    endIssueSpan({
+      exitReason,
+      iterations: innerIterations,
+      agentMs: issueTiming.agentMs,
+      validationMs: issueTiming.validationMs,
+      syncMs: issueTiming.syncMs,
+    });
+
     log.info(
       `Outer cycle ${outerCycles}: issue ${issueSummaryLabel(issue)} completed — exitReason=${exitReason}, iterations=${innerIterations}`,
     );
+
+    if (runLog && exitReason === 'done') {
+      // Native Writes never reach allToolCalls (only MCP tool results do) —
+      // the stream handler's sightings are the real source of instance
+      // paths; cardPathsFromToolCalls stays as a fallback for wirings
+      // without streaming.
+      let cardPaths = streamHandler?.instanceCardPaths() ?? [];
+      if (cardPaths.length === 0) {
+        cardPaths = cardPathsFromToolCalls(allToolCalls);
+      }
+      let cardEntries = cardPaths.slice(0, 3).map((cardPath) => ({
+        kind: 'card-ready' as const,
+        headline: `Card ready: ${cardPath.split('/').pop()?.replace(/-/g, ' ') ?? cardPath}`,
+        body: 'This is the live card — click through to open it.',
+        cardPath,
+      }));
+      await runLog.append([
+        ...cardEntries,
+        {
+          kind: 'issue-done',
+          headline: `Done: ${issueDisplayTitle(issue)}`,
+        },
+      ]);
+    }
     if (debug) {
       log.info(
         `  Timing: agent ${fmtSecs(issueTiming.agentMs)}, validation ${fmtSecs(issueTiming.validationMs)}, sync ${fmtSecs(issueTiming.syncMs)}, total ${fmtSecs(issueTiming.totalMs)}`,
@@ -712,6 +1787,12 @@ export async function runIssueLoop(
 
   log.info(`Outer loop finished: outcome=${outcome}, cycles=${outerCycles}`);
 
+  if (runLog) {
+    await runLog.finish(
+      outcome === 'all_issues_done' ? 'completed' : 'stopped',
+    );
+  }
+
   // Mark the project as completed only when ALL issues in the realm are done
   // (not just the ones we processed). This prevents marking complete when
   // pre-existing blocked issues still exist.
@@ -752,6 +1833,14 @@ export async function runIssueLoop(
     logTimingSummary(issueResults, grand);
   }
 
+  endRunSpan({
+    outcome,
+    cycles: outerCycles,
+    agentMs: grand.agentMs,
+    validationMs: grand.validationMs,
+    syncMs: grand.syncMs,
+  });
+
   return { outcome, outerCycles, issueResults };
 }
 
diff --git a/packages/software-factory/src/issue-scheduler.ts b/packages/software-factory/src/issue-scheduler.ts
index ab4750f95ff..65fc64e5479 100644
--- a/packages/software-factory/src/issue-scheduler.ts
+++ b/packages/software-factory/src/issue-scheduler.ts
@@ -39,6 +39,14 @@ export interface IssueStore {
   listIssues(): Promise<SchedulableIssue[]>;
   /** Re-read a single issue's current state from the realm. */
   refreshIssue(issueId: string): Promise<SchedulableIssue>;
+  /**
+   * Read an issue's status from the AUTHORITATIVE local workspace file
+   * (not the realm index). Returns undefined when the file is absent.
+   * Used to reconcile against a stale index snapshot — the control-plane
+   * sync pushes raw writes that don't wait for indexing, so `listIssues`
+   * can report a status the workspace has already moved past.
+   */
+  readLocalStatus?(issueId: string): Promise<string | undefined>;
   /** Update issue fields in the realm (e.g., status, priority). Descriptions are immutable — use addComment instead. */
   updateIssue(
     issueId: string,
@@ -137,6 +145,11 @@ export class IssueScheduler {
     return this.getUnblockedIssues(exclude).length > 0;
   }
 
+  /** Number of unblocked issues remaining (queue depth for monitor notes). */
+  unblockedCount(exclude?: ReadonlySet<string>): number {
+    return this.getUnblockedIssues(exclude).length;
+  }
+
   /** True if the loaded issue list is non-empty (regardless of status). */
   hasAnyIssues(): boolean {
     return this.issues.length > 0;
@@ -247,6 +260,20 @@ export class RealmIssueStore implements IssueStore {
     return mapCardToSchedulableIssue(result.data[0]);
   }
 
+  async readLocalStatus(issueId: string): Promise<string | undefined> {
+    let filePath = ensureJsonExtension(
+      toRealmRelativePath(issueId, this.realmUrl),
+    );
+    let readResult = await readCard(this.workspaceDir, filePath);
+    if (!readResult.ok || !readResult.document) {
+      return undefined;
+    }
+    let doc = readResult.document as unknown as LooseSingleCardDocument;
+    let status = (doc.data.attributes as Record<string, unknown> | undefined)
+      ?.status;
+    return typeof status === 'string' ? status : undefined;
+  }
+
   async updateIssue(
     issueId: string,
     updates: { status?: string; priority?: string },
diff --git a/packages/software-factory/src/realm-issue-relationship-loader.ts b/packages/software-factory/src/realm-issue-relationship-loader.ts
index 0f91db2fffd..fbe05b318a4 100644
--- a/packages/software-factory/src/realm-issue-relationship-loader.ts
+++ b/packages/software-factory/src/realm-issue-relationship-loader.ts
@@ -66,7 +66,10 @@ export class RealmIssueRelationshipLoader implements IssueRelationshipLoader {
 
     let projectLink = extractRelationshipLink(fullIssue, 'project');
     if (!projectLink) {
-      log.info(`Issue "${issue.id}" has no project relationship`);
+      // Expected for seed issues (bootstrap, analysis, design-foundation),
+      // which run before any Project card exists — debug, not info, so it
+      // doesn't drip into every normal-level run log.
+      log.debug(`Issue "${issue.id}" has no project relationship`);
       return undefined;
     }
 
diff --git a/packages/software-factory/src/render-gate.ts b/packages/software-factory/src/render-gate.ts
new file mode 100644
index 00000000000..92b036830a8
--- /dev/null
+++ b/packages/software-factory/src/render-gate.ts
@@ -0,0 +1,192 @@
+/**
+ * Render gate (v3 P0) — the first rung of the runtime feedback loop.
+ *
+ * Every static gate can pass while the card renders an empty section, a
+ * broken layout, or an invisible affordance (the wardrobe run shipped all
+ * five issues green and every one had a runtime defect). The render gate
+ * closes the cheapest half of that hole: after an issue finishes, capture
+ * real host-rendered screenshots of the cards it shipped via the realm
+ * server's `POST /_screenshot-card` endpoint, attach them to the run log,
+ * and hand the PNG paths to the acceptance walkthrough turn — whose agent
+ * READS them with its image-capable Read tool and verdicts each
+ * acceptance criterion against what is actually on screen.
+ *
+ * Endpoint contract (see realm-server handle-screenshot-card):
+ * - formats: 'isolated' | 'embedded' only (fitted capture is an upstream
+ *   ask — the prerenderer doesn't expose a sized fitted container yet).
+ * - response: { data: { attributes: { status, base64?, width?, height?,
+ *   error? } } }; status 'ready' is necessary but NOT sufficient for
+ *   async domain renderers (WebGL/PDF/media may not have painted — bug
+ *   report filed 2026-07-17), so treat screenshots of such cards as
+ *   advisory.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
+
+import { logger } from './logger.ts';
+
+const log = logger('render-gate');
+
+export type ScreenshotFormat = 'isolated' | 'embedded';
+
+/**
+ * A uniform-color PNG (blank render) compresses to almost nothing; a real
+ * card screenshot is comfortably above this. Below the threshold we flag
+ * the capture as a suspected blank so the walkthrough looks harder.
+ */
+const SUSPECT_BLANK_BYTES = 3_000;
+
+export interface RenderGateOptions {
+  /** Owns auth: `authedServerFetch` carries the realm-server JWT. */
+  client: BoxelCLIClient;
+  realmServerUrl: string;
+  /** Product realm the cards live in. */
+  targetRealm: string;
+  /** Shared local workspace; PNGs land under design/render/. */
+  workspaceDir: string;
+}
+
+export interface CardScreenshotResult {
+  /** Realm-relative card path (no .json), e.g. `Garment/cloudmark-tee`. */
+  cardPath: string;
+  format: ScreenshotFormat;
+  ok: boolean;
+  /** Workspace-relative PNG path on success. */
+  outputPath?: string;
+  width?: number;
+  height?: number;
+  bytes?: number;
+  /** Tiny PNG — likely an empty/blank render. */
+  suspectBlank?: boolean;
+  error?: string;
+}
+
+export class RenderGate {
+  private opts: RenderGateOptions;
+
+  constructor(opts: RenderGateOptions) {
+    this.opts = opts;
+  }
+
+  /**
+   * Capture isolated + embedded screenshots for each card path (bounded
+   * by `limit` cards). Sequential on purpose: the prerenderer queue
+   * serializes per realm anyway, and burst-enqueueing just times out.
+   * A failed capture retries once after a short indexing-settle delay.
+   */
+  async captureCards(
+    cardPaths: string[],
+    opts?: { limit?: number },
+  ): Promise<CardScreenshotResult[]> {
+    let limit = opts?.limit ?? 4;
+    let results: CardScreenshotResult[] = [];
+    for (let cardPath of cardPaths.slice(0, limit)) {
+      for (let format of ['isolated', 'embedded'] as const) {
+        let result = await this.captureOne(cardPath, format);
+        if (!result.ok) {
+          // One retry — the most common failure is the index not having
+          // settled the just-synced instance yet.
+          await sleep(5_000);
+          result = await this.captureOne(cardPath, format);
+        }
+        results.push(result);
+      }
+    }
+    return results;
+  }
+
+  private async captureOne(
+    cardPath: string,
+    format: ScreenshotFormat,
+  ): Promise<CardScreenshotResult> {
+    let { client, realmServerUrl, targetRealm, workspaceDir } = this.opts;
+    let cardId = new URL(cardPath, targetRealm).href;
+    try {
+      let response = await client.authedServerFetch(
+        new URL('_screenshot-card', realmServerUrl),
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            data: {
+              type: 'screenshot-card',
+              attributes: { realmURL: targetRealm, cardId, format },
+            },
+          }),
+        },
+      );
+      if (!response.ok) {
+        let text = await response.text().catch(() => '');
+        return {
+          cardPath,
+          format,
+          ok: false,
+          error: `HTTP ${response.status}: ${text.slice(0, 200)}`,
+        };
+      }
+      let body = (await response.json()) as {
+        data?: {
+          attributes?: {
+            status?: string;
+            base64?: string;
+            width?: number;
+            height?: number;
+            error?: string | null;
+          };
+        };
+      };
+      let attrs = body.data?.attributes;
+      if (attrs?.status !== 'ready' || !attrs.base64) {
+        return {
+          cardPath,
+          format,
+          ok: false,
+          error: `screenshot ${attrs?.status ?? 'no response'}: ${attrs?.error ?? 'no image data'}`,
+        };
+      }
+      let png = Buffer.from(attrs.base64, 'base64');
+      let outputPath = `design/render/${cardPath.replace(/\//g, '-')}-${format}.png`;
+      let absolute = join(workspaceDir, outputPath);
+      await mkdir(dirname(absolute), { recursive: true });
+      await writeFile(absolute, png);
+      let suspectBlank = png.byteLength < SUSPECT_BLANK_BYTES;
+      log.info(
+        `render gate: ${cardPath} (${format}) → ${outputPath} (${png.byteLength} bytes${suspectBlank ? ', SUSPECT BLANK' : ''})`,
+      );
+      return {
+        cardPath,
+        format,
+        ok: true,
+        outputPath,
+        width: attrs.width,
+        height: attrs.height,
+        bytes: png.byteLength,
+        ...(suspectBlank ? { suspectBlank: true } : {}),
+      };
+    } catch (error) {
+      let message = error instanceof Error ? error.message : String(error);
+      log.warn(`render gate capture failed for ${cardPath}: ${message}`);
+      return { cardPath, format, ok: false, error: message };
+    }
+  }
+}
+
+/** One-line human summary for the run log / walkthrough prompt. */
+export function summarizeRenderResults(
+  results: CardScreenshotResult[],
+): string {
+  let ok = results.filter((r) => r.ok && !r.suspectBlank).length;
+  let blank = results.filter((r) => r.suspectBlank).length;
+  let failed = results.filter((r) => !r.ok).length;
+  let parts = [`${ok}/${results.length} surfaces captured clean`];
+  if (blank > 0) parts.push(`${blank} suspected blank`);
+  if (failed > 0) parts.push(`${failed} failed to render`);
+  return parts.join(', ');
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
diff --git a/packages/software-factory/src/run-log.ts b/packages/software-factory/src/run-log.ts
new file mode 100644
index 00000000000..d185347c072
--- /dev/null
+++ b/packages/software-factory/src/run-log.ts
@@ -0,0 +1,2394 @@
+/**
+ * Run log — the live-blog surface for a factory run.
+ *
+ * The factory writes a `run-log.gts` module (a `RunLog` app card + a
+ * `RunLogEntry` card) into the control realm. Each real event (issue picked,
+ * design screenshot, validation result, card ready, run done) becomes ONE
+ * `RunLogEntry` instance under `RunLogEntries/` — a single small write, never
+ * a rewrite of a growing array. The `RunLog` isolated view is a live,
+ * realm-scoped, newest-first, page-capped query over those entries (the same
+ * shape as the platform's workspace Activity feed). The operator watches the
+ * card in the realm instead of tailing a terminal; design screenshots embed
+ * as images and the REAL built card embeds live, each via a `linksTo` on its
+ * entry. Churn kinds (status/iteration) are dropped so the feed stays a blog
+ * of milestones, not an audit log.
+ */
+
+import {
+  readFile,
+  writeFile,
+  mkdir,
+  stat,
+  copyFile,
+  readdir,
+} from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { isControlPath } from './control-plane-sync.ts';
+import { logger } from './logger.ts';
+
+const log = logger('run-log');
+
+// ---------------------------------------------------------------------------
+// Card-reference auto-linking
+// ---------------------------------------------------------------------------
+
+/**
+ * A card-instance path under a capitalized card-type directory
+ * (`Knowledge Articles/…`, `Garment/…`, `Spec/…`) — a single PascalCase
+ * token or the literal `Knowledge Articles` (the base catalog's only spaced
+ * dir), then `/<name>.json`. Deliberately narrow so prose like "the Foo Bar
+ * report" and non-card files (`design/tokens.css`, lowercase dirs) never
+ * match. As a source fragment (no flags/anchors) so it can be composed into
+ * the directive/link/bare matchers below.
+ */
+const CARD_PATH = String.raw`(Knowledge Articles|[A-Z][A-Za-z0-9]+)\/([A-Za-z0-9._-]+)\.json`;
+
+/**
+ * Resolve a workspace card path (`<dir>/<name>`, no `.json`) to its full
+ * card URL. Control-plane paths (Knowledge Articles, Issues, Projects,
+ * Boards, …) resolve against the control realm; product cards — built
+ * cards (Garment, Outfit, …) and their Catalog Specs — against the
+ * product realm.
+ */
+function resolveCardUrl(
+  dir: string,
+  name: string,
+  realms: { controlRealm?: string; productRealm: string },
+): string {
+  let relPath = `${dir}/${name}`;
+  let base = isControlPath(relPath)
+    ? (realms.controlRealm ?? realms.productRealm)
+    : realms.productRealm;
+  return new URL(relPath, base).href;
+}
+
+/**
+ * Resolve card references in a run-log entry body so the MarkdownField
+ * renders them as live cards. The agent is taught (post_update tool) to
+ * author BFM card directives using the workspace PATH and to choose the
+ * format — inline `:card[…]` (atom), block `::card[…]` (embedded), or
+ * `::card[… | fitted strip]` (a sized tile). It knows the path but not the
+ * realm routing, so this fills in the full URL and picks control-vs-product
+ * realm. Four ordered rewrites, applied only outside fenced code blocks
+ * (BFM keeps directives literal there, so rewriting would corrupt code
+ * samples):
+ *
+ *  1. markdown-link targets   `[text](Dir/name.json)`      → `[text](URL)`
+ *  2. block directives        `::card[Dir/name.json | s]`  → `::card[URL | s]`
+ *  3. inline directives       `:card[Dir/name.json]`       → `:card[URL]`
+ *  4. bare / backticked paths  `` `Dir/name.json` ``        → `:card[URL]` (atom fallback)
+ *
+ * Directives the agent already wrote with a full URL carry no `.json` path
+ * segment, so they pass through untouched. Unresolvable targets degrade to
+ * a muted pill, so linking a not-yet-indexed card is safe.
+ */
+export function autolinkCardReferences(
+  body: string,
+  realms: { controlRealm?: string; productRealm: string },
+): string {
+  let resolve = (dir: string, name: string) =>
+    resolveCardUrl(dir, name, realms);
+  let segments = body.split(/(```[\s\S]*?```)/g);
+  return segments
+    .map((segment) => {
+      if (segment.startsWith('```')) return segment;
+      return (
+        segment
+          // 1. Markdown-link targets — keep the link, resolve the path.
+          .replace(
+            new RegExp(String.raw`\]\(\s*${CARD_PATH}\s*\)`, 'g'),
+            (_m, dir, name) => `](${resolve(dir, name)})`,
+          )
+          // 2. Block directives with an optional `| spec` — preserve the spec.
+          .replace(
+            new RegExp(
+              String.raw`::card\[\s*${CARD_PATH}\s*(\|[^\]]*?)?\s*\]`,
+              'g',
+            ),
+            (_m, dir, name, spec) =>
+              `::card[${resolve(dir, name)}${spec ? ` ${spec.trim()}` : ''}]`,
+          )
+          // 3. Inline directives (single colon; not the `::` block form).
+          .replace(
+            new RegExp(String.raw`(?<!:):card\[\s*${CARD_PATH}\s*\]`, 'g'),
+            (_m, dir, name) => `:card[${resolve(dir, name)}]`,
+          )
+          // 4. Bare or backticked path in prose → inline atom fallback.
+          .replace(
+            new RegExp(String.raw`\`?${CARD_PATH}\`?`, 'g'),
+            (_m, dir, name) => `:card[${resolve(dir, name)}]`,
+          )
+      );
+    })
+    .join('');
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RunLogEntryInput {
+  kind:
+    | 'phase'
+    | 'issue-picked'
+    | 'design'
+    | 'validation'
+    | 'card-ready'
+    | 'issue-done'
+    | 'run-done'
+    | 'status'
+    | 'status-change'
+    | 'iteration'
+    | 'comment'
+    | 'progress'
+    | 'decision'
+    | 'agent-spawn'
+    | 'blocked'
+    | 'note'
+    // Orchestrator monitor (v3): stall narration / scheduler / watchdog
+    // notes, and per-turn cost/duration telemetry. See run-monitor.ts.
+    | 'monitor'
+    | 'telemetry';
+  headline: string;
+  body?: string;
+  /** Absolute URL of a screenshot image to embed (public realms only). */
+  imageUrl?: string;
+  /**
+   * Realm-relative path of the screenshot's FILE CARD (extension kept,
+   * e.g. `design/song-isolated.png`) — preferred over imageUrl: the PngDef
+   * card renders with realm auth handled.
+   */
+  imageCardPath?: string;
+  /**
+   * Realm-relative card path (no .json extension, relative to realm root,
+   * e.g. `JaraokePlayer/thursday-night-jaraoke`) — embeds the live card.
+   */
+  cardPath?: string;
+  /**
+   * Which realm `cardPath` is relative to under the v3 control/product
+   * split: 'product' (default — built cards in the target realm) or
+   * 'control' (issues, validation artifacts). Links are written as
+   * absolute URLs so they resolve regardless of which realm hosts the
+   * run log. Without a split the two realms coincide.
+   */
+  cardRealm?: 'product' | 'control';
+  /**
+   * Absolute URL of the Issue card this entry belongs to (issues live in the
+   * control realm). Set on every entry produced during an issue's turn so the
+   * feed row links straight to the issue — the portal from which the operator
+   * reaches the project, spec, built card, and acceptance criteria.
+   */
+  issueUrl?: string;
+  /** Who is speaking: orchestrator | executor | validator | an agent name. */
+  who?: string;
+}
+
+export interface RunLogWriterOptions {
+  workspaceDir: string;
+  targetRealm: string;
+  /**
+   * Control realm hosting the run log under the v3 split. Defaults to
+   * `targetRealm` (no split). Entry links resolve absolute: cardPath
+   * against `targetRealm` (or `controlRealm` when the entry says
+   * `cardRealm: 'control'`), imageCardPath against `targetRealm` (design
+   * PNGs ride the product sync — raw writes are text-only).
+   */
+  controlRealm?: string;
+  runSlug: string;
+  runTitle: string;
+  /** Push the workspace to the realm (the loop's shared sync gate). */
+  syncWorkspace: () => Promise<{ ok: boolean; error?: string }>;
+  /**
+   * Raw single-file write to the realm (card-source MIME, content as-is).
+   * Workaround for the /_atomic?waitForIndex=true bug that rewrites card
+   * sources with containsMany FieldDef attributes stripped to `{}`: after
+   * every workspace sync, the run-log instance is re-written raw so the
+   * live blog keeps its entry data. Optional — when absent the writer
+   * relies on syncWorkspace alone (and entries may render blank).
+   */
+  rawWriteFile?: (
+    relativePath: string,
+    content: string,
+  ) => Promise<{ ok: boolean; error?: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// Writer
+// ---------------------------------------------------------------------------
+
+/**
+ * Kinds that are audit-trail churn, not live-blog milestones — every issue
+ * status transition and inner-iteration marker. They were the bulk of the
+ * old run log's volume (hundreds of "backlog → in progress → done" lines) and
+ * would flood the feed. They never become entry cards; the meaningful signal
+ * they carried lives in `issue-done` / `card-ready` / `blocked` entries and
+ * in the index card's `nowWorkingOn`.
+ */
+const FEED_NOISE_KINDS = new Set(['status', 'iteration']);
+
+/** How many of the most-recent legacy entries a migration carries forward. */
+const MIGRATION_KEEP_RECENT = 60;
+
+export class RunLogWriter {
+  private opts: RunLogWriterOptions;
+  /** The small RunLog "index" card: masthead, status, and milestone counters. */
+  private instancePath: string;
+  /** Directory of one-file-per-entry RunLogEntry cards. */
+  private entriesDir: string;
+  /** Monotonic per-run entry sequence — the feed query's stable sort key. */
+  private seq = 0;
+  /**
+   * Milestone counters mirrored onto the index card so the header renders
+   * without scanning the feed. Entries are separate cards now, so a new
+   * entry is one small write — never a rewrite of a growing array.
+   */
+  private counts = {
+    entry: 0,
+    cardsReady: 0,
+    designRounds: 0,
+    validationsGreen: 0,
+    issuesDone: 0,
+  };
+  /**
+   * All writes are serialized through this chain: streamed appends fire
+   * from tool-call hooks mid-agent-turn and would otherwise race the
+   * loop's own read-modify-write appends.
+   */
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(opts: RunLogWriterOptions) {
+    this.opts = opts;
+    this.instancePath = join(opts.workspaceDir, 'Runs', `${opts.runSlug}.json`);
+    this.entriesDir = join(opts.workspaceDir, 'RunLogEntries');
+  }
+
+  private enqueue(fn: () => Promise<void>): Promise<void> {
+    let next = this.chain.then(fn, fn);
+    this.chain = next;
+    return next;
+  }
+
+  /** Idempotent: writes the CardDef module if missing and creates or re-arms the index card. */
+  async start(): Promise<void> {
+    try {
+      let modulePath = join(this.opts.workspaceDir, 'run-log.gts');
+      // Always (re)write the module so a code-level RUN_LOG_GTS upgrade
+      // propagates to existing realms on restart. The control-plane sync is
+      // content-hash-gated, so an unchanged module is a no-op over the wire.
+      await writeFile(modulePath, RUN_LOG_GTS, 'utf8');
+      await mkdir(this.entriesDir, { recursive: true });
+
+      if (await fileExists(this.instancePath)) {
+        // Restart. If the existing index is the legacy containsMany format,
+        // convert its entries[] array into individual RunLogEntry cards
+        // before continuing (one-time, in place). Otherwise just recover seq
+        // + counters so the sequence continues monotonically.
+        let migrated = await this.migrateLegacyIndexIfNeeded();
+        if (!migrated) {
+          await this.recoverState();
+        }
+        await this.append([
+          {
+            kind: 'phase',
+            headline: 'Run restarted',
+            body: `New factory run against this brief started at ${new Date().toISOString()}.`,
+          },
+        ]);
+        await this.patch({ status: 'running' });
+        return;
+      }
+
+      let doc = {
+        data: {
+          type: 'card',
+          attributes: {
+            runTitle: this.opts.runTitle,
+            status: 'running',
+            nowWorkingOn: 'Bootstrapping',
+            upNext: null,
+            startedAt: new Date().toISOString(),
+            finishedAt: null,
+            runId: this.opts.runSlug,
+            entryCount: 0,
+            cardsReadyCount: 0,
+            designRoundsCount: 0,
+            validationsGreenCount: 0,
+            issuesDoneCount: 0,
+            cardInfo: {
+              name: `Run log — ${this.opts.runTitle}`,
+              notes: null,
+              summary:
+                'Live blog of this factory run: design rounds, validations, and finished cards as they land.',
+              cardThumbnailURL: null,
+            },
+          },
+          relationships: {},
+          meta: {
+            adoptsFrom: { module: '../run-log', name: 'RunLog' },
+          },
+        },
+      };
+      await mkdir(dirname(this.instancePath), { recursive: true });
+      await writeFile(this.instancePath, JSON.stringify(doc, null, 2), 'utf8');
+      await this.append([{ kind: 'phase', headline: 'Run started' }]);
+    } catch (error) {
+      // The run log must never take down a run.
+      log.warn(`run-log start failed: ${String(error)}`);
+    }
+  }
+
+  /**
+   * Restore `seq` and `counts` after a restart: the highest existing entry
+   * seq for this run, and the counters last written to the index card.
+   */
+  private async recoverState(): Promise<void> {
+    try {
+      let doc = JSON.parse(await readFile(this.instancePath, 'utf8'));
+      let a = doc?.data?.attributes ?? {};
+      this.counts = {
+        entry: Number(a.entryCount) || 0,
+        cardsReady: Number(a.cardsReadyCount) || 0,
+        designRounds: Number(a.designRoundsCount) || 0,
+        validationsGreen: Number(a.validationsGreenCount) || 0,
+        issuesDone: Number(a.issuesDoneCount) || 0,
+      };
+    } catch {
+      // Index unreadable — counters stay at zero.
+    }
+    try {
+      let prefix = `${this.opts.runSlug}-`;
+      let files = await readdir(this.entriesDir);
+      let maxSeq = 0;
+      for (let f of files) {
+        if (!f.startsWith(prefix) || !f.endsWith('.json')) continue;
+        let n = Number(f.slice(prefix.length, -'.json'.length));
+        if (Number.isFinite(n) && n > maxSeq) maxSeq = n;
+      }
+      this.seq = Math.max(this.seq, maxSeq);
+    } catch {
+      // No entries dir yet — seq stays as is.
+    }
+  }
+
+  /**
+   * One-time in-place conversion of a legacy containsMany run log into the
+   * card-per-entry format: reads the existing index, and if it carries an
+   * `entries` array, writes one RunLogEntry card per element into
+   * `RunLogEntries/`, rewrites the index without the array (counters
+   * populated), and seeds `this.seq`/`this.counts` so appends continue from
+   * the migrated tail. Returns true when a migration happened. Best-effort —
+   * any failure leaves the run log untouched and returns false.
+   */
+  private async migrateLegacyIndexIfNeeded(): Promise<boolean> {
+    let oldDoc: unknown;
+    try {
+      oldDoc = JSON.parse(await readFile(this.instancePath, 'utf8'));
+    } catch {
+      return false;
+    }
+    let plan = buildLegacyMigration(oldDoc, this.opts.runSlug);
+    if (!plan) return false;
+    try {
+      await mkdir(this.entriesDir, { recursive: true });
+      for (let entry of plan.entries) {
+        await writeFile(
+          join(this.opts.workspaceDir, entry.relPath),
+          JSON.stringify(entry.doc, null, 2),
+          'utf8',
+        );
+      }
+      await writeFile(
+        this.instancePath,
+        JSON.stringify(plan.index, null, 2),
+        'utf8',
+      );
+      this.seq = plan.seq;
+      this.counts = plan.counts;
+      log.info(
+        `run-log migrated ${plan.entries.length} legacy entr${plan.entries.length === 1 ? 'y' : 'ies'} to card format`,
+      );
+      return true;
+    } catch (error) {
+      log.warn(`run-log legacy migration failed: ${String(error)}`);
+      return false;
+    }
+  }
+
+  /**
+   * Append one or more entries in a single write+sync. With
+   * `opts.stream: true` the full workspace sync is skipped — the instance
+   * is raw-written to the realm directly, which is cheap enough to call
+   * from per-tool-call streaming hooks mid-agent-turn.
+   */
+  async append(
+    entries: RunLogEntryInput[],
+    updates?: { nowWorkingOn?: string; upNext?: string },
+    opts?: { stream?: boolean },
+  ): Promise<void> {
+    // Drop churn kinds before they ever become cards — they flood the feed
+    // and add no milestone value. `updates` (now/next) still apply even when
+    // the whole batch was noise.
+    let feedEntries = entries.filter((e) => !FEED_NOISE_KINDS.has(e.kind));
+    if (feedEntries.length === 0 && !updates) return;
+    return this.enqueue(async () => {
+      try {
+        let milestoneBumped = false;
+        for (let entry of feedEntries) {
+          this.seq += 1;
+          this.counts.entry += 1;
+          if (this.bumpCounters(entry)) milestoneBumped = true;
+          let relPath = this.entryRelPath(this.seq);
+          let content = JSON.stringify(
+            this.buildEntryDoc(entry, this.seq),
+            null,
+            2,
+          );
+          await writeFile(
+            join(this.opts.workspaceDir, relPath),
+            content,
+            'utf8',
+          );
+          // Streamed (mid-turn) entries raw-write straight to the realm so
+          // the indexer surfaces them in the live feed without waiting for a
+          // full workspace sync.
+          if (opts?.stream && this.opts.rawWriteFile) {
+            let w = await this.opts.rawWriteFile(relPath, content);
+            if (!w.ok)
+              log.warn(
+                `run-log entry raw-write failed: ${w.error ?? 'unknown'}`,
+              );
+          }
+        }
+
+        // Rewrite the tiny index card only when it actually changed — a
+        // milestone counter moved, an explicit now/next update, or we're
+        // still in the warm-up window (<5 entries) where entryCount drives
+        // the "setup phase" hint. Plain comments after warm-up touch nothing
+        // but their own entry card.
+        let needIndexWrite =
+          milestoneBumped || updates !== undefined || this.counts.entry <= 5;
+        if (needIndexWrite) {
+          await this.writeIndex(updates, opts?.stream === true);
+        }
+
+        if (!opts?.stream) {
+          await this.syncUnqueued();
+        }
+      } catch (error) {
+        log.warn(`run-log append failed: ${String(error)}`);
+      }
+    });
+  }
+
+  private entryRelPath(seq: number): string {
+    return `RunLogEntries/${this.opts.runSlug}-${String(seq).padStart(6, '0')}.json`;
+  }
+
+  /** Bump milestone counters for this entry; returns true if any moved. */
+  private bumpCounters(entry: RunLogEntryInput): boolean {
+    if (entry.kind === 'card-ready') {
+      this.counts.cardsReady += 1;
+      return true;
+    }
+    if (entry.kind === 'design') {
+      this.counts.designRounds += 1;
+      return true;
+    }
+    if (entry.kind === 'issue-done') {
+      this.counts.issuesDone += 1;
+      return true;
+    }
+    if (
+      entry.kind === 'validation' &&
+      !(entry.headline ?? '').toLowerCase().includes('fail')
+    ) {
+      this.counts.validationsGreen += 1;
+      return true;
+    }
+    return false;
+  }
+
+  private buildEntryDoc(entry: RunLogEntryInput, seq: number): unknown {
+    let relationships: Record<string, unknown> = {};
+    if (entry.cardPath) {
+      let base =
+        entry.cardRealm === 'control'
+          ? (this.opts.controlRealm ?? this.opts.targetRealm)
+          : this.opts.targetRealm;
+      relationships.card = {
+        links: { self: new URL(entry.cardPath, base).href },
+      };
+    }
+    if (entry.imageCardPath) {
+      relationships.image = {
+        links: {
+          self: new URL(entry.imageCardPath, this.opts.targetRealm).href,
+        },
+      };
+    }
+    if (entry.issueUrl) {
+      relationships.issue = { links: { self: entry.issueUrl } };
+    }
+    return {
+      data: {
+        type: 'card',
+        attributes: {
+          runId: this.opts.runSlug,
+          seq,
+          kind: entry.kind,
+          postedAt: new Date().toISOString(),
+          headline: entry.headline,
+          body: entry.body
+            ? autolinkCardReferences(entry.body, {
+                controlRealm: this.opts.controlRealm,
+                productRealm: this.opts.targetRealm,
+              })
+            : null,
+          imageUrl: entry.imageUrl ?? null,
+          // The writer is the orchestrator's pen; streamed agent entries
+          // pass their own voice ('executor', an agent name, …).
+          who: entry.who ?? 'orchestrator',
+          cardInfo: { name: entry.headline },
+        },
+        relationships,
+        meta: {
+          adoptsFrom: { module: '../run-log', name: 'RunLogEntry' },
+        },
+      },
+    };
+  }
+
+  /** Read-modify-write the small index card (counters + optional now/next). */
+  private async writeIndex(
+    updates: { nowWorkingOn?: string; upNext?: string } | undefined,
+    stream: boolean,
+  ): Promise<void> {
+    let doc = JSON.parse(await readFile(this.instancePath, 'utf8'));
+    let attrs = doc.data.attributes;
+    attrs.entryCount = this.counts.entry;
+    attrs.cardsReadyCount = this.counts.cardsReady;
+    attrs.designRoundsCount = this.counts.designRounds;
+    attrs.validationsGreenCount = this.counts.validationsGreen;
+    attrs.issuesDoneCount = this.counts.issuesDone;
+    if (updates?.nowWorkingOn !== undefined)
+      attrs.nowWorkingOn = updates.nowWorkingOn;
+    if (updates?.upNext !== undefined) attrs.upNext = updates.upNext;
+    let content = JSON.stringify(doc, null, 2);
+    await writeFile(this.instancePath, content, 'utf8');
+    if (stream && this.opts.rawWriteFile) {
+      let w = await this.opts.rawWriteFile(
+        `Runs/${this.opts.runSlug}.json`,
+        content,
+      );
+      if (!w.ok)
+        log.warn(`run-log index raw-write failed: ${w.error ?? 'unknown'}`);
+    }
+  }
+
+  async finish(status: 'completed' | 'failed' | 'stopped'): Promise<void> {
+    try {
+      await this.append(
+        [
+          {
+            kind: 'run-done',
+            headline:
+              status === 'completed' ? 'Run completed' : `Run ${status}`,
+          },
+        ],
+        { nowWorkingOn: '—', upNext: '—' },
+      );
+      await this.patch({ status, finishedAt: new Date().toISOString() });
+    } catch (error) {
+      log.warn(`run-log finish failed: ${String(error)}`);
+    }
+  }
+
+  private async patch(updates: {
+    status?: string;
+    finishedAt?: string;
+  }): Promise<void> {
+    return this.enqueue(async () => {
+      let doc = JSON.parse(await readFile(this.instancePath, 'utf8'));
+      if (updates.status) {
+        doc.data.attributes.status = updates.status;
+      }
+      if (updates.finishedAt) {
+        doc.data.attributes.finishedAt = updates.finishedAt;
+      }
+      let content = JSON.stringify(doc, null, 2);
+      await writeFile(this.instancePath, content, 'utf8');
+      // Best-effort immediate realm write so status flips promptly; the next
+      // full sync reconciles regardless.
+      if (this.opts.rawWriteFile) {
+        await this.opts.rawWriteFile(`Runs/${this.opts.runSlug}.json`, content);
+      }
+      await this.syncUnqueued();
+    });
+  }
+
+  private async syncUnqueued(): Promise<void> {
+    let result = await this.opts.syncWorkspace();
+    if (!result.ok) {
+      log.warn(`run-log sync failed: ${result.error ?? 'unknown'}`);
+    }
+  }
+
+  /**
+   * Vestigial no-op. The FieldDef-strip heal existed only because the run
+   * log was a single card with a `containsMany(RunLogEntry)` array that the
+   * `/_atomic?waitForIndex=true` path stripped to `{}` on every sync. Entries
+   * are now independent cards with no containsMany field, so nothing gets
+   * stripped and there is nothing to heal. Kept so the loop's postSyncHeal
+   * wiring compiles without change.
+   */
+  async healInstance(): Promise<void> {
+    return;
+  }
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+interface LegacyMigrationPlan {
+  index: unknown;
+  entries: { relPath: string; doc: unknown }[];
+  seq: number;
+  counts: RunLogWriter['counts'];
+}
+
+/**
+ * Pure conversion of a legacy containsMany run-log index document into the
+ * card-per-entry plan. Returns null when the doc is not legacy (no
+ * `attributes.entries` array) — e.g. an already-migrated index or a fresh
+ * one. Exported for direct testing.
+ *
+ * Each `entries[i]` element (fields `kind`, `at`, `headline`, `body`,
+ * `imageUrl`, `who`) becomes a RunLogEntry card at
+ * `RunLogEntries/<runSlug>-<seq>.json`, carrying forward its `entries.i.card`
+ * / `entries.i.image` links from the index's relationships. The rewritten
+ * index keeps the masthead fields and drops the array in favor of counters.
+ */
+export function buildLegacyMigration(
+  oldDoc: unknown,
+  runSlug: string,
+): LegacyMigrationPlan | null {
+  let data = (oldDoc as { data?: { attributes?: any; relationships?: any } })
+    ?.data;
+  let attrs = data?.attributes;
+  let legacyEntries = attrs?.entries;
+  if (!attrs || !Array.isArray(legacyEntries)) return null;
+
+  let oldRels: Record<string, any> = data?.relationships ?? {};
+
+  // Pass 1 — milestone counters over the WHOLE history, so the rail stats
+  // stay accurate even though we only carry the recent tail forward.
+  let counts = {
+    entry: 0,
+    cardsReady: 0,
+    designRounds: 0,
+    validationsGreen: 0,
+    issuesDone: 0,
+  };
+  legacyEntries.forEach((e: any) => {
+    let kind = e?.kind;
+    let headline = String(e?.headline ?? '');
+    if (kind === 'card-ready') counts.cardsReady += 1;
+    else if (kind === 'design') counts.designRounds += 1;
+    else if (kind === 'issue-done') counts.issuesDone += 1;
+    else if (kind === 'validation' && !headline.toLowerCase().includes('fail'))
+      counts.validationsGreen += 1;
+  });
+
+  // Pass 2 — carry only the most-recent meaningful entries as cards (drop
+  // status/iteration churn; cap the count) so the migration doesn't recreate
+  // the flood we're fixing. Keep original indices for relationship lookup,
+  // then re-sequence the kept entries 1..K.
+  let meaningful = legacyEntries
+    .map((e: any, i: number) => ({ e, i }))
+    .filter(({ e }: { e: any }) => !FEED_NOISE_KINDS.has(e?.kind));
+  let kept = meaningful.slice(-MIGRATION_KEEP_RECENT);
+  let entries: { relPath: string; doc: unknown }[] = kept.map(
+    ({ e, i }: { e: any; i: number }, k: number) => {
+      let seq = k + 1;
+      let headline = e?.headline ?? '';
+      let relationships: Record<string, unknown> = {};
+      let cardLink = oldRels[`entries.${i}.card`]?.links?.self;
+      let imageLink = oldRels[`entries.${i}.image`]?.links?.self;
+      if (cardLink) relationships.card = { links: { self: cardLink } };
+      if (imageLink) relationships.image = { links: { self: imageLink } };
+      return {
+        relPath: `RunLogEntries/${runSlug}-${String(seq).padStart(6, '0')}.json`,
+        doc: {
+          data: {
+            type: 'card',
+            attributes: {
+              runId: runSlug,
+              seq,
+              kind: e?.kind ?? 'note',
+              postedAt: e?.at ?? null,
+              headline,
+              body: e?.body ?? null,
+              imageUrl: e?.imageUrl ?? null,
+              who: e?.who ?? 'orchestrator',
+              cardInfo: { name: headline || 'Run log entry' },
+            },
+            relationships,
+            meta: { adoptsFrom: { module: '../run-log', name: 'RunLogEntry' } },
+          },
+        },
+      };
+    },
+  );
+  counts.entry = kept.length;
+
+  let index = {
+    data: {
+      type: 'card',
+      attributes: {
+        runTitle: attrs.runTitle ?? null,
+        status: attrs.status ?? 'running',
+        nowWorkingOn: attrs.nowWorkingOn ?? null,
+        upNext: attrs.upNext ?? null,
+        startedAt: attrs.startedAt ?? null,
+        finishedAt: attrs.finishedAt ?? null,
+        runId: runSlug,
+        entryCount: counts.entry,
+        cardsReadyCount: counts.cardsReady,
+        designRoundsCount: counts.designRounds,
+        validationsGreenCount: counts.validationsGreen,
+        issuesDoneCount: counts.issuesDone,
+        cardInfo: attrs.cardInfo ?? { name: `Run log — ${runSlug}` },
+      },
+      relationships: {},
+      meta: { adoptsFrom: { module: '../run-log', name: 'RunLog' } },
+    },
+  };
+
+  return { index, entries, seq: kept.length, counts };
+}
+
+// ---------------------------------------------------------------------------
+// Live-blog streaming: tool-call events → run-log entries, mid-agent-turn
+// ---------------------------------------------------------------------------
+
+const POST_UPDATE_KINDS = new Set(['comment', 'progress', 'decision']);
+const CHECK_TOOLS = [
+  'run_lint',
+  'run_parse',
+  'run_evaluate',
+  'run_instantiate',
+];
+const CHECK_FAIL_MIN_INTERVAL_MS = 120_000;
+
+/**
+ * Best-effort one-to-three-line summary of a failed mid-turn self-check
+ * (`run_lint` / `run_parse` / `run_evaluate` / `run_instantiate`), for the
+ * run-log entry's body since these tools write no realm artifact to link
+ * to. Each tool names its failure list and per-item message field
+ * differently (lint: `violations[].message`, parse: `errors[].message`,
+ * evaluate/instantiate: `failures[].error`) — try each in turn and fall
+ * back to `errorMessage` or a generic line so the entry is never blank.
+ */
+export function summarizeCheckFailure(result: unknown): string | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  let r = result as Record<string, unknown>;
+  let items = (r.violations ?? r.errors ?? r.failures) as
+    | Array<Record<string, unknown>>
+    | undefined;
+  if (Array.isArray(items) && items.length > 0) {
+    let lines = items.slice(0, 3).map((item) => {
+      // `||` not `??`: an instantiate failure's `path` is `''` (not
+      // undefined) for a bare-instantiation fallback with no example file,
+      // and an empty string must fall through to `cardName` too.
+      let file = (item.file || item.path || item.cardName) as
+        | string
+        | undefined;
+      let message = (item.message ?? item.error) as string | undefined;
+      return file ? `${file}: ${message ?? 'failed'}` : (message ?? 'failed');
+    });
+    let more = items.length > 3 ? ` (+${items.length - 3} more)` : '';
+    return lines.join('\n') + more;
+  }
+  if (typeof r.errorMessage === 'string' && r.errorMessage) {
+    return r.errorMessage;
+  }
+  return undefined;
+}
+
+/**
+ * Copy a `design/` (or `design/render/`) screenshot into `design-history/`
+ * and return the path a run-log entry should link to instead.
+ *
+ * `design/` is BUILD-turn scratch: once a mockup is translated into a real
+ * card, the agent routinely deletes its `design/*.png` files as tidy-up,
+ * and the next workspace sync mirrors that local deletion to the realm —
+ * silently orphaning any run-log entry that already linked to it.
+ * `design-history/` is never written or touched by the agent, so nothing
+ * ever goes missing there and a later sync has no deletion to propagate.
+ *
+ * Preserves the path under `design/` (not just the basename): the agent
+ * doesn't always slug-prefix screenshot names (this run alone produced
+ * both `design/prompt-template-v1.png` and generic ones like
+ * `design/v2-top.png`), and render-gate output collides by construction
+ * whenever two different cards render the same format. Collapsing to a
+ * bare basename would let a later issue's copy silently overwrite an
+ * earlier issue's already-linked file — same run-log symptom we're
+ * fixing here (a dangling/wrong image), except silent instead of a 404.
+ *
+ * Falls back to the original path (best-effort — the run log must never
+ * fail a turn) if the copy fails for any reason.
+ */
+export async function persistDesignScreenshot(
+  workspaceDir: string,
+  designPath: string,
+): Promise<string> {
+  let historyPath = `design-history/${designPath.replace(/^design\//, '')}`;
+  try {
+    let dest = join(workspaceDir, historyPath);
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(join(workspaceDir, designPath), dest);
+    // Preserve the HTML mockup SOURCE alongside the flattened PNG. The PNG is
+    // a picture of the design; the `.html` is the editable, re-renderable
+    // truth behind it. It lives in scratch `design/` which the agent tidies
+    // away, so copy its sibling into the durable `design-history/` too — a
+    // best-effort archive (render-gate PNGs under design/render/ have no
+    // sibling HTML; missing source is fine).
+    let htmlSource = designPath.replace(/\.png$/i, '.html');
+    if (htmlSource !== designPath) {
+      try {
+        let htmlDest = join(
+          workspaceDir,
+          `design-history/${htmlSource.replace(/^design\//, '')}`,
+        );
+        await mkdir(dirname(htmlDest), { recursive: true });
+        await copyFile(join(workspaceDir, htmlSource), htmlDest);
+      } catch {
+        // No sibling HTML (e.g. a render-gate capture) — nothing to archive.
+      }
+    }
+    return historyPath;
+  } catch (err) {
+    log.warn(
+      `design-history copy failed for ${designPath}, linking it directly: ${String(err)}`,
+    );
+    return designPath;
+  }
+}
+
+/**
+ * Build an `AgentContext.onToolCall` handler that live-blogs an agent turn:
+ *
+ * - `post_update` calls (the agent's own commentary channel) → run-log
+ *   entry + issue comment, verbatim.
+ * - successful `screenshot_html` → a design entry with the image linked
+ *   (full sync so the PNG itself reaches the realm).
+ * - first native Write of each non-test `.gts` → "Writing <file>".
+ * - failed validation checks → one "fixing" note per tool per 2 minutes.
+ *
+ * Everything is fire-and-forget; the writer serializes the actual file
+ * writes. `sawDesign()` tells the loop whether the post-turn design
+ * summary would duplicate what already streamed.
+ */
+export function createRunLogStreamHandler(opts: {
+  runLog: RunLogWriter;
+  addIssueComment?: (body: string) => Promise<void>;
+  /**
+   * Workspace root. Needed to durably copy `design/*.png` into
+   * `design-history/` before linking it — `design/` is BUILD-turn scratch
+   * the agent routinely deletes once a mockup is translated into a real
+   * card, and the next workspace sync mirrors that deletion to the realm,
+   * orphaning the run-log entry that already linked to it. `design-history/`
+   * is never written or touched by the agent, so it never goes missing
+   * locally and the sync never sees a reason to delete it remotely.
+   */
+  workspaceDir: string;
+  /**
+   * Absolute URL of the Issue this turn is working. Attached to every
+   * streamed entry so each feed row links back to its issue.
+   */
+  issueUrl?: string;
+}): {
+  handler: (entry: {
+    tool: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    durationMs?: number;
+  }) => void;
+  sawDesign: () => boolean;
+  /**
+   * Card paths (`<Type>/<id>`, infra dirs excluded) of instance JSONs the
+   * agent wrote this issue — native Writes never reach `result.toolCalls`,
+   * so this is the loop's source for ship-moment card links.
+   */
+  instanceCardPaths: () => string[];
+} {
+  const EXCLUDED_INSTANCE_DIRS =
+    /^(Issues|Projects|Boards|Knowledge(?: |%20)Articles|Spec|Validations|Runs|RunLogEntries|design|design-history|\.factory-scratch)\//;
+  let sawDesign = false;
+  let seenGtsWrites = new Set<string>();
+  let lastCheckFailAt = new Map<string, number>();
+  let instancePaths: string[] = [];
+
+  let handler = (entry: {
+    tool: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+  }): void => {
+    try {
+      let tool = entry.tool.replace(/^mcp__[^_]+__/, '');
+
+      if (tool === 'post_update' || tool.endsWith('post_update')) {
+        let headline = String(entry.args.headline ?? '').trim();
+        if (!headline) return;
+        let body =
+          typeof entry.args.body === 'string' && entry.args.body.trim()
+            ? entry.args.body.trim()
+            : undefined;
+        let kind = POST_UPDATE_KINDS.has(String(entry.args.kind))
+          ? String(entry.args.kind)
+          : 'comment';
+        void opts.runLog.append(
+          [
+            {
+              kind: kind as RunLogEntryInput['kind'],
+              headline,
+              body,
+              who: 'executor',
+              issueUrl: opts.issueUrl,
+            },
+          ],
+          undefined,
+          { stream: true },
+        );
+        if (opts.addIssueComment) {
+          void opts
+            .addIssueComment(body ? `**${headline}**\n\n${body}` : headline)
+            .catch(() => {});
+        }
+        return;
+      }
+
+      if (tool === 'screenshot_html' || tool.endsWith('screenshot_html')) {
+        let result = entry.result as
+          | { ok?: boolean; outputPath?: string }
+          | undefined;
+        if (!result?.ok || !result.outputPath) return;
+        sawDesign = true;
+        let designPath = result.outputPath;
+        let name = designPath.replace(/^design\//, '').replace(/\.png$/, '');
+        void (async () => {
+          let imageCardPath = await persistDesignScreenshot(
+            opts.workspaceDir,
+            designPath,
+          );
+          // Full sync (not stream) so the screenshot file itself reaches the
+          // realm before the entry links it.
+          await opts.runLog.append([
+            {
+              kind: 'design',
+              headline: `Design round: ${name}`,
+              imageCardPath,
+              who: 'executor',
+              issueUrl: opts.issueUrl,
+            },
+          ]);
+        })();
+        return;
+      }
+
+      if (tool === 'Write' || tool === 'Edit') {
+        let filePath = String(entry.args.file_path ?? entry.args.path ?? '');
+        let normalized = filePath.replace(
+          /^.*boxel-factory-workspaces\/[^/]+\//,
+          '',
+        );
+        if (
+          tool === 'Write' &&
+          normalized.endsWith('.json') &&
+          normalized.includes('/') &&
+          !EXCLUDED_INSTANCE_DIRS.test(normalized)
+        ) {
+          let cardPath = normalized.replace(/\.json$/, '');
+          if (!instancePaths.includes(cardPath)) {
+            instancePaths.push(cardPath);
+          }
+          return;
+        }
+        if (!filePath.endsWith('.gts') || filePath.endsWith('.test.gts')) {
+          return;
+        }
+        let name = filePath.split('/').pop() ?? filePath;
+        if (seenGtsWrites.has(name)) return;
+        seenGtsWrites.add(name);
+        void opts.runLog.append(
+          [
+            {
+              kind: 'progress',
+              headline: `Writing ${name}`,
+              body: 'Design accepted — translating the mockup into card code.',
+              who: 'executor',
+              issueUrl: opts.issueUrl,
+            },
+          ],
+          undefined,
+          { stream: true },
+        );
+        return;
+      }
+
+      let checkTool = CHECK_TOOLS.find((t) => tool === t || tool.endsWith(t));
+      if (checkTool) {
+        let result = entry.result as { status?: string } | undefined;
+        if (result?.status !== 'failed') return;
+        let now = Date.now();
+        let last = lastCheckFailAt.get(checkTool) ?? 0;
+        if (now - last < CHECK_FAIL_MIN_INTERVAL_MS) return;
+        lastCheckFailAt.set(checkTool, now);
+        void opts.runLog.append(
+          [
+            {
+              kind: 'progress',
+              headline: `${checkTool.replace('run_', '')} check failed — fixing`,
+              // These mid-turn self-checks (run_lint/run_parse/run_evaluate/
+              // run_instantiate) never write a realm artifact — only the
+              // post-signal_done validation pipeline does, and that already
+              // links its own Validations/ card (see issue-loop.ts). There's
+              // nothing to link to here, so surface the actual failure text
+              // instead of a bare, unclickable headline.
+              body: summarizeCheckFailure(result),
+              who: 'executor',
+              issueUrl: opts.issueUrl,
+            },
+          ],
+          undefined,
+          { stream: true },
+        );
+      }
+    } catch {
+      // Streaming must never break the run.
+    }
+  };
+
+  return {
+    handler,
+    sawDesign: () => sawDesign,
+    instanceCardPaths: () => [...instancePaths],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tool-call extraction helpers (used by the issue loop)
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract design-screenshot events from an agent turn's tool-call log:
+ * the LAST successful screenshot per distinct output path (final state of
+ * each surface), as ready-to-append entries with absolute image URLs.
+ */
+export async function designEntriesFromToolCalls(
+  toolCalls: { tool: string; args: Record<string, unknown>; result: unknown }[],
+  targetRealm: string,
+  workspaceDir: string,
+): Promise<RunLogEntryInput[]> {
+  let latest = new Map<string, { outputPath: string }>();
+  for (let call of toolCalls) {
+    if (!call.tool.endsWith('screenshot_html')) continue;
+    let result = call.result as { ok?: boolean; outputPath?: string } | null;
+    if (!result?.ok || !result.outputPath) continue;
+    latest.set(result.outputPath, { outputPath: result.outputPath });
+  }
+  return Promise.all(
+    [...latest.values()].map(async ({ outputPath }) => {
+      // persist before linking — see persistDesignScreenshot's doc comment.
+      let imageCardPath = await persistDesignScreenshot(
+        workspaceDir,
+        outputPath,
+      );
+      return {
+        kind: 'design' as const,
+        headline: `Design round: ${outputPath.replace(/^design\//, '').replace(/\.png$/, '')}`,
+        imageCardPath,
+        imageUrl: new URL(imageCardPath, targetRealm).href,
+      };
+    }),
+  );
+}
+
+/**
+ * Extract "real card" paths from an agent turn's tool-call log: instance
+ * JSON files written outside the tracker/validation/design folders. These
+ * become card-ready entries that embed the live card.
+ */
+export function cardPathsFromToolCalls(
+  toolCalls: { tool: string; args: Record<string, unknown>; result: unknown }[],
+  limit = 3,
+): string[] {
+  const EXCLUDED =
+    /^(Issues|Projects|Boards|Knowledge(?: |%20)Articles|Spec|Validations|Runs|RunLogEntries|design|design-history|\.factory-scratch)\//;
+  let paths: string[] = [];
+  for (let call of toolCalls) {
+    if (call.tool !== 'Write') continue;
+    let filePath = call.args?.file_path;
+    if (typeof filePath !== 'string') continue;
+    let normalized = filePath.replace(
+      /^.*boxel-factory-workspaces\/[^/]+\//,
+      '',
+    );
+    if (!normalized.endsWith('.json')) continue;
+    if (EXCLUDED.test(normalized)) continue;
+    if (!normalized.includes('/')) continue; // instances live in <Type>/<id>.json
+    let cardPath = normalized.replace(/\.json$/, '');
+    if (!paths.includes(cardPath)) {
+      paths.push(cardPath);
+    }
+  }
+  return paths.slice(0, limit);
+}
+
+// ---------------------------------------------------------------------------
+// The RunLog CardDef module, written verbatim into the target realm
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// The RunLog CardDef module, written verbatim into the target realm.
+// Design language: Boxel Workspace (card-grid v2) — stage/surface paper,
+// hairlines, mono micro-labels, Boxel-teal accent; ALL motion (scan line,
+// pulse, arrival wash) is gated on status=running.
+// ---------------------------------------------------------------------------
+
+const RUN_LOG_GTS = `import { registerDestructor } from '@ember/destroyable';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
+import { gte, lt } from '@cardstack/boxel-ui/helpers';
+import {
+  CardDef,
+  field,
+  contains,
+  linksTo,
+  Component,
+} from 'https://cardstack.com/base/card-api';
+import StringField from 'https://cardstack.com/base/string';
+import NumberField from 'https://cardstack.com/base/number';
+import DatetimeField from 'https://cardstack.com/base/datetime';
+import MarkdownField from 'https://cardstack.com/base/markdown';
+import FileDef from 'https://cardstack.com/base/file-api';
+import {
+  codeRef,
+  realmURL,
+  searchEntryWireQueryFromQuery,
+  type Query,
+  type SearchEntryWireQuery,
+} from '@cardstack/runtime-common';
+
+// @ts-expect-error import.meta is supported by the Boxel host
+const here: string = import.meta.url;
+
+function clock(value: Date | string | undefined): string {
+  if (!value) return '';
+  try {
+    return new Date(value).toLocaleTimeString('en-US', {
+      hour: '2-digit',
+      minute: '2-digit',
+      hour12: false,
+    });
+  } catch {
+    return '';
+  }
+}
+
+// Reveal-on-scroll feed window: fetch the last FEED_CAP entries once, reveal
+// FEED_STEP at a time as the reader scrolls back (the workspace.gts pattern).
+const FEED_STEP = 20;
+const FEED_CAP = 100;
+
+const KIND_GLYPHS: Record<string, string> = {
+  phase: '◆',
+  'issue-picked': '▸',
+  'issue-done': '■',
+  design: '✦',
+  validation: '✓',
+  'card-ready': '●',
+  'run-done': '◼',
+  status: '↻',
+  'status-change': '⇄',
+  iteration: '↻',
+  blocked: '▲',
+  comment: '❝',
+  progress: '▹',
+  decision: '⚑',
+  'agent-spawn': '⚙',
+  note: '·',
+  monitor: '◉',
+  telemetry: '≡',
+};
+
+class RunLogEntryEmbedded extends Component<typeof RunLogEntry> {
+  @tracked nowMs = Date.now();
+  #ticker: ReturnType<typeof setInterval>;
+
+  constructor(owner: any, args: any) {
+    super(owner, args);
+    this.#ticker = setInterval(() => {
+      this.nowMs = Date.now();
+    }, 30000);
+    registerDestructor(this, () => clearInterval(this.#ticker));
+  }
+
+  get timeLabel() {
+    return clock(this.args.model.postedAt);
+  }
+  get agoLabel() {
+    let at = this.args.model.postedAt;
+    if (!at) return '';
+    let mins = Math.floor((this.nowMs - new Date(at).getTime()) / 60000);
+    if (mins < 1) return 'just now';
+    if (mins < 60) return mins + 'm ago';
+    return Math.floor(mins / 60) + 'h ' + (mins % 60) + 'm ago';
+  }
+  get glyph() {
+    return KIND_GLYPHS[this.args.model.kind ?? ''] ?? '·';
+  }
+  get isShipMoment() {
+    return this.args.model.kind === 'card-ready';
+  }
+  get isCompactLink() {
+    let kind = this.args.model.kind ?? '';
+    return (
+      kind === 'validation' ||
+      kind === 'status' ||
+      kind === 'status-change' ||
+      kind === 'iteration'
+    );
+  }
+  <template>
+    <div class='entry' data-kind={{@model.kind}}>
+      <span class='t'>{{this.timeLabel}}
+        <span class='ago'>{{this.agoLabel}}</span></span>
+      <span class='chip'><span class='glyph'>{{this.glyph}}</span>
+        {{@model.kind}}
+        {{#if @model.who}}<span class='who'>{{@model.who}}</span>{{/if}}</span>
+      <span class='h'>{{@model.headline}}</span>
+      {{#if @model.body}}
+        <div class='b'><@fields.body /></div>
+      {{/if}}
+      {{#if @model.image}}
+        <div class='shot-frame'>
+          <@fields.image @format='embedded' />
+        </div>
+      {{else if @model.imageUrl}}
+        <div class='shot-frame'>
+          <img class='shot-img' src={{@model.imageUrl}} alt={{@model.headline}} />
+        </div>
+      {{/if}}
+      {{#if @model.card}}
+        {{#if this.isShipMoment}}
+          <div class='livecard'>
+            <div class='shipped'>&#9679; shipped &mdash; live card</div>
+            <div class='cardwrap'>
+              <@fields.card @format='embedded' />
+            </div>
+          </div>
+        {{else if this.isCompactLink}}
+          <div class='showme showme-inline'>
+            <span class='showme-label'>details</span>
+            <span class='atom-chip'><@fields.card @format='atom' /></span>
+          </div>
+        {{else}}
+          <div class='showme'>
+            <span class='showme-label'>show me</span>
+            <div class='cardwrap'>
+              <@fields.card @format='embedded' />
+            </div>
+          </div>
+        {{/if}}
+      {{/if}}
+      {{#if @model.issue}}
+        {{! portal to the underlying truth: click through to the Issue this
+          entry belongs to (and from there its project, spec, criteria) }}
+        <div class='entry-links'>
+          <span class='entry-link-label'>issue</span>
+          <span class='atom-chip'><@fields.issue @format='atom' /></span>
+        </div>
+      {{/if}}
+    </div>
+    <style scoped>
+      .entry {
+        display: grid;
+        grid-template-columns: 52px 102px minmax(0, 1fr);
+        gap: 0 14px;
+        padding: 13px 0;
+        border-bottom: 1px solid var(--rl-hairline, #eceef1);
+        align-items: baseline;
+        font-family: var(--rl-sans, var(--boxel-font-family, sans-serif));
+      }
+      .t {
+        font: 500 11px var(--rl-mono, monospace);
+        font-variant-numeric: tabular-nums;
+        color: var(--rl-ink-meta, #a2a2ab);
+      }
+      .ago {
+        display: block;
+        font: 400 8.5px var(--rl-mono, monospace);
+        letter-spacing: 0.02em;
+        color: var(--rl-ink-ghost, #c0c0c7);
+        margin-top: 2px;
+        white-space: nowrap;
+      }
+      .chip {
+        font: 600 8.5px var(--rl-mono, monospace);
+        letter-spacing: 0.1em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta, #a2a2ab);
+        white-space: nowrap;
+      }
+      .glyph {
+        font-size: 10px;
+        letter-spacing: 0;
+        margin-right: 1px;
+      }
+      .who {
+        display: block;
+        margin-top: 2px;
+        font: 500 8px var(--rl-mono, monospace);
+        letter-spacing: 0.08em;
+        color: var(--rl-ink-ghost, #c0c0c7);
+      }
+      .entry[data-kind='design'] .chip {
+        color: var(--rl-attention, #d97706);
+      }
+      .entry[data-kind='card-ready'] .chip,
+      .entry[data-kind='run-done'] .chip,
+      .entry[data-kind='status'] .chip,
+      .entry[data-kind='status-change'] .chip {
+        color: var(--rl-interactive, #0c9d7c);
+      }
+      .entry[data-kind='blocked'] .chip {
+        color: #ff5050;
+      }
+      .entry[data-kind='iteration'] .chip,
+      .entry[data-kind='comment'] .chip,
+      .entry[data-kind='monitor'] .chip,
+      .entry[data-kind='telemetry'] .chip {
+        color: var(--rl-ink-quiet, #5c5967);
+      }
+      /* Orchestrator meta-chatter reads smaller than build milestones. */
+      .entry[data-kind='monitor'] .h,
+      .entry[data-kind='telemetry'] .h {
+        font-size: 12.5px;
+        font-weight: 500;
+        color: var(--rl-ink-quiet, #5c5967);
+      }
+      .showme {
+        grid-column: 3;
+        margin-top: 10px;
+      }
+      .showme-label {
+        display: block;
+        font: 700 9px var(--rl-mono, monospace);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta, #a2a2ab);
+        margin-bottom: 6px;
+      }
+      .showme-inline {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+      }
+      .entry-links {
+        grid-column: 3;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin-top: 8px;
+      }
+      .entry-link-label {
+        font: 700 9px var(--rl-mono, monospace);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta, #a2a2ab);
+      }
+      .showme-inline .showme-label {
+        display: inline;
+        margin-bottom: 0;
+      }
+      .atom-chip :deep(.boxel-card-container) {
+        border-radius: 5px;
+        box-shadow: 0 0 0 1px var(--rl-border, #e2e8f0);
+        cursor: pointer;
+      }
+      .h {
+        font: 600 14px/1.35 var(--rl-sans, sans-serif);
+        color: var(--rl-ink, #272330);
+      }
+      .b {
+        grid-column: 3;
+        font: 400 12.5px/1.5 var(--rl-sans, sans-serif);
+        color: var(--rl-ink-quiet, #5c5967);
+        margin-top: 3px;
+      }
+      .shot-frame {
+        grid-column: 3;
+        margin-top: 10px;
+        max-width: 540px;
+        border: 1px solid var(--rl-border, #e2e8f0);
+        border-radius: 6px;
+        overflow: hidden;
+        background: var(--rl-surface, #fff);
+      }
+      .shot-frame :deep(.boxel-card-container) {
+        border-radius: 0;
+        box-shadow: none;
+      }
+      .shot-img {
+        width: 100%;
+        display: block;
+      }
+      .livecard {
+        grid-column: 3;
+        margin-top: 10px;
+        max-width: 540px;
+      }
+      .shipped {
+        font: 700 9px var(--rl-mono, monospace);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--rl-interactive, #0c9d7c);
+        margin-bottom: 6px;
+      }
+      .cardwrap :deep(.boxel-card-container) {
+        border-radius: 8px;
+        box-shadow: 0 2px 8px rgba(28, 28, 50, 0.05);
+      }
+    </style>
+  </template>
+}
+
+export class RunLogEntry extends CardDef {
+  static displayName = 'Run Log Entry';
+  // Each entry is its OWN card instance (not a containsMany element), so a
+  // new entry is one small file write — never a rewrite of a growing log.
+  // The RunLog feed is a live query over these, scoped by runId.
+  @field runId = contains(StringField);
+  // Monotonic per-run sequence — the query's stable sort key (postedAt can
+  // tie within a second under rapid appends).
+  @field seq = contains(NumberField);
+  @field kind = contains(StringField);
+  @field postedAt = contains(DatetimeField);
+  @field headline = contains(StringField);
+  @field body = contains(MarkdownField);
+  @field imageUrl = contains(StringField);
+  /** Who is speaking: orchestrator | executor | validator | an agent name. */
+  @field who = contains(StringField);
+  // File cards (PngDef etc.) descend from FileDef, NOT CardDef — a
+  // CardDef-typed link rejects them at field validation.
+  @field image = linksTo(() => FileDef);
+  @field card = linksTo(() => CardDef);
+  // The Issue this entry belongs to — the portal to the underlying truth
+  // (project, spec, acceptance criteria, built card).
+  @field issue = linksTo(() => CardDef);
+  @field cardTitle = contains(StringField, {
+    computeVia: function (this: RunLogEntry) {
+      return this.headline ?? 'Run log entry';
+    },
+  });
+
+  static embedded = RunLogEntryEmbedded;
+  // Fitted just reuses the embedded surface — entries are only ever rendered
+  // in the feed (embedded); fitted exists to satisfy the 3-format contract.
+  static fitted = RunLogEntryEmbedded;
+  static isolated = RunLogEntryEmbedded;
+}
+
+class RunLogIsolated extends Component<typeof RunLog> {
+  @tracked nowMs = Date.now();
+  #ticker: ReturnType<typeof setInterval>;
+  #destroyed = false;
+
+  // The feed renders a stable window of the fetched tail (newest-first,
+  // capped at FEED_CAP). Two independent edges bound it:
+  //
+  //  - newCount (head): how many just-arrived entries are BUFFERED, not
+  //    rendered. A live run prepends at index 0; rendering them would shove
+  //    the reader's content down. Instead they're held behind a subtle
+  //    "N new" pill and only revealed on click (or auto, if the reader is
+  //    already at the top watching live) — so passive updates never shift
+  //    what's on screen.
+  //  - feedShown (tail): reveal-on-scroll window (workspace.gts pattern);
+  //    grows by FEED_STEP as the bottom sentinel comes into view.
+  //
+  // Rendered rows are entries[newCount .. newCount + feedShown).
+  @tracked feedShown = FEED_STEP;
+  @tracked feedFetched = 0;
+  @tracked newCount = 0;
+  @tracked private atTop = true;
+  @tracked private anchorId: string | null = null;
+  private topSentinel: HTMLElement | null = null;
+
+  constructor(owner: any, args: any) {
+    super(owner, args);
+    this.#ticker = setInterval(() => {
+      this.nowMs = Date.now();
+    }, 1000);
+    registerDestructor(this, () => {
+      this.#destroyed = true;
+      clearInterval(this.#ticker);
+    });
+  }
+
+  // End index of the rendered window (exclusive).
+  get windowEnd(): number {
+    return this.newCount + this.feedShown;
+  }
+  // More rows are fetched below the window — show the tail sentinel.
+  get moreFeed(): boolean {
+    return this.feedFetched > this.windowEnd;
+  }
+  // The whole capped window is revealed — show the terminal note.
+  get feedAtCap(): boolean {
+    return this.feedFetched >= FEED_CAP && this.windowEnd >= this.feedFetched;
+  }
+
+  // Reveal the buffered head: acknowledge the newest entry and jump to the
+  // top. User-initiated, so the scroll-to-top is expected, not a jarring
+  // shift. Auto-reconcile (below) then recomputes newCount to 0.
+  showNew = () => {
+    this.atTop = true;
+    this.newCount = 0;
+    this.topSentinel?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+  };
+
+  // Reconcile the head buffer against the live entry stream. When the reader
+  // is at the top, stay caught up — acknowledge the newest and buffer
+  // nothing, so a live watcher sees updates immediately. When scrolled away,
+  // hold every entry newer than the anchor (the newest they've seen) so the
+  // visible rows never move; newCount drives the pill.
+  //
+  // Modifier bodies run inside the render transaction, and this state feeds
+  // values the template consumed earlier in the same pass (newCount,
+  // windowEnd) — a synchronous tracked write here trips Glimmer's
+  // backtracking assertion and error-tiles the prerendered card. So the
+  // reconcile is deferred to a microtask (outside the render), and every
+  // write is change-guarded so a re-run with identical values settles
+  // instead of revalidating forever.
+  captureFeed = modifier(
+    (_el: HTMLElement, [entries]: [{ id: string }[]]) => {
+      void Promise.resolve().then(() => {
+        if (this.#destroyed) {
+          return;
+        }
+        if (this.feedFetched !== entries.length) {
+          this.feedFetched = entries.length;
+        }
+        if (entries.length === 0) {
+          if (this.newCount !== 0) {
+            this.newCount = 0;
+          }
+          return;
+        }
+        let newestId = entries[0].id;
+        if (this.anchorId === null || this.atTop) {
+          if (this.anchorId !== newestId) {
+            this.anchorId = newestId;
+          }
+          if (this.newCount !== 0) {
+            this.newCount = 0;
+          }
+          return;
+        }
+        let idx = entries.findIndex((e) => e.id === this.anchorId);
+        // Anchor still present → entries before it are new. Anchor fell off
+        // the capped window → can't hold what we can't show; re-anchor to
+        // newest.
+        if (idx < 0) {
+          this.anchorId = newestId;
+          if (this.newCount !== 0) {
+            this.newCount = 0;
+          }
+        } else if (this.newCount !== idx) {
+          this.newCount = idx;
+        }
+      });
+    },
+  );
+
+  // Track whether the feed is scrolled to its top, to decide auto-reveal vs
+  // buffer. A top sentinel just below the masthead drives it.
+  watchFeedTop = modifier((element: HTMLElement) => {
+    this.topSentinel = element;
+    let root = element.closest('.scroll-container');
+    let observer = new IntersectionObserver(
+      ([entry]) => {
+        this.atTop = entry.isIntersecting;
+      },
+      { root, rootMargin: '0px' },
+    );
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+      this.topSentinel = null;
+    };
+  });
+
+  // Reveal the next FEED_STEP when the tail sentinel scrolls near the feed
+  // bottom. Re-arm after each reveal: observe() delivers a fresh async
+  // notification, so a still-visible sentinel keeps paging until caught up.
+  watchFeedEnd = modifier((element: HTMLElement) => {
+    let root = element.closest('.scroll-container');
+    let observer = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          this.feedShown = Math.min(
+            this.feedShown + FEED_STEP,
+            this.feedFetched - this.newCount,
+          );
+          observer.unobserve(element);
+          observer.observe(element);
+        }
+      },
+      { root, rootMargin: '160px 0px' },
+    );
+    observer.observe(element);
+    return () => observer.disconnect();
+  });
+
+  get running() {
+    return this.args.model.status === 'running';
+  }
+  get statusWord() {
+    return this.running ? 'LIVE' : (this.args.model.status ?? '');
+  }
+  get elapsedLabel() {
+    let started = this.args.model.startedAt;
+    if (!started) return '';
+    let end = this.running
+      ? this.nowMs
+      : new Date(this.args.model.finishedAt ?? started).getTime();
+    let secs = Math.max(0, Math.floor((end - new Date(started).getTime()) / 1000));
+    let h = String(Math.floor(secs / 3600)).padStart(2, '0');
+    let m = String(Math.floor((secs % 3600) / 60)).padStart(2, '0');
+    let sec = String(secs % 60).padStart(2, '0');
+    return h + ':' + m + ':' + sec;
+  }
+  get warmingUp() {
+    // The "setup phase" hint shows only during bootstrap — no counters
+    // needed (the rail facets below are query-backed).
+    return (
+      this.running &&
+      (!this.args.model.nowWorkingOn ||
+        this.args.model.nowWorkingOn === 'Bootstrapping')
+    );
+  }
+  // ---- live feed query: every RunLogEntry for THIS run, newest first ----
+  get entryRef() {
+    return codeRef(here, './run-log', 'RunLogEntry');
+  }
+  get realms(): string[] {
+    let url = this.args.model?.[realmURL];
+    return url ? [url.href] : [];
+  }
+  // ---- rail facets: query-backed counts, one lightweight count-query per
+  // facet (page:size:1 → results.meta.page.total), so the numbers reflect the
+  // actual RunLogEntry cards instead of a maintained counter that can drift. --
+  countWireQuery(kind: string): SearchEntryWireQuery {
+    let ref = this.entryRef;
+    let q = searchEntryWireQueryFromQuery({
+      filter: {
+        on: ref,
+        eq: { runId: this.args.model.runId ?? '', kind },
+      },
+      page: { size: 1 },
+    });
+    return { ...q, realms: this.realms };
+  }
+  get cardsReadyWireQuery() {
+    return this.countWireQuery('card-ready');
+  }
+  get designRoundsWireQuery() {
+    return this.countWireQuery('design');
+  }
+  get validationsWireQuery() {
+    return this.countWireQuery('validation');
+  }
+  get issuesDoneWireQuery() {
+    return this.countWireQuery('issue-done');
+  }
+  get facets() {
+    return [
+      { label: 'Cards ready', accent: true, query: this.cardsReadyWireQuery },
+      { label: 'Design rounds', accent: false, query: this.designRoundsWireQuery },
+      { label: 'Validations', accent: false, query: this.validationsWireQuery },
+      { label: 'Issues done', accent: false, query: this.issuesDoneWireQuery },
+    ];
+  }
+  get entriesQuery(): Query {
+    let ref = this.entryRef;
+    // on: ref scopes the eq predicate to RunLogEntry AND filters by runId;
+    // custom-field sort (seq) also requires on: ref. Newest-first and BOUNDED
+    // (cardinal rule 15): one fetch of the recent tail, capped at FEED_CAP;
+    // the template reveals it FEED_STEP at a time on scroll (no re-query).
+    // Rendered in query order (no column-reverse), newest on top.
+    return {
+      filter: { on: ref, eq: { runId: this.args.model.runId ?? '' } },
+      sort: [{ by: 'seq', on: ref, direction: 'desc' }],
+      page: { size: FEED_CAP },
+    };
+  }
+  get entriesWireQuery(): SearchEntryWireQuery {
+    let q = searchEntryWireQueryFromQuery(this.entriesQuery);
+    return {
+      ...q,
+      realms: this.realms,
+      filter: {
+        ...q.filter,
+        eq: { ...q.filter?.eq, htmlQuery: { eq: { format: 'embedded' } } },
+      },
+    };
+  }
+  <template>
+    <article class='runlog' data-status={{@model.status}}>
+      {{#if this.running}}<div class='scanline'></div>{{/if}}
+      <header class='masthead'>
+        <span class='signage'>Factory &middot; Run Log</span>
+        <h1 class='run-title'>{{@model.runTitle}}</h1>
+        <div class='live-block'>
+          {{#if this.running}}<span class='live-dot'></span>{{/if}}
+          <span class='live-word'>{{this.statusWord}}</span>
+          <span class='started'>{{this.elapsedLabel}}</span>
+        </div>
+      </header>
+      <div class='nowband'>
+        <span class='k'>Now</span>
+        {{#if this.running}}
+          <span class='throbber'><i></i><i></i><i></i></span>
+        {{/if}}
+        <span class='now-item'>{{@model.nowWorkingOn}}</span>
+        {{#if this.warmingUp}}
+          <span class='now-hint'>setup phase — first design round lands in a few minutes</span>
+        {{/if}}
+        <span class='next-wrap'>
+          <span class='k'>Next</span>
+          <span class='next-item'>{{if @model.upNext @model.upNext '—'}}</span>
+        </span>
+      </div>
+      <div class='body-grid'>
+        <aside class='rail'>
+          {{! Each facet is a query-backed count tile: a page:size:1 count
+            query over RunLogEntry (this run, this kind) whose
+            results.meta.page.total is the live, drift-free number — no
+            maintained counter. }}
+          {{#each this.facets as |facet|}}
+            <div class='stat'>
+              <div class='n {{if facet.accent "accent"}}'>
+                {{#if @context.searchResultsComponent}}
+                  <@context.searchResultsComponent
+                    @query={{facet.query}}
+                    @mode='none'
+                    as |results|
+                  >
+                    {{if results.isLoading '·' results.meta.page.total}}
+                  </@context.searchResultsComponent>
+                {{/if}}
+              </div>
+              <div class='l'>{{facet.label}}</div>
+            </div>
+          {{/each}}
+        </aside>
+        <div class='feed'>
+          {{! Top sentinel: drives the at-top detection that decides whether
+            live arrivals auto-reveal or buffer behind the pill. }}
+          <div class='feed-top' {{this.watchFeedTop}}></div>
+          {{! Buffered live arrivals — subtle, non-shifting, click to reveal.
+            Only shows when the reader has scrolled away from the head. }}
+          {{#if this.newCount}}
+            <button
+              class='newpill'
+              type='button'
+              {{on 'click' this.showNew}}
+            >
+              <span class='newpill-arrow'>&uarr;</span>
+              {{this.newCount}}
+              new
+            </button>
+          {{/if}}
+          {{! newest-first query order, rendered top-to-bottom; the intro
+            explainer follows the entries so it settles at the bottom }}
+          {{#if @context.searchResultsComponent}}
+            <@context.searchResultsComponent
+              @query={{this.entriesWireQuery}}
+              @mode='hover'
+              as |results|
+            >
+              {{#if results.isLoading}}
+                <div class='feed-loading'>Loading the live feed…</div>
+              {{/if}}
+              {{! Render only the stable window [newCount, windowEnd): head
+                entries below newCount are buffered (see the pill), tail
+                beyond windowEnd waits for the scroll sentinel. }}
+              {{#each results.entries key='id' as |entry index|}}
+                {{#if (lt index this.windowEnd)}}
+                  {{#if (gte index this.newCount)}}
+                    <entry.component />
+                  {{/if}}
+                {{/if}}
+              {{else}}
+                {{#unless results.isLoading}}
+                  <div class='feed-empty'>No entries yet — the first
+                    milestone lands here shortly.</div>
+                {{/unless}}
+              {{/each}}
+              {{! Reconcile the head buffer + fetched count from the live
+                entry stream (modifiers run render-safe). }}
+              <div
+                class='meta-sink'
+                {{this.captureFeed results.entries}}
+              ></div>
+            </@context.searchResultsComponent>
+            {{#if this.moreFeed}}
+              {{! reveal-on-scroll: the sentinel reveals the next batch }}
+              <div class='feed-tail' {{this.watchFeedEnd}}>
+                <span class='feed-tail-label'>Showing
+                  {{this.feedShown}}
+                  of
+                  {{this.feedFetched}}</span>
+              </div>
+            {{else if this.feedAtCap}}
+              <p class='feed-end-note'>Showing the last {{this.feedFetched}}
+                entries.</p>
+            {{/if}}
+          {{/if}}
+          {{#if this.running}}
+            <div class='intro'>
+              <span class='intro-signage'>How this works</span>
+              <p class='intro-copy'>
+                The factory is building this realm live. It reads the brief,
+                plans the card family, mocks each card in HTML first,
+                critiques and revises the design, then writes the real code
+                — every milestone lands here the moment it happens, newest
+                at the top.
+              </p>
+              <div class='legend'>
+                <span class='lg'><i class='dot d-design'></i> design round</span>
+                <span class='lg'><i class='dot d-val'></i> validation</span>
+                <span class='lg'><i class='dot d-ready'></i> card ready</span>
+                <span class='lg'><i class='dot d-issue'></i> issue progress</span>
+              </div>
+            </div>
+          {{/if}}
+        </div>
+      </div>
+    </article>
+    <style scoped>
+      .runlog {
+        --rl-ink: #272330;
+        --rl-ink-quiet: #5c5967;
+        --rl-ink-meta: #a2a2ab;
+        --rl-ink-ghost: #c0c0c7;
+        --rl-stage: var(--background, #f7f8fa);
+        --rl-surface: #ffffff;
+        --rl-track: #eef0f4;
+        --rl-border: #e2e8f0;
+        --rl-hairline: #eceef1;
+        --rl-interactive: var(--primary, #0c9d7c);
+        --rl-live: #00c495;
+        --rl-accent: var(--boxel-teal, #00ffba);
+        --rl-attention: #d97706;
+        --rl-mono: var(--boxel-monospace-font-family, 'IBM Plex Mono', monospace);
+        --rl-sans: var(--boxel-font-family, 'IBM Plex Sans', sans-serif);
+        position: relative;
+        container-type: inline-size;
+        container-name: runlog;
+        min-height: 100%;
+        background: var(--rl-stage);
+        color: var(--rl-ink);
+        font-family: var(--rl-sans);
+      }
+      .scanline {
+        position: absolute;
+        top: 0;
+        left: 0;
+        right: 0;
+        height: 2px;
+        z-index: 2;
+        background: linear-gradient(
+          90deg,
+          transparent,
+          var(--rl-accent),
+          var(--rl-live),
+          transparent
+        );
+        background-size: 200% 100%;
+        animation: scan 2.4s linear infinite;
+      }
+      @keyframes scan {
+        from { background-position: 200% 0; }
+        to { background-position: -200% 0; }
+      }
+      @keyframes softpulse {
+        0%, 100% { opacity: 1; }
+        50% { opacity: 0.35; }
+      }
+      .masthead {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        padding: 16px 22px 14px;
+        background: var(--rl-surface);
+        border-bottom: 1px solid var(--rl-hairline);
+      }
+      .signage {
+        padding: 3px 8px;
+        border: 1px solid var(--rl-border);
+        border-radius: 5px;
+        font: 600 9.5px var(--rl-mono);
+        letter-spacing: 0.11em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+        white-space: nowrap;
+      }
+      .run-title {
+        margin: 0;
+        font: 650 20px/1.2 var(--rl-sans);
+        letter-spacing: -0.01em;
+      }
+      .live-block {
+        margin-left: auto;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+      }
+      .live-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: var(--rl-live);
+        animation: softpulse 2s ease-in-out infinite;
+      }
+      .live-word {
+        font: 700 10.5px var(--rl-mono);
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+        color: var(--rl-interactive);
+      }
+      .runlog[data-status='failed'] .live-word { color: #ff5050; }
+      .started {
+        font: 500 11px var(--rl-mono);
+        font-variant-numeric: tabular-nums;
+        color: var(--rl-ink-meta);
+      }
+      .nowband {
+        display: flex;
+        align-items: baseline;
+        gap: 14px;
+        padding: 14px 22px;
+        background: var(--rl-surface);
+        border-bottom: 1px solid var(--rl-hairline);
+      }
+      .k {
+        font: 600 9.5px var(--rl-mono);
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+        flex: none;
+      }
+      .throbber {
+        display: inline-flex;
+        align-items: flex-end;
+        gap: 2.5px;
+        height: 16px;
+        align-self: center;
+        flex: none;
+      }
+      .throbber i {
+        width: 3px;
+        border-radius: 1.5px;
+        background: var(--rl-live);
+        animation: eq 1.1s ease-in-out infinite;
+      }
+      .throbber i:nth-child(1) { height: 8px; }
+      .throbber i:nth-child(2) { height: 14px; animation-delay: 0.18s; }
+      .throbber i:nth-child(3) { height: 10px; animation-delay: 0.36s; }
+      @keyframes eq {
+        0%, 100% { transform: scaleY(0.55); }
+        50% { transform: scaleY(1); }
+      }
+      .now-item {
+        font: 400 24px/1.15 var(--rl-sans);
+        letter-spacing: -0.015em;
+        min-width: 0;
+      }
+      .next-wrap {
+        margin-left: auto;
+        display: flex;
+        align-items: baseline;
+        gap: 8px;
+      }
+      .next-item {
+        font: 400 13px var(--rl-sans);
+        color: var(--rl-ink-quiet);
+      }
+      .body-grid {
+        display: grid;
+        grid-template-columns: 188px minmax(0, 1fr);
+      }
+      .rail {
+        padding: 20px 0 26px 22px;
+        border-right: 1px solid var(--rl-hairline);
+        display: flex;
+        flex-direction: column;
+        gap: 20px;
+      }
+      .stat .n {
+        font: 300 40px/1 var(--rl-sans);
+        letter-spacing: -0.02em;
+        font-variant-numeric: tabular-nums;
+      }
+      .stat .n.accent { color: var(--rl-interactive); }
+      .stat .l {
+        font: 600 9px var(--rl-mono);
+        letter-spacing: 0.11em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+        margin-top: 5px;
+      }
+      .feed {
+        display: flex;
+        flex-direction: column;
+        padding: 6px 22px 22px 24px;
+      }
+      /* Each entry renders through the host search-results component, which
+         wraps it in embedded CardContainer chrome — a boundaried box with a
+         fixed ~78px height and overflow:hidden. That clips any entry tall
+         enough to have a body and pads short ones with dead space. Own the
+         container: let each entry size to its content, and drop the per-entry
+         card frame so the feed reads as flat rows (the .entry template draws
+         its own dividers), not a stack of little cards. */
+      .feed :deep(.boxel-card-container.embedded-format) {
+        height: auto;
+        min-height: 0;
+        max-height: none;
+        overflow: visible;
+        border: none;
+        border-radius: 0;
+        box-shadow: none;
+        background: transparent;
+      }
+      /* Zero-DOM sink: only exists to run the captureFeed modifier. */
+      .meta-sink {
+        display: none;
+      }
+      /* Zero-height marker at the head; drives at-top detection. */
+      .feed-top {
+        height: 0;
+        margin: 0;
+        pointer-events: none;
+      }
+      /* Buffered-arrivals pill. Sticky so it floats at the top of the
+         viewport while the reader is scrolled away — new items are held out
+         of the flow (never rendered until revealed), so nothing shifts; this
+         is the only cue. Subtle by default, accent on hover. */
+      .newpill {
+        position: sticky;
+        top: 8px;
+        z-index: 6;
+        align-self: center;
+        margin: 2px 0 8px;
+        padding: 5px 13px;
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        border: 1px solid var(--rl-border);
+        border-radius: 999px;
+        background: color-mix(in srgb, var(--rl-surface) 88%, transparent);
+        backdrop-filter: blur(6px);
+        box-shadow: 0 2px 10px rgba(0, 0, 0, 0.08);
+        color: var(--rl-ink-quiet);
+        font: 600 10.5px var(--rl-mono);
+        letter-spacing: 0.07em;
+        text-transform: uppercase;
+        cursor: pointer;
+        opacity: 0.82;
+        transition: opacity 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+      }
+      .newpill:hover {
+        opacity: 1;
+        color: var(--rl-accent);
+        border-color: var(--rl-accent);
+      }
+      .newpill-arrow {
+        font-size: 12px;
+        line-height: 1;
+      }
+      /* Tail sentinel — the IntersectionObserver target that pages back. */
+      .feed-tail {
+        display: flex;
+        justify-content: center;
+        padding: 14px 0 4px;
+      }
+      .feed-tail-label {
+        font: 500 10px var(--rl-mono);
+        letter-spacing: 0.09em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+        opacity: 0.7;
+      }
+      .feed-end-note {
+        margin: 14px 0 2px;
+        text-align: center;
+        font: 500 10px var(--rl-mono);
+        letter-spacing: 0.09em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+        opacity: 0.7;
+      }
+      .intro {
+        margin-top: 16px;
+        padding: 14px 16px;
+        border: 1px dashed var(--rl-border);
+        border-radius: 8px;
+        background: var(--rl-surface);
+      }
+      .intro-signage {
+        font: 600 9px var(--rl-mono);
+        letter-spacing: 0.11em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+      }
+      .intro-copy {
+        margin: 6px 0 10px;
+        font: 400 12.5px/1.55 var(--rl-sans);
+        color: var(--rl-ink-quiet);
+        max-width: 60ch;
+      }
+      .legend {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 6px 16px;
+      }
+      .lg {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        font: 500 9.5px var(--rl-mono);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--rl-ink-meta);
+      }
+      .dot {
+        width: 7px;
+        height: 7px;
+        border-radius: 50%;
+        display: inline-block;
+      }
+      .d-design { background: var(--rl-attention); }
+      .d-val { background: var(--rl-live); }
+      .d-ready { background: var(--rl-interactive); }
+      .d-issue { background: var(--rl-ink-ghost); }
+      .now-hint {
+        align-self: center;
+        font: 400 12px var(--rl-sans);
+        color: var(--rl-ink-meta);
+      }
+      .feed > :first-child {
+        border-bottom: 0;
+      }
+      /* newest entry gets a one-shot teal arrival wash while live */
+      .runlog[data-status='running'] .feed > :last-child {
+        animation: arrive 3s ease-out 1;
+      }
+      @keyframes arrive {
+        0% { background: rgba(0, 255, 186, 0.14); }
+        100% { background: transparent; }
+      }
+      @container runlog (max-width: 700px) {
+        .body-grid { grid-template-columns: 1fr; }
+        .rail {
+          flex-direction: row;
+          gap: 26px;
+          padding: 16px 22px;
+          border-right: 0;
+          border-bottom: 1px solid var(--rl-hairline);
+        }
+        .stat .n { font-size: 26px; }
+        .now-item { font-size: 18px; }
+        .next-wrap { display: none; }
+      }
+    </style>
+  </template>
+}
+
+export class RunLog extends CardDef {
+  static displayName = 'Run Log';
+  static prefersWideFormat = true;
+  @field runTitle = contains(StringField);
+  @field status = contains(StringField);
+  @field nowWorkingOn = contains(StringField);
+  @field upNext = contains(StringField);
+  @field startedAt = contains(DatetimeField);
+  @field finishedAt = contains(DatetimeField);
+  // Scopes the live feed query to THIS run's entries.
+  @field runId = contains(StringField);
+  // Lightweight milestone counters (feed entries are separate cards now;
+  // the writer bumps these instead of scanning a containsMany array).
+  @field entryCount = contains(NumberField);
+  @field cardsReadyCount = contains(NumberField);
+  @field designRoundsCount = contains(NumberField);
+  @field validationsGreenCount = contains(NumberField);
+  @field issuesDoneCount = contains(NumberField);
+  @field cardTitle = contains(StringField, {
+    computeVia: function (this: RunLog) {
+      return this.runTitle ? 'Run log — ' + this.runTitle : 'Run log';
+    },
+  });
+
+  static isolated = RunLogIsolated;
+
+  static embedded = class Embedded extends Component<typeof this> {
+    get running() {
+      return this.args.model.status === 'running';
+    }
+    get shipped() {
+      return this.args.model.cardsReadyCount ?? 0;
+    }
+    get rounds() {
+      return this.args.model.designRoundsCount ?? 0;
+    }
+    <template>
+      <div class='row' data-status={{@model.status}}>
+        {{#if this.running}}<span class='dot'></span>{{/if}}
+        <div class='mid'>
+          <div class='nm'>{{@model.runTitle}}</div>
+          <div class='now'>Now: {{@model.nowWorkingOn}}</div>
+        </div>
+        <span class='counts'><em>{{this.shipped}}</em> shipped &middot; {{this.rounds}} rounds</span>
+      </div>
+      <style scoped>
+        .row {
+          display: flex;
+          align-items: center;
+          gap: 11px;
+          padding: 11px 14px;
+          font-family: var(--boxel-font-family, 'IBM Plex Sans', sans-serif);
+        }
+        .dot {
+          width: 8px;
+          height: 8px;
+          border-radius: 50%;
+          background: #00c495;
+          flex: none;
+          animation: softpulse 2s ease-in-out infinite;
+        }
+        @keyframes softpulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.35; }
+        }
+        .mid { flex: 1; min-width: 0; }
+        .nm { font: 600 13.5px/1.3 var(--boxel-font-family, sans-serif); }
+        .now {
+          font: 400 11.5px/1.4 var(--boxel-font-family, sans-serif);
+          color: #5c5967;
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .counts {
+          margin-left: auto;
+          font: 500 10.5px var(--boxel-monospace-font-family, monospace);
+          font-variant-numeric: tabular-nums;
+          color: #a2a2ab;
+          white-space: nowrap;
+        }
+        .counts em { font-style: normal; color: #0c9d7c; }
+      </style>
+    </template>
+  };
+
+  static fitted = class Fitted extends Component<typeof this> {
+    get running() {
+      return this.args.model.status === 'running';
+    }
+    get shipped() {
+      return this.args.model.cardsReadyCount ?? 0;
+    }
+    <template>
+      <div class='fit' data-status={{@model.status}}>
+        <span class='dot'></span>
+        <span class='nm'>{{@model.runTitle}}</span>
+        <span class='now'>{{@model.nowWorkingOn}}</span>
+        <span class='count'>{{this.shipped}}</span>
+      </div>
+      <style scoped>
+        .fit {
+          display: flex;
+          align-items: center;
+          gap: 8px;
+          padding: 8px 10px;
+          height: 100%;
+          min-height: 0;
+          overflow: hidden;
+          font-family: var(--boxel-font-family, 'IBM Plex Sans', sans-serif);
+        }
+        .dot {
+          width: 7px;
+          height: 7px;
+          border-radius: 50%;
+          background: #00c495;
+          flex: none;
+        }
+        .fit[data-status='running'] .dot {
+          animation: softpulse 2s ease-in-out infinite;
+        }
+        .fit[data-status='completed'] .dot { background: #0c9d7c; }
+        .fit[data-status='failed'] .dot { background: #ff5050; }
+        @keyframes softpulse {
+          0%, 100% { opacity: 1; }
+          50% { opacity: 0.35; }
+        }
+        .nm {
+          font: 600 12px/1.3 var(--boxel-font-family, sans-serif);
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+        .now, .count { display: none; }
+        @container fitted-card (min-width: 200px) {
+          .now {
+            display: block;
+            flex: 1;
+            min-width: 0;
+            font: 400 10.5px/1.3 var(--boxel-font-family, sans-serif);
+            color: #5c5967;
+            white-space: nowrap;
+            overflow: hidden;
+            text-overflow: ellipsis;
+          }
+          .count {
+            display: block;
+            font: 500 10px var(--boxel-monospace-font-family, monospace);
+            font-variant-numeric: tabular-nums;
+            color: #0c9d7c;
+          }
+        }
+        @container fitted-card (min-height: 170px) {
+          .fit {
+            flex-direction: column;
+            align-items: flex-start;
+            justify-content: space-between;
+            padding: 12px;
+          }
+          .nm { font-size: 13.5px; white-space: normal; }
+          .now { flex: none; white-space: normal; }
+        }
+      </style>
+    </template>
+  };
+}
+`;
diff --git a/packages/software-factory/src/run-monitor.ts b/packages/software-factory/src/run-monitor.ts
new file mode 100644
index 00000000000..abc08199eb7
--- /dev/null
+++ b/packages/software-factory/src/run-monitor.ts
@@ -0,0 +1,316 @@
+/**
+ * RunMonitor — the orchestrator's own voice on the run log.
+ *
+ * V2's live blog gave the EXECUTOR a voice (post_update, streamed writes,
+ * failed checks). The operator's side — "is anything happening?", "what did
+ * that turn cost?", "why is the log silent?" — was hand-typed during the
+ * wardrobe run. This class owns it:
+ *
+ * - **Stall narration**: a timer reset by every stream event. When a turn
+ *   goes quiet past the threshold, post what we know (the model is
+ *   generating; last visible activity and when). Long model turns are the
+ *   single biggest run-log UX failure — 88% of wall clock is generation,
+ *   and an unnarrated 14-minute gap reads as a hang.
+ * - **Turn telemetry**: per-turn entry with model/effort budget, duration,
+ *   tool-call count, files touched, and token usage when the backend
+ *   reports it. The data was previously discarded.
+ * - **Scheduler + watchdog notes**: queue state and sync failures routed
+ *   onto the run log instead of terminal-only logging.
+ *
+ * All entries post with `who: 'orchestrator'` via the run-log writer's
+ * streaming (raw-write) path, so the monitor never triggers a workspace
+ * sync and never blocks the loop. Everything is level-gated
+ * (quiet | normal | verbose) and rate-limited per event class.
+ */
+
+import type { RunLogWriter, RunLogEntryInput } from './run-log.ts';
+import { logger } from './logger.ts';
+
+const log = logger('run-monitor');
+
+export type MonitorLevel = 'quiet' | 'normal' | 'verbose';
+
+export interface RunMonitorOptions {
+  runLog: RunLogWriter;
+  /** quiet = stalls + failures only; normal (default) = + turn telemetry
+   *  and scheduler notes; verbose = + turn starts, heals, sync successes. */
+  level?: MonitorLevel;
+  /** Silence (no stream events) before the first stall post. Default 90s. */
+  stallAfterMs?: number;
+  /** Minimum gap between repeated stall posts while still silent. Default 4m. */
+  stallRepeatMs?: number;
+  /** Stall-check timer resolution. Default 15s. */
+  checkIntervalMs?: number;
+}
+
+export interface TurnInfo {
+  issueTitle: string;
+  /** prime | bootstrap | design | build | fix | implement | acceptance */
+  turnType: string;
+  iteration?: number;
+  maxIterations?: number;
+  /** Budget the orchestrator chose; undefined = session default. */
+  model?: string;
+  effort?: string;
+}
+
+export interface TurnOutcome {
+  status: string;
+  durationMs: number;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    costUsd?: number;
+  };
+}
+
+/** Minimum gap between posts of the same watchdog event class. */
+const WATCHDOG_MIN_INTERVAL_MS = 60_000;
+
+export class RunMonitor {
+  private runLog: RunLogWriter;
+  private level: MonitorLevel;
+  private stallAfterMs: number;
+  private stallRepeatMs: number;
+  private checkIntervalMs: number;
+
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private turn: (TurnInfo & { startedAt: number }) | undefined;
+  private lastActivityAt = Date.now();
+  private lastActivityDesc = '';
+  private lastStallPostAt = 0;
+  private lastWatchdogPostAt = new Map<string, number>();
+  // Per-turn accumulators, reset by beginTurn().
+  private turnToolEvents = 0;
+  private turnFilesTouched = new Set<string>();
+
+  constructor(opts: RunMonitorOptions) {
+    this.runLog = opts.runLog;
+    this.level = opts.level ?? 'normal';
+    this.stallAfterMs = opts.stallAfterMs ?? 90_000;
+    this.stallRepeatMs = opts.stallRepeatMs ?? 240_000;
+    this.checkIntervalMs = opts.checkIntervalMs ?? 15_000;
+  }
+
+  start(): void {
+    if (this.timer || this.level === 'quiet') {
+      // quiet still gets stall posts — they're the whole point — so only
+      // skip the timer when one is already running.
+      if (this.timer) return;
+    }
+    this.timer = setInterval(() => this.checkStall(), this.checkIntervalMs);
+    // Never hold the process open for the monitor.
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  /**
+   * Every stream event (tool call, assistant message) lands here. Cheap:
+   * updates the stall clock and per-turn stats, never posts.
+   */
+  noteActivity(desc: string): void {
+    this.lastActivityAt = Date.now();
+    if (desc) this.lastActivityDesc = desc;
+  }
+
+  /**
+   * Activity variant for tool-call stream entries — also accumulates the
+   * per-turn stats (tool count, files touched) used by turn telemetry.
+   */
+  noteToolEvent(entry: { tool: string; args: Record<string, unknown> }): void {
+    this.turnToolEvents++;
+    let tool = entry.tool.replace(/^mcp__[^_]+__/, '');
+    if (tool === 'Write' || tool === 'Edit') {
+      let filePath = String(entry.args.file_path ?? entry.args.path ?? '');
+      if (filePath) {
+        this.turnFilesTouched.add(filePath);
+      }
+    }
+    this.noteActivity(describeToolEvent(tool, entry.args));
+  }
+
+  beginTurn(info: TurnInfo): void {
+    this.turn = { ...info, startedAt: Date.now() };
+    this.turnToolEvents = 0;
+    this.turnFilesTouched = new Set();
+    this.lastActivityAt = Date.now();
+    this.lastActivityDesc = 'turn started';
+    this.lastStallPostAt = 0;
+    if (this.level === 'verbose') {
+      this.post({
+        kind: 'monitor',
+        headline: `Turn starting: ${turnLabel(info)}`,
+        body: budgetLabel(info),
+      });
+    }
+  }
+
+  endTurn(outcome: TurnOutcome): void {
+    let info = this.turn;
+    this.turn = undefined;
+    if (!info || this.level === 'quiet') return;
+
+    let parts: string[] = [turnLabel(info), budgetLabel(info)];
+    if (this.turnFilesTouched.size > 0) {
+      parts.push(
+        `${this.turnFilesTouched.size} file${this.turnFilesTouched.size === 1 ? '' : 's'} touched`,
+      );
+    }
+    let usage = outcome.usage;
+    if (usage && (usage.inputTokens || usage.outputTokens)) {
+      let tokens = `tokens ${fmtCount(usage.inputTokens)} in / ${fmtCount(usage.outputTokens)} out`;
+      if (usage.cacheReadTokens) {
+        tokens += ` (${fmtCount(usage.cacheReadTokens)} cached)`;
+      }
+      parts.push(tokens);
+    }
+    if (usage?.costUsd != null) {
+      parts.push(`$${usage.costUsd.toFixed(2)}`);
+    }
+    this.post({
+      kind: 'telemetry',
+      headline: `Turn ${outcome.status === 'blocked' ? 'blocked' : 'finished'} in ${fmtDuration(outcome.durationMs)} — ${this.turnToolEvents} tool event${this.turnToolEvents === 1 ? '' : 's'}`,
+      body: parts.join(' · '),
+    });
+  }
+
+  /** Scheduler state — queue depth, pickup rationale. Posts at normal+. */
+  noteScheduler(headline: string, body?: string): void {
+    if (this.level === 'quiet') return;
+    this.post({ kind: 'monitor', headline, body });
+  }
+
+  /**
+   * Watchdog events — sync failures, heals, realm health. Failure classes
+   * post at normal+; success/heal classes at verbose. Rate-limited to one
+   * post per class per minute so a retry storm doesn't flood the log.
+   */
+  noteWatchdog(
+    eventClass: string,
+    headline: string,
+    opts?: { body?: string; failure?: boolean },
+  ): void {
+    let failure = opts?.failure === true;
+    if (this.level === 'quiet' && !failure) return;
+    if (this.level === 'normal' && !failure) return;
+    let now = Date.now();
+    let last = this.lastWatchdogPostAt.get(eventClass) ?? 0;
+    if (now - last < WATCHDOG_MIN_INTERVAL_MS) return;
+    this.lastWatchdogPostAt.set(eventClass, now);
+    this.post({
+      kind: failure ? 'blocked' : 'monitor',
+      headline,
+      body: opts?.body,
+    });
+  }
+
+  private checkStall(): void {
+    if (!this.turn) return;
+    let now = Date.now();
+    let silentMs = now - this.lastActivityAt;
+    if (silentMs < this.stallAfterMs) return;
+    // First post when the threshold is crossed; repeats at stallRepeatMs
+    // while the silence continues.
+    if (
+      this.lastStallPostAt > this.lastActivityAt &&
+      now - this.lastStallPostAt < this.stallRepeatMs
+    ) {
+      return;
+    }
+    this.lastStallPostAt = now;
+    let turnElapsed = fmtDuration(now - this.turn.startedAt);
+    this.post({
+      kind: 'monitor',
+      headline: `Still working — ${fmtDuration(silentMs)} since the last visible step`,
+      body: [
+        `The model is generating (${turnLabel(this.turn)}, ${turnElapsed} into the turn).`,
+        `Long silences are normal here: extended thinking and large file emission produce no stream events.`,
+        this.lastActivityDesc
+          ? `Last visible activity: ${this.lastActivityDesc}.`
+          : undefined,
+      ]
+        .filter(Boolean)
+        .join(' '),
+    });
+  }
+
+  private post(entry: {
+    kind: RunLogEntryInput['kind'];
+    headline: string;
+    body?: string;
+  }): void {
+    void this.runLog
+      .append(
+        [{ ...entry, who: 'orchestrator' }],
+        undefined,
+        // Raw-write streaming only — the monitor must never trigger a
+        // workspace sync (control-plane churn is what V3 is eliminating).
+        { stream: true },
+      )
+      .catch((error) => {
+        log.warn(`monitor post failed: ${String(error)}`);
+      });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function turnLabel(info: TurnInfo): string {
+  let iter =
+    info.iteration != null && info.maxIterations != null
+      ? ` (iteration ${info.iteration}/${info.maxIterations})`
+      : '';
+  return `${info.turnType} turn for "${info.issueTitle}"${iter}`;
+}
+
+function budgetLabel(info: TurnInfo): string {
+  let model = info.model ?? 'session default';
+  let effort = info.effort ? ` @ ${info.effort}` : '';
+  return `model ${model}${effort}`;
+}
+
+function describeToolEvent(
+  tool: string,
+  args: Record<string, unknown>,
+): string {
+  if (tool === 'Write' || tool === 'Edit') {
+    let filePath = String(args.file_path ?? args.path ?? '');
+    let name = filePath.split('/').pop() ?? filePath;
+    return name ? `${tool} ${name}` : tool;
+  }
+  if (tool === 'post_update' || tool.endsWith('post_update')) {
+    let headline = String(args.headline ?? '').trim();
+    return headline ? `posted "${headline}"` : 'posted an update';
+  }
+  if (tool === 'screenshot_html' || tool.endsWith('screenshot_html')) {
+    let path = String(args.path ?? '');
+    return path ? `screenshot of ${path}` : 'design screenshot';
+  }
+  return tool;
+}
+
+export function fmtDuration(ms: number): string {
+  let secs = Math.round(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  let mins = Math.floor(secs / 60);
+  let rem = secs % 60;
+  if (mins < 60) return rem > 0 ? `${mins}m ${rem}s` : `${mins}m`;
+  let hours = Math.floor(mins / 60);
+  return `${hours}h ${mins % 60}m`;
+}
+
+function fmtCount(value: number | undefined): string {
+  if (value == null) return '?';
+  if (value >= 1_000_000) return `${(value / 1_000_000).toFixed(1)}M`;
+  if (value >= 1_000) return `${Math.round(value / 1_000)}k`;
+  return String(value);
+}
diff --git a/packages/software-factory/src/run-trace.ts b/packages/software-factory/src/run-trace.ts
new file mode 100644
index 00000000000..20ff45f3f34
--- /dev/null
+++ b/packages/software-factory/src/run-trace.ts
@@ -0,0 +1,178 @@
+/**
+ * Run-trace telemetry: tagged timing spans for every significant phase of a
+ * factory run, written as NDJSON so a visualization can consume the file
+ * with one JSON.parse per line — no framing, no post-processing, append-only
+ * and therefore crash-safe (a killed run keeps every span that finished).
+ *
+ * File location: `<workspaceDir>/.factory-trace/run-<startedAt>.ndjson`.
+ * Dot-directories are excluded from every realm sync path, so traces never
+ * leave the machine.
+ *
+ * Line schema (all fields flat primitives, compact keys):
+ *   header  {"v":1,"c":"run","n":"meta","t":<epoch-ms>, ...run metadata}
+ *   span    {"t":<epoch-ms start>,"d":<duration-ms>,"c":<category>,
+ *            "n":<name>, ...tags}
+ *   instant {"t":<epoch-ms>,"c":<category>,"n":<name>, ...tags}   (no "d")
+ *
+ * Categories ("c") — the aggregation axis for the visualization:
+ *   run         whole issue-loop lifetime
+ *   startup     realm bootstrap, brief load, workspace pulls
+ *   seed        seed-issue creation
+ *   skills      workspace materialization + per-issue skill resolution
+ *   manifest    host-import manifest derivation
+ *   scheduler   issue load/pick/index-settle polling
+ *   context     agent context building
+ *   inference   agent turns (n = turn type: design, build, fix, review, …)
+ *   tool        factory MCP tool executions inside agent turns
+ *   sync        workspace→realm syncs (n = workspace | product | control)
+ *   validation  the pipeline (n = pipeline) and each step (n = step name)
+ *   render-gate host-render captures
+ *   issue       one outer cycle working a single issue
+ *   iteration   one inner loop pass (agent turn + validation + syncs)
+ *
+ * Spans are self-contained (start + duration on one line): the consumer
+ * never has to pair begin/end records, and nesting is recoverable from
+ * containment of [t, t+d] intervals. Durations use the monotonic clock;
+ * `t` is wall-clock for cross-referencing with the debug log.
+ *
+ * The module is a no-op until `initRunTrace` is called; spans recorded
+ * before init (early startup) are buffered and flushed on init so the
+ * pre-workspace phases are not lost.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+import { logger } from './logger.ts';
+
+const log = logger('run-trace');
+
+/** Flat primitive tags only — keeps every line cheap to parse and index. */
+export type TraceTags = Record<string, string | number | boolean | undefined>;
+
+let tracePath: string | undefined;
+let preInitBuffer: string[] = [];
+let disabled = false;
+
+function writeLine(record: Record<string, unknown>): void {
+  if (disabled) return;
+  let line = JSON.stringify(record);
+  if (!tracePath) {
+    preInitBuffer.push(line);
+    return;
+  }
+  try {
+    appendFileSync(tracePath, line + '\n');
+  } catch (error) {
+    // Tracing must never take down a run. Disable on the first write
+    // failure (disk full, path removed) instead of failing every span.
+    disabled = true;
+    log.warn(`Trace disabled — write failed: ${String(error)}`);
+  }
+}
+
+function cleanTags(tags?: TraceTags): TraceTags {
+  if (!tags) return {};
+  let out: TraceTags = {};
+  for (let [key, value] of Object.entries(tags)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Open the trace file and flush any spans buffered before init. Returns the
+ * trace file path. Safe to call once per process; later calls are ignored
+ * (the first workspace wins — one factory run per process).
+ */
+export function initRunTrace(opts: {
+  workspaceDir: string;
+  tags?: TraceTags;
+}): string | undefined {
+  if (tracePath || disabled) return tracePath;
+  try {
+    let dir = join(opts.workspaceDir, '.factory-trace');
+    mkdirSync(dir, { recursive: true });
+    let startedAt = new Date().toISOString().replace(/[:.]/g, '-');
+    tracePath = join(dir, `run-${startedAt}.ndjson`);
+    appendFileSync(
+      tracePath,
+      JSON.stringify({
+        v: 1,
+        c: 'run',
+        n: 'meta',
+        t: Date.now(),
+        pid: process.pid,
+        ...cleanTags(opts.tags),
+      }) + '\n',
+    );
+    if (preInitBuffer.length > 0) {
+      appendFileSync(tracePath, preInitBuffer.join('\n') + '\n');
+      preInitBuffer = [];
+    }
+    log.info(`Run trace: ${tracePath}`);
+    return tracePath;
+  } catch (error) {
+    disabled = true;
+    log.warn(`Trace disabled — init failed: ${String(error)}`);
+    return undefined;
+  }
+}
+
+/** Record an instantaneous event (no duration). */
+export function traceEvent(cat: string, name: string, tags?: TraceTags): void {
+  writeLine({ t: Date.now(), c: cat, n: name, ...cleanTags(tags) });
+}
+
+/**
+ * Start a span; the returned closer writes the line. Closing twice is a
+ * no-op, and an unclosed span writes nothing — a crashed phase is visible
+ * in the trace as a gap rather than a fabricated duration.
+ */
+export function startSpan(
+  cat: string,
+  name: string,
+  tags?: TraceTags,
+): (endTags?: TraceTags) => void {
+  let t = Date.now();
+  let started = performance.now();
+  let closed = false;
+  return (endTags?: TraceTags) => {
+    if (closed) return;
+    closed = true;
+    writeLine({
+      t,
+      d: Math.round(performance.now() - started),
+      c: cat,
+      n: name,
+      ...cleanTags(tags),
+      ...cleanTags(endTags),
+    });
+  };
+}
+
+/** Run `fn` inside a span; the span closes on resolve OR reject. */
+export async function withSpan<T>(
+  cat: string,
+  name: string,
+  tags: TraceTags | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  let end = startSpan(cat, name, tags);
+  try {
+    let result = await fn();
+    end();
+    return result;
+  } catch (error) {
+    end({ error: true });
+    throw error;
+  }
+}
+
+/** Test seam: reset module state so unit tests get isolated trace files. */
+export function resetRunTraceForTesting(): void {
+  tracePath = undefined;
+  preInitBuffer = [];
+  disabled = false;
+}
diff --git a/packages/software-factory/src/screenshot-execution.ts b/packages/software-factory/src/screenshot-execution.ts
new file mode 100644
index 00000000000..e359eb31456
--- /dev/null
+++ b/packages/software-factory/src/screenshot-execution.ts
@@ -0,0 +1,140 @@
+/**
+ * Screenshot execution — renders a workspace HTML file in headless Chromium
+ * and writes a PNG next to it (or to a caller-chosen workspace path).
+ *
+ * This powers the factory's HTML-first design loop: the agent writes a plain
+ * HTML+CSS mockup with real sample copy, screenshots it here, then Reads the
+ * PNG with its native (image-capable) Read tool to critique and revise —
+ * seconds per iteration, with no lint/index/realm round-trip in the loop.
+ *
+ * Uses `@playwright/test`'s bundled chromium (already a package dependency
+ * for the QUnit runner path). Both the HTML input and the PNG output are
+ * constrained to resolve inside the workspace directory.
+ */
+
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { logger } from './logger.ts';
+
+const log = logger('screenshot-execution');
+
+export interface ScreenshotHtmlOptions {
+  /** Local workspace directory mirroring the target realm. */
+  workspaceDir: string;
+  /** Workspace-relative path to the HTML file to render. */
+  path: string;
+  /**
+   * Workspace-relative output path for the PNG. Defaults to the HTML path
+   * with its extension replaced by `.png`.
+   */
+  outputPath?: string;
+  /** Viewport width in px. Defaults to 390 (mobile). */
+  width?: number;
+  /** Viewport height in px. Defaults to 844 (mobile). */
+  height?: number;
+  /** Capture the full scrollable page (default) or just the viewport. */
+  fullPage?: boolean;
+}
+
+export interface ScreenshotHtmlResult {
+  ok: boolean;
+  /** Workspace-relative path of the written PNG on success. */
+  outputPath?: string;
+  error?: string;
+  durationMs: number;
+}
+
+export async function captureHtmlScreenshot(
+  options: ScreenshotHtmlOptions,
+): Promise<ScreenshotHtmlResult> {
+  let start = Date.now();
+  let {
+    workspaceDir,
+    path: htmlPath,
+    width = 390,
+    height = 844,
+    fullPage = true,
+  } = options;
+
+  let resolvedHtml = resolveInsideWorkspace(workspaceDir, htmlPath);
+  if (!resolvedHtml) {
+    return {
+      ok: false,
+      error: `Path "${htmlPath}" resolves outside the workspace. Use a workspace-relative path.`,
+      durationMs: Date.now() - start,
+    };
+  }
+  if (!/\.html?$/i.test(resolvedHtml)) {
+    return {
+      ok: false,
+      error: `Path "${htmlPath}" is not an .html file.`,
+      durationMs: Date.now() - start,
+    };
+  }
+  try {
+    await stat(resolvedHtml);
+  } catch {
+    return {
+      ok: false,
+      error: `HTML file "${htmlPath}" does not exist in the workspace. Write it first.`,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  let outputRelative =
+    options.outputPath ?? htmlPath.replace(/\.html?$/i, '.png');
+  let resolvedOutput = resolveInsideWorkspace(workspaceDir, outputRelative);
+  if (!resolvedOutput || !/\.png$/i.test(resolvedOutput)) {
+    return {
+      ok: false,
+      error: `Output path "${outputRelative}" must be a workspace-relative .png path.`,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  let { chromium } = await import('@playwright/test');
+  let browser = await chromium.launch();
+  try {
+    let page = await browser.newPage({ viewport: { width, height } });
+    await page.goto(pathToFileURL(resolvedHtml).href, { waitUntil: 'load' });
+    // Give fonts/layout a beat to settle — file:// loads fire `load` before
+    // font rasterization completes and a too-early capture shows fallbacks.
+    await page.waitForTimeout(200);
+    await mkdir(dirname(resolvedOutput), { recursive: true });
+    await page.screenshot({ path: resolvedOutput, fullPage });
+  } catch (error) {
+    let message = error instanceof Error ? error.message : String(error);
+    log.warn(`screenshot of ${htmlPath} failed: ${message}`);
+    return {
+      ok: false,
+      error: `Screenshot failed: ${message}`,
+      durationMs: Date.now() - start,
+    };
+  } finally {
+    await browser.close();
+  }
+
+  log.info(
+    `screenshot ${htmlPath} → ${outputRelative} (${width}x${height}, fullPage=${fullPage})`,
+  );
+  return {
+    ok: true,
+    outputPath: outputRelative,
+    durationMs: Date.now() - start,
+  };
+}
+
+function resolveInsideWorkspace(
+  workspaceDir: string,
+  candidate: string,
+): string | undefined {
+  let root = resolve(workspaceDir);
+  let abs = resolve(root, candidate);
+  let rel = relative(root, abs);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+    return undefined;
+  }
+  return abs;
+}
diff --git a/packages/software-factory/src/skill-catalog.ts b/packages/software-factory/src/skill-catalog.ts
new file mode 100644
index 00000000000..f444c481f70
--- /dev/null
+++ b/packages/software-factory/src/skill-catalog.ts
@@ -0,0 +1,207 @@
+/**
+ * Skill catalog — on-demand skill discovery and reading for the factory agent.
+ *
+ * The system prompt front-loads only a small always-on skill core; everything
+ * else is discoverable at runtime through the `list_skills` / `read_skill`
+ * factory tools built on these functions. Progressive disclosure keeps the
+ * per-turn context budget on precedent code and design specs instead of
+ * skill text the current issue never touches.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+import { skillSearchDirs } from './factory-skill-loader.ts';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SkillCatalogEntry {
+  name: string;
+  description: string;
+  /** Reference file names loadable individually via read_skill. */
+  references: string[];
+}
+
+export interface SkillReadResult {
+  name: string;
+  /**
+   * SKILL.md body when no reference was requested; the reference file's
+   * content when one was.
+   */
+  content: string;
+  /** Reference file names available for follow-up reads. */
+  references: string[];
+  /** Set when a specific reference file was read. */
+  referenceFileName?: string;
+}
+
+const DESCRIPTION_MAX_CHARS = 240;
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Enumerate every skill resolvable from the loader's search directories.
+ * Earlier directories win on name collisions — the same precedence the
+ * SkillLoader applies — so the catalog never advertises a skill the loader
+ * would resolve to a different copy.
+ */
+export async function catalogSkills(
+  dirs: string[] = skillSearchDirs(),
+): Promise<SkillCatalogEntry[]> {
+  let seen = new Map<string, SkillCatalogEntry>();
+
+  for (let dir of dirs) {
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch {
+      continue;
+    }
+    for (let name of entries) {
+      if (seen.has(name)) continue;
+      let skillDir = join(dir, name);
+      let content: string;
+      try {
+        content = await readFile(join(skillDir, 'SKILL.md'), 'utf8');
+      } catch {
+        continue;
+      }
+      seen.set(name, {
+        name,
+        description: extractDescription(content),
+        references: await listReferenceFiles(skillDir),
+      });
+    }
+  }
+
+  return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// ---------------------------------------------------------------------------
+// Read
+// ---------------------------------------------------------------------------
+
+/**
+ * Read a skill's SKILL.md, or one of its reference files, by name.
+ * Reference reads are constrained to basenames inside the skill's own
+ * `references/` directory (or its compiled `AGENTS.md`) — no traversal.
+ */
+export async function readSkillOnDemand(
+  skillName: string,
+  referenceFileName?: string,
+  dirs: string[] = skillSearchDirs(),
+): Promise<SkillReadResult> {
+  let skillDir = await findSkillDir(skillName, dirs);
+  if (!skillDir) {
+    throw new Error(
+      `Skill "${skillName}" not found. Call list_skills for the catalog of available names.`,
+    );
+  }
+
+  let references = await listReferenceFiles(skillDir);
+
+  if (referenceFileName) {
+    let safeName = basename(referenceFileName);
+    if (!references.includes(safeName)) {
+      throw new Error(
+        `Skill "${skillName}" has no reference "${referenceFileName}". ` +
+          `Available references: ${references.length > 0 ? references.join(', ') : '(none)'}.`,
+      );
+    }
+    let refPath =
+      safeName === 'AGENTS.md'
+        ? join(skillDir, 'AGENTS.md')
+        : join(skillDir, 'references', safeName);
+    return {
+      name: skillName,
+      content: await readFile(refPath, 'utf8'),
+      references,
+      referenceFileName: safeName,
+    };
+  }
+
+  return {
+    name: skillName,
+    content: await readFile(join(skillDir, 'SKILL.md'), 'utf8'),
+    references,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+async function findSkillDir(
+  skillName: string,
+  dirs: string[],
+): Promise<string | undefined> {
+  let safeName = basename(skillName);
+  for (let dir of dirs) {
+    let candidate = join(dir, safeName);
+    try {
+      await stat(join(candidate, 'SKILL.md'));
+      return candidate;
+    } catch {
+      // try next directory
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Reference files a skill exposes: the compiled `AGENTS.md` for rules-style
+ * skills (e.g. ember-best-practices), else the `references/*.md` set — the
+ * same shapes the SkillLoader inlines.
+ */
+async function listReferenceFiles(skillDir: string): Promise<string[]> {
+  try {
+    await stat(join(skillDir, 'rules'));
+    try {
+      await stat(join(skillDir, 'AGENTS.md'));
+      return ['AGENTS.md'];
+    } catch {
+      return [];
+    }
+  } catch {
+    // no rules/ dir — fall through to references/
+  }
+
+  try {
+    let files = await readdir(join(skillDir, 'references'));
+    return files.filter((f) => f.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * One-line description for the catalog: frontmatter `description:` when
+ * present, else the first non-empty non-heading body line.
+ */
+function extractDescription(skillMd: string): string {
+  let body = skillMd;
+  let frontmatter = skillMd.match(/^---\n([\s\S]*?)\n---\n/);
+  if (frontmatter) {
+    let descLine = frontmatter[1]
+      .split('\n')
+      .find((l) => l.startsWith('description:'));
+    if (descLine) {
+      return truncate(descLine.slice('description:'.length).trim());
+    }
+    body = skillMd.slice(frontmatter[0].length);
+  }
+  let line = body
+    .split('\n')
+    .find((l) => l.trim() !== '' && !l.trim().startsWith('#'));
+  return truncate(line?.trim() ?? '');
+}
+
+function truncate(text: string): string {
+  return text.length > DESCRIPTION_MAX_CHARS
+    ? text.slice(0, DESCRIPTION_MAX_CHARS - 1) + '…'
+    : text;
+}
diff --git a/packages/software-factory/src/transient-agent-error.ts b/packages/software-factory/src/transient-agent-error.ts
new file mode 100644
index 00000000000..cb17983c25c
--- /dev/null
+++ b/packages/software-factory/src/transient-agent-error.ts
@@ -0,0 +1,80 @@
+/**
+ * Retry wrapper for transient Agent SDK / network faults on a single
+ * agent turn. Observed cause: an SDK "Stream idle timeout - partial
+ * response received" crashed a whole multi-hour factory run 5 issues
+ * deep (wardrobe, 2026-07-17) — no code defect involved, just a network
+ * blip during a long-running turn. `runIssueLoop` has no retry around
+ * `agent.run()`, so any exception there — transient or not — propagates
+ * straight up through the CLI and kills the process.
+ *
+ * This does NOT catch agent logic errors, tool failures, or validation
+ * failures — those are real signal the loop already handles (blocked
+ * status, iteration retry, defect issues). It only retries the narrow
+ * set of errors that mean "the network hiccuped," identified by message
+ * pattern since the Agent SDK doesn't expose a typed error class for
+ * them.
+ */
+
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_BASE_DELAY_MS = 2_000;
+
+const TRANSIENT_PATTERNS = [
+  /stream idle timeout/i,
+  /econnreset/i,
+  /etimedout/i,
+  /econnrefused/i,
+  /socket hang up/i,
+  /fetch failed/i,
+  /network error/i,
+  /premature close/i,
+];
+
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** True for the narrow set of errors that mean "the network hiccuped," not a real failure. */
+export function isTransientAgentError(error: unknown): boolean {
+  let message = errorMessage(error);
+  return TRANSIENT_PATTERNS.some((pattern) => pattern.test(message));
+}
+
+export interface RetryTransientAgentErrorOptions {
+  /** Retries after the first attempt. Default 2 (3 attempts total). */
+  maxRetries?: number;
+  /** Base delay before the first retry; doubles each subsequent retry. Default 2000ms. */
+  baseDelayMs?: number;
+  /** Override for tests — avoids real sleeps. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Call `attempt` and retry on a transient error, with exponential
+ * backoff. A non-transient error (or the final retry's transient error)
+ * rethrows immediately — callers see the same exception shape as an
+ * unwrapped `attempt()` call, just with transient faults absorbed.
+ */
+export async function retryTransientAgentError<T>(
+  attempt: () => Promise<T>,
+  onRetry?: (attemptNumber: number, error: unknown) => void,
+  options: RetryTransientAgentErrorOptions = {},
+): Promise<T> {
+  let maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  let baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  let sleep =
+    options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+
+  let attemptNumber = 0;
+  for (;;) {
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!isTransientAgentError(error) || attemptNumber >= maxRetries) {
+        throw error;
+      }
+      attemptNumber++;
+      onRetry?.(attemptNumber, error);
+      await sleep(baseDelayMs * 2 ** (attemptNumber - 1));
+    }
+  }
+}
diff --git a/packages/software-factory/src/validation-run-cache.ts b/packages/software-factory/src/validation-run-cache.ts
index bfd40ac0b84..eae4dcd324e 100644
--- a/packages/software-factory/src/validation-run-cache.ts
+++ b/packages/software-factory/src/validation-run-cache.ts
@@ -20,7 +20,7 @@
  */
 
 import { createHash } from 'node:crypto';
-import { readdir, stat } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { logger } from './logger.ts';
@@ -34,10 +34,50 @@ let log = logger('validation-run-cache');
  */
 const FINGERPRINT_IGNORED = new Set(['.boxel-history', '.boxel-sync.json']);
 
+/**
+ * Per-file content-hash memo, keyed by absolute path. A bidirectional sync's
+ * pull step rewrites unchanged files to disk with fresh mtime/ctime, so
+ * mtime is not a sound proxy for "changed" — fingerprinting on it busted the
+ * sync gate after every pull and turned every no-op sync into a full network
+ * round-trip. We hash file *content* instead, and memo the hash by
+ * (path, size, mtimeMs) so an unchanged file is stat-only (no re-read) and a
+ * pull-rewritten-but-identical file costs exactly one content hash to
+ * confirm it can still be skipped. The memo caches only the digest, so its
+ * footprint is bounded by the workspace's file count.
+ */
+const fileContentHashMemo = new Map<
+  string,
+  { size: number; mtimeMs: number; hash: string }
+>();
+
+async function contentHashForFile(
+  full: string,
+  size: number,
+  mtimeMs: number,
+): Promise<string> {
+  let memoized = fileContentHashMemo.get(full);
+  if (memoized && memoized.size === size && memoized.mtimeMs === mtimeMs) {
+    return memoized.hash;
+  }
+  let hash: string;
+  try {
+    hash = createHash('sha1')
+      .update(await readFile(full))
+      .digest('hex');
+  } catch {
+    // Unreadable (raced deletion, permission) — fall back to size so the
+    // entry still varies with the file rather than throwing out the walk.
+    hash = `unreadable:${size}`;
+  }
+  fileContentHashMemo.set(full, { size, mtimeMs, hash });
+  return hash;
+}
+
 /**
  * Cheap content fingerprint of a workspace directory: a hash over every
- * file's relative path, size, and mtime. Editing, adding, or deleting any
- * file changes it; re-syncing or checkpointing does not.
+ * file's relative path, size, and content digest. Editing, adding, or
+ * deleting any file changes it; re-syncing, pulling, or checkpointing does
+ * not (an identical file that a pull rewrote keeps its content digest).
  *
  * `extraIgnoredTopLevel` names additional top-level directories to leave
  * out of the fingerprint (e.g. `Validations` for the validation cache —
@@ -70,10 +110,8 @@ export async function computeWorkspaceFingerprint(
       if (info.isDirectory()) {
         await walk(full, rel);
       } else {
-        // ctimeMs joins size + mtimeMs to reduce the odds of a same-size
-        // edit landing within one coarse mtime tick fingerprinting as
-        // unchanged.
-        entries.push(`${rel}|${info.size}|${info.mtimeMs}|${info.ctimeMs}`);
+        let hash = await contentHashForFile(full, info.size, info.mtimeMs);
+        entries.push(`${rel}|${info.size}|${hash}`);
       }
     }
   }
diff --git a/packages/software-factory/src/validators/imports-step.ts b/packages/software-factory/src/validators/imports-step.ts
new file mode 100644
index 00000000000..c73bc29da35
--- /dev/null
+++ b/packages/software-factory/src/validators/imports-step.ts
@@ -0,0 +1,119 @@
+/**
+ * Imports validation step (v3) — the static half of the host-import
+ * manifest gate.
+ *
+ * Scans every workspace `.gts` module for `@cardstack/boxel-host/tools/`
+ * (and legacy `commands/`) imports that don't resolve against the
+ * manifest derived from the host build. Runs entirely in-process against
+ * the local workspace — no realm round-trip, no artifact card — so a
+ * phantom import fails the iteration seconds after the agent writes it
+ * instead of at runtime in the operator's browser.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+
+import type {
+  ValidationStepResult,
+  ValidationError,
+} from '../factory-agent/index.ts';
+
+import type { ValidationStepRunner } from './validation-pipeline.ts';
+
+import { findHostImportViolations } from '../host-import-manifest.ts';
+import { logger } from '../logger.ts';
+
+const log = logger('imports-step');
+
+// Workspace dirs that never contain agent-authored .gts modules.
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'design',
+  '.factory-scratch',
+]);
+
+export interface ImportsValidationStepConfig {
+  workspaceDir: string;
+  /** Valid `@cardstack/boxel-host/tools/<name>` module names. */
+  hostToolImports: string[];
+}
+
+export class ImportsValidationStep implements ValidationStepRunner {
+  readonly step = 'imports' as const;
+  private workspaceDir: string;
+  private manifest: Set<string>;
+
+  constructor(config: ImportsValidationStepConfig) {
+    this.workspaceDir = config.workspaceDir;
+    this.manifest = new Set(config.hostToolImports);
+  }
+
+  async run(): Promise<ValidationStepResult> {
+    let errors: ValidationError[] = [];
+    let files: string[] = [];
+    try {
+      files = await this.listGtsFiles();
+    } catch (error) {
+      // Never block a run on the gate's own failure — report pass with a log.
+      log.warn(`imports step could not list workspace: ${String(error)}`);
+      return { step: this.step, passed: true, errors: [] };
+    }
+    for (let relPath of files) {
+      let source: string;
+      try {
+        source = await readFile(join(this.workspaceDir, relPath), 'utf8');
+      } catch {
+        continue;
+      }
+      for (let violation of findHostImportViolations(source, this.manifest)) {
+        errors.push({
+          file: relPath,
+          message: violation.suggestion
+            ? `invalid host import '${violation.specifier}': ${violation.suggestion}`
+            : `invalid host import '${violation.specifier}'`,
+        });
+      }
+    }
+    return {
+      step: this.step,
+      passed: errors.length === 0,
+      files,
+      errors,
+    };
+  }
+
+  formatForContext(result: ValidationStepResult): string {
+    if (result.passed || result.errors.length === 0) {
+      return '';
+    }
+    let lines = [
+      '### Host import check FAILED',
+      '',
+      'These imports do not exist in the host build and will crash at',
+      'runtime. Fix them before anything else — the module cannot load:',
+      '',
+      ...result.errors.map((e) => `- ${e.file ?? '?'}: ${e.message}`),
+      '',
+      'The authoritative import list is in the `host-tools-import-manifest`',
+      'skill in your context.',
+    ];
+    return lines.join('\n');
+  }
+
+  private async listGtsFiles(): Promise<string[]> {
+    let entries = await readdir(this.workspaceDir, {
+      recursive: true,
+      withFileTypes: true,
+    });
+    let files: string[] = [];
+    for (let entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith('.gts')) continue;
+      let abs = join(entry.parentPath, entry.name);
+      let rel = relative(this.workspaceDir, abs).split(sep).join('/');
+      if (SKIP_DIRS.has(rel.split('/')[0])) continue;
+      files.push(rel);
+    }
+    return files;
+  }
+}
diff --git a/packages/software-factory/src/validators/validation-pipeline.ts b/packages/software-factory/src/validators/validation-pipeline.ts
index ede73a07fb4..9f2fda6b4de 100644
--- a/packages/software-factory/src/validators/validation-pipeline.ts
+++ b/packages/software-factory/src/validators/validation-pipeline.ts
@@ -16,10 +16,12 @@ import type {
 } from '../factory-agent/index.ts';
 
 import type { Validator } from '../issue-loop.ts';
+import { startSpan } from '../run-trace.ts';
 
 import { TestValidationStep } from './test-step.ts';
 import { LintValidationStep } from './lint-step.ts';
 import { EvalValidationStep } from './eval-step.ts';
+import { ImportsValidationStep } from './imports-step.ts';
 import { InstantiateValidationStep } from './instantiate-step.ts';
 import { ParseValidationStep } from './parse-step.ts';
 
@@ -77,8 +79,21 @@ export class ValidationPipeline implements Validator {
       return { passed: true, steps: [] };
     }
 
+    // Steps run concurrently, so step spans overlap inside the pipeline
+    // span — the visualization should treat the pipeline duration as the
+    // wall-clock cost and the step durations as attribution.
     let settled = await Promise.allSettled(
-      this.runners.map((runner) => runner.run(targetRealm, iteration)),
+      this.runners.map(async (runner) => {
+        let endStepSpan = startSpan('validation', runner.step, { iteration });
+        try {
+          let result = await runner.run(targetRealm, iteration);
+          endStepSpan({ passed: result.passed });
+          return result;
+        } catch (error) {
+          endStepSpan({ passed: false, error: true });
+          throw error;
+        }
+      }),
     );
 
     let stepResults: ValidationStepResult[] = [];
@@ -179,6 +194,20 @@ export interface ValidationPipelineConfig {
   searchSpecsFn?: InstantiateValidationStepConfig['searchSpecsFn'];
   /** Injected for testing — passed through to ParseValidationStep. */
   parseSearchSpecsFn?: ParseValidationStepConfig['searchSpecsFn'];
+  /**
+   * Include the QUnit test step (default true). The V2 lean loop sets this
+   * to false — tests belong to a separate hardening phase, so the per-issue
+   * pipeline is parse/lint/eval/instantiate only.
+   */
+  includeTestStep?: boolean;
+  /**
+   * Valid `@cardstack/boxel-host/tools/<name>` module names, derived from
+   * the host build at run start (v3 import gate). When set, the pipeline
+   * gains an in-process `imports` step that fails any workspace .gts
+   * importing a host tool that doesn't exist — the class of failure that
+   * previously only surfaced at runtime in the browser. Absent = no gate.
+   */
+  hostToolImports?: string[];
 }
 
 /**
@@ -240,11 +269,22 @@ export function createDefaultPipeline(
     fetchFilenames: config.fetchFilenames,
   };
 
-  return new ValidationPipeline([
+  let steps: ValidationStepRunner[] = [
     new ParseValidationStep(parseConfig),
     new LintValidationStep(lintConfig),
     new EvalValidationStep(evalConfig),
     new InstantiateValidationStep(instantiateConfig),
-    new TestValidationStep(testConfig),
-  ]);
+  ];
+  if (config.hostToolImports) {
+    steps.unshift(
+      new ImportsValidationStep({
+        workspaceDir: config.workspaceDir,
+        hostToolImports: config.hostToolImports,
+      }),
+    );
+  }
+  if (config.includeTestStep !== false) {
+    steps.push(new TestValidationStep(testConfig));
+  }
+  return new ValidationPipeline(steps);
 }
diff --git a/packages/software-factory/src/workspace-skills.ts b/packages/software-factory/src/workspace-skills.ts
new file mode 100644
index 00000000000..a0b0d764fe4
--- /dev/null
+++ b/packages/software-factory/src/workspace-skills.ts
@@ -0,0 +1,153 @@
+/**
+ * Materialize the factory skill catalog into the agent workspace as
+ * `<workspace>/.claude/skills/<name>/` — the same convention Claude Code
+ * uses for project skills.
+ *
+ * Why: the MCP `read_skill` tool is a custom lookup path the model has
+ * no trained instinct for, and it cannot SEARCH across skills. Models
+ * are heavily conditioned to explore `.claude/*` with native
+ * Glob/Grep/Read — leaning into that instinct beats teaching a bespoke
+ * tool. With the files on disk the agent can `Grep 'fitted'
+ * .claude/skills` and find the standard it didn't know existed (the
+ * unknown-unknown failure mode that shipped a non-standard fitted view,
+ * wardrobe 2026-07-17), and with `settingSources: ['project']` the SDK
+ * harness discovers them natively like any Claude Code project.
+ *
+ * Sync safety: the realm sync skips every dotfile/dotdir, so `.claude/`
+ * never reaches the realm. The `read_skill` MCP tool stays available
+ * (other backends, and the resolver's always-on injection path).
+ */
+
+import {
+  cp,
+  mkdir,
+  readdir,
+  readFile,
+  stat,
+  writeFile,
+} from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import { skillSearchDirs } from './factory-skill-loader.ts';
+import { logger } from './logger.ts';
+
+let log = logger('workspace-skills');
+
+const PACKAGE_ROOT = resolve(import.meta.dirname, '..');
+
+/** Factory-adapted Boxel conventions, copied to `<workspace>/CLAUDE.md`. */
+const WORKSPACE_CLAUDE_MD_SOURCE = join(
+  PACKAGE_ROOT,
+  '.agents',
+  'workspace-CLAUDE.md',
+);
+
+const IGNORE_MARKER = '# factory agent-infra (auto-generated block)';
+
+async function isDir(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Copy every resolvable skill (its whole directory: SKILL.md, AGENTS.md,
+ * references/) into `<workspace>/.claude/skills/<name>/`. Earlier search
+ * dirs win on name collisions, matching the loader's precedence. Returns
+ * the number of skills materialized. Best-effort: a failure logs and
+ * skips — the run must not die over skill copying.
+ */
+export async function materializeWorkspaceSkills(
+  workspaceDir: string,
+  dirs: string[] = skillSearchDirs(),
+): Promise<number> {
+  let targetRoot = join(workspaceDir, '.claude', 'skills');
+  let materialized = new Set<string>();
+  for (let dir of dirs) {
+    if (!(await isDir(dir))) continue;
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (let entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (materialized.has(entry.name)) continue; // precedence: first wins
+      let skillMd = join(dir, entry.name, 'SKILL.md');
+      try {
+        await stat(skillMd);
+      } catch {
+        continue; // not a skill dir
+      }
+      try {
+        await mkdir(targetRoot, { recursive: true });
+        await cp(join(dir, entry.name), join(targetRoot, entry.name), {
+          recursive: true,
+          force: true,
+        });
+        materialized.add(entry.name);
+      } catch (err) {
+        log.warn(
+          `Failed to materialize skill "${entry.name}": ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  }
+  if (materialized.size > 0) {
+    log.info(
+      `Materialized ${materialized.size} skill(s) into workspace .claude/skills/`,
+    );
+  }
+  await materializeWorkspaceClaudeMd(workspaceDir);
+  return materialized.size;
+}
+
+/**
+ * Copy the factory-adapted Boxel conventions to `<workspace>/CLAUDE.md`
+ * and make sure the realm sync ignores it. With `settingSources:
+ * ['project']` the SDK harness auto-loads a workspace-root CLAUDE.md as
+ * project instructions — the same always-on conventions channel every
+ * Claude Code project gets. Unlike `.claude/` (a dotdir the sync skips
+ * automatically), a root CLAUDE.md WOULD sync to the product realm, so
+ * an ignore entry is appended to `.boxelignore` (which the sync
+ * consumes) before the file is written.
+ */
+export async function materializeWorkspaceClaudeMd(
+  workspaceDir: string,
+  sourcePath: string = WORKSPACE_CLAUDE_MD_SOURCE,
+): Promise<boolean> {
+  let content;
+  try {
+    content = await readFile(sourcePath, 'utf8');
+  } catch {
+    return false; // no template shipped — nothing to do
+  }
+  try {
+    let ignorePath = join(workspaceDir, '.boxelignore');
+    let existing = '';
+    try {
+      existing = await readFile(ignorePath, 'utf8');
+    } catch {
+      // no ignore file yet
+    }
+    if (!existing.includes(IGNORE_MARKER)) {
+      let block = [IGNORE_MARKER, '/CLAUDE.md', ''].join('\n');
+      await writeFile(
+        ignorePath,
+        existing ? `${existing.replace(/\n?$/, '\n')}${block}` : block,
+        'utf8',
+      );
+    }
+    await writeFile(join(workspaceDir, 'CLAUDE.md'), content, 'utf8');
+    log.info('Materialized workspace CLAUDE.md (sync-ignored)');
+    return true;
+  } catch (err) {
+    log.warn(
+      `Failed to materialize workspace CLAUDE.md: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}
diff --git a/packages/software-factory/tests/agent-tool-telemetry.test.ts b/packages/software-factory/tests/agent-tool-telemetry.test.ts
new file mode 100644
index 00000000000..341a053454f
--- /dev/null
+++ b/packages/software-factory/tests/agent-tool-telemetry.test.ts
@@ -0,0 +1,103 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import {
+  TurnToolTelemetry,
+  describeToolArg,
+} from '../src/factory-agent/agent-tool-telemetry.ts';
+
+module('agent-tool-telemetry', function (hooks) {
+  let workspaceDir: string;
+
+  hooks.beforeEach(function () {
+    workspaceDir = mkdtempSync(join(tmpdir(), 'tool-telemetry-'));
+  });
+
+  hooks.afterEach(function () {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  test('a clean turn flags nothing', function (assert) {
+    let t = new TurnToolTelemetry(workspaceDir);
+    t.record('Read', { file_path: 'a.gts' });
+    t.record('Edit', { file_path: 'a.gts' });
+    t.record('Bash', { command: 'boxel search --realm x' });
+    let s = t.finish();
+    assert.strictEqual(s.totalCalls, 3);
+    assert.deepEqual(s.concerns, [], 'no waste concerns');
+  });
+
+  test('flags a duplicate Read of the same file', function (assert) {
+    let t = new TurnToolTelemetry(workspaceDir);
+    t.record('Read', { file_path: 'card.gts' });
+    t.record('Read', { file_path: 'card.gts' });
+    t.record('Read', { file_path: 'other.gts' });
+    let s = t.finish();
+    assert.ok(
+      s.concerns.some((c) => c.includes('re-read') && c.includes('card.gts')),
+      'duplicate read is flagged',
+    );
+  });
+
+  test('flags a whole-file Write over an existing file', function (assert) {
+    writeFileSync(join(workspaceDir, 'model.gts'), 'export class M {}');
+    let t = new TurnToolTelemetry(workspaceDir);
+    t.record('Write', { file_path: 'model.gts' }); // exists → rewrite
+    t.record('Write', { file_path: 'new.gts' }); // absent → fine
+    let s = t.finish();
+    assert.ok(
+      s.concerns.some(
+        (c) => c.includes('whole-file Write') && c.includes('model.gts'),
+      ),
+      'rewrite of existing file flagged',
+    );
+    assert.notOk(
+      s.concerns.some((c) => c.includes('new.gts')),
+      'first-time write of a new file is not flagged',
+    );
+  });
+
+  test('flags mutating Bash but not read-only Bash', function (assert) {
+    let t = new TurnToolTelemetry(workspaceDir);
+    t.record('Bash', { command: 'ls -la && grep foo bar' });
+    t.record('Bash', { command: 'rm -rf design/old' });
+    let s = t.finish();
+    assert.ok(
+      s.concerns.some((c) => c.includes('mutating Bash')),
+      'mutating bash flagged',
+    );
+  });
+
+  test('flags screenshot thrash only past the threshold', function (assert) {
+    let t = new TurnToolTelemetry(workspaceDir);
+    for (let i = 0; i < 5; i++) {
+      t.record('mcp__factory__screenshot_html', { path: `design/v${i}.html` });
+    }
+    let s = t.finish();
+    assert.ok(
+      s.concerns.some((c) => c.includes('screenshots')),
+      '5 screenshots flagged',
+    );
+  });
+
+  test('describeToolArg returns a basename for path-bearing tools', function (assert) {
+    assert.strictEqual(
+      describeToolArg('Read', { file_path: 'design/foo/bar.gts' }),
+      'bar.gts',
+    );
+    assert.strictEqual(
+      describeToolArg('Bash', { command: 'boxel search --realm https://x/y' }),
+      'boxel search --realm https://x/y',
+    );
+    assert.strictEqual(
+      describeToolArg('mcp__factory__screenshot_html', {
+        path: 'design/card.html',
+      }),
+      'card.html',
+    );
+  });
+});
diff --git a/packages/software-factory/tests/control-plane-sync.test.ts b/packages/software-factory/tests/control-plane-sync.test.ts
new file mode 100644
index 00000000000..c6938879197
--- /dev/null
+++ b/packages/software-factory/tests/control-plane-sync.test.ts
@@ -0,0 +1,188 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
+
+import {
+  ControlPlaneSync,
+  ensureControlPlaneIgnoreFile,
+  isControlPath,
+} from '../src/control-plane-sync.ts';
+
+const CONTROL_REALM = 'https://example.com/user/control/';
+
+interface FakeClient {
+  client: BoxelCLIClient;
+  writes: { path: string; content: string }[];
+  remoteFiles: Map<string, string>;
+}
+
+function makeFakeClient(remote: Record<string, string> = {}): FakeClient {
+  let writes: { path: string; content: string }[] = [];
+  let remoteFiles = new Map(Object.entries(remote));
+  let client = {
+    listFiles: async () => ({ filenames: [...remoteFiles.keys()] }),
+    read: async (_realm: string, path: string) => {
+      let content = remoteFiles.get(path);
+      return content !== undefined
+        ? { ok: true, content }
+        : { ok: false, error: 'not found' };
+    },
+    write: async (_realm: string, path: string, content: string) => {
+      writes.push({ path, content });
+      remoteFiles.set(path, content);
+      return { ok: true };
+    },
+  } as unknown as BoxelCLIClient;
+  return { client, writes, remoteFiles };
+}
+
+async function makeWorkspace(): Promise<string> {
+  return mkdtemp(join(tmpdir(), 'control-plane-sync-test-'));
+}
+
+test('isControlPath classifies tracker, run-log, and product paths', () => {
+  assert.equal(isControlPath('Issues/seed.json'), true);
+  assert.equal(isControlPath('Knowledge Articles/how-to.json'), true);
+  assert.equal(isControlPath('Runs/boxel-wardrobe.json'), true);
+  assert.equal(isControlPath('run-log.gts'), true);
+  assert.equal(isControlPath('garment.gts'), false);
+  assert.equal(isControlPath('Garment/tee.json'), false);
+  assert.equal(isControlPath('design/garment-isolated.png'), false);
+  // Prefix similarity must not leak: `IssuesArchive/` is not `Issues/`.
+  assert.equal(isControlPath('IssuesArchive/x.json'), false);
+});
+
+test('sync pushes only changed control files (hash-gated raw writes)', async () => {
+  let workspaceDir = await makeWorkspace();
+  try {
+    let { client, writes } = makeFakeClient();
+    let sync = new ControlPlaneSync({
+      client,
+      controlRealm: CONTROL_REALM,
+      workspaceDir,
+    });
+
+    await mkdir(join(workspaceDir, 'Issues'), { recursive: true });
+    await writeFile(join(workspaceDir, 'Issues', 'seed.json'), '{"a":1}');
+    await writeFile(join(workspaceDir, 'run-log.gts'), 'export class X {}');
+    // Product file — must never ride the control sync.
+    await writeFile(join(workspaceDir, 'garment.gts'), 'export class G {}');
+
+    let first = await sync.sync();
+    assert.equal(first.ok, true);
+    assert.deepEqual(first.pushed.sort(), ['Issues/seed.json', 'run-log.gts']);
+
+    // Unchanged content — nothing goes over the wire.
+    let second = await sync.sync();
+    assert.equal(second.ok, true);
+    assert.deepEqual(second.pushed, []);
+    assert.equal(writes.length, 2);
+
+    // Changed content — only the changed file re-pushes.
+    await writeFile(join(workspaceDir, 'Issues', 'seed.json'), '{"a":2}');
+    let third = await sync.sync();
+    assert.deepEqual(third.pushed, ['Issues/seed.json']);
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+test('pull fetches only control paths and seeds the hash gate', async () => {
+  let workspaceDir = await makeWorkspace();
+  try {
+    let { client, writes } = makeFakeClient({
+      'Issues/old-issue.json': '{"status":"done"}',
+      'index.json': '{"product":"index — must not be pulled"}',
+      'garment.gts': 'product module — must not be pulled',
+    });
+    let sync = new ControlPlaneSync({
+      client,
+      controlRealm: CONTROL_REALM,
+      workspaceDir,
+    });
+
+    let pull = await sync.pull();
+    assert.equal(pull.ok, true);
+    assert.equal(pull.pulled, 1);
+    let pulled = await readFile(
+      join(workspaceDir, 'Issues', 'old-issue.json'),
+      'utf8',
+    );
+    assert.equal(pulled, '{"status":"done"}');
+
+    // The pulled file's hash is seeded — an immediate sync re-pushes nothing.
+    let push = await sync.sync();
+    assert.deepEqual(push.pushed, []);
+    assert.equal(writes.length, 0);
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+test('ensureControlPlaneIgnoreFile is idempotent and appends to user content', async () => {
+  let workspaceDir = await makeWorkspace();
+  try {
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    let content = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+    assert.match(content, /^\/Issues\/$/m);
+    assert.match(content, /^\/Runs\/$/m);
+    assert.match(content, /^\/run-log\.gts$/m);
+    assert.match(content, /^\/\.boxelignore$/m);
+
+    // Second call leaves the file untouched.
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    let again = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+    assert.equal(again, content);
+
+    // A user-authored ignore file gets the block appended, not replaced.
+    await writeFile(join(workspaceDir, '.boxelignore'), '/scratch/\n');
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    let merged = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+    assert.match(merged, /^\/scratch\/$/m);
+    assert.match(merged, /^\/Issues\/$/m);
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+test('ensureControlPlaneIgnoreFile refreshes a STALE managed block', async () => {
+  let workspaceDir = await makeWorkspace();
+  try {
+    // An older run wrote a control block that predates RunLogEntries — the
+    // exact state that leaked entry cards into the product atomic sync (500).
+    let stale = [
+      '/scratch/',
+      '',
+      '# software-factory control-plane split',
+      '/Issues/',
+      '/Runs/',
+      '/run-log.gts',
+      '/.boxelignore',
+      '',
+    ].join('\n');
+    await writeFile(join(workspaceDir, '.boxelignore'), stale);
+
+    await ensureControlPlaneIgnoreFile(workspaceDir);
+    let refreshed = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+
+    // The current CONTROL_DIRS set is now present…
+    assert.match(
+      refreshed,
+      /^\/RunLogEntries\/$/m,
+      'stale block refreshed to include RunLogEntries',
+    );
+    // …the user content is preserved…
+    assert.match(refreshed, /^\/scratch\/$/m, 'user-authored lines kept');
+    // …and the marker appears exactly once (no duplicate stacked block).
+    let markerCount = (
+      refreshed.match(/# software-factory control-plane split/g) || []
+    ).length;
+    assert.equal(markerCount, 1, 'no duplicate control-plane marker block');
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/software-factory/tests/factory-agent-claude-code.test.ts b/packages/software-factory/tests/factory-agent-claude-code.test.ts
index 3ab7b6fecca..51d4a61893c 100644
--- a/packages/software-factory/tests/factory-agent-claude-code.test.ts
+++ b/packages/software-factory/tests/factory-agent-claude-code.test.ts
@@ -442,7 +442,12 @@ module('factory-agent-claude-code', function () {
         'function',
         'canUseTool is wired so native fs ops can be scoped to the workspace',
       );
-      assert.deepEqual(capturedOptions!.settingSources, []);
+      // 'project' (not 'user'/'local'): the factory materializes its
+      // skill catalog into `<workspace>/.claude/skills/` and the harness
+      // discovers it natively, while staying isolated from the host
+      // user's own Claude settings. This agent has a workspaceDir, so
+      // project settings load; without one it stays [].
+      assert.deepEqual(capturedOptions!.settingSources, ['project']);
     });
 
     test('native fs tools are NOT auto-approved so canUseTool can gate them (CS-11033)', async function (assert) {
diff --git a/packages/software-factory/tests/factory-context-builder.test.ts b/packages/software-factory/tests/factory-context-builder.test.ts
index ea1810f233b..8a1b26f00de 100644
--- a/packages/software-factory/tests/factory-context-builder.test.ts
+++ b/packages/software-factory/tests/factory-context-builder.test.ts
@@ -543,26 +543,39 @@ module('factory-context-builder > buildForIssue > relationships', function () {
     assert.strictEqual(ctx.knowledge[1].id, 'ka-2');
   });
 
-  test('throws when issue has no linked project', async function (assert) {
+  test('an issue with no linked project gets a stub instead of killing the run', async function (assert) {
     let { config } = makeIssueConfig({ project: null });
     let builder = new ContextBuilder(config);
 
-    try {
-      await builder.buildForIssue({
-        issue: makeIssue({ id: 'orphan-issue' }),
-        targetRealm: 'https://example.test/target/',
-      });
-      assert.ok(false, 'should have thrown');
-    } catch (error) {
-      assert.ok(
-        (error as Error).message.includes('orphan-issue'),
-        'error mentions the issue id',
-      );
-      assert.ok(
-        (error as Error).message.includes('no linked project'),
-        'error explains the problem',
-      );
-    }
+    // Agent-authored issues (e.g. acceptance-walkthrough defect issues)
+    // may omit relationships entirely; throwing here took down a whole
+    // run over one unlinked issue (wardrobe, 2026-07-17).
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue({ id: 'orphan-issue' }),
+      targetRealm: 'https://example.test/target/',
+    });
+
+    assert.strictEqual(
+      ctx.project.id,
+      'bootstrap-pending',
+      'context builds with the stub project rather than throwing',
+    );
+  });
+
+  test('analysis issue (PORT-0) with no linked project gets a stub project instead of throwing', async function (assert) {
+    let { config } = makeIssueConfig({ project: null });
+    let builder = new ContextBuilder(config);
+
+    let ctx = await builder.buildForIssue({
+      issue: makeIssue({ id: 'port-analysis-seed', issueType: 'analysis' }),
+      targetRealm: 'https://example.test/target/',
+    });
+
+    assert.strictEqual(
+      ctx.project.id,
+      'bootstrap-pending',
+      'analysis issues get the same project stub as bootstrap issues, since PORT-0 runs before any Project card exists',
+    );
   });
 });
 
diff --git a/packages/software-factory/tests/factory-entrypoint.integration.test.ts b/packages/software-factory/tests/factory-entrypoint.integration.test.ts
index eb365e5c77b..24b1f69aa41 100644
--- a/packages/software-factory/tests/factory-entrypoint.integration.test.ts
+++ b/packages/software-factory/tests/factory-entrypoint.integration.test.ts
@@ -403,7 +403,11 @@ module('factory-entrypoint integration', function () {
     );
 
     assert.strictEqual(result.status, 1);
-    assert.true(/Missing required --brief-url/.test(result.stderr));
+    assert.true(
+      /Missing required input: pass --brief-url .* or --repo-url/.test(
+        result.stderr,
+      ),
+    );
     assert.true(/Usage:/.test(result.stderr));
     assert.true(/--target-realm <realm>/.test(result.stderr));
   });
diff --git a/packages/software-factory/tests/factory-entrypoint.test.ts b/packages/software-factory/tests/factory-entrypoint.test.ts
index 77506511695..75c56ed2929 100644
--- a/packages/software-factory/tests/factory-entrypoint.test.ts
+++ b/packages/software-factory/tests/factory-entrypoint.test.ts
@@ -66,16 +66,16 @@ module('factory-entrypoint', function (hooks) {
       'https://realms.example.test/',
     ]);
 
-    assert.deepEqual(options, {
+    // Round-trip through JSON to drop undefined-valued optional flags, so
+    // this assertion pins the defined defaults without re-enumerating every
+    // optional flag the parser knows about.
+    assert.deepEqual(JSON.parse(JSON.stringify(options)), {
       briefUrl,
       targetRealm,
+      controlRealm: null,
       realmServerUrl: 'https://realms.example.test/',
       agent: 'claude',
-      openRouterModel: undefined,
-      openRouterApiKey: undefined,
-      debug: undefined,
       retryBlocked: true,
-      enableBoxelUiDiscovery: undefined,
     });
   });
 
@@ -213,7 +213,9 @@ module('factory-entrypoint', function (hooks) {
       () => parseFactoryEntrypointArgs(['--target-realm', targetRealm]),
       (error: unknown) =>
         error instanceof FactoryEntrypointUsageError &&
-        error.message === 'Missing required --brief-url',
+        /Missing required input: pass --brief-url .* or --repo-url/.test(
+          error.message,
+        ),
     );
   });
 
diff --git a/packages/software-factory/tests/factory-prompt-loader.test.ts b/packages/software-factory/tests/factory-prompt-loader.test.ts
index 97b12db5972..1d910d06ff9 100644
--- a/packages/software-factory/tests/factory-prompt-loader.test.ts
+++ b/packages/software-factory/tests/factory-prompt-loader.test.ts
@@ -9,6 +9,7 @@ import {
   buildOneShotMessages,
   FilePromptLoader,
   interpolate,
+  isBugFixIssue,
   PromptTemplateNotFoundError,
 } from '../src/factory-prompt-loader.ts';
 
@@ -834,3 +835,61 @@ module(
     });
   },
 );
+
+// ---------------------------------------------------------------------------
+// Bug-fix routing — defects skip the design round
+// ---------------------------------------------------------------------------
+
+module('factory-prompt-loader > bug-fix routing', function () {
+  test('isBugFixIssue matches defect/bug types, not feature', function (assert) {
+    assert.true(isBugFixIssue({ issueType: 'defect' }));
+    assert.true(isBugFixIssue({ issueType: 'bug' }));
+    assert.true(isBugFixIssue({ issueType: 'Regression' }));
+    assert.false(isBugFixIssue({ issueType: 'feature' }));
+    assert.false(isBugFixIssue({ issueType: 'adjustment' }));
+    assert.false(isBugFixIssue({}));
+    assert.false(isBugFixIssue(undefined));
+  });
+
+  test('a v2 defect issue gets the diagnose-and-fix prompt (no design round)', function (assert) {
+    let loader = new FilePromptLoader();
+    let prompt = assembleImplementPrompt({
+      context: makeMinimalContext({
+        v2: true,
+        issue: {
+          id: 'Issues/crash',
+          issueType: 'defect',
+          summary: 'x crashes',
+        },
+      }),
+      loader,
+    });
+    assert.true(
+      /bug fix on an existing card/i.test(prompt),
+      'uses issue-fix-v2',
+    );
+    assert.true(
+      /Do NOT run a design round/i.test(prompt),
+      'explicitly forbids the design round',
+    );
+    assert.notOk(
+      /HTML mockup before any schema/i.test(prompt),
+      'no design-first mockup section',
+    );
+  });
+
+  test('a v2 feature issue still gets the design-first implement prompt', function (assert) {
+    let loader = new FilePromptLoader();
+    let prompt = assembleImplementPrompt({
+      context: makeMinimalContext({
+        v2: true,
+        issue: { id: 'Issues/new', issueType: 'feature', summary: 'new card' },
+      }),
+      loader,
+    });
+    assert.true(
+      /DESIGN — HTML mockup before any schema/i.test(prompt),
+      'feature build keeps the design round',
+    );
+  });
+});
diff --git a/packages/software-factory/tests/factory-seed.spec.ts b/packages/software-factory/tests/factory-seed.spec.ts
index 56461163411..676da64309b 100644
--- a/packages/software-factory/tests/factory-seed.spec.ts
+++ b/packages/software-factory/tests/factory-seed.spec.ts
@@ -1,4 +1,5 @@
-import { resolve } from 'node:path';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 
 import { SupportedMimeType } from '@cardstack/runtime-common/supported-mime-type';
 
@@ -247,16 +248,30 @@ test('creates an adjust-flavored bootstrap seed when the brief carries a sourceC
   }
 });
 
-test('seed issue creation is idempotent', async ({ realm }) => {
+test('seed re-arms a pending seed and resumes a done same-brief seed', async ({
+  realm,
+}) => {
   let { cleanup, seedOptions } = buildSeedContext(realm);
 
   try {
     let result1 = await createSeedIssue(stickyNoteBrief, seedOptions);
     expect(result1.status).toBe('created');
 
+    // A seed that never reached `done` is re-armed with the current brief.
     let result2 = await createSeedIssue(stickyNoteBrief, seedOptions);
-    expect(result2.status).toBe('existing');
+    expect(result2.status).toBe('created');
     expect(result2.issueId).toBe(result1.issueId);
+
+    // A done seed belonging to the same brief is left intact so the loop
+    // resumes from the board instead of redoing finished work.
+    let seedFile = join(seedOptions.workspaceDir, `${result1.issueId}.json`);
+    let document = JSON.parse(await readFile(seedFile, 'utf8'));
+    document.data.attributes.status = 'done';
+    await writeFile(seedFile, JSON.stringify(document, null, 2));
+
+    let result3 = await createSeedIssue(stickyNoteBrief, seedOptions);
+    expect(result3.status).toBe('existing');
+    expect(result3.issueId).toBe(result1.issueId);
   } finally {
     cleanup();
   }
diff --git a/packages/software-factory/tests/factory-seed.test.ts b/packages/software-factory/tests/factory-seed.test.ts
index 29efabe7c32..fcb624f964c 100644
--- a/packages/software-factory/tests/factory-seed.test.ts
+++ b/packages/software-factory/tests/factory-seed.test.ts
@@ -3,7 +3,11 @@ const { module, test } = QUnit;
 
 import type { BoxelCLIClient } from '@cardstack/boxel-cli/api';
 
-import { linkProjectToSeedIssue } from '../src/factory-seed.ts';
+import {
+  createSeedIssue,
+  linkProjectToSeedIssue,
+} from '../src/factory-seed.ts';
+import type { FactoryBrief } from '../src/factory-brief.ts';
 import { createTestWorkspace } from './helpers/workspace-fixture.ts';
 
 const REALM = 'https://realms.example.test/me/proj/';
@@ -117,3 +121,135 @@ module('factory-seed > linkProjectToSeedIssue', function (hooks) {
     );
   });
 });
+
+const ANALYSIS_ISSUE_FILE = 'Issues/port-analysis-seed.json';
+const DESIGN_FOUNDATION_ISSUE_FILE = 'Issues/design-foundation-seed.json';
+
+function portBrief(repoUrl: string): FactoryBrief {
+  return {
+    title: `Port: ${repoUrl.split('/').pop() ?? 'app'}`,
+    sourceUrl: repoUrl,
+    content: `# Port ${repoUrl}`,
+    contentSummary: 'A GitHub app to port to Boxel.',
+    tags: [],
+    githubRepoUrl: repoUrl,
+  };
+}
+
+/** A seed card as a prior turn would leave it once completed. */
+function doneSeed(issueId: string, identityToken: string) {
+  return JSON.stringify(
+    {
+      data: {
+        type: 'card',
+        attributes: {
+          issueId,
+          status: 'done',
+          // The URL the resume guard keys on lives in the summary verbatim.
+          summary: `Done: ${identityToken}`,
+        },
+        meta: { adoptsFrom: { module: DARKFACTORY, name: 'Issue' } },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+function statusOf(
+  workspace: ReturnType<typeof createTestWorkspace>,
+  file: string,
+) {
+  return JSON.parse(workspace.read(file)).data.attributes.status;
+}
+
+module('factory-seed > createSeedIssue resume guard', function (hooks) {
+  let workspace: ReturnType<typeof createTestWorkspace>;
+  const REPO = 'https://github.com/acme/wardrobe';
+
+  hooks.beforeEach(function () {
+    workspace = createTestWorkspace();
+  });
+  hooks.afterEach(function () {
+    workspace.cleanup();
+  });
+
+  test('a fresh workspace arms analysis, bootstrap, and design-foundation at backlog', async function (assert) {
+    let result = await createSeedIssue(portBrief(REPO), {
+      darkfactoryModuleUrl: DARKFACTORY,
+      workspaceDir: workspace.dir,
+      designFoundation: true,
+    });
+
+    assert.strictEqual(result.status, 'created', 'bootstrap freshly created');
+    assert.strictEqual(
+      statusOf(workspace, ANALYSIS_ISSUE_FILE),
+      'backlog',
+      'analysis armed',
+    );
+    assert.strictEqual(
+      statusOf(workspace, SEED_ISSUE_FILE),
+      'backlog',
+      'bootstrap armed',
+    );
+    assert.strictEqual(
+      statusOf(workspace, DESIGN_FOUNDATION_ISSUE_FILE),
+      'backlog',
+      'design-foundation armed',
+    );
+  });
+
+  test('a restart on the SAME brief leaves done seeds intact (resume, not re-arm)', async function (assert) {
+    // Simulate the control-realm pull: prior turn's completed seeds are here.
+    workspace.write(ANALYSIS_ISSUE_FILE, doneSeed('PORT-0', REPO));
+    workspace.write(SEED_ISSUE_FILE, doneSeed('BOOT-1', REPO));
+    workspace.write(DESIGN_FOUNDATION_ISSUE_FILE, doneSeed('DESIGN-0', REPO));
+
+    let result = await createSeedIssue(portBrief(REPO), {
+      darkfactoryModuleUrl: DARKFACTORY,
+      workspaceDir: workspace.dir,
+      designFoundation: true,
+    });
+
+    assert.strictEqual(result.status, 'existing', 'bootstrap not re-armed');
+    assert.strictEqual(
+      statusOf(workspace, ANALYSIS_ISSUE_FILE),
+      'done',
+      'analysis stays done — no repo re-study',
+    );
+    assert.strictEqual(
+      statusOf(workspace, SEED_ISSUE_FILE),
+      'done',
+      'bootstrap stays done',
+    );
+    assert.strictEqual(
+      statusOf(workspace, DESIGN_FOUNDATION_ISSUE_FILE),
+      'done',
+      'design-foundation stays done',
+    );
+  });
+
+  test('a restart with a DIFFERENT brief re-arms the stale done seeds', async function (assert) {
+    // Done seeds left by a PRIOR brief (different repo) must not be resumed.
+    let priorRepo = 'https://github.com/acme/old-thing';
+    workspace.write(ANALYSIS_ISSUE_FILE, doneSeed('PORT-0', priorRepo));
+    workspace.write(SEED_ISSUE_FILE, doneSeed('BOOT-1', priorRepo));
+
+    let result = await createSeedIssue(portBrief(REPO), {
+      darkfactoryModuleUrl: DARKFACTORY,
+      workspaceDir: workspace.dir,
+    });
+
+    assert.strictEqual(result.status, 'created', 'bootstrap re-armed');
+    assert.strictEqual(
+      statusOf(workspace, ANALYSIS_ISSUE_FILE),
+      'backlog',
+      'analysis re-armed for the new brief',
+    );
+    assert.strictEqual(
+      statusOf(workspace, SEED_ISSUE_FILE),
+      'backlog',
+      'bootstrap re-armed for the new brief',
+    );
+  });
+});
diff --git a/packages/software-factory/tests/github-port-brief.test.ts b/packages/software-factory/tests/github-port-brief.test.ts
new file mode 100644
index 00000000000..a9f6e82cb56
--- /dev/null
+++ b/packages/software-factory/tests/github-port-brief.test.ts
@@ -0,0 +1,153 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  FactoryBriefError,
+  loadFactoryBrief,
+  loadGitHubBrief,
+  parseGitHubRepoUrl,
+} from '../src/factory-brief.ts';
+import { createSeedIssue } from '../src/factory-seed.ts';
+
+const DARKFACTORY_MODULE = 'https://example.com/software-factory/darkfactory';
+
+function githubFetchStub(): typeof globalThis.fetch {
+  return (async (input: string | URL | Request) => {
+    let url = String(input);
+    if (url === 'https://api.github.com/repos/acme/closet-app') {
+      return new Response(
+        JSON.stringify({
+          name: 'closet-app',
+          description: 'Digitize your closet with AI cutouts.',
+        }),
+        { status: 200 },
+      );
+    }
+    if (url === 'https://api.github.com/repos/acme/closet-app/readme') {
+      return new Response('# Closet App\n\nSnap photos, build outfits.', {
+        status: 200,
+      });
+    }
+    return new Response('not found', { status: 404 });
+  }) as typeof globalThis.fetch;
+}
+
+test('parseGitHubRepoUrl accepts repo URLs and rejects everything else', () => {
+  assert.deepEqual(parseGitHubRepoUrl('https://github.com/acme/closet-app'), {
+    owner: 'acme',
+    repo: 'closet-app',
+  });
+  assert.deepEqual(
+    parseGitHubRepoUrl('https://github.com/acme/closet-app.git'),
+    { owner: 'acme', repo: 'closet-app' },
+  );
+  assert.equal(parseGitHubRepoUrl('https://github.com/acme'), undefined);
+  assert.equal(
+    parseGitHubRepoUrl('https://example.com/acme/closet-app'),
+    undefined,
+  );
+  assert.equal(parseGitHubRepoUrl('not a url'), undefined);
+});
+
+test('loadFactoryBrief rejects GitHub URLs with a --repo-url pointer', async () => {
+  await assert.rejects(
+    loadFactoryBrief('https://github.com/acme/closet-app', {
+      fetch: githubFetchStub(),
+    }),
+    (err: unknown) =>
+      err instanceof FactoryBriefError && /--repo-url/.test(err.message),
+  );
+});
+
+test('loadGitHubBrief synthesizes a port brief from a repo URL', async () => {
+  let brief = await loadGitHubBrief('https://github.com/acme/closet-app', {
+    fetch: githubFetchStub(),
+  });
+  assert.equal(brief.title, 'Port: Closet App');
+  assert.equal(brief.githubRepoUrl, 'https://github.com/acme/closet-app');
+  assert.equal(brief.contentSummary, 'Digitize your closet with AI cutouts.');
+  assert.match(brief.content, /Snap photos, build outfits/);
+  assert.deepEqual(brief.tags, ['github-port']);
+});
+
+test('createSeedIssue seeds a port-analysis issue that blocks bootstrap', async () => {
+  let workspaceDir = await mkdtemp(join(tmpdir(), 'github-port-seed-'));
+  try {
+    let brief = await loadGitHubBrief('https://github.com/acme/closet-app', {
+      fetch: githubFetchStub(),
+    });
+    let result = await createSeedIssue(brief, {
+      darkfactoryModuleUrl: DARKFACTORY_MODULE,
+      workspaceDir,
+    });
+    assert.equal(result.status, 'created');
+
+    let analysis = JSON.parse(
+      await readFile(
+        join(workspaceDir, 'Issues', 'port-analysis-seed.json'),
+        'utf8',
+      ),
+    );
+    assert.equal(analysis.data.attributes.issueType, 'analysis');
+    assert.equal(analysis.data.attributes.status, 'backlog');
+    assert.equal(analysis.data.attributes.order, 0);
+    assert.match(
+      analysis.data.attributes.description,
+      /github\.com\/acme\/closet-app/,
+    );
+    assert.match(
+      analysis.data.attributes.acceptanceCriteria,
+      /Ported test contract/,
+    );
+
+    let bootstrap = JSON.parse(
+      await readFile(
+        join(workspaceDir, 'Issues', 'bootstrap-seed.json'),
+        'utf8',
+      ),
+    );
+    assert.deepEqual(bootstrap.data.relationships['blockedBy.0'], {
+      links: { self: '../Issues/port-analysis-seed' },
+    });
+    assert.equal(bootstrap.data.attributes.order, 1);
+    assert.match(
+      bootstrap.data.attributes.description,
+      /Port background \(read first\)/,
+    );
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
+
+test('non-GitHub briefs seed no analysis issue', async () => {
+  let workspaceDir = await mkdtemp(join(tmpdir(), 'plain-seed-'));
+  try {
+    let brief = {
+      title: 'Plain Brief',
+      sourceUrl: 'https://example.com/realm/Wiki/plain',
+      content: 'Build a widget.',
+      contentSummary: 'Build a widget.',
+      tags: [],
+    };
+    await createSeedIssue(brief, {
+      darkfactoryModuleUrl: DARKFACTORY_MODULE,
+      workspaceDir,
+    });
+    let bootstrap = JSON.parse(
+      await readFile(
+        join(workspaceDir, 'Issues', 'bootstrap-seed.json'),
+        'utf8',
+      ),
+    );
+    assert.equal(bootstrap.data.relationships, undefined);
+    assert.equal(bootstrap.data.attributes.order, 0);
+    await assert.rejects(
+      readFile(join(workspaceDir, 'Issues', 'port-analysis-seed.json'), 'utf8'),
+    );
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/software-factory/tests/host-import-manifest.test.ts b/packages/software-factory/tests/host-import-manifest.test.ts
new file mode 100644
index 00000000000..d40959baa8d
--- /dev/null
+++ b/packages/software-factory/tests/host-import-manifest.test.ts
@@ -0,0 +1,123 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, writeFile, rm, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  buildHostToolsSkill,
+  deriveHostToolImports,
+  findHostImportViolations,
+} from '../src/host-import-manifest.ts';
+import { ImportsValidationStep } from '../src/validators/imports-step.ts';
+
+const MANIFEST = new Set([
+  'get-card-type-schema',
+  'write-binary-file',
+  'one-shot-llm-request',
+  'bot-requests/openrouter-image',
+]);
+
+test('findHostImportViolations flags legacy commands/ imports with the rename fix', () => {
+  let source = `
+import GetCardTypeSchemaCommand from '@cardstack/boxel-host/commands/get-card-type-schema';
+import { restartable } from 'ember-concurrency';
+`;
+  let violations = findHostImportViolations(source, MANIFEST);
+  assert.equal(violations.length, 1);
+  assert.equal(
+    violations[0].specifier,
+    '@cardstack/boxel-host/commands/get-card-type-schema',
+  );
+  assert.match(violations[0].suggestion ?? '', /renamed commands\/ to tools\//);
+  assert.match(violations[0].suggestion ?? '', /tools\/get-card-type-schema/);
+});
+
+test('findHostImportViolations flags unknown tools with a near-match suggestion', () => {
+  let source = `
+import SchemaCommand from '@cardstack/boxel-host/tools/card-type-schema';
+import WriteBinary from "@cardstack/boxel-host/tools/write-binary-file";
+const lazy = await import('@cardstack/boxel-host/tools/no-such-tool');
+`;
+  let violations = findHostImportViolations(source, MANIFEST);
+  assert.equal(violations.length, 2);
+  assert.match(
+    violations[0].suggestion ?? '',
+    /did you mean '@cardstack\/boxel-host\/tools\/get-card-type-schema'/,
+  );
+  assert.equal(
+    violations[1].specifier,
+    '@cardstack/boxel-host/tools/no-such-tool',
+  );
+});
+
+test('non-gated boxel-host subpaths and valid tools pass', () => {
+  let source = `
+import { getCard } from '@cardstack/boxel-host/resources/card-resource';
+import OneShot from '@cardstack/boxel-host/tools/one-shot-llm-request';
+import ImageGen from '@cardstack/boxel-host/tools/bot-requests/openrouter-image';
+`;
+  assert.deepEqual(findHostImportViolations(source, MANIFEST), []);
+});
+
+test('deriveHostToolImports walks the tools tree recursively', async () => {
+  let dir = await mkdtemp(join(tmpdir(), 'host-tools-'));
+  try {
+    await writeFile(join(dir, 'copy-card.ts'), 'export default class {}');
+    await mkdir(join(dir, 'bot-requests'));
+    await writeFile(
+      join(dir, 'bot-requests', 'image.ts'),
+      'export default class {}',
+    );
+    await writeFile(join(dir, 'README.md'), 'not a module');
+    let names = await deriveHostToolImports(dir);
+    assert.deepEqual(names, ['bot-requests/image', 'copy-card']);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test('deriveHostToolImports returns undefined for a missing dir (gate disabled)', async () => {
+  let names = await deriveHostToolImports('/no/such/host/tools');
+  assert.equal(names, undefined);
+});
+
+test('buildHostToolsSkill lists every module and states the rename', () => {
+  let skill = buildHostToolsSkill(['copy-card', 'get-card']);
+  assert.equal(skill.name, 'host-tools-import-manifest');
+  assert.match(skill.content, /@cardstack\/boxel-host\/tools\/copy-card/);
+  assert.match(skill.content, /commands\/.*NO LONGER EXISTS/s);
+});
+
+test('ImportsValidationStep fails workspace .gts with phantom imports', async () => {
+  let workspaceDir = await mkdtemp(join(tmpdir(), 'imports-step-'));
+  try {
+    await writeFile(
+      join(workspaceDir, 'wardrobe-ai.gts'),
+      `import Cmd from '@cardstack/boxel-host/commands/one-shot-llm-request';`,
+    );
+    await writeFile(
+      join(workspaceDir, 'garment.gts'),
+      `import S from 'https://cardstack.com/base/string';`,
+    );
+    let step = new ImportsValidationStep({
+      workspaceDir,
+      hostToolImports: [...MANIFEST],
+    });
+    let result = await step.run();
+    assert.equal(result.passed, false);
+    assert.equal(result.errors.length, 1);
+    assert.equal(result.errors[0].file, 'wardrobe-ai.gts');
+    assert.match(step.formatForContext(result), /Host import check FAILED/);
+
+    // Fix the import — the step passes.
+    await writeFile(
+      join(workspaceDir, 'wardrobe-ai.gts'),
+      `import Cmd from '@cardstack/boxel-host/tools/one-shot-llm-request';`,
+    );
+    let fixed = await step.run();
+    assert.equal(fixed.passed, true);
+  } finally {
+    await rm(workspaceDir, { recursive: true, force: true });
+  }
+});
diff --git a/packages/software-factory/tests/index.ts b/packages/software-factory/tests/index.ts
index 0bfebe19e38..766440ded4e 100644
--- a/packages/software-factory/tests/index.ts
+++ b/packages/software-factory/tests/index.ts
@@ -2,6 +2,7 @@ import './qunit-bootstrap.ts'; // configures QUnit before any test registers
 import QUnit from 'qunit';
 import './factory-brief.test.ts';
 import './validation-run-cache.test.ts';
+import './agent-tool-telemetry.test.ts';
 import './factory-prompt-loader.test.ts';
 import './factory-entrypoint.test.ts';
 import './factory-entrypoint.integration.test.ts';
@@ -19,6 +20,11 @@ import './factory-tool-schema-adapter.test.ts';
 import './factory-agent-claude-code.test.ts';
 import './issue-loop.test.ts';
 import './issue-scheduler.test.ts';
+import './run-log.test.ts';
+import './run-trace.test.ts';
+import './instance-discovery.test.ts';
+import './transient-agent-error.test.ts';
+import './workspace-skills.test.ts';
 import './retry-blocked-issues.test.ts';
 import './validation-pipeline.test.ts';
 import './test-step.test.ts';
diff --git a/packages/software-factory/tests/instance-discovery.test.ts b/packages/software-factory/tests/instance-discovery.test.ts
new file mode 100644
index 00000000000..9536be28049
--- /dev/null
+++ b/packages/software-factory/tests/instance-discovery.test.ts
@@ -0,0 +1,119 @@
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import { mkdtemp, mkdir, writeFile, rm, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { discoverRecentInstanceCardPaths } from '../src/instance-discovery.ts';
+
+function instanceDoc(module: string) {
+  return JSON.stringify({
+    data: {
+      type: 'card',
+      attributes: {},
+      meta: { adoptsFrom: { module, name: 'X' } },
+    },
+  });
+}
+
+module(
+  'instance-discovery > discoverRecentInstanceCardPaths',
+  function (hooks) {
+    let workspaceDir: string;
+
+    hooks.beforeEach(async function () {
+      workspaceDir = await mkdtemp(join(tmpdir(), 'instance-discovery-test-'));
+    });
+
+    hooks.afterEach(async function () {
+      await rm(workspaceDir, { recursive: true, force: true });
+    });
+
+    async function write(
+      relPath: string,
+      content: string,
+      mtime?: Date,
+    ): Promise<void> {
+      let abs = join(workspaceDir, relPath);
+      await mkdir(join(workspaceDir, relPath.split('/')[0]), {
+        recursive: true,
+      });
+      await writeFile(abs, content);
+      if (mtime) await utimes(abs, mtime, mtime);
+    }
+
+    test('finds local-module product instances, newest first, capped', async function (assert) {
+      await write(
+        'PromptTemplate/vision.json',
+        instanceDoc('../prompt-template'),
+        new Date('2026-07-17T10:00:00Z'),
+      );
+      await write(
+        'Garment/red-jacket.json',
+        instanceDoc('../garment'),
+        new Date('2026-07-17T12:00:00Z'),
+      );
+
+      let paths = await discoverRecentInstanceCardPaths(workspaceDir);
+
+      assert.deepEqual(
+        paths,
+        ['Garment/red-jacket', 'PromptTemplate/vision'],
+        'newest-modified instance first',
+      );
+    });
+
+    test('excludes control-plane dirs and non-local modules', async function (assert) {
+      await write('Issues/some-issue.json', instanceDoc('../darkfactory'));
+      await write('Runs/wardrobe.json', instanceDoc('../run-log'));
+      await write(
+        'Spec/garment.json',
+        instanceDoc('https://cardstack.com/base/spec'),
+      );
+      // Non-local module in a product dir: a card adopted from the base
+      // realm is not a product card built by this run.
+      await write(
+        'Imported/base-thing.json',
+        instanceDoc('https://cardstack.com/base/card-def'),
+      );
+      await write('Garment/tee.json', instanceDoc('../garment'));
+
+      let paths = await discoverRecentInstanceCardPaths(workspaceDir);
+
+      assert.deepEqual(paths, ['Garment/tee']);
+    });
+
+    test('caps at the limit', async function (assert) {
+      for (let i = 0; i < 6; i++) {
+        await write(
+          `Garment/g${i}.json`,
+          instanceDoc('../garment'),
+          new Date(Date.UTC(2026, 6, 17, 10, i)),
+        );
+      }
+
+      let paths = await discoverRecentInstanceCardPaths(workspaceDir, 4);
+
+      assert.strictEqual(paths.length, 4);
+      assert.strictEqual(paths[0], 'Garment/g5', 'newest kept');
+    });
+
+    test('returns empty for an empty or missing workspace without throwing', async function (assert) {
+      assert.deepEqual(await discoverRecentInstanceCardPaths(workspaceDir), []);
+      assert.deepEqual(
+        await discoverRecentInstanceCardPaths(join(workspaceDir, 'nope')),
+        [],
+      );
+    });
+
+    test('skips malformed JSON files without failing the scan', async function (assert) {
+      await write('Garment/broken.json', '{not json');
+      await write('Garment/good.json', instanceDoc('../garment'));
+
+      let paths = await discoverRecentInstanceCardPaths(workspaceDir);
+
+      assert.deepEqual(paths, ['Garment/good']);
+    });
+  },
+);
diff --git a/packages/software-factory/tests/issue-loop.test.ts b/packages/software-factory/tests/issue-loop.test.ts
index 3f424bd5fa6..6dc8dd239c2 100644
--- a/packages/software-factory/tests/issue-loop.test.ts
+++ b/packages/software-factory/tests/issue-loop.test.ts
@@ -18,6 +18,8 @@ import type { IssueStore } from '../src/issue-scheduler.ts';
 import {
   runIssueLoop,
   NoOpValidator,
+  decideSessionStrategy,
+  failureFingerprint,
   type IssueContextBuilderLike,
   type IssueLoopConfig,
   type Validator,
@@ -133,7 +135,9 @@ class MockLoopAgent implements LoopAgent {
       }
     }
 
-    return { status: 'done', toolCalls };
+    // A stable per-turn session id so the loop's inner-iteration chaining
+    // (resume the prior iteration's session) is observable in tests.
+    return { status: 'done', toolCalls, sessionId: `sess-${this.turnIndex}` };
   }
 
   get callCount(): number {
@@ -500,6 +504,52 @@ module('issue-loop > validation failure', function () {
       'second iteration gets failing validation from first',
     );
   });
+
+  test('fix iterations chain the prior iteration session (no re-read)', async function (assert) {
+    let store = new MockIssueStore([
+      makeIssue({ id: 'iss-1', status: 'backlog', priority: 'high', order: 1 }),
+    ]);
+
+    let agent = new MockLoopAgent(
+      [
+        {
+          toolCalls: [
+            { tool: 'write_file', args: { path: 'c.gts', content: 'v1' } },
+          ],
+        },
+        {
+          toolCalls: [
+            { tool: 'write_file', args: { path: 'c.gts', content: 'v2' } },
+          ],
+          updateIssue: { id: 'iss-1', status: 'done' },
+        },
+      ],
+      store,
+    );
+
+    await runIssueLoop(
+      makeLoopConfig({
+        agent,
+        issueStore: store,
+        createValidator: () =>
+          new MockValidator([makeFailingValidation(), makePassingValidation()]),
+      }),
+    );
+
+    // Iteration 1 starts fresh (no prior session to chain).
+    assert.strictEqual(
+      agent.receivedContexts[0].resumeSession,
+      undefined,
+      'first iteration does not resume a session',
+    );
+    // Iteration 2 resumes iteration 1's session (sess-1) as a fork, so the
+    // files/edits it already read stay in context instead of being re-read.
+    assert.deepEqual(
+      agent.receivedContexts[1].resumeSession,
+      { sessionId: 'sess-1', fork: true },
+      'second iteration forks the first iteration session',
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -1373,3 +1423,99 @@ module('issue-loop > project completion', function () {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// Session-reuse decision
+// ---------------------------------------------------------------------------
+
+function failing(steps: Record<string, number>): ValidationResults {
+  let names = new Set(Object.keys(steps));
+  return {
+    passed: false,
+    steps: (['parse', 'lint', 'evaluate', 'instantiate', 'test'] as const).map(
+      (step) => ({
+        step,
+        passed: !names.has(step),
+        errors: names.has(step)
+          ? Array.from({ length: steps[step] }, () => ({
+              message: `${step} err`,
+            }))
+          : [],
+      }),
+    ),
+  };
+}
+
+module('issue-loop > failureFingerprint', function () {
+  test('empty for passing or missing results', function (assert) {
+    assert.deepEqual(failureFingerprint(undefined), {
+      steps: '',
+      errorCount: 0,
+    });
+    assert.deepEqual(failureFingerprint(makePassingValidation()), {
+      steps: '',
+      errorCount: 0,
+    });
+  });
+
+  test('sorted failing steps + total error count', function (assert) {
+    assert.deepEqual(failureFingerprint(failing({ test: 2, lint: 1 })), {
+      steps: 'lint,test',
+      errorCount: 3,
+    });
+  });
+});
+
+module('issue-loop > decideSessionStrategy', function () {
+  test('first turn is always fresh', function (assert) {
+    let d = decideSessionStrategy({
+      iteration: 1,
+      hasPriorSession: false,
+      chainDepth: 0,
+    });
+    assert.strictEqual(d.strategy, 'fresh');
+  });
+
+  test('no prior session is fresh even past iteration 1', function (assert) {
+    let d = decideSessionStrategy({
+      iteration: 3,
+      hasPriorSession: false,
+      chainDepth: 0,
+    });
+    assert.strictEqual(d.strategy, 'fresh');
+  });
+
+  test('continues while converging (fewer errors, same step)', function (assert) {
+    let d = decideSessionStrategy({
+      iteration: 3,
+      hasPriorSession: true,
+      chainDepth: 1,
+      previousFailure: failureFingerprint(failing({ lint: 3 })),
+      currentFailure: failureFingerprint(failing({ lint: 1 })),
+    });
+    assert.strictEqual(d.strategy, 'continue');
+  });
+
+  test('resets to fresh when the same failure repeats with no progress', function (assert) {
+    let same = failureFingerprint(failing({ lint: 2 }));
+    let d = decideSessionStrategy({
+      iteration: 3,
+      hasPriorSession: true,
+      chainDepth: 1,
+      previousFailure: same,
+      currentFailure: same,
+    });
+    assert.strictEqual(d.strategy, 'fresh');
+  });
+
+  test('resets to fresh at the chain cap', function (assert) {
+    let d = decideSessionStrategy({
+      iteration: 5,
+      hasPriorSession: true,
+      chainDepth: 3,
+      previousFailure: failureFingerprint(failing({ lint: 3 })),
+      currentFailure: failureFingerprint(failing({ test: 1 })),
+    });
+    assert.strictEqual(d.strategy, 'fresh');
+  });
+});
diff --git a/packages/software-factory/tests/issue-scheduler.test.ts b/packages/software-factory/tests/issue-scheduler.test.ts
index 9eda91cb669..407462ab530 100644
--- a/packages/software-factory/tests/issue-scheduler.test.ts
+++ b/packages/software-factory/tests/issue-scheduler.test.ts
@@ -10,6 +10,7 @@ import {
   RealmIssueStore,
   type IssueStore,
 } from '../src/issue-scheduler.ts';
+import { createTestWorkspace } from './helpers/workspace-fixture.ts';
 
 // ---------------------------------------------------------------------------
 // MockIssueStore
@@ -508,3 +509,53 @@ module('issue-scheduler > RealmIssueStore issue-type filter', function () {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// RealmIssueStore.readLocalStatus — authoritative workspace-file status
+// ---------------------------------------------------------------------------
+
+module('issue-scheduler > RealmIssueStore readLocalStatus', function (hooks) {
+  const realmUrl = 'http://localhost:4201/user/my-test-realm/';
+  const darkfactoryModuleUrl =
+    'http://localhost:4201/software-factory/darkfactory';
+  let workspace: ReturnType<typeof createTestWorkspace>;
+
+  hooks.beforeEach(function () {
+    workspace = createTestWorkspace();
+  });
+  hooks.afterEach(function () {
+    workspace.cleanup();
+  });
+
+  function makeStore() {
+    return new RealmIssueStore({
+      realmUrl,
+      darkfactoryModuleUrl,
+      client: {} as unknown as BoxelCLIClient,
+      workspaceDir: workspace.dir,
+    });
+  }
+
+  test('reads the status from the local workspace file, not the realm index', async function (assert) {
+    // The workspace file is the source of truth the sync pushes; the index
+    // can lag behind it. A completed seed reads `done` here even while the
+    // index still reports `in_progress`.
+    workspace.write(
+      'Issues/port-analysis-seed.json',
+      JSON.stringify({
+        data: { type: 'card', attributes: { status: 'done' } },
+      }),
+    );
+    let status = await makeStore().readLocalStatus(
+      `${realmUrl}Issues/port-analysis-seed`,
+    );
+    assert.strictEqual(status, 'done');
+  });
+
+  test('returns undefined when the workspace file is absent', async function (assert) {
+    let status = await makeStore().readLocalStatus(
+      `${realmUrl}Issues/never-written`,
+    );
+    assert.strictEqual(status, undefined);
+  });
+});
diff --git a/packages/software-factory/tests/run-log.test.ts b/packages/software-factory/tests/run-log.test.ts
new file mode 100644
index 00000000000..7aecb593df3
--- /dev/null
+++ b/packages/software-factory/tests/run-log.test.ts
@@ -0,0 +1,791 @@
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import {
+  mkdtemp,
+  mkdir,
+  writeFile,
+  readFile,
+  rm,
+  stat,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  cardPathsFromToolCalls,
+  persistDesignScreenshot,
+  summarizeCheckFailure,
+  RunLogWriter,
+  buildLegacyMigration,
+  autolinkCardReferences,
+} from '../src/run-log.ts';
+
+const CONTROL = 'https://app.boxel.ai/me/proj-ops/';
+const PRODUCT = 'https://app.boxel.ai/me/proj/';
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+function writeCall(filePath: string) {
+  return {
+    tool: 'Write',
+    args: { file_path: filePath },
+    result: undefined,
+  };
+}
+
+async function makeWorkspace(): Promise<string> {
+  return mkdtemp(join(tmpdir(), 'run-log-test-'));
+}
+
+// ---------------------------------------------------------------------------
+// Tests: cardPathsFromToolCalls
+// ---------------------------------------------------------------------------
+
+module('run-log > cardPathsFromToolCalls', function () {
+  test('excludes Knowledge Articles paths written with a real space', function (assert) {
+    let paths = cardPathsFromToolCalls([
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Knowledge Articles/port-code-analysis.json',
+      ),
+    ]);
+
+    assert.deepEqual(
+      paths,
+      [],
+      'a real-space "Knowledge Articles/" path must not be treated as a product ship-moment card — it lives in the control realm and would otherwise get an absolute product-realm link that 404s',
+    );
+  });
+
+  test('excludes Knowledge Articles paths written with a URL-encoded space', function (assert) {
+    let paths = cardPathsFromToolCalls([
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Knowledge%20Articles/port-background.json',
+      ),
+    ]);
+
+    assert.deepEqual(
+      paths,
+      [],
+      'a %20-encoded "Knowledge Articles/" path is excluded too',
+    );
+  });
+
+  test('still includes ordinary product-realm instance paths', function (assert) {
+    let paths = cardPathsFromToolCalls([
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Garment/red-jacket.json',
+      ),
+    ]);
+
+    assert.deepEqual(
+      paths,
+      ['Garment/red-jacket'],
+      'a normal deliverable instance is still picked up as a ship-moment card',
+    );
+  });
+
+  test('excludes other control-plane dirs (Issues, Projects, Boards, Spec, Validations, Runs, design)', function (assert) {
+    let paths = cardPathsFromToolCalls([
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Issues/bootstrap-seed.json',
+      ),
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Projects/wardrobe.json',
+      ),
+      writeCall('/tmp/boxel-factory-workspaces/wardrobe/Boards/main.json'),
+      writeCall('/tmp/boxel-factory-workspaces/wardrobe/Spec/garment.json'),
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/Validations/lint_issue-1-1.json',
+      ),
+      writeCall('/tmp/boxel-factory-workspaces/wardrobe/Runs/wardrobe.json'),
+      writeCall(
+        '/tmp/boxel-factory-workspaces/wardrobe/design/song-isolated.json',
+      ),
+    ]);
+
+    assert.deepEqual(
+      paths,
+      [],
+      'none of the control-plane dirs are treated as ship-moment cards',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: persistDesignScreenshot
+// ---------------------------------------------------------------------------
+
+module('run-log > persistDesignScreenshot', function (hooks) {
+  let workspaceDir: string;
+
+  hooks.beforeEach(async function () {
+    workspaceDir = await makeWorkspace();
+  });
+
+  hooks.afterEach(async function () {
+    await rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  test('copies design/*.png into design-history/ and returns the new path', async function (assert) {
+    await mkdir(join(workspaceDir, 'design'), { recursive: true });
+    await writeFile(
+      join(workspaceDir, 'design', 'garment-isolated.png'),
+      'fake-png-bytes',
+    );
+
+    let result = await persistDesignScreenshot(
+      workspaceDir,
+      'design/garment-isolated.png',
+    );
+
+    assert.strictEqual(
+      result,
+      'design-history/garment-isolated.png',
+      'returns the design-history/ path, not the original design/ path',
+    );
+    let copied = await readFile(
+      join(workspaceDir, 'design-history', 'garment-isolated.png'),
+      'utf8',
+    );
+    assert.strictEqual(
+      copied,
+      'fake-png-bytes',
+      'the copy has the same bytes as the source',
+    );
+  });
+
+  test('also preserves the sibling HTML mockup source in design-history/', async function (assert) {
+    await mkdir(join(workspaceDir, 'design'), { recursive: true });
+    await writeFile(join(workspaceDir, 'design', 'garment-v2.png'), 'png');
+    await writeFile(
+      join(workspaceDir, 'design', 'garment-v2.html'),
+      '<html>the editable mockup</html>',
+    );
+
+    await persistDesignScreenshot(workspaceDir, 'design/garment-v2.png');
+
+    let html = await readFile(
+      join(workspaceDir, 'design-history', 'garment-v2.html'),
+      'utf8',
+    );
+    assert.strictEqual(
+      html,
+      '<html>the editable mockup</html>',
+      'the HTML source is archived alongside the PNG so agent cleanup cannot throw it away',
+    );
+  });
+
+  test('tolerates a PNG with no sibling HTML (render-gate capture)', async function (assert) {
+    await mkdir(join(workspaceDir, 'design', 'render'), { recursive: true });
+    await writeFile(
+      join(workspaceDir, 'design', 'render', 'Garment-x-embedded.png'),
+      'png',
+    );
+
+    // Must not throw when there is no matching .html.
+    let result = await persistDesignScreenshot(
+      workspaceDir,
+      'design/render/Garment-x-embedded.png',
+    );
+    assert.strictEqual(result, 'design-history/render/Garment-x-embedded.png');
+  });
+
+  test('a later deletion of design/ does not remove the design-history/ copy', async function (assert) {
+    await mkdir(join(workspaceDir, 'design'), { recursive: true });
+    await writeFile(
+      join(workspaceDir, 'design', 'garment-isolated.png'),
+      'fake-png-bytes',
+    );
+
+    await persistDesignScreenshot(workspaceDir, 'design/garment-isolated.png');
+
+    // Simulate a later BUILD-turn cleanup of the design/ scratch dir — the
+    // exact behavior that orphaned run-log links in production.
+    await rm(join(workspaceDir, 'design'), { recursive: true, force: true });
+
+    let historyStat = await stat(
+      join(workspaceDir, 'design-history', 'garment-isolated.png'),
+    );
+    assert.ok(
+      historyStat.isFile(),
+      'design-history/ copy survives design/ being deleted',
+    );
+  });
+
+  test('falls back to the original path when the source file is missing', async function (assert) {
+    let result = await persistDesignScreenshot(
+      workspaceDir,
+      'design/does-not-exist.png',
+    );
+
+    assert.strictEqual(
+      result,
+      'design/does-not-exist.png',
+      'best-effort fallback: never throws, just links the original path',
+    );
+  });
+
+  test('supports render-gate paths under design/render/, preserving the subdirectory', async function (assert) {
+    await mkdir(join(workspaceDir, 'design', 'render'), { recursive: true });
+    await writeFile(
+      join(workspaceDir, 'design', 'render', 'Garment-tee-isolated.png'),
+      'fake-render-bytes',
+    );
+
+    let result = await persistDesignScreenshot(
+      workspaceDir,
+      'design/render/Garment-tee-isolated.png',
+    );
+
+    assert.strictEqual(
+      result,
+      'design-history/render/Garment-tee-isolated.png',
+    );
+  });
+
+  test('does not let two different design/ subpaths with the same basename collide', async function (assert) {
+    await mkdir(join(workspaceDir, 'design', 'render'), { recursive: true });
+    await writeFile(join(workspaceDir, 'design', 'isolated.png'), 'root-bytes');
+    await writeFile(
+      join(workspaceDir, 'design', 'render', 'isolated.png'),
+      'render-bytes',
+    );
+
+    let rootResult = await persistDesignScreenshot(
+      workspaceDir,
+      'design/isolated.png',
+    );
+    let renderResult = await persistDesignScreenshot(
+      workspaceDir,
+      'design/render/isolated.png',
+    );
+
+    assert.notStrictEqual(
+      rootResult,
+      renderResult,
+      'two same-basename screenshots in different design/ subdirectories must not collapse to the same design-history/ path',
+    );
+    assert.strictEqual(
+      await readFile(join(workspaceDir, rootResult), 'utf8'),
+      'root-bytes',
+      'the first copy is not silently overwritten by the second',
+    );
+    assert.strictEqual(
+      await readFile(join(workspaceDir, renderResult), 'utf8'),
+      'render-bytes',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: summarizeCheckFailure
+// ---------------------------------------------------------------------------
+
+module('run-log > summarizeCheckFailure', function () {
+  test('summarizes run_lint violations', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'failed',
+      violations: [{ file: 'garment.gts', message: "Expected ';'" }],
+    });
+
+    assert.strictEqual(body, "garment.gts: Expected ';'");
+  });
+
+  test('summarizes run_parse errors', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'failed',
+      errors: [{ file: 'garment.gts', message: 'Unexpected token' }],
+    });
+
+    assert.strictEqual(body, 'garment.gts: Unexpected token');
+  });
+
+  test('summarizes run_evaluate/run_instantiate failures (path + error)', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'failed',
+      failures: [{ path: 'garment.gts', error: 'Cannot find module ./base' }],
+    });
+
+    assert.strictEqual(body, 'garment.gts: Cannot find module ./base');
+  });
+
+  test('falls back to cardName when a bare-instantiation failure has no path', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'failed',
+      failures: [
+        { path: '', cardName: 'Garment', error: 'instantiation failed' },
+      ],
+    });
+
+    assert.strictEqual(body, 'Garment: instantiation failed');
+  });
+
+  test('caps the summary at 3 items and notes how many more', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'failed',
+      violations: [
+        { file: 'a.gts', message: 'e1' },
+        { file: 'b.gts', message: 'e2' },
+        { file: 'c.gts', message: 'e3' },
+        { file: 'd.gts', message: 'e4' },
+        { file: 'e.gts', message: 'e5' },
+      ],
+    });
+
+    assert.strictEqual(body, 'a.gts: e1\nb.gts: e2\nc.gts: e3 (+2 more)');
+  });
+
+  test('falls back to errorMessage when there is no violations/errors/failures list', function (assert) {
+    let body = summarizeCheckFailure({
+      status: 'error',
+      errorMessage: 'sync failed before lint could run',
+    });
+
+    assert.strictEqual(body, 'sync failed before lint could run');
+  });
+
+  test('returns undefined for a passing or empty result', function (assert) {
+    assert.strictEqual(summarizeCheckFailure({ status: 'passed' }), undefined);
+    assert.strictEqual(summarizeCheckFailure(null), undefined);
+    assert.strictEqual(summarizeCheckFailure(undefined), undefined);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: RunLogWriter (Posts + live-query model)
+// ---------------------------------------------------------------------------
+
+module('run-log > RunLogWriter', function (hooks) {
+  let workspaceDir: string;
+
+  hooks.beforeEach(async function () {
+    workspaceDir = await makeWorkspace();
+  });
+  hooks.afterEach(async function () {
+    await rm(workspaceDir, { recursive: true, force: true });
+  });
+
+  function makeWriter() {
+    let syncs = 0;
+    let writer = new RunLogWriter({
+      workspaceDir,
+      targetRealm: 'https://realm.test/product/',
+      controlRealm: 'https://realm.test/control/',
+      runSlug: 'wardrobe',
+      runTitle: 'Wardrobe',
+      syncWorkspace: async () => {
+        syncs++;
+        return { ok: true };
+      },
+    });
+    return { writer, syncCount: () => syncs };
+  }
+
+  async function readJson(rel: string) {
+    return JSON.parse(await readFile(join(workspaceDir, rel), 'utf8'));
+  }
+  async function listEntries(): Promise<string[]> {
+    try {
+      let { readdir } = await import('node:fs/promises');
+      return (await readdir(join(workspaceDir, 'RunLogEntries'))).sort();
+    } catch {
+      return [];
+    }
+  }
+
+  test('each append writes ONE new entry card — never rewrites prior entries', async function (assert) {
+    let { writer } = makeWriter();
+    await writer.start(); // creates index + "Run started" entry (seq 1)
+    await writer.append([
+      { kind: 'design', headline: 'Design round: garment' },
+    ]);
+
+    let entries = await listEntries();
+    assert.deepEqual(
+      entries,
+      ['wardrobe-000001.json', 'wardrobe-000002.json'],
+      'two discrete entry cards exist, one per append — no growing array',
+    );
+
+    // The first entry is byte-stable after the second append landed: appends
+    // never rewrite earlier entry files (the whole point of the refactor).
+    let first = await readJson('RunLogEntries/wardrobe-000001.json');
+    assert.strictEqual(first.data.attributes.seq, 1);
+    assert.strictEqual(first.data.attributes.runId, 'wardrobe');
+    assert.strictEqual(
+      first.data.meta.adoptsFrom.name,
+      'RunLogEntry',
+      'entries adopt the RunLogEntry CardDef',
+    );
+    assert.ok(first.data.attributes.postedAt, 'entry carries postedAt');
+  });
+
+  test('milestone counters accumulate on the small index card', async function (assert) {
+    let { writer } = makeWriter();
+    await writer.start();
+    await writer.append([{ kind: 'design', headline: 'd1' }]);
+    await writer.append([{ kind: 'design', headline: 'd2' }]);
+    await writer.append([{ kind: 'validation', headline: 'lint passed' }]);
+    await writer.append([{ kind: 'validation', headline: 'parse failed' }]);
+    await writer.append([{ kind: 'card-ready', headline: 'Garment shipped' }]);
+    await writer.append([{ kind: 'issue-done', headline: 'WR-3 done' }]);
+
+    let index = await readJson('Runs/wardrobe.json');
+    let a = index.data.attributes;
+    assert.strictEqual(a.designRoundsCount, 2, 'two design rounds counted');
+    assert.strictEqual(
+      a.validationsGreenCount,
+      1,
+      'only the passing validation counts as green',
+    );
+    assert.strictEqual(a.cardsReadyCount, 1, 'one card ready');
+    assert.strictEqual(a.issuesDoneCount, 1, 'one issue done');
+    assert.strictEqual(
+      a.runId,
+      'wardrobe',
+      'index card carries runId for the feed query',
+    );
+    assert.notOk(
+      'entries' in a,
+      'the index card has NO containsMany entries array',
+    );
+  });
+
+  test('buildLegacyMigration converts a containsMany index into entry cards', function (assert) {
+    let legacy = {
+      data: {
+        type: 'card',
+        attributes: {
+          runTitle: 'Port: Wardrobe',
+          status: 'running',
+          nowWorkingOn: 'Building',
+          startedAt: '2026-07-17T12:00:00.000Z',
+          cardInfo: { name: 'Run log — Port: Wardrobe' },
+          entries: [
+            {
+              kind: 'phase',
+              at: '2026-07-17T12:00:00.000Z',
+              headline: 'Run started',
+            },
+            {
+              kind: 'design',
+              at: '2026-07-17T12:02:00.000Z',
+              headline: 'Design round: garment',
+              body: 'crit pass',
+              who: 'executor',
+            },
+            {
+              kind: 'validation',
+              at: '2026-07-17T12:03:00.000Z',
+              headline: 'lint passed',
+            },
+            {
+              kind: 'validation',
+              at: '2026-07-17T12:04:00.000Z',
+              headline: 'parse failed',
+            },
+            {
+              kind: 'card-ready',
+              at: '2026-07-17T12:05:00.000Z',
+              headline: 'Garment shipped',
+            },
+          ],
+        },
+        relationships: {
+          'entries.4.card': {
+            links: { self: 'https://realm.test/product/Garment/red-jacket' },
+          },
+        },
+      },
+    };
+    let plan = buildLegacyMigration(legacy, 'wardrobe');
+    assert.ok(plan, 'legacy doc produces a migration plan');
+    assert.strictEqual(plan!.entries.length, 5, 'one card per legacy entry');
+    assert.strictEqual(plan!.seq, 5, 'seq continues from the migrated tail');
+    assert.strictEqual(
+      plan!.entries[0].relPath,
+      'RunLogEntries/wardrobe-000001.json',
+    );
+
+    let e2: any = plan!.entries[1].doc;
+    assert.strictEqual(e2.data.attributes.seq, 2);
+    assert.strictEqual(
+      e2.data.attributes.postedAt,
+      '2026-07-17T12:02:00.000Z',
+      'at → postedAt',
+    );
+    assert.strictEqual(e2.data.attributes.who, 'executor');
+    assert.strictEqual(e2.data.meta.adoptsFrom.name, 'RunLogEntry');
+
+    let e5: any = plan!.entries[4].doc;
+    assert.strictEqual(
+      e5.data.relationships.card.links.self,
+      'https://realm.test/product/Garment/red-jacket',
+      'the entries.4.card link is carried onto the 5th entry card',
+    );
+
+    let idx: any = plan!.index;
+    assert.strictEqual(idx.data.attributes.designRoundsCount, 1);
+    assert.strictEqual(
+      idx.data.attributes.validationsGreenCount,
+      1,
+      'only the passing validation is green',
+    );
+    assert.strictEqual(idx.data.attributes.cardsReadyCount, 1);
+    assert.strictEqual(idx.data.attributes.entryCount, 5);
+    assert.strictEqual(idx.data.attributes.runId, 'wardrobe');
+    assert.notOk(
+      'entries' in idx.data.attributes,
+      'the rewritten index drops the containsMany array',
+    );
+    assert.deepEqual(
+      idx.data.relationships,
+      {},
+      'legacy entries.N.* relationships are dropped from the index',
+    );
+  });
+
+  test('buildLegacyMigration drops status/iteration churn but counts them for totals', function (assert) {
+    let entries = [];
+    // 3 real design rounds interleaved with lots of status churn.
+    for (let i = 0; i < 3; i++) {
+      entries.push({
+        kind: 'status',
+        at: '2026-07-17T12:00:00.000Z',
+        headline: 'Issue status: backlog → in progress',
+      });
+      entries.push({
+        kind: 'iteration',
+        at: '2026-07-17T12:00:00.000Z',
+        headline: 'Inner iteration 1/8',
+      });
+      entries.push({
+        kind: 'design',
+        at: '2026-07-17T12:00:00.000Z',
+        headline: 'Design round ' + i,
+      });
+    }
+    let plan = buildLegacyMigration(
+      { data: { attributes: { runTitle: 'X', entries }, relationships: {} } },
+      'wardrobe',
+    )!;
+    // 9 legacy entries → only the 3 design entries survive as cards.
+    assert.strictEqual(
+      plan.entries.length,
+      3,
+      'status + iteration churn dropped',
+    );
+    assert.ok(
+      plan.entries.every((e: any) => e.doc.data.attributes.kind === 'design'),
+      'only meaningful kinds become cards',
+    );
+    assert.strictEqual(
+      (plan.index as any).data.attributes.designRoundsCount,
+      3,
+      'counter still reflects all 3 rounds',
+    );
+  });
+
+  test('buildLegacyMigration caps the carried tail to the recent window', function (assert) {
+    let entries = [];
+    for (let i = 0; i < 200; i++) {
+      entries.push({
+        kind: 'comment',
+        at: '2026-07-17T12:00:00.000Z',
+        headline: 'note ' + i,
+      });
+    }
+    let plan = buildLegacyMigration(
+      { data: { attributes: { entries }, relationships: {} } },
+      'wardrobe',
+    )!;
+    assert.ok(plan.entries.length <= 60, 'carried tail is capped (<=60)');
+    // The kept entries are the MOST RECENT ones.
+    let last: any = plan.entries[plan.entries.length - 1].doc;
+    assert.strictEqual(
+      last.data.attributes.headline,
+      'note 199',
+      'newest entry is kept',
+    );
+  });
+
+  test('buildLegacyMigration returns null for an already-migrated index', function (assert) {
+    let modern = {
+      data: { type: 'card', attributes: { runId: 'wardrobe', entryCount: 3 } },
+    };
+    assert.strictEqual(buildLegacyMigration(modern, 'wardrobe'), null);
+  });
+
+  test('a card-path entry links the live card by absolute URL', async function (assert) {
+    let { writer } = makeWriter();
+    await writer.start();
+    await writer.append([
+      {
+        kind: 'card-ready',
+        headline: 'Garment shipped',
+        cardPath: 'Garment/red-jacket',
+      },
+    ]);
+    let entry = await readJson('RunLogEntries/wardrobe-000002.json');
+    assert.strictEqual(
+      entry.data.relationships.card.links.self,
+      'https://realm.test/product/Garment/red-jacket',
+      'ship-moment card linked absolutely against the product realm',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// autolinkCardReferences — card paths in prose become :card[URL] directives
+// ---------------------------------------------------------------------------
+
+module('run-log > autolinkCardReferences', function () {
+  test('routes a control-plane card ref to the control realm', function (assert) {
+    let out = autolinkCardReferences(
+      'Wrote `Knowledge Articles/port-background.json`. 12 screens.',
+      { controlRealm: CONTROL, productRealm: PRODUCT },
+    );
+    assert.strictEqual(
+      out,
+      `Wrote :card[${CONTROL}Knowledge%20Articles/port-background]. 12 screens.`,
+      'backticks consumed, space encoded, control realm base',
+    );
+  });
+
+  test('routes a product card ref to the product realm', function (assert) {
+    let out = autolinkCardReferences(
+      'Shipped Garment/orange-football-kit.json today.',
+      {
+        controlRealm: CONTROL,
+        productRealm: PRODUCT,
+      },
+    );
+    assert.strictEqual(
+      out,
+      `Shipped :card[${PRODUCT}Garment/orange-football-kit] today.`,
+      'bare ref (no backticks) linked against product realm',
+    );
+  });
+
+  test('links Specs against the product realm', function (assert) {
+    let out = autolinkCardReferences('See `Spec/Garment.json`.', {
+      controlRealm: CONTROL,
+      productRealm: PRODUCT,
+    });
+    assert.strictEqual(out, `See :card[${PRODUCT}Spec/Garment].`);
+  });
+
+  test('leaves non-card and lowercase paths untouched', function (assert) {
+    let body =
+      'Tokens in design/tokens.css and the mockup design/family-sheet.html.';
+    assert.strictEqual(
+      autolinkCardReferences(body, {
+        controlRealm: CONTROL,
+        productRealm: PRODUCT,
+      }),
+      body,
+      'no .json card dirs → unchanged',
+    );
+  });
+
+  test('does not rewrite references inside fenced code blocks', function (assert) {
+    let body = [
+      'Created `Garment/tee.json`.',
+      '',
+      '```',
+      'boxel file write Garment/tee.json',
+      '```',
+    ].join('\n');
+    let out = autolinkCardReferences(body, {
+      controlRealm: CONTROL,
+      productRealm: PRODUCT,
+    });
+    assert.ok(
+      out.includes(`:card[${PRODUCT}Garment/tee]`),
+      'prose ref outside the fence is linked',
+    );
+    assert.ok(
+      out.includes('boxel file write Garment/tee.json'),
+      'the same path inside the fence stays literal',
+    );
+  });
+
+  test('falls back to the product realm when no control realm is set', function (assert) {
+    let out = autolinkCardReferences('Wrote `Issues/seed.json`.', {
+      productRealm: PRODUCT,
+    });
+    assert.strictEqual(out, `Wrote :card[${PRODUCT}Issues/seed].`);
+  });
+
+  test('links multiple references in one body', function (assert) {
+    let out = autolinkCardReferences(
+      'Linked `Knowledge Articles/brief.json` and Outfit/summer.json.',
+      { controlRealm: CONTROL, productRealm: PRODUCT },
+    );
+    assert.strictEqual(
+      out,
+      `Linked :card[${CONTROL}Knowledge%20Articles/brief] and :card[${PRODUCT}Outfit/summer].`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// autolinkCardReferences — agent-authored BFM directives (path → URL)
+// ---------------------------------------------------------------------------
+
+module('run-log > autolinkCardReferences directives', function () {
+  const realms = { controlRealm: CONTROL, productRealm: PRODUCT };
+
+  test('resolves an inline :card directive path to a full URL', function (assert) {
+    assert.strictEqual(
+      autolinkCardReferences('See :card[Garment/tee.json] here.', realms),
+      `See :card[${PRODUCT}Garment/tee] here.`,
+    );
+  });
+
+  test('resolves a block ::card directive path, no double-processing as inline', function (assert) {
+    assert.strictEqual(
+      autolinkCardReferences('::card[Garment/orange-kit.json]', realms),
+      `::card[${PRODUCT}Garment/orange-kit]`,
+    );
+  });
+
+  test('preserves the format spec on a block directive', function (assert) {
+    assert.strictEqual(
+      autolinkCardReferences(
+        '::card[Knowledge Articles/port-background.json | fitted strip]',
+        realms,
+      ),
+      `::card[${CONTROL}Knowledge%20Articles/port-background | fitted strip]`,
+    );
+  });
+
+  test('resolves a markdown-link path target, keeping the link text', function (assert) {
+    assert.strictEqual(
+      autolinkCardReferences(
+        '[the brief](Knowledge Articles/brief.json)',
+        realms,
+      ),
+      `[the brief](${CONTROL}Knowledge%20Articles/brief)`,
+    );
+  });
+
+  test('leaves a directive that already has a full URL untouched', function (assert) {
+    let body = `Already linked ::card[${PRODUCT}Garment/tee | embedded] fine.`;
+    assert.strictEqual(autolinkCardReferences(body, realms), body);
+  });
+
+  test('mixes an embedded spotlight with inline atoms in one body', function (assert) {
+    let out = autolinkCardReferences(
+      'Shipped ::card[Garment/tee.json | embedded] linked from `Outfit/summer.json`.',
+      realms,
+    );
+    assert.strictEqual(
+      out,
+      `Shipped ::card[${PRODUCT}Garment/tee | embedded] linked from :card[${PRODUCT}Outfit/summer].`,
+    );
+  });
+});
diff --git a/packages/software-factory/tests/run-monitor.test.ts b/packages/software-factory/tests/run-monitor.test.ts
new file mode 100644
index 00000000000..d0143851b02
--- /dev/null
+++ b/packages/software-factory/tests/run-monitor.test.ts
@@ -0,0 +1,135 @@
+import { test, mock } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { RunMonitor } from '../src/run-monitor.ts';
+import type { RunLogWriter, RunLogEntryInput } from '../src/run-log.ts';
+
+function makeRunLogStub(): {
+  runLog: RunLogWriter;
+  entries: RunLogEntryInput[];
+} {
+  let entries: RunLogEntryInput[] = [];
+  let runLog = {
+    append: async (batch: RunLogEntryInput[]) => {
+      entries.push(...batch);
+    },
+  } as unknown as RunLogWriter;
+  return { runLog, entries };
+}
+
+test('endTurn posts telemetry with budget, stats, and usage', async () => {
+  let { runLog, entries } = makeRunLogStub();
+  let monitor = new RunMonitor({ runLog, level: 'normal' });
+
+  monitor.beginTurn({
+    issueTitle: 'Garment card',
+    turnType: 'build',
+    iteration: 1,
+    maxIterations: 8,
+    model: 'claude-sonnet-5',
+    effort: 'medium',
+  });
+  monitor.noteToolEvent({ tool: 'Write', args: { file_path: 'garment.gts' } });
+  monitor.noteToolEvent({
+    tool: 'mcp__factory__run_lint',
+    args: { path: 'garment.gts' },
+  });
+  monitor.endTurn({
+    status: 'done',
+    durationMs: 272_000,
+    usage: { inputTokens: 42_000, outputTokens: 9_100, costUsd: 1.23 },
+  });
+  // append is fire-and-forget inside the monitor; let it settle.
+  await new Promise((r) => setImmediate(r));
+
+  assert.equal(entries.length, 1);
+  let entry = entries[0];
+  assert.equal(entry.kind, 'telemetry');
+  assert.equal(entry.who, 'orchestrator');
+  assert.match(entry.headline, /finished in 4m 32s/);
+  assert.match(entry.headline, /2 tool events/);
+  assert.match(entry.body ?? '', /claude-sonnet-5 @ medium/);
+  assert.match(entry.body ?? '', /1 file touched/);
+  assert.match(entry.body ?? '', /42k in \/ 9k out/);
+  assert.match(entry.body ?? '', /\$1\.23/);
+});
+
+test('quiet level suppresses telemetry and scheduler notes', async () => {
+  let { runLog, entries } = makeRunLogStub();
+  let monitor = new RunMonitor({ runLog, level: 'quiet' });
+
+  monitor.beginTurn({ issueTitle: 'x', turnType: 'build' });
+  monitor.endTurn({ status: 'done', durationMs: 1000 });
+  monitor.noteScheduler('Queue: picked "x"');
+  await new Promise((r) => setImmediate(r));
+
+  assert.equal(entries.length, 0);
+});
+
+test('stall check posts after the silence threshold, then respects the repeat gap', async () => {
+  let { runLog, entries } = makeRunLogStub();
+  mock.timers.enable({ apis: ['setInterval', 'Date'] });
+  try {
+    let monitor = new RunMonitor({
+      runLog,
+      level: 'normal',
+      stallAfterMs: 90_000,
+      stallRepeatMs: 240_000,
+      checkIntervalMs: 15_000,
+    });
+    monitor.start();
+    monitor.beginTurn({ issueTitle: 'Garment card', turnType: 'build' });
+    monitor.noteToolEvent({
+      tool: 'Write',
+      args: { file_path: 'garment.gts' },
+    });
+
+    // 60s of silence — under the threshold, nothing posts.
+    mock.timers.tick(60_000);
+    await new Promise((r) => setImmediate(r));
+    assert.equal(entries.length, 0);
+
+    // Cross 90s — one stall post.
+    mock.timers.tick(45_000);
+    await new Promise((r) => setImmediate(r));
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].kind, 'monitor');
+    assert.match(entries[0].headline, /Still working/);
+    assert.match(entries[0].body ?? '', /Write garment\.gts/);
+
+    // Another 60s of continued silence — inside the repeat gap, no new post.
+    mock.timers.tick(60_000);
+    await new Promise((r) => setImmediate(r));
+    assert.equal(entries.length, 1);
+
+    // Past the 4-minute repeat gap — a second stall post.
+    mock.timers.tick(200_000);
+    await new Promise((r) => setImmediate(r));
+    assert.equal(entries.length, 2);
+
+    // Activity resets the clock; no further posts inside the threshold.
+    monitor.noteActivity('tool_use(Write)');
+    mock.timers.tick(60_000);
+    await new Promise((r) => setImmediate(r));
+    assert.equal(entries.length, 2);
+
+    monitor.stop();
+  } finally {
+    mock.timers.reset();
+  }
+});
+
+test('watchdog failures post at normal level and rate-limit per class', async () => {
+  let { runLog, entries } = makeRunLogStub();
+  let monitor = new RunMonitor({ runLog, level: 'normal' });
+
+  monitor.noteWatchdog('sync-failed', 'sync failed', { failure: true });
+  monitor.noteWatchdog('sync-failed', 'sync failed again', { failure: true });
+  // Non-failure watchdog events (heals) stay off the log at normal level.
+  monitor.noteWatchdog('heal', 'healed run log');
+  await new Promise((r) => setImmediate(r));
+
+  assert.equal(entries.length, 1);
+  assert.equal(entries[0].kind, 'blocked');
+  assert.equal(entries[0].headline, 'sync failed');
+});
diff --git a/packages/software-factory/tests/run-trace.test.ts b/packages/software-factory/tests/run-trace.test.ts
new file mode 100644
index 00000000000..7d1547ded05
--- /dev/null
+++ b/packages/software-factory/tests/run-trace.test.ts
@@ -0,0 +1,114 @@
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import {
+  initRunTrace,
+  resetRunTraceForTesting,
+  startSpan,
+  traceEvent,
+  withSpan,
+} from '../src/run-trace.ts';
+
+function readTraceLines(workspaceDir: string): Record<string, unknown>[] {
+  let traceDir = join(workspaceDir, '.factory-trace');
+  let files = readdirSync(traceDir).filter((f) => f.endsWith('.ndjson'));
+  if (files.length !== 1) {
+    throw new Error(`expected exactly one trace file, found ${files.length}`);
+  }
+  return readFileSync(join(traceDir, files[0]), 'utf8')
+    .trim()
+    .split('\n')
+    .map((line) => JSON.parse(line));
+}
+
+module('run-trace', function (hooks) {
+  let workspaceDir: string;
+
+  hooks.beforeEach(function () {
+    resetRunTraceForTesting();
+    workspaceDir = mkdtempSync(join(tmpdir(), 'run-trace-test-'));
+  });
+
+  hooks.afterEach(function () {
+    resetRunTraceForTesting();
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  test('header line carries schema version and run tags', function (assert) {
+    initRunTrace({ workspaceDir, tags: { targetRealm: 'https://r/' } });
+    let [header] = readTraceLines(workspaceDir);
+    assert.strictEqual(header.v, 1);
+    assert.strictEqual(header.c, 'run');
+    assert.strictEqual(header.n, 'meta');
+    assert.strictEqual(header.targetRealm, 'https://r/');
+    assert.strictEqual(typeof header.t, 'number');
+  });
+
+  test('spans buffered before init flush after the header', function (assert) {
+    let end = startSpan('startup', 'load-brief');
+    end();
+    traceEvent('scheduler', 'pre-init-event');
+    initRunTrace({ workspaceDir });
+    let lines = readTraceLines(workspaceDir);
+    assert.strictEqual(lines.length, 3);
+    assert.strictEqual(lines[0].n, 'meta');
+    assert.strictEqual(lines[1].n, 'load-brief');
+    assert.strictEqual(lines[2].n, 'pre-init-event');
+  });
+
+  test('span lines have start, duration, category, name, and tags', function (assert) {
+    initRunTrace({ workspaceDir });
+    let end = startSpan('inference', 'design', { issue: 'sn-1', iteration: 1 });
+    end({ status: 'done', toolCalls: 7 });
+    let lines = readTraceLines(workspaceDir);
+    let span = lines[1];
+    assert.strictEqual(span.c, 'inference');
+    assert.strictEqual(span.n, 'design');
+    assert.strictEqual(span.issue, 'sn-1');
+    assert.strictEqual(span.iteration, 1);
+    assert.strictEqual(span.status, 'done');
+    assert.strictEqual(span.toolCalls, 7);
+    assert.strictEqual(typeof span.t, 'number');
+    assert.strictEqual(typeof span.d, 'number');
+  });
+
+  test('instant events have no duration; undefined tags are dropped', function (assert) {
+    initRunTrace({ workspaceDir });
+    traceEvent('scheduler', 'skip-stale-done', {
+      issue: 'sn-1',
+      cycle: undefined,
+    });
+    let lines = readTraceLines(workspaceDir);
+    let event = lines[1];
+    assert.false('d' in event);
+    assert.false('cycle' in event);
+    assert.strictEqual(event.issue, 'sn-1');
+  });
+
+  test('closing a span twice writes exactly one line', function (assert) {
+    initRunTrace({ workspaceDir });
+    let end = startSpan('sync', 'workspace');
+    end({ ok: true });
+    end({ ok: false });
+    let lines = readTraceLines(workspaceDir);
+    assert.strictEqual(lines.length, 2);
+    assert.true(lines[1].ok);
+  });
+
+  test('withSpan closes on throw and tags the error', async function (assert) {
+    initRunTrace({ workspaceDir });
+    await assert.rejects(
+      withSpan('validation', 'pipeline', undefined, async () => {
+        throw new Error('boom');
+      }),
+      /boom/,
+    );
+    let lines = readTraceLines(workspaceDir);
+    assert.strictEqual(lines[1].n, 'pipeline');
+    assert.true(lines[1].error);
+  });
+});
diff --git a/packages/software-factory/tests/transient-agent-error.test.ts b/packages/software-factory/tests/transient-agent-error.test.ts
new file mode 100644
index 00000000000..527f895845f
--- /dev/null
+++ b/packages/software-factory/tests/transient-agent-error.test.ts
@@ -0,0 +1,135 @@
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import {
+  isTransientAgentError,
+  retryTransientAgentError,
+} from '../src/transient-agent-error.ts';
+
+module('transient-agent-error > isTransientAgentError', function () {
+  test('matches the observed SDK stream idle timeout', function (assert) {
+    assert.ok(
+      isTransientAgentError(
+        new Error('API Error: Stream idle timeout - partial response received'),
+      ),
+    );
+  });
+
+  test('matches common network fault messages', function (assert) {
+    assert.ok(isTransientAgentError(new Error('connect ECONNRESET')));
+    assert.ok(isTransientAgentError(new Error('fetch failed')));
+    assert.ok(isTransientAgentError(new Error('socket hang up')));
+  });
+
+  test('does not match real agent/tool errors', function (assert) {
+    assert.notOk(
+      isTransientAgentError(new Error('Issue "x" has no linked project')),
+    );
+    assert.notOk(isTransientAgentError(new Error('Unexpected token')));
+  });
+
+  test('handles non-Error throws without crashing', function (assert) {
+    assert.notOk(isTransientAgentError('a plain string'));
+    assert.notOk(isTransientAgentError(undefined));
+  });
+});
+
+module('transient-agent-error > retryTransientAgentError', function () {
+  test('returns the result on first success without retrying', async function (assert) {
+    let calls = 0;
+    let result = await retryTransientAgentError(
+      async () => {
+        calls++;
+        return 'ok';
+      },
+      undefined,
+      { sleep: async () => {} },
+    );
+
+    assert.strictEqual(result, 'ok');
+    assert.strictEqual(calls, 1);
+  });
+
+  test('retries a transient error and succeeds on a later attempt', async function (assert) {
+    let calls = 0;
+    let retryLog: number[] = [];
+    let result = await retryTransientAgentError(
+      async () => {
+        calls++;
+        if (calls < 3) throw new Error('Stream idle timeout');
+        return 'recovered';
+      },
+      (attempt) => retryLog.push(attempt),
+      { sleep: async () => {} },
+    );
+
+    assert.strictEqual(result, 'recovered');
+    assert.strictEqual(calls, 3);
+    assert.deepEqual(
+      retryLog,
+      [1, 2],
+      'onRetry fired once per retry, in order',
+    );
+  });
+
+  test('rethrows immediately on a non-transient error without retrying', async function (assert) {
+    let calls = 0;
+    await assert.rejects(
+      retryTransientAgentError(
+        async () => {
+          calls++;
+          throw new Error('Issue has no linked project');
+        },
+        undefined,
+        { sleep: async () => {} },
+      ),
+      /no linked project/,
+    );
+    assert.strictEqual(
+      calls,
+      1,
+      'no retry attempted for a non-transient error',
+    );
+  });
+
+  test('gives up and rethrows after exhausting maxRetries', async function (assert) {
+    let calls = 0;
+    await assert.rejects(
+      retryTransientAgentError(
+        async () => {
+          calls++;
+          throw new Error('fetch failed');
+        },
+        undefined,
+        { sleep: async () => {}, maxRetries: 2 },
+      ),
+      /fetch failed/,
+    );
+    assert.strictEqual(calls, 3, 'initial attempt + 2 retries, then give up');
+  });
+
+  test('backs off exponentially between retries', async function (assert) {
+    let delays: number[] = [];
+    let calls = 0;
+    await retryTransientAgentError(
+      async () => {
+        calls++;
+        if (calls < 3) throw new Error('ECONNRESET');
+        return 'ok';
+      },
+      undefined,
+      {
+        baseDelayMs: 100,
+        sleep: async (ms) => {
+          delays.push(ms);
+        },
+      },
+    );
+
+    assert.deepEqual(
+      delays,
+      [100, 200],
+      'delay doubles each retry from the base',
+    );
+  });
+});
diff --git a/packages/software-factory/tests/validation-run-cache.test.ts b/packages/software-factory/tests/validation-run-cache.test.ts
index 0c9e6d59779..b156c6b5639 100644
--- a/packages/software-factory/tests/validation-run-cache.test.ts
+++ b/packages/software-factory/tests/validation-run-cache.test.ts
@@ -1,4 +1,11 @@
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import {
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+  mkdirSync,
+  readFileSync,
+  utimesSync,
+} from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
@@ -49,6 +56,31 @@ module('validation-run-cache', function (hooks) {
       assert.notStrictEqual(a, c, 'edited file → different fingerprint');
     });
 
+    test('is stable when a pull rewrites identical content with a fresh mtime', async function (assert) {
+      let a = await computeWorkspaceFingerprint(workspaceDir);
+      // Simulate a bidirectional sync's pull: same bytes, new mtime/ctime.
+      let target = join(workspaceDir, 'card.gts');
+      let bytes = readFileSync(target);
+      let future = new Date(Date.now() + 60_000);
+      writeFileSync(target, bytes);
+      utimesSync(target, future, future);
+      let b = await computeWorkspaceFingerprint(workspaceDir);
+      assert.strictEqual(
+        a,
+        b,
+        'identical content rewritten with a new mtime → same fingerprint',
+      );
+
+      // A real content edit at the same size still changes the fingerprint.
+      writeFileSync(target, Buffer.alloc(bytes.length, 0x59));
+      let c = await computeWorkspaceFingerprint(workspaceDir);
+      assert.notStrictEqual(
+        a,
+        c,
+        'same-size content edit → different fingerprint',
+      );
+    });
+
     test('ignores sync bookkeeping (.boxel-history, .boxel-sync.json)', async function (assert) {
       let a = await computeWorkspaceFingerprint(workspaceDir);
       mkdirSync(join(workspaceDir, '.boxel-history'));
diff --git a/packages/software-factory/tests/workspace-skills.test.ts b/packages/software-factory/tests/workspace-skills.test.ts
new file mode 100644
index 00000000000..4ac79e04ec8
--- /dev/null
+++ b/packages/software-factory/tests/workspace-skills.test.ts
@@ -0,0 +1,202 @@
+import QUnit from 'qunit';
+const { module, test } = QUnit;
+
+import {
+  mkdtemp,
+  mkdir,
+  writeFile,
+  readFile,
+  rm,
+  readdir,
+} from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  materializeWorkspaceSkills,
+  materializeWorkspaceClaudeMd,
+} from '../src/workspace-skills.ts';
+
+module('workspace-skills > materializeWorkspaceSkills', function (hooks) {
+  let workspaceDir: string;
+  let catalogA: string;
+  let catalogB: string;
+
+  hooks.beforeEach(async function () {
+    workspaceDir = await mkdtemp(join(tmpdir(), 'ws-skills-test-ws-'));
+    catalogA = await mkdtemp(join(tmpdir(), 'ws-skills-test-a-'));
+    catalogB = await mkdtemp(join(tmpdir(), 'ws-skills-test-b-'));
+  });
+
+  hooks.afterEach(async function () {
+    for (let d of [workspaceDir, catalogA, catalogB]) {
+      await rm(d, { recursive: true, force: true });
+    }
+  });
+
+  async function makeSkill(
+    root: string,
+    name: string,
+    body: string,
+    refs?: Record<string, string>,
+  ): Promise<void> {
+    await mkdir(join(root, name, 'references'), { recursive: true });
+    await writeFile(join(root, name, 'SKILL.md'), body);
+    for (let [ref, content] of Object.entries(refs ?? {})) {
+      await writeFile(join(root, name, 'references', ref), content);
+    }
+  }
+
+  test('copies skills with SKILL.md and references into .claude/skills', async function (assert) {
+    await makeSkill(catalogA, 'boxel-development', '# dev skill', {
+      'dev-fitted-formats.md': '# fitted standard',
+    });
+
+    let count = await materializeWorkspaceSkills(workspaceDir, [catalogA]);
+
+    assert.strictEqual(count, 1);
+    assert.strictEqual(
+      await readFile(
+        join(
+          workspaceDir,
+          '.claude',
+          'skills',
+          'boxel-development',
+          'SKILL.md',
+        ),
+        'utf8',
+      ),
+      '# dev skill',
+    );
+    assert.strictEqual(
+      await readFile(
+        join(
+          workspaceDir,
+          '.claude',
+          'skills',
+          'boxel-development',
+          'references',
+          'dev-fitted-formats.md',
+        ),
+        'utf8',
+      ),
+      '# fitted standard',
+      'reference docs come along — greppable in the workspace',
+    );
+  });
+
+  test('earlier catalog dirs win on name collision (loader precedence)', async function (assert) {
+    await makeSkill(catalogA, 'shared-skill', '# primary version');
+    await makeSkill(catalogB, 'shared-skill', '# fallback version');
+
+    await materializeWorkspaceSkills(workspaceDir, [catalogA, catalogB]);
+
+    assert.strictEqual(
+      await readFile(
+        join(workspaceDir, '.claude', 'skills', 'shared-skill', 'SKILL.md'),
+        'utf8',
+      ),
+      '# primary version',
+    );
+  });
+
+  test('skips directories without a SKILL.md', async function (assert) {
+    await mkdir(join(catalogA, 'not-a-skill'), { recursive: true });
+    await writeFile(join(catalogA, 'not-a-skill', 'notes.txt'), 'x');
+    await makeSkill(catalogA, 'real-skill', '# real');
+
+    let count = await materializeWorkspaceSkills(workspaceDir, [catalogA]);
+
+    assert.strictEqual(count, 1);
+    let names = await readdir(join(workspaceDir, '.claude', 'skills'));
+    assert.deepEqual(names.sort(), ['real-skill']);
+  });
+
+  test('is idempotent and refreshes content on re-run', async function (assert) {
+    await makeSkill(catalogA, 'a-skill', '# v1');
+    await materializeWorkspaceSkills(workspaceDir, [catalogA]);
+    await writeFile(join(catalogA, 'a-skill', 'SKILL.md'), '# v2');
+
+    let count = await materializeWorkspaceSkills(workspaceDir, [catalogA]);
+
+    assert.strictEqual(count, 1);
+    assert.strictEqual(
+      await readFile(
+        join(workspaceDir, '.claude', 'skills', 'a-skill', 'SKILL.md'),
+        'utf8',
+      ),
+      '# v2',
+    );
+  });
+
+  test('missing catalog dirs are tolerated', async function (assert) {
+    let count = await materializeWorkspaceSkills(workspaceDir, [
+      join(catalogA, 'does-not-exist'),
+    ]);
+
+    assert.strictEqual(count, 0);
+  });
+});
+
+module('workspace-skills > materializeWorkspaceClaudeMd', function (hooks) {
+  let workspaceDir: string;
+  let sourceDir: string;
+
+  hooks.beforeEach(async function () {
+    workspaceDir = await mkdtemp(join(tmpdir(), 'ws-claude-md-test-ws-'));
+    sourceDir = await mkdtemp(join(tmpdir(), 'ws-claude-md-test-src-'));
+  });
+
+  hooks.afterEach(async function () {
+    for (let d of [workspaceDir, sourceDir]) {
+      await rm(d, { recursive: true, force: true });
+    }
+  });
+
+  test('writes CLAUDE.md and a sync-ignore entry', async function (assert) {
+    let src = join(sourceDir, 'workspace-CLAUDE.md');
+    await writeFile(src, '# Boxel conventions');
+
+    let ok = await materializeWorkspaceClaudeMd(workspaceDir, src);
+
+    assert.true(ok);
+    assert.strictEqual(
+      await readFile(join(workspaceDir, 'CLAUDE.md'), 'utf8'),
+      '# Boxel conventions',
+    );
+    let ignore = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+    assert.true(
+      ignore.includes('/CLAUDE.md'),
+      'a root CLAUDE.md would otherwise sync to the product realm',
+    );
+  });
+
+  test('appends to an existing .boxelignore without clobbering, idempotently', async function (assert) {
+    let src = join(sourceDir, 'workspace-CLAUDE.md');
+    await writeFile(src, '# conventions');
+    await writeFile(
+      join(workspaceDir, '.boxelignore'),
+      '# control-plane block\n/Issues/\n',
+    );
+
+    await materializeWorkspaceClaudeMd(workspaceDir, src);
+    await materializeWorkspaceClaudeMd(workspaceDir, src);
+
+    let ignore = await readFile(join(workspaceDir, '.boxelignore'), 'utf8');
+    assert.true(ignore.includes('/Issues/'), 'existing entries preserved');
+    assert.strictEqual(
+      ignore.split('/CLAUDE.md').length - 1,
+      1,
+      'CLAUDE.md entry appended exactly once across repeat runs',
+    );
+  });
+
+  test('missing source template is tolerated', async function (assert) {
+    let ok = await materializeWorkspaceClaudeMd(
+      workspaceDir,
+      join(sourceDir, 'nope.md'),
+    );
+
+    assert.false(ok);
+  });
+});