mercury-agent 0.15.0 → 0.16.1

package/container/Dockerfile

@@ -60,49 +60,47 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.79.6
+RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
 
 WORKDIR /app
 
 COPY container/agent-package.json /app/package.json
 RUN bun install --production
 
-# Patch pi: skip thinkingConfig for Gemma models (Google API rejects thinkingBudget for them,
-# but pi marks gemma-4 as reasoning:true and sends thinkingBudget:0 to disable it)
-RUN node <<'EOF'
-const fs = require('fs'), path = require('path');
-function patch(dir) {
-  try {
-    for (const f of fs.readdirSync(dir)) {
-      const p = path.join(dir, f);
-      try {
-        if (fs.statSync(p).isDirectory()) patch(p);
-        else if (f === 'google.js' && p.includes('@earendil-works/pi-ai')) {
-          let c = fs.readFileSync(p, 'utf8');
-          const noThinking = '&& !model.id.startsWith("gemma")';
-          const p1 = 'if (options.thinking?.enabled && model.reasoning) {';
-          const p2 = 'else if (model.reasoning && options.thinking && !options.thinking.enabled) {';
-          if (!c.includes(noThinking)) {
-            c = c.replace(p1, 'if (options.thinking?.enabled && model.reasoning ' + noThinking + ') {');
-            c = c.replace(p2, 'else if (model.reasoning && options.thinking && !options.thinking.enabled ' + noThinking + ') {');
-            fs.writeFileSync(p, c);
-            console.log('Patched:', p);
-          }
-        }
-      } catch(e) {}
-    }
-  } catch(e) {}
-}
-patch('/home/mercury/.bun');
-patch('/app/node_modules');
-EOF
+# pi >= 0.84 handles Gemma 4's thinking config itself, so the patch that used to
+# live here is gone. It string-replaced two exact lines in pi-ai's
+# dist/providers/google.js to stop `thinkingBudget: 0` being sent to Gemma
+# models, which the Google API rejects. In 0.84 that file moved to
+# dist/api/google-generative-ai.js and gained `isGemma4Model()`, whose
+# `getDisabledThinkingConfig()` returns `{ thinkingLevel: "MINIMAL" }` instead.
+# Neither string the patch matched still exists.
+#
+# Narrower than what it replaces, deliberately and worth knowing: the patch
+# gated on `model.id.startsWith("gemma")` — every Gemma — while `isGemma4Model`
+# is `/gemma-?4/`, so anything else still falls through to `thinkingBudget: 0`.
+# pi's built-in Google catalog only ships gemma-4 ids, so reaching the gap needs
+# a hand-authored models.json entry for e.g. gemma-3 marked `reasoning: true`.
+# If that turns up, fix it upstream rather than reinstating a source patch.
+#
+# Deleted rather than updated for a second reason: the patch swallowed every
+# error (`catch(e) {}`) and only wrote when its marker was absent, so once pi
+# moved the file it silently did nothing while still reading as protection. A
+# no-op that looks like a safeguard is worse than no safeguard. If a future pi
+# regresses here, reinstate it as a build step that FAILS when its pattern does
+# not match.
 
 # Fix ownership of all mercury home dir artifacts before switching user.
-# Placed here — after the last step that writes to /home/mercury (the pi patch),
+# Placed here — after the last step that writes to /home/mercury (the global
+# `bun add -g` above),
 # but before the volatile /app source COPYs below — so this expensive `chown -R`
 # (it walks the whole Chromium + .bun tree) lands in a stable cached layer.
 # Editing source files no longer invalidates it or forces the huge layer re-export.
-RUN chown -R mercury:mercury /home/mercury
+# `mkdir` here rather than leaving it to Docker: the host mounts the global dir
+# into PI_CODING_AGENT_DIR entry by entry, so Docker would create this dir as
+# the mount parent and own it as root — and pi 0.84's credential store writes
+# an empty auth.json on its first *read*, which then fails EACCES and takes
+# every model leg down with it. Folded into the chown so it shares the layer.
+RUN mkdir -p /home/mercury/.pi/agent && chown -R mercury:mercury /home/mercury
 
 COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
 COPY src/agent/model-capabilities-core.ts /app/src/agent/model-capabilities-core.ts

package/container/Dockerfile.base

@@ -42,42 +42,34 @@ RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
 ENV CHROMIUM_FLAGS="--no-sandbox"
 
 # Install CLIs
-RUN bun add -g @earendil-works/pi-coding-agent@~0.79.6
+RUN bun add -g @earendil-works/pi-coding-agent@~0.84.1
 
 WORKDIR /app
 
 COPY container/agent-package.json /app/package.json
 RUN bun install --production
 
-# Patch pi: skip thinkingConfig for Gemma models (Google API rejects thinkingBudget for them,
-# but pi marks gemma-4 as reasoning:true and sends thinkingBudget:0 to disable it)
-RUN node <<'EOF'
-const fs = require('fs'), path = require('path');
-function patch(dir) {
-  try {
-    for (const f of fs.readdirSync(dir)) {
-      const p = path.join(dir, f);
-      try {
-        if (fs.statSync(p).isDirectory()) patch(p);
-        else if (f === 'google.js' && p.includes('@earendil-works/pi-ai')) {
-          let c = fs.readFileSync(p, 'utf8');
-          const noThinking = '&& !model.id.startsWith("gemma")';
-          const p1 = 'if (options.thinking?.enabled && model.reasoning) {';
-          const p2 = 'else if (model.reasoning && options.thinking && !options.thinking.enabled) {';
-          if (!c.includes(noThinking)) {
-            c = c.replace(p1, 'if (options.thinking?.enabled && model.reasoning ' + noThinking + ') {');
-            c = c.replace(p2, 'else if (model.reasoning && options.thinking && !options.thinking.enabled ' + noThinking + ') {');
-            fs.writeFileSync(p, c);
-            console.log('Patched:', p);
-          }
-        }
-      } catch(e) {}
-    }
-  } catch(e) {}
-}
-patch('/home/mercury/.bun');
-patch('/app/node_modules');
-EOF
+# pi >= 0.84 handles Gemma 4's thinking config itself, so the patch that used to
+# live here is gone. It string-replaced two exact lines in pi-ai's
+# dist/providers/google.js to stop `thinkingBudget: 0` being sent to Gemma
+# models, which the Google API rejects. In 0.84 that file moved to
+# dist/api/google-generative-ai.js and gained `isGemma4Model()`, whose
+# `getDisabledThinkingConfig()` returns `{ thinkingLevel: "MINIMAL" }` instead.
+# Neither string the patch matched still exists.
+#
+# Narrower than what it replaces, deliberately and worth knowing: the patch
+# gated on `model.id.startsWith("gemma")` — every Gemma — while `isGemma4Model`
+# is `/gemma-?4/`, so anything else still falls through to `thinkingBudget: 0`.
+# pi's built-in Google catalog only ships gemma-4 ids, so reaching the gap needs
+# a hand-authored models.json entry for e.g. gemma-3 marked `reasoning: true`.
+# If that turns up, fix it upstream rather than reinstating a source patch.
+#
+# Deleted rather than updated for a second reason: the patch swallowed every
+# error (`catch(e) {}`) and only wrote when its marker was absent, so once pi
+# moved the file it silently did nothing while still reading as protection. A
+# no-op that looks like a safeguard is worse than no safeguard. If a future pi
+# regresses here, reinstate it as a build step that FAILS when its pattern does
+# not match.
 
 COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
 COPY src/agent/model-capabilities-core.ts /app/src/agent/model-capabilities-core.ts
@@ -102,7 +94,12 @@ RUN echo '#!/bin/sh\nbun run /app/src/cli/mrctl.ts "$@"' > /usr/local/bin/mrctl
     chmod +x /usr/local/bin/mrctl
 
 # Fix ownership of all mercury home dir artifacts before switching user
-RUN chown -R mercury:mercury /home/mercury
+# `mkdir` here rather than leaving it to Docker: the host mounts the global dir
+# into PI_CODING_AGENT_DIR entry by entry, so Docker would create this dir as
+# the mount parent and own it as root — and pi 0.84's credential store writes
+# an empty auth.json on its first *read*, which then fails EACCES and takes
+# every model leg down with it. Folded into the chown so it shares the layer.
+RUN mkdir -p /home/mercury/.pi/agent && chown -R mercury:mercury /home/mercury
 
 USER mercury
 

package/container/agent-package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "~0.79.6"
+    "@earendil-works/pi-coding-agent": "~0.84.1"
   }
 }

package/docs/configuration.md

@@ -39,6 +39,41 @@ context:
 
 Per-space overrides via `mrctl config set context.<key> <value>` always win over YAML defaults; YAML re-reads on restart do not overwrite an existing space row.
 
+## Operator alerts (`alerts:`)
+
+When a provider OAuth credential can no longer be refreshed, every space stops
+answering until someone re-authenticates on the host. Mercury DMs the configured
+operators so the outage does not wait for a human to read the logs.
+
+```yaml
+alerts:
+  enabled: true              # default: true
+  cooldown_ms: 21600000      # 60000 – 604800000 (default: 6h)
+```
+
+Env equivalents: **`MERCURY_ALERTS_ENABLED`**, **`MERCURY_ALERTS_COOLDOWN_MS`**.
+
+- **Recipients** are the ids already listed in `permissions.admins` (`MERCURY_ADMINS`)
+  and `dm_auto_space.admin_ids` (`MERCURY_DM_AUTO_SPACE_ADMIN_IDS`)
+  — there is no separate alert-recipient key. An id is alerted only when it
+  resolves to an existing space **with a linked conversation**, i.e. a chat
+  Mercury can actually send into; an alert never creates a space. With no
+  configured admin, or none that has ever messaged the bot, the alert has
+  nowhere to go — Mercury logs that fact at ERROR and leaves the cooldown
+  unclaimed, so the next failure tries again.
+- **Channel** is the ordinary adapter outbox, the same path scheduled-task
+  failures use. It carries no agent run and no LLM, so it still works when the
+  agent's own credential is what died.
+- **`cooldown_ms`** is the minimum gap between identical alerts, per credential
+  and per reason. It is deliberately long: the alert names a manual recovery
+  step, and repeating it while an operator performs it adds nothing. The state is
+  stored in the database, so a crash-looping service does not re-alert on every
+  restart. A successful credential load clears it — if the credential dies again
+  later, that is news and alerts immediately.
+- **Transient failures** (HTTP 408/429/5xx from the token endpoint) alert only
+  after three in a row; a single blip heals itself. A rejected refresh token, or
+  a cause that could not be classified, alerts on the first occurrence.
+
 ## Ambient group context
 
 In linked group chats, messages that don't trigger the bot are stored as **ambient context** (author-attributed) so it can answer questions about conversation it overheard. Every message in a linked group becomes a row, bounded on both ends:
@@ -74,6 +109,57 @@ Container env passthrough: all — these vars reach every space's container and
 
 For secrets that only host-side hooks and jobs need, prefer `mercury.env({ from: "…", hostOnly: true })`, which keeps them out of containers in either mode. For credentials the agent should never hold at all, use a host-side capability handler (`mercury.capability()`), which runs the privileged call on the host and returns only the result.
 
+## Agent run traces (`agent.trace_runs`)
+
+Captures pi's raw output from inside each agent container, with arrival timestamps, and copies it to `<dataDir>/traces/` before the container is reaped:
+
+```yaml
+agent:
+  trace_runs: false          # false (default) | true
+```
+
+Env: `MERCURY_CONTAINER_TRACE_RUNS`.
+
+Agent containers run with `--rm`, so pi's session logs die with the container. That is fine until a run misbehaves — a turn that hits `container_timeout_ms` is killed and leaves **nothing** to show where its time went. Tracing exists for exactly that question.
+
+Each harvested file is `<dataDir>/traces/<container-name>.jsonl`, one JSON object per line:
+
+```json
+{"atMs":0,"stream":"meta","data":"{\"piSpawnedAtIso\":\"2026-08-13T09:15:02.104Z\"}"}
+{"atMs":812,"stream":"stdout","data":"{\"type\":\"message_start\"…"}
+{"atMs":47310,"stream":"stdout","data":"{\"type\":\"tool_call\"…"}
+```
+
+- `atMs` — milliseconds since pi was spawned. **A long gap between consecutive lines is the finding**: it says which call the run was sitting inside.
+- `stream` — `stdout`, `stderr`, or `meta`.
+- A trace with no closing `meta` line carrying `exitCode` means the container was **killed** rather than exiting — itself a diagnosis. A `meta` line carrying `spawnError` instead means pi never started, which looks similar but is a different fault.
+
+> **One file can hold several segments.** A run with a model chain, or one that retries a retryable failure, invokes pi more than once, and every invocation appends to the same file. Each one opens with its own `piSpawnedAtIso` `meta` line and **restarts `atMs` from zero**.
+>
+> So: split the file on `meta` lines carrying `piSpawnedAtIso`, and treat each segment separately. Comparing `atMs` across a boundary yields a negative gap and hides however long the earlier leg took — which matters, because a retry fires on exactly the misbehaving runs a trace is opened for. Concatenating `stdout` reconstructs pi's raw output byte for byte **within a segment**; glued across segments it parses as neither.
+
+Writes go through `appendFileSync` rather than a buffered stream, deliberately: a buffered write loses whatever is in userspace when the process is SIGKILLed, which is the case the trace is for.
+
+To find where a slow run actually spent its time — the largest gap between consecutive lines, and what the run was doing when it stalled:
+
+```bash
+bun -e 'const ls=require("fs").readFileSync(process.argv[1],"utf8").trim().split("\n").map(l=>JSON.parse(l));
+let prev=0,seg=0,w={gapMs:0};for(const l of ls){
+if(l.stream==="meta"&&String(l.data).includes("piSpawnedAtIso")){seg++;prev=0;continue}
+const g=l.atMs-prev;if(g>w.gapMs)w={gapMs:g,seg,atMs:l.atMs,after:String(l.data).slice(0,160)};prev=l.atMs}
+console.log(w)' .mercury/traces/<container-name>.jsonl
+```
+
+The `prev=0` reset at each `meta` line is what keeps a multi-leg run honest — without it the boundary produces a negative gap and the earlier leg's stall never wins.
+
+`after` is the output that arrived *when the gap ended*, so the call that hung is the one immediately before it.
+
+> ⚠️ **A trace contains the full prompt and the full reply in clear text** — real conversation content, including anything group members said. Treat it like `log_level: debug`: switch it on for a bounded window, capture the run you need, and switch it back.
+
+`<dataDir>/traces/` is swept by the storage cleanup: a trace file is deleted once it is older than **`MERCURY_TRACE_TTL_DAYS`** (default `7`). The sweep runs whether or not `agent.trace_runs` is currently on — otherwise switching tracing off would strand that window's traces on disk permanently, which is the case the retention exists for. Shorten it if traces are being captured on a host where the conversation content is sensitive; deleting files by hand is still fine at any time.
+
+> ⚠️ **Changing this setting needs an agent image rebuild, not just a restart.** The capture half lives in `src/agent/container-entry.ts`, which is baked into the image (`container/Dockerfile`). A restart alone deploys the host-side half and leaves tracing silently doing nothing.
+
 ## Extension config defaults (`extensions:`)
 
 Deployment-wide defaults for extension config keys, applied to **every space** (including auto-created DM spaces) at read time:

package/docs/context-architecture.md

@@ -68,6 +68,12 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 
 ```
 <caller id="…" name="…" role="…" space="…" />
+<run_budget>                            ← wall-clock window for this run
+  <started_at>…</started_at>
+  <killed_at>…</killed_at>              ← host kills the container here
+  <begin_final_answer_by>…</begin_final_answer_by>
+  <total_budget>…</total_budget>
+</run_budget>
 <episodic_memory>…</episodic_memory>   ← MEMORY.md (if present)
 <active_episodes>…</active_episodes>   ← relevance-scored episode snippets
 <history>                               ← sliding window from DB
@@ -85,6 +91,20 @@ The session boundary (`chat_state.min_message_id`) excludes messages older than
 [user prompt text]
 ```
 
+`<run_budget>` carries the wall clock the host enforces. `containerTimeoutMs`
+kills the container at `killed_at`, and before this block existed the agent had
+no way to learn that — the first and only signal was SIGKILL, too late to pace
+the work or save partial findings. `begin_final_answer_by` reserves a
+proportional slice of the budget (20%, floored at 30s, capped at 5min) for
+composing and sending the answer. The block is omitted entirely when the host
+supplies no window, or an incoherent one — a missing budget beats one claiming
+the run is already over.
+
+The matching `## Run budget` instructions live in the system prompt. They are
+gated more tightly than the block itself: a toolless model gets the block (the
+kill time is useful context regardless) but not the instructions, which all
+assume a shell to run `date` in and a file tool to save findings with.
+
 ---
 
 ## Why Not a Pi Session File?

package/examples/extensions/poster/skill/SKILL.md

@@ -5,12 +5,16 @@ description: Generate styled marketing posters, flyers and day-programme graphic
 
 # Poster CLI
 
-Two commands, two layers. Keep them separate — that separation is the whole point.
+Two layers. Keep them separate — that separation is the whole point.
 
 | Layer | Command | Nature | Cost |
 |---|---|---|---|
 | 1 — art | `poster art` | probabilistic, calls an image model | per image |
-| 2 — typography | `poster render` | deterministic, Chromium + HTML | free |
+| 2 — typography | `poster render` / `poster compose` | deterministic, Chromium + HTML | free |
+
+Layer 2 has two paths. `render` fills a fixed template; `compose` renders a
+layout you author yourself. Both go through the same document shell, so both
+carry the same Hebrew guarantee.
 
 ## The rule that matters
 
@@ -149,6 +153,56 @@ right — layer 2 is free.
 does not reliably obey `--reserve`, and flipping the composition costs nothing where
 re-rolling a generation costs money and may come back worse.
 
+## `poster compose` — author the layout yourself
+
+```
+poster compose --layout <file.html> --assets <file.json> -o <file>
+               [--aspect ...] [--size ...] [--dir rtl|ltr] [--workspace <dir>]
+               [--audit-json <file>] [--strict-warn] [--dump-html <file>]
+
+poster contract        # the authoring rules, printed
+```
+
+You write a **fragment** — `<style>` blocks plus markup — and the pipeline wraps
+it in the shell it owns: doctype, `dir="rtl"`, the embedded font palette, the
+canvas, and `#poster-stage` (a box at exactly the poster's size that your markup
+sits inside). Then it validates the fragment, measures the rendered result, and
+**refuses to write a poster that is clipped or off-stage**.
+
+```bash
+poster contract                 # read this first — it lists the families and rules
+poster compose --layout work/layout.html --assets work/assets.json \
+  --aspect 3:2 -o outbox/poster.png
+```
+
+The skill directory is read-only. Write `layout.html` and `assets.json` into the
+**workspace** (`work/…`), not next to the templates, or the write fails.
+
+Images are referenced by token, never by path — `<img src="asset:background">`,
+resolved from `{ "background": "work/bg.png" }`. A path or URL in your markup is
+rejected.
+
+Exit codes: `0` written · `1` the command was wrong · `2` the layout was
+rejected. On `2`, read the report, fix the layout, re-run — it costs nothing.
+After two failed attempts, fall back to `poster render` with the nearest
+template and say that you did.
+
+Full rules, the checked-automatically table, and the surface-landing techniques:
+`references/authoring-contract.md`.
+
+### Which path to use
+
+| Use | When |
+|---|---|
+| `render --template schedule-day` | the content is time-ordered and a hero + timed-rows card fits it |
+| `render --template feature-grid` | the content is feature-ordered — a challenge, a workshop, a launch |
+| `compose` | the content does not fit either shape, or the art has a specific surface (a hanging sign, a chalkboard, a ribbon) that the copy should sit on, or the caller asked for a particular look |
+
+Default to a template when one genuinely fits — it is one Chromium pass instead
+of two, and it is already known to hold its content. Reach for `compose` when
+the template would fight the content or waste the art. "Make it look designed,
+not filled in" is a `compose` request.
+
 ## Typography rules
 
 Apply these unless asked otherwise.

package/examples/extensions/poster/skill/references/authoring-contract.md

@@ -0,0 +1,230 @@
+# Authoring contract — `poster compose`
+
+Read this before authoring a layout. `poster contract` prints the short version
+at the terminal; this is the long one, with the reasoning.
+
+## What you write, and what you must not
+
+You write a **fragment**: one or more `<style>` blocks plus the markup that goes
+inside the poster. You do not write a document.
+
+The pipeline supplies — and you cannot override:
+
+- `<!doctype html>`, `<html dir="rtl" lang="he">`, `<meta charset="utf-8">`
+- every `@font-face` in the bundled palette, base64-inlined
+- `html, body` sized to the exact canvas, `overflow: hidden`
+- `#poster-stage` — a `position: relative` box at exactly the poster's
+  dimensions. Your markup goes inside it. Position against it.
+- a `.ltr` utility class
+- the audit script (present only in the measuring pass, never in the shot one)
+
+This split is not bureaucracy. It is the reason the extension exists: a layout
+**cannot** forget to embed the font or set the wrong text direction, because
+neither is in the part you write. Get the composition wrong and you get an ugly
+poster; get font embedding wrong and you get a poster full of empty boxes where
+the Hebrew should be, which is the failure this pipeline was built to make
+impossible.
+
+## Fonts
+
+Four Hebrew faces, plus the Latin fallback. Run `poster fonts --list` for what
+each is for.
+
+| Family | Face | Use for |
+|---|---|---|
+| `PosterSans` | Rubik | body copy, rows, anything neutral |
+| `PosterDisplay` | Suez One | big headlines; very heavy |
+| `PosterHand` | Amatic SC | taglines, asides — hand-drawn and thin |
+| `PosterSerif` | Frank Ruhl Libre | editorial or formal |
+| `PosterLatin` | Rubik Latin | digits and Latin words fall through to it already |
+
+**Naming any other family is an error**, checked before anything renders. Not a
+style preference — a face that is not embedded renders as tofu boxes or silently
+drops the glyphs, and nothing downstream would notice.
+
+Use `font-family`. The `font` shorthand is refused, because its family position
+cannot be extracted reliably enough to check, and a check that is sometimes
+wrong is worse than a rule that is always clear.
+
+`PosterHand` has a much smaller x-height than the others. If you use it, raise
+the font size ~40% over what you would give `PosterSans`.
+
+**Mix faces deliberately.** One family across a whole poster reads as a slide,
+not a design. Heavy display headline + hand-drawn aside + neutral sans body is
+the combination that makes these look designed.
+
+## Images
+
+Reference every image by **token**, never by path:
+
+```html
+<img src="asset:background" alt="">
+<div style="background: url(asset:dish) center/cover"></div>
+```
+
+Tokens resolve from the `--assets` JSON map, which the caller writes:
+
+```json
+{ "background": "work/bg.png", "dish": "work/dish.png" }
+```
+
+This applies wherever an image can appear, `image-set("…")` and `image("…")`
+included — those take a bare quoted string with no `url()` wrapper, and they are
+checked the same way.
+
+A filesystem path, a URL, or a `data:` URI in your markup is an error. The
+indirection is deliberate: it means a layout has no way to name a file, so
+`<img src="../../.env">` fails as an unresolvable token rather than being read
+and base64-inlined into an image someone then shares. Paths come from the
+caller and are confined to the workspace.
+
+## Hebrew and numerals
+
+The page is RTL. Never reorder Hebrew strings by hand — the browser's bidi
+algorithm handles it, and hand-reordering is how text ends up backwards.
+
+**Wrap every digit run in `class="ltr"`:**
+
+```html
+<div>יציאה <span class="ltr">12:30</span> מהמלון</div>
+```
+
+Without it `12:30` can render as `30:12`. This is checked and warns; the warning
+is printed but does not block output; pass `--strict-warn` if you want it to.
+
+One nuance worth knowing if you are tempted to write your own isolation: setting
+`unicode-bidi: isolate` does *not* satisfy this. Chromium's own stylesheet
+already computes `isolate` for every block element, so it distinguishes nothing.
+What matters is `direction: ltr`, which is what `.ltr` sets.
+
+## Composition — physical sides, not logical ones
+
+Use `left` / `right`, **not** `inset-inline-start` / `inset-inline-end`.
+
+Under `dir="rtl"` the logical properties mirror the entire composition, which
+desyncs the layout from wherever the art layer actually left its blank space.
+Which side holds the hero is a *design* decision about the specific background
+you were given; it is not a consequence of the text direction. Text inside each
+block still flows RTL regardless.
+
+## Landing text on a surface
+
+A flat absolutely-positioned box renders perfect Hebrew and still looks pasted
+on. What makes a poster look designed is copy that sits *on* something in the
+art:
+
+```css
+.title { transform: rotate(-2.5deg); }                    /* match a tilted sign */
+.ribbon { transform: rotate(1.5deg) skewX(-3deg); }       /* follow a ribbon */
+.chalk { mix-blend-mode: multiply; }                      /* sink into a chalkboard */
+.on-photo { text-shadow: 0 2px 6px rgba(0,0,0,.5); }      /* mandatory over photography */
+```
+
+`transform` also **moves** a block, which is how you land a headline on a
+surface the model put somewhere unexpected:
+`transform: translateY(120px) rotate(-1deg)`.
+
+Iterate freely. Layer 2 is deterministic and free — only the art call costs
+money, and re-rendering never touches it.
+
+## What is checked automatically
+
+Static, before any render:
+
+| Rule | Rejects |
+|---|---|
+| `forbidden-element` | `script` `iframe` `object` `embed` `link` `base` `form` `input` `meta` `html` `head` `body`; also `id="poster-stage"`, which is the pipeline's |
+| `forbidden-at-rule` | `@import`, `@font-face`, `@charset`, `@namespace` |
+| `event-handler` | any `on*` attribute |
+| `external-url` | any URL that is not `asset:<token>` or `#fragment` |
+| `unknown-font` | a family outside the palette; the `font` shorthand |
+| `unresolved-asset` | a token with no entry in the assets map |
+| `asset-escape` | an assets path resolving outside the workspace |
+
+Measured in a real browser, after fonts have loaded:
+
+| Rule | Level | Means |
+|---|---|---|
+| `clipped` | error | text overflows an element whose `overflow` is hidden |
+| `offstage` | error | an element's box falls outside `#poster-stage` |
+| `tofu` | error | a Hebrew character no bundled face covers — it renders as an empty box |
+| `numerals-not-isolated` | warning | a digit run that could reorder |
+| `audit-failed` | error | the check could not run — never treated as a pass |
+
+**Errors block output entirely.** No PNG is written, not even a partial one.
+Warnings print and proceed — `--strict-warn` promotes them to blocking. Nothing overrides an error.
+
+`clipped` only fires where overflow is actually hidden — text that spills
+visibly is a design choice, and the words are still there.
+
+`tofu` is the one that protects the whole premise. It draws each Hebrew character
+twice — once in your font stack, once with the bundled faces stripped out — and
+flags any character where the two are pixel-identical, meaning no bundled face
+contributed and a fallback drew it. On this image no fallback covers Hebrew at
+all, so that is an empty box in the poster. Known gap: standalone combining marks
+(nikud) are not reliably caught, because the dotted-circle placeholder is itself
+in the subset. Proofread vowelised text by eye.
+
+> **A clean audit does not mean the poster is good.** These checks catch *broken* —
+> text that is cut off, boxes off the canvas, glyphs that did not render. They say
+> nothing about whether the composition is attractive, whether the copy is legible
+> against the art behind it, or whether the type sits convincingly on a surface.
+> Look at the PNG before you send it, and never report a green audit as "the
+> poster looks good" — that is not what was measured.
+
+## When it rejects your layout
+
+The report names the element. Fix the layout and re-run: exit code **2** means
+the layout was rejected, **1** means the command itself was wrong (retrying
+that unchanged will fail identically).
+
+For `clipped`, cut content or grow the box — do not shrink type below
+legibility. For `offstage`, the report gives both rects; the element is outside
+a stage of the size it names.
+
+Two authoring attempts. If the second is still rejected, fall back to
+`poster render` with the nearest template and say that you did — a template
+poster that ships beats a bespoke one that does not.
+
+## Where files go
+
+The skill directory is mounted **read-only**. Write `layout.html` and
+`assets.json` into your workspace:
+
+```bash
+poster compose --layout work/layout.html --assets work/assets.json \
+  --aspect 3:2 -o outbox/poster.png
+```
+
+Writing next to the templates fails with `EROFS`.
+
+## Worked examples
+
+The two templates are the reference for what good looks like in this system —
+read one before authoring your own:
+
+- `skill/templates/schedule-day.mjs` — time-ordered: hero, taped card of timed
+  rows, footer. Note the LTR pin on `.row-time` and the physical-sides comment.
+- `skill/templates/feature-grid.mjs` — feature-ordered: dark hero band with a
+  contrast scrim, torn-paper split, icon columns, cards, CTA.
+
+They emit fragments through the same shell you do, so anything they do is
+available to you.
+
+A worked **freeform** layout ships alongside this file:
+
+- `references/example-layout.html` — an itinerary whose title is painted into
+  the grain of a wooden sign in the plate (`mix-blend-mode: multiply`, rotated to
+  match its hang), with the timed rows in the open corner. It renders clean, and
+  it is the shape of thing no fixed template can produce: nothing in a template
+  knows there is a sign in the art, let alone where.
+
+Run it against your own background to see the mechanics:
+
+```bash
+poster compose --layout references/example-layout.html \
+  --assets work/assets.json --aspect 3:2 -o work/try.png
+```
+
+(Copy it into your workspace first if you want to edit it — the skill directory
+is read-only.)