mercury-agent 0.13.0 → 0.15.0

package/README.md

@@ -279,8 +279,17 @@ mercury service install
 mercury service uninstall
 mercury service status
 mercury service logs [-f]
+
+# upgrade (stops the service, installs globally, restarts)
+mercury upgrade             # latest
+mercury upgrade 0.14.0      # a specific version
 ```
 
+> **Windows:** stop Mercury before upgrading. Windows locks the native
+> `libvips` DLL that a running Mercury has mapped, so a global install fails
+> with `EBUSY`. `mercury upgrade` detects the lock and stops before npm leaves a
+> rolled-back install behind — see [docs/deployment.md](docs/deployment.md#windows-stop-mercury-before-upgrading).
+
 ### `mrctl` (in-container API CLI)
 
 ```bash

package/docs/container-lifecycle.md

@@ -96,8 +96,9 @@ Containers have a maximum runtime to prevent runaway processes.
 When a container exceeds the timeout:
 1. Container is killed via `docker kill`
 2. `ContainerError` thrown with `reason: "timeout"`
-3. User sees: "Container timed out."
-4. Queue unblocks, next message can proceed
+3. User sees: "I ran out of time before finishing. Partial work may be saved in the workspace — ask me to continue."
+4. A marker assistant message ("[System: this run was killed at the container time limit before replying. …]") is recorded in chat history, so the next run's agent knows the previous run was cut off and can check the workspace for partial work
+5. Queue unblocks, next message can proceed
 
 The host always injects a resolved **model chain** into the container (after `MERCURY_*` passthrough) so retries and fallbacks use the same policy Mercury loaded at startup:
 
@@ -113,7 +114,7 @@ Container failures are classified by `ContainerError`:
 
 | Reason | Exit Code | Cause | User Message |
 |--------|-----------|-------|--------------|
-| `timeout` | — | Exceeded `containerTimeoutMs` | "Container timed out." |
+| `timeout` | — | Exceeded `containerTimeoutMs` | "I ran out of time before finishing. Partial work may be saved in the workspace — ask me to continue." |
 | `oom` | 137 | SIGKILL (OOM, resource limits, or manual kill) | "Container was killed (possibly out of memory)." |
 | `aborted` | — | User sent `stop` command | "Stopped current run." |
 | `error` | non-zero | Agent crashed or failed | *(error thrown, logged)* |

package/docs/deployment.md

@@ -99,6 +99,42 @@ Not currently supported via `mercury service`. Options:
 2. **NSSM**: Use [NSSM](https://nssm.cc/) to wrap Mercury as a Windows service
 3. **PM2**: Use `pm2 start "mercury run" --name mercury`
 
+## Upgrading
+
+```bash
+mercury upgrade            # to the latest published version
+mercury upgrade 0.14.0     # to a specific version
+```
+
+On macOS and Linux this stops the managed service, installs the new version
+globally, and restarts the service.
+
+### Windows: stop Mercury before upgrading
+
+Windows will not let a file be replaced while a running process has it mapped.
+Mercury reaches `sharp` transitively (via `@whiskeysockets/baileys`, which loads
+it on demand to build image thumbnails), and importing sharp maps
+`libvips-*.dll` out of the global install tree. Once a running Mercury has
+handled a single image, a plain `npm install -g mercury-agent@latest` fails:
+
+```
+npm error code EBUSY
+npm error EBUSY: resource busy or locked
+npm error path ...\node_modules\@img\sharp-win32-x64\lib\libvips-42.dll
+```
+
+`mercury upgrade` detects this before npm does and stops with the list of locked
+files instead of leaving a rolled-back install behind. The fix is to stop Mercury
+first:
+
+1. Stop every running Mercury — `Ctrl+C` in the `mercury run` terminal, or stop
+   the NSSM / Task Scheduler / PM2 entry wrapping it.
+2. `mercury upgrade`
+3. Start Mercury again.
+
+Mercury's own CLI does not load the WhatsApp stack at startup, so running
+`mercury upgrade` never locks the tree it is replacing.
+
 ## Auto-Restart Behavior
 
 Both systemd and launchd are configured to automatically restart Mercury if it crashes:

package/docs/permissions.md

@@ -28,7 +28,7 @@ Message arrives
 |------|---------------------|-------------|
 | `system` | All | Internal system caller (scheduler, etc.) — not assignable |
 | `admin` | All | Full control over the space |
-| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send` | Can chat, read space preferences, and exchange files (default for new users) |
+| `member` | `prompt`, `prefs.get`, `media.receive`, `media.send`, `model.list` | Can chat, read space preferences, exchange files, and list models (default for new users) |
 
 Custom roles can be created by assigning permissions to any role name.
 
@@ -56,6 +56,8 @@ Custom roles can be created by assigning permissions to any role name.
 | `spaces.list` | View all spaces |
 | `spaces.rename` | Rename a space and link/unlink conversations |
 | `spaces.delete` | Delete current space and all related DB data |
+| `model.list` | List the configured model chain (`mrctl model list`, chat `/model list`) |
+| `model.switch` | Switch the active model for the space (`mrctl model switch`, chat `/model switch`) — takes effect on the next agent run |
 | `media.receive` | Incoming attachments are saved to `inbox/` and shown to the agent |
 | `media.send` | Outbox files produced on this caller's turn are delivered back to the chat |
 

package/examples/extensions/README.md

@@ -9,4 +9,5 @@ Real-world Mercury extensions. Copy any of these into `.mercury/extensions/` to
 | **gws** | Google Workspace (Drive/Gmail/Calendar/etc.) | cli, skill, permission (admin-only default) |
 | **pinchtab** | Browser automation via Playwright | cli, skill, permission, `before_container` hook (env + system prompt) |
 | **napkin** | Obsidian vault management + KB distillation | cli, skill, permission, `workspace_init` hook, `before_container` hook, job, config, widget, store |
+| **poster** | Styled posters with correct Hebrew/RTL text — AI background art + deterministic HTML typography | cli, skill, permission, env, config, `requires`, `before_container` hook (config → env) |
 

package/examples/extensions/gws/README.md

@@ -28,19 +28,38 @@ npm i -g @googleworkspace/cli
 gws auth login
 ```
 
-2. Export credentials once:
+2. Export the credentials and put the JSON (as a single line) into `.env`:
 
 ```bash
-gws auth export --unmasked > .mercury/global/gws-credentials.json
+gws auth export --unmasked
 ```
 
-3. Add to `.env`:
-
 ```bash
-MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/home/mercury/.pi/agent/gws-credentials.json
+MERCURY_GWS_CREDENTIALS_JSON={"client_id":"...","client_secret":"...","refresh_token":"...","type":"authorized_user"}
 ```
 
-(You can also use `MERCURY_GOOGLE_WORKSPACE_CLI_TOKEN`, but it expires quickly.)
+3. Restart Mercury. The extension's `before_container` hook passes the JSON
+   into the inner container, and the skill materializes it as a credentials
+   file at runtime.
+
+> **Do not use the file-based path.** Older versions of this README said to
+> export to `.mercury/global/gws-credentials.json` and set
+> `MERCURY_GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`. That no longer works: the
+> runtime mounts the global dir into the inner container entry-by-entry via an
+> allowlist (`PI_AGENT_RESOURCE_ENTRIES` in `container-runner.ts`), and the
+> credentials file is not on it — the container never sees it.
+>
+> **Windows/PowerShell note:** if you do redirect `gws auth export` output to a
+> file, PowerShell's `>` writes UTF-16 — invalid for JSON readers. Use
+> `gws auth export --unmasked | Out-File -Encoding utf8 <path>` instead.
+>
+> (`MERCURY_GOOGLE_WORKSPACE_CLI_TOKEN` also exists, but it expires quickly.)
+
+## Refreshing credentials
+
+Re-run `gws auth login` + `gws auth export --unmasked`, replace the
+`MERCURY_GWS_CREDENTIALS_JSON` value in `.env` (the refresh token changes),
+and restart Mercury.
 
 ## Verify
 

package/examples/extensions/gws/index.ts

@@ -56,9 +56,42 @@ const gwsEnv = {
 const CREDENTIALS_FILE = "/tmp/gws-credentials.json";
 
 export default function (mercury: MercuryExt) {
+  // The gws CLI can only take refresh-token credentials from a file, so someone
+  // has to materialize GWS_CREDENTIALS_JSON before the first command runs. The
+  // before_container hook can't (see the comment on that hook below), and asking
+  // the skill to do it makes credential delivery depend on the model remembering
+  // a prose instruction. Instead, /usr/local/bin/gws is a wrapper that does it on
+  // every invocation and execs the real binary.
+  //
+  // Ordering note: parseInstallCommand() keeps a command that mixes a package
+  // manager with shell parts intact as a single shell step, which is what makes
+  // the `mv` reliably run after the npm install. Do NOT split this into separate
+  // mercury.cli() declarations — mergeInstalls() would then reorder npm ahead of
+  // shell only by coincidence of grouping, and the wrapper would be clobbered.
   mercury.cli({
     name: "gws",
-    install: "npm install -g @googleworkspace/cli",
+    install: [
+      "npm install -g @googleworkspace/cli",
+      'mv "$(command -v gws)" /usr/local/bin/gws-real',
+      // Written line-by-line via printf so the credentials never reach a traced
+      // shell; $GWS_CREDENTIALS_JSON is single-quoted here and expanded only at
+      // runtime, inside the wrapper.
+      "printf '%s\\n' " +
+        "'#!/bin/sh' " +
+        "'if [ -n \"$GWS_CREDENTIALS_JSON\" ]; then' " +
+        `'  c="\${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-${CREDENTIALS_FILE}}"' ` +
+        "'  t=\"$c.$$\"' " +
+        "'  (umask 077; printf %s \"$GWS_CREDENTIALS_JSON\" > \"$t\")' " +
+        // Credentials changed (rotation, or a different caller in a reused
+        // container) invalidates the cached access token alongside them.
+        "'  cmp -s \"$t\" \"$c\" 2>/dev/null || rm -f \"${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json\"' " +
+        "'  mv -f \"$t\" \"$c\"' " +
+        "'  GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=\"$c\"; export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE' " +
+        "'fi' " +
+        "'exec /usr/local/bin/gws-real \"$@\"' " +
+        "> /usr/local/bin/gws",
+      "chmod 755 /usr/local/bin/gws",
+    ].join(" && "),
   });
 
   mercury.permission({ defaultRoles: ["admin"] });

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

@@ -23,16 +23,20 @@ Use the `gws` CLI via Bash for all Google Workspace operations.
 | JSON objects or arrays | Summarise in prose |
 | Email `labelIds`, `threadId`, `messageId` | Never shown |
 
-## Credentials setup (run once per session before any gws command)
+## Credentials
 
-`GWS_CREDENTIALS_JSON` contains the credentials as a JSON string. Materialize it to the path gws expects, then verify auth:
+Credentials are set up automatically — there is **no** setup step to run. Never
+write a credentials file yourself and never set
+`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`; the `gws` command does both on every
+invocation.
 
-```bash
-[ -n "$GWS_CREDENTIALS_JSON" ] && echo "$GWS_CREDENTIALS_JSON" > "${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}" && export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE="${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-/tmp/gws-credentials.json}"
-gws auth status
-```
+If a command fails on authentication, run `gws auth status` and report the cause
+accurately:
 
-If `auth_method` is not `none`, credentials are ready. Skip this step on subsequent calls in the same session (the file persists in /tmp for the container lifetime).
+| `gws auth status` says | What it actually means — report this |
+|---|---|
+| `"auth_method": "none"` | The caller does not have the `gws` permission, or no Google Workspace connection has been set up for this deployment. Say that — do **not** say Google Workspace is broken or misconfigured. |
+| `"auth_method": "oauth2"` but the command still fails | Credentials are present and delivered. The failure is API-side (revoked token, missing scope, or a per-service permission), not a Mercury configuration problem. Report the API's own error message. |
 
 ## Dispatch table
 

package/examples/extensions/longview/index.ts

@@ -20,6 +20,7 @@ import { join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
+  providerCredentialEnvVar,
 } from "mercury-agent/storage/pi-auth";
 import {
   DEFAULT_THRESHOLD,
@@ -130,12 +131,23 @@ export default function (mercury: {
     const authPath = resolve(
       config.authPath ?? join(config.globalDir, "auth.json"),
     );
+    // Name the credential the way pi reads it for this provider — the same
+    // shared table container-runner injects from, so the two spawn paths can't
+    // drift apart again. Asked *before* resolving, in that same order: a
+    // provider pi reads no env var for (openai-codex) can never be served, and
+    // resolving would spend a single-use refresh token to learn that. Only
+    // non-anthropic providers can land here, so the fail-fast below is
+    // unaffected — anthropic always has an env var.
+    const credEnvVar = providerCredentialEnvVar(config.modelProvider);
+    if (!credEnvVar) {
+      return { ok: true, env };
+    }
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,
     });
     if (cred.status === "ok") {
-      env.ANTHROPIC_API_KEY = cred.apiKey;
+      env[credEnvVar] = cred.apiKey;
       return { ok: true, env };
     }
 

package/examples/extensions/napkin/index.ts

@@ -14,6 +14,7 @@ import { delimiter, dirname, join, resolve } from "node:path";
 import {
   getPiAuthCredential,
   parseOAuthTokenEnv,
+  providerCredentialEnvVar,
 } from "mercury-agent/storage/pi-auth";
 
 const KNOWLEDGE_DIR = "knowledge";
@@ -458,12 +459,23 @@ export default function (mercury: {
     const authPath = resolve(
       config.authPath ?? join(config.globalDir, "auth.json"),
     );
+    // Name the credential the way pi reads it for this provider — the same
+    // shared table container-runner injects from, so the two spawn paths can't
+    // drift apart again. Asked *before* resolving, in that same order: a
+    // provider pi reads no env var for (openai-codex) can never be served, and
+    // resolving would spend a single-use refresh token to learn that. Only
+    // non-anthropic providers can land here, so the fail-fast below is
+    // unaffected — anthropic always has an env var.
+    const credEnvVar = providerCredentialEnvVar(config.modelProvider);
+    if (!credEnvVar) {
+      return { ok: true, env };
+    }
     const cred = await getPiAuthCredential({
       provider: config.modelProvider,
       authPath,
     });
     if (cred.status === "ok") {
-      env.ANTHROPIC_API_KEY = cred.apiKey;
+      env[credEnvVar] = cred.apiKey;
       return { ok: true, env };
     }
 

package/examples/extensions/poster/index.ts

@@ -0,0 +1,92 @@
+/**
+ * poster — styled poster generation with correct Hebrew (and other RTL) text.
+ *
+ * Two layers, deliberately separated:
+ *
+ *   1. art   — an image model paints the background (photographic scene, textures,
+ *              product plates). Prompted to render NO text at all.
+ *   2. render — Chromium composites the copy from an HTML template using a real
+ *              embedded Hebrew font.
+ *
+ * The split exists because no image model renders Hebrew reliably. Nano Banana Pro
+ * is the best available (Gemini 3 backbone plans layout before rendering) but
+ * accuracy is length-dependent — ~100% on headlines, ~80% at 15-30 words, ~60%
+ * beyond — and Arabic, the closest published RTL analogue to Hebrew, sits at ~75%
+ * per short line. A poster with twenty text runs is never fully clean. Layer 2
+ * makes the typography deterministic: fonts, RTL, kerning and safe-area geometry
+ * are code, not a prompt.
+ *
+ * No CLI install step is needed. The container base image is the Microsoft
+ * Playwright image and already provides `/usr/local/bin/chromium` plus Bun, so
+ * `mercury.cli()` only drops a shim onto the read-only skill mount.
+ */
+
+import type { MercuryExtensionAPI } from "mercury-agent/extensions/types";
+
+const EXT = "poster";
+
+/** Skill dir as mounted inside the container (read-only). */
+const SKILL_DIR = `/home/mercury/.pi/agent/skills/${EXT}`;
+
+export default function setup(mercury: MercuryExtensionAPI) {
+  // A shim rather than an npm package: the implementation ships in the skill
+  // directory, so there is nothing to publish and nothing to version separately.
+  mercury.cli({
+    name: EXT,
+    install: [
+      `printf '#!/bin/sh\\nexec bun ${SKILL_DIR}/scripts/poster.mjs "$@"\\n'`,
+      `> /usr/local/bin/${EXT}`,
+      `&& chmod +x /usr/local/bin/${EXT}`,
+    ].join(" "),
+  });
+
+  mercury.permission({ defaultRoles: ["admin", "member"] });
+
+  // Layer 2 is free; layer 1 needs whichever provider is configured. Keys are
+  // only injected for callers who hold the `poster` permission.
+  mercury.env({ from: "MERCURY_POSTER_GEMINI_KEY", as: "POSTER_GEMINI_KEY" });
+  mercury.env({ from: "MERCURY_POSTER_OPENAI_KEY", as: "POSTER_OPENAI_KEY" });
+
+  mercury.config("provider", {
+    description:
+      "Art-layer image provider: gemini (Nano Banana Pro), openai (GPT Image 2), or local (self-hosted HTTP endpoint).",
+    default: "gemini",
+    validate: (v) => v === "gemini" || v === "openai" || v === "local",
+  });
+
+  mercury.config("local_endpoint", {
+    description:
+      "HTTP endpoint for provider=local, e.g. http://host.docker.internal:8188/mercury-poster. POSTed {prompt,width,height}; must return {image_b64} or a raw PNG.",
+    default: "",
+  });
+
+  mercury.config("size", {
+    description:
+      "Default art-layer resolution: 1K, 2K or 4K. Gemini bills 2K and 1K identically, so 2K is the sensible floor.",
+    default: "2K",
+    validate: (v) => v === "1K" || v === "2K" || v === "4K",
+  });
+
+  // The CLI runs inside the container and cannot read space config directly, so
+  // resolve it host-side and hand it over as env.
+  mercury.on("before_container", async (event, ctx) => {
+    return {
+      env: {
+        POSTER_PROVIDER:
+          ctx.getConfig(event.spaceId, `${EXT}.provider`) ?? "gemini",
+        POSTER_LOCAL_ENDPOINT:
+          ctx.getConfig(event.spaceId, `${EXT}.local_endpoint`) ?? "",
+        POSTER_SIZE: ctx.getConfig(event.spaceId, `${EXT}.size`) ?? "2K",
+        POSTER_SKILL_DIR: SKILL_DIR,
+      },
+    };
+  });
+
+  // Both layers are driven from bash; without tool use the skill is inert.
+  // Note that `requires` gates the *skill* install, not the `cli()` install: on a
+  // chain leg with no tool use the `poster` shim still exists but points at a skill
+  // directory that was never copied. Harmless, but the failure reads as a bun
+  // stack trace rather than "command not found".
+  mercury.requires(["tools"]);
+  mercury.skill("./skill");
+}

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

@@ -0,0 +1,227 @@
+---
+name: poster
+description: Generate styled marketing posters, flyers and day-programme graphics with correct Hebrew (or other RTL) text — AI-generated background art composited with deterministic HTML typography
+---
+
+# Poster CLI
+
+Two commands, 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 |
+
+## The rule that matters
+
+**Never ask the image model to draw the text.** No image model renders Hebrew reliably:
+short headlines land ~95–100% of the time, but 15–30 word blocks drop to ~80% and RTL
+scripts sit near ~75% *per line*. A poster has fifteen to twenty text runs, so "mostly
+correct" means "one broken word per poster, every time".
+
+`poster art` already appends a suppression clause to every prompt. Do not undo it by
+asking for a title in the scene — you will get the model's mangled Hebrew *underneath*
+the correct composited text.
+
+## Workflow
+
+```bash
+# 1. Background plate. Describe the scene only; leave signs and boards blank.
+poster art \
+  --prompt "Golan Heights vineyard at golden hour, rustic wooden signpost, blank hanging
+            wooden sign, wine bottle and glass on a weathered table, grapes, warm lantern,
+            string lights in the trees, lush green foliage, cinematic depth of field" \
+  --aspect 3:2 --size 2K \
+  -o work/summer-bg.png
+
+# 2. Copy. Write the config, then composite.
+poster render --template schedule-day --config work/summer.json -o outbox/summer.png
+```
+
+Anything written to `outbox/` is delivered to the chat automatically.
+
+## `poster art`
+
+```
+poster art --prompt "<scene>" -o <file>
+           [--aspect 1:1|4:5|3:4|2:3|3:2|16:9|9:16]   default 3:2
+           [--size 1K|2K|4K]                          default from poster.size (2K)
+           [--provider gemini|openai|local]            default from poster.provider
+           [--reserve "<where>"]                       e.g. "left third", "lower band"
+```
+
+`--reserve` asks the model to leave negative space where the copy will land. Use it —
+a background with the subject dead-centre forces you to cover it.
+
+Providers:
+
+| Provider | Model | Notes |
+|---|---|---|
+| `gemini` | `gemini-3-pro-image-preview` (Nano Banana Pro) | Best scene reasoning. Needs `POSTER_GEMINI_KEY`. |
+| `openai` | `gpt-image-2` | Cheaper per image. Needs `POSTER_OPENAI_KEY`. |
+| `local` | self-hosted | POSTs to `poster.local_endpoint`. No API cost. |
+
+Prompt the art layer for **surfaces**, not text: "blank wooden sign", "empty chalkboard",
+"plain kraft-paper label". The template then lays copy onto those surfaces.
+
+## `poster render`
+
+```
+poster render [--template <name>] (--config <file> | < stdin) -o <file>
+              [--aspect ...] [--size ...] [--dump-html <file>]
+```
+
+Deterministic, so iterate freely — fix a typo and re-render, no new generation.
+`--dump-html` writes the intermediate page when a layout needs debugging.
+
+Discover the config shape from the template itself:
+
+```bash
+poster templates            # list
+poster schema schedule-day  # fields
+```
+
+### Choosing a template
+
+| Template | Shape | Use when |
+|---|---|---|
+| `schedule-day` | hero + taped card of timed rows + footer | the content is **time-ordered** — an itinerary, a programme, a day plan |
+| `feature-grid` | dark hero + torn-paper split + icon columns + checklist/callout cards + CTA | the content is **feature-ordered** — a challenge, a workshop, a launch, a visual newsletter |
+
+Both default to RTL. `schedule-day` defaults to 3:2 (landscape), `feature-grid` to 3:4 (portrait).
+
+### Example config — `schedule-day`
+
+```json
+{
+  "template": "schedule-day",
+  "background": "work/summer-bg.png",
+  "aspect": "3:2",
+  "title": "חופשת",
+  "title2": "קיץ",
+  "ribbon": "בכפר קצרין",
+  "tagline": "אווירת צפון. רגעים של יחד.",
+  "date_label": "חמישי 20.8",
+  "accent": "#7d9a3f",
+  "rows": [
+    {
+      "time": "12:30",
+      "heading": "יקב תל שיפון",
+      "body": "פותחים את החופשה בטעמים של הגולן",
+      "icon": "🍷",
+      "photo": "work/vineyard.png"
+    },
+    { "time": "15:15", "heading": "סדנת שוקולד", "body": "מתוק, יצירתי וכיפי לכל המשפחה", "icon": "🍫" },
+    { "time": "19:45", "heading": "סיור עששיות", "body": "מסיימים את היום בהרפתקה לילית", "icon": "🏮" }
+  ],
+  "credits": "קקון | צברי | יעל",
+  "footer": "צפון. טבע. חברים. זכרונות טובים."
+}
+```
+
+### Making text sit *on* a surface
+
+Flat text boxes render perfect Hebrew and still look pasted on. Each hero run takes an
+optional surface hint so it can be laid onto the art:
+
+```json
+{
+  "title_surface":   { "transform": "rotate(-2.5deg)" },
+  "ribbon_surface":  { "transform": "rotate(1.5deg) skewX(-3deg)" },
+  "tagline_surface": { "blend": "multiply", "shadow": "0 2px 6px rgba(0,0,0,.5)" }
+}
+```
+
+Keys: `transform` (any CSS transform), `blend` (`mix-blend-mode`, `multiply` for
+chalkboards and paper), `shadow` (`text-shadow`), `color`.
+
+Match the hint to the surface in the art — if the generated sign tilts left, tilt the
+title to match. This is the step that separates a designed poster from a caption on a photo.
+
+`transform` also **moves** a block, which is how you land a title on a surface the model
+put somewhere unexpected: `"title_surface": { "transform": "translateY(120px) rotate(-1deg)" }`
+drops the hero down onto a sign hanging in the middle of the frame. Re-render until it sits
+right — layer 2 is free.
+
+### When the art puts the blank surface on the wrong side
+
+`schedule-day` accepts `"flip": true`, which swaps the hero and card sides. The art layer
+does not reliably obey `--reserve`, and flipping the composition costs nothing where
+re-rolling a generation costs money and may come back worse.
+
+## Typography rules
+
+Apply these unless asked otherwise.
+
+- **Hebrew is RTL by default.** The template sets `dir="rtl"`; pass `"dir": "ltr"` only for
+  a Latin-only poster. Never reorder Hebrew strings by hand — the browser handles it.
+- **Times and numerals stay LTR.** Already pinned in the template so `12:30` cannot
+  become `30:12`. If you add a numeric run elsewhere, pin `direction: ltr` on it.
+- **Headlines short.** 8–14 characters for `title`/`title2`; they render at 11–17% of
+  poster height. Longer strings overflow rather than shrink.
+- **Body blurbs ≤ 8 words.** Two lines at most per row.
+- **Contrast, not decoration.** Cream `#f6efdd` / `#fdf6e6` on dark art, ink `#2f2a22` on
+  light cards. A drop shadow on light text over photography is mandatory, not optional.
+- **Fonts are bundled.** All faces are OFL, base64-inlined at render time. Never reference
+  Google Fonts or a system font: the container has no Hebrew system face, and a render must
+  not depend on a network fetch that can fail silently into tofu boxes.
+- **Mix faces deliberately.** A single family across a whole poster reads as a slide, not a
+  design. Heavy display for the headline, hand-drawn for the aside, neutral sans for the
+  body is the combination that makes these look designed.
+- **Emoji icons work.** The base image ships Noto Color Emoji, so `"icon": "🍷"` renders in
+  colour. Verified in the container, not assumed.
+
+## Type palette
+
+Four bundled Hebrew families. Latin characters and digits always fall through to Rubik, so
+mixed strings like `יקב Tel Shifon 12:30` stay coherent instead of breaking mid-line.
+
+```bash
+poster fonts --list
+```
+
+| Family | Face | Use for |
+|---|---|---|
+| `PosterSans` | Rubik | body copy, rows, anything neutral — the default |
+| `PosterDisplay` | Suez One | big headlines; very heavy, the default for hero titles |
+| `PosterHand` | Amatic SC | taglines, asides, annotations — hand-drawn and thin |
+| `PosterSerif` | Frank Ruhl Libre | editorial or formal posters |
+
+Set one per template key (`title_font`, `tagline_font`, `tag_font`, `body_font`) or per run
+via a surface hint:
+
+```json
+{ "title_font": "PosterSerif", "tagline_surface": { "font": "PosterHand" } }
+```
+
+`PosterHand` has a much smaller x-height than the others; the templates already size it up
+where they use it. If you apply it somewhere new, expect to raise the font size by ~40%.
+
+## When Hebrew comes out as boxes
+
+That is a font failure, not a layout failure. Diagnose it directly:
+
+```bash
+poster fonts --check
+```
+
+It renders the Hebrew alphabet once per bundled family plus one row in a deliberately
+missing family, then prints a per-family verdict into the image. Every family row must show
+real letters and the block must read `ALL PASS`. A single `FAIL` line names the family whose
+`.woff2` did not load — check `assets/` is present in the skill mount.
+
+Run this after adding any font. A face advertised as "supporting Hebrew" often ships a
+Latin-only subset, and nothing else in the pipeline notices.
+
+## Configuration
+
+Space admins set these via `mrctl config set`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `poster.provider` | `gemini` | Art-layer provider |
+| `poster.size` | `2K` | Default resolution (Gemini bills 1K and 2K the same) |
+| `poster.local_endpoint` | — | Required when `provider=local` |
+
+Host `.env`: `MERCURY_POSTER_GEMINI_KEY`, `MERCURY_POSTER_OPENAI_KEY`. Keys are only
+injected for callers holding the `poster` permission.