feat(daemon): add project export manifest (#3245)

* feat(daemon): add project export manifest

* fix(daemon): honor export manifest primary refs

* fix(daemon): bind headless runs to default conversation

* test(e2e): retry tools-dev namespace startup collisions

* test(daemon): reject sandbox imported export manifests

* fix(daemon): honor artifact manifest entry refs

* fix(daemon): update renamed artifact manifest entries

* fix(daemon): update artifact refs during rename

* fix(daemon): preserve export refs across directory moves

.claude/commands/od-contribute.md

@@ -0,0 +1,23 @@
+---
+description: Open a first-contribution PR (or bug issue) on nexu-io/open-design — works for non-coders too.
+argument-hint: "[skill | design-system | i18n | docs | bug — optional, otherwise the skill will ask]"
+---
+
+You are entering the **od-contribute** flow.
+
+User input (may be empty): `$ARGUMENTS`
+
+## What to do right now
+
+1. **Load the skill** by invoking the `od-contribute` skill via the Skill tool. The skill owns the full execution playbook — do not reimplement it inline.
+
+2. **Pass the user input forward**:
+   - If `$ARGUMENTS` is one of `skill`, `design-system`, `i18n`, `docs`, `bug` (or a recognizable Chinese / English equivalent), pre-select that branch and skip the type-picking `AskUserQuestion` in Step 2.
+   - Otherwise, the skill will ask the user via `AskUserQuestion`.
+
+3. **Honor the interactive contract**:
+   - Always run the prerequisite check first (`gh` installed + authed). If it fails, surface the install/auth hint and stop — do not try workarounds.
+   - Always show the preview + require explicit confirmation before pushing or opening any PR/issue.
+   - At the end, print the PR or issue URL on its own line so the user can click through.
+
+Begin by invoking the skill now.

.claude/skills/od-contribute/SKILL.md

@@ -0,0 +1,320 @@
+---
+name: od-contribute
+description: One-click contribution flow for Open Design (nexu-io/open-design) — even for non-coders. Pick one of four cards (ship a Skill or Design System you made with OD; translate docs; fix a typo / write a blog; report a bug), the agent validates and opens a PR (or issue) for you. Trigger words contribute to open design, ship my OD skill, ship my OD design system, translate OD docs, report an OD bug, od-contribute.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
+  - TaskCreate
+  - TaskUpdate
+  - WebFetch
+---
+
+# od-contribute — first-contribution flow for Open Design
+
+Locked to `nexu-io/open-design`. Branches by **contribution type**, not by issue. Replaces the dev-loop with type-specific no-code validators. Designed so a product user with zero coding background can ship a real PR.
+
+## Language
+
+Mirror the user's language in every user-facing message — `AskUserQuestion` labels and descriptions, status updates, error explanations. Detect from their first message; when uncertain, default to English.
+
+**Generated artifacts (PR titles, commit messages, PR/issue body files, branch names) MUST be English** regardless of the user's chat language. GitHub conventions, maintainer review, and search all assume English. The templates under `templates/` are already English — keep them that way when rendering.
+
+Scripts live under `scripts/`. Source the shared helpers from any script:
+
+```bash
+source "$(dirname "$0")/config.sh"
+```
+
+`SKILL_DIR` below = the directory that contains this `SKILL.md`.
+
+---
+
+## Step 1 — Prereq check (always first)
+
+```bash
+bash "$SKILL_DIR/scripts/check-prereqs.sh"
+```
+
+- Exit 0: capture `GH_USER=<login>` from stdout. Default `TARGET_FORK="${GH_USER}/open-design"`.
+- Exit 2: surface the printed install / auth hint **verbatim** and stop. Do not attempt token workarounds.
+
+If `gh repo view "$TARGET_FORK"` fails, ask the user (one `AskUserQuestion`) whether to fork now via `gh repo fork nexu-io/open-design --clone=false`. Default to yes.
+
+## Step 2 — Pick contribution type
+
+Single `AskUserQuestion` (header: "Contribution", multiSelect: false), four options. Translate option labels/descriptions into the user's chat language; the branch routing is unchanged.
+
+1. **🎨 Ship something I made with OD** — _a Skill, Design System, HyperFrame, or template I want to contribute upstream_ → branch `3a`
+2. **🌍 Translate OD docs** — _README / QUICKSTART / CONTRIBUTING into a new language_ → branch `3b`
+3. **📝 Fix docs / write a blog / fix a typo** — _typo fix, dead link, use-case writeup_ → branch `3c`
+4. **🐛 Report a bug** — _something broke; I'll help turn it into a high-quality issue_ → branch `3d` (issue path, no PR)
+
+Each branch below is self-contained. Steps 7–8 (preview + push) are shared across branches `3a`/`3b`/`3c`. Branch `3d` skips them entirely.
+
+---
+
+### Step 3a — OD product submission (Skill / Design System)
+
+**3a.1** Ask user: "What's the local path to the artifact you want to ship?" (single free-text, translated into the user's chat language). Common: a folder path (Skill) or a single `DESIGN.md` file (Design System).
+
+**3a.2** Sniff type:
+
+```bash
+# Skill: folder containing SKILL.md with frontmatter.
+# Design System: file matching DESIGN.md anatomy.
+```
+
+If ambiguous, ask the user to confirm.
+
+**3a.3** Run setup:
+
+```bash
+bash "$SKILL_DIR/scripts/setup-workspace.sh" skill <slug>
+# or
+bash "$SKILL_DIR/scripts/setup-workspace.sh" design-system <slug>
+```
+
+`<slug>` is `od::slugify` of the Skill `name` frontmatter field or of the brand name. Capture `WORKDIR` from stdout.
+
+**3a.4** Copy artifact into workspace at the right target dir:
+- Skill → `$WORKDIR/skills/<slug>/`
+- Design System → `$WORKDIR/design-systems/<brand-slug>/DESIGN.md` (+ any sibling assets in the same folder)
+
+**3a.5** Validate:
+
+```bash
+bash "$SKILL_DIR/scripts/validate-skill-submission.sh" "$WORKDIR/skills/<slug>"
+# or, with 1-2 reference DESIGN.md files passed in:
+bash "$SKILL_DIR/scripts/validate-design-system.sh" \
+  "$WORKDIR/design-systems/<slug>/DESIGN.md" \
+  --reference "$WORKDIR/design-systems/airbnb/DESIGN.md" \
+  --reference "$WORKDIR/design-systems/apple/DESIGN.md"
+```
+
+If validation fails, surface the FAIL lines verbatim, ask the user to fix, retry. **Never push a failing artifact.**
+
+**3a.6** Ask 3 short questions via `AskUserQuestion` (translate the labels into the user's chat language):
+- "What name should we credit you under in the PR?" — free-text
+- "One-line pitch for this Skill / Design System?" — free-text
+- "Path to a screenshot (optional)?" — free-text
+
+**3a.7** Render `templates/PR-BODY-skill.md` (or `PR-BODY-design-system.md`) with substitutions:
+- `{{SKILL_NAME}}`, `{{SKILL_SLUG}}` (or `{{BRAND_NAME}}`, `{{BRAND_SLUG}}`)
+- `{{PITCH}}` (the one-line)
+- `{{MOTIVATION}}` (free-text — agent can offer to draft this from the skill body, but user confirms)
+- `{{TRY_PROMPT}}` (a prompt they recommend trying — agent suggests a default, user confirms)
+- `{{SCREENSHOT_BLOCK}}` (Markdown image block if a screenshot path was given, else empty)
+- `{{DISCORD_INVITE}}` from `$OD_DISCORD_INVITE`
+
+Write to `$WORKDIR/.od-contrib/PR-BODY.md`.
+
+→ Jump to **Step 7**.
+
+---
+
+### Step 3b — i18n translation
+
+**3b.1** Setup workspace (slug = `translate-<doc>-<lang>` if known, else `translate`):
+
+```bash
+bash "$SKILL_DIR/scripts/setup-workspace.sh" i18n translate
+# capture WORKDIR
+```
+
+**3b.2** Discover gaps:
+
+```bash
+bash "$SKILL_DIR/scripts/discover-i18n-gaps.sh" "$WORKDIR" > /tmp/od-i18n-gaps.json
+```
+
+Each line is JSON. Rank by:
+- `status: "missing"` first (missing language is highest leverage)
+- then `status: "stale"` ordered by `english_commits_since_translation` desc
+- README family before QUICKSTART before CONTRIBUTING
+
+**3b.3** Take the top 3–4 gaps and present via `AskUserQuestion` (header: "Translation target"). Each option label like: `README → 한국어 (Korean)` / `QUICKSTART (zh-CN) refresh — 12 commits behind`. Translate the header text into the user's chat language but keep the option labels descriptive (the language names belong in their native script).
+
+**3b.4** Once user picks, **rename branch** to be specific:
+```bash
+git -C "$WORKDIR" branch -m "od-contrib/i18n/<doc>-<lang>-<date>"
+```
+(or pre-set the slug in step 3b.1 if the user confirmed earlier.)
+
+**3b.5** Translate. Read the English source. Translate **structure-preserving**:
+- Code blocks: leave untranslated
+- Brand / product names: leave untranslated
+- Filenames in inline code: leave untranslated
+- Image / link targets: leave untranslated; if a localized version of a linked doc exists, swap the link to the localized file
+- Headings: translate, keep the heading depth identical
+- Tables: translate cell text only, keep alignment / pipes
+
+Write the result to `$WORKDIR/<TRANSLATED_PATH>` (e.g. `QUICKSTART.es.md`). Show user a unified diff vs. the English source for visual sanity-check (line-count delta within ±15% is a healthy signal).
+
+**3b.6** Validate the translated file against the English source. The `--reference` flag tells the validator to ignore relative refs that were already broken in the source — OD docs frequently link to website route slugs (e.g. `skills/blog-post/`) that aren't files on disk; we don't want a structure-preserving translation to fail because of pre-existing dead refs.
+
+```bash
+bash "$SKILL_DIR/scripts/validate-markdown.sh" \
+  "$WORKDIR/<TRANSLATED_PATH>" \
+  --reference "$WORKDIR/<ENGLISH_PATH>"
+```
+
+If FAIL → surface verbatim, fix, retry.
+
+**3b.7** Render `templates/PR-BODY-i18n.md` with `{{DOC_NAME}}`, `{{LANG_DISPLAY_NAME}}`, `{{LANG_CODE}}`, `{{TRANSLATED_PATH}}`, `{{ENGLISH_PATH}}`, `{{STATUS}}`, `{{TRANSLATION_NOTES}}` (one paragraph from the agent: anything tricky, untranslated terms it kept, etc.), `{{DISCORD_INVITE}}`.
+
+→ **Step 7**.
+
+---
+
+### Step 3c — Docs / blog / typo
+
+**3c.1** Setup workspace (slug `docs`):
+
+```bash
+bash "$SKILL_DIR/scripts/setup-workspace.sh" docs <slug>
+```
+
+**3c.2** Ask user (one `AskUserQuestion`):
+1. **Auto-discover small fixes** (run discover-doc-gaps, pick something)
+2. **I have a specific fix in mind** (free-text)
+3. **I want to write a blog / case study** (free-text — what's the use case?)
+
+**3c.3 (Auto-discover branch)** Run:
+
+```bash
+bash "$SKILL_DIR/scripts/discover-doc-gaps.sh" "$WORKDIR" > /tmp/od-doc-gaps.json
+```
+
+Group by `kind` (typo / deadlink / todo). Show the user up to 6 candidates via `AskUserQuestion`. Once picked, apply the fix in code (typo: replace word; deadlink: ask user for the new URL; todo: that's a proper task, ask user to write the missing prose).
+
+**3c.4 (Specific-fix branch)** Read the file, apply user's described change. Confirm via diff.
+
+**3c.5 (Blog branch)** First check whether OD has a blog directory:
+
+```bash
+ls "$WORKDIR/docs" 2>/dev/null
+```
+
+If a `docs/blog/` or similar exists, place the new post there. If not, ask the user where it should live, defaulting to `docs/<slug>.md`. Generate an outline → user fills in user-specific bits (their use case, screenshots, the prompt they used, the rendered output) → agent stitches into a final Markdown.
+
+**3c.6** Validate every changed/added file. For files that already exist in the repo (typo fix, dead-link fix, doc edit), pass `--reference` pointing at HEAD's version so we only fail on relative refs the user *introduced*, not on pre-existing route slugs:
+
+```bash
+# For modifications to existing files:
+git -C "$WORKDIR" show "HEAD:<path>" > "/tmp/od-contrib-orig-<basename>" 2>/dev/null
+bash "$SKILL_DIR/scripts/validate-markdown.sh" \
+  "$WORKDIR/<changed-path>" \
+  --reference "/tmp/od-contrib-orig-<basename>"
+
+# For brand-new files (e.g. a blog post the user is creating from scratch),
+# omit --reference. The validator will skip the relative-ref check entirely
+# (since it can't tell route slugs from real paths in isolation).
+```
+
+**3c.7** Render `templates/PR-BODY-docs.md` with `{{ONE_LINE_SUMMARY}}`, `{{DETAILS}}`, `{{FILES_LIST}}`, `{{DISCORD_INVITE}}`.
+
+→ **Step 7**.
+
+---
+
+### Step 3d — Bug report (issue path, no PR)
+
+**3d.1** Read OD's actual schema at runtime to make sure we mirror it:
+
+```bash
+gh api "repos/${TARGET_REPO}/contents/.github/ISSUE_TEMPLATE/bug-report.yml" --jq .content | base64 -d > /tmp/od-bug-report.yml
+```
+
+If the schema has drifted from the template (`templates/ISSUE-BODY-bug.md`), regenerate the body to match.
+
+**3d.2** Ask the user via `AskUserQuestion`, one structured prompt per critical field. Use **plain language**, not the YAML field names:
+
+| Bug-report field | Prompt to user |
+|---|---|
+| `description` | "What went wrong? One sentence is fine." |
+| `steps` | "How can I reproduce it? Walk me through step by step." |
+| `expected` | "What did you expect to happen?" |
+| `version` | "Which OD version are you running? (About menu, or `od --version`)" |
+| `platform` | dropdown: macOS (Apple Silicon) / macOS (Intel) / Windows / Linux / Other |
+| `logs` | "Any error logs you can paste? Skip if you don't have them." |
+| `screenshots` | "Path to a screenshot? Skip if you don't have one." |
+
+Translate every prompt above into the user's chat language at runtime.
+
+**3d.3** Auto-collect what we can (these don't need to ask the user):
+- OS family from `uname`
+- Node version from `node -v` if relevant
+
+**3d.4** Dedupe: extract 3–5 keywords from the description, run:
+
+```bash
+gh search issues "<keywords>" --repo "$TARGET_REPO" --state open --limit 5 --json number,title,url
+```
+
+If matches exist, present them to the user via `AskUserQuestion` (translate to user's language): "These existing issues look related. Do you want to: (a) comment on an existing one, (b) open a new issue anyway, (c) cancel?"
+
+**3d.5** If proceeding with new issue, render `templates/ISSUE-BODY-bug.md` and submit:
+
+```bash
+bash "$SKILL_DIR/scripts/create-issue.sh" \
+  --title "$TITLE" \
+  --body-file "$WORKDIR_OR_TMP/.od-contrib/ISSUE-BODY.md" \
+  --dedupe-keywords "<keywords>"
+```
+
+**3d.6** Print the issue URL on its own line. **Do not** push branches or open PRs from this branch.
+
+---
+
+## Step 7 — Preview + confirm (shared, PR branches only)
+
+Show the user a clean summary:
+
+```text
+About to commit:
+  Branch:  od-contrib/<type>/<slug>-<date>
+  Files:
+    + skills/foo/SKILL.md            (1.2 KB)
+    + skills/foo/preview.png         (54 KB)
+  Push to:  <fork or upstream>
+  Open PR:  nexu-io/open-design:main ← <fork>:<branch>
+```
+
+Then `git -C "$WORKDIR" diff --stat` and a `head -40` of the rendered PR body for visual sanity.
+
+Required `AskUserQuestion` confirmation (translate to user's language): **"Push this PR?"** with three options:
+- **Ship it** — proceed to Step 8
+- **Let me revise** — return to the relevant Step 3 sub-step
+- **Cancel** — leave the workspace on disk, tell the user the path so they can return later, exit
+
+Never push without an explicit "Ship it".
+
+## Step 8 — Push & open PR
+
+```bash
+bash "$SKILL_DIR/scripts/create-pr.sh" \
+  --workdir "$WORKDIR" \
+  --type "<skill|design-system|i18n|docs>" \
+  --title "<PR title from references/newcomer-tone.md>" \
+  --body-file "$WORKDIR/.od-contrib/PR-BODY.md"
+```
+
+Print the PR URL on its own line. Done.
+
+---
+
+## Safety rails (mandatory)
+
+- Never push to `main` / `master` / `develop`. The push scripts refuse.
+- Never `--force` push. Just don't.
+- All workspace activity stays under `$OD_WORK_ROOT` (default `$HOME/od-contrib-work`). `od::assert_in_workroot` enforces this.
+- Bug-report path **always** runs the dedupe search before `gh issue create`.
+- Honor user memory: skip GitHub user `xxiaoxiong` from any contributor lookup ([[feedback_no_outreach_xxiaoxiong]]).
+
+## When NOT to use this skill
+
+- The user wants to fix a daemon / web bug or add a feature with code changes → use `auto-github-contributor` instead (it has the TDD loop). This skill deliberately doesn't run lint/typecheck/tests because content paths don't need them.
+- The user wants to *generate* a Skill / Design System from scratch → that's Open Design itself. Run OD first, get an artifact, then come back here to ship it.

.claude/skills/od-contribute/agents/openai.yaml

@@ -0,0 +1,13 @@
+# Codex CLI sidecar (optional). Adds a friendlier picker entry when this skill
+# is loaded by Codex from ~/.agents/skills/od-contribute/ or .agents/skills/.
+# Not required — Codex loads SKILL.md regardless.
+
+interface:
+  display_name: "Open Design — Contribute"
+  short_description: "Ship a Skill / Design System / translation / typo fix to nexu-io/open-design without writing code."
+  default_prompt: "I want to contribute to Open Design."
+
+policy:
+  # Allow Codex to surface this skill when the user mentions OD contribution
+  # without an explicit `$od-contribute` invocation. Keep on — it's the whole point.
+  allow_implicit_invocation: true

.claude/skills/od-contribute/install.sh

@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+# OD Contribute installer — self-bootstrapping.
+# Fetches the latest od-contribute skill from nexu-io/open-design and installs
+# it into every supported AI agent's home directory.
+#
+# Two ways to run this:
+#
+# 1) Tell your AI agent (Claude Code / Codex / Cursor / etc.) in the chat:
+#
+#      curl -sSL https://raw.githubusercontent.com/nexu-io/open-design/main/.claude/skills/od-contribute/install.sh | bash
+#
+#    The agent's Bash tool runs this. You never open a terminal yourself.
+#
+# 2) Or paste that same one-liner into a terminal directly, if you prefer.
+#
+# Targets installed:
+#   ~/.claude/skills/od-contribute/        Claude Code (native skill format)
+#   ~/.claude/commands/od-contribute.md    Claude Code slash command
+#   ~/.agents/skills/od-contribute/        Codex CLI (canonical path)
+#   ~/.codex/skills/od-contribute/         Codex CLI (legacy, only if ~/.codex exists)
+#
+# Override the source branch with OD_CONTRIBUTE_BRANCH=feat/foo (default: main).
+
+set -euo pipefail
+
+REPO="nexu-io/open-design"
+BRANCH="${OD_CONTRIBUTE_BRANCH:-main}"
+
+cyan()  { printf '\033[36m%s\033[0m\n' "$*"; }
+green() { printf '\033[32m%s\033[0m\n' "$*"; }
+gray()  { printf '\033[90m%s\033[0m\n' "$*"; }
+die()   { printf '\033[31m[error]\033[0m %s\n' "$*" >&2; exit 1; }
+
+cyan "Installing OD Contribute skill from ${REPO}@${BRANCH}..."
+
+command -v curl >/dev/null 2>&1 || die "curl is required."
+command -v tar  >/dev/null 2>&1 || die "tar is required."
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+# Tarball download — no `git clone` needed (works in env without git).
+TARBALL="$TMPDIR/repo.tar.gz"
+curl -fsSL "https://github.com/${REPO}/archive/refs/heads/${BRANCH}.tar.gz" -o "$TARBALL" \
+  || die "failed to fetch ${REPO}@${BRANCH} (branch may not exist)"
+
+# Extract just the two paths we need. GitHub tarballs name the root dir
+# <repo>-<branch>/, with slashes in branch names converted to dashes.
+TARBALL_ROOT="open-design-${BRANCH//\//-}"
+tar -xzf "$TARBALL" -C "$TMPDIR" \
+  "${TARBALL_ROOT}/.claude/skills/od-contribute" \
+  "${TARBALL_ROOT}/.claude/commands/od-contribute.md" \
+  2>/dev/null || die "skill files not found in tarball — branch may have different layout"
+
+SKILL_SRC="$TMPDIR/${TARBALL_ROOT}/.claude/skills/od-contribute"
+CMD_SRC="$TMPDIR/${TARBALL_ROOT}/.claude/commands/od-contribute.md"
+
+[[ -f "$SKILL_SRC/SKILL.md" ]] || die "SKILL.md missing at expected path"
+[[ -f "$CMD_SRC"             ]] || die "slash command missing at expected path"
+
+install_skill_to() {
+  local dest="$1" label="$2"
+
+  # Preserve user-local state across reinstall/upgrade. Re-running this script
+  # is the documented upgrade path ("re-run to pull the latest skill from
+  # main"), so anything the user wrote here that ISN'T part of the skill
+  # itself must survive `rm -rf`. Today that's just `.gh-token` (sandboxed
+  # agents like Codex.app / Cursor write a GitHub token here when they can't
+  # reach the macOS keychain — see check-prereqs.sh's hint and config.sh's
+  # fallback). Add new state filenames to PRESERVE if we ever introduce more.
+  local PRESERVE=(.gh-token)
+  local stash=""
+  local f
+  for f in "${PRESERVE[@]}"; do
+    if [[ -f "$dest/$f" ]]; then
+      [[ -z "$stash" ]] && stash="$(mktemp -d)"
+      cp -p "$dest/$f" "$stash/$f"
+    fi
+  done
+
+  rm -rf "$dest"
+  mkdir -p "$dest"
+  cp -R "$SKILL_SRC/." "$dest/"
+
+  # Restore preserved state. The mode preservation (`cp -p` above + this
+  # explicit chmod) keeps tokens at 600.
+  if [[ -n "$stash" ]]; then
+    for f in "${PRESERVE[@]}"; do
+      if [[ -f "$stash/$f" ]]; then
+        cp -p "$stash/$f" "$dest/$f"
+        chmod 600 "$dest/$f" 2>/dev/null || true
+      fi
+    done
+    rm -rf "$stash"
+  fi
+
+  # Ensure scripts retain executable bit (tar usually preserves; defense in depth).
+  find "$dest" -name '*.sh' -exec chmod +x {} + 2>/dev/null || true
+  green "  ✓ $label"
+  gray  "      $dest"
+}
+
+# --- Claude Code (native, always install) -----------------------------------
+install_skill_to "$HOME/.claude/skills/od-contribute" "Claude Code skill"
+mkdir -p "$HOME/.claude/commands"
+cp "$CMD_SRC" "$HOME/.claude/commands/od-contribute.md"
+green "  ✓ Claude Code slash command (/od-contribute)"
+gray  "      $HOME/.claude/commands/od-contribute.md"
+
+# --- Codex CLI (canonical) --------------------------------------------------
+install_skill_to "$HOME/.agents/skills/od-contribute" "Codex CLI skill (~/.agents/skills/)"
+
+# --- Codex CLI (legacy) — only if user already has Codex --------------------
+if [[ -d "$HOME/.codex" ]]; then
+  install_skill_to "$HOME/.codex/skills/od-contribute" "Codex CLI skill (legacy ~/.codex/skills/)"
+fi
+
+echo
+green "Done."
+echo
+cyan "How to use it:"
+cat <<'EOF'
+
+  In Claude Code:  type  /od-contribute  in any chat.
+  In Codex CLI:    type  @od-contribute  or pick "Open Design — Contribute" from /skills.
+  In other agents: ask the agent to follow ~/.claude/skills/od-contribute/SKILL.md
+
+The skill walks you through one of:
+
+  * shipping a Skill or Design System you made with Open Design
+  * translating a doc to a new language
+  * fixing a typo or writing a use-case blog
+  * reporting a clean bug
+
+Need help? Open Design Discord:  https://discord.gg/qhbcCH8Am4
+EOF

.claude/skills/od-contribute/references/design-system-anatomy.md

@@ -0,0 +1,51 @@
+# What an OD design-system folder looks like
+
+Reference for the `od-contribute` skill's `validate-design-system.sh` step.
+
+> **Authoritative source**: read 1–2 existing folders under `design-systems/` in `nexu-io/open-design` at runtime — the conventions evolve as new systems land.
+
+## Minimum viable design system
+
+```
+design-systems/<brand-slug>/
+└── DESIGN.md          # required — the brand brief OD loads
+```
+
+A few systems include extras: `components.html`, `tokens.css`. These are optional, referenced from `DESIGN.md` if present.
+
+## DESIGN.md structure (observed convention)
+
+H1 with the brand name, then a blockquote with category + one-sentence pitch, then numbered H2 sections. Looking at established systems (`airbnb`, `apple`, etc.), the typical section list is:
+
+```markdown
+# Design System Inspired by <Brand>
+
+> Category: <e.g. E-Commerce & Retail>
+> <one-sentence pitch>
+
+## 1. Visual Theme & Atmosphere
+## 2. Color Palette & Roles
+## 3. Typography
+## 4. Layout & Spacing
+## 5. Components
+## 6. Motion & Interaction
+## 7. Iconography & Imagery
+## 8. Voice & Tone
+## 9. Edge Cases & Variations
+```
+
+Section ordering and exact titles vary — the validator only checks **structural overlap with reference systems**, not exact heading text. ≥30% overlap with the union of headings from existing systems is enough to pass.
+
+## What the validator actually enforces
+
+1. File is non-empty and has at least one H1.
+2. ≥30% heading overlap with reference DESIGN.md files (when references are passed in).
+3. No `../` relative paths that would resolve outside `design-systems/<brand>/`.
+
+That's deliberately loose — DESIGN.md is a creative brief, not a schema.
+
+## Don'ts
+
+- Don't reference assets outside the brand folder.
+- Don't paste binary fonts; use a CSS `@font-face` reference and let OD resolve at runtime.
+- Don't use real customer logos / proprietary brand assets you don't have rights to (the validator won't catch this — it's a maintainer-review concern).

.claude/skills/od-contribute/references/newcomer-tone.md

@@ -0,0 +1,42 @@
+# Newcomer tone — voice rules for PR / issue text
+
+Per user feedback ([[feedback_outreach_minimal]]), keep it minimal. The PR body is the **only** place we get to shape the maintainer's first impression of this contributor — make it warm, brief, and useful.
+
+## Hard rules
+
+1. **Always end the PR body with two things:**
+   - "👋 This is my first OD contribution." (or a similar one-line warmth)
+   - The OD Discord invite: <https://discord.gg/qhbcCH8Am4> (read from `OD_DISCORD_INVITE` env, never hardcode)
+2. **Never claim more than the PR actually does.** A typo fix is a typo fix — don't dress it up as "improving documentation quality" or list 5 fake checkboxes.
+3. **Plain language only.** No "ergonomic", "DX", "stakeholder", "stack rank". Talk like a friendly user, not a startup blog.
+4. **No emojis except the opening 👋 and one optional 🎨 / 🌍 / 📝 / 🐛 in the title or first line.** OD is design-loving but the maintainers read a *lot* of PRs.
+
+## Soft rules
+
+- Lead with **what changed**, not why or how. Maintainers can read the diff for the how.
+- "Why" gets at most 2–3 sentences. If it needs more, the work is too big for this skill — open an issue instead.
+- One screenshot if the change is visible. Zero is fine.
+- The "checklist" should reflect what the validator actually checked, not a generic ceremonial list.
+
+## Anti-patterns (do not do these)
+
+- **Don't** write an "ask" section. Don't say "please review when you have time" — the PR is the ask.
+- **Don't** invite the maintainer to call / DM you. Discord is the channel.
+- **Don't** apologize. ("Sorry if this isn't right" — the maintainer will tell you if it isn't.)
+- **Don't** include a "TL;DR" — if the summary needs a TL;DR, the summary is too long.
+
+## Title conventions (for `git commit` and `gh pr create --title`)
+
+| Type | Format | Example |
+|---|---|---|
+| Skill | `Add Skill: <name>` | `Add Skill: invoice-template` |
+| Design System | `Add Design System: <brand>` | `Add Design System: notion` |
+| i18n | `Translate <doc> to <Lang>` | `Translate QUICKSTART to Spanish` |
+| i18n (refresh) | `Update <Lang> translation of <doc>` | `Update zh-CN translation of README` |
+| Docs typo | `Fix typo in <file>` | `Fix typo in README.md` |
+| Docs other | `<verb> <noun> in <where>` | `Clarify daemon setup in QUICKSTART` |
+| Bug (issue title) | `<observed> on <surface>` | `Preview iframe is blank on Safari 17` |
+
+## When to ask before writing
+
+If the user wants to ship something whose tone is unusual (a manifesto blog post, a contentious refactor, naming a brand after a real company without rights), pause and ask the user. Better to skip the PR than ship something the maintainer will close politely.

.claude/skills/od-contribute/references/od-repo-map.md

@@ -0,0 +1,38 @@
+# OD repo map — what goes where
+
+Mirrors `nexu-io/open-design` `CONTRIBUTING.md` so the skill doesn't need to re-fetch it on every run. **If this drifts from upstream CONTRIBUTING.md, upstream wins** — re-read the live file when in doubt.
+
+## Three high-leverage contribution surfaces (per OD's CONTRIBUTING.md)
+
+| If you want to… | You're really adding | Where it lives | Ship size |
+|---|---|---|---|
+| Make OD render a new kind of artifact | a **Skill** | `skills/<your-skill>/` | one folder, ~2 files |
+| Make OD speak a new brand's visual language | a **Design System** | `design-systems/<brand>/DESIGN.md` | one Markdown file |
+| Hook up a new coding-agent CLI | an **Agent adapter** | `apps/daemon/src/agents.ts` | ~10 lines (code — out of scope for this skill) |
+| Improve docs, port a section to fr / de / zh-CN, fix typos | docs | `README.md`, `README.fr.md`, `README.de.md`, `README.zh-CN.md`, `docs/`, `QUICKSTART.md` | one PR |
+
+## Localized doc files we know about
+
+| Doc family | English source | Translations seen on disk (as of plan time) |
+|---|---|---|
+| README | `README.md` | ar, de, es, fr, ja-JP, ko, pt-BR, ru, tr, uk, zh-CN, zh-TW |
+| QUICKSTART | `QUICKSTART.md` | de, fr, ja-JP, pt-BR, zh-CN, zh-TW |
+| CONTRIBUTING | `CONTRIBUTING.md` | de, fr, ja-JP, pt-BR, zh-CN |
+| MAINTAINERS | `MAINTAINERS.md` | de, fr, ja-JP, pt-BR, zh-CN |
+
+The skill `discover-i18n-gaps.sh` does NOT trust this table — it scans the workspace at runtime. Use this list only when you need to seed an `AskUserQuestion` card without a workspace.
+
+## Issue templates
+
+- `bug-report.yml` — required fields: description, steps to reproduce, expected, version, platform.
+- `feature-request.yml` — out of scope for this skill (feature requests should come from product, not auto-routed.)
+- `preview-v0.8.0-feedback.yml` — branch-specific.
+
+## Out-of-scope surfaces (don't touch from this skill)
+
+- `apps/daemon/src/` — daemon code. Requires real review.
+- `apps/web/src/` — web app code. Requires real review.
+- `packages/`, `plugins/`, `tools/` — internal libs.
+- `e2e/` — Playwright-driven; non-trivial to author.
+
+If a user asks to contribute to those surfaces, suggest the original `auto-github-contributor` skill (TDD pipeline) instead.

.claude/skills/od-contribute/references/skill-anatomy.md

@@ -0,0 +1,53 @@
+# What an OD skill folder looks like
+
+Reference for the `od-contribute` skill's `validate-skill-submission.sh` step and for guiding a user through assembling a Skill submission.
+
+> **Authoritative source**: read 1–2 existing folders under `skills/` in `nexu-io/open-design` at runtime — conventions evolve faster than this doc.
+
+## Minimum viable skill
+
+```
+skills/<your-skill>/
+└── SKILL.md          # required, must have YAML frontmatter
+```
+
+That's it. Many of the simplest skills in OD are exactly that: one Markdown file in one folder.
+
+## Frontmatter — what `validate-skill-submission.sh` requires
+
+```yaml
+---
+name: <kebab-case-slug>           # required; usually matches the folder name
+description: |                    # required; one paragraph; what the skill does in user terms
+  Generate and iterate ad creative including headlines, descriptions, and primary text.
+triggers:                         # optional but strongly recommended
+  - "ad creative"
+  - "ad headline"
+od:                               # optional; OD-specific metadata
+  mode: design-system             # or other modes; check existing skills
+  category: <category-slug>
+  upstream: "https://github.com/..."  # if the skill was lifted from somewhere
+---
+```
+
+**Required by validator**: `name`, `description`. Everything else is convention.
+
+## Body conventions (after the frontmatter)
+
+Looking at existing skills, the typical body has:
+
+1. `# <skill-name>` H1.
+2. A one-line "what it does" sentence.
+3. Optional `## Source` block when adapted from upstream (with attribution).
+4. `## How to use` with one or two example prompts the user might type.
+
+## When a skill folder needs more than `SKILL.md`
+
+- **Reference assets** — long prompt fragments, example outputs, image references — go alongside `SKILL.md` in the same folder, referenced via relative paths in `SKILL.md`.
+- **Subfolders** are fine: the validator only requires that every relative reference inside `SKILL.md` resolves and that no path escapes the skill folder.
+
+## Don'ts
+
+- Don't put runtime code in here. Skills are *content* — Markdown + maybe assets. Code adapters live in `apps/daemon/src/`.
+- Don't reference files outside `skills/<your-skill>/` — that breaks portability.
+- Don't put binaries you don't need (the lighter the folder, the easier the review).

.claude/skills/od-contribute/scripts/check-prereqs.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Verify required tools + gh auth before the skill starts.
+# Exit 0  = ready (prints GH_USER=... and READY=1 to stdout)
+# Exit 2  = missing prereq, hint printed to stderr; skill should surface it verbatim.
+
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/config.sh"
+
+# config.sh runs with `set -e` for its own callers, but this script wants the
+# OPPOSITE behavior: continue checking all prereqs even when one fails so we
+# can surface the full diagnostic in one shot rather than aborting at the
+# first miss. Restore -uo pipefail without -e after sourcing.
+set +e
+set -uo pipefail
+
+# Skill root, used in the auth-failure hint below to tell the user where to
+# drop a .gh-token file if they're stuck in a sandboxed agent.
+_OD_SKILL_DIR_HINT="$(cd "$(dirname "$0")/.." && pwd)"
+
+STATUS=0
+MISSING=()
+HINTS=()
+
+check_bin() {
+  local bin="$1" install_hint="$2"
+  if command -v "$bin" >/dev/null 2>&1; then
+    printf '  ✓ %s\n' "$bin" >&2
+  else
+    printf '  ✗ %s (not installed)\n' "$bin" >&2
+    MISSING+=("$bin")
+    HINTS+=("$install_hint")
+    STATUS=2
+  fi
+}
+
+printf '[od-contrib] checking prerequisites...\n' >&2
+
+OS="$(uname -s)"
+case "$OS" in
+  Darwin) GH_HINT="brew install gh" ;;
+  Linux)  GH_HINT="see https://github.com/cli/cli#installation (e.g. 'sudo apt install gh' or 'brew install gh')" ;;
+  *)      GH_HINT="see https://github.com/cli/cli#installation" ;;
+esac
+
+check_bin gh   "$GH_HINT"
+check_bin git  "install git for your OS"
+check_bin jq   "$( [[ $OS == Darwin ]] && echo 'brew install jq' || echo 'sudo apt install jq  (or brew install jq)' )"
+
+if ((${#MISSING[@]} > 0)); then
+  printf '\n[od-contrib][error] missing required tools: %s\n' "${MISSING[*]}" >&2
+  printf '\nInstall hints:\n' >&2
+  for i in "${!MISSING[@]}"; do
+    printf '  - %s: %s\n' "${MISSING[$i]}" "${HINTS[$i]}" >&2
+  done
+  exit 2
+fi
+
+# Two acceptable auth paths:
+#   1. `gh auth status` succeeds (gh has a token in keychain or hosts.yml)
+#   2. GH_TOKEN env var is set (config.sh loaded it from .gh-token, or caller exported it)
+# Path 2 matters for sandboxed runtimes (Codex.app, Cursor, etc.) where gh
+# CAN'T reach macOS keychain due to App Sandbox restrictions.
+if [[ -n "${GH_TOKEN:-}" ]]; then
+  # Verify the token actually works against the API.
+  if ! gh api user --jq .login >/dev/null 2>&1; then
+    printf '[od-contrib][error] GH_TOKEN is set but gh api call failed (token expired?).\n' >&2
+    printf '[od-contrib][error] Refresh the token: from a terminal run  gh auth refresh  or replace the .gh-token file.\n' >&2
+    exit 2
+  fi
+elif ! gh auth status >/dev/null 2>&1; then
+  cat >&2 <<EOF
+
+[od-contrib][error] No GitHub credentials available.
+
+Two ways to fix this:
+
+  Option A (one-time, works for any agent):
+    From a regular terminal, run:
+      gh auth login
+    Pick GitHub.com → HTTPS → browser login. Need 'repo' scope.
+
+  Option B (for sandboxed agents like Codex.app / Cursor that can't reach
+  the macOS keychain):
+    From a regular terminal where gh IS authenticated, run:
+      gh auth token > "$_OD_SKILL_DIR_HINT/.gh-token"
+      chmod 600 "$_OD_SKILL_DIR_HINT/.gh-token"
+    The skill will pick up the token automatically next run.
+EOF
+  exit 2
+fi
+
+# Resolve the authenticated login. Fail closed if this can't be done — even
+# with `gh auth status` green, `gh api user` can fail when the token has
+# insufficient scopes, has been revoked, or GitHub is unreachable. Returning
+# a fabricated GH_USER like `?` would propagate to TARGET_FORK and cause
+# downstream pushes to point at `?/open-design`, so we'd rather stop here.
+GH_USER="$(gh api user --jq .login 2>/dev/null)"
+if [[ -z "$GH_USER" ]]; then
+  cat >&2 <<'EOF'
+
+[od-contrib][error] gh auth check passed but `gh api user` could not resolve a login.
+
+Common causes:
+  - The token has insufficient scopes (need at least 'repo')
+  - The token has been revoked or expired since the session started
+  - GitHub API is unreachable
+
+Refresh the token with the right scopes and retry:
+
+  gh auth refresh -s repo
+EOF
+  exit 2
+fi
+
+printf '  ✓ gh authed as %s\n' "$GH_USER" >&2
+printf '  ✓ target locked to %s\n' "$OD_TARGET_REPO" >&2
+
+printf 'GH_USER=%s\n' "$GH_USER"
+printf 'READY=1\n'

.claude/skills/od-contribute/scripts/config.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Shared config for the od-contribute skill.
+# TARGET_REPO is hard-locked to nexu-io/open-design — this skill is OD-specific.
+#
+# Override via env vars before invoking a script:
+#   TARGET_FORK   "<owner>/<name>"  push branches here. Defaults to $GH_USER/open-design at runtime.
+#   OD_BASE_BRANCH                   default: main
+#   OD_WORK_ROOT                     default: $HOME/od-contrib-work
+#   OD_DISCORD_INVITE                default: https://discord.gg/qhbcCH8Am4
+
+set -euo pipefail
+
+readonly OD_TARGET_REPO="nexu-io/open-design"
+TARGET_REPO="$OD_TARGET_REPO"
+
+: "${TARGET_FORK:=}"
+: "${OD_BASE_BRANCH:=main}"
+: "${OD_WORK_ROOT:="$HOME/od-contrib-work"}"
+: "${OD_DISCORD_INVITE:=https://discord.gg/qhbcCH8Am4}"
+
+# Sandboxed-agent fallback for gh auth.
+# Codex.app, Cursor, and other macOS App Sandbox runtimes can't reach the
+# system keychain where `gh auth login` stores the token by default. If
+# GH_TOKEN isn't already set in the env, look for a token file shipped
+# alongside the skill. The skill never *creates* this file automatically —
+# it must be written by either:
+#   - a one-time `gh auth token > <skill>/.gh-token` from a non-sandboxed shell, or
+#   - the OAuth Device Flow bootstrap (TODO: implement for non-coder users).
+_OD_SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+if [[ -z "${GH_TOKEN:-}" && -f "$_OD_SKILL_DIR/.gh-token" ]]; then
+  GH_TOKEN="$(tr -d '[:space:]' < "$_OD_SKILL_DIR/.gh-token")"
+  export GH_TOKEN
+fi
+unset _OD_SKILL_DIR
+
+export TARGET_REPO TARGET_FORK OD_BASE_BRANCH OD_WORK_ROOT OD_DISCORD_INVITE
+
+od::log()  { printf '[od-contrib] %s\n' "$*" >&2; }
+od::warn() { printf '[od-contrib][warn] %s\n' "$*" >&2; }
+od::err()  { printf '[od-contrib][error] %s\n' "$*" >&2; }
+od::die()  { od::err "$*"; exit 1; }
+
+od::require() {
+  command -v "$1" >/dev/null 2>&1 || od::die "missing dependency: $1"
+}
+
+od::slugify() {
+  local s="${1:-}"
+  s="$(printf '%s' "$s" | tr '[:upper:]' '[:lower:]')"
+  s="$(printf '%s' "$s" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//')"
+  printf '%s' "${s:0:48}"
+}
+
+od::workdir_for() {
+  # $1 = a slug for this contribution session (e.g. "skill-foo-2026-05-28")
+  printf '%s/%s\n' "$OD_WORK_ROOT" "$1"
+}
+
+# Refuse to operate outside $OD_WORK_ROOT (defense against runaway scripts).
+od::assert_in_workroot() {
+  local path="$1"
+  case "$path" in
+    "$OD_WORK_ROOT"/*) return 0 ;;
+    *) od::die "refusing to operate on path outside OD_WORK_ROOT: $path" ;;
+  esac
+}

.claude/skills/od-contribute/scripts/create-issue.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# Create a bug-report issue on nexu-io/open-design from a rendered body file.
+# Usage:
+#   create-issue.sh --title "<issue title>" --body-file <rendered .md>
+#                   [--allow-duplicates] [--dedupe-keywords "<kw>"]
+#
+# Dedupe gate (now actually a gate, not a print):
+#   - If --dedupe-keywords is supplied, the script runs `gh search issues`
+#     FIRST and writes the matches to stderr.
+#   - If any matches are found AND --allow-duplicates was NOT passed, the
+#     script EXITS NON-ZERO with a clear hint and refuses to call
+#     `gh issue create`. This lets the agent (per SKILL.md Step 3d.4) show
+#     the matches to the user and only re-invoke with --allow-duplicates
+#     after the user explicitly chose "open a new issue anyway".
+#   - If `gh search` ITSELF fails (network, rate limit, jq parse error),
+#     the script also exits non-zero. Failing closed is the right default
+#     for a bug-dedupe gate — we'd rather block creation than open
+#     potentially redundant issues silently.
+#
+# Caller contract (matches SKILL.md):
+#   1. Run with --dedupe-keywords on first attempt; show output to user.
+#   2. If exit is non-zero with REASON=duplicates_found, ask the user.
+#   3. If user picks "open anyway", re-run WITHOUT --dedupe-keywords (or
+#      WITH --allow-duplicates). The script then creates the issue.
+#
+# Emits the issue URL on its own line (stdout) on success.
+
+set -euo pipefail
+source "$(dirname "$0")/config.sh"
+
+TITLE=""
+BODY_FILE=""
+DEDUPE_KEYWORDS=""
+ALLOW_DUPES=0
+
+while (($#)); do
+  case "$1" in
+    --title)            TITLE="$2"; shift 2 ;;
+    --body-file)        BODY_FILE="$2"; shift 2 ;;
+    --dedupe-keywords)  DEDUPE_KEYWORDS="$2"; shift 2 ;;
+    --allow-duplicates) ALLOW_DUPES=1; shift ;;
+    *) od::die "unknown flag: $1" ;;
+  esac
+done
+
+[[ -n "$TITLE"     ]] || od::die "--title required"
+[[ -f "$BODY_FILE" ]] || od::die "--body-file does not exist: $BODY_FILE"
+
+od::require gh
+od::require jq
+
+if [[ -n "$DEDUPE_KEYWORDS" && "$ALLOW_DUPES" -eq 0 ]]; then
+  od::log "checking for duplicates: $DEDUPE_KEYWORDS"
+
+  # Run gh search and jq as separate steps so a failure in either is loud
+  # rather than swallowed by `|| true`. The previous implementation chained
+  # them with `|| true`, which let a network or jq error mask "no duplicates"
+  # vs "search broken" — both produced empty output and the script then
+  # created the issue regardless.
+  if ! SEARCH_JSON="$(gh search issues "$DEDUPE_KEYWORDS" \
+        --repo "$TARGET_REPO" \
+        --state open \
+        --limit 5 \
+        --json number,title,url 2>&1)"; then
+    od::err "gh search failed: $SEARCH_JSON"
+    printf 'REASON=search_failed\n' >&2
+    exit 2
+  fi
+
+  MATCH_COUNT="$(printf '%s' "$SEARCH_JSON" | jq -r 'length' 2>/dev/null || echo 'parse-error')"
+  if [[ "$MATCH_COUNT" == "parse-error" ]]; then
+    od::err "could not parse gh search output as JSON"
+    printf 'REASON=parse_failed\n' >&2
+    exit 2
+  fi
+
+  if (( MATCH_COUNT > 0 )); then
+    printf '%s' "$SEARCH_JSON" \
+      | jq -r '.[] | "  #\(.number)  \(.title)\n           \(.url)"' >&2
+    od::err "${MATCH_COUNT} potentially duplicate open issue(s) found."
+    od::err "Refusing to create a new issue. Show these to the user and ask:"
+    od::err "  (a) comment on an existing one — open the URL above"
+    od::err "  (b) open a new issue anyway — re-run with --allow-duplicates"
+    od::err "  (c) cancel — do nothing"
+    printf 'REASON=duplicates_found\n' >&2
+    printf 'MATCH_COUNT=%s\n' "$MATCH_COUNT" >&2
+    exit 3
+  fi
+
+  od::log "no duplicates found — proceeding with create"
+fi
+
+URL="$(gh issue create \
+  --repo "$TARGET_REPO" \
+  --title "$TITLE" \
+  --body-file "$BODY_FILE" \
+  --label bug)" || od::die "gh issue create failed"
+
+printf '\n'
+printf '%s\n' "$URL"

.claude/skills/od-contribute/scripts/create-pr.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Commit, push, and open a PR against nexu-io/open-design.
+# Usage: create-pr.sh --workdir <dir> --type <skill|design-system|i18n|docs> \
+#                     --title "<pr title>" --body-file <rendered PR body .md>
+#
+# Reads:
+#   <workdir>/.od-contrib/contributor.txt   (display name; optional)
+#   <workdir>/.od-contrib/pitch.txt         (one-line pitch; optional)
+# Emits PR URL on its own line at the end (stdout).
+
+set -euo pipefail
+source "$(dirname "$0")/config.sh"
+
+WORKDIR=""
+TYPE=""
+TITLE=""
+BODY_FILE=""
+DRAFT=""
+
+while (($#)); do
+  case "$1" in
+    --workdir)   WORKDIR="$2"; shift 2 ;;
+    --type)      TYPE="$2"; shift 2 ;;
+    --title)     TITLE="$2"; shift 2 ;;
+    --body-file) BODY_FILE="$2"; shift 2 ;;
+    --draft)     DRAFT="--draft"; shift ;;
+    *) od::die "unknown flag: $1" ;;
+  esac
+done
+
+[[ -n "$WORKDIR"   ]] || od::die "--workdir required"
+[[ -n "$TYPE"      ]] || od::die "--type required (skill|design-system|i18n|docs)"
+[[ -n "$TITLE"     ]] || od::die "--title required"
+[[ -f "$BODY_FILE" ]] || od::die "--body-file does not exist: $BODY_FILE"
+[[ -d "$WORKDIR/.git" ]] || od::die "not a git workdir: $WORKDIR"
+
+od::require gh
+od::require git
+
+cd "$WORKDIR"
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+
+case "$BRANCH" in
+  main|master|develop) od::die "refusing to push base branch '$BRANCH'" ;;
+esac
+
+# 1) Stage + commit if there are changes. Use a non-jargon commit message.
+#
+# Use `git status --porcelain` rather than `git diff --quiet` because the latter
+# ignores untracked files. The most common contribution shape — a brand-new
+# Skill folder, translation file, or doc — is 100% untracked at this point;
+# any predicate that misses untracked paths would silently push an empty PR.
+#
+# Belt-and-suspenders against the skill's internal scratch dir leaking into
+# the user's contribution PR: setup-workspace.sh adds `.od-contrib/` to
+# .git/info/exclude, but in case this script is invoked against a workdir
+# set up differently, also pass `:!.od-contrib` as a pathspec exclude so
+# nothing under .od-contrib/ gets staged here.
+SCRATCH_EXCLUDE=':!:.od-contrib'
+if [[ -n "$(git status --porcelain -- . "$SCRATCH_EXCLUDE")" ]]; then
+  git add -A -- . "$SCRATCH_EXCLUDE"
+  # If even after `git add` the index is clean (e.g., changes were only in
+  # ignored paths or symlink mode bits), skip the commit instead of erroring.
+  if git diff --cached --quiet; then
+    od::log "no real changes after staging — skipping commit"
+  else
+    git commit -m "$TITLE"
+    od::log "created commit"
+  fi
+else
+  od::log "nothing new to commit (assuming work was already committed)"
+fi
+
+# 2) Decide push remote. Prefer fork.
+PUSH_REMOTE="origin"
+if [[ -n "${TARGET_FORK}" ]] && git remote | grep -q '^fork$'; then
+  PUSH_REMOTE="fork"
+else
+  od::warn "no fork configured (TARGET_FORK empty) — pushing to upstream ${TARGET_REPO}. 3s to abort..."
+  sleep 3 || true
+fi
+
+od::log "pushing to ${PUSH_REMOTE}/${BRANCH}"
+git push -u "$PUSH_REMOTE" "$BRANCH"
+
+# 3) Pick label set per contribution type. (OD's labels: documentation, i18n, blog, enhancement, ...)
+LABELS=()
+case "$TYPE" in
+  skill)         LABELS+=("good first issue" "enhancement") ;;
+  design-system) LABELS+=("good first issue" "enhancement") ;;
+  i18n)          LABELS+=("i18n" "documentation") ;;
+  docs)          LABELS+=("documentation") ;;
+esac
+
+LABEL_FLAGS=()
+for L in "${LABELS[@]}"; do
+  LABEL_FLAGS+=(--label "$L")
+done
+
+# 4) Open the PR. `gh pr create` automatically picks `head` from the pushed branch.
+HEAD_REF="$BRANCH"
+if [[ "$PUSH_REMOTE" == "fork" && -n "$TARGET_FORK" ]]; then
+  HEAD_REF="${TARGET_FORK%%/*}:${BRANCH}"
+fi
+
+PR_URL="$(gh pr create \
+  --repo "$TARGET_REPO" \
+  --base "$OD_BASE_BRANCH" \
+  --head "$HEAD_REF" \
+  --title "$TITLE" \
+  --body-file "$BODY_FILE" \
+  ${DRAFT} \
+  "${LABEL_FLAGS[@]}")" || od::die "gh pr create failed"
+
+printf '\n'
+printf '%s\n' "$PR_URL"

.claude/skills/od-contribute/scripts/discover-doc-gaps.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# Find low-effort doc improvements in nexu-io/open-design.
+# Usage: discover-doc-gaps.sh <workdir>
+# Stdout: NDJSON rows. Three classes:
+#   {"kind":"todo","file":"docs/foo.md","line":42,"text":"TODO: explain the daemon"}
+#   {"kind":"typo","file":"README.md","line":17,"word":"recieve","suggested":"receive"}
+#   {"kind":"deadlink","file":"docs/bar.md","line":3,"url":"https://example.com/x","status":"404"}
+#
+# Dead-link checks are best-effort: timeout 8s, only reports 4xx/5xx/timeout, not network errors.
+
+set -uo pipefail
+source "$(dirname "$0")/config.sh"
+
+WORKDIR="${1:?workdir required}"
+[[ -d "$WORKDIR/.git" ]] || od::die "not a git workdir: $WORKDIR"
+
+cd "$WORKDIR"
+od::require jq
+
+# Use ripgrep when present for speed; fall back to grep -rE.
+if command -v rg >/dev/null 2>&1; then
+  GREP() { rg --no-heading --line-number --color never "$@"; }
+else
+  GREP() {
+    # Translate a couple of rg flags we use to grep-equivalents.
+    local args=()
+    while (($#)); do
+      case "$1" in
+        --no-heading|--color) shift ;;
+        --color=never) shift ;;
+        --line-number) args+=("-n"); shift ;;
+        *) args+=("$1"); shift ;;
+      esac
+    done
+    grep -rE "${args[@]}"
+  }
+fi
+
+# 1) TODOs / FIXMEs in docs.
+emit_todo() {
+  while IFS=: read -r file line rest; do
+    [[ -z "$file" ]] && continue
+    jq -nc --arg file "$file" --argjson line "$line" --arg text "$rest" \
+      '{kind:"todo", file:$file, line:$line, text:($text|sub("^[[:space:]]+";""))}'
+  done
+}
+
+GREP --no-heading --line-number --color never -e 'TODO|FIXME|XXX' \
+  -g '*.md' docs/ README*.md QUICKSTART*.md CONTRIBUTING*.md 2>/dev/null \
+  | emit_todo || true
+
+# Fallback path for environments where rg --glob isn't available — grep equivalent.
+if ! command -v rg >/dev/null 2>&1; then
+  grep -rEn -- 'TODO|FIXME|XXX' docs README*.md QUICKSTART*.md CONTRIBUTING*.md 2>/dev/null \
+    | emit_todo || true
+fi
+
+# 2) Common typos. Whole-word match, case-sensitive (avoid false positives in code/links).
+TYPOS=(
+  "teh|the"
+  "recieve|receive"
+  "seperate|separate"
+  "occured|occurred"
+  "succesful|successful"
+  "untill|until"
+  "wich|which"
+  "thier|their"
+  "alot|a lot"
+  "definately|definitely"
+  "neccessary|necessary"
+  "enviroment|environment"
+  "transparant|transparent"
+  "appearence|appearance"
+)
+
+for entry in "${TYPOS[@]}"; do
+  bad="${entry%%|*}"
+  good="${entry##*|}"
+  while IFS=: read -r file line _rest; do
+    [[ -z "$file" ]] && continue
+    # Skip code blocks (rough heuristic: skip if line is inside ```).
+    jq -nc --arg file "$file" --argjson line "$line" --arg word "$bad" --arg good "$good" \
+      '{kind:"typo", file:$file, line:$line, word:$word, suggested:$good}'
+  done < <(GREP --no-heading --line-number --color never -e "\\b${bad}\\b" -g '*.md' . 2>/dev/null \
+           || grep -rEn "\\b${bad}\\b" --include='*.md' . 2>/dev/null \
+           || true)
+done
+
+# 3) External link health (best-effort, capped).
+# Cap to 50 links per run so we don't hammer arbitrary hosts.
+MAX_LINKS=50
+SEEN=0
+extract_links() {
+  GREP --no-heading --line-number --color never -e '\]\(https?://[^) ]+\)' -g '*.md' . 2>/dev/null \
+    || grep -rEn '\]\(https?://[^) ]+\)' --include='*.md' . 2>/dev/null
+}
+
+while IFS= read -r row; do
+  [[ "$SEEN" -ge "$MAX_LINKS" ]] && break
+  file="${row%%:*}"
+  rest="${row#*:}"
+  line="${rest%%:*}"
+  text="${rest#*:}"
+  # Extract first http(s) URL on the line.
+  url="$(printf '%s' "$text" | grep -oE 'https?://[^) ]+' | head -1)"
+  [[ -z "$url" ]] && continue
+  SEEN=$((SEEN+1))
+  # HEAD with 8s timeout, follow redirects, take final status.
+  status="$(curl -sS -o /dev/null -m 8 -L -w '%{http_code}' --head "$url" 2>/dev/null || echo "000")"
+  case "$status" in
+    2*|3*) ;;  # OK
+    000) ;;    # network/timeout — skip rather than spam false positives
+    *)
+      jq -nc --arg file "$file" --argjson line "$line" --arg url "$url" --arg status "$status" \
+        '{kind:"deadlink", file:$file, line:$line, url:$url, status:$status}'
+      ;;
+  esac
+done < <(extract_links | head -n "$MAX_LINKS")

.claude/skills/od-contribute/scripts/discover-i18n-gaps.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Find translation gaps in nexu-io/open-design.
+# Usage: discover-i18n-gaps.sh <workdir>
+# Stdout: NDJSON, one row per gap:
+#   {"doc":"README","english":"README.md","lang":"es","translated":null,"status":"missing"}
+#   {"doc":"QUICKSTART","english":"QUICKSTART.md","lang":"zh-CN","translated":"QUICKSTART.zh-CN.md","status":"stale","english_mtime":"...","translated_mtime":"...","english_commits_since":12}
+#
+# A "stale" translation is one whose last-touched commit is older than the most recent
+# commit touching the English source. Ranking is left to the caller (the agent).
+
+set -euo pipefail
+source "$(dirname "$0")/config.sh"
+
+WORKDIR="${1:?workdir required}"
+[[ -d "$WORKDIR/.git" ]] || od::die "not a git workdir: $WORKDIR"
+
+cd "$WORKDIR"
+od::require git
+od::require jq
+
+# Translatable English source files we care about (top-level docs).
+ENGLISH_DOCS=(README.md QUICKSTART.md CONTRIBUTING.md MAINTAINERS.md TRANSLATIONS.md PRIVACY.md)
+
+# Common language suffixes seen in OD's tree (extend as the project grows).
+LANGS=(zh-CN zh-TW ja-JP de fr es ko ru pt-BR tr uk ar)
+
+# Languages already represented for a given doc are detected from disk;
+# the LANGS array is what we *offer* to a contributor when no translation exists.
+
+last_commit_epoch() {
+  # Last commit touching $1 — empty string if file has never been committed.
+  git log -1 --format=%ct -- "$1" 2>/dev/null || true
+}
+
+commits_between() {
+  # How many commits touched $newer that are NOT ancestors of $older_ref's tip
+  # commit. Uses commit ancestry rather than `--since=<epoch>` math because
+  # `--since` is inclusive of the boundary epoch — so when English source and
+  # translation are touched in the SAME commit (very common: bulk i18n
+  # refresh, structural change applied across all translations), `--since`
+  # would count that shared commit and mark the translation "stale" by 1.
+  #
+  # `tr_sha..HEAD -- $newer` reads as: "commits reachable from HEAD but not
+  # from tr_sha, that touched $newer". When tr_sha is HEAD's tip for $newer
+  # too (same-commit update), the answer is correctly 0.
+  local newer="$1" older_ref="$2"
+  local tr_sha
+  tr_sha="$(git log -1 --format=%H -- "$older_ref" 2>/dev/null)"
+  if [[ -z "$tr_sha" ]]; then
+    # Translation never committed; count all history of $newer.
+    git log --format=%H -- "$newer" 2>/dev/null | wc -l | tr -d ' '
+  else
+    git rev-list "${tr_sha}..HEAD" -- "$newer" 2>/dev/null | wc -l | tr -d ' '
+  fi
+}
+
+emit() {
+  jq -nc \
+    --arg doc "$1" --arg english "$2" --arg lang "$3" \
+    --arg translated "$4" --arg status "$5" \
+    --arg en_epoch "$6" --arg tr_epoch "$7" --arg en_commits_since "$8" \
+    '{
+      doc: $doc, english: $english, lang: $lang,
+      translated: ($translated | select(length>0)),
+      status: $status,
+      english_mtime_epoch: ($en_epoch | select(length>0) | tonumber? // null),
+      translated_mtime_epoch: ($tr_epoch | select(length>0) | tonumber? // null),
+      english_commits_since_translation: ($en_commits_since | tonumber? // null)
+    }'
+}
+
+for english in "${ENGLISH_DOCS[@]}"; do
+  [[ -f "$english" ]] || continue
+  doc="${english%.md}"
+  en_epoch="$(last_commit_epoch "$english")"
+
+  # Track observed languages for this doc as a newline-delimited string.
+  # Avoids `declare -A` (associative arrays), which requires Bash 4 — macOS
+  # ships with Bash 3.2 by default and most agent-spawned bash subprocesses
+  # inherit that. The leading + trailing newlines let us match `\n<lang>\n`
+  # without false positives on prefix overlap (e.g. zh vs zh-CN).
+  SEEN_LANGS=$'\n'
+
+  while IFS= read -r -d '' translated; do
+    # Filename pattern: <DOC>.<lang>.md  (e.g. README.zh-CN.md).
+    # `find . ... -print0` emits paths with a leading `./`; strip that first
+    # and operate on the basename so the prefix-strip below works regardless.
+    base="${translated#./}"
+    base="$(basename "$base")"
+    lang_part="${base#${doc}.}"
+    lang_part="${lang_part%.md}"
+    [[ -z "$lang_part" || "$lang_part" == "$base" ]] && continue
+    SEEN_LANGS+="${lang_part}"$'\n'
+
+    tr_epoch="$(last_commit_epoch "$translated")"
+    if [[ -z "$tr_epoch" ]]; then
+      emit "$doc" "$english" "$lang_part" "$translated" "untracked" "$en_epoch" "" ""
+      continue
+    fi
+    en_commits_since="$(commits_between "$english" "$translated")"
+    if [[ "$en_commits_since" -gt 0 ]]; then
+      emit "$doc" "$english" "$lang_part" "$translated" "stale" "$en_epoch" "$tr_epoch" "$en_commits_since"
+    fi
+    # else: up-to-date, skip emission entirely.
+  done < <(find . -maxdepth 1 -type f -name "${doc}.*.md" -print0)
+
+  # Then, for each language in LANGS that we didn't see, emit a "missing" row.
+  for lang in "${LANGS[@]}"; do
+    case "$SEEN_LANGS" in
+      *$'\n'"$lang"$'\n'*) continue ;;
+    esac
+    emit "$doc" "$english" "$lang" "" "missing" "$en_epoch" "" ""
+  done
+done

.claude/skills/od-contribute/scripts/setup-workspace.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# Clone (or reuse) nexu-io/open-design in an isolated workdir + create a feature branch.
+# Usage: setup-workspace.sh <type> <slug>
+#   <type>  one of: skill | design-system | i18n | docs
+#   <slug>  short kebab-case identifier (e.g. "translate-readme-es", "fix-typo-quickstart")
+#
+# Env: TARGET_FORK optional (else pushes go to upstream — create-pr.sh warns first).
+#
+# Stdout (machine-readable):
+#   WORKDIR=<abs path>
+#   BRANCH=<branch name>
+
+set -euo pipefail
+source "$(dirname "$0")/config.sh"
+
+TYPE="${1:?type required (skill|design-system|i18n|docs)}"
+SLUG="${2:?slug required}"
+
+case "$TYPE" in
+  skill|design-system|i18n|docs) ;;
+  *) od::die "unknown type: $TYPE (expected skill|design-system|i18n|docs)" ;;
+esac
+
+od::require gh
+od::require git
+
+# Use second-precision timestamp so two contribution sessions on the same day
+# (or the SKILL.md i18n flow that calls setup-workspace.sh with a placeholder
+# slug like "translate" before the user has picked a language) don't collide
+# into the same workdir. Reusing a workdir would leak untracked / half-edited
+# files from an earlier abandoned session into a later contribution.
+SESSION_TAG="$(date +%Y%m%d-%H%M%S)"
+SESSION_DIR="${TYPE}-${SLUG}-${SESSION_TAG}"
+WORKDIR="$(od::workdir_for "$SESSION_DIR")"
+BRANCH="od-contrib/${TYPE}/${SLUG}-${SESSION_TAG}"
+
+mkdir -p "$OD_WORK_ROOT"
+od::assert_in_workroot "$WORKDIR"
+
+CLONE_URL="https://github.com/${TARGET_REPO}.git"
+
+if [[ -d "$WORKDIR/.git" ]]; then
+  # We reach here only if the user explicitly resumed by passing the same
+  # SESSION_TAG, or if the wall clock somehow produced a duplicate. Clean any
+  # untracked/dirty state so the run starts from a known good base instead of
+  # inheriting whatever the previous occupant left behind.
+  od::log "reusing existing workdir: $WORKDIR"
+  git -C "$WORKDIR" fetch origin --prune
+  git -C "$WORKDIR" reset --hard HEAD
+  git -C "$WORKDIR" clean -fdx
+else
+  od::log "cloning $CLONE_URL → $WORKDIR (depth 50)"
+  git clone --depth 50 "$CLONE_URL" "$WORKDIR"
+fi
+
+# Tell git to ignore our internal scratch dir so `git add -A` later (in
+# create-pr.sh) doesn't accidentally stage type.txt, slug.txt, PR-BODY.md
+# into the user's contribution PR. .git/info/exclude is repo-local and not
+# committed, so we don't pollute the OD repo's .gitignore.
+mkdir -p "$WORKDIR/.git/info"
+if ! grep -qxF '.od-contrib/' "$WORKDIR/.git/info/exclude" 2>/dev/null; then
+  printf '\n# od-contribute scratch dir (added by setup-workspace.sh)\n.od-contrib/\n' \
+    >> "$WORKDIR/.git/info/exclude"
+fi
+
+git -C "$WORKDIR" checkout "$OD_BASE_BRANCH"
+git -C "$WORKDIR" pull --ff-only origin "$OD_BASE_BRANCH"
+
+# Configure fork remote if provided.
+if [[ -n "${TARGET_FORK}" ]]; then
+  if git -C "$WORKDIR" remote | grep -q '^fork$'; then
+    git -C "$WORKDIR" remote set-url fork "https://github.com/${TARGET_FORK}.git"
+  else
+    git -C "$WORKDIR" remote add fork "https://github.com/${TARGET_FORK}.git"
+  fi
+fi
+
+# Create or reset branch off latest base.
+if git -C "$WORKDIR" show-ref --verify --quiet "refs/heads/$BRANCH"; then
+  od::log "branch $BRANCH already exists — switching"
+  git -C "$WORKDIR" checkout "$BRANCH"
+else
+  git -C "$WORKDIR" checkout -b "$BRANCH" "$OD_BASE_BRANCH"
+fi
+
+mkdir -p "$WORKDIR/.od-contrib"
+printf '%s\n' "$TYPE" > "$WORKDIR/.od-contrib/type.txt"
+printf '%s\n' "$SLUG" > "$WORKDIR/.od-contrib/slug.txt"
+
+od::log "workspace ready"
+printf 'WORKDIR=%s\n' "$WORKDIR"
+printf 'BRANCH=%s\n' "$BRANCH"

.claude/skills/od-contribute/scripts/validate-design-system.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# Validate a user-supplied DESIGN.md (Open Design "design system" submission).
+# Usage: validate-design-system.sh <DESIGN.md path> [--reference <existing-DESIGN.md>]
+#
+# Strategy: instead of hardcoding a schema, we read 1-3 existing DESIGN.md files
+# from the OD repo at runtime to learn which top-level sections are conventional,
+# then check the new file has at least those sections (case-insensitive H1/H2 match).
+#
+# Heuristic-only: warns rather than fails on missing optional sections; only fails
+# when the file is empty, unparseable, or has zero structural overlap with samples.
+
+set -uo pipefail
+source "$(dirname "$0")/config.sh"
+
+NEW_FILE="${1:?DESIGN.md path required}"
+shift || true
+
+REFERENCE_FILES=()
+while (($#)); do
+  case "$1" in
+    --reference) REFERENCE_FILES+=("$2"); shift 2 ;;
+    *) od::die "unknown flag: $1" ;;
+  esac
+done
+
+[[ -f "$NEW_FILE" ]] || od::die "not a file: $NEW_FILE"
+[[ -s "$NEW_FILE" ]] || od::die "file is empty: $NEW_FILE"
+
+extract_headings() {
+  # Pull H1/H2 lines, lowercase, trim, dedupe.
+  awk '/^#{1,2}[[:space:]]+/ { sub(/^#{1,2}[[:space:]]+/, ""); print tolower($0) }' "$1" \
+    | sed -E 's/[[:space:]]+$//' | sort -u
+}
+
+new_headings="$(extract_headings "$NEW_FILE")"
+[[ -n "$new_headings" ]] || { printf 'FAIL  no H1/H2 headings found in %s — is this really a design system doc?\n' "$NEW_FILE"; printf 'RESULT=fail\n'; exit 1; }
+
+# If references were supplied, build the union of their headings as the "expected" set.
+EXPECTED=""
+for ref in "${REFERENCE_FILES[@]}"; do
+  [[ -f "$ref" ]] || continue
+  EXPECTED+=$'\n'"$(extract_headings "$ref")"
+done
+EXPECTED="$(printf '%s' "$EXPECTED" | grep -v '^$' | sort -u || true)"
+
+PASS=0
+WARN=0
+FAIL=0
+
+if [[ -z "$EXPECTED" ]]; then
+  printf 'WARN  no reference DESIGN.md provided — running structure-only checks\n'
+  WARN=$((WARN+1))
+else
+  # Count overlap. >= 30% structural overlap = looks like a design system.
+  overlap=0
+  total=0
+  while IFS= read -r h; do
+    [[ -z "$h" ]] && continue
+    total=$((total+1))
+    if printf '%s\n' "$new_headings" | grep -Fxq "$h"; then
+      overlap=$((overlap+1))
+    fi
+  done <<< "$EXPECTED"
+
+  if [[ "$total" -eq 0 ]]; then
+    printf 'WARN  references parsed but had no headings\n'; WARN=$((WARN+1))
+  else
+    pct=$(( overlap * 100 / total ))
+    if [[ "$pct" -ge 30 ]]; then
+      printf 'PASS  structural overlap with reference DESIGN.md files: %d%% (%d/%d)\n' "$pct" "$overlap" "$total"
+      PASS=$((PASS+1))
+    else
+      printf 'FAIL  structural overlap with reference DESIGN.md files only %d%% (%d/%d) — likely missing required sections\n' "$pct" "$overlap" "$total"
+      FAIL=$((FAIL+1))
+    fi
+  fi
+fi
+
+# Always-on lightweight checks:
+if grep -qE '^(#)[[:space:]]+' "$NEW_FILE"; then
+  printf 'PASS  has at least one H1 heading\n'; PASS=$((PASS+1))
+else
+  printf 'WARN  no H1 heading found — convention is one H1 with the brand/system name\n'; WARN=$((WARN+1))
+fi
+
+# No relative path escape (../).
+if grep -nE '\(\.\./' "$NEW_FILE" >/dev/null; then
+  printf 'WARN  contains ../ relative paths — make sure they resolve once placed at design-systems/<brand>/DESIGN.md\n'; WARN=$((WARN+1))
+fi
+
+if [[ "$FAIL" -eq 0 ]]; then
+  printf 'RESULT=pass (passes=%d warns=%d)\n' "$PASS" "$WARN"
+  exit 0
+else
+  printf 'RESULT=fail (passes=%d warns=%d fails=%d)\n' "$PASS" "$WARN" "$FAIL"
+  exit 1
+fi

.claude/skills/od-contribute/scripts/validate-markdown.sh

@@ -0,0 +1,205 @@
+#!/usr/bin/env bash
+# Lightweight Markdown validation for i18n / docs / blog contributions.
+#
+# Usage: validate-markdown.sh <file> [<file> ...] [--reference <orig>]
+#
+# Checks per file:
+#   - File is non-empty.
+#   - Code fences are balanced (count of ``` is even).
+#   - Newly-introduced relative refs that don't resolve on disk fail.
+#     Refs that ALREADY exist in the --reference file (the English source for
+#     a translation, or HEAD's version for a docs edit) are NOT failed even
+#     if they don't resolve — many OD docs reference website-router slugs
+#     like `skills/blog-post/` that aren't files in the checked-out repo.
+#   - External http(s) links return 2xx/3xx (best-effort, capped, 8s timeout).
+#
+# Without --reference, relative-ref checking is skipped entirely (since we
+# can't tell route slugs from file paths in isolation). The other checks
+# still run.
+
+set -uo pipefail
+source "$(dirname "$0")/config.sh"
+set +e
+set -uo pipefail  # restore the "accumulate diagnostics" stance after sourcing.
+
+REFERENCE=""
+FILES=()
+while (($#)); do
+  case "$1" in
+    --reference) REFERENCE="$2"; shift 2 ;;
+    --) shift; while (($#)); do FILES+=("$1"); shift; done ;;
+    -*) od::die "unknown flag: $1" ;;
+    *) FILES+=("$1"); shift ;;
+  esac
+done
+
+(( ${#FILES[@]} >= 1 )) || od::die "usage: validate-markdown.sh <file> [<file> ...] [--reference <orig>]"
+
+# Build the "already-broken in source" set of relative refs (newline-delimited
+# string for Bash 3 compatibility — no associative arrays). Anything in this
+# set is excused from failing the new-file check.
+KNOWN_DEAD=$'\n'
+if [[ -n "$REFERENCE" ]]; then
+  if [[ ! -f "$REFERENCE" ]]; then
+    od::warn "--reference $REFERENCE does not exist; ignoring."
+  else
+    ref_dir="$(cd "$(dirname "$REFERENCE")" && pwd -P)"
+    while IFS= read -r ref; do
+      [[ -z "$ref" ]] && continue
+      case "$ref" in http*|mailto:*|\#*|/*) continue ;; esac
+      target="${ref%%#*}"; target="${target%%\?*}"
+      [[ -z "$target" ]] && continue
+      if [[ ! -e "$ref_dir/$target" ]]; then
+        KNOWN_DEAD+="${ref}"$'\n'
+      fi
+    done < <(grep -oE '\!?\[[^]]*\]\([^)]+\)' "$REFERENCE" 2>/dev/null \
+             | sed -E 's/.*\(([^)]+)\).*/\1/' \
+             | sort -u)
+  fi
+fi
+
+OVERALL=0
+MAX_HTTP_PER_FILE=20
+
+check_file() {
+  local f="$1"
+  local fail=0
+  printf -- '--- %s ---\n' "$f"
+
+  if [[ ! -f "$f" ]]; then
+    printf 'FAIL  not a file: %s\n' "$f"
+    return 1
+  fi
+  if [[ ! -s "$f" ]]; then
+    printf 'FAIL  empty file: %s\n' "$f"
+    return 1
+  fi
+  printf 'PASS  exists, non-empty\n'
+
+  # Code fence balance.
+  local fences
+  fences="$(grep -cE '^```' "$f" 2>/dev/null)"
+  if (( fences % 2 == 0 )); then
+    printf 'PASS  code fences balanced (%d)\n' "$fences"
+  else
+    printf 'FAIL  unbalanced code fences (%d ``` lines)\n' "$fences"
+    fail=1
+  fi
+
+  # Relative refs — tiered check:
+  #
+  #   Image refs (![alt](path)) — always validate. No website route uses
+  #   image-syntax markdown; if it doesn't resolve on disk, it's broken.
+  #
+  #   Link refs starting with ./ or ../ — always validate. Explicit relative
+  #   paths are unambiguously file references, not router slugs.
+  #
+  #   Other link refs (e.g. `skills/blog-post/`) — only validated when
+  #   --reference is supplied (we excuse refs already broken in the source).
+  #   Without --reference we skip these because OD docs use slug-style refs
+  #   for website routes that don't resolve to files in the checkout.
+  #
+  # In all cases, refs already broken in --reference (when supplied) are
+  # excused from failure rather than reported as regressions.
+  local dir rel_bad=0 rel_excused=0 rel_skipped_ambiguous=0
+  dir="$(cd "$(dirname "$f")" && pwd -P)"
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    # `!?` in grep keeps the leading `!` for image refs; case-detect here.
+    is_img=0
+    case "$entry" in '!'*) is_img=1 ;; esac
+    # Extract URL: between first `(` and last `)`.
+    ref="${entry#*\(}"
+    ref="${ref%\)*}"
+    case "$ref" in http*|mailto:*|\#*|/*) continue ;; esac
+    target="${ref%%#*}"; target="${target%%\?*}"
+    [[ -z "$target" ]] && continue
+
+    # Should we validate this ref?
+    if (( is_img == 0 )); then
+      case "$ref" in
+        ./*|../*) ;;  # explicit relative — always validate
+        *)
+          # File-like targets (have an obvious file extension) are unambiguously
+          # on-disk references — `[doc](missing.md)` is not a website route, it
+          # is a sibling file. Validate without --reference. Otherwise (no
+          # extension, looks like a slug), only validate when we have a
+          # reference to compare against.
+          case "${target##*/}" in
+            *.md|*.markdown|*.mdx \
+            |*.png|*.jpg|*.jpeg|*.gif|*.webp|*.svg|*.ico|*.bmp \
+            |*.pdf|*.txt|*.json|*.yaml|*.yml|*.toml \
+            |*.sh|*.ts|*.tsx|*.js|*.jsx|*.css|*.html|*.xml \
+            |*.csv|*.zip|*.gz)
+              ;;  # file-like — always validate
+            *)
+              if [[ -z "$REFERENCE" ]]; then
+                rel_skipped_ambiguous=$((rel_skipped_ambiguous+1))
+                continue
+              fi
+              ;;
+          esac
+          ;;
+      esac
+    fi
+
+    if [[ ! -e "$dir/$target" ]]; then
+      case "$KNOWN_DEAD" in
+        *$'\n'"$ref"$'\n'*) rel_excused=$((rel_excused+1)) ;;
+        *)
+          printf 'FAIL  broken relative reference: %s\n' "$ref"
+          rel_bad=$((rel_bad+1))
+          fail=1
+          ;;
+      esac
+    fi
+  done < <(grep -oE '!?\[[^]]*\]\([^)]+\)' "$f" 2>/dev/null | sort -u)
+
+  if (( rel_bad == 0 )); then
+    msg="PASS  relative refs OK"
+    (( rel_excused > 0 )) && msg+=" (${rel_excused} pre-existing dead refs kept as-is)"
+    (( rel_skipped_ambiguous > 0 )) && msg+=" (${rel_skipped_ambiguous} slug-style refs skipped — pass --reference to check)"
+    printf '%s\n' "$msg"
+  fi
+
+  # External link health (best-effort).
+  local http_seen=0 http_bad=0
+  while IFS= read -r url; do
+    [[ -z "$url" ]] && continue
+    (( http_seen >= MAX_HTTP_PER_FILE )) && break
+    http_seen=$((http_seen+1))
+    local code
+    code="$(curl -sS -o /dev/null -m 8 -L -w '%{http_code}' --head "$url" 2>/dev/null)"
+    [[ -z "$code" ]] && code="000"
+    case "$code" in
+      2*|3*|000) ;;  # OK, or network-flaky — don't punish.
+      *)
+        printf 'FAIL  external link %s returned %s\n' "$url" "$code"
+        http_bad=$((http_bad+1))
+        fail=1
+        ;;
+    esac
+  # URL extraction: stop at whitespace, ), ", ', <, >, [, ]. HTML <img src="..."> in
+  # OD docs would otherwise leak a trailing quote into the URL and cause false 404s.
+  done < <(grep -oE 'https?://[^][[:space:]"'\''<>)]+' "$f" 2>/dev/null | sort -u)
+
+  if (( http_bad == 0 && http_seen > 0 )); then
+    printf 'PASS  %d external links return 2xx/3xx (or network-skipped)\n' "$http_seen"
+  fi
+
+  return "$fail"
+}
+
+for f in "${FILES[@]}"; do
+  if ! check_file "$f"; then
+    OVERALL=1
+  fi
+done
+
+if [[ "$OVERALL" -eq 0 ]]; then
+  printf 'RESULT=pass\n'
+  exit 0
+else
+  printf 'RESULT=fail\n'
+  exit 1
+fi

.claude/skills/od-contribute/scripts/validate-skill-submission.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Validate a user-supplied OD skill folder before staging it for PR.
+# Usage: validate-skill-submission.sh <skill-folder>
+# Checks (each prints PASS/FAIL line on stdout):
+#   - SKILL.md exists
+#   - SKILL.md has frontmatter with `name` and `description`
+#   - `name` matches folder name (warn-only, since OD may rename on merge)
+#   - all relative paths in SKILL.md resolve to files inside the folder
+#   - no path escapes the skill folder (../ in references)
+# Exit 0 = all PASS or only warnings. Exit 1 = at least one FAIL.
+
+set -uo pipefail
+source "$(dirname "$0")/config.sh"
+
+SKILL_DIR="${1:?skill folder path required}"
+[[ -d "$SKILL_DIR" ]] || od::die "not a directory: $SKILL_DIR"
+
+ABS_SKILL_DIR="$(cd "$SKILL_DIR" && pwd -P)"
+FAIL=0
+
+pass() { printf 'PASS  %s\n' "$1"; }
+warn() { printf 'WARN  %s\n' "$1"; }
+fail() { printf 'FAIL  %s\n' "$1"; FAIL=1; }
+
+SKILL_MD="$ABS_SKILL_DIR/SKILL.md"
+if [[ ! -f "$SKILL_MD" ]]; then
+  fail "SKILL.md missing — every OD skill folder must contain SKILL.md at its root"
+  printf 'RESULT=%s\n' "fail"
+  exit 1
+fi
+pass "SKILL.md exists"
+
+# Frontmatter parse: extract YAML between the first two '---' lines.
+#
+# The opening fence MUST be on line 1 — both Claude Code's loader and Codex
+# CLI's loader (codex-rs/core-skills) parse the top of the file, so a SKILL.md
+# that starts with prose, a BOM, or whitespace and only contains a `---` block
+# later will load as having no frontmatter, even if this validator picks it up.
+# Reject leading content explicitly so the validator can't pass a file the
+# real loaders will reject.
+FIRST_LINE="$(head -n 1 "$SKILL_MD")"
+if [[ ! "$FIRST_LINE" =~ ^---[[:space:]]*$ ]]; then
+  fail "SKILL.md must start with a YAML frontmatter fence ('---') on line 1 — found: $(printf '%q' "$FIRST_LINE" | head -c 80)"
+  printf 'RESULT=%s\n' "fail"
+  exit 1
+fi
+
+FRONT=$(awk '
+  BEGIN { in_fm=0; fence=0 }
+  /^---[[:space:]]*$/ {
+    fence++
+    if (fence==1) { in_fm=1; next }
+    if (fence==2) { exit }
+  }
+  in_fm { print }
+' "$SKILL_MD")
+
+if [[ -z "$FRONT" ]]; then
+  fail "SKILL.md has a leading '---' but no closing fence or empty frontmatter"
+else
+  pass "SKILL.md frontmatter present"
+
+  name_line="$(printf '%s' "$FRONT" | grep -E '^name:' | head -1 || true)"
+  desc_line="$(printf '%s' "$FRONT" | grep -E '^description:' | head -1 || true)"
+  [[ -n "$name_line" ]] && pass "frontmatter has 'name'" || fail "frontmatter missing 'name:'"
+  [[ -n "$desc_line" ]] && pass "frontmatter has 'description'" || fail "frontmatter missing 'description:'"
+
+  # Sanity: name should look like a slug.
+  fm_name="$(printf '%s' "$name_line" | sed -E 's/^name:[[:space:]]*//; s/^["'\''"]//; s/["'\''"]$//')"
+  folder_name="$(basename "$ABS_SKILL_DIR")"
+  if [[ -n "$fm_name" && "$fm_name" != "$folder_name" ]]; then
+    warn "frontmatter name '$fm_name' differs from folder name '$folder_name' (maintainer may rename — OK)"
+  fi
+fi
+
+# Relative path scan: every non-URL, non-anchor markdown link target must
+# resolve inside the skill folder.
+#
+# We extract ALL markdown links (`[label](target)`) and filter out URLs and
+# anchors here, rather than only matching dot-prefixed paths in the regex.
+# Plain intra-skill references like `[ref](references/foo.md)` or
+# `[script](scripts/run.sh)` are common and must be validated too — the
+# contract for SKILL.md says every relative path resolves on disk, regardless
+# of whether the author wrote `./references/foo.md` or `references/foo.md`.
+# A narrower `\(\.{1,2}/...\)` pattern would silently let bare paths through.
+BAD_REFS=0
+ESCAPE=0
+# Lexical escape check: count path segments and ensure no prefix walks above
+# the skill root. We do this on the literal target rather than from `cd … &&
+# pwd -P` so that a missing intermediate directory (which is itself a fail
+# we want to report) doesn't masquerade as an escape.
+escapes_root() {
+  local p="$1" depth=0 seg
+  # Strip a leading "./" if present.
+  p="${p#./}"
+  IFS='/' read -r -a _segs <<< "$p"
+  for seg in "${_segs[@]}"; do
+    case "$seg" in
+      ''|.) ;;
+      ..)   depth=$((depth-1)); (( depth < 0 )) && return 0 ;;
+      *)    depth=$((depth+1)) ;;
+    esac
+  done
+  return 1
+}
+while IFS= read -r ref; do
+  # Skip protocol URLs, mailto, anchors-only, and absolute paths.
+  case "$ref" in
+    http*|https*|mailto:*|tel:*|\#*|/*) continue ;;
+  esac
+  # Strip query and fragment components before resolving.
+  target="${ref%%#*}"
+  target="${target%%\?*}"
+  [[ -z "$target" ]] && continue
+  if escapes_root "$target"; then
+    ESCAPE=1
+    fail "path escapes skill folder: $ref"
+    continue
+  fi
+  if [[ ! -e "$ABS_SKILL_DIR/$target" ]]; then
+    BAD_REFS=$((BAD_REFS+1))
+    fail "referenced file does not exist: $ref"
+  fi
+done < <(grep -oE '\!?\[[^]]*\]\([^)]+\)' "$SKILL_MD" 2>/dev/null \
+         | sed -E 's/.*\(([^)]+)\).*/\1/' \
+         | sort -u)
+
+if [[ "$BAD_REFS" -eq 0 && "$ESCAPE" -eq 0 ]]; then
+  pass "all relative references resolve inside the skill folder"
+fi
+
+if [[ "$FAIL" -eq 0 ]]; then
+  printf 'RESULT=%s\n' "pass"
+  exit 0
+else
+  printf 'RESULT=%s\n' "fail"
+  exit 1
+fi

.claude/skills/od-contribute/templates/ISSUE-BODY-bug.md

@@ -0,0 +1,37 @@
+### What happened?
+
+{{WHAT_HAPPENED}}
+
+### Steps to reproduce
+
+{{STEPS}}
+
+### Expected behavior
+
+{{EXPECTED}}
+
+### Open Design version
+
+{{OD_VERSION}}
+
+### Platform
+
+{{PLATFORM}}
+
+### Logs (optional)
+
+```
+{{LOGS}}
+```
+
+### Screenshots (optional)
+
+{{SCREENSHOTS}}
+
+### Additional context
+
+{{CONTEXT}}
+
+---
+
+_Reported via the `od-contribute` skill. If you can reproduce or have more context, please add a comment — every signal helps narrow the fix._

.claude/skills/od-contribute/templates/PR-BODY-design-system.md

@@ -0,0 +1,37 @@
+## What this PR adds
+
+A new Design System — **{{BRAND_NAME}}** — at `design-systems/{{BRAND_SLUG}}/DESIGN.md`.
+
+> {{PITCH}}
+
+## What this design system covers
+
+{{COVERAGE_NOTES}}
+
+## How to try it
+
+1. `cd open-design`
+2. `pnpm tools-dev run web`
+3. Start a new project and pick **{{BRAND_NAME}}** from the design system picker.
+4. Ask the model: _"{{TRY_PROMPT}}"_
+
+{{SCREENSHOT_BLOCK}}
+
+## What's in this PR
+
+- `design-systems/{{BRAND_SLUG}}/DESIGN.md` — the canonical design brief OD loads.
+- Any supporting assets in `design-systems/{{BRAND_SLUG}}/` are referenced from `DESIGN.md`.
+
+## Checklist
+
+- [x] DESIGN.md has the conventional sections (compared against existing OD design systems)
+- [x] No `../` path escapes outside the brand folder
+- [ ] Maintainer review
+
+---
+
+👋 This is my first OD contribution. Hi! If anything looks off, tell me what to change and I'll happily push a fixup commit.
+
+If you want to chat (or you're another newcomer reading this and want help shipping your first PR), come hang out in the OD Discord: {{DISCORD_INVITE}}
+
+_Generated with the `od-contribute` skill._

.claude/skills/od-contribute/templates/PR-BODY-docs.md

@@ -0,0 +1,32 @@
+## What this PR fixes
+
+{{ONE_LINE_SUMMARY}}
+
+## Details
+
+{{DETAILS}}
+
+<!--
+Use this for the body when there's nuance:
+- which file/section
+- the exact sentence/typo/dead link
+- what you replaced it with and why
+-->
+
+## Files touched
+
+{{FILES_LIST}}
+
+## Checklist
+
+- [x] Markdown still parses cleanly (no broken fences or structure)
+- [x] All links and image paths still resolve
+- [ ] Maintainer review
+
+---
+
+👋 This is my first OD contribution. Hi! Small fix, but I figured every typo / dead link costs the next reader 30 seconds, and this saves that.
+
+If you want to chat or there's something you'd love help getting fixed, come find us in the OD Discord: {{DISCORD_INVITE}}
+
+_Generated with the `od-contribute` skill._

.claude/skills/od-contribute/templates/PR-BODY-i18n.md

@@ -0,0 +1,41 @@
+## What this PR translates
+
+**{{DOC_NAME}}** → **{{LANG_DISPLAY_NAME}}** (`{{LANG_CODE}}`)
+
+- New file: `{{TRANSLATED_PATH}}`
+- Source: `{{ENGLISH_PATH}}`
+- Status: {{STATUS}}  <!-- "missing" (new translation) or "stale" (refreshed) -->
+
+## What I preserved
+
+- Every Markdown structure element (headings, lists, tables, callouts, link/image targets)
+- Code blocks — left untranslated
+- Brand names and product names — left untranslated
+- Internal cross-links — adjusted to point to the localized file when one exists, else to the English source
+
+## What I changed
+
+{{TRANSLATION_NOTES}}
+
+## How to verify
+
+```bash
+# Render preview locally
+cd open-design
+# (or just open the .md file in any Markdown viewer)
+```
+
+## Checklist
+
+- [x] Markdown parses cleanly (code fences balanced, no broken structure)
+- [x] All relative links and image paths still resolve
+- [x] External links return 2xx/3xx
+- [ ] Maintainer review
+
+---
+
+👋 This is my first OD contribution. I'm a native {{LANG_DISPLAY_NAME}} speaker (or close to it!) and want to help OD reach more people in my language.
+
+If you want to chat or you're another translator reading this, come find us in the OD Discord: {{DISCORD_INVITE}}
+
+_Generated with the `od-contribute` skill._

.claude/skills/od-contribute/templates/PR-BODY-skill.md

@@ -0,0 +1,37 @@
+## What this PR adds
+
+A new Skill — **{{SKILL_NAME}}** — at `skills/{{SKILL_SLUG}}/`.
+
+> {{PITCH}}
+
+## Why I made it
+
+{{MOTIVATION}}
+
+## How to try it
+
+1. `cd open-design`
+2. Run OD locally: `pnpm tools-dev run web`
+3. Open a project, start a chat, and ask: _"{{TRY_PROMPT}}"_
+
+{{SCREENSHOT_BLOCK}}
+
+## What's in this PR
+
+- `skills/{{SKILL_SLUG}}/SKILL.md` — the skill itself (frontmatter + instructions)
+- everything else inside `skills/{{SKILL_SLUG}}/` is referenced from `SKILL.md`
+
+## Checklist
+
+- [x] `SKILL.md` has a `name` and `description` in the frontmatter
+- [x] Every relative path in `SKILL.md` resolves
+- [x] No path escapes the skill folder
+- [ ] Maintainer review
+
+---
+
+👋 This is my first OD contribution. Hi! If anything looks off, tell me what to change and I'll happily push a fixup commit.
+
+If you want to chat (or you're another newcomer reading this and want help shipping your first PR), come hang out in the OD Discord: {{DISCORD_INVITE}}
+
+_Generated with the `od-contribute` skill._

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -64,13 +64,15 @@ body:
   - type: textarea
     id: logs
     attributes:
-      label: Logs / screenshots (optional)
-      description: |
-        If relevant, paste any error output, console logs, or screenshots.
-        For daemon logs, run `pnpm tools-dev logs --json`.
+      label: Logs (optional)
+      description: Paste any error output or console logs. For daemon logs, run `pnpm tools-dev logs --json`.
       render: shell
-    validations:
-      required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots (optional)
+      description: Drag and drop or paste images here to show the visual bug.
 
   - type: textarea
     id: context

.github/actionlint.yaml

@@ -0,0 +1,10 @@
+paths:
+  .github/workflows/*.lock.yml:
+    ignore:
+      - 'shellcheck reported issue in this script: SC2016:.+'
+      - 'shellcheck reported issue in this script: SC2086:.+'
+self-hosted-runner:
+  labels:
+    - agent-pr-explore
+    - nexu-win
+    - release-beta

.github/actions/setup-playwright/action.yml

@@ -0,0 +1,34 @@
+name: Setup Playwright
+description: Restore Playwright browser cache and install browsers
+
+inputs:
+  package-json-path:
+    description: Path to package.json containing @playwright/test or playwright devDependency
+    required: true
+  install-command:
+    description: Command used to install browsers
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve Playwright version
+      id: playwright-version
+      shell: bash
+      run: |
+        version=$(node -p "const pkg = require('./${{ inputs.package-json-path }}'); const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }; (deps['@playwright/test'] || deps.playwright || '').replace(/[^0-9.]/g,'')")
+        if [ -z "$version" ]; then
+          echo "Could not resolve Playwright version from ${{ inputs.package-json-path }}" >&2
+          exit 1
+        fi
+        echo "version=$version" >> "$GITHUB_OUTPUT"
+
+    - name: Cache Playwright browser binaries
+      uses: actions/cache@v5.0.5
+      with:
+        path: ~/.cache/ms-playwright
+        key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
+
+    - name: Install Playwright browsers
+      shell: bash
+      run: ${{ inputs.install-command }}

.github/actions/setup-workspace/action.yml

@@ -0,0 +1,41 @@
+name: Setup workspace
+description: Restore pnpm cache and install dependencies
+
+inputs:
+  node-version:
+    description: Node.js version to install
+    required: false
+    default: '24'
+  pnpm-version:
+    description: pnpm version to install
+    required: false
+    default: '10.33.2'
+
+runs:
+  using: composite
+  steps:
+    - name: Setup pnpm
+      uses: pnpm/action-setup@v6.0.8
+      with:
+        version: ${{ inputs.pnpm-version }}
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v6.4.0
+      with:
+        node-version: ${{ inputs.node-version }}
+        package-manager-cache: false
+
+    - name: Resolve pnpm store path
+      id: pnpm-store
+      shell: bash
+      run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+    - name: Cache pnpm store
+      uses: actions/cache@v5.0.5
+      with:
+        path: ${{ steps.pnpm-store.outputs.path }}
+        key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+    - name: Install dependencies
+      shell: bash
+      run: pnpm install --frozen-lockfile

.github/scripts/agent-pr-explore-local.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  .github/scripts/agent-pr-explore-local.sh <pr-number>
+
+Runs the Docker-isolated PR exploration path from a local or self-hosted
+machine, without relying on a GitHub Actions workflow being present on main.
+
+Required on the host:
+  docker, gh, jq, node/npm, expect-cli@0.1.3
+
+Optional environment:
+  BASE_REPO=nexu-io/open-design
+  RUNNER_TEMP=/tmp/od-agent-pr-explore-local
+  OD_EXPECT_TIMEOUT_SECONDS=1200
+  OD_SANDBOX_CPUS=4
+  OD_SANDBOX_MEMORY=8g
+  OD_ALLOW_NPX_EXPECT_CLI=1
+  OD_TRACE_R2_UPLOAD=1
+  R2_ACCOUNT_ID=...
+  R2_ACCESS_KEY_ID=...
+  R2_SECRET_ACCESS_KEY=...
+  R2_BUCKET=...
+  R2_PUBLIC_ORIGIN=https://...
+USAGE
+}
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+  usage
+  exit 0
+fi
+
+pr_number="${1:-${PR_NUMBER:-}}"
+if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then
+  usage >&2
+  exit 2
+fi
+
+base_repo="${BASE_REPO:-nexu-io/open-design}"
+runner_temp="${RUNNER_TEMP:-/tmp/od-agent-pr-explore-local}"
+
+for command_name in docker gh jq node; do
+  if ! command -v "$command_name" >/dev/null 2>&1; then
+    echo "::error::$command_name is required on the mini/local runner" >&2
+    exit 1
+  fi
+done
+
+if [ -z "${GH_TOKEN:-}" ]; then
+  if ! GH_TOKEN="$(gh auth token 2>/dev/null)"; then
+    echo "::error::GH_TOKEN is not set and gh auth token failed. Run gh auth login or export GH_TOKEN." >&2
+    exit 1
+  fi
+  export GH_TOKEN
+fi
+
+if ! command -v expect-cli >/dev/null 2>&1 && [ "${OD_ALLOW_NPX_EXPECT_CLI:-0}" != "1" ]; then
+  echo "::error::expect-cli is not installed. Install it on the mini with: npm install -g expect-cli@${OD_EXPECT_CLI_VERSION:-0.1.3}" >&2
+  echo "        For a one-off smoke run, set OD_ALLOW_NPX_EXPECT_CLI=1 to use the pinned npx fallback." >&2
+  exit 1
+fi
+
+mkdir -p "$runner_temp"
+
+pr_json="$(gh pr view "$pr_number" --repo "$base_repo" --json state,isDraft,headRefOid,baseRefOid,headRepositoryOwner,headRepository)"
+state="$(jq -r '.state' <<<"$pr_json")"
+draft="$(jq -r '.isDraft' <<<"$pr_json")"
+head_sha="$(jq -r '.headRefOid' <<<"$pr_json")"
+base_sha="$(jq -r '.baseRefOid' <<<"$pr_json")"
+head_repo="$(jq -r '.headRepositoryOwner.login + "/" + .headRepository.name' <<<"$pr_json")"
+
+if [ "$state" != "OPEN" ]; then
+  echo "::error::Refusing to explore PR $pr_number because state is $state." >&2
+  exit 1
+fi
+if [ "$draft" != "false" ]; then
+  echo "::error::Refusing to explore draft PR $pr_number." >&2
+  exit 1
+fi
+if ! [[ "$head_sha" =~ ^[0-9a-f]{40}$ && "$base_sha" =~ ^[0-9a-f]{40}$ ]]; then
+  echo "::error::Invalid PR SHA metadata for PR $pr_number." >&2
+  exit 1
+fi
+
+echo "Running agent PR exploration locally"
+echo "  PR:        $base_repo#$pr_number"
+echo "  Head:      $head_repo@$head_sha"
+echo "  Base SHA:  $base_sha"
+echo "  Temp root: $runner_temp"
+
+PR_NUMBER="$pr_number" \
+HEAD_SHA="$head_sha" \
+HEAD_REPO="$head_repo" \
+BASE_REPO="$base_repo" \
+BASE_SHA="$base_sha" \
+RUNNER_TEMP="$runner_temp" \
+GH_TOKEN="$GH_TOKEN" \
+.github/scripts/agent-pr-explore-sandbox.sh
+
+echo
+echo "Artifacts:"
+echo "  $runner_temp/agent-pr-explore-sandbox/artifacts"

.github/scripts/provision-agent-pr-explore-runner.sh

@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+#
+# Provision / repair the self-hosted agent-pr-explore runner.
+#
+# The runner that powers `.github/workflows/agent-pr-explore-sandbox.yml` is a
+# self-hosted macOS host. Several pieces of its setup are layered on top of the
+# base toolchain and are easy to lose on a rebuild (most importantly the
+# codex-acp pin -- see below). This script makes that layer reproducible and
+# idempotent: run it on the runner, any time, to bring it back to a working
+# state. It never prints or embeds secrets.
+#
+# Run as the runner user (e.g. `mashu`) on the runner host:
+#   bash provision-agent-pr-explore-runner.sh
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# MANUAL prerequisites this script does NOT do (one-time, need a human/secret):
+#
+#  A. Base toolchain (user-local, no sudo). Install once into ~/agent-pr-explore-bin
+#     + ~/.npm-global if missing: docker CLI, colima, lima, node, npm, gh,
+#     expect-cli. Then start colima (give the VM real resources):
+#       colima start --runtime docker --cpu 8 --memory 13 --disk 80 \
+#         --vm-type=vz --mount-type=virtiofs --network-address=false
+#     (Playwright Chromium for the host user is auto-installed by the sandbox
+#      script's fallback on first run.)
+#
+#  B. Codex ChatGPT login (interactive OAuth, cannot be scripted):
+#       codex login          # complete ChatGPT auth in a browser
+#     On a headless box, log in on a workstation and copy ~/.codex/auth.json here.
+#     This script verifies login status and warns if absent.
+#
+#  C. Register the read-only deploy key (printed by this script) on the repo:
+#       gh api repos/${BASE_REPO}/keys -X POST -f title='agent-pr-explore runner' \
+#         -f key="$(cat ~/.ssh/od_agent_deploy.pub)" -F read_only=true
+#     (Needs repo admin. Required so the host can SSH-fetch PR source — the one
+#      git transport GFW does not reset.)
+#
+#  D. Register + service-install the GitHub Actions runner (token-based):
+#       ./config.sh --url https://github.com/${BASE_REPO} --token <RUNNER_TOKEN> \
+#         --labels self-hosted,agent-pr-explore --name macmini-agent-pr-explore
+#     then install it as a launchd service so it survives reboot.
+# ─────────────────────────────────────────────────────────────────────────────
+set -uo pipefail
+
+# --- config (override via env) -----------------------------------------------
+BASE_REPO="${BASE_REPO:-nexu-io/open-design}"
+CODEX_MODEL="${CODEX_MODEL:-gpt-5.4}"
+ACP_VERSION="${ACP_VERSION:-0.15.0}"
+ACP_ARCH_PKG="${ACP_ARCH_PKG:-@zed-industries/codex-acp-darwin-arm64}"  # match the runner arch
+NPM_MIRROR="${NPM_MIRROR:-https://registry.npmmirror.com}"
+DEPLOY_KEY="${DEPLOY_KEY:-$HOME/.ssh/od_agent_deploy}"
+MIRROR_DIR="${OD_SANDBOX_REPO_MIRROR:-$HOME/.cache/agent-pr-explore/open-design.git}"
+TOOLS_DIR="$HOME/agent-pr-explore-tools"
+export PATH="$TOOLS_DIR/lima-2.1.1/bin:$HOME/agent-pr-explore-bin:$HOME/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+ok()   { printf '  \033[32m✔\033[0m %s\n' "$*"; }
+warn() { printf '  \033[33m⚠\033[0m %s\n' "$*"; }
+step() { printf '\n\033[1m== %s ==\033[0m\n' "$*"; }
+
+# --- 0. sanity: base tools present -------------------------------------------
+step "0. base toolchain"
+missing=0
+for c in node npm docker expect-cli; do
+  if command -v "$c" >/dev/null 2>&1; then ok "$c: $(command -v "$c")"; else warn "$c MISSING — see manual step A"; missing=1; fi
+done
+[ "$missing" = 1 ] && warn "install the missing base tools first (manual step A), then re-run."
+
+# --- 1. codex CLI ------------------------------------------------------------
+step "1. codex CLI"
+if command -v codex >/dev/null 2>&1; then
+  ok "codex present: $(codex --version 2>&1 | head -1)"
+else
+  warn "installing @openai/codex via mirror…"
+  npm_config_registry="$NPM_MIRROR" npm install -g @openai/codex >/dev/null 2>&1 \
+    && ok "codex installed: $(codex --version 2>&1 | head -1)" || warn "codex install FAILED"
+fi
+
+# --- 2. codex model pin (ChatGPT account rejects -codex / gpt-5 models) -------
+step "2. codex model pin -> $CODEX_MODEL"
+mkdir -p "$HOME/.codex"
+cfg="$HOME/.codex/config.toml"
+touch "$cfg"
+if grep -q "^model *= *\"$CODEX_MODEL\"" "$cfg"; then
+  ok "config.toml already pins model = \"$CODEX_MODEL\""
+elif grep -q '^model *=' "$cfg"; then
+  # Replace just the model line in place; leave any other settings intact.
+  tmp="$(mktemp)" && sed "s|^model *=.*|model = \"$CODEX_MODEL\"|" "$cfg" > "$tmp" && mv "$tmp" "$cfg"
+  ok "updated model -> \"$CODEX_MODEL\" (other config.toml settings preserved)"
+else
+  printf 'model = "%s"\n' "$CODEX_MODEL" >> "$cfg"
+  ok "appended model = \"$CODEX_MODEL\" to config.toml"
+fi
+
+# --- 3. codex login (verify only; interactive — manual step B) ---------------
+step "3. codex login (ChatGPT OAuth)"
+if codex login status 2>&1 | grep -qi 'logged in'; then
+  ok "$(codex login status 2>&1 | head -1)"
+else
+  warn "codex NOT logged in — run 'codex login' (manual step B) or copy ~/.codex/auth.json here."
+fi
+
+# --- 4. codex-acp pin (CRITICAL: expect-cli bundles 0.10 which is incompatible
+#        with ChatGPT-account auth; reinstalling expect-cli reverts this). -----
+step "4. codex-acp pin -> $ACP_VERSION (the fragile one)"
+zed="$(npm root -g 2>/dev/null)/expect-cli/node_modules/@zed-industries"
+cur="$(cat "$zed/codex-acp/package.json" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1)"
+if [ "$cur" = "$ACP_VERSION" ]; then
+  ok "codex-acp already $ACP_VERSION"
+elif [ -d "$zed" ]; then
+  warn "codex-acp is '$cur' — pinning to $ACP_VERSION"
+  tmp="$(mktemp -d)"; ( cd "$tmp" && npm_config_registry="$NPM_MIRROR" npm pack \
+      "@zed-industries/codex-acp@$ACP_VERSION" "$ACP_ARCH_PKG@$ACP_VERSION" >/dev/null 2>&1 )
+  for pair in "codex-acp:@zed-industries/codex-acp" "$(basename "$ACP_ARCH_PKG"):$ACP_ARCH_PKG"; do
+    dir="${pair%%:*}"; tgz="$(ls "$tmp"/*"${dir}"-"$ACP_VERSION".tgz 2>/dev/null | head -1)"
+    [ -z "$tgz" ] && { warn "tarball for $dir not fetched"; continue; }
+    mkdir -p "$tmp/x_$dir"; tar -xzf "$tgz" -C "$tmp/x_$dir"
+    rm -rf "$zed/$dir"/* && cp -a "$tmp/x_$dir/package/." "$zed/$dir/"
+  done
+  chmod +x "$zed/$(basename "$ACP_ARCH_PKG")/bin/"* 2>/dev/null || true
+  rm -rf "$tmp"
+  now="$(cat "$zed/codex-acp/package.json" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1)"
+  [ "$now" = "$ACP_VERSION" ] && ok "codex-acp now $ACP_VERSION" || warn "codex-acp pin FAILED (still $now)"
+else
+  warn "expect-cli not found at $zed — install expect-cli first (manual step A)."
+fi
+
+# --- 5. deploy key (generate if missing; registration is manual step C) ------
+step "5. SSH deploy key"
+if [ -f "$DEPLOY_KEY" ]; then
+  ok "deploy key present: $DEPLOY_KEY"
+else
+  # On a fresh-rebuild host ~/.ssh often does not exist yet; create it first so
+  # ssh-keygen doesn't fail with "No such file or directory".
+  mkdir -p "$(dirname "$DEPLOY_KEY")" && chmod 700 "$(dirname "$DEPLOY_KEY")" 2>/dev/null || true
+  if ssh-keygen -t ed25519 -N "" -C "agent-pr-explore-deploy@$(hostname)" -f "$DEPLOY_KEY" >/dev/null; then
+    ok "generated $DEPLOY_KEY"
+  else
+    warn "ssh-keygen failed — deploy key NOT created; mirror bootstrap will not work until fixed."
+  fi
+fi
+if [ -f "$DEPLOY_KEY.pub" ]; then
+  warn "ensure this pubkey is a READ-ONLY deploy key on $BASE_REPO (manual step C):"
+  echo "        $(cat "$DEPLOY_KEY.pub")"
+fi
+
+# --- 6. base repo git mirror (so per-PR fetches are small deltas) ------------
+step "6. git mirror"
+export GIT_SSH_COMMAND="ssh -i $DEPLOY_KEY -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=20"
+if [ -d "$MIRROR_DIR" ] && git --git-dir="$MIRROR_DIR" rev-parse HEAD >/dev/null 2>&1; then
+  ok "mirror present ($(du -sh "$MIRROR_DIR" 2>/dev/null | cut -f1)); refreshing main…"
+  git --git-dir="$MIRROR_DIR" fetch --no-tags --depth=1 origin main >/dev/null 2>&1 && ok "main refreshed" || warn "mirror refresh failed (network?)"
+else
+  mkdir -p "$(dirname "$MIRROR_DIR")"
+  warn "seeding mirror (one-time, ~150MB over SSH)…"
+  git clone --bare --depth=1 --single-branch --branch main "git@github.com:${BASE_REPO}.git" "$MIRROR_DIR" >/dev/null 2>&1 \
+    && ok "mirror seeded" || warn "mirror clone FAILED (deploy key registered? network?)"
+fi
+mkdir -p "$HOME/.cache/agent-pr-explore/pnpm-store" "$HOME/.cache/agent-pr-explore/reports"
+ok "pnpm-store + reports dirs ready"
+
+# --- 7. base image refresh helper + weekly cron ------------------------------
+step "7. sandbox image refresh helper + cron"
+mkdir -p "$TOOLS_DIR"
+cat > "$TOOLS_DIR/refresh-sandbox-image.sh" <<'RSH'
+#!/usr/bin/env bash
+# Best-effort refresh of the sandbox base image. The sandbox script skips
+# `docker pull` when the image is cached (the runner's docker.io access is
+# flaky), so this is the decoupled refresh path; it never fails the host.
+set -uo pipefail
+export PATH="$HOME/agent-pr-explore-tools/lima-2.1.1/bin:$HOME/agent-pr-explore-bin:$HOME/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+image="${OD_SANDBOX_IMAGE:-node:24-bookworm}"
+ts() { date "+%Y-%m-%dT%H:%M:%S%z"; }
+echo "[$(ts)] refresh start: $image"
+colima status >/dev/null 2>&1 || { echo "[$(ts)] colima down; skip"; exit 0; }
+before="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null || echo none)"
+if docker pull "$image"; then
+  after="$(docker image inspect --format '{{.Id}}' "$image" 2>/dev/null || echo none)"
+  [ "$before" != "$after" ] && { echo "[$(ts)] refreshed $before -> $after"; docker image prune -f >/dev/null 2>&1 || true; } || echo "[$(ts)] up to date"
+else
+  echo "[$(ts)] pull failed (registry unreachable?); keeping cached $before"
+fi
+echo "[$(ts)] done"
+RSH
+chmod +x "$TOOLS_DIR/refresh-sandbox-image.sh"
+ok "wrote $TOOLS_DIR/refresh-sandbox-image.sh"
+cron_line="17 4 * * 0 $TOOLS_DIR/refresh-sandbox-image.sh >> $TOOLS_DIR/image-refresh.log 2>&1"
+if crontab -l 2>/dev/null | grep -qF "refresh-sandbox-image.sh"; then
+  ok "weekly refresh cron already installed"
+else
+  { crontab -l 2>/dev/null; echo "# agent-pr-explore weekly base-image refresh"; echo "$cron_line"; } | crontab - && ok "installed weekly refresh cron"
+fi
+
+# --- 8. readiness self-check helper ------------------------------------------
+step "8. readiness self-check helper"
+cat > "$HOME/check-agent-ready.sh" <<'CHK'
+#!/usr/bin/env bash
+# Quick readiness check: VPN reaches chatgpt backend + Codex responds.
+export PATH="$HOME/agent-pr-explore-tools/lima-2.1.1/bin:$HOME/agent-pr-explore-bin:$HOME/.npm-global/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+ok=1
+echo "1. chatgpt backend: $(curl -sS -m 15 -o /dev/null -w '%{http_code}' https://chatgpt.com/backend-api/ 2>/dev/null || echo FAIL)  (403/200 = reachable)"
+echo "2. codex model: $(grep '^model' "$HOME/.codex/config.toml" 2>/dev/null)"
+echo "3. codex-acp: $(cat "$(npm root -g)/expect-cli/node_modules/@zed-industries/codex-acp/package.json" 2>/dev/null | sed -n 's/.*"version": *"\([^"]*\)".*/\1/p' | head -1)"
+out="$(perl -e 'alarm shift; exec @ARGV' 90 codex exec --skip-git-repo-check 'reply with exactly READY_OK' 2>&1)"
+if printf '%s' "$out" | grep -q READY_OK; then echo "4. codex: ✅ responds"; else echo "4. codex: ❌ no response"; ok=0; fi
+[ "$ok" = 1 ] && echo "==> READY ✅" || echo "==> NOT READY ❌"
+CHK
+chmod +x "$HOME/check-agent-ready.sh"
+ok "wrote ~/check-agent-ready.sh"
+
+step "done — run ~/check-agent-ready.sh after VPN/login to confirm"

.github/scripts/release/assets/win.ps1

@@ -8,21 +8,37 @@ foreach ($name in @("CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN", "RELEASE_CHANNEL", "
 
 $assetSuffix = if ($null -eq $env:WINDOWS_ASSET_SUFFIX) { "" } else { $env:WINDOWS_ASSET_SUFFIX }
 $versionPathSuffix = if ($null -eq $env:ASSET_VERSION_SUFFIX) { "" } else { $env:ASSET_VERSION_SUFFIX }
+$includeZip = if ([string]::IsNullOrWhiteSpace($env:WINDOWS_INCLUDE_ZIP)) { $true } else { $env:WINDOWS_INCLUDE_ZIP -ne "false" }
 $releaseDir = Join-Path $env:RUNNER_TEMP "release-assets"
 New-Item -ItemType Directory -Force -Path $releaseDir | Out-Null
 
-$sourceInstaller = Join-Path $env:RUNNER_TEMP "tools-pack/out/win/namespaces/${env:TOOLS_PACK_NAMESPACE}/builder/Open Design-${env:TOOLS_PACK_NAMESPACE}-setup.exe"
+$builderDir = Join-Path $env:RUNNER_TEMP "tools-pack/out/win/namespaces/${env:TOOLS_PACK_NAMESPACE}/builder"
+$sourceInstaller = Join-Path $builderDir "Open Design-${env:TOOLS_PACK_NAMESPACE}-setup.exe"
+$sourceZip = Join-Path $builderDir "Open Design-${env:TOOLS_PACK_NAMESPACE}-portable.zip"
 if (!(Test-Path $sourceInstaller)) {
   throw "expected installer not found at $sourceInstaller"
 }
+if ($includeZip -and !(Test-Path $sourceZip)) {
+  throw "expected portable zip not found at $sourceZip (build with --to all or --to zip, or set WINDOWS_INCLUDE_ZIP=false to skip)"
+}
 
 $versionedInstaller = "open-design-${env:RELEASE_VERSION}$assetSuffix-win-x64-setup.exe"
-$checksumFile = "$versionedInstaller.sha256"
-Copy-Item $sourceInstaller (Join-Path $releaseDir $versionedInstaller)
+$versionedZip = "open-design-${env:RELEASE_VERSION}$assetSuffix-win-x64-portable.zip"
+$installerChecksumFile = "$versionedInstaller.sha256"
+$zipChecksumFile = "$versionedZip.sha256"
 
+Copy-Item $sourceInstaller (Join-Path $releaseDir $versionedInstaller)
 $installerPath = Join-Path $releaseDir $versionedInstaller
-$hash = (Get-FileHash -Path $installerPath -Algorithm SHA256).Hash.ToLowerInvariant()
-"$hash  $versionedInstaller" | Set-Content -Path (Join-Path $releaseDir $checksumFile)
+$installerHash = (Get-FileHash -Path $installerPath -Algorithm SHA256).Hash.ToLowerInvariant()
+"$installerHash  $versionedInstaller" | Set-Content -Path (Join-Path $releaseDir $installerChecksumFile)
+
+if ($includeZip) {
+  Copy-Item $sourceZip (Join-Path $releaseDir $versionedZip)
+  $zipPath = Join-Path $releaseDir $versionedZip
+  $zipHash = (Get-FileHash -Path $zipPath -Algorithm SHA256).Hash.ToLowerInvariant()
+  "$zipHash  $versionedZip" | Set-Content -Path (Join-Path $releaseDir $zipChecksumFile)
+}
+
 $installerBytes = [System.IO.File]::ReadAllBytes($installerPath)
 $installerSha512 = [System.Convert]::ToBase64String([System.Security.Cryptography.SHA512]::Create().ComputeHash($installerBytes))
 $installerSize = (Get-Item $installerPath).Length
@@ -39,6 +55,9 @@ $releaseNotes = if ([string]::IsNullOrWhiteSpace($env:RELEASE_NOTES)) {
 } else {
   $env:RELEASE_NOTES
 }
+# latest.yml is the electron-updater auto-update feed; it only references the
+# NSIS installer because the portable zip is a manual-download convenience and
+# is not consumed by the in-app updater.
 @(
   "version: `"${env:RELEASE_VERSION}`""
   'files:'

.github/scripts/release/r2/publish-platform.ts

@@ -175,10 +175,18 @@ if (platform === "mac") {
 } else if (platform === "win") {
   const suffix = optional("WIN_ASSET_SUFFIX", assetVersionSuffix);
   const installer = `open-design-${releaseVersion}${suffix}-win-x64-setup.exe`;
+  const portableZip = `open-design-${releaseVersion}${suffix}-win-x64-portable.zip`;
+  const includeZip = optional("WIN_INCLUDE_ZIP", "true") !== "false";
+  const artifacts = { installer: fileEntry(installer, contentType(installer)) };
+  const assetNames = [installer, `${installer}.sha256`, "latest.yml"];
+  if (includeZip) {
+    artifacts.portableZip = fileEntry(portableZip, contentType(portableZip));
+    assetNames.push(portableZip, `${portableZip}.sha256`);
+  }
   config = {
     arch: "x64",
-    artifacts: { installer: fileEntry(installer, contentType(installer)) },
-    assetNames: [installer, `${installer}.sha256`, "latest.yml"],
+    artifacts,
+    assetNames,
     feed: {
       latestUrl: publicUrl(latestPrefix, "latest.yml"),
       name: "latest.yml",

.github/scripts/release/r2/publish.sh

@@ -109,8 +109,17 @@ mac_zip="open-design-$RELEASE_VERSION$asset_version_suffix-mac-arm64.zip"
 mac_intel_dmg="open-design-$RELEASE_VERSION$mac_intel_asset_suffix-mac-x64.dmg"
 mac_intel_zip="open-design-$RELEASE_VERSION$mac_intel_asset_suffix-mac-x64.zip"
 win_installer="open-design-$RELEASE_VERSION$win_asset_suffix-win-x64-setup.exe"
+win_portable_zip="open-design-$RELEASE_VERSION$win_asset_suffix-win-x64-portable.zip"
 linux_appimage="open-design-$RELEASE_VERSION$linux_asset_suffix-linux-x64.AppImage"
 metadata_path="$release_root/metadata.json"
+win_include_zip="${WIN_INCLUDE_ZIP:-true}"
+case "$win_include_zip" in
+  true | false) ;;
+  *)
+    echo "unsupported WIN_INCLUDE_ZIP: $win_include_zip" >&2
+    exit 1
+    ;;
+esac
 
 if [ "$ENABLE_MAC" = "true" ]; then
   upload "$release_root/mac/$mac_dmg" "$version_prefix/$mac_dmg" "application/x-apple-diskimage" "public, max-age=31536000, immutable"
@@ -139,6 +148,13 @@ if [ "$ENABLE_WIN" = "true" ]; then
     echo "win_installer_url=$public_origin/$version_prefix/$win_installer"
     echo "win_feed_url=$public_origin/$latest_prefix/latest.yml"
   } >> "$GITHUB_OUTPUT"
+  if [ "$win_include_zip" = "true" ]; then
+    upload "$release_root/win/$win_portable_zip" "$version_prefix/$win_portable_zip" "application/zip" "public, max-age=31536000, immutable"
+    upload "$release_root/win/$win_portable_zip.sha256" "$version_prefix/$win_portable_zip.sha256" "text/plain; charset=utf-8" "public, max-age=31536000, immutable"
+    {
+      echo "win_portable_zip_url=$public_origin/$version_prefix/$win_portable_zip"
+    } >> "$GITHUB_OUTPUT"
+  fi
 fi
 
 if [ "$ENABLE_MAC_INTEL" = "true" ]; then
@@ -177,6 +193,8 @@ MAC_ZIP="$mac_zip" \
 MAC_INTEL_DMG="$mac_intel_dmg" \
 MAC_INTEL_ZIP="$mac_intel_zip" \
 WIN_INSTALLER="$win_installer" \
+WIN_PORTABLE_ZIP="$win_portable_zip" \
+WIN_INCLUDE_ZIP="$win_include_zip" \
 LINUX_APPIMAGE="$linux_appimage" \
 MAC_ARTIFACT_MODE="$mac_artifact_mode" \
 METADATA_PATH="$metadata_path" \
@@ -236,6 +254,12 @@ if (enabled("ENABLE_MAC")) {
   };
 }
 if (enabled("ENABLE_WIN")) {
+  const winArtifacts = {
+    installer: fileEntry("win", env.WIN_INSTALLER, "application/vnd.microsoft.portable-executable"),
+  };
+  if (env.WIN_INCLUDE_ZIP !== "false") {
+    winArtifacts.portableZip = fileEntry("win", env.WIN_PORTABLE_ZIP, "application/zip");
+  }
   platforms.win = {
     arch: "x64",
     enabled: true,
@@ -245,9 +269,7 @@ if (enabled("ENABLE_WIN")) {
       url: url(versionPrefix, "latest.yml"),
     },
     signed: false,
-    artifacts: {
-      installer: fileEntry("win", env.WIN_INSTALLER, "application/vnd.microsoft.portable-executable"),
-    },
+    artifacts: winArtifacts,
   };
 }
 if (enabled("ENABLE_LINUX")) {

.github/scripts/release/r2/summary.sh

@@ -65,6 +65,7 @@ if (platforms.mac.enabled) {
 if (platforms.win.enabled) {
   platforms.win.artifacts = {
     installer: optional("R2_WIN_INSTALLER_URL"),
+    portableZip: optional("R2_WIN_PORTABLE_ZIP_URL"),
   };
   platforms.win.feed = optional("R2_WIN_FEED_URL");
   platforms.win.e2e = platformReport("win");
@@ -142,7 +143,10 @@ const platformRows = [
   [
     "Windows x64",
     platformStatus(platforms.win, "Published"),
-    linkList([{ label: "Installer", url: platforms.win.artifacts?.installer }]),
+    linkList([
+      { label: "Installer", url: platforms.win.artifacts?.installer },
+      { label: "Portable ZIP", url: platforms.win.artifacts?.portableZip },
+    ]),
     link("latest.yml", platforms.win.feed),
   ],
   [

.github/scripts/release/r2/verify.sh

@@ -134,6 +134,9 @@ if [ "$ENABLE_WIN" = "true" ]; then
   grep -F "version: \"$RELEASE_VERSION\"" "$downloaded_feed"
   grep -F "$R2_WIN_INSTALLER_URL" "$downloaded_feed"
   curl -fsSI "$R2_WIN_INSTALLER_URL" >/dev/null
+  if [ -n "${R2_WIN_PORTABLE_ZIP_URL:-}" ]; then
+    curl -fsSI "$R2_WIN_PORTABLE_ZIP_URL" >/dev/null
+  fi
   require_report_file "win/manifest.json"
   require_report_file "win/screenshots/open-design-win-smoke.png"
   require_report_file "win/suite-result.json"

.github/workflows/actionlint.yml

@@ -0,0 +1,28 @@
+name: actionlint
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/**
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/**
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    name: Lint GitHub Actions workflows
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+
+      - name: Check workflow files
+        uses: docker://rhysd/actionlint:1.7.12
+        with:
+          args: -color

.github/workflows/agent-pr-explore-sandbox.yml

@@ -0,0 +1,330 @@
+name: agent-pr-explore-sandbox
+
+# Trusted-orchestrator workflow for PR exploration on the self-hosted runner.
+# Triggered by manual workflow_dispatch, or by a maintainer commenting
+# "/explore" on a PR (write-access gated). It deliberately does not auto-run on
+# every PR, so ordinary PRs do not accumulate waiting checks; PR code only ever
+# runs inside the Docker sandbox without secrets.
+on:
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to explore.
+        required: true
+        type: string
+      skip_comment:
+        description: Skip posting the exploration report comment on the PR (the report is still uploaded as an artifact). Use for validation/dry runs.
+        required: false
+        default: false
+        type: boolean
+  # A maintainer commenting "/explore" on a PR explores that PR. issue_comment
+  # runs in the base (trusted) context with secrets, so the job `if` gate below
+  # restricts it to users with write access; untrusted PR code still runs only
+  # inside the Docker sandbox without secrets.
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+concurrency:
+  group: agent-pr-explore-sandbox-${{ github.event.issue.number || inputs.pr_number }}
+  cancel-in-progress: true
+
+jobs:
+  sandbox:
+    name: Sandbox PR runtime
+    runs-on: [self-hosted, agent-pr-explore]
+    # No environment approval gate: both triggers are already write-access
+    # gated (workflow_dispatch needs repo write; the "/explore" comment path is
+    # gated on author_association below), and PR code runs only in the sandbox.
+    # R2 credentials are repo-level secrets, so they remain available here.
+    timeout-minutes: 45
+    # Manual dispatch is always allowed. A "/explore" PR comment is allowed only
+    # from a user with write access (OWNER/MEMBER/COLLABORATOR), never on issues.
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event_name == 'issue_comment' &&
+      github.event.issue.pull_request != null &&
+      startsWith(github.event.comment.body, '/explore') &&
+      contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+
+    steps:
+      - name: Acknowledge /explore command
+        if: ${{ github.event_name == 'issue_comment' }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -uo pipefail
+          # 👀 on the command comment = picked up.
+          gh api "repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID/reactions" -f content=eyes --silent || true
+          # Post a placeholder carrying the report marker; the report step later
+          # PATCHes this same comment, so the run produces one evolving comment.
+          marker="<!-- agent-pr-explore-sandbox:${PR_NUMBER} -->"
+          body="🔍 Exploring this PR in an isolated sandbox — [follow the run]($RUN_URL). The report will replace this comment when it is ready.
+
+          $marker"
+          existing="$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --paginate --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" | tail -n 1)"
+          if [ -n "$existing" ]; then
+            gh api "repos/$GITHUB_REPOSITORY/issues/comments/$existing" -X PATCH -f body="$body" --silent || true
+          else
+            gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" -f body="$body" --silent || true
+          fi
+
+      - name: Fetch trusted base script
+        # Only the self-contained sandbox script is needed on the trusted host;
+        # PR code is checked out inside Docker. A full actions/checkout of this
+        # large repo stalled on the self-hosted runner before the agent ever
+        # ran, so fetch just the one trusted file via the API instead. The ref
+        # is pinned to the trusted base/dispatch commit, never PR head.
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TRUSTED_REF: ${{ github.event.pull_request.base.sha || github.sha }}
+        run: |
+          set -euo pipefail
+          mkdir -p .github/scripts
+          gh api \
+            -H 'Accept: application/vnd.github.raw' \
+            "repos/$GITHUB_REPOSITORY/contents/.github/scripts/agent-pr-explore-sandbox.sh?ref=$TRUSTED_REF" \
+            > .github/scripts/agent-pr-explore-sandbox.sh
+          chmod +x .github/scripts/agent-pr-explore-sandbox.sh
+          echo "Fetched trusted agent-pr-explore-sandbox.sh at $TRUSTED_REF"
+
+      - name: Resolve PR metadata
+        id: pr
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_PR_NUMBER: ${{ inputs.pr_number || github.event.issue.number }}
+        run: |
+          set -euo pipefail
+          if ! [[ "$EVENT_PR_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "::error::Invalid PR number: $EVENT_PR_NUMBER"
+            exit 1
+          fi
+
+          state="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json state --jq '.state')"
+          draft="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json isDraft --jq '.isDraft')"
+          author="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json author --jq '.author.login')"
+          head_sha="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid --jq '.headRefOid')"
+          head_repo="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRepositoryOwner,headRepository --jq '.headRepositoryOwner.login + "/" + .headRepository.name')"
+          base_repo="$GITHUB_REPOSITORY"
+          base_sha="$(gh pr view "$EVENT_PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json baseRefOid --jq '.baseRefOid')"
+
+          if [ "$state" != "OPEN" ]; then
+            echo "::error::Refusing to explore PR $EVENT_PR_NUMBER because state is $state."
+            exit 1
+          fi
+          if [ "$draft" != "false" ]; then
+            echo "::error::Refusing to explore draft PR $EVENT_PR_NUMBER."
+            exit 1
+          fi
+          if [ "$base_repo" != "$GITHUB_REPOSITORY" ]; then
+            echo "::error::Unexpected base repo $base_repo."
+            exit 1
+          fi
+          if ! [[ "$head_sha" =~ ^[0-9a-f]{40}$ && "$base_sha" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::Invalid PR SHA metadata."
+            exit 1
+          fi
+
+          {
+            echo "number=$EVENT_PR_NUMBER"
+            echo "author=$author"
+            echo "head_sha=$head_sha"
+            echo "head_repo=$head_repo"
+            echo "base_sha=$base_sha"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Run expect against Docker-isolated PR app
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+          HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          HEAD_REPO: ${{ steps.pr.outputs.head_repo }}
+          BASE_REPO: ${{ github.repository }}
+          BASE_SHA: ${{ steps.pr.outputs.base_sha }}
+          OD_SANDBOX_CPUS: "4"
+          OD_SANDBOX_MEMORY: "8g"
+          OD_SANDBOX_READY_TIMEOUT_SECONDS: "900"
+          OD_EXPECT_TIMEOUT_SECONDS: "1200"
+          OD_EXPECT_CONTEXT_MAX_BYTES: "120000"
+          OD_TRACE_R2_UPLOAD: "1"
+          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID || secrets.CLOUDFLARE_ACCOUNT_ID }}
+          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID || secrets.CLOUDFLARE_R2_RELEASES_AK }}
+          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY || secrets.CLOUDFLARE_R2_RELEASES_SK }}
+          R2_BUCKET: ${{ secrets.R2_BUCKET || secrets.CLOUDFLARE_R2_RELEASES_BUCKET }}
+          R2_PUBLIC_ORIGIN: ${{ vars.R2_PUBLIC_ORIGIN || vars.CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN || secrets.CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN }}
+          R2_ENDPOINT: ${{ secrets.R2_ENDPOINT || secrets.CLOUDFLARE_R2_RELEASES_URL }}
+        run: .github/scripts/agent-pr-explore-sandbox.sh
+
+      - name: Upload sandbox artifacts
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: agent-pr-explore-sandbox-${{ steps.pr.outputs.number }}-${{ steps.pr.outputs.head_sha }}
+          # The trace zips (~28MB) and videos are already published to R2; keep
+          # them out of the GitHub artifact so it stays small (report + logs).
+          path: |
+            ${{ runner.temp }}/agent-pr-explore-sandbox/artifacts/
+            !${{ runner.temp }}/agent-pr-explore-sandbox/artifacts/**/*.zip
+            !${{ runner.temp }}/agent-pr-explore-sandbox/artifacts/**/*.webm
+          if-no-files-found: warn
+          retention-days: 7
+
+      - name: Comment exploration report
+        if: ${{ always() && !inputs.skip_comment }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+          PR_AUTHOR: ${{ steps.pr.outputs.author }}
+          HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+        run: |
+          set -euo pipefail
+          report="$RUNNER_TEMP/agent-pr-explore-sandbox/artifacts/agent-pr-exploration-report.md"
+          if [ ! -s "$report" ]; then
+            echo "No agent exploration report was produced; skipping PR comment."
+            exit 0
+          fi
+
+          marker="<!-- agent-pr-explore-sandbox:${PR_NUMBER} -->"
+          body_file="$(mktemp)"
+          {
+            cat "$report"
+            echo
+            echo "$marker"
+          } > "$body_file"
+
+          comment_id="$(
+            gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --paginate \
+              --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" \
+              | tail -n 1
+          )"
+          body="$(cat "$body_file")"
+          if [ -n "$comment_id" ]; then
+            gh api "repos/$GITHUB_REPOSITORY/issues/comments/$comment_id" -X PATCH -f body="$body" --silent
+          else
+            gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" -f body="$body" --silent
+          fi
+
+          pr_author_lc="$(printf '%s' "$PR_AUTHOR" | tr '[:upper:]' '[:lower:]')"
+          case "$pr_author_lc" in
+            nettee|mrcfps|alchemistklk|siri-ray)
+              ;;
+            *)
+              echo "PR author $PR_AUTHOR is not configured for inline agent reports; skipping inline review comment."
+              exit 0
+              ;;
+          esac
+
+          files_json="$(mktemp)"
+          gh api --paginate --slurp "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/files" > "$files_json"
+          inline_target="$(
+            FILES_JSON="$files_json" node <<'NODE'
+          const fs = require("node:fs");
+          const pages = JSON.parse(fs.readFileSync(process.env.FILES_JSON, "utf8"));
+          const files = pages.flat();
+
+          function firstAddedLine(file) {
+            if (typeof file.patch !== "string") return null;
+            let newLine = null;
+            for (const line of file.patch.split("\n")) {
+              const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+              if (hunk) {
+                newLine = Number(hunk[1]);
+                continue;
+              }
+              if (newLine == null) continue;
+              if (line.startsWith("+") && !line.startsWith("+++")) return newLine;
+              if (!line.startsWith("-")) newLine += 1;
+            }
+            return null;
+          }
+
+          for (const file of files) {
+            if (!file || file.status === "removed") continue;
+            const line = firstAddedLine(file);
+            if (line != null) {
+              process.stdout.write(JSON.stringify({ path: file.filename, line }));
+              process.exit(0);
+            }
+          }
+          NODE
+          )"
+          if [ -z "$inline_target" ]; then
+            echo "No added diff line was available for an inline agent report; skipping inline review comment."
+            exit 0
+          fi
+
+          inline_path="$(node -e 'const target = JSON.parse(process.argv[1]); process.stdout.write(target.path)' "$inline_target")"
+          inline_line="$(node -e 'const target = JSON.parse(process.argv[1]); process.stdout.write(String(target.line))' "$inline_target")"
+          inline_marker="<!-- agent-pr-explore-inline:${PR_NUMBER} -->"
+          inline_body_file="$(mktemp)"
+          {
+            cat "$report"
+            echo
+            echo "$inline_marker"
+          } > "$inline_body_file"
+          inline_body="$(cat "$inline_body_file")"
+
+          inline_comment_id="$(
+            gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" --paginate \
+              --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$inline_marker\"))) | .id" \
+              | tail -n 1
+          )"
+          if [ -n "$inline_comment_id" ]; then
+            gh api "repos/$GITHUB_REPOSITORY/pulls/comments/$inline_comment_id" -X PATCH -f body="$inline_body" --silent
+          else
+            gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER/comments" \
+              -f body="$inline_body" \
+              -f commit_id="$HEAD_SHA" \
+              -f path="$inline_path" \
+              -F line="$inline_line" \
+              -f side=RIGHT \
+              --silent
+          fi
+
+      - name: React done on /explore command
+        if: ${{ success() && github.event_name == 'issue_comment' }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+        run: gh api "repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID/reactions" -f content=rocket --silent || true
+
+      - name: Report /explore command failure
+        if: ${{ failure() && github.event_name == 'issue_comment' }}
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMENT_ID: ${{ github.event.comment.id }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          set -uo pipefail
+          # If a report was produced before the non-zero exit, the report step
+          # already posted it — leave it rather than clobbering useful output.
+          if [ -s "$RUNNER_TEMP/agent-pr-explore-sandbox/artifacts/agent-pr-exploration-report.md" ]; then
+            echo "A report exists despite the non-zero exit; leaving it in place."
+            exit 0
+          fi
+          gh api "repos/$GITHUB_REPOSITORY/issues/comments/$COMMENT_ID/reactions" -f content="-1" --silent || true
+          marker="<!-- agent-pr-explore-sandbox:${PR_NUMBER} -->"
+          body="⚠️ Exploration run failed before producing a report — see [the run]($RUN_URL).
+
+          $marker"
+          existing="$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --paginate --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" | tail -n 1)"
+          if [ -n "$existing" ]; then
+            gh api "repos/$GITHUB_REPOSITORY/issues/comments/$existing" -X PATCH -f body="$body" --silent || true
+          else
+            gh api "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" -f body="$body" --silent || true
+          fi

.github/workflows/agent-pr-explore.lock.yml

@@ -0,0 +1,36 @@
+# Placeholder for PR Explore Agent.
+#
+# GitHub only reliably triggers pull_request workflows once a workflow
+# file with the same path exists on the default branch. The real
+# generated gh-aw workflow is introduced by PR #2604; this placeholder
+# is intentionally inert and can be replaced by the compiled workflow
+# when that PR merges.
+name: "PR Explore Agent - placeholder"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - "apps/web/**"
+      - "apps/landing-page/**"
+      - "design-templates/open-design-landing/**"
+      - "skills/**"
+      - "design-systems/**"
+      - "craft/**"
+      - "templates/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - ".github/workflows/agent-pr-explore.lock.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  placeholder:
+    name: Placeholder
+    if: ${{ github.event_name == 'agent_pr_explore_placeholder_never' }}
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "agent-pr-explore placeholder only"

.github/workflows/blog-3day-report.yml

@@ -87,9 +87,11 @@ jobs:
           if [ -n "$FEISHU_BLOG_DIGEST_WEBHOOK" ]; then
             feishu=true
           fi
-          echo "gsc=$gsc" >> "$GITHUB_OUTPUT"
-          echo "bot=$bot" >> "$GITHUB_OUTPUT"
-          echo "feishu=$feishu" >> "$GITHUB_OUTPUT"
+          {
+            echo "gsc=$gsc"
+            echo "bot=$bot"
+            echo "feishu=$feishu"
+          } >> "$GITHUB_OUTPUT"
           {
             echo "### Blog 3-day report configuration"
             echo "- GSC auth configured: \`$gsc\`"
@@ -122,16 +124,16 @@ jobs:
           GSC_SERVICE_ACCOUNT_KEY: ${{ secrets.GSC_SERVICE_ACCOUNT_KEY }}
         run: |
           mkdir -p .blog-indexing
-          flags=""
+          flags=()
           if [ -n "${{ github.event.inputs.today }}" ]; then
-            flags="$flags --today ${{ github.event.inputs.today }}"
+            flags+=(--today "${{ github.event.inputs.today }}")
           fi
           if [ "${{ github.event.inputs.skip_inspect }}" = "true" ]; then
-            flags="$flags --no-inspect"
+            flags+=(--no-inspect)
           fi
           pnpm --filter @open-design/landing-page exec tsx scripts/blog-indexing/report-3day.ts \
             --summary-out ../../.blog-indexing/blog-traffic-digest-summary.json \
-            $flags
+            "${flags[@]}"
           # Surface the latest section in the run summary for quick review.
           {
             echo "### Latest digest section"

.github/workflows/blog-indexing-monitor.yml

@@ -251,7 +251,9 @@ jobs:
         run: |
           existing=$(gh issue list --repo nexu-io/open-design --state open --search 'in:title "Blog indexing — URLs stalled in Search Console"' --json number --jq '.[0].number // empty')
           if [ -n "$existing" ]; then
-            gh issue comment "$existing" --repo nexu-io/open-design --body 'All previously stalled URLs have reached `indexed` status. Closing automatically. — `blog-indexing-monitor`'
+            body_file="$RUNNER_TEMP/blog-indexing-monitor-stall-close.md"
+            printf '%s\n' "All previously stalled URLs have reached \`indexed\` status. Closing automatically. — \`blog-indexing-monitor\`" > "$body_file"
+            gh issue comment "$existing" --repo nexu-io/open-design --body-file "$body_file"
             gh issue close "$existing" --repo nexu-io/open-design
           fi
 
@@ -262,7 +264,9 @@ jobs:
         run: |
           existing=$(gh issue list --repo nexu-io/open-design --state open --search 'in:title "Blog traffic — indexed posts with zero impressions"' --json number --jq '.[0].number // empty')
           if [ -n "$existing" ]; then
-            gh issue comment "$existing" --repo nexu-io/open-design --body 'All previously low-traffic tracked URLs now have impressions or no longer match the escalation window. Closing automatically. — `blog-indexing-monitor`'
+            body_file="$RUNNER_TEMP/blog-indexing-monitor-low-traffic-close.md"
+            printf '%s\n' "All previously low-traffic tracked URLs now have impressions or no longer match the escalation window. Closing automatically. — \`blog-indexing-monitor\`" > "$body_file"
+            gh issue comment "$existing" --repo nexu-io/open-design --body-file "$body_file"
             gh issue close "$existing" --repo nexu-io/open-design
           fi
 

.github/workflows/blog-indexing-on-deploy.yml

@@ -1,6 +1,8 @@
 name: blog-indexing-on-deploy
 
-# Runs after every successful `landing-page-deploy` on main. The job is
+# Runs after every successful `landing-page-production` promotion. Staging
+# deploys (`landing-page-staging`) intentionally do NOT trigger indexing, so
+# the test environment is never submitted to search engines. The job is
 # idempotent and follows the blog-indexing-automation skill:
 #
 #   1. Detect blog URLs added/modified in the deploy
@@ -16,7 +18,7 @@ name: blog-indexing-on-deploy
 
 on:
   workflow_run:
-    workflows: ['landing-page-deploy']
+    workflows: ['landing-page-production']
     types: [completed]
     branches: [main]
   workflow_dispatch:
@@ -29,7 +31,10 @@ on:
         required: false
 
 permissions:
-  contents: read
+  # `contents: write` lets the job advance the `blog-indexed-prod` tag after a
+  # successful run so the next promotion diffs from exactly where this one
+  # stopped. The status PR uses a separate GitHub App token (below).
+  contents: write
 
 concurrency:
   group: blog-indexing-on-deploy
@@ -147,8 +152,21 @@ jobs:
           mkdir -p .blog-indexing
           BASE="${{ github.event.inputs.base_sha || '' }}"
           if [ -z "$BASE" ]; then
-            BASE="$(git rev-parse HEAD^)"
+            # Diff from the last production deploy we already indexed, tracked
+            # by the `blog-indexed-prod` tag. Production is a manual promotion
+            # that may bundle several merged posts, so a HEAD^ diff would miss
+            # all but the last commit. The tag is advanced at the end of a
+            # successful run (see "Advance indexed-production pointer").
+            git fetch --no-tags origin "+refs/tags/blog-indexed-prod:refs/tags/blog-indexed-prod" 2>/dev/null || true
+            BASE="$(git rev-parse --verify --quiet 'refs/tags/blog-indexed-prod^{commit}' || true)"
+            if [ -n "$BASE" ]; then
+              echo "Diffing from last indexed production commit (blog-indexed-prod): $BASE"
+            else
+              BASE="$(git rev-parse HEAD^)"
+              echo "No blog-indexed-prod tag yet; bootstrapping from HEAD^: $BASE"
+            fi
           fi
+          echo "base=$BASE" >> "$GITHUB_OUTPUT"
           pnpm --filter @open-design/landing-page exec tsx scripts/blog-indexing/detect-changed-urls.ts \
             --base "$BASE" \
             --head HEAD \
@@ -264,3 +282,20 @@ jobs:
             Generated by `.github/workflows/blog-indexing-on-deploy.yml`. The
             sidecar `docs/blog-indexing-status.json` is the canonical state;
             the markdown file is rendered from it.
+
+      # Advance the pointer LAST, only after every post-deploy step above
+      # (detect, verify, submit, inspect, analytics, render, status PR)
+      # succeeded. `success()` is false if any earlier step failed, so a
+      # failure leaves the tag where it was and the next production run
+      # re-processes the same range rather than silently skipping posts.
+      # Skipped steps (count == 0, or GSC/bot not configured) do not count as
+      # failures, so the pointer still advances over an empty/partial range.
+      # Restricted to the real production-deploy trigger; an ad-hoc manual
+      # dispatch must not move the production baseline.
+      - name: Advance indexed-production pointer
+        if: success() && github.event_name == 'workflow_run'
+        run: |
+          HEAD_SHA="$(git rev-parse HEAD)"
+          git tag -f blog-indexed-prod "$HEAD_SHA"
+          git push -f origin "refs/tags/blog-indexed-prod"
+          echo "Advanced blog-indexed-prod -> $HEAD_SHA"

.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: ci
 
 on:
   pull_request:
+  merge_group:
   # Release validation is owned by the release workflows rather than this CI
   # workflow: `release-stable` has a verify job before publishing, and
   # `release-beta` builds from its selected release commit. Keep this trigger
@@ -35,6 +36,7 @@ jobs:
       web_tests_required: ${{ steps.detect.outputs.web_tests_required }}
       tools_dev_tests_required: ${{ steps.detect.outputs.tools_dev_tests_required }}
       tools_pack_tests_required: ${{ steps.detect.outputs.tools_pack_tests_required }}
+      nix_validation_required: ${{ steps.detect.outputs.nix_validation_required }}
       workspace_validation_required: ${{ steps.detect.outputs.workspace_validation_required }}
 
     steps:
@@ -49,6 +51,7 @@ jobs:
           web_tests_required=false
           tools_dev_tests_required=false
           tools_pack_tests_required=false
+          nix_validation_required=false
           workspace_validation_required=false
           if [ "${{ github.event_name }}" = "pull_request" ]; then
             gh api --paginate \
@@ -71,16 +74,20 @@ jobs:
               if [[ "$file" == "tools/pack/"* || "$file" == "apps/packaged/"* || "$file" == "apps/desktop/"* || "$file" == "packages/host/"* || "$file" == "packages/platform/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/sidecar-proto/"* ]]; then
                 tools_pack_tests_required=true
               fi
-              if [[ "$file" == "package.json" || "$file" == "pnpm-lock.yaml" || "$file" == "pnpm-workspace.yaml" || "$file" == ".github/workflows/ci.yml" ]]; then
+              if [[ "$file" == "package.json" || "$file" == "apps/daemon/package.json" || "$file" == "apps/web/package.json" || "$file" == "apps/desktop/package.json" || "$file" == "apps/packaged/package.json" || "$file" == "packages/"*/"package.json" || "$file" == "tools/"*/"package.json" || "$file" == "e2e/package.json" || "$file" == "pnpm-lock.yaml" || "$file" == "pnpm-workspace.yaml" || "$file" == ".github/workflows/ci.yml" ]]; then
                 daemon_tests_required=true
                 web_tests_required=true
                 tools_dev_tests_required=true
                 tools_pack_tests_required=true
               fi
+              # Keep this filter in sync with flake.nix daemonWorkspacePaths / webWorkspacePaths.
+              if [[ "$file" == "package.json" || "$file" == "pnpm-lock.yaml" || "$file" == "pnpm-workspace.yaml" || "$file" == "flake.nix" || "$file" == "flake.lock" || "$file" == "nix/"* || "$file" == ".github/workflows/ci.yml" || "$file" == ".github/workflows/nix-check.yml" || "$file" == ".github/workflows/nix-hash-autofix.yml" || "$file" == "apps/daemon/"* || "$file" == "apps/web/"* || "$file" == "packages/contracts/"* || "$file" == "packages/registry-protocol/"* || "$file" == "packages/agui-adapter/"* || "$file" == "packages/plugin-runtime/"* || "$file" == "packages/sidecar-proto/"* || "$file" == "packages/sidecar/"* || "$file" == "packages/platform/"* || "$file" == "packages/diagnostics/"* || "$file" == "packages/host/"* || "$file" == "assets/"* || "$file" == "plugins/"* || "$file" == "skills/"* || "$file" == "design-systems/"* || "$file" == "design-templates/"* || "$file" == "craft/"* || "$file" == "prompt-templates/"* || "$file" == "scripts/update-nix-pnpm-deps-hash.ts" ]]; then
+                nix_validation_required=true
+              fi
               case "$file" in
                 *.md|*.mdx|*.txt|LICENSE|.gitignore|.editorconfig|.vscode/*|.idea/*|docs/*|.github/ISSUE_TEMPLATE/*|.github/CODEOWNERS)
                   ;;
-                apps/landing-page/*|.github/workflows/landing-page-ci.yml|.github/workflows/landing-page-deploy.yml|.github/workflows/blog-indexing-on-deploy.yml|.github/workflows/blog-indexing-monitor.yml)
+                apps/landing-page/*|flake.nix|flake.lock|nix/*|.github/workflows/nix-check.yml|.github/workflows/landing-page-ci.yml|.github/workflows/landing-page-staging.yml|.github/workflows/landing-page-production.yml|.github/workflows/blog-indexing-on-deploy.yml|.github/workflows/blog-indexing-monitor.yml|.github/workflows/blog-3day-report.yml|.github/workflows/seo-daily-report.yml|.github/workflows/actionlint.yml|.github/workflows/visual-pr-capture.yml|.github/workflows/visual-pr-comment.yml)
                   ;;
                 *)
                   workspace_validation_required=true
@@ -90,6 +97,7 @@ jobs:
                 && [ "$web_tests_required" = "true" ] \
                 && [ "$tools_dev_tests_required" = "true" ] \
                 && [ "$tools_pack_tests_required" = "true" ] \
+                && [ "$nix_validation_required" = "true" ] \
                 && [ "$workspace_validation_required" = "true" ]; then
                 break
               fi
@@ -100,11 +108,21 @@ jobs:
               || [ "$tools_pack_tests_required" = "true" ]; then
               workspace_validation_required=true
             fi
+          elif [ "${{ github.event_name }}" = "push" ]; then
+            daemon_tests_required=true
+            web_tests_required=true
+            tools_dev_tests_required=true
+            tools_pack_tests_required=true
+            # Main already runs .github/workflows/nix-check.yml, so keep this
+            # workflow's push path focused on the non-Nix workspace signal.
+            nix_validation_required=false
+            workspace_validation_required=true
           else
             daemon_tests_required=true
             web_tests_required=true
             tools_dev_tests_required=true
             tools_pack_tests_required=true
+            nix_validation_required=true
             workspace_validation_required=true
           fi
           {
@@ -112,9 +130,119 @@ jobs:
             echo "web_tests_required=$web_tests_required"
             echo "tools_dev_tests_required=$tools_dev_tests_required"
             echo "tools_pack_tests_required=$tools_pack_tests_required"
+            echo "nix_validation_required=$nix_validation_required"
             echo "workspace_validation_required=$workspace_validation_required"
           } >> "$GITHUB_OUTPUT"
 
+  nix_validation:
+    name: Validate Nix flake
+    needs: [change_scopes]
+    if: ${{ needs.change_scopes.outputs.nix_validation_required == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v27
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            accept-flake-config = true
+
+      - name: Setup Node for Nix hash refresh
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+
+      - name: nix flake check
+        id: flake_check
+        continue-on-error: true
+        run: nix flake check --print-build-logs --keep-going
+
+      - name: Generate Nix hash refresh patch
+        id: hash_refresh
+        if: ${{ github.event_name == 'pull_request' && steps.flake_check.outcome == 'failure' }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          out_dir="$RUNNER_TEMP/nix-hash-refresh"
+          mkdir -p "$out_dir"
+
+          status="update-failed"
+          if node --experimental-strip-types ./scripts/update-nix-pnpm-deps-hash.ts >"$out_dir/update.log" 2>&1; then
+            if git diff --quiet --exit-code -- nix/pnpm-deps.nix; then
+              status="no-change"
+            else
+              git diff -- nix/pnpm-deps.nix >"$out_dir/nix-pnpm-deps.patch"
+              cp nix/pnpm-deps.nix "$out_dir/pnpm-deps.nix"
+              status="patch-generated"
+            fi
+          fi
+
+          printf '{"status":"%s","runId":%s,"prNumber":%s,"headSha":"%s"}\n' \
+            "$status" \
+            '${{ github.run_id }}' \
+            '${{ github.event.pull_request.number }}' \
+            '${{ github.event.pull_request.head.sha }}' >"$out_dir/metadata.json"
+
+          echo "status=$status" >> "$GITHUB_OUTPUT"
+
+      - name: Upload Nix hash refresh artifact
+        if: ${{ github.event_name == 'pull_request' && steps.flake_check.outcome == 'failure' && steps.hash_refresh.outputs.status != 'no-change' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: nix-hash-refresh
+          path: ${{ runner.temp }}/nix-hash-refresh
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Summarize Nix hash refresh guidance
+        if: ${{ github.event_name == 'pull_request' && steps.flake_check.outcome == 'failure' }}
+        env:
+          HASH_REFRESH_STATUS: ${{ steps.hash_refresh.outputs.status }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          case "${HASH_REFRESH_STATUS:-not-run}" in
+            patch-generated)
+              cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
+          ## Generated Nix hash refresh
+
+          CI regenerated a patch for `nix/pnpm-deps.nix` and uploaded it as the
+          `nix-hash-refresh` artifact for this run.
+
+          - same-repo PRs: the follow-up `nix-hash-autofix` workflow will try to
+            push the hash-only patch back to the PR branch automatically;
+          - fork PRs: a PR comment will include the patch and artifact guidance.
+          EOF
+              ;;
+            no-change)
+              cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
+          ## Nix hash refresh unavailable
+
+          `nix flake check` failed, but `nix/pnpm-deps.nix` did not change after
+          running the hash refresh helper. Inspect the Nix build logs for a
+          non-hash failure.
+          EOF
+              ;;
+            *)
+              cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
+          ## Nix hash refresh failed
+
+          `nix flake check` failed and the helper could not generate a hash-only
+          patch. See the `nix-hash-refresh` artifact for `update.log`.
+          EOF
+              ;;
+          esac
+
+      - name: Fail when Nix validation fails
+        if: ${{ steps.flake_check.outcome == 'failure' }}
+        run: exit 1
+
   preflight:
     name: Preflight
     needs: [change_scopes]
@@ -126,30 +254,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
       # `scripts/postinstall.mjs` only prebuilds package/tool entrypoints that
       # are needed immediately after install for linked bins and shared
@@ -183,8 +289,8 @@ jobs:
       - name: Check i18n structure
         run: pnpm i18n:check
 
-  core_tests:
-    name: Core package tests
+  workspace_unit_tests:
+    name: Workspace unit tests
     needs: [change_scopes]
     if: ${{ needs.change_scopes.outputs.workspace_validation_required == 'true' }}
     runs-on: ubuntu-latest
@@ -194,77 +300,16 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Core package tests
+      - name: Workspace unit tests
         run: |
           pnpm --filter @open-design/contracts test
           pnpm --filter @open-design/host test
           pnpm --filter @open-design/platform test
           pnpm --filter @open-design/sidecar test
           pnpm --filter @open-design/sidecar-proto test
-
-  tools_workspace_tests:
-    name: Tools workspace tests
-    needs: [change_scopes]
-    if: ${{ needs.change_scopes.outputs.tools_dev_tests_required == 'true' || needs.change_scopes.outputs.tools_pack_tests_required == 'true' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6.0.2
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Tools workspace smoke tests
-        run: |
           if [ "${{ needs.change_scopes.outputs.tools_dev_tests_required }}" = "true" ]; then
             pnpm --filter @open-design/tools-dev test
           fi
@@ -273,50 +318,24 @@ jobs:
           fi
 
   daemon_workspace_tests:
-    name: Daemon workspace tests (${{ matrix.shard }}/2)
+    name: Daemon workspace tests
     needs: [change_scopes]
     if: ${{ needs.change_scopes.outputs.daemon_tests_required == 'true' }}
     runs-on: ubuntu-latest
     timeout-minutes: 20
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1, 2]
 
     steps:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
       - name: Prebuild daemon entrypoint declarations
         run: pnpm --filter @open-design/daemon build
 
       - name: Daemon workspace tests
-        run: pnpm --filter @open-design/daemon exec vitest run -c vitest.config.ts --shard=${{ matrix.shard }}/2
+        run: pnpm --filter @open-design/daemon test
 
   web_workspace_tests:
     name: Web workspace tests
@@ -329,30 +348,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
       - name: Prebuild web sidecar declarations
         run: pnpm --filter @open-design/web build:sidecar
@@ -360,164 +357,26 @@ jobs:
       - name: Web workspace tests
         run: pnpm --filter @open-design/web test
 
-  app_tests:
-    name: App workspace tests
+  browser_tests:
+    name: Browser tests
     needs:
       - change_scopes
-      - tools_workspace_tests
-      - daemon_workspace_tests
-      - web_workspace_tests
-    if: ${{ always() && needs.change_scopes.result == 'success' && (needs.change_scopes.outputs.tools_dev_tests_required == 'true' || needs.change_scopes.outputs.tools_pack_tests_required == 'true' || needs.change_scopes.outputs.daemon_tests_required == 'true' || needs.change_scopes.outputs.web_tests_required == 'true') }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-
-    steps:
-      - name: Check app workspace test jobs
-        env:
-          NEEDS_JSON: ${{ toJSON(needs) }}
-          TOOLS_REQUIRED: ${{ needs.change_scopes.outputs.tools_dev_tests_required == 'true' || needs.change_scopes.outputs.tools_pack_tests_required == 'true' }}
-          DAEMON_REQUIRED: ${{ needs.change_scopes.outputs.daemon_tests_required }}
-          WEB_REQUIRED: ${{ needs.change_scopes.outputs.web_tests_required }}
-        run: |
-          set -euo pipefail
-          echo "$NEEDS_JSON" | jq .
-          failures=()
-          if [ "$TOOLS_REQUIRED" = "true" ] && [ "$(echo "$NEEDS_JSON" | jq -r '.tools_workspace_tests.result')" != "success" ]; then
-            failures+=("tools_workspace_tests=$(echo "$NEEDS_JSON" | jq -r '.tools_workspace_tests.result')")
-          fi
-          if [ "$DAEMON_REQUIRED" = "true" ] && [ "$(echo "$NEEDS_JSON" | jq -r '.daemon_workspace_tests.result')" != "success" ]; then
-            failures+=("daemon_workspace_tests=$(echo "$NEEDS_JSON" | jq -r '.daemon_workspace_tests.result')")
-          fi
-          if [ "$WEB_REQUIRED" = "true" ] && [ "$(echo "$NEEDS_JSON" | jq -r '.web_workspace_tests.result')" != "success" ]; then
-            failures+=("web_workspace_tests=$(echo "$NEEDS_JSON" | jq -r '.web_workspace_tests.result')")
-          fi
-          if [ "${#failures[@]}" -gt 0 ]; then
-            printf 'App workspace validation failed:\n'
-            printf '%s\n' "${failures[@]}"
-            exit 1
-          fi
-
-  e2e_vitest:
-    name: E2E vitest
-    needs: [change_scopes]
-    if: ${{ needs.change_scopes.outputs.workspace_validation_required == 'true' }}
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6.0.2
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      # Some Vitest-based smoke tests drive the browser directly through
-      # @playwright/test. Restore browser binaries without saving from CI runs;
-      # the key follows the @playwright/test version so browser revisions
-      # update with package bumps.
-      - name: Resolve Playwright version
-        id: playwright-version
-        run: |
-          version=$(node -p "require('./e2e/package.json').devDependencies['@playwright/test'].replace(/[^0-9.]/g,'')")
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-      - name: Restore Playwright browser cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
-
-      - name: Install Playwright browsers
-        run: pnpm -C e2e exec playwright install --with-deps chromium
-
-      - name: E2E vitest
-        run: pnpm --filter @open-design/e2e test
-
-  ui_e2e_critical:
-    name: Playwright critical (${{ matrix.group }})
-    needs: [change_scopes]
     if: ${{ needs.change_scopes.outputs.workspace_validation_required == 'true' }}
     runs-on: ubuntu-latest
     timeout-minutes: 30
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - group: core
-            grep_flag: --grep-invert
-            grep_pattern: home starters|home hero
-          - group: starters
-            grep_flag: --grep
-            grep_pattern: home starters|home hero
 
     steps:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
+
+      - name: Setup Playwright
+        uses: ./.github/actions/setup-playwright
         with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      # Restore Playwright browser binaries without saving from CI runs. The
-      # key follows the @playwright/test version so browser revisions update
-      # with package bumps.
-      - name: Resolve Playwright version
-        id: playwright-version
-        run: |
-          version=$(node -p "require('./e2e/package.json').devDependencies['@playwright/test'].replace(/[^0-9.]/g,'')")
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-      - name: Restore Playwright browser cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
-
-      - name: Install Playwright browsers
-        run: pnpm -C e2e exec playwright install --with-deps chromium
+          package-json-path: e2e/package.json
+          install-command: pnpm -C e2e exec playwright install --with-deps chromium
 
       - name: Prebuild workspace type declarations
         run: |
@@ -525,10 +384,13 @@ jobs:
           pnpm --filter @open-design/desktop build
           pnpm --filter @open-design/web build:sidecar
 
+      - name: E2E vitest
+        run: pnpm --filter @open-design/e2e test
+
       - name: Playwright critical
         run: |
           pnpm -C e2e exec tsx scripts/playwright.ts clean
-          pnpm -C e2e exec playwright test -c playwright.config.ts ${{ matrix.grep_flag }} '${{ matrix.grep_pattern }}' ui/critical-smoke.test.ts ui/entry-chrome-flows.test.ts
+          pnpm -C e2e exec playwright test -c playwright.config.ts ui/critical-smoke.test.ts ui/entry-chrome-flows.test.ts
 
   build_workspaces:
     name: Build workspaces
@@ -541,30 +403,8 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
       - name: Prebuild workspace type declarations
         run: |
@@ -583,11 +423,13 @@ jobs:
   validate:
     name: Validate workspace
     needs:
+      - change_scopes
       - preflight
-      - core_tests
-      - app_tests
-      - e2e_vitest
-      - ui_e2e_critical
+      - nix_validation
+      - workspace_unit_tests
+      - daemon_workspace_tests
+      - web_workspace_tests
+      - browser_tests
       - build_workspaces
     if: ${{ always() }}
     runs-on: ubuntu-latest

.github/workflows/contributor-card-bot.yml

@@ -6,10 +6,8 @@ name: Contributor Card Bot
 #
 # Intentionally NOT included: pull_request_review, pull_request_review_comment,
 # issue_comment. GitHub withholds repository secrets from these events when
-# they originate on forked PRs, which is precisely the path most external
-# contributor activity takes; the bot requires BOT_APP_* secrets to authenticate,
-# so wiring those events here would fail-closed exactly for the contributors we
-# want to recognize. They can be re-added later via a workflow_run handoff.
+# they originate on forked PRs, so the relay secret would fail-closed there too.
+# They can be re-added later via a workflow_run handoff.
 on:
   pull_request_target:
     types: [closed]
@@ -24,21 +22,16 @@ on:
 permissions:
   contents: read
 
-# Serialize all bot runs across the whole repository. The bot reads-then-writes
-# `data/contributor-card-state.json`; running events in parallel let multiple
-# runs read the same SHA and only the first PUT succeeds, the rest fail with a
-# 409 Conflict. They also let the same actor receive duplicate cards when a
-# burst of events fires before the first state write lands. A single repo-wide
-# group with `cancel-in-progress: false` queues runs and processes them in
-# arrival order, so every event still gets a card and the state file is never
-# stale on write.
+# Serialize all relay runs across the whole repository. The Cloudflare worker
+# owns durable state now, but queuing still keeps identical GitHub events from
+# racing each other and producing duplicate comments during bursty merge windows.
 concurrency:
   group: contributor-card-bot
   cancel-in-progress: false
 
 jobs:
   recognize:
-    name: Render and post contributor card
+    name: Relay contributor event to Cloudflare worker
     if: |
       github.repository == 'nexu-io/open-design' &&
       (
@@ -49,32 +42,46 @@ jobs:
         github.event_name == 'workflow_dispatch'
       )
     runs-on: ubuntu-latest
-    timeout-minutes: 8
+    timeout-minutes: 5
 
     steps:
-      - name: Checkout contributor bot
-        uses: actions/checkout@v6.0.2
-        with:
-          repository: nexu-io/open-design-bot-sandbox
-          ref: main
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 10
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.0.0
-        with:
-          node-version: 22
-          cache: pnpm
-
-      - name: Install bot dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Run contributor bot
+      - name: Relay event payload
         env:
-          BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
-          BOT_APP_INSTALLATION_ID: ${{ secrets.BOT_APP_INSTALLATION_ID }}
-          BOT_APP_PRIVATE_KEY: ${{ secrets.BOT_APP_PRIVATE_KEY }}
-        run: pnpm exec tsx scripts/action-handler.ts
+          CONTRIBUTOR_CARD_WORKER_URL: ${{ secrets.CONTRIBUTOR_CARD_WORKER_URL }}
+          CONTRIBUTOR_CARD_WORKER_SECRET: ${{ secrets.CONTRIBUTOR_CARD_WORKER_SECRET }}
+          GITHUB_EVENT_NAME: ${{ github.event_name }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+          GITHUB_EVENT_ACTION: ${{ github.event.action }}
+          GITHUB_RUN_ID: ${{ github.run_id }}
+          GITHUB_RUN_ATTEMPT: ${{ github.run_attempt }}
+          GITHUB_EVENT_PATH: ${{ github.event_path }}
+        run: |
+          python - <<'PY'
+          import json, os
+          from pathlib import Path
+
+          payload = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())
+          envelope = {
+            "repository": os.environ["GITHUB_REPOSITORY"],
+            "eventName": os.environ["GITHUB_EVENT_NAME"],
+            "action": os.environ.get("GITHUB_EVENT_ACTION") or payload.get("action"),
+            "deliveryId": f"{os.environ['GITHUB_RUN_ID']}-{os.environ['GITHUB_RUN_ATTEMPT']}",
+            "triggeredAt": __import__("datetime").datetime.utcnow().isoformat(timespec="milliseconds") + "Z",
+            "payload": payload,
+          }
+          Path("body.json").write_text(json.dumps(envelope, separators=(",", ":")))
+          PY
+          python - <<'PY'
+          import hashlib, hmac, os
+          from pathlib import Path
+
+          body = Path("body.json").read_bytes()
+          digest = hmac.new(os.environ["CONTRIBUTOR_CARD_WORKER_SECRET"].encode(), body, hashlib.sha256).hexdigest()
+          Path("signature.txt").write_text(f"sha256={digest}")
+          PY
+          curl --fail --silent --show-error \
+            -X POST \
+            -H "content-type: application/json" \
+            -H "x-open-design-signature: $(cat signature.txt)" \
+            --data-binary @body.json \
+            "$CONTRIBUTOR_CARD_WORKER_URL/api/github/events"

.github/workflows/fork-pr-workflow-approval.yml

@@ -0,0 +1,57 @@
+name: fork-pr-workflow-approval
+
+# This workflow runs in the trusted base-repository context. It never checks out
+# or executes the fork head; the TypeScript policy script only reads PR metadata
+# through the GitHub API and approves pending pull_request runs when the touched
+# paths are inside the low-risk source allowlist. It only approves low-privilege
+# pull_request workflows (`ci`, visual verify, and strict web-source visual
+# capture); privileged
+# workflow_run / release / deploy workflows stay on manual gates.
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, ready_for_review, edited]
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: Pull request number to evaluate.
+        required: true
+        type: string
+      dry_run:
+        description: Log decisions without approving workflow runs.
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  actions: write
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: fork-pr-workflow-approval-${{ github.event.pull_request.number || inputs.pr_number }}
+  cancel-in-progress: false
+
+jobs:
+  approve:
+    if: github.repository == 'nexu-io/open-design' && (github.event_name != 'pull_request_target' || github.event.action != 'edited' || github.event.changes.base != null)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout trusted base code
+        uses: actions/checkout@v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.base.sha || github.sha }}
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6.4.0
+        with:
+          node-version: 24
+
+      - name: Evaluate and approve low-risk fork PR workflows
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr_number }}
+          DRY_RUN: ${{ inputs.dry_run || false }}
+        run: node --experimental-strip-types scripts/approve-fork-pr-workflows.ts

.github/workflows/landing-page-ci.yml

@@ -5,7 +5,8 @@ on:
     paths:
       # Workflow files
       - .github/workflows/landing-page-ci.yml
-      - .github/workflows/landing-page-deploy.yml
+      - .github/workflows/landing-page-staging.yml
+      - .github/workflows/landing-page-production.yml
       - .github/workflows/blog-indexing-on-deploy.yml
       - .github/workflows/blog-indexing-monitor.yml
       # Landing page sources
@@ -19,16 +20,29 @@ on:
       - design-systems/**
       - craft/**
       - templates/**
+      # Plugin manifests power the bundled-plugin catalog and the new
+      # `_lib/bundled-plugins.ts` reader; CI must rerun when their
+      # `title_i18n` / `description_i18n` maps or other fields change.
+      - plugins/**
       # Workspace plumbing
       - package.json
       - pnpm-lock.yaml
       - pnpm-workspace.yaml
+  # Merge queue trigger so PRs that touch the same paths can clear
+  # `Validate landing page` / `Strict PR visual tests` while queued.
+  # Without this branch ruleset blocks merges (the queue waits forever
+  # for a check name that never gets dispatched against the merge_group
+  # ref), which is the exact deadlock observed during the 5/26 release
+  # window.
+  merge_group:
+    types: [checks_requested]
   push:
     branches:
       - main
     paths:
       - .github/workflows/landing-page-ci.yml
-      - .github/workflows/landing-page-deploy.yml
+      - .github/workflows/landing-page-staging.yml
+      - .github/workflows/landing-page-production.yml
       - .github/workflows/blog-indexing-on-deploy.yml
       - .github/workflows/blog-indexing-monitor.yml
       - apps/landing-page/**
@@ -37,6 +51,7 @@ on:
       - design-systems/**
       - craft/**
       - templates/**
+      - plugins/**
       - package.json
       - pnpm-lock.yaml
       - pnpm-workspace.yaml
@@ -44,6 +59,10 @@ on:
 
 permissions:
   contents: read
+  # Needed to post/update the preview-URL comment on the PR. Fork PRs run
+  # with a read-only token regardless, so the preview steps below are gated
+  # to same-repo branches.
+  pull-requests: write
 
 concurrency:
   group: landing-page-ci-${{ github.event.pull_request.number || github.ref }}
@@ -61,37 +80,26 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v5
-        with:
-          version: 10.33.2
+      - name: Setup workspace
+        uses: ./.github/actions/setup-workspace
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Cache generated previews
+        id: previews-cache
+        uses: actions/cache@v5.0.5
         with:
-          node-version: 24
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+          path: apps/landing-page/public/previews
+          key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
+          restore-keys: |
+            landing-page-previews-${{ runner.os }}-
 
       # Cache the Playwright browser binaries between runs. The cache key
       # is pinned to the playwright version we depend on (kept in
       # apps/landing-page/package.json) so a bump invalidates correctly.
-      - name: Resolve Playwright version
-        id: playwright-version
-        run: |
-          version=$(node -p "require('./apps/landing-page/package.json').devDependencies.playwright.replace(/[^0-9.]/g,'')")
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-      - name: Cache Playwright browsers
-        uses: actions/cache@v4
+      - name: Setup Playwright
+        uses: ./.github/actions/setup-playwright
         with:
-          path: ~/.cache/ms-playwright
-          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
-
-      - name: Install Playwright Chromium
-        run: pnpm --filter @open-design/landing-page exec playwright install --with-deps chromium
+          package-json-path: apps/landing-page/package.json
+          install-command: pnpm --filter @open-design/landing-page exec playwright install --with-deps chromium
 
       - name: Typecheck landing page
         run: pnpm --filter @open-design/landing-page typecheck
@@ -103,16 +111,30 @@ jobs:
       # launch failure or a 100%-failure run exits non-zero so the
       # build stops instead of silently shipping zero thumbnails.
       - name: Generate skill + template previews
+        # Exact previews-cache hit ⇒ public/previews already holds the correct
+        # thumbnails, skip the slow Playwright render. A restore-keys partial
+        # hit keeps cache-hit false, so we still regenerate — no stale-thumbnail
+        # drift.
+        if: steps.previews-cache.outputs.cache-hit != 'true'
         run: pnpm --filter @open-design/landing-page previews
 
+      # No PUBLIC_GA_MEASUREMENT_ID for PR/CI builds: the per-PR preview must
+      # not report into the production GA property. OD_LANDING_NOINDEX=1 keeps
+      # the PR preview (pr-<n>.open-design-landing-staging.pages.dev) out of
+      # search engines. Only `landing-page-production` builds without these.
       - name: Build landing page
-        run: pnpm --filter @open-design/landing-page build
+        env:
+          OD_LANDING_NOINDEX: '1'
+        run: pnpm --filter @open-design/landing-page build:static
 
       - name: Lint changed blog SEO
         run: |
-          BASE="${{ github.event.pull_request.base.sha || github.event.before || 'HEAD^' }}"
-          if [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
-            BASE="HEAD^"
+          BASE="${{ github.event.pull_request.base.sha || github.event.before || '' }}"
+          if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
+            # merge_group (and first-push) events have no base SHA. Resolve a
+            # concrete commit instead of passing the literal "HEAD^", which the
+            # blog-indexing scripts' assertSafeGitRef rejects (no "^" allowed).
+            BASE="$(git rev-parse HEAD^)"
           fi
           pnpm --filter @open-design/landing-page exec tsx scripts/blog-indexing/lint-blog-seo.ts \
             --base "$BASE" \
@@ -121,9 +143,12 @@ jobs:
 
       - name: Guard blog URL changes
         run: |
-          BASE="${{ github.event.pull_request.base.sha || github.event.before || 'HEAD^' }}"
-          if [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
-            BASE="HEAD^"
+          BASE="${{ github.event.pull_request.base.sha || github.event.before || '' }}"
+          if [ -z "$BASE" ] || [ "$BASE" = "0000000000000000000000000000000000000000" ]; then
+            # merge_group (and first-push) events have no base SHA. Resolve a
+            # concrete commit instead of passing the literal "HEAD^", which the
+            # blog-indexing scripts' assertSafeGitRef rejects (no "^" allowed).
+            BASE="$(git rev-parse HEAD^)"
           fi
           pnpm --filter @open-design/landing-page exec tsx scripts/blog-indexing/check-blog-url-changes.ts \
             --base "$BASE" \
@@ -162,3 +187,74 @@ jobs:
             process.exit(1);
           }
           NODE
+
+      # --- PR preview deploy -------------------------------------------------
+      # Publish this PR's built site to its own preview URL in the STAGING
+      # project (`--branch=pr-<number>`) so reviewers see the rendered result
+      # before merge. It lands in the staging project, never the production
+      # project. Gated to same-repo branches: fork PRs run without the
+      # Cloudflare secrets and with a read-only token, so they skip the
+      # deploy/comment and keep just the validation above.
+      - name: Deploy PR preview to Cloudflare Pages
+        id: preview
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: apps/landing-page
+          packageManager: npm
+          command: >
+            pages deploy out
+            --project-name=open-design-landing-staging
+            --branch=pr-${{ github.event.pull_request.number }}
+
+      - name: Comment preview URL on PR
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        uses: actions/github-script@v7
+        env:
+          DEPLOY_URL: ${{ steps.preview.outputs.deployment-url }}
+          ALIAS_URL: ${{ steps.preview.outputs.pages-deployment-alias-url }}
+        with:
+          script: |
+            const marker = '<!-- landing-preview -->';
+            const deploy = process.env.DEPLOY_URL || '';
+            const alias =
+              process.env.ALIAS_URL ||
+              `https://pr-${context.issue.number}.open-design-landing-staging.pages.dev`;
+            const sha = context.payload.pull_request.head.sha.slice(0, 7);
+            const body = [
+              marker,
+              '### 🚀 Landing page preview',
+              '',
+              'This PR is deployed to a Cloudflare Pages preview — **not** staging or production:',
+              '',
+              `- Stable alias: ${alias}`,
+              deploy ? `- This build: ${deploy}` : '',
+              '',
+              `Updated for commit \`${sha}\`.`,
+            ]
+              .filter(Boolean)
+              .join('\n');
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+            const existing = comments.find((c) => c.body && c.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

.github/workflows/landing-page-production.yml

@@ -0,0 +1,161 @@
+name: landing-page-production
+
+# Promotes the current landing page to PRODUCTION: the `open-design-landing`
+# Cloudflare Pages project, served at open-design.ai. This is the ONLY
+# workflow that names the production project, and it is manual-only
+# (workflow_dispatch) — a merge to `main` can never reach production on its
+# own; it only updates the staging project (staging.open-design.ai) via
+# `landing-page-staging`. Gate this further by configuring required reviewers
+# on the GitHub `production` environment (Settings → Environments).
+#
+# The build is identical to staging/CI, so what you reviewed on
+# staging.open-design.ai is what ships.
+
+on:
+  workflow_dispatch:
+    inputs:
+      reason:
+        description: 'Why promote now? (recorded in the run log)'
+        required: false
+
+permissions:
+  contents: read
+  deployments: write
+
+# Never cancel an in-flight production deploy.
+concurrency:
+  group: landing-page-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy landing page to production
+    # Production ships `main` only. workflow_dispatch can be launched from any
+    # ref via the Actions "Use workflow from" dropdown; gate the whole job on
+    # the main ref so a dispatch from a feature branch/tag is skipped outright
+    # (no deploy) instead of recording a non-main production run — which would
+    # also dodge blog-indexing's `workflow_run` `branches: [main]` filter.
+    if: github.repository == 'nexu-io/open-design' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    environment:
+      name: production
+      url: https://open-design.ai
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+        with:
+          # Production always ships `main`. workflow_dispatch can be launched
+          # from any ref via the Actions "Use workflow from" dropdown, so pin
+          # the checkout to main — the deployed artifact must equal reviewed
+          # main, never whatever branch/tag the operator happened to select.
+          ref: main
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v5
+        with:
+          version: 10.33.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Resolve Playwright version
+        id: playwright-version
+        run: |
+          version=$(node -p "require('./apps/landing-page/package.json').devDependencies.playwright.replace(/[^0-9.]/g,'')")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Cache generated previews
+        id: previews-cache
+        uses: actions/cache@v5.0.5
+        with:
+          path: apps/landing-page/public/previews
+          key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
+          restore-keys: |
+            landing-page-previews-${{ runner.os }}-
+
+      - name: Cache Playwright browsers
+        uses: actions/cache@v5.0.5
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
+
+      - name: Install Playwright Chromium
+        run: pnpm --filter @open-design/landing-page exec playwright install --with-deps chromium
+
+      - name: Typecheck landing page
+        run: pnpm --filter @open-design/landing-page typecheck
+
+      # Generate previews before build so they end up in `out/previews/`.
+      # Soft vs. hard failure is enforced inside the script itself:
+      # individual broken `example.html` entries are logged and skipped,
+      # but a systemic failure (chromium launch error, every job failing)
+      # exits non-zero so we don't silently ship a deploy with zero
+      # thumbnails to production.
+      - name: Generate skill + template previews
+        # Exact previews-cache hit ⇒ public/previews already holds the correct
+        # thumbnails, skip the slow Playwright render. A restore-keys partial
+        # hit keeps cache-hit false, so we still regenerate — no stale-thumbnail
+        # drift.
+        if: steps.previews-cache.outputs.cache-hit != 'true'
+        run: pnpm --filter @open-design/landing-page previews
+
+      - name: Build landing page
+        env:
+          PUBLIC_GA_MEASUREMENT_ID: ${{ vars.PUBLIC_GA_MEASUREMENT_ID }}
+        run: pnpm --filter @open-design/landing-page build:static
+
+      - name: Verify zero external JavaScript
+        run: |
+          node <<'NODE'
+          const { readFileSync } = require('node:fs');
+          const html = readFileSync('apps/landing-page/out/index.html', 'utf8');
+          const forbidden = [
+            /<script\b[^>]*\bsrc=/i,
+            /type=["']module["']/i,
+            /\/_astro\/[^"'<>\s]+\.js/i,
+          ];
+          for (const pattern of forbidden) {
+            if (pattern.test(html)) {
+              console.error(`Unexpected client JavaScript matched ${pattern}`);
+              process.exit(1);
+            }
+          }
+          NODE
+
+      - name: Verify Cloudflare image resizing URLs
+        run: |
+          node <<'NODE'
+          const { readFileSync } = require('node:fs');
+          const html = readFileSync('apps/landing-page/out/index.html', 'utf8');
+          const resizedUrls = html.match(/https:\/\/static\.open-design\.ai\/cdn-cgi\/image\//g) ?? [];
+          if (resizedUrls.length < 16) {
+            console.error(`Expected at least 16 Cloudflare resized image URLs, found ${resizedUrls.length}`);
+            process.exit(1);
+          }
+          if (/(?:src|content)=["']\/assets\/[A-Za-z0-9_.-]+\.png/.test(html)) {
+            console.error('Found local /assets/*.png image reference in generated landing HTML.');
+            process.exit(1);
+          }
+          NODE
+
+      # `--branch=main` IS the Cloudflare Pages production branch, so this
+      # publishes to the production domain (open-design.ai).
+      - name: Deploy to Cloudflare Pages (production)
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: apps/landing-page
+          packageManager: npm
+          command: >
+            pages deploy out
+            --project-name=open-design-landing
+            --branch=main

.github/workflows/landing-page-staging.yml

@@ -1,4 +1,11 @@
-name: landing-page-deploy
+name: landing-page-staging
+
+# Pushes to `main` deploy the landing page to the STAGING Cloudflare Pages
+# project (`open-design-landing-staging`, served at staging.open-design.ai).
+# Production (the separate `open-design-landing` project → open-design.ai) is
+# never named here — it is reached exclusively through the manual
+# `landing-page-production` workflow. This is the safety gate: project
+# separation means a merge to main can only ever change staging.
 
 on:
   push:
@@ -6,7 +13,8 @@ on:
       - main
     paths:
       # Workflow files
-      - .github/workflows/landing-page-deploy.yml
+      - .github/workflows/landing-page-staging.yml
+      - .github/workflows/landing-page-production.yml
       - .github/workflows/landing-page-ci.yml
       # Landing page sources
       - apps/landing-page/**
@@ -20,6 +28,11 @@ on:
       - design-systems/**
       - craft/**
       - templates/**
+      # Plugin marketplace — the registry JSON and bundled official plugin
+      # manifests are read at build time by plugin-registry.ts to render the
+      # /plugins catalogue. Merging a plugin PR MUST trigger a redeploy or the
+      # published catalogue silently falls behind.
+      - plugins/**
       # Workspace plumbing
       - package.json
       - pnpm-lock.yaml
@@ -31,15 +44,18 @@ permissions:
   deployments: write
 
 concurrency:
-  group: landing-page-deploy-${{ github.ref }}
+  group: landing-page-staging-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   deploy:
-    name: Deploy landing page
+    name: Deploy landing page to staging
     if: github.repository == 'nexu-io/open-design'
     runs-on: ubuntu-latest
     timeout-minutes: 20
+    environment:
+      name: landing-staging
+      url: https://staging.open-design.ai
 
     steps:
       - name: Checkout
@@ -65,8 +81,17 @@ jobs:
           version=$(node -p "require('./apps/landing-page/package.json').devDependencies.playwright.replace(/[^0-9.]/g,'')")
           echo "version=$version" >> "$GITHUB_OUTPUT"
 
+      - name: Cache generated previews
+        id: previews-cache
+        uses: actions/cache@v5.0.5
+        with:
+          path: apps/landing-page/public/previews
+          key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
+          restore-keys: |
+            landing-page-previews-${{ runner.os }}-
+
       - name: Cache Playwright browsers
-        uses: actions/cache@v4
+        uses: actions/cache@v5.0.5
         with:
           path: ~/.cache/ms-playwright
           key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
@@ -84,10 +109,26 @@ jobs:
       # exits non-zero so we don't silently ship a deploy with zero
       # thumbnails to production.
       - name: Generate skill + template previews
+        # Skip only on an EXACT previews-cache hit: the cache key hashes every
+        # rendering input, so an exact hit means public/previews already holds
+        # the correct thumbnails and regenerating is wasted work. A restore-keys
+        # partial hit leaves cache-hit unset (false), so we still regenerate
+        # then — no stale-thumbnail drift. This is what lets a plugins-only
+        # deploy skip the slowest step (Playwright screenshotting) while a
+        # skill/template change still re-renders.
+        if: steps.previews-cache.outputs.cache-hit != 'true'
         run: pnpm --filter @open-design/landing-page previews
 
+      # No PUBLIC_GA_MEASUREMENT_ID on staging: leaving it unset omits the
+      # Google Analytics tag entirely, so test-environment traffic does not
+      # pollute the production GA property. OD_LANDING_NOINDEX=1 makes every
+      # page emit <meta name="robots" content="noindex"> so the staging mirror
+      # stays out of search engines. Only `landing-page-production` builds
+      # without these (GA on, indexable).
       - name: Build landing page
-        run: pnpm --filter @open-design/landing-page build
+        env:
+          OD_LANDING_NOINDEX: '1'
+        run: pnpm --filter @open-design/landing-page build:static
 
       - name: Verify zero external JavaScript
         run: |
@@ -123,7 +164,11 @@ jobs:
           }
           NODE
 
-      - name: Deploy to Cloudflare Pages
+      # Deploys to the dedicated STAGING project. `--branch=main` is that
+      # project's production branch, so it serves at its custom domain
+      # staging.open-design.ai. The production project (open-design-landing)
+      # is a different project and is never named here.
+      - name: Deploy to Cloudflare Pages (staging)
         uses: cloudflare/wrangler-action@v3
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
@@ -132,5 +177,5 @@ jobs:
           packageManager: npm
           command: >
             pages deploy out
-            --project-name=open-design-landing
-            --branch=${{ github.ref_name }}
+            --project-name=open-design-landing-staging
+            --branch=main

.github/workflows/nix-hash-autofix.yml

@@ -0,0 +1,205 @@
+name: nix-hash-autofix
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write
+
+jobs:
+  autofix:
+    if: ${{ github.repository == 'nexu-io/open-design' && github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'failure' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check for Nix hash refresh artifact
+        id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          artifact_id="$(gh api "repos/$REPO/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "nix-hash-refresh") | .id' | head -n 1 || true)"
+          if [ -z "$artifact_id" ]; then
+            echo "present=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "present=true" >> "$GITHUB_OUTPUT"
+          echo "artifact_id=$artifact_id" >> "$GITHUB_OUTPUT"
+
+      - name: Download Nix hash refresh artifact
+        if: ${{ steps.artifact.outputs.present == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          ARTIFACT_ID: ${{ steps.artifact.outputs.artifact_id }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          mkdir -p "$RUNNER_TEMP/nix-hash-refresh"
+          gh api \
+            -H 'Accept: application/vnd.github+json' \
+            "repos/$REPO/actions/artifacts/$ARTIFACT_ID/zip" > "$RUNNER_TEMP/nix-hash-refresh.zip"
+          unzip -q "$RUNNER_TEMP/nix-hash-refresh.zip" -d "$RUNNER_TEMP/nix-hash-refresh"
+
+      - name: Read PR and patch metadata
+        if: ${{ steps.artifact.outputs.present == 'true' }}
+        id: meta
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          WORKFLOW_PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number || '' }}
+          WORKFLOW_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          status="$(python3 -c 'import json, sys; data = json.load(open(sys.argv[1], "r", encoding="utf-8")); print(data.get("status", "missing"))' "$RUNNER_TEMP/nix-hash-refresh/metadata.json")"
+          artifact_head_sha="$(python3 -c 'import json, sys; data = json.load(open(sys.argv[1], "r", encoding="utf-8")); print(data.get("headSha", ""))' "$RUNNER_TEMP/nix-hash-refresh/metadata.json")"
+
+          pr_number="$WORKFLOW_PR_NUMBER"
+          if [ -z "$pr_number" ]; then
+            pr_number="$(gh api "repos/$REPO/commits/$WORKFLOW_HEAD_SHA/pulls" --jq '.[0].number // empty')"
+          fi
+          if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then
+            echo "Unable to derive PR number for workflow head $WORKFLOW_HEAD_SHA." >&2
+            exit 1
+          fi
+
+          pr_json="$(gh api "repos/$REPO/pulls/$pr_number")"
+          head_repo="$(printf '%s' "$pr_json" | python3 -c 'import json,sys; print(json.load(sys.stdin)["head"]["repo"]["full_name"])')"
+          head_ref="$(printf '%s' "$pr_json" | python3 -c 'import json,sys; print(json.load(sys.stdin)["head"]["ref"])')"
+          head_sha="$(printf '%s' "$pr_json" | python3 -c 'import json,sys; print(json.load(sys.stdin)["head"]["sha"])')"
+          {
+            echo "status=$status"
+            echo "artifact_head_sha=$artifact_head_sha"
+            echo "pr_number=$pr_number"
+            echo "head_repo=$head_repo"
+            echo "head_ref=$head_ref"
+            echo "head_sha=$head_sha"
+          } >> "$GITHUB_OUTPUT"
+          if [ -n "$artifact_head_sha" ] && [ "$artifact_head_sha" = "$head_sha" ]; then
+            echo "head_sha_matches=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "head_sha_matches=false" >> "$GITHUB_OUTPUT"
+          fi
+          if [ "$head_repo" = "$REPO" ] && [ "$status" = "patch-generated" ] && [ "$artifact_head_sha" = "$head_sha" ]; then
+            echo "can_autopush=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "can_autopush=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Detect bot credentials
+        if: ${{ steps.meta.outputs.can_autopush == 'true' }}
+        id: bot-secrets
+        env:
+          BOT_APP_ID: ${{ secrets.BOT_APP_ID }}
+          BOT_APP_PRIVATE_KEY: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [ -n "${BOT_APP_ID}" ] && [ -n "${BOT_APP_PRIVATE_KEY}" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "present=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate Open Design bot token
+        if: ${{ steps.meta.outputs.can_autopush == 'true' && steps.bot-secrets.outputs.present == 'true' }}
+        id: bot-token
+        continue-on-error: true
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_APP_PRIVATE_KEY }}
+          owner: nexu-io
+          repositories: open-design
+          permission-contents: write
+
+      - name: Checkout PR branch for auto-apply
+        if: ${{ steps.meta.outputs.can_autopush == 'true' && steps.bot-token.outcome == 'success' }}
+        uses: actions/checkout@v6.0.2
+        with:
+          repository: ${{ steps.meta.outputs.head_repo }}
+          ref: ${{ steps.meta.outputs.head_ref }}
+          token: ${{ steps.bot-token.outputs.token }}
+
+      - name: Apply generated hash patch
+        if: ${{ steps.meta.outputs.can_autopush == 'true' && steps.bot-token.outcome == 'success' }}
+        id: apply
+        shell: bash
+        run: |
+          set -euo pipefail
+          patch_path="$RUNNER_TEMP/nix-hash-refresh/nix-pnpm-deps.patch"
+          if [ ! -f "$patch_path" ]; then
+            echo "applied=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          git apply --check "$patch_path"
+          git apply "$patch_path"
+          changed_files="$(git diff --name-only)"
+          if [ "$changed_files" != "nix/pnpm-deps.nix" ]; then
+            echo "Unexpected files changed after applying hash patch:" >&2
+            printf '%s\n' "$changed_files" >&2
+            exit 1
+          fi
+          if git diff --quiet --exit-code; then
+            echo "applied=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "applied=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Commit and push generated hash refresh
+        if: ${{ steps.meta.outputs.can_autopush == 'true' && steps.bot-token.outcome == 'success' && steps.apply.outputs.applied == 'true' }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          git config user.name 'open-design-bot[bot]'
+          git config user.email '282769551+open-design-bot[bot]@users.noreply.github.com'
+          git add nix/pnpm-deps.nix
+          git commit -m 'chore(nix): refresh pnpm deps hash'
+          git push origin "HEAD:${{ steps.meta.outputs.head_ref }}"
+
+      - name: Upsert fork/manual patch comment
+        if: ${{ steps.artifact.outputs.present == 'true' && steps.meta.outputs.head_sha_matches == 'true' && (steps.meta.outputs.can_autopush != 'true' || steps.bot-token.outcome != 'success' || steps.apply.outputs.applied != 'true') }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ steps.meta.outputs.pr_number }}
+          HASH_REFRESH_STATUS: ${{ steps.meta.outputs.status }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          body_file="$RUNNER_TEMP/nix-hash-refresh-comment.md"
+          patch_file="$RUNNER_TEMP/nix-hash-refresh/nix-pnpm-deps.patch"
+          marker='<!-- nix-hash-refresh -->'
+
+          {
+            printf '%s\n' "$marker"
+            if [ "${HASH_REFRESH_STATUS}" = 'patch-generated' ]; then
+              printf "A generated Nix hash refresh is available for this PR.\n\n"
+              printf "Apply the patch from the \`nix-hash-refresh\` artifact attached to the failed \`ci\` run, or paste the diff below into \`git apply\`:\n\n"
+              printf '```diff\n'
+              if [ -f "$patch_file" ]; then
+                cat "$patch_file"
+              else
+                printf '(artifact did not include nix-pnpm-deps.patch)\n'
+              fi
+              printf '\n```\n'
+            else
+              printf "The failed \`ci\` run attempted to refresh \`nix/pnpm-deps.nix\`, but it could not produce a hash-only patch.\n\n"
+              printf "Download the \`nix-hash-refresh\` artifact from that run and inspect \`update.log\` for details.\n"
+            fi
+          } > "$body_file"
+
+          comment_id="$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" --jq ".[] | select(.body | contains(\"$marker\")) | .id" | tail -n 1 || true)"
+          if [ -n "$comment_id" ]; then
+            gh api --method PATCH "repos/$REPO/issues/comments/$comment_id" --field body="$(cat "$body_file")" >/dev/null
+          else
+            gh api --method POST "repos/$REPO/issues/$PR_NUMBER/comments" --field body="$(cat "$body_file")" >/dev/null
+          fi

.github/workflows/release-beta-s.yml

@@ -0,0 +1,64 @@
+# Self-hosted release-beta lane. Hosted baseline remains release-beta.yml.
+name: release-beta-s
+
+on:
+  workflow_dispatch:
+    inputs:
+      enable_win:
+        description: "Run the Windows self-hosted beta lane."
+        required: true
+        type: boolean
+        default: true
+      publish:
+        description: "Publish release assets and metadata. Keep disabled while validating the runner lane."
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: release-beta-s-win
+  cancel-in-progress: false
+
+jobs:
+  windows_probe:
+    name: Probe Windows self-hosted runner
+    if: ${{ inputs.enable_win }}
+    runs-on: [self-hosted, Windows, X64, nexu-win, release-beta]
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6.0.2
+        with:
+          lfs: true
+
+      - name: Verify preinstalled toolchain
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          where.exe git
+          where.exe git-lfs
+          where.exe node
+          where.exe pnpm
+          where.exe cargo
+          where.exe makensis
+          git --version
+          git lfs version
+          node --version
+          pnpm --version
+          cargo --version
+          makensis /VERSION
+
+      - name: Confirm workflow boundary
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          "workspace=$env:GITHUB_WORKSPACE"
+          "runner_temp=$env:RUNNER_TEMP"
+          "runner_tool_cache=$env:RUNNER_TOOL_CACHE"
+          if ($env:GITHUB_WORKSPACE -like "C:\Users\runner\Projects\*") {
+            throw "GITHUB_WORKSPACE must not point at the operator Projects directory"
+          }

.github/workflows/release-beta.yml

@@ -122,11 +122,12 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Verify mac Electron framework symlinks
+      - name: Inspect mac Electron framework symlinks
         run: |
           set -euo pipefail
           electron_dist="$(node -e 'const path = require("node:path"); const { createRequire } = require("node:module"); const requireFromDesktop = createRequire(path.join(process.cwd(), "apps/desktop/package.json")); const electron = requireFromDesktop.resolve("electron"); process.stdout.write(path.join(path.dirname(electron), "dist"));')"
           framework="$electron_dist/Electron.app/Contents/Frameworks/Electron Framework.framework"
+          missing_links=0
           for link in \
             "$framework/Electron Framework" \
             "$framework/Helpers" \
@@ -134,12 +135,15 @@ jobs:
             "$framework/Resources" \
             "$framework/Versions/Current"; do
             if [ ! -L "$link" ]; then
-              echo "Expected Electron framework symlink, got non-symlink: $link" >&2
-              ls -la "$framework" >&2 || true
-              ls -la "$framework/Versions" >&2 || true
-              exit 1
+              echo "::warning::Expected Electron framework symlink, got non-symlink: $link"
+              missing_links=1
             fi
           done
+          if [ "$missing_links" -ne 0 ]; then
+            ls -la "$framework" >&2 || true
+            ls -la "$framework/Versions" >&2 || true
+            echo "Continuing into tools-pack because electron-builder is the source of truth for whether packaging actually works."
+          fi
 
       - name: Prepare Apple signing certificate
         env:
@@ -177,6 +181,7 @@ jobs:
             --mac-compression normal
             --to dmg
             --json
+            --require-vela-cli
             --signed
           )
           if build_output="$(pnpm "${build_args[@]}" 2> >(tee -a "$build_log_path" >&2))"; then
@@ -459,7 +464,7 @@ jobs:
             "--namespace", "release-beta-win",
             "--portable",
             "--app-version", "${{ needs.metadata.outputs.beta_version }}",
-            "--to", "nsis",
+            "--to", "all",
             "--json"
           )
           "cache_failed=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
@@ -477,7 +482,7 @@ jobs:
               --namespace release-beta-win `
               --portable `
               --app-version "${{ needs.metadata.outputs.beta_version }}" `
-              --to nsis `
+              --to all `
               --json
             if ($LASTEXITCODE -ne 0) {
               throw "Windows tools-pack uncached fallback build exited with code $LASTEXITCODE"

.github/workflows/release-preview.yml

@@ -456,7 +456,7 @@ jobs:
             "--namespace", "release-preview-win",
             "--portable",
             "--app-version", "${{ needs.metadata.outputs.release_version }}",
-            "--to", "nsis",
+            "--to", "all",
             "--json"
           )
           "cache_failed=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
@@ -474,7 +474,7 @@ jobs:
               --namespace release-preview-win `
               --portable `
               --app-version "${{ needs.metadata.outputs.release_version }}" `
-              --to nsis `
+              --to all `
               --json
             if ($LASTEXITCODE -ne 0) {
               throw "Windows tools-pack uncached fallback build exited with code $LASTEXITCODE"
@@ -727,6 +727,7 @@ jobs:
           R2_REPORT_ZIP_URL: ${{ steps.r2.outputs.report_zip_url }}
           R2_WIN_FEED_URL: ${{ steps.r2.outputs.win_feed_url }}
           R2_WIN_INSTALLER_URL: ${{ steps.r2.outputs.win_installer_url }}
+          R2_WIN_PORTABLE_ZIP_URL: ${{ steps.r2.outputs.win_portable_zip_url }}
         run: bash .github/scripts/release/r2/verify.sh
 
       - name: Publish summary
@@ -743,6 +744,7 @@ jobs:
           R2_VERSION_PREFIX: ${{ steps.r2.outputs.version_prefix }}
           R2_WIN_FEED_URL: ${{ steps.r2.outputs.win_feed_url }}
           R2_WIN_INSTALLER_URL: ${{ steps.r2.outputs.win_installer_url }}
+          R2_WIN_PORTABLE_ZIP_URL: ${{ steps.r2.outputs.win_portable_zip_url }}
         run: bash .github/scripts/release/r2/summary.sh
 
       - name: Cleanup workflow artifacts

.github/workflows/release-stable.yml

@@ -503,7 +503,7 @@ jobs:
             "--namespace", "${{ needs.metadata.outputs.win_namespace }}",
             "--portable",
             "--app-version", "${{ needs.metadata.outputs.release_version }}",
-            "--to", "nsis",
+            "--to", "all",
             "--json"
           )
           "cache_failed=false" | Out-File -FilePath $env:GITHUB_OUTPUT -Append
@@ -521,7 +521,7 @@ jobs:
               --namespace "${{ needs.metadata.outputs.win_namespace }}" `
               --portable `
               --app-version "${{ needs.metadata.outputs.release_version }}" `
-              --to nsis `
+              --to all `
               --json
             if ($LASTEXITCODE -ne 0) {
               throw "Windows tools-pack uncached fallback build exited with code $LASTEXITCODE"
@@ -888,6 +888,7 @@ jobs:
           R2_REPORT_ZIP_URL: ${{ steps.r2.outputs.report_zip_url }}
           R2_WIN_FEED_URL: ${{ steps.r2.outputs.win_feed_url }}
           R2_WIN_INSTALLER_URL: ${{ steps.r2.outputs.win_installer_url }}
+          R2_WIN_PORTABLE_ZIP_URL: ${{ steps.r2.outputs.win_portable_zip_url }}
         run: bash .github/scripts/release/r2/verify.sh
 
       - name: Promote draft to published latest
@@ -921,6 +922,7 @@ jobs:
           R2_VERSION_PREFIX: ${{ steps.r2.outputs.version_prefix }}
           R2_WIN_FEED_URL: ${{ steps.r2.outputs.win_feed_url }}
           R2_WIN_INSTALLER_URL: ${{ steps.r2.outputs.win_installer_url }}
+          R2_WIN_PORTABLE_ZIP_URL: ${{ steps.r2.outputs.win_portable_zip_url }}
         run: bash .github/scripts/release/r2/summary.sh
 
       - name: Cleanup workflow artifacts

.github/workflows/seo-daily-report.yml

@@ -103,11 +103,11 @@ jobs:
           OPP_LOW_CTR: '0.01'
           OPP_MOBILE_DESKTOP_CTR_GAP: '0.30'
         run: |
-          flags=""
+          flags=()
           if [ -n "${{ github.event.inputs.today }}" ]; then
-            flags="$flags --today ${{ github.event.inputs.today }}"
+            flags+=(--today "${{ github.event.inputs.today }}")
           fi
           if [ "${{ github.event.inputs.dry_run }}" = "true" ]; then
-            flags="$flags --dry-run"
+            flags+=(--dry-run)
           fi
-          pnpm --filter @open-design/landing-page exec tsx scripts/seo-daily-report.ts $flags
+          pnpm --filter @open-design/landing-page exec tsx scripts/seo-daily-report.ts "${flags[@]}"

.github/workflows/visual-pr-capture.yml

@@ -18,7 +18,6 @@ on:
 permissions:
   actions: read
   contents: read
-  pull-requests: write
 
 concurrency:
   group: visual-pr-capture-${{ github.event.pull_request.number }}
@@ -73,132 +72,3 @@ jobs:
             e2e/ui/reports/visual-report/manifest.json
           if-no-files-found: ignore
           retention-days: 7
-
-  comment_same_repo:
-    name: Comment PR visual screenshots
-    needs: [capture]
-    if: ${{ always() && !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository }}
-    runs-on: ubuntu-24.04
-    timeout-minutes: 15
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6.0.2
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v6.0.8
-        with:
-          version: 10.33.2
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6.4.0
-        with:
-          node-version: 24
-          package-manager-cache: false
-
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Download PR visual artifact
-        uses: actions/download-artifact@v8
-        with:
-          run-id: ${{ github.run_id }}
-          path: visual-artifact
-          merge-multiple: true
-          github-token: ${{ github.token }}
-
-      - name: Validate capture manifest
-        id: manifest
-        shell: bash
-        env:
-          EXPECTED_PR_NUMBER: ${{ github.event.pull_request.number }}
-          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          EXPECTED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          EXPECTED_RUN_ID: ${{ github.run_id }}
-        run: |
-          set -euo pipefail
-          manifest="visual-artifact/visual-report/manifest.json"
-          if [ ! -f "$manifest" ]; then
-            manifest="visual-artifact/manifest.json"
-          fi
-          if [ ! -f "$manifest" ]; then
-            echo "Capture manifest not found" >&2
-            find visual-artifact -maxdepth 4 -type f >&2
-            exit 1
-          fi
-          pr_number="$(jq -r '.pr_number' "$manifest")"
-          head_sha="$(jq -r '.head_sha' "$manifest")"
-          base_sha="$(jq -r '.base_sha' "$manifest")"
-          run_id="$(jq -r '.run_id' "$manifest")"
-          capture_outcome="$(jq -r '.capture_outcome // "success"' "$manifest")"
-          if [ "$pr_number" != "$EXPECTED_PR_NUMBER" ] || [ "$head_sha" != "$EXPECTED_HEAD_SHA" ] || [ "$base_sha" != "$EXPECTED_BASE_SHA" ] || [ "$run_id" != "$EXPECTED_RUN_ID" ]; then
-            echo "Capture manifest does not match the current pull_request event." >&2
-            jq . "$manifest" >&2
-            exit 1
-          fi
-          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
-          echo "head_sha=$head_sha" >> "$GITHUB_OUTPUT"
-          echo "base_sha=$base_sha" >> "$GITHUB_OUTPUT"
-          echo "run_id=$run_id" >> "$GITHUB_OUTPUT"
-          echo "capture_outcome=$capture_outcome" >> "$GITHUB_OUTPUT"
-
-      - name: Build visual diff report
-        env:
-          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
-          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
-          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
-          R2_BUCKET: ${{ secrets.R2_BUCKET }}
-          R2_PUBLIC_ORIGIN: ${{ vars.R2_PUBLIC_ORIGIN }}
-          CLOUDFLARE_R2_RELEASES_AK: ${{ secrets.CLOUDFLARE_R2_RELEASES_AK }}
-          CLOUDFLARE_R2_RELEASES_SK: ${{ secrets.CLOUDFLARE_R2_RELEASES_SK }}
-          CLOUDFLARE_R2_RELEASES_BUCKET: ${{ secrets.CLOUDFLARE_R2_RELEASES_BUCKET }}
-          CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN: ${{ vars.CLOUDFLARE_R2_RELEASES_PUBLIC_ORIGIN }}
-          CLOUDFLARE_R2_RELEASES_URL: ${{ secrets.CLOUDFLARE_R2_RELEASES_URL }}
-        run: |
-          pnpm -C e2e exec tsx scripts/visual-report.ts compare-pr \
-            --pr-number "${{ steps.manifest.outputs.pr_number }}" \
-            --run-id "${{ steps.manifest.outputs.run_id }}" \
-            --head-sha "${{ steps.manifest.outputs.head_sha }}" \
-            --base-sha "${{ steps.manifest.outputs.base_sha }}" \
-            --capture-outcome "${{ steps.manifest.outputs.capture_outcome }}" \
-            --screenshots ../visual-artifact/visual-screenshots \
-            --comment-out ui/reports/visual-report/comment.md \
-            --manifest-out ui/reports/visual-report/report-manifest.json
-
-      - name: Upsert PR comment
-        env:
-          GH_TOKEN: ${{ github.token }}
-          PR_NUMBER: ${{ steps.manifest.outputs.pr_number }}
-        run: |
-          set -euo pipefail
-          body_path="e2e/ui/reports/visual-report/comment.md"
-          comments_json="$RUNNER_TEMP/comments.json"
-          gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" > "$comments_json"
-          comment_id="$(jq -r '.[] | select(.body | contains("<!-- visual-regression-bot -->")) | .id' "$comments_json" | tail -n 1)"
-          if [ -n "$comment_id" ]; then
-            gh api --method PATCH "repos/$GITHUB_REPOSITORY/issues/comments/$comment_id" --field "body=$(cat "$body_path")"
-          else
-            gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR_NUMBER/comments" --field "body=$(cat "$body_path")"
-          fi
-
-      - name: Upload visual report artifact
-        if: ${{ always() }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: visual-pr-report-${{ github.event.pull_request.number }}-${{ github.run_id }}
-          path: e2e/ui/reports/visual-report
-          if-no-files-found: ignore
-          retention-days: 7

.github/workflows/visual-pr-comment.yml

@@ -27,15 +27,21 @@ concurrency:
 jobs:
   comment:
     name: Publish PR visual diff comment
+    # Fork PR capture artifacts are untrusted. Always validate the live PR state
+    # and only execute trusted base-repository code before publishing comments
+    # or reports.
     if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 15
 
     steps:
-      - name: Checkout
+      - name: Checkout same-repository workflow head
+        if: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_repository.full_name == github.repository }}
         uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
+          repository: ${{ github.event.workflow_run.head_repository.full_name }}
+          ref: ${{ github.event.workflow_run.head_sha }}
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v6.0.8
@@ -48,25 +54,11 @@ jobs:
           node-version: 24
           package-manager-cache: false
 
-      - name: Resolve pnpm store path
-        id: pnpm-store
-        shell: bash
-        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
-
-      - name: Restore pnpm store cache
-        uses: actions/cache/restore@v5.0.5
-        with:
-          path: ${{ steps.pnpm-store.outputs.path }}
-          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
       - name: Download PR visual artifact
         uses: actions/download-artifact@v8
         with:
           run-id: ${{ github.event.workflow_run.id || inputs.capture_run_id }}
-          path: visual-artifact
+          path: ${{ runner.temp }}/visual-artifact
           merge-multiple: true
           github-token: ${{ github.token }}
 
@@ -77,16 +69,19 @@ jobs:
           GH_TOKEN: ${{ github.token }}
           WORKFLOW_PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number || inputs.pr_number }}
           WORKFLOW_HEAD_SHA: ${{ github.event.workflow_run.head_sha || '' }}
+          WORKFLOW_HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name || '' }}
+          WORKFLOW_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch || '' }}
           WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id || inputs.capture_run_id }}
         run: |
           set -euo pipefail
-          manifest="visual-artifact/visual-report/manifest.json"
+          artifact_dir="$RUNNER_TEMP/visual-artifact"
+          manifest="$artifact_dir/visual-report/manifest.json"
           if [ ! -f "$manifest" ]; then
-            manifest="visual-artifact/manifest.json"
+            manifest="$artifact_dir/manifest.json"
           fi
           if [ ! -f "$manifest" ]; then
             echo "Capture manifest not found" >&2
-            find visual-artifact -maxdepth 4 -type f >&2
+            find "$artifact_dir" -maxdepth 4 -type f >&2
             exit 1
           fi
           manifest_pr_number="$(jq -r '.pr_number' "$manifest")"
@@ -97,22 +92,6 @@ jobs:
             echo "Invalid manifest pr_number: $manifest_pr_number" >&2
             exit 1
           fi
-          derived_pr_number="$WORKFLOW_PR_NUMBER"
-          if [ -z "$derived_pr_number" ] && [ -n "$WORKFLOW_HEAD_SHA" ]; then
-            derived_pr_number="$(gh api "repos/$GITHUB_REPOSITORY/commits/$WORKFLOW_HEAD_SHA/pulls" --jq '.[0].number // empty')"
-          fi
-          pr_number="$derived_pr_number"
-          if [ -z "$pr_number" ]; then
-            pr_number="$manifest_pr_number"
-          fi
-          if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then
-            echo "Unable to derive PR number from workflow event, capture manifest, or GitHub API for workflow head $WORKFLOW_HEAD_SHA." >&2
-            exit 1
-          fi
-          if [ -n "$derived_pr_number" ] && [ "$manifest_pr_number" != "$derived_pr_number" ]; then
-            echo "Manifest pr_number ($manifest_pr_number) does not match GitHub-derived PR number ($derived_pr_number)." >&2
-            exit 1
-          fi
           if ! [[ "$base_sha" =~ ^[0-9a-f]{40}$ ]]; then
             echo "Invalid manifest base_sha: $base_sha" >&2
             exit 1
@@ -125,23 +104,171 @@ jobs:
             echo "Invalid manifest capture_outcome: $capture_outcome" >&2
             exit 1
           fi
+          source_head_sha="$WORKFLOW_HEAD_SHA"
+          source_head_repository="$WORKFLOW_HEAD_REPOSITORY"
+          source_head_branch="$WORKFLOW_HEAD_BRANCH"
+          if [ -z "$source_head_sha" ] || [ -z "$source_head_repository" ] || [ -z "$source_head_branch" ]; then
+            run_json="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$WORKFLOW_RUN_ID")"
+            if [ -z "$source_head_sha" ]; then
+              source_head_sha="$(jq -r '.head_sha // empty' <<< "$run_json")"
+            fi
+            if [ -z "$source_head_repository" ]; then
+              source_head_repository="$(jq -r '.head_repository.full_name // empty' <<< "$run_json")"
+            fi
+            if [ -z "$source_head_branch" ]; then
+              source_head_branch="$(jq -r '.head_branch // empty' <<< "$run_json")"
+            fi
+          fi
           manifest_head="$(jq -r '.head_sha' "$manifest")"
           if ! [[ "$manifest_head" =~ ^[0-9a-f]{40}$ ]]; then
             echo "Invalid manifest head_sha: $manifest_head" >&2
             exit 1
           fi
-          if [ -n "$WORKFLOW_HEAD_SHA" ] && [ "$manifest_head" != "$WORKFLOW_HEAD_SHA" ]; then
-            echo "Artifact manifest head_sha ($manifest_head) does not match workflow_run head_sha ($WORKFLOW_HEAD_SHA)." >&2
+          if ! [[ "$source_head_sha" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "Unable to resolve trusted workflow_run head_sha for run $WORKFLOW_RUN_ID." >&2
             exit 1
           fi
-          echo "path=$manifest" >> "$GITHUB_OUTPUT"
-          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
-          echo "head_sha=$manifest_head" >> "$GITHUB_OUTPUT"
-          echo "base_sha=$base_sha" >> "$GITHUB_OUTPUT"
-          echo "run_id=$run_id" >> "$GITHUB_OUTPUT"
-          echo "capture_outcome=$capture_outcome" >> "$GITHUB_OUTPUT"
+          if [ "$manifest_head" != "$source_head_sha" ]; then
+            echo "Artifact manifest head_sha ($manifest_head) does not match workflow_run head_sha ($source_head_sha)." >&2
+            exit 1
+          fi
+          if [ -z "$source_head_repository" ]; then
+            echo "Unable to resolve trusted workflow_run head repository for run $WORKFLOW_RUN_ID." >&2
+            exit 1
+          fi
+          if [ -z "$source_head_branch" ]; then
+            echo "Unable to resolve trusted workflow_run head branch for run $WORKFLOW_RUN_ID." >&2
+            exit 1
+          fi
+          pr_number="$WORKFLOW_PR_NUMBER"
+          if [ -z "$pr_number" ]; then
+            head_owner="${source_head_repository%%/*}"
+            if [ -z "$head_owner" ] || [ "$head_owner" = "$source_head_repository" ]; then
+              echo "Unable to resolve trusted workflow_run head owner from $source_head_repository." >&2
+              exit 1
+            fi
+            encoded_head="$(jq -rn --arg head "$head_owner:$source_head_branch" '$head|@uri')"
+            matching_pr_numbers="$(
+              gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$encoded_head&per_page=100" \
+                | jq -r --arg repo "$source_head_repository" \
+                    '.[] | select((.head.repo.full_name // "") == $repo) | .number' \
+                | paste -sd ' ' -
+            )"
+            match_count="$(wc -w <<< "$matching_pr_numbers" | tr -d ' ')"
+            if [ "$match_count" -gt 1 ]; then
+              echo "Unable to resolve a unique open PR from trusted workflow metadata for $source_head_repository@$source_head_branch ($source_head_sha); found $match_count matches." >&2
+              exit 1
+            fi
+            if [ "$match_count" -eq 1 ]; then
+              pr_number="$matching_pr_numbers"
+            else
+              pr_number="$manifest_pr_number"
+            fi
+          fi
+          if ! [[ "$pr_number" =~ ^[0-9]+$ ]]; then
+            echo "Unable to derive PR number from trusted workflow metadata for workflow head $source_head_sha." >&2
+            exit 1
+          fi
+          if [ -n "$WORKFLOW_PR_NUMBER" ] && [ "$manifest_pr_number" != "$WORKFLOW_PR_NUMBER" ]; then
+            echo "Manifest pr_number ($manifest_pr_number) does not match workflow_run PR number ($WORKFLOW_PR_NUMBER)." >&2
+            exit 1
+          fi
+          {
+            echo "path=$manifest"
+            echo "pr_number=$pr_number"
+            echo "head_sha=$manifest_head"
+            echo "base_sha=$base_sha"
+            echo "run_id=$run_id"
+            echo "capture_outcome=$capture_outcome"
+            echo "source_head_repository=$source_head_repository"
+            echo "source_head_branch=$source_head_branch"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Validate live PR state for trusted checkout
+        id: trusted-pr
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EVENT_NAME: ${{ github.event_name }}
+          PR_NUMBER: ${{ steps.manifest.outputs.pr_number }}
+          ARTIFACT_HEAD_SHA: ${{ steps.manifest.outputs.head_sha }}
+          ARTIFACT_BASE_SHA: ${{ steps.manifest.outputs.base_sha }}
+          SOURCE_HEAD_REPOSITORY: ${{ steps.manifest.outputs.source_head_repository }}
+          SOURCE_HEAD_BRANCH: ${{ steps.manifest.outputs.source_head_branch }}
+        run: |
+          set -euo pipefail
+          skip_or_fail_stale() {
+            local message="$1"
+            if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+              echo "$message" >&2
+              exit 1
+            fi
+            echo "$message"
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          }
+
+          pr_json="$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER")"
+          pr_state="$(jq -r '.state' <<< "$pr_json")"
+          pr_is_draft="$(jq -r '.draft' <<< "$pr_json")"
+          pr_is_cross_repository="$(jq -r '(.head.repo.full_name // "") != (.base.repo.full_name // "")' <<< "$pr_json")"
+          current_head="$(jq -r '.head.sha' <<< "$pr_json")"
+          current_base="$(jq -r '.base.sha' <<< "$pr_json")"
+          current_head_repository="$(jq -r '.head.repo.full_name // empty' <<< "$pr_json")"
+          current_head_branch="$(jq -r '.head.ref // empty' <<< "$pr_json")"
+          if [ "$pr_state" != "open" ]; then
+            skip_or_fail_stale "Skipping trusted checkout for PR $PR_NUMBER because state is $pr_state."
+          fi
+          if [ "$pr_is_draft" != "false" ]; then
+            skip_or_fail_stale "Skipping trusted checkout for PR $PR_NUMBER because it is draft."
+          fi
+          if [ "$current_head" != "$ARTIFACT_HEAD_SHA" ]; then
+            skip_or_fail_stale "Skipping stale visual artifact for $ARTIFACT_HEAD_SHA; current PR head is $current_head."
+          fi
+          if [ "$current_base" != "$ARTIFACT_BASE_SHA" ]; then
+            skip_or_fail_stale "Skipping stale visual artifact for base $ARTIFACT_BASE_SHA; current PR base is $current_base."
+          fi
+          if [ "$current_head_repository" != "$SOURCE_HEAD_REPOSITORY" ]; then
+            echo "Artifact PR head repository ($current_head_repository) does not match trusted workflow_run head repository ($SOURCE_HEAD_REPOSITORY)." >&2
+            exit 1
+          fi
+          if [ "$current_head_branch" != "$SOURCE_HEAD_BRANCH" ]; then
+            echo "Artifact PR head branch ($current_head_branch) does not match trusted workflow_run head branch ($SOURCE_HEAD_BRANCH)." >&2
+            exit 1
+          fi
+          {
+            echo "stale=false"
+            echo "base_sha=$current_base"
+            echo "is_cross_repository=$pr_is_cross_repository"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Checkout trusted base revision
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' && (github.event_name == 'workflow_dispatch' || github.event.workflow_run.head_repository.full_name != github.repository) }}
+        uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+          repository: ${{ github.repository }}
+          ref: ${{ steps.trusted-pr.outputs.base_sha }}
+
+      - name: Resolve pnpm store path
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' }}
+        id: pnpm-store
+        shell: bash
+        run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+      - name: Restore pnpm store cache
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' }}
+        uses: actions/cache/restore@v5.0.5
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Install dependencies
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' }}
+        run: pnpm install --frozen-lockfile
 
       - name: Stop stale visual runs
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' }}
         id: stale
         env:
           GH_TOKEN: ${{ github.token }}
@@ -150,9 +277,21 @@ jobs:
           ARTIFACT_BASE_SHA: ${{ steps.manifest.outputs.base_sha }}
         run: |
           set -euo pipefail
-          pr_json="$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid,baseRefOid)"
+          pr_json="$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json state,isDraft,headRefOid,baseRefOid)"
+          pr_state="$(jq -r '.state' <<< "$pr_json")"
+          pr_is_draft="$(jq -r '.isDraft' <<< "$pr_json")"
           current_head="$(jq -r '.headRefOid' <<< "$pr_json")"
           current_base="$(jq -r '.baseRefOid' <<< "$pr_json")"
+          if [ "$pr_state" != "OPEN" ]; then
+            echo "Skipping visual report for PR $PR_NUMBER because state is $pr_state."
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$pr_is_draft" != "false" ]; then
+            echo "Skipping visual report for PR $PR_NUMBER because it is draft."
+            echo "stale=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
           if [ "$current_head" != "$ARTIFACT_HEAD_SHA" ]; then
             echo "Skipping stale visual artifact for $ARTIFACT_HEAD_SHA; current PR head is $current_head."
             echo "stale=true" >> "$GITHUB_OUTPUT"
@@ -166,7 +305,7 @@ jobs:
           echo "stale=false" >> "$GITHUB_OUTPUT"
 
       - name: Build visual diff report
-        if: ${{ steps.stale.outputs.stale != 'true' }}
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' && steps.stale.outputs.stale != 'true' }}
         env:
           R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
           R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
@@ -185,12 +324,12 @@ jobs:
             --head-sha "${{ steps.manifest.outputs.head_sha }}" \
             --base-sha "${{ steps.manifest.outputs.base_sha }}" \
             --capture-outcome "${{ steps.manifest.outputs.capture_outcome }}" \
-            --screenshots ../visual-artifact/visual-screenshots \
+            --screenshots "$RUNNER_TEMP/visual-artifact/visual-screenshots" \
             --comment-out ui/reports/visual-report/comment.md \
             --manifest-out ui/reports/visual-report/report-manifest.json
 
       - name: Upsert PR comment
-        if: ${{ steps.stale.outputs.stale != 'true' }}
+        if: ${{ steps.trusted-pr.outputs.stale != 'true' && steps.stale.outputs.stale != 'true' }}
         env:
           GH_TOKEN: ${{ github.token }}
           PR_NUMBER: ${{ steps.manifest.outputs.pr_number }}
@@ -198,9 +337,19 @@ jobs:
           ARTIFACT_BASE_SHA: ${{ steps.manifest.outputs.base_sha }}
         run: |
           set -euo pipefail
-          pr_json="$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefOid,baseRefOid)"
+          pr_json="$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json state,isDraft,headRefOid,baseRefOid)"
+          pr_state="$(jq -r '.state' <<< "$pr_json")"
+          pr_is_draft="$(jq -r '.isDraft' <<< "$pr_json")"
           current_head="$(jq -r '.headRefOid' <<< "$pr_json")"
           current_base="$(jq -r '.baseRefOid' <<< "$pr_json")"
+          if [ "$pr_state" != "OPEN" ]; then
+            echo "Skipping visual comment for PR $PR_NUMBER because state is $pr_state."
+            exit 0
+          fi
+          if [ "$pr_is_draft" != "false" ]; then
+            echo "Skipping visual comment for PR $PR_NUMBER because it is draft."
+            exit 0
+          fi
           if [ "$current_head" != "$ARTIFACT_HEAD_SHA" ]; then
             echo "Skipping stale visual comment for $ARTIFACT_HEAD_SHA; current PR head is $current_head."
             exit 0
@@ -220,7 +369,7 @@ jobs:
           fi
 
       - name: Upload visual report artifact
-        if: ${{ always() && steps.stale.outputs.stale != 'true' }}
+        if: ${{ always() && steps.trusted-pr.outputs.stale != 'true' && steps.stale.outputs.stale != 'true' }}
         uses: actions/upload-artifact@v7
         with:
           name: visual-pr-report-${{ steps.manifest.outputs.pr_number }}-${{ steps.manifest.outputs.run_id }}

.gitignore

@@ -42,9 +42,18 @@ tsconfig.tsbuildinfo
 .cursor/
 .agents/
 .opencode/
-.claude/
+.claude/*
+# Exception: od-contribute skill ships with the repo so the OD app can mount it
+# for non-coder contributors. Personal Claude state (sessions, settings, etc.) stays ignored.
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/od-contribute/
+!.claude/commands/
+.claude/commands/*
+!.claude/commands/od-contribute.md
 .codex/
 .deepseek/
+.antigravitycli/
 
 # Commander task scratchpad; keep local task notes out of git by default.
 .task/
@@ -66,3 +75,8 @@ docs/superpowers/
 # `skills/<slug>/example.html` and `templates/live-artifacts/<slug>/`
 # on every deploy. Should not be committed (~70MB of PNGs).
 apps/landing-page/public/previews/
+
+# Ad-hoc local e2e scripts and their screenshots
+e2e/scripts/test-fal-webui.ts
+e2e/scripts/fal-webui-*.png
+growth/**

AGENTS.md

@@ -14,7 +14,7 @@ This file is the single source of truth for agents entering this repository. Rea
 ## Workspace directories
 
 - Workspace packages come from `pnpm-workspace.yaml`: `apps/*`, `packages/*`, `tools/*`, and `e2e`.
-- Top-level content directories: `skills/` (functional skills the agent invokes mid-task — utilities, briefs, packagers; see `skills/AGENTS.md`), `design-templates/` (rendering catalogue: decks, prototypes, image/video/audio templates; see `design-templates/AGENTS.md` and `specs/current/skills-and-design-templates.md`), `design-systems/` (brand `DESIGN.md` files), `craft/` (universal brand-agnostic craft rules a skill can opt into via `od.craft.requires`).
+- Top-level content directories: `skills/` (functional skills the agent invokes mid-task — utilities, briefs, packagers; see `skills/AGENTS.md`), `design-templates/` (rendering catalogue: decks, prototypes, image/video/audio templates; see `design-templates/AGENTS.md` and `specs/current/skills-and-design-templates.md`), `design-systems/` (brand `DESIGN.md` files), `craft/` (universal brand-agnostic craft rules a skill can opt into via `od.craft.requires`), `mocks/` (replay-based mock CLIs for `opencode`/`claude`/`codex`/`gemini`/`cursor-agent`/`deepseek`/`qwen`/`grok`, the ACP family `devin`/`hermes`/`kilo`/`kimi`/`kiro`/`vibe`, and the AMR `vela` CLI (login + models + ACP), built from anonymized Langfuse traces — PATH-overlay drop-in for tests and self-validation; see `mocks/README.md`).
 - `apps/web` is the Next.js 16 App Router + React 18 web runtime; do not restore `apps/nextjs`.
 - `apps/daemon` is the local privileged daemon and `od` bin. It owns `/api/*`, agent spawning, skills, design systems, artifacts, and static serving.
 - `apps/desktop` is the Electron shell; it discovers the web URL through sidecar IPC.
@@ -23,7 +23,6 @@ This file is the single source of truth for agents entering this repository. Rea
 - `packages/sidecar-proto` owns the Open Design sidecar business protocol; `packages/sidecar` owns the generic sidecar runtime; `packages/platform` owns generic OS process primitives.
 - `tools/dev` is the local development lifecycle control plane.
 - `tools/pack` is the local packaged build/start/stop/logs control plane, packaged updater harness, installer identity/registry validation surface, and mac beta release artifact preparation surface.
-- `tools/pr` is the maintainer PR-duty control plane: a thin `gh` wrapper that encodes this repo's review-lane derivation, forbidden-surface flags, lane checklists, and validation-command suggestions.
 - `tools/serve` is the local fixture-service control plane; first service is `tools-serve start updater` for deterministic updater metadata and artifacts.
 - `e2e` owns user-level end-to-end smoke tests and Playwright UI automation; read `e2e/AGENTS.md` before editing its tests or commands.
 
@@ -58,8 +57,8 @@ This file is the single source of truth for agents entering this repository. Rea
 
 ## Root command boundary
 
-- Keep root scripts reserved for true repo-level checks and tools control-plane entrypoints: `pnpm guard`, `pnpm typecheck`, `pnpm tools-dev`, `pnpm tools-pack`, `pnpm tools-pr`, and `pnpm tools-serve`.
-- Do not add root aggregate `pnpm build` or `pnpm test` aliases. Build/test commands must stay package-scoped (`pnpm --filter <package> ...`) or tool-scoped (`pnpm tools-pack ...` / `pnpm tools-pr ...`).
+- Keep root scripts reserved for true repo-level checks and tools control-plane entrypoints: `pnpm guard`, `pnpm typecheck`, `pnpm tools-dev`, `pnpm tools-pack`, and `pnpm tools-serve`.
+- Do not add root aggregate `pnpm build` or `pnpm test` aliases. Build/test commands must stay package-scoped (`pnpm --filter <package> ...`) or tool-scoped (`pnpm tools-pack ...`).
 - Do not add root e2e aliases; e2e package commands and ownership rules live in `e2e/AGENTS.md`.
 
 ## Release channel model
@@ -123,16 +122,11 @@ Every user-facing capability must be reachable through both the web UI **and** t
 
 ## PR-duty tooling
 
-`pnpm tools-pr` is the maintainer-only control plane for PR-duty work on this repo. It is a thin `gh` wrapper that encodes repo-specific knowledge — review-lane derivation, forbidden-surface flags, per-lane checklists, validation-command suggestions, and a fixed dictionary of factual classify tags (`bot-only-approval`, `needs-rebase`, `stale-approval`, `unresolved-changes-requested`, `awaiting-*` timing, `org-member`, etc.). The tool is read-only on the PR surface: it never approves, merges, comments, or closes; those side effects stay in explicit `gh` invocations the maintainer runs.
-
-Common subcommands:
-
-- `pnpm tools-pr list` — triage the open queue by lane and review-state bucket.
-- `pnpm tools-pr view <num>` — factual review brief for a single PR.
-- `pnpm tools-pr classify --all` — script-level tag JSON for the whole open queue (entry point for cron / digest consumers); per-PR `classify <num>` for spot checks.
-- `pnpm tools-pr assignment` — assigner-perspective ownership + idle-time / blocker view across the queue.
-
-For the full tag dictionary, operational playbook (direct merge / duplicate-title / awaiting-author / org-member / agent-review flows), comment templates, language-detection rules, and tool-design constraints (precision boundaries, factual-output rule, retry + pagination strategy), see [`tools/pr/AGENTS.md`](tools/pr/AGENTS.md).
+This repository no longer ships a maintainer PR-duty control plane. The former
+`pnpm tools-pr` workflow has moved to the standalone `PerishCode/duty` project
+so personal review-lane automation does not become product workspace
+maintenance surface. Do not recreate `tools/pr`, `@open-design/tools-pr`, or a
+root `pnpm tools-pr` script without a new explicit maintainer decision.
 
 ## Agent runtime conventions
 
@@ -145,10 +139,19 @@ For the full tag dictionary, operational playbook (direct merge / duplicate-titl
 ## Chat UI conventions
 
 - `apps/web/src/components/file-viewer-render-mode.ts` decides URL-load vs srcDoc for HTML previews. Bridges (deck, comment/inspect selection, palette, edit, tweaks) can ONLY inject through the srcDoc path. Add a new disqualifier to `UrlLoadDecision` whenever a feature needs a srcDoc-only bridge; pass it from `FileViewer.tsx` based on a source-content heuristic where appropriate (e.g. `hasTweaksTemplate`). The host keeps both iframes mounted simultaneously and swaps CSS visibility so toggling render mode does not cause an iframe reload flash; `iframeRef.current` stays aligned with the active iframe via `useEffect`. Receive filters use `isOurIframe(ev.source)` to accept messages from either iframe but signals that should ONLY come from the active iframe (e.g. `od:tweaks-available`) re-check `ev.source === iframeRef.current?.contentWindow`.
-- TodoWrite UI pins one canonical task list above the chat composer via `PinnedTodoSlot` in `ChatPane.tsx`. The slot reads the latest TodoWrite snapshot across the conversation through `latestTodoWriteInputFromMessages` (`apps/web/src/runtime/todos.ts`). `AssistantMessage.stripTodoToolGroups` removes any TodoWrite tool groups from per message rendering so there is exactly one TodoCard on screen. The progress count includes both `completed` and `in_progress` items (1/4 reads "one underway" not "zero finished"). Dismissal via the Done button is keyed on the snapshot's JSON, so a fresh TodoWrite from the agent automatically re shows the card.
+- TodoWrite UI pins one canonical task list above the chat composer via `PinnedTodoSlot` in `ChatPane.tsx`. The slot reads the latest TodoWrite snapshot across the conversation through `latestTodoWriteInputFromMessages` (`apps/web/src/runtime/todos.ts`). `AssistantMessage.stripTodoToolGroups` removes any TodoWrite tool groups from per message rendering so there is exactly one TodoCard on screen. The progress count includes both `completed` and `in_progress` items (1/4 reads "one underway" not "zero finished"). Dismissal via the Done button is keyed on the snapshot's JSON, so a fresh TodoWrite from the agent automatically re shows the card. `PinnedTodoSlot` sits OUTSIDE the `.chat-log` scroll container, so auto-scroll requires explicit coverage: `ChatPane`'s `ResizeObserver` accepts a `containerRef` from `PinnedTodoSlot` and observes that element directly, and a pane-level `MutationObserver` (`childList: true` on the chat pane ancestor) re-syncs that observation whenever the slot mounts or unmounts as new TodoWrite snapshots arrive.
 - `AskUserQuestionCard` (in `ToolCard.tsx`) prefers the live `onAnswerToolUse(toolUseId, content)` route (POSTs to `/api/runs/:id/tool-result`) and falls back to the legacy `onSubmitForm(text)` path when the run has already terminated. Selected chips persist across reloads by parsing the stored `tool_result.content` back into the selections shape.
 - Tool group rendering uses `dedupeSnapshotToolRetries` to collapse identical `AskUserQuestion` retries (one card per unique input, keeping the latest tool_use_id) and `TodoWrite` snapshots (only the most recent call, since each call is a state replace).
 
+## Web CSS ownership
+
+- `apps/web/src/index.css` is an import-only cascade entrypoint. Do not add selectors or declarations there; add imports only when a truly global stylesheet is needed, and keep import order intentional.
+- Shared global styles belong in `apps/web/src/styles/`: design tokens, base/reset rules, primitives, app-shell layout, and legacy cross-component selectors that cannot safely be scoped yet. Keep domain-level global files grouped by owner (for example `styles/viewer/` and `styles/workspace/`) instead of adding more large files directly under `styles/`.
+- New component-owned UI styles should default to CSS Modules next to the component (`Component.module.css`) instead of expanding global stylesheets. This is preferred for isolated components, panels, menus, drawers, toolbars, cards, and form sections.
+- When touching an existing component with nearby global styles, prefer migrating that component's local selectors to a CSS Module as part of the change if it is small and testable. Do not mix a large mechanical move with behavior/styling changes in the same patch.
+- Keep global class names only for deliberate shared contracts: reusable primitives, theme hooks, third-party/content styling, cross-component layout, or selectors that rely on global cascade/specificity. Document any new global selector group with its owning feature.
+- CSS refactors must preserve cascade semantics. For mechanical splits, verify expanded import content/order matches the previous stylesheet; for CSS Module migrations, validate the affected UI path with `pnpm --filter @open-design/web typecheck` and a focused build/test or visual check when practical.
+
 ## i18n keys
 
 - `apps/web/src/i18n/types.ts` is the typed `Dict`; every key must be defined in all 18 locale files under `apps/web/src/i18n/locales/*.ts` (`ar`, `de`, `en`, `es-ES`, `fa`, `fr`, `hu`, `id`, `ja`, `ko`, `pl`, `pt-BR`, `ru`, `th`, `tr`, `uk`, `zh-CN`, `zh-TW`). Add the key to `types.ts` first; missing translations produce a typecheck error.
@@ -164,6 +167,8 @@ For the full tag dictionary, operational playbook (direct merge / duplicate-titl
 ## Validation strategy
 
 - After package, workspace, or command-entry changes, run `pnpm install` so workspace links and generated dist entries stay fresh.
+- For agent-stream / parser changes (`apps/daemon/src/claude-stream.ts`, `json-event-stream.ts`, `qoder-stream.ts`, etc.), replay a recorded session through the mock CLIs in `mocks/` to verify event shapes round-trip without burning provider budget. PATH-overlay activation: `export PATH="$PWD/mocks/bin:$PATH" OD_MOCKS_TRACE=<8-char-id> OD_MOCKS_NO_DELAY=1`. See `mocks/README.md` for the trace catalog and selection knobs.
+- Treat every `pnpm-lock.yaml` change as requiring a Nix pnpm deps hash refresh check. `nix/pnpm-deps.nix` is a generated lock artifact; use `pnpm nix:update-hash` only when intentionally maintaining Nix packaging, then re-run `nix flake check --print-build-logs --keep-going`. Contributors without Nix can rely on the PR `Validate workspace` gate, which now uploads or auto-applies the generated hash-only fix when possible.
 - Before marking regular work ready, run at least `pnpm guard` and `pnpm typecheck`, plus the package-scoped tests/builds that match the files changed. Do not use or add root `pnpm test`/`pnpm build` aliases.
 - For local web runtime loops, prefer `pnpm tools-dev run web --daemon-port <port> --web-port <port>`.
 - On a GUI-capable machine, validate desktop by running `pnpm tools-dev`, then `pnpm tools-dev inspect desktop status`.
@@ -188,6 +193,7 @@ For a worked example of one full loop (red e2e spec → fix → green), see `e2e
 
 ```bash
 pnpm install
+pnpm nix:update-hash
 pnpm tools-dev
 pnpm tools-serve start updater
 pnpm tools-dev start web
@@ -205,14 +211,6 @@ pnpm guard
 pnpm typecheck
 ```
 
-```bash
-pnpm tools-pr list
-pnpm tools-pr list --bucket=merge-ready,approved-blocked
-pnpm tools-pr list --lane=skill,contract --json
-pnpm tools-pr view 1180
-pnpm tools-pr view 1180 --json
-```
-
 ```bash
 pnpm --filter @open-design/web typecheck
 pnpm --filter @open-design/web test
@@ -222,7 +220,6 @@ pnpm --filter @open-design/daemon build
 pnpm --filter @open-design/desktop build
 pnpm --filter @open-design/tools-dev build
 pnpm --filter @open-design/tools-pack build
-pnpm --filter @open-design/tools-pr build
 pnpm --filter @open-design/tools-serve build
 ```
 

CONTEXT.md

@@ -52,6 +52,34 @@ _Avoid_: generic subject field, hidden prompt text
 The default voice option shown when the Home Audio composer cannot load configured ElevenLabs voices. It keeps ElevenLabs speech runnable by selecting the same default voice id the daemon uses when no explicit voice is supplied.
 _Avoid_: required credential setup, empty voice selector
 
+**AMR Cloud**:
+The user-facing cloud runtime option for Open Design's official model router, shown in onboarding and login-oriented product surfaces.
+_Avoid_: Vela, local CLI label
+
+**AMR CLI**:
+The local command-line runtime adapter used to run AMR from an installed or packaged native CLI.
+_Avoid_: AMR Cloud, cloud account
+
+**AMR CLI Distribution Contract**:
+The separately owned release contract that provides the native AMR CLI builds Open Design can package.
+_Avoid_: Open Design release channel, package build step, source checkout
+
+**AMR CLI Distribution Slice**:
+The set of native AMR CLI platforms currently available through the distribution contract; platforms outside the slice do not bundle the AMR CLI.
+_Avoid_: Open Design supported platforms, release channel, future platform promise
+
+**AMR Account Status**:
+Whether the user has authenticated the account needed to use AMR Cloud.
+_Avoid_: profile badge, environment, CLI version
+
+**AMR Environment Profile**:
+The target AMR service environment a packaged runtime is configured to use.
+_Avoid_: release channel, account status, app identity
+
+**Onboarding Skip**:
+The explicit path that lets a user leave onboarding without completing the currently selected setup option.
+_Avoid_: continue, finish setup, passive close
+
 ## Relationships
 
 - A **Project** contains zero or more **Normal Artifacts**.
@@ -62,6 +90,12 @@ _Avoid_: required credential setup, empty voice selector
 - A **Home Composer Media Surface** maps user intent to an existing project kind and project metadata at submit time.
 - The **Chip Rail** is the visible Home entry point for choosing a **Home Composer Media Surface**.
 - **Essential Audio Generation** uses an **Audio Source Field** plus model options before creating an audio **Project**.
+- **AMR Cloud** is the user-facing product choice; **AMR CLI** is the local execution adapter behind that capability.
+- The **AMR CLI Distribution Contract** is owned separately from Open Design; Open Design release packaging consumes it instead of defining the native CLI release itself.
+- The first **AMR CLI Distribution Slice** is mac arm64 only.
+- **AMR Account Status** describes account readiness for **AMR Cloud**, not the environment profile or CLI installation state.
+- An **AMR Environment Profile** is independent from release channel identity; a beta, preview, nightly, or stable package can target different AMR service environments when explicitly configured.
+- **Onboarding Skip** bypasses setup completion requirements that belong to the normal onboarding continue path.
 
 ## Example dialogue
 

CONTRIBUTING.de.md

@@ -36,7 +36,7 @@ pnpm typecheck            # tsc -b --noEmit
 pnpm --filter @open-design/web build  # Web-Paket bei Bedarf bauen
 ```
 
-Node `~24` und pnpm `10.33.x` sind erforderlich. `nvm` / `fnm` sind optional; nutzen Sie `nvm install 24 && nvm use 24` oder `fnm install 24 && fnm use 24`, wenn Sie Node so verwalten. macOS, Linux und WSL2 sind die primären Pfade. Windows nativ sollte funktionieren, ist aber kein primäres Ziel.
+Node `~24` und pnpm `10.33.x` sind erforderlich. `nvm` / `fnm` sind optional; nutzen Sie `nvm install 24 && nvm use 24` oder `fnm install 24 && fnm use 24`, wenn Sie Node so verwalten. macOS, Linux und WSL2 sind die primären Pfade. Windows nativ wird unterstützt; siehe [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md) für die häufigsten Setup-Stolpersteine.
 
 Sie brauchen keine Agent-CLI im `PATH`, um OD selbst zu entwickeln. Der daemon meldet dann "no agents found" und fällt auf den **Anthropic API · BYOK** Pfad zurück, der oft die schnellste Dev-Schleife ist.
 
@@ -217,6 +217,7 @@ Außerdem:
 
 - **Ein Anliegen pro PR.**
 - **Titel ist imperativ + Scope.** `add dating-web skill`, `fix daemon SSE backpressure when CLI hangs`, `docs: clarify .od layout`.
+- **Nutzen Sie das PR-Template.** Füllen Sie jeden Abschnitt von [`.github/pull_request_template.md`](.github/pull_request_template.md) aus — Why, What users will see, Surface area, Screenshots (bei UI), Bug fix verification (bei Bugfix), Validation. Leere Abschnitte ergeben einen "please fill in"-Kommentar.
 - **Body erklärt das Warum.** Der Diff zeigt oft das Was, aber selten den Grund.
 - **Issue referenzieren**, falls vorhanden. Bei nicht-trivialen PRs ohne Issue bitte zuerst eines öffnen.
 - **Während Review nicht squashen.** Fixups pushen; wir squashen beim Merge.

CONTRIBUTING.fr.md

@@ -48,8 +48,8 @@ Node `~24` et pnpm `10.33.x` sont requis. `nvm` / `fnm` sont optionnels ;
 utilisez `nvm install 24 && nvm use 24` ou `fnm install 24 && fnm use 24` si
 vous gérez Node comme cela. macOS, Linux et WSL2 sont les environnements
 principaux pris en charge.
-Windows natif devrait fonctionner, mais ce n'est pas la cible principale :
-ouvrez une issue si ce n'est pas le cas.
+Windows natif est supporté ; voir [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md)
+pour les pièges de configuration les plus courants.
 
 Vous n'avez pas besoin d'une CLI d'agent dans votre `PATH` pour développer OD.
 Le daemon indiquera "no agents found" ; utilisez alors le mode API/BYOK
@@ -357,6 +357,11 @@ Au-delà de ça :
   dépendance : ce sont trois PR.
 - **Titre impératif + scope.** `add dating-web skill`,
   `fix daemon SSE backpressure when CLI hangs`, `docs: clarify .od layout`.
+- **Utilisez le template de PR.** Remplissez chaque section de
+  [`.github/pull_request_template.md`](.github/pull_request_template.md) — Why,
+  What users will see, Surface area, Screenshots (si UI), Bug fix verification
+  (si correctif), Validation. Les sections vides recevront un commentaire
+  « please fill in ».
 - **Le body explique le pourquoi.** Le diff montre souvent le quoi ; le pourquoi
   est rarement évident.
 - **Référencez une issue** s'il y en a une. S'il n'y en a pas et que la PR est

CONTRIBUTING.ja-JP.md

@@ -36,7 +36,7 @@ pnpm typecheck            # tsc -b --noEmit
 pnpm --filter @open-design/web build  # 必要に応じて web パッケージをビルド
 ```
 
-Node `~24` と pnpm `10.33.x` が必要です。`nvm` / `fnm` はオプション。使用する場合は `nvm install 24 && nvm use 24` または `fnm install 24 && fnm use 24` を実行してください。macOS、Linux、WSL2 が主要プラットフォームです。Windows ネイティブでも動作するはずですが、主要ターゲットではありません — 動作しない場合は issue を作成してください。
+Node `~24` と pnpm `10.33.x` が必要です。`nvm` / `fnm` はオプション。使用する場合は `nvm install 24 && nvm use 24` または `fnm install 24 && fnm use 24` を実行してください。macOS、Linux、WSL2 が主要プラットフォームです。Windows ネイティブもサポートされています — 一般的なセットアップ時の落とし穴については [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md) を参照してください。
 
 OD 自体の開発に agent CLI は `PATH` 上に不要です — daemon は「no agents found」と表示し、**Anthropic API · BYOK** パスにフォールバックします。このパスが最も高速な開発ループです。
 
@@ -213,6 +213,7 @@ design-systems/your-brand/
 
 - **PR 1 つにつき 1 つの関心事。** Skill の追加 + パーサーのリファクタリング + 依存関係のバンプは 3 つの PR です。
 - **タイトルは命令形 + スコープ。** `add dating-web skill`、`fix daemon SSE backpressure when CLI hangs`、`docs: clarify .od layout`。
+- **PR テンプレートを使用する。** [`.github/pull_request_template.md`](.github/pull_request_template.md) の各セクション（Why、What users will see、Surface area、Screenshots（UI の場合）、Bug fix verification（バグ修正の場合）、Validation）をすべて埋めてください。空欄のセクションには "please fill in" のコメントが付きます。
 - **本文は「なぜ」を説明。** 「何をするか」は通常 diff から明らかです。「なぜこれが必要か」はほとんどの場合そうではありません。
 - **issue がある場合は参照。** ない場合で、PR が自明でないなら、先に issue を作成して変更が求められていることを合意してから時間を費やしてください。
 - **レビュー中にスカッシュしない。** fixup をプッシュしてください。マージ時にスカッシュします。

CONTRIBUTING.pt-BR.md

@@ -36,7 +36,7 @@ pnpm typecheck            # tsc -b --noEmit
 pnpm --filter @open-design/web build  # build do pacote web quando necessário
 ```
 
-Node `~24` e pnpm `10.33.x` são obrigatórios. `nvm` / `fnm` são opcionais; use `nvm install 24 && nvm use 24` ou `fnm install 24 && fnm use 24` se preferir gerenciar Node assim. macOS, Linux e WSL2 são os caminhos principais. Windows nativo costuma funcionar, mas não é alvo principal — abra uma issue se quebrar.
+Node `~24` e pnpm `10.33.x` são obrigatórios. `nvm` / `fnm` são opcionais; use `nvm install 24 && nvm use 24` ou `fnm install 24 && fnm use 24` se preferir gerenciar Node assim. macOS, Linux e WSL2 são os caminhos principais. Windows nativo é suportado; veja [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md) para os tropeços de configuração mais comuns.
 
 Você não precisa de nenhum CLI de agente no `PATH` para desenvolver o próprio OD — o daemon dirá "no agents found" e cairá no caminho **Anthropic API · BYOK**, que é o loop de dev mais rápido de qualquer jeito.
 
@@ -243,6 +243,7 @@ Além disso:
 
 - **Uma preocupação por PR.** Adicionar uma skill + refatorar o parser + bumpar uma dep são três PRs.
 - **Título é imperativo + escopo.** `add dating-web skill`, `fix daemon SSE backpressure when CLI hangs`, `docs: clarify .od layout`.
+- **Use o template de PR.** Preencha cada seção de [`.github/pull_request_template.md`](.github/pull_request_template.md) — Why, What users will see, Surface area, Screenshots (se UI), Bug fix verification (se correção de bug), Validation. Seções vazias ganham um comentário "please fill in".
 - **Corpo explica o porquê.** "O que isso faz" geralmente é óbvio do diff; "por que isso precisa existir" raramente é.
 - **Referencie uma issue** se houver. Se não houver e o PR for não-trivial, abra uma antes para combinarmos que a mudança é desejada antes de você gastar o tempo.
 - **Sem squash durante review.** Empurre fixups; squash no merge.

CONTRIBUTING.zh-CN.md

@@ -36,7 +36,7 @@ pnpm typecheck            # tsc -b --noEmit
 pnpm --filter @open-design/web build  # 需要时构建 web package
 ```
 
-要求 Node `~24` 和 pnpm `10.33.x`。`nvm` / `fnm` 是可选路径；如果你习惯用它们，先执行 `nvm install 24 && nvm use 24` 或 `fnm install 24 && fnm use 24`。macOS、Linux、WSL2 是主要路径。Windows 原生应该能跑但不是主要目标 —— 跑不起来请开 issue。
+要求 Node `~24` 和 pnpm `10.33.x`。`nvm` / `fnm` 是可选路径；如果你习惯用它们，先执行 `nvm install 24 && nvm use 24` 或 `fnm install 24 && fnm use 24`。macOS、Linux、WSL2 是主要路径。Windows 原生已支持；常见的安装与配置坑请参见 [`docs/windows-troubleshooting.md`](docs/windows-troubleshooting.md)。
 
 **开发 OD 本身不需要在 `PATH` 上装任何 agent CLI** —— daemon 会告诉你「找不到 agent」并落到 **Anthropic API · BYOK** 路径，反而是最快的开发循环。
 
@@ -234,6 +234,7 @@ node --experimental-strip-types scripts/sync-litellm-models.ts
 
 - **一个 PR 只做一件事。** 加 skill + 重构 parser + 升依赖，是三个 PR。
 - **标题用动词起头 + 范围。** `add dating-web skill`、`fix daemon SSE backpressure when CLI hangs`、`docs: clarify .od layout`。
+- **使用 PR 模板。** 把 [`.github/pull_request_template.md`](.github/pull_request_template.md) 的每一节都填上 —— Why、What users will see、Surface area、Screenshots（如果有 UI 改动）、Bug fix verification（如果是修 bug）、Validation。留空的节会被 reviewer 回 "please fill in"。
 - **正文解释 why。** 「这个 PR 改了什么」从 diff 一般能看出来；「为什么要改」很少能。
 - **如果有 issue，引用它。** 没有、且改动非平凡，请先开 issue 让我们先就「值不值得做」达成一致，再投入时间。
 - **Review 期间不要 squash。** 推 fixup commit；merge 时我们会 squash。

QUICKSTART.md

@@ -55,8 +55,24 @@ docker compose version
 
 From the repository root:
 
+1. Change to the deploy directory and copy the environment template:
+
+   ```bash
+   cd deploy
+   cp .env.example .env
+   ```
+
+2. Generate a secure token:
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. Open `.env` in your editor, find `OD_API_TOKEN=`, and paste the generated token there.
+
+Then start the service:
+
 ```bash
-cd deploy
 docker compose up -d
 ```
 
@@ -107,7 +123,13 @@ docker compose down -v
 
 ## Environment Configuration
 
-Create a `deploy/.env` file to override the default configuration:
+Create a `deploy/.env` file to override the default configuration. Start from the provided example:
+
+```bash
+cp deploy/.env.example deploy/.env
+```
+
+Edit `deploy/.env` to set your own token and adjust other values as needed:
 
 ```env
 # Port exposed on the host
@@ -121,6 +143,10 @@ OPEN_DESIGN_ALLOWED_ORIGINS=https://yourdomain.com
 
 # Docker image tag
 OPEN_DESIGN_IMAGE=docker.io/vanjayak/open-design:latest
+
+# Required API token for daemon security
+# Generate one with: openssl rand -hex 32
+OD_API_TOKEN=
 ```
 
 ---

README.ar.md

@@ -1,18 +1,18 @@
 <div dir="rtl">
 
-# Open Design
+# Open Design — البديل الرسمي مفتوح المصدر لـ [Claude Design][cd]
+
+> **Open Design هو البديل مفتوح المصدر والمحلي أولاً لـ [Claude Design][cd].** قابل للنشر على Vercel، ويدعم BYOK في كل طبقة — **16 أداة CLI لوكلاء البرمجة** يكتشفها تلقائياً من `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) لتصبح هي محرّك التصميم، مدفوعةً بـ **31 Skill قابلة للتركيب** و**72 نظام تصميم بمستوى الهوية البصرية**. لا توجد لديك CLI؟ بروكسي BYOK متوافق مع OpenAI يقدّم نفس الحلقة بدون عملية الـ spawn.
 
 > [!IMPORTANT]
 > ### 🔥 وصلت النسخة `0.8.0-preview`. عالم التصميم القديم ينتهي هنا.
 >
-> بديل مفتوح المصدر و agent-native لـ Claude Design / Figma — 40k نجمة في أسبوعين أوصلتنا إلى هنا. **نحتاجك لدفعنا بقية الطريق.**
+> بديل مفتوح المصدر لـ Claude Design / Figma — 40k نجمة في أسبوعين أوصلتنا إلى هنا. **نحتاجك لدفعنا بقية الطريق.**
 >
 > **تكرار سريع على `main`** — 0.8.0 هي المرحلة التالية من Open Design. أرسل PR، اطرح فكرة جامحة، أبلغ عن عُلّة — ما تجلبه أنت هو ما تصير إليه هذه الحركة.
 >
 > → [**اقرأ الإعلان · حمّل المثبّت · انضم إلى الحركة**](https://github.com/nexu-io/open-design/discussions/1727) · يعمل جنبًا إلى جنب مع نسخة 0.7 الحالية لديك.
 
-> **البديل مفتوح المصدر لـ [Claude Design][cd].** يعمل محلياً أولاً، قابل للنشر على Vercel، ويدعم BYOK في كل طبقة — **16 أداة CLI لوكلاء البرمجة** يكتشفها تلقائياً من `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) لتصبح هي محرّك التصميم، مدفوعةً بـ **31 Skill قابلة للتركيب** و**72 نظام تصميم بمستوى الهوية البصرية**. لا توجد لديك CLI؟ بروكسي BYOK متوافق مع OpenAI يقدّم نفس الحلقة بدون عملية الـ spawn.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — غلاف افتتاحي: صمّم مع الوكيل على حاسوبك المحمول" width="100%" />
 </p>
@@ -800,7 +800,7 @@ Issues و PRs و skills جديدة وأنظمة تصميم جديدة، كلّه
 شكراً لكلّ من ساعد في دفع Open Design للأمام — بكود، بوثائق، بملاحظات، بـ skills جديدة، بأنظمة تصميم جديدة، أو حتى بـ issue حادّة. كلّ مساهمة حقيقية تهمّ، والجدار أدناه أسهل طريقة لقول ذلك علناً.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design contributors" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design contributors" />
 </a>
 
 إن شحنت أوّل PR — مرحباً. تصنيف [`good-first-issue`](https://github.com/nexu-io/open-design/labels/good-first-issue) هو نقطة الدخول.
@@ -817,9 +817,9 @@ Issues و PRs و skills جديدة وأنظمة تصميم جديدة، كلّه
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.de.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — die offizielle Open-Source-Alternative zu [Claude Design][cd]
+
+> **Open Design ist die Open-Source- und Local-first-Alternative zu [Claude Design][cd].** Web-deploybar, BYOK auf jeder Ebene: **16 coding-agent CLIs** werden automatisch in Ihrem `PATH` erkannt (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) und werden zur Design-Engine, gesteuert von **31 kombinierbaren Skills** und **72 brandreifen Design Systems**. Keine CLI? Ein OpenAI-kompatibler BYOK-Proxy ist dieselbe Schleife ohne Spawn.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` ist da. Hier endet die alte Welt des Designs.
 >
-> Eine Open-Source-, agent-native Alternative zu Claude Design / Figma — 40k Sterne in zwei Wochen haben uns hierher gebracht. **Wir brauchen dich für den Rest des Weges.**
+> Eine Open-Source-Alternative zu Claude Design / Figma — 40k Sterne in zwei Wochen haben uns hierher gebracht. **Wir brauchen dich für den Rest des Weges.**
 >
 > **Schnelle Iteration auf `main`** — 0.8.0 ist die nächste Phase von Open Design. Schick einen PR, wirf eine wilde Idee rein, melde einen Bug — was du mitbringst, dazu wird diese Bewegung.
 >
 > → [**Ankündigung lesen · Installer herunterladen · der Bewegung beitreten**](https://github.com/nexu-io/open-design/discussions/1727) · läuft parallel zu deinem aktuellen 0.7.
 
-> **Die Open-Source-Alternative zu [Claude Design][cd].** Local-first, web-deploybar, BYOK auf jeder Ebene: **16 coding-agent CLIs** werden automatisch in Ihrem `PATH` erkannt (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) und werden zur Design-Engine, gesteuert von **31 kombinierbaren Skills** und **72 brandreifen Design Systems**. Keine CLI? Ein OpenAI-kompatibler BYOK-Proxy ist dieselbe Schleife ohne Spawn.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — editorial cover: design with the agent on your laptop" width="100%" />
 </p>
@@ -726,7 +726,7 @@ Vollständiger Walkthrough, Merge-Messlatte, Code Style und was wir nicht annehm
 Danke an alle, die Open Design vorangebracht haben: durch Code, Docs, Feedback, neue Skills, neue Design Systems oder auch ein scharfes Issue. Jeder echte Beitrag zählt, und die Wand unten ist die einfachste Art, das laut zu sagen.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design contributors" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design contributors" />
 </a>
 
 Wenn Sie Ihren ersten PR gemergt haben: willkommen. Das Label [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) ist der Einstiegspunkt.
@@ -743,9 +743,9 @@ Das SVG oben wird täglich von [`.github/workflows/metrics.yml`](.github/workflo
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.es.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — la alternativa open source oficial a [Claude Design][cd]
+
+> **Open Design es la alternativa open source y local-first a [Claude Design][cd].** Desplegable en web, BYOK en cada capa: **16 CLI de coding agents** detectadas automáticamente en tu `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) se convierten en el motor de diseño, impulsadas por **31 Skills componibles** y **72 Design Systems de nivel marca**. ¿No tienes una CLI? Un proxy BYOK compatible con OpenAI ejecuta el mismo bucle sin el spawn local.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` ya está aquí. El viejo mundo del diseño termina aquí.
 >
-> Una alternativa open source y agent-native a Claude Design / Figma — 40k estrellas en dos semanas nos trajeron hasta aquí. **Te necesitamos para empujar el resto del camino.**
+> Una alternativa open source a Claude Design / Figma — 40k estrellas en dos semanas nos trajeron hasta aquí. **Te necesitamos para empujar el resto del camino.**
 >
 > **Iterando rápido sobre `main`** — 0.8.0 es la próxima fase de Open Design. Envía un PR, lanza una idea loca, reporta un bug — lo que traes tú es en lo que este movimiento se convierte.
 >
 > → [**Lee el anuncio · descarga el instalador · únete al movimiento**](https://github.com/nexu-io/open-design/discussions/1727) · funciona en paralelo con tu 0.7 actual.
 
-> **La alternativa open source a [Claude Design][cd].** Local-first, desplegable en web, BYOK en cada capa: **16 CLI de coding agents** detectadas automáticamente en tu `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) se convierten en el motor de diseño, impulsadas por **31 Skills componibles** y **72 Design Systems de nivel marca**. ¿No tienes una CLI? Un proxy BYOK compatible con OpenAI ejecuta el mismo bucle sin el spawn local.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — editorial cover: design with the agent on your laptop" width="100%" />
 </p>
@@ -787,7 +787,7 @@ Walkthrough completo, estándar de merge, code style y lo que no aceptamos → [
 Gracias a todas las personas que han ayudado a mover Open Design hacia adelante: con código, docs, feedback, nuevas skills, nuevos design systems o incluso un issue preciso. Toda contribución real cuenta, y el muro de abajo es la forma más simple de decirlo en voz alta.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Contribuidores de Open Design" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Contribuidores de Open Design" />
 </a>
 
 Si ya enviaste tu primer PR, bienvenido. La etiqueta [`good-first-issue`](https://github.com/nexu-io/open-design/labels/good-first-issue) es el punto de entrada.
@@ -804,9 +804,9 @@ El SVG anterior se regenera diariamente mediante [`.github/workflows/metrics.yml
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Historial de estrellas de Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Historial de estrellas de Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.fr.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — l’alternative open source officielle à [Claude Design][cd]
+
+> **Open Design est l’alternative open source et local-first à [Claude Design][cd].** Déployable sur le web, BYOK à chaque couche : vos CLI de coding agents détectées automatiquement dans le `PATH` deviennent le design engine, piloté par les catalogues de **Skills** et de **Design Systems** du repo. Aucune CLI ? Le proxy BYOK multi-provider exécute la même boucle, sans spawn local.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` est là. L'ancien monde du design s'arrête ici.
 >
-> Une alternative open source et agent-native à Claude Design / Figma — 40k étoiles en deux semaines nous ont menés jusqu'ici. **Nous avons besoin de toi pour faire le reste du chemin.**
+> Une alternative open source à Claude Design / Figma — 40k étoiles en deux semaines nous ont menés jusqu'ici. **Nous avons besoin de toi pour faire le reste du chemin.**
 >
 > **Itération rapide sur `main`** — 0.8.0 est la prochaine phase d'Open Design. Envoie une PR, balance une idée folle, signale un bug — ce que tu apportes, c'est ce que ce mouvement devient.
 >
 > → [**Lire l'annonce · télécharger l'installateur · rejoindre le mouvement**](https://github.com/nexu-io/open-design/discussions/1727) · s'installe à côté de votre 0.7 actuel.
 
-> **L’alternative open source à [Claude Design][cd].** Local-first, déployable sur le web, BYOK à chaque couche : vos CLI de coding agents détectées automatiquement dans le `PATH` deviennent le design engine, piloté par les catalogues de **Skills** et de **Design Systems** du repo. Aucune CLI ? Le proxy BYOK multi-provider exécute la même boucle, sans spawn local.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design : couverture éditoriale, design avec l’agent sur votre laptop" width="100%" />
 </p>
@@ -733,7 +733,7 @@ Guide complet, critères de merge, style de code et refus fréquents → [`CONTR
 Merci à toutes les personnes qui font avancer Open Design : code, docs, retours, nouveaux Skills, nouveaux Design Systems ou issues bien ciblées. Chaque vraie contribution compte.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Contributeurs Open Design" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Contributeurs Open Design" />
 </a>
 
 Si vous avez livré votre première PR, bienvenue. Le label [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) est le point d’entrée.
@@ -750,9 +750,9 @@ Le SVG ci-dessus est régénéré chaque jour par [`.github/workflows/metrics.ym
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Historique des stars Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Historique des stars Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.ja-JP.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — [Claude Design][cd] の公式オープンソース代替
+
+> **Open Design は [Claude Design][cd] のオープンソース、ローカルファーストな代替です。** Vercel デプロイ可能、あらゆるレイヤーで BYOK（Bring Your Own Key） — `PATH` 上で自動検出される **16 種類の coding-agent CLI**（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）がデザインエンジンとなり、**31 個の組み合わせ可能な Skill** と **72 種のブランドグレード Design System** で駆動されます。CLI が未インストールでも、OpenAI 互換の BYOK プロキシ `/api/proxy/stream` で同じループを spawn なしで実行できます。
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` が公開されました。デザインの旧時代は、ここで終わります。
 >
-> オープンソースで agent-native な Claude Design / Figma の代替 —— 2 週間で 40k stars、ここまで来ました。**残りの道のりは、あなたと一緒に進みたい。**
+> Claude Design / Figma のオープンソース代替 —— 2 週間で 40k stars、ここまで来ました。**残りの道のりは、あなたと一緒に進みたい。**
 >
 > **`main` で高速イテレーション中** — 0.8.0 は Open Design の次のフェーズです。PR を投げ、突飛なアイデアを放り込み、バグを報告してください —— あなたが持ち込んだものが、このムーブメントの次の姿になります。
 >
 > → [**告知を読む · インストーラーを入手 · このムーブメントに参加**](https://github.com/nexu-io/open-design/discussions/1727) · 現在の 0.7 と並行してインストールできます。
 
-> **[Claude Design][cd] のオープンソース代替。** ローカルファースト、Vercel デプロイ可能、あらゆるレイヤーで BYOK（Bring Your Own Key） — `PATH` 上で自動検出される **16 種類の coding-agent CLI**（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）がデザインエンジンとなり、**31 個の組み合わせ可能な Skill** と **72 種のブランドグレード Design System** で駆動されます。CLI が未インストールでも、OpenAI 互換の BYOK プロキシ `/api/proxy/stream` で同じループを spawn なしで実行できます。
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — ノートパソコン上のエージェントとデザインする" width="100%" />
 </p>
@@ -723,7 +723,7 @@ Issue、PR、新 Skill、新 Design System を歓迎します。最も効果の
 コード、ドキュメント、フィードバック、新 Skill、新 Design System、あるいは鋭い Issue — あらゆる形で Open Design を前進させてくださったすべての方に感謝します。すべての実質的なコントリビューションは大切であり、以下のウォールは最もシンプルな感謝の表明です。
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design コントリビューター" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design コントリビューター" />
 </a>
 
 初めての PR を送った方 — ようこそ。[`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) ラベルがエントリポイントです。
@@ -740,9 +740,9 @@ Issue、PR、新 Skill、新 Design System を歓迎します。最も効果の
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.ko.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — [Claude Design][cd]의 공식 오픈소스 대안
+
+> **Open Design은 [Claude Design][cd]의 오픈소스, 로컬 우선 대안입니다.** 웹 배포 가능, 모든 레이어에서 BYOK — `PATH`에서 자동 감지되는 **16개의 코딩 에이전트 CLI**(Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI)가 **31가지 조합 가능한 Skill**과 **72가지 브랜드급 디자인 시스템**으로 구동되는 디자인 엔진이 됩니다. CLI가 하나도 없다? OpenAI 호환 BYOK 프록시가 spawn만 빠진 동일한 루프를 돌립니다.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview`가 도착했습니다. 디자인의 옛 시대는 여기서 끝납니다.
 >
-> 오픈소스이자 agent-native한 Claude Design / Figma 대안 — 2주 만에 40k stars로 여기까지 왔습니다. **남은 길은 당신과 함께 가야 합니다.**
+> Claude Design / Figma의 오픈소스 대안 — 2주 만에 40k stars로 여기까지 왔습니다. **남은 길은 당신과 함께 가야 합니다.**
 >
 > **`main`에서 빠르게 이터레이션 중** — 0.8.0은 Open Design의 다음 단계입니다. PR을 보내고, 거친 아이디어를 던지고, 버그를 신고하세요 — 당신이 가져오는 것이 곧 이 무브먼트가 됩니다.
 >
 > → [**공지 읽기 · 인스톨러 다운로드 · 무브먼트에 합류**](https://github.com/nexu-io/open-design/discussions/1727) · 현재 사용 중인 0.7과 나란히 설치됩니다.
 
-> **[Claude Design][cd]의 오픈소스 대안.** 로컬 우선, 웹 배포 가능, 모든 레이어에서 BYOK — `PATH`에서 자동 감지되는 **16개의 코딩 에이전트 CLI**(Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI)가 **31가지 조합 가능한 Skill**과 **72가지 브랜드급 디자인 시스템**으로 구동되는 디자인 엔진이 됩니다. CLI가 하나도 없다? OpenAI 호환 BYOK 프록시가 spawn만 빠진 동일한 루프를 돌립니다.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — 노트북 위의 에이전트와 함께 설계하는 표지" width="100%" />
 </p>
@@ -726,7 +726,7 @@ daemon 부팅 시 `PATH`에서 자동 감지됩니다. 설정 필요 없음. 스
 Open Design을 앞으로 나아가게 도와준 모든 분께 감사드립니다 — 코드, 문서, 피드백, 새 skill, 새 디자인 시스템, 또는 날카로운 이슈 하나라도. 모든 진짜 기여가 의미 있고, 아래의 벽이 가장 직접적인 "감사합니다"입니다.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design 컨트리뷰터" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design 컨트리뷰터" />
 </a>
 
 첫 PR을 보냈다면 — 환영합니다. [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) 레이블이 시작점입니다.
@@ -743,9 +743,9 @@ Open Design을 앞으로 나아가게 도와준 모든 분께 감사드립니다
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — the open-source Claude Design alternative
+
+> **Open Design is the open-source, local-first alternative to [Claude Design][cd].** Web-deployable, BYOK at every layer — **16 coding-agent CLIs** auto-detected on your `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) become the design engine, driven by **137 composable Skills** and **150 brand-grade Design Systems**. No CLI? An OpenAI-compatible BYOK proxy is the same loop minus the spawn.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` is here. Design's old world ends here.
 >
-> An open, agent-native alternative to Claude Design / Figma — 40k stars in two weeks got us this far. **We need you to push the rest of the way.**
+> The open-source alternative to Claude Design / Figma — 40k stars in two weeks got us this far. **We need you to push the rest of the way.**
 >
 > **Iterating fast on `main`** — 0.8.0 is the next phase of Open Design. Ship a PR, drop a wild idea, file a bug — what you bring is what this movement becomes.
 >
 > → [**Read the announcement, grab the installer, join the movement**](https://github.com/nexu-io/open-design/discussions/1727) · runs side-by-side with your current 0.7.
 
-> **The open-source alternative to [Claude Design][cd].** Local-first, web-deployable, BYOK at every layer — **16 coding-agent CLIs** auto-detected on your `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) become the design engine, driven by **31 composable Skills** and **72 brand-grade Design Systems**. No CLI? An OpenAI-compatible BYOK proxy is the same loop minus the spawn.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — editorial cover: design with the agent on your laptop" width="100%" />
 </p>
@@ -30,8 +30,8 @@
   <a href="https://github.com/nexu-io/open-design/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/nexu-io/open-design?style=flat-square&color=blueviolet&label=release&include_prereleases&display_name=tag" /></a>
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square" /></a>
   <a href="#supported-coding-agents"><img alt="Agents" src="https://img.shields.io/badge/agents-16%20CLIs%20%2B%20BYOK%20proxy-black?style=flat-square" /></a>
-  <a href="#design-systems"><img alt="Design systems" src="https://img.shields.io/badge/design%20systems-149-orange?style=flat-square" /></a>
-  <a href="#skills"><img alt="Skills" src="https://img.shields.io/badge/skills-131-teal?style=flat-square" /></a>
+  <a href="#design-systems"><img alt="Design systems" src="https://img.shields.io/badge/design%20systems-150-orange?style=flat-square" /></a>
+  <a href="#skills"><img alt="Skills" src="https://img.shields.io/badge/skills-137-teal?style=flat-square" /></a>
   <a href="https://discord.gg/qhbcCH8Am4"><img alt="Discord" src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
   <a href="https://x.com/nexudotio"><img alt="Follow @nexudotio on X" src="https://img.shields.io/badge/follow-%40nexudotio-1DA1F2?style=flat-square&logo=x&logoColor=white" /></a>
   <a href="QUICKSTART.md"><img alt="Quickstart" src="https://img.shields.io/badge/quickstart-3%20commands-green?style=flat-square" /></a>
@@ -64,9 +64,9 @@ OD stands on four open-source shoulders:
 |---|---|
 | **Coding-agent CLIs (16)** | Claude Code · Codex CLI · Devin for Terminal · Cursor Agent · Gemini CLI · OpenCode · Qwen Code · Qoder CLI · GitHub Copilot CLI · Hermes (ACP) · Kimi CLI (ACP) · Pi (RPC) · Kiro CLI (ACP) · Kilo (ACP) · Mistral Vibe CLI (ACP) · DeepSeek TUI — auto-detected on `PATH`, swap with one click |
 | **BYOK fallback** | Protocol-specific API proxy at `/api/proxy/{anthropic,openai,azure,google,ollama,senseaudio}/stream` — paste `baseUrl` + `apiKey` + `model`, choose Anthropic / OpenAI / Azure OpenAI / Google Gemini / Ollama Cloud / SenseAudio, and the daemon normalizes SSE back to the same chat stream. SenseAudio chat additionally exposes `generate_image` and `generate_video` tools so the model can write rendered artifacts straight into the active project's folder. Internal-IP/SSRF blocked at the daemon edge. |
-| **Design systems built-in** | **129** — 2 hand-authored starters + 70 product systems (Linear, Stripe, Vercel, Airbnb, Tesla, Notion, Anthropic, Apple, Cursor, Supabase, Figma, Xiaohongshu, …) from [`awesome-design-md`][acd2], plus 57 design skills from [`awesome-design-skills`][ads] added directly under `design-systems/` |
-| **Skills built-in** | **31** — 27 in `prototype` mode (web-prototype, saas-landing, dashboard, mobile-app, gamified-app, social-carousel, magazine-poster, dating-web, sprite-animation, motion-frames, critique, tweaks, wireframe-sketch, pm-spec, eng-runbook, finance-report, hr-onboarding, invoice, kanban-board, team-okrs, …) + 4 in `deck` mode (`guizang-ppt` · `simple-deck` · `replit-deck` · `weekly-update`). Grouped in the picker by `scenario`: design / marketing / operation / engineering / product / finance / hr / sale / personal. |
-| **Media generation** | Image · video · audio surfaces ship alongside the design loop. **gpt-image-2** (Azure / OpenAI) for posters, avatars, infographics, illustrated maps · **Seedance 2.0** (ByteDance) for cinematic 15s text-to-video and image-to-video · **HyperFrames** ([heygen-com/hyperframes](https://github.com/heygen-com/hyperframes)) for HTML→MP4 motion graphics (product reveals, kinetic typography, data charts, social overlays, logo outros). **93** ready-to-replicate prompts gallery — 43 gpt-image-2 + 39 Seedance + 11 HyperFrames — under [`prompt-templates/`](prompt-templates/), with preview thumbnails and source attribution. Same chat surface as code; outputs a real `.mp4` / `.png` chip into the project workspace. |
+| **Design systems built-in** | **150** — hand-authored starters plus product systems (Linear, Stripe, Vercel, Airbnb, Tesla, Notion, Anthropic, Apple, Cursor, Supabase, Figma, Xiaohongshu, …) from [`awesome-design-md`][acd2], with curated entries from [`awesome-design-skills`][ads] added directly under `design-systems/` |
+| **Skills built-in** | **137** — across `prototype` (web-prototype, saas-landing, dashboard, mobile-app, gamified-app, social-carousel, magazine-poster, dating-web, sprite-animation, motion-frames, critique, tweaks, wireframe-sketch, pm-spec, eng-runbook, finance-report, hr-onboarding, invoice, kanban-board, team-okrs, …), `deck` (`guizang-ppt` · `simple-deck` · `replit-deck` · `weekly-update`), and `image` / `video` / `audio` / `template` / `design-system` / `utility` modes. Grouped in the picker by `scenario`: design / marketing / operation / engineering / product / finance / hr / sale / personal. |
+| **Media generation** | Image · video · audio surfaces ship alongside the design loop. **gpt-image-2** (Azure / OpenAI) for posters, avatars, infographics, illustrated maps · **Seedance 2.0** (ByteDance) for cinematic 15s text-to-video and image-to-video · **HyperFrames** ([heygen-com/hyperframes](https://github.com/heygen-com/hyperframes)) for HTML→MP4 motion graphics (product reveals, kinetic typography, data charts, social overlays, logo outros). Other image generators can already plug in through **Custom Image API** / **ImageRouter** when they expose an OpenAI-compatible image endpoint; workflow-first local runtimes such as **ComfyUI** are tracked separately as planned adapters. **93** ready-to-replicate prompts gallery — 43 gpt-image-2 + 39 Seedance + 11 HyperFrames — under [`prompt-templates/`](prompt-templates/), with preview thumbnails and source attribution. Same chat surface as code; outputs a real `.mp4` / `.png` chip into the project workspace. |
 | **Visual directions** | 5 curated schools (Editorial Monocle · Modern Minimal · Warm Soft · Tech Utility · Brutalist Experimental) — each ships a deterministic OKLch palette + font stack ([`apps/daemon/src/prompts/directions.ts`](apps/daemon/src/prompts/directions.ts)) |
 | **Device frames** | iPhone 15 Pro · Pixel · iPad Pro · MacBook · Browser Chrome — pixel-accurate, shared across skills under [`assets/frames/`](assets/frames/) |
 | **Agent runtime** | Local daemon spawns the CLI in your project folder — agent gets real `Read`, `Write`, `Bash`, `WebFetch` against a real on-disk environment, with Windows `ENAMETOOLONG` fallbacks (stdin / prompt-file) on every adapter |
@@ -111,8 +111,8 @@ Linux AppImage packaging is available through the optional release lane and is c
 <sub><b>Sandboxed preview</b> — every <code>&lt;artifact&gt;</code> renders in a clean srcdoc iframe. Editable in place via the file workspace; downloadable as HTML, PDF, ZIP.</sub>
 </td>
 <td width="50%">
-<img src="docs/screenshots/06-design-systems-library.png" alt="06 · 72-system library" /><br/>
-<sub><b>72-system library</b> — every product system shows its 4-color signature. Click for the full <code>DESIGN.md</code>, swatch grid, and live showcase.</sub>
+<img src="docs/screenshots/06-design-systems-library.png" alt="06 · 150-system library" /><br/>
+<sub><b>150-system library</b> — every product system shows its 4-color signature. Click for the full <code>DESIGN.md</code>, swatch grid, and live showcase.</sub>
 </td>
 </tr>
 <tr>
@@ -129,9 +129,9 @@ Linux AppImage packaging is available through the optional release lane and is c
 
 ## Skills
 
-**31 skills ship in the box.** Each is a folder under [`skills/`](skills/) following the Claude Code [`SKILL.md`][skill] convention with an extended `od:` frontmatter that the daemon parses verbatim — `mode`, `platform`, `scenario`, `preview.type`, `design_system.requires`, `default_for`, `featured`, `fidelity`, `speaker_notes`, `animations`, `example_prompt` ([`apps/daemon/src/skills.ts`](apps/daemon/src/skills.ts)).
+**137 skills ship in the box.** Each is a folder under [`skills/`](skills/) following the Claude Code [`SKILL.md`][skill] convention with an extended `od:` frontmatter that the daemon parses verbatim — `mode`, `platform`, `scenario`, `preview.type`, `design_system.requires`, `default_for`, `featured`, `fidelity`, `speaker_notes`, `animations`, `example_prompt` ([`apps/daemon/src/skills.ts`](apps/daemon/src/skills.ts)).
 
-Two top-level **modes** carry the catalog: **`prototype`** (27 skills — anything that renders as a single-page artifact, from a magazine landing to a phone screen to a PM spec doc) and **`deck`** (4 skills — horizontal-swipe presentations with deck-framework chrome). The **`scenario`** field is what the picker groups them by: `design` · `marketing` · `operation` · `engineering` · `product` · `finance` · `hr` · `sale` · `personal`.
+Two **modes** anchor the interactive catalog: **`prototype`** (anything that renders as a single-page artifact, from a magazine landing to a phone screen to a PM spec doc) and **`deck`** (horizontal-swipe presentations with deck-framework chrome). The catalog also ships `image`, `video`, `audio`, `template`, `design-system`, and `utility` modes for media generation, catalog updaters, and post-export audit helpers. The **`scenario`** field is what the picker groups them by: `design` · `marketing` · `operation` · `engineering` · `product` · `finance` · `hr` · `sale` · `personal`.
 
 ### Showcase examples
 
@@ -259,8 +259,8 @@ What you compose at send time isn't "system + user". It's:
 ```
 DISCOVERY directives  (turn-1 form, turn-2 brand branch, TodoWrite, 5-dim critique)
   + identity charter   (OFFICIAL_DESIGNER_PROMPT, anti-AI-slop, junior-pass)
-  + active DESIGN.md   (72 systems available)
-  + active SKILL.md    (31 skills available)
+  + active DESIGN.md   (150 systems available)
+  + active SKILL.md    (137 skills available)
   + project metadata   (kind, fidelity, speakerNotes, animations, inspiration ids)
   + skill side files   (auto-injected pre-flight: read assets/template.html + references/*.md)
   + (deck kind, no skill seed) DECK_FRAMEWORK_DIRECTIVE   (nav / counter / scroll / print)
@@ -338,9 +338,25 @@ docker compose version
 
 #### Start Open Design
 
-```bash id="m9w43w"
-git clone https://github.com/nexu-io/open-design.git
-cd open-design/deploy
+1. Clone the repository, change to the deploy directory, and copy the environment template:
+
+   ```bash
+   git clone https://github.com/nexu-io/open-design.git
+   cd open-design/deploy
+   cp .env.example .env
+   ```
+
+2. Generate a secure token:
+
+   ```bash
+   openssl rand -hex 32
+   ```
+
+3. Open `.env` in your editor, find `OD_API_TOKEN=`, and paste the generated token there.
+
+Then start the service:
+
+```bash
 docker compose up -d
 ```
 
@@ -392,7 +408,7 @@ For desktop/background startup, fixed-port restarts, and media generation dispat
 The first load:
 
 1. Detects which agent CLIs you have on `PATH` and picks one automatically.
-2. Loads 31 skills + 72 design systems.
+2. Loads 137 skills + 150 design systems.
 3. Pops the welcome dialog so you can paste an Anthropic key (only needed for the BYOK fallback path).
 4. **Auto-creates `./.od/`** — the local runtime folder for the SQLite project DB, per-project artifacts, and saved renders. There is no `od init` step; the daemon `mkdir`s everything it needs on boot.
 
@@ -693,7 +709,7 @@ open-design/
 │   ├── sidecar/                   ← generic sidecar runtime primitives
 │   └── platform/                  ← generic process/platform primitives
 │
-├── skills/                        ← 31 SKILL.md skill bundles (27 prototype + 4 deck)
+├── skills/                        ← 137 SKILL.md skill bundles (prototype, deck, image, video, audio, template, design-system, utility)
 │   ├── web-prototype/             ← default for prototype mode
 │   ├── saas-landing/  dashboard/  pricing-page/  docs-page/  blog-post/
 │   ├── mobile-app/  mobile-onboarding/  gamified-app/
@@ -708,7 +724,7 @@ open-design/
 │       ├── assets/template.html   ← seed
 │       └── references/{themes,layouts,components,checklist}.md
 │
-├── design-systems/                ← 72 DESIGN.md systems
+├── design-systems/                ← 150 DESIGN.md systems
 │   ├── default/                   ← Neutral Modern (starter)
 │   ├── warm-editorial/            ← Warm Editorial (starter)
 │   ├── linear-app/  vercel/  stripe/  airbnb/  notion/  cursor/  apple/  …
@@ -750,10 +766,10 @@ open-design/
 ## Design Systems
 
 <p align="center">
-  <img src="docs/assets/design-systems-library.png" alt="The 72 design systems library — style guide spread" width="100%" />
+  <img src="docs/assets/design-systems-library.png" alt="The 150 design systems library — style guide spread" width="100%" />
 </p>
 
-72 systems out of the box, each as a single [`DESIGN.md`](design-systems/README.md):
+150 systems out of the box, each as a single [`DESIGN.md`](design-systems/README.md):
 
 <details>
 <summary><b>Full catalog</b> (click to expand)</summary>
@@ -798,7 +814,7 @@ Full spec → [`apps/daemon/src/prompts/directions.ts`](apps/daemon/src/prompts/
 
 OD doesn't stop at code. The same chat surface that produces `<artifact>` HTML also drives **image**, **video**, and **audio** generation, with model adapters wired into the daemon's media pipeline ([`apps/daemon/src/media-models.ts`](apps/daemon/src/media-models.ts), [`apps/web/src/media/models.ts`](apps/web/src/media/models.ts)). Every render lands as a real file in the project workspace — `.png` for image, `.mp4` for video — and shows up as a download chip when the turn ends.
 
-Three model families carry the load today:
+Three flagship paths carry the load today:
 
 | Surface | Model | Provider | What it's for |
 |---|---|---|---|
@@ -806,6 +822,12 @@ Three model families carry the load today:
 | **Video** | `seedance-2.0` | ByteDance Volcengine | 15s cinematic t2v + i2v with audio — narrative shorts, character close-ups, product films, MV-style choreography |
 | **Video** | `hyperframes-html` | [HeyGen / OSS](https://github.com/heygen-com/hyperframes) | HTML→MP4 motion graphics — product reveals, kinetic typography, data charts, social overlays, logo outros, TikTok-style verticals with karaoke captions |
 
+Other generators are possible, but the path depends on the API shape:
+
+- **Today:** use **Settings → Media providers → Custom Image API** for any local or hosted image generator that exposes an OpenAI-compatible `POST /v1/images/generations` endpoint. **ImageRouter** covers the same contract for routed image and video backends.
+- **Not wired yet:** workflow-first local runtimes such as **ComfyUI**. OD now lists ComfyUI in the Media providers “Coming soon” drawer to make that gap explicit, but direct JSON-workflow execution still needs a dedicated adapter.
+- **Still provider-specific:** arbitrary non-OpenAI-compatible video APIs. Those need a first-class daemon integration rather than just a base URL swap.
+
 A growing **prompt gallery** at [`prompt-templates/`](prompt-templates/) ships **93 ready-to-replicate prompts** — 43 image (`prompt-templates/image/*.json`), 39 Seedance (`prompt-templates/video/*.json` excluding `hyperframes-*`), 11 HyperFrames (`prompt-templates/video/hyperframes-*.json`). Each carries a preview thumbnail, the prompt body verbatim, the target model, the aspect ratio, and a `source` block for license + attribution. The daemon serves them at `GET /api/prompt-templates`, the web app surfaces them as a card grid in the **Image templates** and **Video templates** tabs of the entry view; one click drops a prompt into the composer with the right model preselected.
 
 ### gpt-image-2 — image gallery (sample of 43)
@@ -873,7 +895,7 @@ The chat / artifact loop gets the spotlight, but a handful of less-visible capab
 
 - **Claude Design ZIP import.** Drop an export from claude.ai onto the welcome dialog. `POST /api/import/claude-design` extracts it into a real `.od/projects/<id>/`, opens the entry file as a tab, and stages a continue-where-Anthropic-left-off prompt for your local agent. No re-prompting, no "ask the model to re-create what we just had". ([`apps/daemon/src/server.ts`](apps/daemon/src/server.ts) — `/api/import/claude-design`)
 - **Multi-provider BYOK proxy.** `POST /api/proxy/{anthropic,openai,azure,google,ollama,senseaudio}/stream` takes `{ baseUrl, apiKey, model, messages }`, builds the provider-specific upstream request, normalizes SSE chunks into `delta/end/error`, and allows loopback local LLM providers while rejecting non-loopback private, link-local, CGNAT, multicast, reserved, and redirect targets to head off SSRF. OpenAI-compatible covers OpenAI, Azure AI Foundry `/openai/v1`, DeepSeek, Groq, MiMo, OpenRouter, Ollama, LM Studio, and self-hosted vLLM; Azure OpenAI adds deployment URL + `api-version`; Google uses Gemini `:streamGenerateContent`.
-- **User-saved templates.** Once you like a render, `POST /api/templates` snapshots the HTML + metadata into the SQLite `templates` table. The next project picks it from a "your templates" row in the picker — same surface as the shipped 31, but yours.
+- **User-saved templates.** Once you like a render, `POST /api/templates` snapshots the HTML + metadata into the SQLite `templates` table. The next project picks it from a "your templates" row in the picker — same surface as the shipped 137, but yours.
 - **Tab persistence.** Every project remembers its open files and active tab in the `tabs` table. Reopen the project tomorrow and the workspace looks exactly the way you left it.
 - **Artifact lint API.** `POST /api/artifacts/lint` runs structural checks on a generated artifact (broken `<artifact>` framing, missing required side files, stale palette tokens) and returns findings the agent can read back into its next turn. The five-dim self-critique uses this to ground its score in real evidence, not vibes.
 - **Sidecar protocol + desktop automation.** Daemon, web, and desktop processes carry typed five-field stamps (`app · mode · namespace · ipc · source`) and expose a JSON-RPC IPC channel at `/tmp/open-design/ipc/<namespace>/<app>.sock`. `tools-dev inspect desktop status \| eval \| screenshot` drives that channel, so headless E2E works against a real Electron shell without bespoke harnesses ([`packages/sidecar-proto/`](packages/sidecar-proto/), [`apps/desktop/src/main/`](apps/desktop/src/main/)).
@@ -899,8 +921,8 @@ The whole machinery below is the [`huashu-design`](https://github.com/alchaincyf
 | Form factor | Web (claude.ai) | Desktop (Electron) | **Web app + local daemon** |
 | Deployable on Vercel | ❌ | ❌ | **✅** |
 | Agent runtime | Bundled (Opus 4.7) | Bundled ([`pi-ai`][piai]) | **Delegated to user's existing CLI** |
-| Skills | Proprietary | 12 custom TS modules + `SKILL.md` | **31 file-based [`SKILL.md`][skill] bundles, droppable** |
-| Design system | Proprietary | `DESIGN.md` (v0.2 roadmap) | **`DESIGN.md` × 129 systems shipped** |
+| Skills | Proprietary | 12 custom TS modules + `SKILL.md` | **137 file-based [`SKILL.md`][skill] bundles, droppable** |
+| Design system | Proprietary | `DESIGN.md` (v0.2 roadmap) | **`DESIGN.md` × 150 systems shipped** |
 | Provider flexibility | Anthropic only | 7+ via [`pi-ai`][piai] | **16 CLI adapters + OpenAI-compatible BYOK proxy** |
 | Init question form | ❌ | ❌ | **✅ Hard rule, turn 1** |
 | Direction picker | ❌ | ❌ | **✅ 5 deterministic directions** |
@@ -972,7 +994,7 @@ Long-form provenance write-up — what we take from each, what we deliberately d
 
 - [x] Daemon + agent detection (16 CLI adapters) + skill registry + design-system catalog
 - [x] Web app + chat + question form + 5-direction picker + todo progress + sandboxed preview
-- [x] 31 skills + 72 design systems + 5 visual directions + 5 device frames
+- [x] 137 skills + 150 design systems + 5 visual directions + 5 device frames
 - [x] SQLite-backed projects · conversations · messages · tabs · templates
 - [x] Multi-provider BYOK proxy (`/api/proxy/{anthropic,openai,azure,google,ollama,senseaudio}/stream`) with SSRF guard
 - [x] Claude Design ZIP import (`/api/import/claude-design`)
@@ -1018,7 +1040,7 @@ Full walkthrough, bar-for-merging, code style, and what we don't accept → [`CO
 Thanks to everyone who has helped move Open Design forward — through code, docs, feedback, new skills, new design systems, or even a sharp issue. Every real contribution counts, and the wall below is the easiest way to say so out loud.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design contributors" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design contributors" />
 </a>
 
 If you've shipped your first PR — welcome. The [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) label is the entry point.
@@ -1035,9 +1057,9 @@ The SVG above is regenerated daily by [`.github/workflows/metrics.yml`](.github/
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.pt-BR.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — a alternativa open source oficial ao [Claude Design][cd]
+
+> **Open Design é a alternativa open source e local-first ao [Claude Design][cd].** Deployável via web, BYOK em toda camada — **16 CLIs de agentes de código** detectados automaticamente no seu `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) viram a engine de design, dirigidos por **31 Skills compositáveis** e **72 Design Systems de qualidade de marca**. Sem CLI? Um proxy BYOK compatível com OpenAI é o mesmo loop, só sem o spawn.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` chegou. O velho mundo do design acaba aqui.
 >
-> Uma alternativa open source e agent-native ao Claude Design / Figma — 40k estrelas em duas semanas nos trouxeram até aqui. **Precisamos de você para nos levar o resto do caminho.**
+> Uma alternativa open source ao Claude Design / Figma — 40k estrelas em duas semanas nos trouxeram até aqui. **Precisamos de você para nos levar o resto do caminho.**
 >
 > **Iterando rápido na `main`** — 0.8.0 é a próxima fase do Open Design. Mande um PR, jogue uma ideia maluca, abra um bug — o que você traz é no que este movimento se transforma.
 >
 > → [**Leia o anúncio · baixe o instalador · junte-se ao movimento**](https://github.com/nexu-io/open-design/discussions/1727) · roda em paralelo com seu 0.7 atual.
 
-> **A alternativa open-source ao [Claude Design][cd].** Local-first, deployável via web, BYOK em toda camada — **16 CLIs de agentes de código** detectados automaticamente no seu `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) viram a engine de design, dirigidos por **31 Skills compositáveis** e **72 Design Systems de qualidade de marca**. Sem CLI? Um proxy BYOK compatível com OpenAI é o mesmo loop, só sem o spawn.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — capa editorial: design com o agente no seu laptop" width="100%" />
 </p>
@@ -730,7 +730,7 @@ Walkthrough completo, barra para mergear, estilo de código e o que não aceitam
 Obrigado a todas as pessoas que ajudaram a empurrar o Open Design pra frente — via código, docs, feedback, novas skills, novos design systems ou até uma issue afiada. Toda contribuição real conta, e a parede abaixo é a forma mais simples de dizer isso em voz alta.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Contribuidoras e contribuidores do Open Design" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Contribuidoras e contribuidores do Open Design" />
 </a>
 
 Se você acabou de mandar seu primeiro PR — bem-vindo. A label [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) é o ponto de entrada.
@@ -747,9 +747,9 @@ O SVG acima é regenerado diariamente por [`.github/workflows/metrics.yml`](.git
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Histórico de estrelas do Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Histórico de estrelas do Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.ru.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — официальная open-source альтернатива [Claude Design][cd]
+
+> **Open Design — открытая, локально-ориентированная альтернатива [Claude Design][cd].** Пригодна для web-деплоя, с BYOK на каждом уровне: **16 CLI coding-агентов** автоматически обнаруживаются в вашем `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) и превращаются в движок генерации дизайна, управляемый **31 комбинируемым навыком** и **72 дизайн-системами уровня бренда**. Нет CLI? OpenAI-совместимый BYOK-прокси даёт тот же цикл без локального запуска агента.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` уже здесь. Старый мир дизайна заканчивается здесь.
 >
-> Open-source, agent-native альтернатива Claude Design / Figma — 40k звёзд за две недели довели нас до этой точки. **Дальше — только с тобой.**
+> Open-source альтернатива Claude Design / Figma — 40k звёзд за две недели довели нас до этой точки. **Дальше — только с тобой.**
 >
 > **Быстрая итерация на `main`** — 0.8.0 — следующая фаза Open Design. Кидай PR, бросай безумную идею, заводи баг — что приносишь ты, таким и становится это движение.
 >
 > → [**Прочитать анонс · скачать установщик · присоединиться к движению**](https://github.com/nexu-io/open-design/discussions/1727) · устанавливается параллельно с твоей текущей 0.7.
 
-> **Открытая альтернатива [Claude Design][cd].** Локально-ориентированная, пригодная для web-деплоя, с BYOK на каждом уровне: **16 CLI coding-агентов** автоматически обнаруживаются в вашем `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) и превращаются в движок генерации дизайна, управляемый **31 комбинируемым навыком** и **72 дизайн-системами уровня бренда**. Нет CLI? OpenAI-совместимый BYOK-прокси даёт тот же цикл без локального запуска агента.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — редакционная обложка: дизайн вместе с агентом на вашем ноутбуке" width="100%" />
 </p>
@@ -729,7 +729,7 @@ Issues, PR, новые skills и новые design systems приветству
 Спасибо всем, кто помогает двигать Open Design вперёд — кодом, документацией, обратной связью, новыми skills, новыми design systems или просто точным issue. Вклад любого реального масштаба здесь важен, а стена ниже — самый простой способ сказать это вслух.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Contributors Open Design" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Contributors Open Design" />
 </a>
 
 Если вы только что отправили свой первый PR — добро пожаловать. Метка [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) — хорошая точка входа.
@@ -746,9 +746,9 @@ SVG выше ежедневно пересобирается workflow [`.github/
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="История звёзд Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="История звёзд Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.tr.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — [Claude Design][cd]'in resmi açık kaynak alternatifi
+
+> **Open Design, [Claude Design][cd]'in açık kaynak ve yerel öncelikli alternatifidir.** Web'e dağıtılabilir, her katmanda BYOK; `PATH` üzerinde otomatik algılanan **16 coding-agent CLI** (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) tasarım motoruna dönüşür. Hepsi **31 birleştirilebilir Skill** ve **72 marka kalitesinde Design System** tarafından yönlendirilir. CLI yok mu? OpenAI uyumlu BYOK proxy aynı döngünün agent spawn olmadan çalışan halidir.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` burada. Tasarımın eski dünyası burada bitiyor.
 >
-> Claude Design / Figma'ya açık kaynaklı, agent-native bir alternatif — iki haftada 40k stars bizi buraya getirdi. **Yolun geri kalanını birlikte yürüyelim.**
+> Claude Design / Figma'ya açık kaynaklı bir alternatif — iki haftada 40k stars bizi buraya getirdi. **Yolun geri kalanını birlikte yürüyelim.**
 >
 > **`main` üzerinde hızlı iterasyon** — 0.8.0 Open Design'in bir sonraki aşaması. Bir PR gönder, çılgın bir fikir at, bir bug bildir — sen ne getirirsen bu hareket o olur.
 >
 > → [**Duyuruyu oku · kurulum dosyasını indir · harekete katıl**](https://github.com/nexu-io/open-design/discussions/1727) · mevcut 0.7'nin yanına paralel kurulur.
 
-> **[Claude Design][cd] için açık kaynak alternatif.** Yerel öncelikli, web'e dağıtılabilir, her katmanda BYOK; `PATH` üzerinde otomatik algılanan **16 coding-agent CLI** (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) tasarım motoruna dönüşür. Hepsi **31 birleştirilebilir Skill** ve **72 marka kalitesinde Design System** tarafından yönlendirilir. CLI yok mu? OpenAI uyumlu BYOK proxy aynı döngünün agent spawn olmadan çalışan halidir.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — dizüstü bilgisayarındaki agent ile tasarım yapma editoryal kapağı" width="100%" />
 </p>
@@ -887,7 +887,7 @@ Tam walkthrough, merge çıtası, code style ve kabul etmediklerimiz → [`CONTR
 Open Design'ı kod, doküman, feedback, yeni skill, yeni design system veya keskin bir issue ile ileri taşıyan herkese teşekkürler. Her gerçek katkı önemlidir; aşağıdaki wall bunu yüksek sesle söylemenin en kolay yolu.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design contributors" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design contributors" />
 </a>
 
 İlk PR'ını gönderdiysen hoş geldin. [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) label'ı giriş noktasıdır.
@@ -904,9 +904,9 @@ Yukarıdaki SVG [`.github/workflows/metrics.yml`](.github/workflows/metrics.yml)
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.uk.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design — офіційна open-source альтернатива [Claude Design][cd]
+
+> **Open Design — це альтернатива з відкритим кодом і локально-перший варіант [Claude Design][cd].** Розгортується в web, BYOK на кожному рівні — **16 CLI агентів для кодування** автоматично виявляються у вашому `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) стають механізмом дизайну, керуються **31 компонуваною навичкою** та **72 системами дизайну комерційного класу**. Немає CLI? OpenAI-сумісний BYOK проксі — це той же цикл без spawn.
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` уже тут. Старий світ дизайну закінчується тут.
 >
-> Open-source, agent-native альтернатива Claude Design / Figma — 40k зірок за два тижні привели нас сюди. **Далі — тільки з тобою.**
+> Open-source альтернатива Claude Design / Figma — 40k зірок за два тижні привели нас сюди. **Далі — тільки з тобою.**
 >
 > **Швидка ітерація на `main`** — 0.8.0 — наступна фаза Open Design. Кидай PR, кидай шалену ідею, заводь баг — те, що приносиш ти, тим стає цей рух.
 >
 > → [**Прочитати анонс · завантажити інсталятор · приєднатися до руху**](https://github.com/nexu-io/open-design/discussions/1727) · встановлюється паралельно з твоєю поточною 0.7.
 
-> **Альтернатива з відкритим кодом до [Claude Design][cd].** Локально-перший, розгортується в web, BYOK на кожному рівні — **16 CLI агентів для кодування** автоматично виявляються у вашому `PATH` (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI) стають механізмом дизайну, керуються **31 компонуваною навичкою** та **72 системами дизайну комерційного класу**. Немає CLI? OpenAI-сумісний BYOK проксі — це той же цикл без spawn.
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design — editorial cover: design with the agent on your laptop" width="100%" />
 </p>
@@ -729,7 +729,7 @@ OD не зупиняється на коді. Та сама поверхня ч
 Дякуємо всім, хто допоміг просувати Open Design — через код, документацію, зворотний зв'язок, нові навички, нові системи дизайну або навіть гостре питання. Кожен реальний внесок рахується, а стіна нижче — найпростіший спосіб сказати це вголос.
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Контриб'ютори Open Design" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Контриб'ютори Open Design" />
 </a>
 
 Якщо ви злили свій перший PR — ласкаво просимо. Мітка [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) — це точка входу.
@@ -746,9 +746,9 @@ SVG вище перегенерується щодня [`.github/workflows/metri
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Історія зірок Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Історія зірок Open Design" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.zh-CN.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design —— [Claude Design][cd] 的官方开源替代品
+
+> **Open Design 是 [Claude Design][cd] 的开源、本地优先替代品。** 可部署到 Vercel、每一层都 BYOK —— **16 套 coding-agent CLI** 在 `PATH` 上自动检测（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）就是设计引擎，由 **31 个可组合 Skills** 和 **72 套品牌级 Design System** 驱动。
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` 已发布。设计的旧世界，到此为止。
 >
-> 开源、agent-native 的 Claude Design / Figma 替代品 —— 上线两周，40k stars 在身，且仍在加速。**剩下的路，需要你和我们一起推完。**
+> Claude Design / Figma 的开源替代品 —— 上线两周，40k stars 在身，且仍在加速。**剩下的路，需要你和我们一起推完。**
 >
 > **正在 `main` 分支飞速迭代中** —— 0.8.0 是 Open Design 的下一阶段。提一个 PR、扔一个想法、报一个 bug —— 你带来的，就是这场运动接下来的样子。
 >
 > → [**读公告 · 下载安装包 · 加入这场运动**](https://github.com/nexu-io/open-design/discussions/1727) · 可与你现有的 0.7 并行安装。
 
-> **[Claude Design][cd] 的开源替代品。** 本地优先、可部署到 Vercel、每一层都 BYOK —— **16 套 coding-agent CLI** 在 `PATH` 上自动检测（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）就是设计引擎，由 **31 个可组合 Skills** 和 **72 套品牌级 Design System** 驱动。
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design 封面：与本地 AI 智能体共同设计" width="100%" />
 </p>
@@ -722,7 +722,7 @@ Daemon 启动时从 `PATH` 自动检测，无需配置。流式分发逻辑在 [
 感谢每一位让 Open Design 变得更好的朋友 —— 无论是写代码、修文档、提 issue、加 skill 还是加 design system，每一次真实贡献都会被记住。下面这面墙是最直观的「Thank you」。
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design 贡献者" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design 贡献者" />
 </a>
 
 第一次提 PR？欢迎从 [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) 标签起步。
@@ -739,9 +739,9 @@ Daemon 启动时从 `PATH` 自动检测，无需配置。流式分发逻辑在 [
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

README.zh-TW.md

@@ -1,16 +1,16 @@
-# Open Design
+# Open Design —— [Claude Design][cd] 的官方開源替代品
+
+> **Open Design 是 [Claude Design][cd] 的開源、本地優先替代品。** 可部署到 Vercel、每一層都 BYOK —— **16 套 coding-agent CLI** 在 `PATH` 上自動檢測（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）就是設計引擎，由 **31 個可組合 Skills** 和 **72 套品牌級 Design System** 驅動。一個都沒裝？還有 OpenAI 相容的 BYOK 代理 `/api/proxy/stream` 備援，同一條 loop，少一次 spawn 而已。
 
 > [!IMPORTANT]
 > ### 🔥 `0.8.0-preview` 已發佈。設計的舊世界，到此為止。
 >
-> 開源、agent-native 的 Claude Design / Figma 替代品 —— 上線兩週，40k stars 在身，且仍在加速。**剩下的路，需要你和我們一起推完。**
+> Claude Design / Figma 的開源替代品 —— 上線兩週，40k stars 在身，且仍在加速。**剩下的路，需要你和我們一起推完。**
 >
 > **正在 `main` 分支飛速迭代中** —— 0.8.0 是 Open Design 的下一階段。提一個 PR、扔一個想法、報一個 bug —— 你帶來的，就是這場運動接下來的樣子。
 >
 > → [**讀公告 · 下載安裝包 · 加入這場運動**](https://github.com/nexu-io/open-design/discussions/1727) · 可與你現有的 0.7 並行安裝。
 
-> **[Claude Design][cd] 的開源替代品。** 本地優先、可部署到 Vercel、每一層都 BYOK —— **16 套 coding-agent CLI** 在 `PATH` 上自動檢測（Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, Qoder CLI, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro, Kilo, Mistral Vibe, DeepSeek TUI）就是設計引擎，由 **31 個可組合 Skills** 和 **72 套品牌級 Design System** 驅動。一個都沒裝？還有 OpenAI 相容的 BYOK 代理 `/api/proxy/stream` 備援，同一條 loop，少一次 spawn 而已。
-
 <p align="center">
   <img src="docs/assets/banner.png" alt="Open Design 封面：與本地 AI 智慧體共同設計" width="100%" />
 </p>
@@ -713,7 +713,8 @@ open-design/
 │       └── browser-chrome.html
 │
 ├── templates/
-│   └── deck-framework.html        ← deck 基線（nav / counter / print）
+│   ├── deck-framework.html        ← deck 基線（nav / counter / print）
+│   └── kami-deck.html             ← kami 風格 deck 起手（羊皮紙 / 墨藍襯線）
 │
 ├── scripts/
 │   └── sync-design-systems.ts     ← 從上游 awesome-design-md tarball 重新匯入
@@ -888,7 +889,7 @@ Chat / artifact 迴圈最顯眼，但這套倉庫裡還有幾個能力被埋得
 | 可部署 Vercel | ❌ | ❌ | **✅** |
 | Agent 執行時 | 內建 (Opus 4.7) | 內建 ([`pi-ai`][piai]) | **委託給使用者已裝好的 CLI** |
 | Skill | 私有 | 12 套自定義 TS 模組 + `SKILL.md` | **31 套基於檔案的 [`SKILL.md`][skill]，可丟入** |
-| Design system | 私有 | `DESIGN.md`（v0.2 路線圖） | **`DESIGN.md` × 72 套，開箱即有** |
+| Design system | 私有 | `DESIGN.md`（v0.2 路線圖） | **`DESIGN.md` × 129 套，開箱即有** |
 | Provider 靈活度 | 僅 Anthropic | 7+（[`pi-ai`][piai]） | **16 套 CLI adapter + OpenAI 相容 BYOK 代理** |
 | 初始化問題表單 | ❌ | ❌ | **✅ 硬規則 turn 1** |
 | 方向選擇器 | ❌ | ❌ | **✅ 5 套確定性方向** |
@@ -1005,7 +1006,7 @@ Daemon 啟動時從 `PATH` 自動檢測，無需配置。流式分發邏輯在 [
 感謝每一位讓 Open Design 變得更好的朋友 —— 無論是寫程式碼、修文檔、提 issue、加 skill 還是加 design system，每一次真實貢獻都會被記住。下面這面牆是最直觀的「Thank you」。
 
 <a href="https://github.com/nexu-io/open-design/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-18" alt="Open Design 貢獻者" />
+  <img src="https://contrib.rocks/image?repo=nexu-io/open-design&cache_bust=2026-05-31" alt="Open Design 貢獻者" />
 </a>
 
 第一次提 PR？歡迎從 [`good-first-issue`/`help-wanted`](https://github.com/nexu-io/open-design/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22%2C%22help+wanted%22) 標籤起步。
@@ -1022,9 +1023,9 @@ Daemon 啟動時從 `PATH` 自動檢測，無需配置。流式分發邏輯在 [
 
 <a href="https://star-history.com/#nexu-io/open-design&Date">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-18" />
-    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
-    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-18" />
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&theme=dark&cache_bust=2026-05-31" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
+    <img alt="Open Design star history" src="https://api.star-history.com/svg?repos=nexu-io/open-design&type=Date&cache_bust=2026-05-31" />
   </picture>
 </a>
 

TRANSLATIONS.md

@@ -104,7 +104,7 @@ pnpm i18n:check
 
 ## 📋 Supported Languages
 
-Open Design currently supports **18 languages** across different surfaces:
+Open Design currently supports **19 languages** across different surfaces:
 
 | Language             | Code    | README | UI Dict | Core Docs | Status |
 | -------------------- | ------- | ------ | ------- | --------- | ------ |
@@ -116,6 +116,7 @@ Open Design currently supports **18 languages** across different surfaces:
 | Français             | `fr`    | ✅     | ✅      | ✅        | active |
 | Magyar (Hungarian)   | `hu`    | —      | ✅      | —         | active |
 | Bahasa Indonesia     | `id`    | —      | ✅      | —         | active |
+| Italiano             | `it`    | —      | ✅      | —         | active |
 | 日本語 (Japanese)    | `ja`    | ✅     | ✅      | ✅        | active |
 | 한국어 (Korean)      | `ko`    | ✅     | ✅      | —         | active |
 | Polski (Polish)      | `pl`    | —      | ✅      | —         | active |
@@ -331,6 +332,88 @@ Translations follow the conventions of the target region's tech writing communit
 - "quickstart" → your language's equivalent
 - "settings" → your language's equivalent
 
+### French (`fr`) Glossary
+
+French UI copy should read naturally for a technical product audience without
+turning product/runtime terms into vague French approximations. Keep these
+rules stable across `apps/web/src/i18n/locales/fr.ts`, French core docs, and
+French display metadata.
+
+#### Keep in English
+
+Keep the exact English/token form for names, protocols, commands, environment
+variables, code identifiers, package names, file extensions, and technical
+runtime nouns that are clearer in English:
+
+| English source | French usage |
+| -------------- | ------------ |
+| Open Design | Open Design |
+| Claude Code, Codex, Cursor, Gemini, OpenCode | Claude Code, Codex, Cursor, Gemini, OpenCode |
+| CLI, API, SDK, MCP, HTTP, REST, SSE, JSONL | CLI, API, SDK, MCP, HTTP, REST, SSE, JSONL |
+| BYOK | BYOK |
+| runtime | runtime |
+| daemon | daemon |
+| sidecar | sidecar |
+| headless | headless |
+| plugin | plugin |
+| prompt | prompt |
+| token | token |
+| iframe | iframe |
+| monorepo, workspace | monorepo, workspace |
+| `od`, `pnpm`, `pnpm tools-dev` | `od`, `pnpm`, `pnpm tools-dev` |
+| `OD_DATA_DIR`, `OD_WEB_PORT`, `{provider}` | `OD_DATA_DIR`, `OD_WEB_PORT`, `{provider}` |
+| `.zip`, `.html`, `.md`, `.json` | `.zip`, `.html`, `.md`, `.json` |
+
+Use French grammar around preserved terms:
+
+- `le daemon local`, `un runtime`, `des plugins`, `les prompts`
+- `l’API`, `un endpoint REST`, `un flux SSE`
+- `la CLI locale`, `un serveur MCP`
+
+#### Translate When Standard
+
+Translate ordinary UI terms, workflow labels, and non-identifier product copy
+when a natural French equivalent exists:
+
+| English source | French |
+| -------------- | ------ |
+| Settings | Paramètres |
+| Save | Enregistrer |
+| Cancel | Annuler |
+| Delete | Supprimer |
+| Folder | Dossier |
+| File | Fichier |
+| Download | Télécharger |
+| Upload | Téléverser |
+| Search | Rechercher |
+| Preview | Aperçu |
+| Project | Projet |
+| Conversation | Conversation |
+| Dashboard | Tableau de bord |
+| Schedule | Planification |
+| Automation | Automatisation |
+| Artifact | Artefact |
+| Live artifact | Artefact dynamique |
+| Design files | Fichiers de design |
+| Slide deck | Présentation |
+| Engineering handoff | Transmission aux ingénieurs |
+| Shipped (product/software status) | Livré |
+
+#### Context-Sensitive Choices
+
+- `Skill` stays `Skill` when it names the Open Design/Claude skill format.
+  Translate only generic prose such as "ability" or "capability" as
+  `capacité`.
+- `Design System` may stay `Design System` when referring to the product
+  registry/object name. In explanatory prose, `système de design` is also
+  acceptable when it improves readability.
+- `runtime` stays `runtime` as a noun. Labels like "execution mode" can still
+  use `mode d’exécution`.
+- `source` can stay `source` for provenance labels, but translate ordinary
+  "data source" as `source de données`.
+- Do not translate command output or examples that users should see exactly in
+  their terminal.
+
 ### zh-CN ↔ zh-TW Glossary
 
 When converting between Simplified and Traditional Chinese, prefer Taiwan-specific phrasing in zh-TW rather than character-only conversion. This list grew out of [PR #194](https://github.com/nexu-io/open-design/pull/194) and is meant as a starting point, not a rulebook.

apps/daemon/bin/od.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const entryDir = dirname(fileURLToPath(import.meta.url));
+const distEntry = resolve(entryDir, "../dist/cli.js");
+
+if (!existsSync(distEntry)) {
+  throw new Error(
+    `Open Design daemon dist entry not found at ${distEntry}. Run "pnpm --filter @open-design/daemon build" first.`,
+  );
+}
+
+await import(pathToFileURL(distEntry).href);

apps/daemon/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@open-design/daemon",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "private": true,
   "type": "module",
   "main": "./dist/cli.js",
   "types": "./dist/cli.d.ts",
   "bin": {
-    "od": "./dist/cli.js"
+    "od": "./bin/od.mjs"
   },
   "exports": {
     ".": {
@@ -20,6 +20,7 @@
     }
   },
   "files": [
+    "bin",
     "dist",
     "package.json"
   ],
@@ -44,8 +45,9 @@
     "@opentelemetry/api": "1.9.1",
     "better-sqlite3": "12.10.0",
     "blake3-wasm": "2.1.5",
+    "cheerio": "1.2.0",
     "chokidar": "5.0.0",
-    "express": "4.22.1",
+    "express": "5.2.1",
     "jszip": "3.10.1",
     "multer": "2.1.1",
     "posthog-node": "5.34.6",
@@ -55,7 +57,7 @@
   },
   "devDependencies": {
     "@types/better-sqlite3": "7.6.13",
-    "@types/express": "4.17.25",
+    "@types/express": "5.0.6",
     "@types/multer": "2.1.0",
     "@types/node": "20.19.39",
     "typescript": "5.9.3",

apps/daemon/scripts/verify-amr-real-vela.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Ad-hoc end-to-end verifier: drives the real `vela` binary through Open
+ * Design's `attachAcpSession`. Not part of the test suite — it makes a real
+ * OpenRouter request when VELA_RUNTIME_KEY is a live key.
+ *
+ * Usage:
+ *   VELA_BIN=/path/to/vela \
+ *   VELA_RUNTIME_KEY=<openrouter-key> \
+ *   VELA_LINK_URL=https://openrouter.ai/api/v1 \
+ *   PATH=<dir-with-opencode>:$PATH \
+ *   node apps/daemon/scripts/verify-amr-real-vela.mjs
+ *
+ * Behaviour:
+ *   - Runs initialize → session/new → session/set_model (if --model given) →
+ *     session/prompt with the prompt from VELA_VERIFY_PROMPT (defaults to a
+ *     short hello).
+ *   - Logs every Open Design `send(event, payload)` to stdout so you can see
+ *     the same text_delta / usage events the chat UI would receive.
+ *   - Exits 0 on completedSuccessfully, 1 otherwise.
+ */
+
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const { attachAcpSession } = await import(
+  path.join(HERE, '..', 'dist', 'acp.js')
+);
+
+const velaBin = process.env.VELA_BIN || 'vela';
+const prompt = process.env.VELA_VERIFY_PROMPT || 'Reply with the exact text: AMR-E2E-OK.';
+const model = process.env.VELA_VERIFY_MODEL || null;
+
+if (
+  (!process.env.VELA_RUNTIME_KEY || !process.env.VELA_LINK_URL) &&
+  !process.env.VELA_PROFILE
+) {
+  console.error(
+    'Provide credentials via either:\n' +
+      '  - VELA_RUNTIME_KEY + VELA_LINK_URL env vars, or\n' +
+      '  - VELA_PROFILE (e.g. "local") with a logged-in ~/.amr/config.json.',
+  );
+  process.exit(2);
+}
+
+const child = spawn(velaBin, ['agent', 'run', '--runtime', 'opencode'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  env: process.env,
+});
+
+child.stderr.on('data', (chunk) => {
+  process.stderr.write(`[vela.stderr] ${chunk}`);
+});
+child.on('error', (err) => {
+  console.error('[child.error]', err.message);
+});
+child.on('exit', (code, signal) => {
+  console.error(`[child.exit] code=${code} signal=${signal}`);
+});
+child.on('close', (code, signal) => {
+  console.error(`[child.close] code=${code} signal=${signal}`);
+});
+
+const overallTimeoutMs = Number(process.env.VELA_VERIFY_TIMEOUT_MS) || 120_000;
+const overallTimer = setTimeout(() => {
+  console.error(`[verify-amr] overall timeout after ${overallTimeoutMs}ms; SIGTERM child`);
+  if (!child.killed) child.kill('SIGTERM');
+}, overallTimeoutMs);
+overallTimer.unref?.();
+
+const session = attachAcpSession({
+  child,
+  prompt,
+  cwd: process.cwd(),
+  model,
+  mcpServers: [],
+  send: (event, payload) => {
+    const stamp = new Date().toISOString();
+    if (event === 'agent' && payload?.type === 'text_delta') {
+      process.stdout.write(payload.delta);
+      return;
+    }
+    console.log(`\n[${stamp}] ${event} ${JSON.stringify(payload)}`);
+  },
+});
+
+await new Promise((resolve) => child.on('close', resolve));
+process.stdout.write('\n');
+
+if (session.hasFatalError()) {
+  console.error('Session reported fatal error.');
+  process.exit(1);
+}
+if (!session.completedSuccessfully()) {
+  console.error('Session did not complete successfully.');
+  process.exit(1);
+}
+console.log('verify-amr-real-vela: OK');

apps/daemon/src/acp.ts

@@ -65,11 +65,13 @@ interface AttachAcpSessionOptions {
   prompt: string;
   cwd?: string;
   model?: string | null;
+  imagePaths?: string[];
   mcpServers?: AcpMcpServerInput[];
   send: (event: string, payload: unknown) => void;
   clientName?: string;
   clientVersion?: string;
   stageTimeoutMs?: number;
+  modelUnavailableErrorCode?: 'AMR_MODEL_UNAVAILABLE';
 }
 
 function errorMessage(err: unknown): string {
@@ -115,6 +117,15 @@ function sendRpcResult(writable: RpcWritable, id: JsonRpcId, result: unknown): v
   writable.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);
 }
 
+function buildPromptBlocks(prompt: string, imagePaths: string[]): Array<Record<string, string>> {
+  const blocks: Array<Record<string, string>> = [{ type: 'text', text: prompt }];
+  for (const imagePath of imagePaths) {
+    if (typeof imagePath !== 'string' || imagePath.trim().length === 0) continue;
+    blocks.push({ type: 'resource_link', uri: imagePath });
+  }
+  return blocks;
+}
+
 function isJsonRpcId(value: unknown): value is JsonRpcId {
   return typeof value === 'number' || typeof value === 'string';
 }
@@ -277,34 +288,269 @@ function currentModelFromSessionResult(result: JsonObject): string | null {
 
 export function createJsonLineStream(onMessage: (message: unknown, rawLine: string) => void) {
   let buffer = '';
+  let pendingJson = '';
+  let pendingJsonLineCount = 0;
+
+  const emit = (candidate: string): boolean => {
+    try {
+      onMessage(JSON.parse(candidate), candidate);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const startPendingJson = (line: string) => {
+    pendingJson = line;
+    pendingJsonLineCount = 1;
+  };
+
+  const resetPendingJson = () => {
+    pendingJson = '';
+    pendingJsonLineCount = 0;
+  };
+
+  const handleLine = (line: string) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    if (pendingJson) {
+      const nextCandidate = `${pendingJson}\n${trimmed}`;
+      if (emit(nextCandidate)) {
+        resetPendingJson();
+        return;
+      }
+      pendingJsonLineCount += 1;
+      const state = classifyJsonCandidate(nextCandidate);
+      if (
+        state === 'incomplete' &&
+        nextCandidate.length <= 128_000 &&
+        pendingJsonLineCount <= 256
+      ) {
+        pendingJson = nextCandidate;
+        return;
+      }
+      resetPendingJson();
+      handleLine(trimmed);
+      return;
+    }
+    if (emit(trimmed)) return;
+    // ACP is line-delimited JSON-RPC, but a few bridges have emitted
+    // pretty-printed JSON during startup. Keep a bounded aggregate so an
+    // otherwise valid multiline initialize response does not get discarded
+    // line-by-line and leave the session stuck in spawn pending.
+    if (
+      (trimmed.startsWith('{') || trimmed.startsWith('[')) &&
+      classifyJsonCandidate(trimmed) === 'incomplete'
+    ) {
+      startPendingJson(trimmed);
+    }
+  };
+
   return {
     feed(chunk: string) {
       buffer += chunk;
       const lines = buffer.split('\n');
       buffer = lines.pop() || '';
       for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed) continue;
-        try {
-          onMessage(JSON.parse(trimmed), trimmed);
-        } catch {
-          // Ignore non-JSON log lines on stdout.
-        }
+        handleLine(line);
       }
     },
     flush() {
       const trimmed = buffer.trim();
       buffer = '';
-      if (!trimmed) return;
-      try {
-        onMessage(JSON.parse(trimmed), trimmed);
-      } catch {
-        // Ignore trailing non-JSON log lines on stdout.
+      if (trimmed) {
+        handleLine(trimmed);
       }
+      if (pendingJson && emit(pendingJson)) {
+        pendingJson = '';
+      }
+      // Ignore trailing non-JSON log lines on stdout.
     },
   };
 }
 
+function classifyJsonCandidate(value: string): 'complete' | 'incomplete' | 'invalid' {
+  type Frame =
+    | { kind: 'object'; expect: 'keyOrEnd' | 'colon' | 'value' | 'commaOrEnd' }
+    | { kind: 'array'; expect: 'valueOrEnd' | 'commaOrEnd' };
+  const stack: Frame[] = [];
+  let rootComplete = false;
+
+  const afterValue = () => {
+    const parent = stack.at(-1);
+    if (!parent) {
+      rootComplete = true;
+      return;
+    }
+    parent.expect = 'commaOrEnd';
+  };
+
+  const closeFrame = (kind: 'object' | 'array'): boolean => {
+    const current = stack.pop();
+    if (!current || current.kind !== kind) return false;
+    afterValue();
+    return true;
+  };
+
+  const parseString = (start: number): number | null => {
+    for (let index = start + 1; index < value.length; index += 1) {
+      const char = value[index];
+      if (char === '\\') {
+        index += 1;
+        continue;
+      }
+      if (char === '"') return index;
+    }
+    return null;
+  };
+
+  const parseLiteral = (start: number, literal: string): number | null | false => {
+    for (let offset = 0; offset < literal.length; offset += 1) {
+      const char = value[start + offset];
+      if (char === undefined) return null;
+      if (char !== literal[offset]) return false;
+    }
+    return start + literal.length - 1;
+  };
+
+  const parseNumber = (start: number): number | false => {
+    let index = start;
+    if (value[index] === '-') index += 1;
+    if (value[index] === '0') {
+      index += 1;
+    } else if (/[1-9]/.test(value[index] ?? '')) {
+      while (/[0-9]/.test(value[index] ?? '')) index += 1;
+    } else {
+      return false;
+    }
+    if (value[index] === '.') {
+      index += 1;
+      if (!/[0-9]/.test(value[index] ?? '')) return false;
+      while (/[0-9]/.test(value[index] ?? '')) index += 1;
+    }
+    if (value[index] === 'e' || value[index] === 'E') {
+      index += 1;
+      if (value[index] === '+' || value[index] === '-') index += 1;
+      if (!/[0-9]/.test(value[index] ?? '')) return false;
+      while (/[0-9]/.test(value[index] ?? '')) index += 1;
+    }
+    return index - 1;
+  };
+
+  const parseValue = (index: number): number | null | false => {
+    const char = value[index];
+    if (char === '"') {
+      const end = parseString(index);
+      if (end === null) return null;
+      afterValue();
+      return end;
+    }
+    if (char === '{') {
+      stack.push({ kind: 'object', expect: 'keyOrEnd' });
+      return index;
+    }
+    if (char === '[') {
+      stack.push({ kind: 'array', expect: 'valueOrEnd' });
+      return index;
+    }
+    if (char === 't') {
+      const end = parseLiteral(index, 'true');
+      if (end === false || end === null) return end;
+      afterValue();
+      return end;
+    }
+    if (char === 'f') {
+      const end = parseLiteral(index, 'false');
+      if (end === false || end === null) return end;
+      afterValue();
+      return end;
+    }
+    if (char === 'n') {
+      const end = parseLiteral(index, 'null');
+      if (end === false || end === null) return end;
+      afterValue();
+      return end;
+    }
+    if (char === '-' || /[0-9]/.test(char ?? '')) {
+      const end = parseNumber(index);
+      if (end === false) return false;
+      afterValue();
+      return end;
+    }
+    return false;
+  };
+
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === undefined) break;
+    if (/\s/.test(char)) continue;
+
+    const current = stack.at(-1);
+    if (!current) {
+      if (rootComplete) return 'invalid';
+      const end = parseValue(index);
+      if (end === false) return 'invalid';
+      if (end === null) return 'incomplete';
+      index = end;
+      continue;
+    }
+
+    if (current.kind === 'object') {
+      if (current.expect === 'keyOrEnd') {
+        if (char === '}') {
+          if (!closeFrame('object')) return 'invalid';
+          continue;
+        }
+        if (char !== '"') return 'invalid';
+        const end = parseString(index);
+        if (end === null) return 'incomplete';
+        current.expect = 'colon';
+        index = end;
+        continue;
+      }
+      if (current.expect === 'colon') {
+        if (char !== ':') return 'invalid';
+        current.expect = 'value';
+        continue;
+      }
+      if (current.expect === 'value') {
+        const end = parseValue(index);
+        if (end === false) return 'invalid';
+        if (end === null) return 'incomplete';
+        index = end;
+        continue;
+      }
+      if (char === '}') {
+        if (!closeFrame('object')) return 'invalid';
+        continue;
+      }
+      if (char !== ',') return 'invalid';
+      current.expect = 'keyOrEnd';
+      continue;
+    }
+
+    if (current.expect === 'valueOrEnd') {
+      if (char === ']') {
+        if (!closeFrame('array')) return 'invalid';
+        continue;
+      }
+      const end = parseValue(index);
+      if (end === false) return 'invalid';
+      if (end === null) return 'incomplete';
+      index = end;
+      continue;
+    }
+    if (char === ']') {
+      if (!closeFrame('array')) return 'invalid';
+      continue;
+    }
+    if (char !== ',') return 'invalid';
+    current.expect = 'valueOrEnd';
+  }
+
+  return rootComplete && stack.length === 0 ? 'complete' : 'incomplete';
+}
+
 export async function detectAcpModels({
   bin,
   args,
@@ -421,11 +667,13 @@ export function attachAcpSession({
   prompt,
   cwd,
   model,
+  imagePaths = [],
   mcpServers,
   send,
   clientName = 'open-design',
   clientVersion = 'runtime-adapter',
   stageTimeoutMs = DEFAULT_STAGE_TIMEOUT_MS,
+  modelUnavailableErrorCode,
 }: AttachAcpSessionOptions) {
   const runStartedAt = Date.now();
   const effectiveCwd = path.resolve(cwd || process.cwd());
@@ -443,6 +691,8 @@ export function attachAcpSession({
   let modelConfigId: string | null = null;
   let emittedThinkingStart = false;
   let emittedFirstTokenStatus = false;
+  let emittedTextChunk = false;
+  let emittedTextBuffer = '';
   let finished = false;
   let fatal = false;
   let aborted = false;
@@ -467,12 +717,41 @@ export function attachAcpSession({
     stageTimer = null;
   };
 
-  const fail = (message: string) => {
+  const amrModelUnavailablePayload = (message: string) => ({
+    message,
+    error: {
+      code: 'AMR_MODEL_UNAVAILABLE',
+      message,
+      retryable: false,
+      details: { kind: 'amr_model', action: 'choose_model' },
+    },
+  });
+
+  const isModelUnavailableError = (message: string) => {
+    const value = message.toLowerCase();
+    return (
+      value.includes('model not found') ||
+      value.includes('providermodelnotfounderror') ||
+      value.includes('unknown model') ||
+      value.includes('invalid model')
+    );
+  };
+
+  const fail = (
+    message: string,
+    options: { forceModelUnavailable?: boolean } = {},
+  ) => {
     if (finished) return;
     finished = true;
     fatal = true;
     clearStageTimer();
-    send('error', { message });
+    const useModelUnavailable =
+      modelUnavailableErrorCode &&
+      (options.forceModelUnavailable || isModelUnavailableError(message));
+    send(
+      'error',
+      useModelUnavailable ? amrModelUnavailablePayload(message) : { message },
+    );
     if (!child.killed) child.kill('SIGTERM');
   };
 
@@ -493,7 +772,7 @@ export function attachAcpSession({
       'session/prompt',
       {
         sessionId,
-        prompt: [{ type: 'text', text: prompt }],
+        prompt: buildPromptBlocks(prompt, imagePaths),
       },
       'session/prompt',
     );
@@ -575,15 +854,22 @@ export function attachAcpSession({
       if (update.sessionUpdate === 'agent_message_chunk') {
         const text = asObject(update.content)?.text;
         if (typeof text === 'string' && text.length > 0) {
-          if (!emittedFirstTokenStatus) {
-            emittedFirstTokenStatus = true;
-            send('agent', {
-              type: 'status',
-              label: 'streaming',
-              ttftMs: Date.now() - runStartedAt,
-            });
+          const delta = text.startsWith(emittedTextBuffer)
+            ? text.slice(emittedTextBuffer.length)
+            : text;
+          if (delta.length > 0) {
+            emittedTextChunk = true;
+            emittedTextBuffer += delta;
+            if (!emittedFirstTokenStatus) {
+              emittedFirstTokenStatus = true;
+              send('agent', {
+                type: 'status',
+                label: 'streaming',
+                ttftMs: Date.now() - runStartedAt,
+              });
+            }
+            send('agent', { type: 'text_delta', delta });
           }
-          send('agent', { type: 'text_delta', delta: text });
         }
         return;
       }
@@ -638,6 +924,13 @@ export function attachAcpSession({
       return;
     }
     if (promptRequestId !== null && obj.id === promptRequestId) {
+      if (!emittedTextChunk && modelUnavailableErrorCode) {
+        fail(
+          'ACP session completed without producing any assistant text. Refresh the AMR model list, choose a supported model, and retry this run.',
+          { forceModelUnavailable: true },
+        );
+        return;
+      }
       const usage = formatUsage(result.usage);
       if (usage) {
         send('agent', {
@@ -672,9 +965,12 @@ export function attachAcpSession({
   });
 
   stdout.on('data', (chunk: string) => parser.feed(chunk));
-  child.on('close', () => {
+  child.on('close', (code, signal) => {
     clearStageTimer();
     parser.flush();
+    if (!finished && !aborted && !fatal) {
+      fail(`ACP session exited before completion (code=${code ?? 'null'}, signal=${signal ?? 'none'})`);
+    }
   });
   child.on('error', (err: Error) => fail(err.message));
   stdin.on('error', (err: Error) => fail(`stdin error: ${err.message}`));
@@ -701,12 +997,27 @@ export function attachAcpSession({
       aborted = true;
       finished = true;
       clearStageTimer();
-      if (!sessionId || !child.stdin || child.stdin.destroyed || child.stdin.writableEnded) return;
+      if (!child.stdin || child.stdin.destroyed || child.stdin.writableEnded)
+        return;
+      // Only cancel an established session; before session/new resolves there
+      // is no sessionId to cancel, but we must still close stdin below.
+      if (sessionId) {
+        try {
+          sendRpc(child.stdin, nextId, 'session/cancel', { sessionId });
+          nextId += 1;
+        } catch {
+          // The caller owns process-signal fallback if the ACP transport is gone.
+        }
+      }
+      // Always close stdin so the agent receives EOF and shuts down its own
+      // runtime — the vela ACP bridge tears down its private OpenCode server on
+      // EOF — instead of lingering (and leaking that server) until the caller's
+      // SIGTERM fallback fires. This also covers aborts during ACP startup,
+      // before session/new returns. Mirrors the clean-completion path above.
       try {
-        sendRpc(child.stdin, nextId, 'session/cancel', { sessionId });
-        nextId += 1;
+        child.stdin.end();
       } catch {
-        // The caller owns process-signal fallback if the ACP transport is gone.
+        // Best effort; the caller still owns the SIGTERM/SIGKILL fallback.
       }
     },
   };

apps/daemon/src/active-context-routes.ts

@@ -1,71 +1,128 @@
 import type { Express } from 'express';
+import { createApiError } from '@open-design/contracts';
 import { ACTIVE_CONTEXT_TTL_MS } from './constants.js';
 import type { RouteDeps } from './server-context.js';
+import { defineJsonRoute, err, mountJsonRoute, ok, type Result } from './http/index.js';
 
 export interface RegisterActiveContextRoutesDeps extends RouteDeps<'db' | 'http' | 'projectStore'> {}
 
-export function registerActiveContextRoutes(app: Express, ctx: RegisterActiveContextRoutesDeps) {
-  const { db } = ctx;
-  const { sendApiError, isLocalSameOrigin, resolvedPortRef } = ctx.http;
-  const { getProject } = ctx.projectStore;
-  const getResolvedPort = () => resolvedPortRef.current;
+// Soft "what is the user looking at right now in Open Design?" channel. The
+// web UI POSTs the current project + file on every route change; the MCP
+// surface reads it so a coding agent in another repo can resolve "the design
+// I have open" without the user typing the project id. In-memory only —
+// daemon restart clears it.
+interface ActiveContext {
+  projectId: string;
+  fileName: string | null;
+  ts: number;
+}
 
-  // Soft "what is the user looking at right now in Open Design?" channel. The
-  // web UI POSTs the current project + file on every route change; the MCP
-  // surface reads it so a coding agent in another repo can resolve "the design
-  // I have open" without the user typing the project id. In-memory only -
-  // daemon restart clears it.
-  let activeContext: { projectId: string; fileName: string | null; ts: number } | null = null;
+interface ActiveContextStore {
+  current: ActiveContext | null;
+}
 
-  // Active context is private to the local machine. The daemon may bind beyond
-  // loopback, so without an origin check a peer on the LAN could read what the
-  // user is currently looking at (GET) or spoof it to redirect MCP fallbacks
-  // (POST). The web proxies same-origin and MCP runs in-process via 127.0.0.1,
-  // so both legitimate callers pass the check.
-  app.post('/api/active', (req, res) => {
-    if (!isLocalSameOrigin(req, getResolvedPort())) {
-      return res.status(403).json({ error: 'cross-origin request rejected' });
-    }
-    try {
-      const body = req.body || {};
-      if (body.active === false) {
-        activeContext = null;
-        res.json({ active: false });
-        return;
-      }
-      const projectId = typeof body.projectId === 'string' ? body.projectId : '';
-      if (!projectId) {
-        sendApiError(res, 400, 'BAD_REQUEST', 'projectId is required');
-        return;
-      }
-      const fileName =
-        typeof body.fileName === 'string' && body.fileName.length > 0
-          ? body.fileName
-          : null;
-      activeContext = { projectId, fileName, ts: Date.now() };
-      res.json({ active: true, ...activeContext });
-    } catch (err) {
-      sendApiError(res, 400, 'BAD_REQUEST', String(err));
-    }
-  });
+type PostActiveInput =
+  | { kind: 'clear' }
+  | { kind: 'set'; projectId: string; fileName: string | null };
 
-  app.get('/api/active', (req, res) => {
-    if (!isLocalSameOrigin(req, getResolvedPort())) {
-      return res.status(403).json({ error: 'cross-origin request rejected' });
-    }
-    if (!activeContext || Date.now() - activeContext.ts > ACTIVE_CONTEXT_TTL_MS) {
-      activeContext = null;
-      res.json({ active: false });
-      return;
-    }
-    const project = getProject(db, activeContext.projectId);
-    res.json({
-      active: true,
-      projectId: activeContext.projectId,
-      projectName: project?.name ?? null,
-      fileName: activeContext.fileName,
-      ts: activeContext.ts,
-      ageMs: Date.now() - activeContext.ts,
-    });
+type PostActiveOutput =
+  | { active: false }
+  | { active: true; projectId: string; fileName: string | null; ts: number };
+
+type GetActiveOutput =
+  | { active: false }
+  | {
+      active: true;
+      projectId: string;
+      projectName: string | null;
+      fileName: string | null;
+      ts: number;
+      ageMs: number;
+    };
+
+interface ActiveContextDomainDeps {
+  store: ActiveContextStore;
+  db: unknown;
+  getProject: (db: unknown, projectId: string) => { name?: string | null } | null | undefined;
+  now: () => number;
+}
+
+function parsePostActive(raw: { body: unknown }): Result<PostActiveInput> {
+  const body = (raw.body ?? {}) as Record<string, unknown>;
+  if (body.active === false) {
+    return ok({ kind: 'clear' });
+  }
+  const projectId = typeof body.projectId === 'string' ? body.projectId : '';
+  if (!projectId) {
+    return err(createApiError('BAD_REQUEST', 'projectId is required'));
+  }
+  const fileName =
+    typeof body.fileName === 'string' && body.fileName.length > 0 ? body.fileName : null;
+  return ok({ kind: 'set', projectId, fileName });
+}
+
+function handlePostActive(
+  input: PostActiveInput,
+  deps: ActiveContextDomainDeps,
+): Result<PostActiveOutput> {
+  if (input.kind === 'clear') {
+    deps.store.current = null;
+    return ok({ active: false });
+  }
+  const next: ActiveContext = {
+    projectId: input.projectId,
+    fileName: input.fileName,
+    ts: deps.now(),
+  };
+  deps.store.current = next;
+  return ok({ active: true, ...next });
+}
+
+function handleGetActive(
+  _input: void,
+  deps: ActiveContextDomainDeps,
+): Result<GetActiveOutput> {
+  const current = deps.store.current;
+  if (!current || deps.now() - current.ts > ACTIVE_CONTEXT_TTL_MS) {
+    deps.store.current = null;
+    return ok({ active: false });
+  }
+  const project = deps.getProject(deps.db, current.projectId);
+  return ok({
+    active: true,
+    projectId: current.projectId,
+    projectName: project?.name ?? null,
+    fileName: current.fileName,
+    ts: current.ts,
+    ageMs: deps.now() - current.ts,
   });
 }
+
+export const postActiveRoute = defineJsonRoute<PostActiveInput, PostActiveOutput, ActiveContextDomainDeps>({
+  method: 'post',
+  path: '/api/active',
+  requireSameOrigin: true,
+  parse: parsePostActive,
+  handle: handlePostActive,
+});
+
+export const getActiveRoute = defineJsonRoute<void, GetActiveOutput, ActiveContextDomainDeps>({
+  method: 'get',
+  path: '/api/active',
+  requireSameOrigin: true,
+  parse: () => ok(undefined),
+  handle: handleGetActive,
+});
+
+export function registerActiveContextRoutes(app: Express, ctx: RegisterActiveContextRoutesDeps): void {
+  const store: ActiveContextStore = { current: null };
+  const domainDeps: ActiveContextDomainDeps = {
+    store,
+    db: ctx.db,
+    getProject: ctx.projectStore.getProject,
+    now: () => Date.now(),
+  };
+  const adapter = { resolvedPortRef: ctx.http.resolvedPortRef };
+  mountJsonRoute(app, postActiveRoute, domainDeps, adapter);
+  mountJsonRoute(app, getActiveRoute, domainDeps, adapter);
+}

apps/daemon/src/amr-image-staging.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const STAGING_DIRNAME = '.amr-attachments';
+const STAGING_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function isWithinRoot(root: string, candidate: string): boolean {
+  const relativePath = path.relative(root, candidate);
+  return (
+    relativePath === '' ||
+    (relativePath.length > 0 &&
+      !relativePath.startsWith('..') &&
+      !path.isAbsolute(relativePath))
+  );
+}
+
+async function pruneStagedAttachments(stagingDir: string): Promise<void> {
+  let entries;
+  try {
+    entries = await fs.promises.readdir(stagingDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const cutoff = Date.now() - STAGING_MAX_AGE_MS;
+  await Promise.all(entries.map(async (entry) => {
+    if (!entry.isFile()) return;
+    const filePath = path.join(stagingDir, entry.name);
+    try {
+      const stat = await fs.promises.stat(filePath);
+      if (stat.mtimeMs < cutoff) {
+        await fs.promises.rm(filePath, { force: true });
+      }
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }));
+}
+
+export async function stageAmrImagePaths(
+  cwd: string | null | undefined,
+  imagePaths: string[],
+  uploadRoot?: string | null,
+): Promise<string[]> {
+  if (!cwd || !Array.isArray(imagePaths) || imagePaths.length === 0) return [];
+  const root = path.resolve(cwd);
+  const uploadRootReal = uploadRoot
+    ? await fs.promises.realpath(uploadRoot).catch(() => null)
+    : null;
+  const stagingDir = path.join(root, STAGING_DIRNAME);
+  await fs.promises.mkdir(stagingDir, { recursive: true });
+  await pruneStagedAttachments(stagingDir);
+
+  const staged: string[] = [];
+  for (const inputPath of imagePaths) {
+    if (typeof inputPath !== 'string' || inputPath.trim().length === 0) continue;
+    try {
+      const resolved = path.resolve(inputPath);
+      const real = await fs.promises.realpath(resolved);
+      if (uploadRootReal && !isWithinRoot(uploadRootReal, real)) continue;
+      const stat = await fs.promises.stat(real);
+      if (!stat.isFile()) continue;
+      if (isWithinRoot(root, real)) {
+        staged.push(real);
+        continue;
+      }
+      const basename = path.basename(real);
+      const destination = path.join(stagingDir, `${randomUUID()}-${basename}`);
+      await fs.promises.copyFile(real, destination);
+      staged.push(destination);
+    } catch {
+      // Ignore malformed or missing files; attachments are advisory input.
+    }
+  }
+  return staged;
+}

apps/daemon/src/app-config.ts

@@ -13,8 +13,9 @@
 // outside this machine.
 
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import path from 'node:path';
+import { expandHomePrefix } from './home-expansion.js';
 
 import {
   readInstallationFile,
@@ -85,6 +86,12 @@ export interface OrbitConfigPrefs {
   templateSkillId?: string | null;
 }
 
+export interface ProjectLocationPrefs {
+  id: string;
+  name: string;
+  path: string;
+}
+
 export interface AppConfigPrefs {
   onboardingCompleted?: boolean;
   agentId?: string | null;
@@ -99,6 +106,8 @@ export interface AppConfigPrefs {
   privacyDecisionAt?: number | null;
   orbit?: OrbitConfigPrefs;
   customInstructions?: string | null;
+  projectLocations?: ProjectLocationPrefs[];
+  defaultProjectLocationId?: string | null;
 }
 
 const ALLOWED_KEYS: ReadonlySet<keyof AppConfigPrefs> = new Set([
@@ -115,6 +124,8 @@ const ALLOWED_KEYS: ReadonlySet<keyof AppConfigPrefs> = new Set([
   'privacyDecisionAt',
   'orbit',
   'customInstructions',
+  'projectLocations',
+  'defaultProjectLocationId',
 ] as const);
 
 function configFile(dataDir: string): string {
@@ -142,6 +153,15 @@ function validateTelemetry(raw: unknown): TelemetryPrefs | undefined {
 }
 
 const AGENT_CLI_ENV_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
+  ['amr', new Set([
+    'VELA_BIN',
+    'VELA_LINK_URL',
+    'VELA_RUNTIME_KEY',
+    'VELA_OPENCODE_BIN',
+    'OPEN_DESIGN_AMR_PROFILE',
+    'OPENCODE_TEST_HOME',
+  ])],
+  ['aider', new Set(['AIDER_BIN'])],
   ['claude', new Set(['CLAUDE_CONFIG_DIR', 'CLAUDE_BIN', 'ANTHROPIC_BASE_URL', 'ANTHROPIC_API_KEY'])],
   ['codex', new Set(['CODEX_HOME', 'CODEX_BIN', 'OPENAI_BASE_URL', 'CODEX_API_KEY', 'OPENAI_API_KEY'])],
   ['copilot', new Set(['COPILOT_BIN'])],
@@ -157,6 +177,7 @@ const AGENT_CLI_ENV_KEYS: ReadonlyMap<string, ReadonlySet<string>> = new Map([
   ['pi', new Set(['PI_BIN'])],
   ['qoder', new Set(['QODER_BIN'])],
   ['qwen', new Set(['QWEN_BIN'])],
+  ['trae-cli', new Set(['TRAE_CLI_BIN'])],
   ['vibe', new Set(['VIBE_BIN'])],
 ]);
 
@@ -235,6 +256,46 @@ function validateOrbit(raw: unknown): OrbitConfigPrefs | undefined {
   return orbit;
 }
 
+function normalizeLocationId(raw: string, fallback: string): string {
+  const trimmed = raw.trim();
+  if (/^[A-Za-z0-9._-]{1,128}$/.test(trimmed) && trimmed !== 'default') {
+    return trimmed;
+  }
+  return fallback;
+}
+
+function autoProjectLocationId(pathKey: string): string {
+  return `loc_${createHash('sha256').update(pathKey).digest('base64url').slice(0, 16)}`;
+}
+
+function validateProjectLocations(raw: unknown): ProjectLocationPrefs[] | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  if (!Array.isArray(raw)) return undefined;
+  const result: ProjectLocationPrefs[] = [];
+  const seenIds = new Set<string>();
+  const seenPaths = new Set<string>();
+  for (const item of raw) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) continue;
+    const obj = item as Record<string, unknown>;
+    if (typeof obj.path !== 'string') continue;
+    const expanded = expandHomePrefix(obj.path.trim());
+    if (!expanded || !path.isAbsolute(expanded)) continue;
+    const normalizedPath = path.normalize(expanded);
+    const pathKey = process.platform === 'win32' ? normalizedPath.toLowerCase() : normalizedPath;
+    if (seenPaths.has(pathKey)) continue;
+    const id = normalizeLocationId(
+      typeof obj.id === 'string' ? obj.id : '',
+      autoProjectLocationId(pathKey),
+    );
+    if (seenIds.has(id)) continue;
+    const rawName = typeof obj.name === 'string' ? obj.name.trim() : '';
+    result.push({ id, name: rawName || path.basename(normalizedPath) || normalizedPath, path: normalizedPath });
+    seenIds.add(id);
+    seenPaths.add(pathKey);
+  }
+  return result;
+}
+
 export function agentCliEnvForAgent(
   prefs: AgentCliEnvPrefs | undefined,
   agentId: string,
@@ -320,6 +381,25 @@ function applyConfigValue(
     }
     return;
   }
+  if (key === 'projectLocations') {
+    const validated = validateProjectLocations(value);
+    if (validated !== undefined) {
+      target[key] = validated;
+    } else {
+      delete target[key];
+    }
+    return;
+  }
+  if (key === 'defaultProjectLocationId') {
+    if (typeof value === 'string') {
+      target[key] = normalizeLocationId(value, 'default');
+    } else if (value === null) {
+      target[key] = null;
+    } else {
+      delete target[key];
+    }
+    return;
+  }
 }
 
 function filterAllowedKeys(obj: Record<string, unknown>): AppConfigPrefs {

apps/daemon/src/artifact-manifest.ts

@@ -132,6 +132,13 @@ export function validateArtifactManifestInput(
     }
   }
 
+  if (manifest.primary !== undefined) {
+    if (manifest.primary !== true) {
+      const primaryErr = validateSupportingPath(manifest.primary);
+      if (primaryErr) return { ok: false, error: `artifactManifest.primary ${primaryErr}` };
+    }
+  }
+
   if (manifest.supportingFiles !== undefined) {
     if (!Array.isArray(manifest.supportingFiles)) {
       return { ok: false, error: 'artifactManifest.supportingFiles must be an array' };
@@ -194,10 +201,15 @@ export function validateArtifactManifestInput(
     }
   }
 
-  const safeEntry = typeof entry === 'string' ? entry : '';
-  if (!safeEntry || safeEntry.length > MAX_ENTRY_LENGTH) {
-    return { ok: false, error: `artifact entry exceeds max length (${MAX_ENTRY_LENGTH})` };
+  const manifestEntry =
+    typeof manifest.entry === 'string' && manifest.entry.trim()
+      ? manifest.entry.trim()
+      : entry;
+  const entryErr = validateSupportingPath(manifestEntry);
+  if (entryErr) {
+    return { ok: false, error: `artifactManifest.entry ${entryErr}` };
   }
+  const safeEntry = (manifestEntry as string).replace(/\\/g, '/');
 
   return { ok: true, value: sanitizeManifest(manifest, safeEntry, options) };
 }
@@ -216,6 +228,12 @@ export function sanitizeManifest(
     renderer: manifest.renderer,
     status: typeof manifest.status === 'string' && ALLOWED_STATUS.has(manifest.status) ? manifest.status : 'complete',
     exports: manifest.exports,
+    primary:
+      manifest.primary === true
+        ? true
+        : typeof manifest.primary === 'string'
+          ? manifest.primary.replace(/\\/g, '/')
+          : undefined,
     supportingFiles: Array.isArray(manifest.supportingFiles)
       ? manifest.supportingFiles.map((x) => String(x).replace(/\\/g, '/'))
       : undefined,

apps/daemon/src/byok-tools.ts

@@ -9,10 +9,8 @@
 // back as a `role: 'tool'` message → re-issue the completion. The chat surface
 // stays the same; the tool dispatch happens entirely daemon-side.
 //
-// Today we ship one tool — `generate_image` — backed by SenseAudio's
-// /v1/image/sync endpoint, since the BYOK chat session already authenticates
-// against SenseAudio with the same API key. Additional tools (TTS, video,
-// research) can be added here as the BYOK surface expands.
+// Today we ship image, video, and speech tools backed by SenseAudio endpoints,
+// since the BYOK chat session already authenticates with the same API key.
 
 import path from 'node:path';
 import { writeFile } from 'node:fs/promises';
@@ -43,6 +41,18 @@ export function isSenseAudioImageModel(value: unknown): value is string {
 
 const SENSEAUDIO_DEFAULT_BASE_URL = 'https://api.senseaudio.cn';
 const PROMPT_MAX_LENGTH = 2000;
+const SENSEAUDIO_TTS_MODEL = 'senseaudio-tts-1.5-260319';
+const SENSEAUDIO_DEFAULT_VOICE_ID = 'female_0033_b';
+const HEX_AUDIO_PATTERN = /^[0-9a-fA-F]+$/;
+
+function appendSenseAudioApiPath(baseUrl: string, path: string): string {
+  const url = new URL(baseUrl);
+  const trimmed = url.pathname.replace(/\/+$/, '');
+  url.pathname = /\/v\d+(\/|$)/.test(trimmed)
+    ? `${trimmed}${path}`
+    : `${trimmed}/v1${path}`;
+  return url.toString();
+}
 
 // SenseAudio video — the API only documents one model today, so the
 // wire id is a const. The chat tool's `generate_video` param surface
@@ -122,6 +132,30 @@ export const BYOK_SENSEAUDIO_TOOLS = [
       },
     },
   },
+  {
+    type: 'function' as const,
+    function: {
+      name: 'generate_speech',
+      description:
+        'Generate a text-to-speech voiceover using SenseAudio TTS. Returns a URL pointing to the rendered MP3. Use this whenever the user asks for narration, voiceover, speech, TTS, or spoken audio. After this tool succeeds, reply with a clickable markdown link to the MP3.',
+      parameters: {
+        type: 'object',
+        properties: {
+          text: {
+            type: 'string',
+            description:
+              'Exact script to speak. Include only the words that should be spoken, not production notes.',
+          },
+          voice_id: {
+            type: 'string',
+            description:
+              `Optional SenseAudio voice id. Defaults to ${SENSEAUDIO_DEFAULT_VOICE_ID}.`,
+          },
+        },
+        required: ['text'],
+      },
+    },
+  },
   {
     type: 'function' as const,
     function: {
@@ -206,6 +240,10 @@ export interface BYOKToolContext {
    *  (e.g. 1 ms) to keep the suite fast without changing the polling
    *  semantics. */
   videoPollIntervalMs?: number;
+  /** Optional per-request init copied from the live chat turn. Used to
+   *  forward the current proxy dispatcher into every upstream/download
+   *  fetch the BYOK tool executor performs. */
+  requestInit?: Pick<RequestInit, 'dispatcher'>;
 }
 
 export interface ImageToolResult {
@@ -217,6 +255,112 @@ export interface ImageToolResult {
   error?: string;
 }
 
+function withToolRequestInit(
+  ctx: BYOKToolContext,
+  init: RequestInit,
+): RequestInit {
+  return {
+    ...ctx.requestInit,
+    ...init,
+  };
+}
+
+export async function executeGenerateSpeech(
+  args: { text?: unknown; voice_id?: unknown },
+  ctx: BYOKToolContext,
+): Promise<ImageToolResult> {
+  const text = typeof args.text === 'string' ? args.text.trim() : '';
+  if (!text) return { ok: false, error: 'text is required' };
+
+  let dir: string;
+  try {
+    dir = await ensureProject(ctx.projectsRoot, ctx.projectId);
+  } catch (err) {
+    return {
+      ok: false,
+      error: `invalid projectId for speech storage: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const apiKey = ctx.upstreamApiKey;
+  if (!apiKey) return { ok: false, error: 'no SenseAudio API key available' };
+
+  const voiceId =
+    typeof args.voice_id === 'string' && args.voice_id.trim()
+      ? args.voice_id.trim()
+      : SENSEAUDIO_DEFAULT_VOICE_ID;
+  const baseUrl = ctx.upstreamBaseUrl || SENSEAUDIO_DEFAULT_BASE_URL;
+  let data: {
+    data?: { audio?: string };
+    base_resp?: { status_code?: number; status_msg?: string };
+  };
+  try {
+    const resp = await fetch(appendSenseAudioApiPath(baseUrl, '/t2a_v2'), withToolRequestInit(ctx, {
+      method: 'POST',
+      redirect: 'error',
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: SENSEAUDIO_TTS_MODEL,
+        text,
+        stream: false,
+        voice_setting: {
+          voice_id: voiceId,
+          speed: 1,
+          vol: 1,
+          pitch: 0,
+        },
+        audio_setting: {
+          format: 'mp3',
+          sample_rate: 32000,
+          bitrate: 128000,
+          channel: 2,
+        },
+      }),
+    }));
+    const respText = await resp.text();
+    if (!resp.ok) {
+      return { ok: false, error: `senseaudio speech ${resp.status}: ${respText.slice(0, 240)}` };
+    }
+    try {
+      data = JSON.parse(respText) as typeof data;
+    } catch {
+      return { ok: false, error: `senseaudio speech non-JSON: ${respText.slice(0, 200)}` };
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+  if (data?.base_resp && data.base_resp.status_code !== 0) {
+    return {
+      ok: false,
+      error: `senseaudio speech api error ${data.base_resp.status_code}: ${data.base_resp.status_msg || 'unknown'}`,
+    };
+  }
+  const hex = data?.data?.audio;
+  if (typeof hex !== 'string' || !hex) {
+    return { ok: false, error: 'senseaudio speech response missing data.audio' };
+  }
+  if (hex.length % 2 !== 0 || !HEX_AUDIO_PATTERN.test(hex)) {
+    return { ok: false, error: 'senseaudio speech response contained invalid hex audio' };
+  }
+  const bytes = Buffer.from(hex, 'hex');
+  if (bytes.length === 0) return { ok: false, error: 'senseaudio speech decoded zero bytes' };
+
+  const id = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+  const filename = `byok-speech-${id}.mp3`;
+  await writeFile(path.join(dir, filename), bytes);
+
+  return {
+    ok: true,
+    url: `/api/projects/${encodeURIComponent(ctx.projectId)}/files/${filename}`,
+  };
+}
+
 function sanitizeAspectRatio(raw: unknown): string {
   if (typeof raw !== 'string') return '1:1';
   return ASPECT_TO_SIZE[raw] ? raw : '1:1';
@@ -290,7 +434,7 @@ export async function executeGenerateImage(
   const trimmedBase = baseUrl.replace(/\/+$/, '');
   let imageUrl: string;
   try {
-    const resp = await fetch(`${trimmedBase}/v1/image/sync`, {
+    const resp = await fetch(`${trimmedBase}/v1/image/sync`, withToolRequestInit(ctx, {
       method: 'POST',
       headers: {
         authorization: `Bearer ${apiKey}`,
@@ -301,7 +445,7 @@ export async function executeGenerateImage(
         prompt,
         size,
       }),
-    });
+    }));
     if (!resp.ok) {
       const text = await resp.text().catch(() => '');
       return {
@@ -339,7 +483,7 @@ export async function executeGenerateImage(
 
   let bytes: Buffer;
   try {
-    const imgResp = await fetch(imageUrl, { redirect: 'error' });
+    const imgResp = await fetch(imageUrl, withToolRequestInit(ctx, { redirect: 'error' }));
     if (!imgResp.ok) {
       return { ok: false, error: `image download ${imgResp.status}` };
     }
@@ -466,7 +610,7 @@ export async function executeGenerateVideo(
   // Step 1: POST /v1/video/create → task_id.
   let taskId: string;
   try {
-    const resp = await fetch(`${trimmedBase}/v1/video/create`, {
+    const resp = await fetch(`${trimmedBase}/v1/video/create`, withToolRequestInit(ctx, {
       method: 'POST',
       headers: {
         authorization: `Bearer ${apiKey}`,
@@ -480,7 +624,7 @@ export async function executeGenerateVideo(
         ratio,
         provider_specific: { generate_audio: generateAudio },
       }),
-    });
+    }));
     if (!resp.ok) {
       const text = await resp.text().catch(() => '');
       return {
@@ -509,10 +653,10 @@ export async function executeGenerateVideo(
     try {
       statusResp = await fetch(
         `${trimmedBase}/v1/video/status?id=${encodeURIComponent(taskId)}`,
-        {
+        withToolRequestInit(ctx, {
           method: 'GET',
           headers: { authorization: `Bearer ${apiKey}` },
-        },
+        }),
       );
     } catch (err) {
       return {
@@ -572,7 +716,7 @@ export async function executeGenerateVideo(
 
   let bytes: Buffer;
   try {
-    const videoResp = await fetch(videoUrl, { redirect: 'error' });
+    const videoResp = await fetch(videoUrl, withToolRequestInit(ctx, { redirect: 'error' }));
     if (!videoResp.ok) {
       return { ok: false, error: `video download ${videoResp.status}` };
     }
@@ -595,4 +739,3 @@ export async function executeGenerateVideo(
     url: `/api/projects/${encodeURIComponent(ctx.projectId)}/files/${filename}`,
   };
 }
-

apps/daemon/src/chat-routes.ts

@@ -1,16 +1,25 @@
 import type { Express } from 'express';
 import type { RouteDeps } from './server-context.js';
 import { seedProviderIfMissing } from './media-config.js';
+import {
+  buildLegacyMaxTokensParam,
+  buildMaxCompletionTokensParam,
+  buildOpenAIChatTokenParam,
+  isUnsupportedMaxTokensError,
+} from './openai-chat-token-params.js';
 import {
   BYOK_SENSEAUDIO_TOOLS,
   executeGenerateImage,
+  executeGenerateSpeech,
   executeGenerateVideo,
   isSenseAudioImageModel,
   type BYOKToolContext,
 } from './byok-tools.js';
 import { isSafeId as isSafeProjectId } from './projects.js';
 import { projectKindToTracking } from '@open-design/contracts/analytics';
-import { validateBaseUrlResolved } from './connectionTest.js';
+import { proxyDispatcherRequestInit, validateBaseUrlResolved } from './connectionTest.js';
+import { googleStreamGenerateContentUrl } from './google-models.js';
+import { createRoleMarkerGuard } from './role-marker-guard.js';
 
 // Allowlist for the `/feedback` route. Mirrors the
 // ChatMessageFeedbackReasonCode union in packages/contracts/src/api/chat.ts.
@@ -35,7 +44,7 @@ export interface RegisterChatRoutesDeps extends RouteDeps<'db' | 'design' | 'htt
 export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
   const { db, design } = ctx;
   const { sendApiError, createSseResponse } = ctx.http;
-  const { startChatRun, submitToolResultToRun } = ctx.chat;
+  const { submitToolResultToRun } = ctx.chat;
   const { testProviderConnection, testAgentConnection, getAgentDef, isKnownModel, sanitizeCustomModel, listProviderModels } = ctx.agents;
   const {
     handleCritiqueArtifact,
@@ -44,7 +53,6 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     critiqueResponseCapBytes,
     critiqueRunRegistry,
   } = ctx.critique;
-  const isDaemonShuttingDown = ctx.lifecycle?.isDaemonShuttingDown ?? (() => false);
   const rejectProxyPluginContext = (body: Record<string, unknown>, res: any) => {
     if (
       (typeof body.pluginId === 'string' && body.pluginId.trim().length > 0) ||
@@ -69,6 +77,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
   // so any handler we wired here was shadowed and never executed. Plugin
   // snapshot resolution, clientType inference, and the daemon-side
   // run_created/finished analytics all live in `server.ts` now.
+  // POST /api/chat is likewise owned by `server.ts`; keep the chat run
+  // launch path single-sourced so validation changes land on the live route.
 
   app.get('/api/runs', (req, res) => {
     const { projectId, conversationId, status } = req.query;
@@ -208,15 +218,6 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     res.status(202).json(outcome);
   });
 
-  app.post('/api/chat', (req, res) => {
-    if (isDaemonShuttingDown()) {
-      return sendApiError(res, 503, 'UPSTREAM_UNAVAILABLE', 'daemon is shutting down');
-    }
-    const run = design.runs.create();
-    design.runs.stream(run, req, res);
-    design.runs.start(run, () => startChatRun(req.body || {}, run));
-  });
-
   // ---- Connection tests (single-shot JSON; no SSE) ------------------------
   // Settings dialog uses these to verify a config works without sending a
   // real chat. Always return HTTP 200 with `ok: false` on upstream-caused
@@ -262,15 +263,21 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       );
     }
     try {
-      const result = await listProviderModels({
-        protocol,
-        baseUrl: body.baseUrl,
-        apiKey: body.apiKey,
-        apiVersion:
-          typeof body.apiVersion === 'string' ? body.apiVersion : undefined,
-        signal: controller.signal,
-      });
-      return res.json(result);
+      const proxyDispatcher = proxyDispatcherRequestInit();
+      try {
+        const result = await listProviderModels({
+          protocol,
+          baseUrl: body.baseUrl,
+          apiKey: body.apiKey,
+          apiVersion:
+            typeof body.apiVersion === 'string' ? body.apiVersion : undefined,
+          signal: controller.signal,
+          requestInit: proxyDispatcher.requestInit,
+        });
+        return res.json(result);
+      } finally {
+        await proxyDispatcher.close();
+      }
     } catch (err: any) {
       console.warn(
         `[provider:models] uncaught: ${err instanceof Error ? err.message : String(err)}`,
@@ -526,7 +533,16 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
         if (!match || match.index === undefined) break;
         const frame = buffer.slice(0, match.index);
         buffer = buffer.slice(match.index + match[0].length);
-        if (await onFrame(collectSseFrame(frame))) return;
+        if (await onFrame(collectSseFrame(frame))) {
+          // Fire-and-forget cancel: awaiting hangs on some response-stream
+          // implementations (notably Response built from Uint8Array body,
+          // exposed by tests/proxy-routes.test.ts ollama case where the
+          // mock body's tee'd cancel() never resolves). The cancel signal
+          // is a hint; we're already returning from the function, so we
+          // don't gain anything by blocking on it.
+          void reader.cancel().catch(() => {});
+          return;
+        }
       }
     }
 
@@ -552,7 +568,11 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
         if (!line) continue;
         try {
           const data = JSON.parse(line);
-          if (await onFrame({ data })) return;
+          if (await onFrame({ data })) {
+            // See note in streamUpstreamSse — fire-and-forget cancel.
+            void reader.cancel().catch(() => {});
+            return;
+          }
         } catch {
           // Ignore malformed provider keepalive lines.
         }
@@ -621,6 +641,30 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     return '';
   };
 
+  // Per-request role-marker guard for BYOK proxy streams (#3247).
+  function createDeltaGuard(sse: any) {
+    const guard = createRoleMarkerGuard('proxy');
+    return {
+      sendDelta(text: string) {
+        if (guard.contaminated || !text) return;
+        const safe = guard.feedText(text);
+        if (safe.length > 0) {
+          sse.send('delta', { delta: safe });
+        }
+        if (guard.contaminated) {
+          const warn = guard.warningEvent();
+          const markerText = warn?.marker ?? '## user';
+          sse.send('delta', {
+            delta: `\n\n---\n⚠️ **Security warning:** The model attempted to emit a fabricated role marker (\`${markerText}\`). Response was truncated to prevent unauthorized instruction injection. See issue #3247.\n`,
+          });
+        }
+      },
+      get contaminated() { 
+        return guard.contaminated; 
+      },
+    };
+  }
+
   app.post('/api/proxy/anthropic/stream', async (req, res) => {
     /** @type {Partial<ProxyStreamRequest>} */
     const proxyBody = req.body || {};
@@ -663,9 +707,12 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     }
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
     try {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      sse.send('start', { model });
       const response = await fetch(url, {
+        ...proxyDispatcher.requestInit,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -690,6 +737,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       }
 
       let ended = false;
+      const guard = createDeltaGuard(sse);
       await streamUpstreamSse(response, ({ event, data }: any) => {
         if (!data) return false;
         if (event === 'error' || data.type === 'error') {
@@ -699,7 +747,12 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           return true;
         }
         if (event === 'content_block_delta' && typeof data.delta?.text === 'string') {
-          sse.send('delta', { delta: data.delta.text });
+          guard.sendDelta(data.delta.text);
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            ended = true; 
+            return true; 
+          }
         }
         if (event === 'message_stop') {
           sse.send('end', {});
@@ -714,6 +767,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:anthropic] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 
@@ -755,15 +810,20 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     const payload: any = {
       model,
       messages: payloadMessages,
-      max_tokens:
+      ...buildOpenAIChatTokenParam(
+        model,
         typeof maxTokens === 'number' && maxTokens > 0 ? maxTokens : 8192,
+      ),
       stream: true,
     };
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
     try {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      sse.send('start', { model });
       const response = await fetch(url, {
+        ...proxyDispatcher.requestInit,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -787,6 +847,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       }
 
       let ended = false;
+      const guard = createDeltaGuard(sse);
       await streamUpstreamSse(response, ({ payload, data }: any) => {
         if (payload === '[DONE]') {
           sse.send('end', {});
@@ -801,7 +862,14 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           return true;
         }
         const delta = extractOpenAIText(data);
-        if (delta) sse.send('delta', { delta });
+        if (delta) { 
+          guard.sendDelta(delta); 
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            ended = true; 
+            return true; 
+          } 
+        }
         return false;
       });
       if (!ended) sse.send('end', {});
@@ -810,6 +878,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:openai] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 
@@ -865,41 +935,74 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       payloadMessages.unshift({ role: 'system', content: systemPrompt });
     }
 
+    const effectiveMaxTokens =
+      typeof maxTokens === 'number' && maxTokens > 0 ? maxTokens : 8192;
     const payload = {
       ...(usesVersionedOpenAIPath ? { model } : {}),
       messages: payloadMessages,
-      max_tokens:
-        typeof maxTokens === 'number' && maxTokens > 0 ? maxTokens : 8192,
+      ...buildLegacyMaxTokensParam(effectiveMaxTokens),
+      stream: true,
+    };
+    const retryPayload = {
+      ...(usesVersionedOpenAIPath ? { model } : {}),
+      messages: payloadMessages,
+      ...buildMaxCompletionTokensParam(effectiveMaxTokens),
       stream: true,
     };
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
     try {
-      const response = await fetch(url, {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      sse.send('start', { model });
+      const requestInit = {
+        ...proxyDispatcher.requestInit,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'api-key': apiKey,
         },
+        redirect: 'error' as const,
+      };
+      let response = await fetch(url, {
+        ...requestInit,
         body: JSON.stringify(payload),
-        redirect: 'error',
       });
 
       if (!response.ok) {
-        const errorText = await response.text();
-        console.error(
-          `[proxy:azure] upstream error: ${response.status} ${redactAuthTokens(errorText)}`,
-        );
-        sendProxyError(sse, `Upstream error: ${response.status}`, {
-          code: proxyErrorCode(response.status),
-          details: errorText,
-          retryable: response.status === 429 || response.status >= 500,
-        });
-        return sse.end();
+        let errorText = await response.text();
+        if (
+          response.status === 400 &&
+          isUnsupportedMaxTokensError(errorText)
+        ) {
+          console.warn(
+            `[proxy:azure] retrying request with max_completion_tokens deployment=${model}`,
+          );
+          response = await fetch(url, {
+            ...requestInit,
+            body: JSON.stringify(retryPayload),
+          });
+          if (response.ok) {
+            errorText = '';
+          } else {
+            errorText = await response.text();
+          }
+        }
+        if (!response.ok) {
+          console.error(
+            `[proxy:azure] upstream error: ${response.status} ${redactAuthTokens(errorText)}`,
+          );
+          sendProxyError(sse, `Upstream error: ${response.status}`, {
+            code: proxyErrorCode(response.status),
+            details: errorText,
+            retryable: response.status === 429 || response.status >= 500,
+          });
+          return sse.end();
+        }
       }
 
       let ended = false;
+      const guard = createDeltaGuard(sse);
       await streamUpstreamSse(response, ({ payload: ssePayload, data }: any) => {
         if (ssePayload === '[DONE]') {
           sse.send('end', {});
@@ -914,7 +1017,13 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           return true;
         }
         const delta = extractOpenAIText(data);
-        if (delta) sse.send('delta', { delta });
+        if (delta) { guard.sendDelta(delta); 
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            ended = true; 
+            return true; 
+          } 
+        }
         return false;
       });
       if (!ended) sse.send('end', {});
@@ -923,6 +1032,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:azure] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 
@@ -951,8 +1062,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       );
     }
 
-    const clean = effectiveBaseUrl.replace(/\/+$/, '');
-    const url = `${clean}/v1beta/models/${encodeURIComponent(model)}:streamGenerateContent?alt=sse`;
+    const url = googleStreamGenerateContentUrl(effectiveBaseUrl, model);
     console.log(
       `[proxy:google] ${req.method} ${validated.parsed!.hostname} model=${model}`,
     );
@@ -973,9 +1083,12 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     }
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
     try {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      sse.send('start', { model });
       const response = await fetch(url, {
+        ...proxyDispatcher.requestInit,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -999,6 +1112,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       }
 
       let ended = false;
+      const guard = createDeltaGuard(sse);
       await streamUpstreamSse(response, ({ data }: any) => {
         if (!data) return false;
         const streamError = extractStreamErrorMessage(data);
@@ -1008,7 +1122,13 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           return true;
         }
         const delta = extractGeminiText(data);
-        if (delta) sse.send('delta', { delta });
+        if (delta) { guard.sendDelta(delta); 
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            ended = true; 
+            return true; 
+          } 
+        }
         const blockMessage = extractGeminiBlockMessage(data);
         if (blockMessage) {
           sendProxyError(sse, blockMessage, { details: data });
@@ -1023,6 +1143,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:google] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 
@@ -1060,9 +1182,12 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     }
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
     try {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      sse.send('start', { model });
       const response = await fetch(url, {
+        ...proxyDispatcher.requestInit,
         method: 'POST',
         headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
         body: JSON.stringify(payload),
@@ -1081,6 +1206,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       }
 
       let ended = false;
+      const guard = createDeltaGuard(sse);
       await streamUpstreamNdjson(response, ({ data }: any) => {
         if (!data) return false;
         if (data.done) {
@@ -1089,7 +1215,14 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           return true;
         }
         const content = data.message?.content;
-        if (typeof content === 'string' && content) sse.send('delta', { delta: content });
+        if (typeof content === 'string' && content) { 
+          guard.sendDelta(content); 
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            ended = true; 
+            return true; 
+          } 
+        }
         return false;
       });
       if (!ended) sse.send('end', {});
@@ -1098,6 +1231,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:ollama] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 
@@ -1193,12 +1328,15 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       ? byokImageModel
       : undefined;
 
+    let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
+
     const toolCtx: BYOKToolContext = {
       projectRoot: ctx.paths.PROJECT_ROOT,
       projectsRoot: ctx.paths.PROJECTS_DIR,
       projectId,
       upstreamApiKey: apiKey,
       upstreamBaseUrl: effectiveBaseUrl,
+      requestInit: {},
       // Spread-conditional because tsconfig's exactOptionalPropertyTypes
       // forbids `field: undefined` on an optional slot. The byok-tools
       // executor reads `ctx.defaultImageModel` with `isSenseAudioImageModel`
@@ -1227,6 +1365,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
         tool_choice: 'auto',
       };
       const response = await fetch(url, {
+        ...toolCtx.requestInit,
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
@@ -1253,6 +1392,7 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       let finishReason = '';
       let providerError = '';
 
+      const guard = createDeltaGuard(sse);
       await streamUpstreamSse(response, ({ payload, data }: any) => {
         if (payload === '[DONE]') return true;
         if (!data) return false;
@@ -1274,7 +1414,11 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
         // emit text before / after a tool_call in the same turn, and
         // we want the user to see whatever the model decided to say.
         if (typeof delta.content === 'string' && delta.content) {
-          sse.send('delta', { delta: delta.content });
+          guard.sendDelta(delta.content);
+          if (guard.contaminated) { 
+            sse.send('end', {}); 
+            return true; 
+          }
         }
 
         // Tool call deltas stream as fragments — `id` arrives once at
@@ -1341,32 +1485,35 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
     const executeOneTool = async (call: {
       id: string;
       function: { name: string; arguments: string };
-    }): Promise<{ ok: boolean; url?: string; error?: string; kind?: 'image' | 'video' }> => {
+    }): Promise<{ ok: boolean; url?: string; error?: string; kind?: 'image' | 'video' | 'speech' }> => {
       const fnName = call?.function?.name ?? '';
-      if (fnName !== 'generate_image' && fnName !== 'generate_video') {
+      if (fnName !== 'generate_image' && fnName !== 'generate_video' && fnName !== 'generate_speech') {
         return {
           ok: false,
           error: `unknown tool: ${fnName || 'unnamed'}`,
         };
       }
+      const toolKind = fnName === 'generate_image' ? 'image' : fnName === 'generate_video' ? 'video' : 'speech';
       let args: any = {};
       try {
         args = JSON.parse(call.function.arguments || '{}');
       } catch {
-        return { ok: false, error: 'tool arguments were not valid JSON' };
+        return { ok: false, error: 'tool arguments were not valid JSON', kind: toolKind };
       }
       if (fnName === 'generate_image') {
         const result = await executeGenerateImage(args, toolCtx);
         return { ...result, kind: 'image' };
       }
+      if (fnName === 'generate_speech') {
+        const result = await executeGenerateSpeech(args, toolCtx);
+        return { ...result, kind: 'speech' };
+      }
       // generate_video — longer (up to 5 min), async-with-polling.
       const result = await executeGenerateVideo(args, toolCtx);
       return { ...result, kind: 'video' };
     };
 
     const sse = createSseResponse(res);
-    sse.send('start', { model });
-
     // SenseAudio's gateway issues one API key that works for both
     // /v1/chat/completions and the image / TTS surfaces. Mirror the
     // BYOK key into media-config so the CLI agent path (`od media
@@ -1393,6 +1540,9 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       });
 
     try {
+      proxyDispatcher = proxyDispatcherRequestInit();
+      toolCtx.requestInit = proxyDispatcher.requestInit;
+      sse.send('start', { model });
       for (let loop = 0; loop < MAX_BYOK_TOOL_LOOPS; loop++) {
         const turn = await runSenseAudioTurn(sse, workingMessages);
         if (turn.kind === 'error') return sse.end();
@@ -1425,9 +1575,13 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
           const content = result.ok
             ? result.kind === 'video'
               ? `Video generated successfully. URL: ${result.url}. Reply to the user with a clickable markdown link, e.g. [▶ Play video](${result.url}). Do NOT use markdown image syntax — the chat renderer does not embed <video> tags.`
+              : result.kind === 'speech'
+                ? `Speech generated successfully. URL: ${result.url}. Reply to the user with a clickable markdown link to the MP3, e.g. [▶ Play voiceover](${result.url}).`
               : `Image generated successfully. URL: ${result.url}. Reply to the user with: ![generated image](${result.url})`
             : result.kind === 'video'
               ? `Video generation failed: ${result.error}. Apologize briefly and suggest a retry with a more specific prompt or a shorter duration.`
+              : result.kind === 'speech'
+                ? `Speech generation failed: ${result.error}. Apologize briefly and suggest a retry with a shorter script or a valid voice id.`
               : `Image generation failed: ${result.error}. Apologize briefly and suggest a retry with a more specific prompt.`;
           workingMessages.push({
             role: 'tool',
@@ -1448,6 +1602,8 @@ export function registerChatRoutes(app: Express, ctx: RegisterChatRoutesDeps) {
       console.error(`[proxy:senseaudio] internal error: ${err.message}`);
       sendProxyError(sse, err.message, { code: 'INTERNAL_ERROR' });
       sse.end();
+    } finally {
+      await proxyDispatcher?.close();
     }
   });
 

apps/daemon/src/claude-diagnostics.ts

@@ -1,3 +1,5 @@
+import path from 'node:path';
+
 import { redactSecrets } from './redact.js';
 
 export interface ClaudeCliDiagnosticInput {
@@ -7,6 +9,7 @@ export interface ClaudeCliDiagnosticInput {
   stderrTail?: string | null;
   stdoutTail?: string | null;
   env?: Record<string, unknown> | null;
+  resolvedBin?: string | null;
 }
 
 export interface ClaudeCliDiagnostic {
@@ -51,6 +54,15 @@ function withContext(
   };
 }
 
+function selectedClaudeCompatibleRuntime(input: ClaudeCliDiagnosticInput): 'claude' | 'openclaude' {
+  if (typeof input.resolvedBin !== 'string' || !input.resolvedBin.trim()) return 'claude';
+  const base = path
+    .basename(input.resolvedBin.trim().replace(/\\/g, '/'))
+    .replace(/\.(exe|cmd|bat)$/i, '')
+    .toLowerCase();
+  return base === 'openclaude' ? 'openclaude' : 'claude';
+}
+
 export function diagnoseClaudeCliFailure(
   input: ClaudeCliDiagnosticInput,
 ): ClaudeCliDiagnostic | null {
@@ -61,6 +73,8 @@ export function diagnoseClaudeCliFailure(
   const normalized = text.toLowerCase();
   const hasCustomBaseUrl = envValue(input.env, 'ANTHROPIC_BASE_URL') !== null;
   const hasConfigDir = envValue(input.env, 'CLAUDE_CONFIG_DIR') !== null;
+  const runtime = selectedClaudeCompatibleRuntime(input);
+  const isOpenClaude = runtime === 'openclaude';
 
   const customEndpointConnectionFailure =
     hasCustomBaseUrl &&
@@ -78,6 +92,8 @@ export function diagnoseClaudeCliFailure(
   const authFailure =
     /\b401\b/.test(text) ||
     /apikeysource["'\s:]+none/i.test(text) ||
+    /not logged in/i.test(text) ||
+    /please run \/login/i.test(text) ||
     /(auth|oauth|credential|token).*(fail|invalid|missing|expired|not found|none|unauthorized)/i.test(text) ||
     /(unauthorized|invalid api key|missing api key|could not authenticate|authentication failed)/i.test(text);
   if (authFailure && hasCustomBaseUrl) {
@@ -88,6 +104,13 @@ export function diagnoseClaudeCliFailure(
     );
   }
   if (authFailure) {
+    if (isOpenClaude) {
+      return withContext(
+        'OpenClaude could not authenticate with its configured endpoint.',
+        'The spawned OpenClaude process exited before producing a response. Check the OpenClaude API key, endpoint, and local configuration, then retry.',
+        input,
+      );
+    }
     const configHint = hasConfigDir
       ? 'The configured Claude config directory may contain stale or expired auth state.'
       : 'If you use multiple Claude profiles, set CLAUDE_CONFIG_DIR in Settings so Open Design spawns the same profile that works in your terminal.';
@@ -145,6 +168,13 @@ export function diagnoseClaudeCliFailure(
   }
 
   if (!text.trim() && input.exitCode === 1) {
+    if (isOpenClaude) {
+      return withContext(
+        'OpenClaude exited before producing diagnostics.',
+        'Check the OpenClaude API key, endpoint, and local configuration, then retry.',
+        input,
+      );
+    }
     const message = hasConfigDir
       ? 'Claude Code exited before producing diagnostics while using the configured Claude profile.'
       : 'Claude Code exited before producing diagnostics.';

apps/daemon/src/claude-stream.ts

@@ -19,6 +19,8 @@
  * `tool_use` event when that block stops.
  */
 
+import { createRoleMarkerGuard, type RoleMarkerGuard } from './role-marker-guard.js';
+
 type StreamEvent = Record<string, unknown>;
 type EventSink = (event: StreamEvent) => void;
 type BlockState = { type?: unknown; name?: unknown; id?: unknown; input: string };
@@ -39,18 +41,60 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
   // Most recent assistant message id so content_block_* events without an id
   // can be attributed correctly.
   let currentMessageId: string | null = null;
-  // Message ids that already streamed text via `stream_event` deltas.
+  // Message ids that already streamed assistant text/thinking via
+  // `stream_event` deltas.
   // When `--include-partial-messages` is OFF (older Claude Code, e.g. 1.0.84
   // pre-flag), no deltas arrive — only the final `assistant` wrapper carries
-  // text. The fallback below emits that text once, but we must skip it for
+  // content. The fallback below emits that content once, but we must skip it for
   // newer builds that already streamed deltas, otherwise the message would
   // duplicate.
   const textStreamed = new Set<string>();
+  const thinkingStreamed = new Set<string>();
+  let currentMessageStreamedText = false;
+  let currentMessageStreamedThinking = false;
+  // Per-message role-marker guards for cross-chunk detection (#3247).
+  const roleGuards = new Map<string, RoleMarkerGuard>();
 
   function blockKey(index: unknown): string {
     return `${currentMessageId ?? 'anon'}:${index}`;
   }
 
+  // Per-message role-marker guard (#3247). Covers text_delta ONLY.
+  //
+  // Why not thinking_delta: extended thinking is rendered to a
+  // separate `kind: 'thinking'` payload and is never folded into
+  // `m.content` by `buildDaemonTranscript` (apps/web/src/providers/daemon.ts),
+  // so it cannot be re-serialized as a turn boundary on the next
+  // round-trip — it is not a #3247 re-injection vector. Models
+  // routinely emit literal `## user` / `## assistant` lines in
+  // chain-of-thought when reasoning about conversation structure,
+  // and with kill-on-detection wired in server.ts a guard on the
+  // thinking channel would abort otherwise-legitimate runs without
+  // any compensating security benefit. See PR #3303 review
+  // r3324xxxxxx. Thinking is passed through unguarded; only the
+  // user-visible text channel is policed.
+  function emitSafeText(msgId: string | null, text: string, eventType: string = 'text_delta') {
+    if (eventType !== 'text_delta' || !msgId) {
+      onEvent({ type: eventType, delta: text });
+      return;
+    }
+    let guard = roleGuards.get(msgId);
+    if (!guard) {
+      guard = createRoleMarkerGuard(msgId);
+      roleGuards.set(msgId, guard);
+    }
+    if (guard.contaminated) return;
+
+    const safe = guard.feedText(text);
+    if (safe.length > 0) {
+      onEvent({ type: eventType, delta: safe });
+    }
+    if (guard.contaminated) {
+      const warn = guard.warningEvent();
+      if (warn) onEvent(warn);
+    }
+  }
+
   function feed(chunk: string) {
     buffer += chunk;
     let nl;
@@ -110,9 +154,12 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
     // covered it (older Claude Code without --include-partial-messages
     // delivers text only here; newer builds stream it and would duplicate).
     if (obj.type === 'assistant' && isRecord(obj.message) && Array.isArray(obj.message.content)) {
-      currentMessageId = typeof obj.message.id === 'string' ? obj.message.id : currentMessageId;
-      const msgId = typeof obj.message.id === 'string' ? obj.message.id : null;
-      const alreadyStreamed = msgId ? textStreamed.has(msgId) : false;
+      const explicitMsgId = typeof obj.message.id === 'string' ? obj.message.id : null;
+      const textMsgId = explicitMsgId ?? (currentMessageStreamedText ? currentMessageId : null);
+      const thinkingMsgId = explicitMsgId ?? (currentMessageStreamedThinking ? currentMessageId : null);
+      if (explicitMsgId) currentMessageId = explicitMsgId;
+      const textAlreadyStreamed = textMsgId ? textStreamed.has(textMsgId) : false;
+      const thinkingAlreadyStreamed = thinkingMsgId ? thinkingStreamed.has(thinkingMsgId) : false;
       // Per-turn `stop_reason` is emitted as `turn_end` AFTER the content
       // blocks have been processed (see below). When `--include-partial-
       // messages` is unsupported, tool_use events surface only from the
@@ -138,19 +185,19 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
             input: block.input ?? null,
           });
         } else if (
-          !alreadyStreamed &&
+          !textAlreadyStreamed &&
           block.type === 'text' &&
           typeof block.text === 'string' &&
           block.text.length > 0
         ) {
-          onEvent({ type: 'text_delta', delta: block.text });
+          emitSafeText(textMsgId, block.text);
         } else if (
-          !alreadyStreamed &&
+          !thinkingAlreadyStreamed &&
           block.type === 'thinking' &&
           typeof block.thinking === 'string' &&
           block.thinking.length > 0
         ) {
-          onEvent({ type: 'thinking_delta', delta: block.thinking });
+          emitSafeText(thinkingMsgId, block.thinking, 'thinking_delta');
         }
       }
       // Surface the turn_end signal now that every tool_use in this
@@ -160,6 +207,8 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
       if (stopReason) {
         onEvent({ type: 'turn_end', stopReason });
       }
+      currentMessageStreamedText = false;
+      currentMessageStreamedThinking = false;
       return;
     }
 
@@ -194,7 +243,11 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
 
   function handleStreamEvent(ev: Record<string, unknown>) {
     if (ev.type === 'message_start') {
+      // Clean up per-message role-marker guard from the previous message.
+      if (currentMessageId) roleGuards.delete(currentMessageId);
       currentMessageId = isRecord(ev.message) && typeof ev.message.id === 'string' ? ev.message.id : null;
+      currentMessageStreamedText = false;
+      currentMessageStreamedThinking = false;
       if (typeof ev.ttft_ms === 'number') {
         onEvent({ type: 'status', label: 'streaming', ttftMs: ev.ttft_ms });
       }
@@ -217,12 +270,14 @@ export function createClaudeStreamHandler(onEvent: EventSink) {
 
       if (delta.type === 'text_delta' && typeof delta.text === 'string') {
         if (currentMessageId) textStreamed.add(currentMessageId);
-        onEvent({ type: 'text_delta', delta: delta.text });
+        currentMessageStreamedText = true;
+        emitSafeText(currentMessageId, delta.text);
         return;
       }
       if (delta.type === 'thinking_delta' && typeof delta.thinking === 'string') {
-        if (currentMessageId) textStreamed.add(currentMessageId);
-        onEvent({ type: 'thinking_delta', delta: delta.thinking });
+        if (currentMessageId) thinkingStreamed.add(currentMessageId);
+        currentMessageStreamedThinking = true;
+        emitSafeText(currentMessageId, delta.thinking, 'thinking_delta');
         return;
       }
       if (delta.type === 'input_json_delta' && typeof delta.partial_json === 'string') {

apps/daemon/src/cli.ts

@@ -6,9 +6,13 @@ import { runArtifactsCli } from './artifacts-cli.js';
 import { runProjectHandoff } from './handoff-cli.js';
 import { runConnectorsToolCli } from './tools-connectors-cli.js';
 import { runDesignSystemsToolCli } from './tools-design-systems-cli.js';
+import { DESIGN_SYSTEMS_USAGE, isDesignSystemsHelpArg } from './design-systems-cli-help.js';
+import { parseDesignSystemRenameArgs } from './design-system-rename-args.js';
 import { runLiveArtifactsToolCli } from './tools-live-artifacts-cli.js';
 import { splitResearchSubcommand } from './research/cli-args.js';
 import { resolveDaemonUrl } from './daemon-url.js';
+import { requestJsonIpc } from '@open-design/sidecar';
+import { SIDECAR_ENV, SIDECAR_MESSAGES } from '@open-design/sidecar-proto';
 
 const argv = process.argv.slice(2);
 
@@ -148,6 +152,7 @@ const PROJECT_STRING_FLAGS = new Set([
   'daemon-url', 'name', 'skill', 'design-system', 'plugin', 'metadata-json',
   'pending-prompt', 'project', 'conversation', 'message', 'path', 'as',
   'agent', 'model', 'snapshot-id', 'inputs', 'grant-caps', 'editor',
+  'title', 'against',
 ]);
 const PROJECT_BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'follow']);
 // `od automation …` mirrors the Automations tab. Same surface, same
@@ -191,6 +196,8 @@ const RECOVERABLE_EXIT_CODES = {
   'plugin-requires-daemon':   71,
   'snapshot-stale':           72,
   'genui-surface-awaiting':   73,
+  'desktop-auth-pending':     74,
+  'desktop-import-token-rejected': 75,
 };
 const PLUGIN_LIST_FILTER_FLAGS = new Set([
   ...PLUGIN_STRING_FLAGS,
@@ -475,7 +482,8 @@ async function runMediaGenerate(rawArgs) {
 
   const daemonUrl = await cliDaemonUrl(flags);
   const projectId = flags.project || process.env.OD_PROJECT_ID;
-  if (!projectId) {
+  const token = process.env.OD_TOOL_TOKEN;
+  if (!projectId && !token) {
     console.error(
       'project id required. Pass --project <id> or set OD_PROJECT_ID. The daemon injects this when it spawns the code agent.',
     );
@@ -509,12 +517,17 @@ async function runMediaGenerate(rawArgs) {
   if (flags['prompt-influence'] != null) body.promptInfluence = Number(flags['prompt-influence']);
   if (flags.loop === true) body.loop = true;
 
-  const url = `${daemonUrl.replace(/\/$/, '')}/api/projects/${encodeURIComponent(projectId)}/media/generate`;
+  const url = token
+    ? `${daemonUrl.replace(/\/$/, '')}/api/tools/media/generate`
+    : `${daemonUrl.replace(/\/$/, '')}/api/projects/${encodeURIComponent(projectId)}/media/generate`;
   let resp;
   try {
     resp = await fetch(url, {
       method: 'POST',
-      headers: { 'content-type': 'application/json' },
+      headers: {
+        'content-type': 'application/json',
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+      },
       body: JSON.stringify(body),
     });
   } catch (err) {
@@ -560,11 +573,11 @@ async function runMediaWait(rawArgs) {
   const since = Number.isFinite(Number(flags.since))
     ? Number(flags.since)
     : 0;
-  await pollUntilDoneOrBudget(daemonUrl, taskId, since);
+  await pollUntilDoneOrBudget(daemonUrl, taskId, since, { totalBudgetMs: 120_000 });
 }
 
 async function pollUntilDoneOrBudget(daemonUrl, taskId, sinceStart, options = {}) {
-  const totalBudgetMs = 25_000;
+  const totalBudgetMs = typeof options.totalBudgetMs === 'number' ? options.totalBudgetMs : 25_000;
   const perCallTimeoutMs = 4_000;
   const stillRunningExitCode =
     typeof options.stillRunningExitCode === 'number'
@@ -746,6 +759,22 @@ function parseFlags(argv, opts = {}) {
   return out;
 }
 
+function positionalArgs(argv, stringFlags = new Set()) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a) continue;
+    if (!a.startsWith('--')) {
+      out.push(a);
+      continue;
+    }
+    const eq = a.indexOf('=');
+    const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+    if (eq < 0 && stringFlags.has(key)) i++;
+  }
+  return out;
+}
+
 async function cliDaemonUrl(flags) {
   return resolveDaemonUrl({ flagUrl: flags?.['daemon-url'] });
 }
@@ -785,7 +814,7 @@ Common options:
                             it, and forwards it to the upstream API.
   --daemon-url <url>
 
-Output: a single line of JSON: {"file": { name, size, kind, mime, ... }}.
+Output: a single line of JSON: {"file": { name, size, kind, mime, ... }}
 
 Skills should call this and then reference the returned filename in their
 artifact / message body. The daemon writes the bytes into the project's
@@ -882,21 +911,38 @@ function exitWithStructuredError({ code, message, data }) {
 async function structuredHttpFailure(resp, fallbackCode = 'daemon-not-running') {
   let parsed;
   try { parsed = await resp.json(); } catch { parsed = {}; }
-  const errCode = parsed?.error?.code;
+  const errCode = normalizeRecoverableErrorCode(parsed?.error?.code, parsed?.error?.message);
   if (errCode && errCode in RECOVERABLE_EXIT_CODES) {
     exitWithStructuredError({
       code:    errCode,
       message: parsed.error.message ?? `HTTP ${resp.status}`,
-      data:    parsed.error.data,
+      data:    structuredErrorData(parsed.error),
     });
   }
   exitWithStructuredError({
     code:    fallbackCode,
     message: parsed?.error?.message ?? `HTTP ${resp.status}: ${await resp.text().catch(() => '')}`,
-    data:    parsed?.error?.data,
+    data:    structuredErrorData(parsed?.error),
   });
 }
 
+function normalizeRecoverableErrorCode(code, message) {
+  if (code === 'DESKTOP_AUTH_PENDING') return 'desktop-auth-pending';
+  if (code === 'FORBIDDEN' && /desktop import token rejected/i.test(String(message ?? ''))) {
+    return 'desktop-import-token-rejected';
+  }
+  return code;
+}
+
+function structuredErrorData(error) {
+  if (!error || typeof error !== 'object') return undefined;
+  const data = {};
+  if ('data' in error && error.data !== undefined) Object.assign(data, error.data);
+  if ('details' in error && error.details !== undefined) data.details = error.details;
+  if (typeof error.retryable === 'boolean') data.retryable = error.retryable;
+  return Object.keys(data).length > 0 ? data : undefined;
+}
+
 async function runPlugin(args) {
   if (args.length === 0 || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
     printPluginHelp();
@@ -928,6 +974,7 @@ async function runPlugin(args) {
     case 'scaffold': return runPluginScaffold(rest);
     case 'validate': return runPluginValidate(rest);
     case 'pack':     return runPluginPack(rest);
+    case 'candidates': return runPluginCandidates(rest);
     case 'login':    return runPluginLogin(rest);
     case 'whoami':   return runPluginWhoami(rest);
     case 'export':   return runPluginExport(rest);
@@ -3016,6 +3063,85 @@ function coerceCliValue(raw) {
   return raw;
 }
 
+async function runPluginCandidates(rest) {
+  const sub = rest[0];
+  const args = rest.slice(1);
+  const flags = parseFlags(args, {
+    string: new Set(['daemon-url', 'project', 'action']),
+    boolean: new Set(['help', 'h', 'json', 'include-dismissed']),
+  });
+  if (!sub || flags.help || flags.h) {
+    console.log(`Usage:
+  od plugin candidates list --project <projectId> [--json] [--include-dismissed]
+  od plugin candidates draft <candidateId> --project <projectId> [--json]
+  od plugin candidates dismiss <candidateId> --project <projectId> [--json]
+
+Lists and formalizes persisted skill-to-plugin candidates.`);
+    process.exit(!sub ? 2 : 0);
+  }
+  const projectId = typeof flags.project === 'string' && flags.project.length > 0 ? flags.project : '';
+  if (!projectId) {
+    console.error('--project <projectId> is required');
+    process.exit(2);
+  }
+  const base = (await pluginDaemonUrl(flags)).replace(/\/$/, '');
+  if (sub === 'list') {
+    const qs = flags['include-dismissed'] ? '?includeDismissed=true' : '';
+    const resp = await fetch(`${base}/api/projects/${encodeURIComponent(projectId)}/plugin-candidates${qs}`);
+    const data = await resp.json().catch(() => null);
+    if (!resp.ok) {
+      console.error(`GET plugin candidates failed: ${resp.status} ${JSON.stringify(data)}`);
+      process.exit(1);
+    }
+    if (flags.json) return process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    const candidates = Array.isArray(data?.candidates) ? data.candidates : [];
+    if (candidates.length === 0) {
+      console.log('No plugin candidates.');
+      return;
+    }
+    for (const candidate of candidates) {
+      console.log(`${candidate.id}\t${candidate.status}\t${candidate.title}\t${candidate.draftPath ?? ''}`);
+    }
+    return;
+  }
+  const candidateId = args.find((a) => !a.startsWith('-') && a !== flags.project && a !== flags.action);
+  if (!candidateId) {
+    console.error(`candidate id is required for ${sub}`);
+    process.exit(2);
+  }
+  if (sub === 'draft') {
+    const resp = await fetch(`${base}/api/projects/${encodeURIComponent(projectId)}/plugin-candidates/${encodeURIComponent(candidateId)}/draft`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+    const data = await resp.json().catch(() => null);
+    if (flags.json) {
+      process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    } else if (resp.ok) {
+      console.log(`[candidate] draft: ${data.draftPath}`);
+      console.log(`[candidate] validation ok=${data.validation?.ok}`);
+    } else {
+      console.error(`[candidate] draft failed: ${data?.message ?? JSON.stringify(data)}`);
+    }
+    process.exit(resp.ok ? 0 : resp.status === 422 ? 4 : 1);
+  }
+  if (sub === 'dismiss') {
+    const resp = await fetch(`${base}/api/projects/${encodeURIComponent(projectId)}/plugin-candidates/${encodeURIComponent(candidateId)}/dismiss`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+    const data = await resp.json().catch(() => null);
+    if (flags.json) process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    else if (resp.ok) console.log(`[candidate] dismissed ${candidateId}`);
+    else console.error(`[candidate] dismiss failed: ${data?.message ?? JSON.stringify(data)}`);
+    process.exit(resp.ok ? 0 : 1);
+  }
+  console.error(`unknown subcommand: od plugin candidates ${sub}`);
+  process.exit(2);
+}
+
 // Phase 4 / spec §14.1 — `od plugin publish --to <catalog>`.
 //
 // Reads the installed plugin's manifest metadata (or the snapshot's
@@ -4152,6 +4278,8 @@ function printPluginHelp() {
                                           (manifest parse + atom + ref checks).
   od plugin pack <folder> [--out <path>]  Build a .tgz archive of a plugin
                                           folder for distribution.
+  od plugin candidates list --project <id>
+                                          List persisted skill-to-plugin candidates.
   od plugin publish-repo <folder>         Create/update the author's public
                                           GitHub repo for a plugin folder.
   od plugin open-design-pr <folder>       Push a community-catalog branch and
@@ -4200,6 +4328,7 @@ async function runProject(args) {
     console.log(`Usage:
   od project create [--name "<title>"] [--skill <id>] [--design-system <id>]
                     [--plugin <id>] [--inputs <json>] [--metadata-json <path|->]
+  od project import <baseDir> [--name "<title>"]
   od project list                         List projects.
   od project info <id>                    Print one project.
   od project delete <id>                  Delete a project.
@@ -4306,6 +4435,35 @@ Common options:
       console.log(`[project] created ${data.project?.id ?? id} (conversation ${data.conversationId})`);
       return;
     }
+    case 'import': {
+      const [baseDir] = positionalArgs(rest, PROJECT_STRING_FLAGS);
+      const importBaseDir = typeof baseDir === 'string' ? baseDir.trim() : '';
+      if (!importBaseDir) {
+        console.error('Usage: od project import <baseDir> [--name "<title>"]');
+        process.exit(2);
+      }
+      const body = { baseDir: importBaseDir };
+      if (typeof flags.name === 'string' && flags.name.length > 0) body.name = flags.name;
+      if (typeof flags.skill === 'string' && flags.skill.length > 0) body.skillId = flags.skill;
+      if (typeof flags['design-system'] === 'string' && flags['design-system'].length > 0) {
+        body.designSystemId = flags['design-system'];
+      }
+      const headers = { 'content-type': 'application/json' };
+      const importToken = await mintCliImportToken(importBaseDir);
+      if (importToken != null) {
+        headers['x-od-desktop-import-token'] = importToken;
+      }
+      const resp = await fetch(`${base}/api/import/folder`, {
+        method:  'POST',
+        headers,
+        body:    JSON.stringify(body),
+      });
+      if (!resp.ok) return structuredHttpFailure(resp);
+      const data = await resp.json();
+      if (flags.json) return process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+      console.log(`[project] imported ${data.project?.id ?? '-'} (conversation ${data.conversationId ?? '-'})`);
+      return;
+    }
     case 'delete': {
       const id = rest.find((a) => !a.startsWith('-'));
       if (!id) {
@@ -4532,6 +4690,8 @@ async function runFiles(args) {
   od files upload <projectId> <localpath> [--as <relpath>]
                                                Upload a local file.
   od files delete <projectId> <name>           Delete a project file.
+  od files diff   <projectId> <relpathA> [<relpathB> | --against -]
+                                               Print a unified diff.
 
 Common options:
   --daemon-url <url>   Open Design daemon HTTP base.
@@ -4644,15 +4804,178 @@ Common options:
       console.log(`[files] deleted ${name}`);
       return;
     }
+    case 'diff': {
+      const positional = positionalArgs(rest, PROJECT_STRING_FLAGS);
+      const [id, relA, relB] = positional;
+      const against = typeof flags.against === 'string' ? flags.against : null;
+      if (!id || !relA || (!relB && !against) || (relB && against)) {
+        console.error('Usage: od files diff <projectId> <relpathA> [<relpathB> | --against -]');
+        process.exit(2);
+      }
+      const left = await fetchProjectFileText(base, id, relA);
+      const rightLabel = against ?? relB;
+      const right = against === '-'
+        ? await readStdinUtf8()
+        : await fetchProjectFileText(base, id, rightLabel);
+      const diff = createUnifiedDiff(`a/${relA}`, `b/${rightLabel}`, left, right);
+      if (flags.json) return process.stdout.write(JSON.stringify({ diff }, null, 2) + '\n');
+      process.stdout.write(diff);
+      return;
+    }
     default:
       console.error(`unknown subcommand: od files ${sub}`);
       process.exit(2);
   }
 }
 
+function encodeProjectRelpath(rel) {
+  return String(rel).split('/').map(encodeURIComponent).join('/');
+}
+
+async function fetchProjectFileText(base, id, rel) {
+  const resp = await fetch(
+    `${base}/api/projects/${encodeURIComponent(id)}/files/${encodeProjectRelpath(rel)}`,
+  );
+  if (!resp.ok) return structuredHttpFailure(resp, 'project-not-found');
+  const buf = Buffer.from(await resp.arrayBuffer());
+  return buf.toString('utf8');
+}
+
+async function readStdinUtf8() {
+  const fs = await import('node:fs');
+  return fs.readFileSync(0, 'utf8');
+}
+
+async function mintCliImportToken(baseDir) {
+  const socketPath = process.env[SIDECAR_ENV.IPC_PATH];
+  if (typeof socketPath !== 'string' || socketPath.length === 0) return null;
+  let result;
+  try {
+    result = await requestJsonIpc(
+      socketPath,
+      { type: SIDECAR_MESSAGES.MINT_IMPORT_TOKEN, input: { baseDir } },
+      { timeoutMs: 800 },
+    );
+  } catch {
+    return null;
+  }
+  if (result?.ok === true && typeof result.token === 'string' && result.token.length > 0) {
+    return result.token;
+  }
+  if (result?.ok === false && result.code === 'DESKTOP_AUTH_PENDING') {
+    exitWithStructuredError({
+      code: 'desktop-auth-pending',
+      message: result.message ?? 'desktop auth required but secret not yet registered',
+      data: { retryable: result.retryable === true },
+    });
+  }
+  return null;
+}
+
+function createUnifiedDiff(leftLabel, rightLabel, leftText, rightText) {
+  if (leftText === rightText) return '';
+  const leftLines = splitDiffLines(leftText);
+  const rightLines = splitDiffLines(rightText);
+  let prefix = 0;
+  while (
+    prefix < leftLines.length
+    && prefix < rightLines.length
+    && leftLines[prefix] === rightLines[prefix]
+  ) {
+    prefix++;
+  }
+  let leftEnd = leftLines.length;
+  let rightEnd = rightLines.length;
+  while (
+    leftEnd > prefix
+    && rightEnd > prefix
+    && leftLines[leftEnd - 1] === rightLines[rightEnd - 1]
+  ) {
+    leftEnd--;
+    rightEnd--;
+  }
+  const oldMid = leftLines.slice(prefix, leftEnd);
+  const newMid = rightLines.slice(prefix, rightEnd);
+  const body = diffLineBody(oldMid, newMid);
+  if (body.length === 0) {
+    body.push(...oldMid.map((line) => diffLine('-', line)), ...newMid.map((line) => diffLine('+', line)));
+  }
+  const oldStart = oldMid.length === 0 ? prefix : prefix + 1;
+  const newStart = newMid.length === 0 ? prefix : prefix + 1;
+  return [
+    `--- ${leftLabel}`,
+    `+++ ${rightLabel}`,
+    `@@ -${formatDiffRange(oldStart, oldMid.length)} +${formatDiffRange(newStart, newMid.length)} @@`,
+    ...body,
+  ].join('\n') + '\n';
+}
+
+function splitDiffLines(text) {
+  const value = String(text);
+  if (value.length === 0) return [];
+  return value.match(/.*?(?:\r\n|\n|\r|$)/gs).filter((line) => line.length > 0);
+}
+
+function formatDiffRange(start, length) {
+  return length === 1 ? String(start) : `${start},${length}`;
+}
+
+function diffLineBody(oldLines, newLines) {
+  if (oldLines.length === 0) return newLines.map((line) => diffLine('+', line));
+  if (newLines.length === 0) return oldLines.map((line) => diffLine('-', line));
+  if (oldLines.length * newLines.length > 1_000_000) {
+    return [...oldLines.map((line) => diffLine('-', line)), ...newLines.map((line) => diffLine('+', line))];
+  }
+  const width = newLines.length + 1;
+  const lcs = Array.from(
+    { length: oldLines.length + 1 },
+    () => new Uint32Array(width),
+  );
+  for (let i = oldLines.length - 1; i >= 0; i--) {
+    for (let j = newLines.length - 1; j >= 0; j--) {
+      lcs[i][j] = oldLines[i] === newLines[j]
+        ? lcs[i + 1][j + 1] + 1
+        : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < oldLines.length && j < newLines.length) {
+    if (oldLines[i] === newLines[j]) {
+      out.push(diffLine(' ', oldLines[i]));
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      out.push(diffLine('-', oldLines[i]));
+      i++;
+    } else {
+      out.push(diffLine('+', newLines[j]));
+      j++;
+    }
+  }
+  while (i < oldLines.length) out.push(diffLine('-', oldLines[i++]));
+  while (j < newLines.length) out.push(diffLine('+', newLines[j++]));
+  return out;
+}
+
+function diffLine(prefix, line) {
+  const value = String(line);
+  if (value.endsWith('\r\n')) return `${prefix}${renderDiffLineContent(value.slice(0, -1))}`;
+  if (value.endsWith('\n')) return `${prefix}${renderDiffLineContent(value.slice(0, -1))}`;
+  if (value.endsWith('\r')) return `${prefix}${renderDiffLineContent(value)}`;
+  return `${prefix}${renderDiffLineContent(value)}\n\\ No newline at end of file`;
+}
+
+function renderDiffLineContent(value) {
+  return String(value).replace(/\r/g, '\\r');
+}
+
 async function runConversation(args) {
   if (args.length === 0 || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
     console.log(`Usage:
+  od conversation new  <projectId> [--title "<title>"]
+                                           Create a conversation in a project.
   od conversation list <projectId>           List conversations in a project.
   od conversation info <conversationId>      Print one conversation.
 
@@ -4666,6 +4989,25 @@ Common options:
   const flags = parseFlags(rest, { string: PROJECT_STRING_FLAGS, boolean: PROJECT_BOOLEAN_FLAGS });
   const base = (await projectDaemonUrl(flags)).replace(/\/$/, '');
   switch (sub) {
+    case 'new': {
+      const [id] = positionalArgs(rest, PROJECT_STRING_FLAGS);
+      if (!id) {
+        console.error('Usage: od conversation new <projectId> [--title "<title>"]');
+        process.exit(2);
+      }
+      const body = {};
+      if (typeof flags.title === 'string') body.title = flags.title;
+      const resp = await fetch(`${base}/api/projects/${encodeURIComponent(id)}/conversations`, {
+        method:  'POST',
+        headers: { 'content-type': 'application/json' },
+        body:    JSON.stringify(body),
+      });
+      if (!resp.ok) return structuredHttpFailure(resp, 'project-not-found');
+      const data = await resp.json();
+      if (flags.json) return process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+      console.log(`[conversation] created ${data.conversation?.id ?? '-'}`);
+      return;
+    }
     case 'list': {
       const id = rest.find((a) => !a.startsWith('-'));
       if (!id) {
@@ -5067,9 +5409,53 @@ async function runLibraryList(name, args) {
 }
 
 async function runSkills(args)        { return runLibraryList('skills', args); }
-async function runDesignSystems(args) { return runLibraryList('design-systems', args); }
 async function runCraft(args)         { return runLibraryList('craft', args); }
 
+async function runDesignSystems(args) {
+  if (args[0] === 'rename') return runDesignSystemRename(args.slice(1));
+  if (!args[0] || isDesignSystemsHelpArg(args[0])) {
+    console.log(DESIGN_SYSTEMS_USAGE);
+    process.exit(isDesignSystemsHelpArg(args[0]) ? 0 : 2);
+  }
+  return runLibraryList('design-systems', args);
+}
+
+// od design-systems rename <id> --title <new-title> [--json]
+// Renames an editable (user-created) design system via PATCH
+// /api/design-systems/:id. Built-in systems are read-only and the daemon
+// returns 404, surfaced here as a structured failure. Arg parsing lives in
+// design-system-rename-args.ts so it can be unit-tested.
+async function runDesignSystemRename(args) {
+  if (args.length === 0 || args[0] === 'help' || args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage:
+  od design-systems rename <id> --title <new-title> [--json] [--daemon-url <url>]
+  od design-systems rename <id> "<new title>" [--json]
+
+Renames an editable (user-created) design system. Built-in systems are read-only.`);
+    process.exit(args.length === 0 ? 2 : 0);
+  }
+  const parsed = parseDesignSystemRenameArgs(args);
+  if (!parsed) {
+    console.error('Usage: od design-systems rename <id> --title <new-title>');
+    process.exit(2);
+  }
+  const flags = parseFlags(args, {
+    string: new Set([...LIBRARY_STRING_FLAGS, 'title']),
+    boolean: LIBRARY_BOOLEAN_FLAGS,
+  });
+  const base = (await libraryDaemonUrl(flags)).replace(/\/$/, '');
+  const resp = await fetch(`${base}/api/design-systems/${encodeURIComponent(parsed.id)}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ title: parsed.title }),
+  });
+  if (!resp.ok) return structuredHttpFailure(resp);
+  const data = await resp.json();
+  if (flags.json) return process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+  const renamed = data.designSystem ?? data;
+  console.log(`Renamed ${parsed.id} -> ${renamed.title ?? parsed.title}`);
+}
+
 async function runStatus(args) {
   // Alias of `od daemon status`.
   return runDaemon(['status', ...args]);

apps/daemon/src/codex-cli.ts

@@ -0,0 +1,121 @@
+// Thin wrapper over `codex mcp add|remove|get` so the Settings panel can
+// offer a one-click "Install to Codex" toggle instead of asking the user
+// to paste TOML into ~/.codex/config.toml. We shell out to the bundled
+// Codex CLI rather than rewriting config.toml ourselves so we inherit
+// Codex's own merge / dedupe / validation rules.
+//
+// CodexRunner is injected so tests can stub spawn without poking the
+// global child_process module; production uses defaultCodexRunner which
+// is a thin spawn() wrapper with a 30s timeout.
+
+import { spawn } from 'node:child_process';
+
+export interface CodexRunnerResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CodexRunner {
+  run(args: string[], opts?: { env?: Record<string, string> }): Promise<CodexRunnerResult>;
+}
+
+const defaultCodexRunner: CodexRunner = {
+  run(args, opts) {
+    return new Promise<CodexRunnerResult>((resolve, reject) => {
+      const child = spawn('codex', args, {
+        env: { ...process.env, ...(opts?.env ?? {}) },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+      let stdout = '';
+      let stderr = '';
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        reject(new Error('codex CLI timed out after 30s'));
+      }, 30_000);
+      child.stdout?.on('data', (d) => {
+        stdout += String(d);
+      });
+      child.stderr?.on('data', (d) => {
+        stderr += String(d);
+      });
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        resolve({ exitCode: code ?? -1, stdout, stderr });
+      });
+    });
+  },
+};
+
+let _runner: CodexRunner | null = null;
+
+// Tests inject a stub runner; production callers use the default. Pass
+// null to restore the default (called from afterEach in test suites).
+export function setCodexRunner(runner: CodexRunner | null): void {
+  _runner = runner;
+}
+
+function activeRunner(): CodexRunner {
+  return _runner ?? defaultCodexRunner;
+}
+
+export interface CodexInstallStatus {
+  // True when the `codex` CLI was found and is runnable. False = the
+  // user does not have Codex CLI on PATH (the UI should show the
+  // one-click button as disabled with an explanatory tooltip).
+  available: boolean;
+  // True when an MCP server with `name` is already registered in
+  // ~/.codex/config.toml. Drives the toggle's "install" vs "uninstall"
+  // label.
+  installed: boolean;
+}
+
+export async function probeCodexInstall(name: string): Promise<CodexInstallStatus> {
+  try {
+    const result = await activeRunner().run(['mcp', 'get', name]);
+    return { available: true, installed: result.exitCode === 0 };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code;
+    if (code === 'ENOENT') {
+      return { available: false, installed: false };
+    }
+    throw err;
+  }
+}
+
+export interface CodexInstallSpec {
+  // MCP server name as it will appear in ~/.codex/config.toml. We
+  // hard-code "open-design" at the route layer but keep the parameter
+  // explicit so the helper can later be reused for other server names.
+  name: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export async function installCodexMcp(spec: CodexInstallSpec): Promise<void> {
+  const argv: string[] = ['mcp', 'add', spec.name];
+  for (const [key, value] of Object.entries(spec.env)) {
+    argv.push('--env', `${key}=${value}`);
+  }
+  argv.push('--', spec.command, ...spec.args);
+  const result = await activeRunner().run(argv);
+  if (result.exitCode !== 0) {
+    throw new Error(`codex mcp add failed: ${failureDetail(result)}`);
+  }
+}
+
+export async function uninstallCodexMcp(name: string): Promise<void> {
+  const result = await activeRunner().run(['mcp', 'remove', name]);
+  if (result.exitCode !== 0) {
+    throw new Error(`codex mcp remove failed: ${failureDetail(result)}`);
+  }
+}
+
+function failureDetail(result: CodexRunnerResult): string {
+  return result.stderr.trim() || result.stdout.trim() || `exit ${result.exitCode}`;
+}

apps/daemon/src/connectionTest.ts

@@ -21,13 +21,19 @@ import { promises as dnsPromises } from 'node:dns';
 import { promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { Agent, EnvHttpProxyAgent, Socks5ProxyAgent } from 'undici';
+import type { Dispatcher, Pool } from 'undici';
 import {
   applyAgentLaunchEnv,
   getAgentDef,
   resolveAgentLaunch,
   spawnEnvForAgent,
 } from './agents.js';
-import { createCommandInvocation } from '@open-design/platform';
+import {
+  createCommandInvocation,
+  mergeProxyAwareEnv,
+  resolveSystemProxyEnv,
+} from '@open-design/platform';
 import { attachAcpSession } from './acp.js';
 import { attachPiRpcSession } from './pi-rpc.js';
 import { createClaudeStreamHandler } from './claude-stream.js';
@@ -40,20 +46,30 @@ import {
   cursorAuthGuidance,
   probeAgentAuthStatus,
 } from './runtimes/auth.js';
+import {
+  buildLegacyMaxTokensParam,
+  buildMaxCompletionTokensParam,
+  buildOpenAIChatTokenParam,
+  isUnsupportedMaxTokensError,
+} from './openai-chat-token-params.js';
 import type { AgentCliEnvPrefs } from './app-config.js';
 import type { RuntimeAgentDef } from './runtimes/types.js';
+import { resolveModelForAgent } from './runtimes/models.js';
 import {
   isBlockedExternalApiHostname,
   isLoopbackApiHost,
   validateBaseUrl,
   type AgentTestRequest,
   type BaseUrlValidationResult,
+  type ConnectionTestDiagnostics,
   type ConnectionTestKind,
+  type ConnectionTestPhase,
   type ConnectionTestProtocol,
   type ConnectionTestResponse,
   type ParsedBaseUrl,
   type ProviderTestRequest,
 } from '@open-design/contracts/api/connectionTest';
+import { googleGenerateContentUrl } from './google-models.js';
 
 export { validateBaseUrl } from '@open-design/contracts/api/connectionTest';
 
@@ -158,6 +174,7 @@ export async function assertExternalAssetUrl(
 // Override with OD_CONNECTION_TEST_PROVIDER_TIMEOUT_MS for slow networks
 // or distant providers; invalid values fall back to the default.
 const DEFAULT_PROVIDER_TIMEOUT_MS = 12_000;
+const LOOPBACK_NO_PROXY_TOKENS = ['localhost', '127.0.0.1', '[::1]'] as const;
 // CLI boot time is dominated by adapter auth/session restore; the heavy
 // adapters (Codex, Cursor Agent) regularly take 5–10 s on a cold first
 // run, so 45 s leaves headroom without making a hung child invisible.
@@ -201,6 +218,336 @@ function agentTimeoutMs(): number {
     DEFAULT_AGENT_TIMEOUT_MS,
   );
 }
+
+export function mergeNoProxyWithLoopbackDefaults(noProxy: string | undefined): string | null {
+  if (noProxy?.split(/[\s,]+/).some((token) => token.trim() === '*')) return '*';
+  const seen = new Set<string>();
+  const values: string[] = [];
+  for (const rawToken of [
+    ...(noProxy ? noProxy.split(/[\s,]+/) : []),
+    ...LOOPBACK_NO_PROXY_TOKENS,
+  ]) {
+    const token = rawToken.trim() === '::1' ? '[::1]' : rawToken.trim();
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    values.push(token);
+  }
+  return values.length > 0 ? values.join(',') : null;
+}
+
+function defaultPortForProtocol(protocol: string): string {
+  if (protocol === 'http:') return '80';
+  if (protocol === 'https:') return '443';
+  return '';
+}
+
+function splitNoProxyHostAndPort(token: string): { host: string; port: string } {
+  const trimmed = token.trim();
+  if (!trimmed) return { host: '', port: '' };
+  if (trimmed.startsWith('[')) {
+    const closingBracket = trimmed.indexOf(']');
+    if (closingBracket === -1) return { host: trimmed.toLowerCase(), port: '' };
+    const host = trimmed.slice(0, closingBracket + 1).toLowerCase();
+    const port = trimmed.slice(closingBracket + 1).replace(/^:/, '');
+    return { host, port };
+  }
+  const firstColon = trimmed.indexOf(':');
+  const lastColon = trimmed.lastIndexOf(':');
+  if (firstColon !== -1 && firstColon === lastColon) {
+    return {
+      host: trimmed.slice(0, firstColon).toLowerCase(),
+      port: trimmed.slice(firstColon + 1),
+    };
+  }
+  return { host: trimmed.toLowerCase(), port: '' };
+}
+
+function noProxyTokenMatchesUrl(token: string, url: URL): boolean {
+  const trimmed = token.trim();
+  if (!trimmed) return false;
+  if (trimmed === '*') return true;
+  if (trimmed === '<local>') return !url.hostname.includes('.') && !url.hostname.includes(':');
+  const { host, port } = splitNoProxyHostAndPort(trimmed.replace(/^\*\./, '.'));
+  if (!host) return false;
+  const normalizedHost = host === '::1' ? '[::1]' : host;
+  const hostname = url.hostname.toLowerCase();
+  const matchesHost = normalizedHost.startsWith('.')
+    ? hostname === normalizedHost.slice(1) || hostname.endsWith(normalizedHost)
+    : hostname === normalizedHost || hostname.endsWith(`.${normalizedHost}`);
+  if (!matchesHost) return false;
+  if (!port) return true;
+  return (url.port || defaultPortForProtocol(url.protocol)) === port;
+}
+
+function shouldBypassProxyForUrl(target: string | URL, noProxy: string | null): boolean {
+  if (!noProxy) return false;
+  let url: URL;
+  try {
+    url = target instanceof URL ? target : new URL(target);
+  } catch {
+    return false;
+  }
+  return noProxy.split(/[\s,]+/).some((token) => noProxyTokenMatchesUrl(token, url));
+}
+
+function socksProxyAgentOptions(
+  options: Pool.Options,
+): ConstructorParameters<typeof Socks5ProxyAgent>[1] {
+  return {
+    ...(options.bodyTimeout === undefined ? {} : { bodyTimeout: options.bodyTimeout }),
+    ...(options.headersTimeout === undefined ? {} : { headersTimeout: options.headersTimeout }),
+  };
+}
+
+class NoProxyAwareSocksProxyAgent {
+  private readonly directAgent: Agent;
+
+  private readonly socksAgent: Socks5ProxyAgent;
+
+  private readonly socksDispatchTimeouts: Pick<Dispatcher.DispatchOptions, 'bodyTimeout' | 'headersTimeout'>;
+
+  constructor(
+    private readonly noProxy: string | null,
+    socksProxy: string,
+    options: Pool.Options,
+  ) {
+    this.directAgent = new Agent(options as ConstructorParameters<typeof Agent>[0]);
+    this.socksAgent = new Socks5ProxyAgent(socksProxy, socksProxyAgentOptions(options));
+    this.socksDispatchTimeouts = {
+      ...(options.bodyTimeout === undefined ? {} : { bodyTimeout: options.bodyTimeout }),
+      ...(options.headersTimeout === undefined
+        ? {}
+        : { headersTimeout: options.headersTimeout }),
+    };
+  }
+
+  dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
+    const origin = options.origin;
+    const targetUrl =
+      typeof origin === 'string' || origin instanceof URL
+        ? new URL(options.path, origin)
+        : null;
+    const dispatcher =
+      targetUrl && shouldBypassProxyForUrl(targetUrl, this.noProxy)
+        ? this.directAgent
+        : this.socksAgent;
+    return dispatcher.dispatch(
+      dispatcher === this.socksAgent ? { ...this.socksDispatchTimeouts, ...options } : options,
+      handler,
+    );
+  }
+
+  async close(): Promise<void> {
+    await Promise.all([this.directAgent.close(), this.socksAgent.close()]);
+  }
+
+  async destroy(error?: Error | null): Promise<void> {
+    await Promise.all([
+      this.directAgent.destroy(error ?? null),
+      this.socksAgent.destroy(error ?? null),
+    ]);
+  }
+}
+
+class NoProxyAwareEnvProxyAgent {
+  private readonly directAgent: Agent;
+
+  constructor(
+    private readonly noProxy: string,
+    private readonly proxyAgent: EnvHttpProxyAgent,
+    options: Pool.Options,
+  ) {
+    this.directAgent = new Agent(options as ConstructorParameters<typeof Agent>[0]);
+  }
+
+  dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
+    const origin = options.origin;
+    const targetUrl =
+      typeof origin === 'string' || origin instanceof URL
+        ? new URL(options.path, origin)
+        : null;
+    return (targetUrl && shouldBypassProxyForUrl(targetUrl, this.noProxy) ? this.directAgent : this.proxyAgent).dispatch(
+      options,
+      handler,
+    );
+  }
+
+  async close(): Promise<void> {
+    await Promise.all([this.directAgent.close(), this.proxyAgent.close()]);
+  }
+
+  async destroy(error?: Error | null): Promise<void> {
+    await Promise.all([
+      this.directAgent.destroy(error ?? null),
+      this.proxyAgent.destroy(error ?? null),
+    ]);
+  }
+}
+
+class NoProxyAwareMixedProxyAgent {
+  private readonly directAgent: Agent;
+
+  private readonly proxyAgent: EnvHttpProxyAgent;
+
+  private readonly socksAgent: Socks5ProxyAgent;
+
+  private readonly socksDispatchTimeouts: Pick<Dispatcher.DispatchOptions, 'bodyTimeout' | 'headersTimeout'>;
+
+  constructor(
+    private readonly noProxy: string | null,
+    private readonly hasHttpProxy: boolean,
+    private readonly hasHttpsProxy: boolean,
+    proxyOptions: ConstructorParameters<typeof EnvHttpProxyAgent>[0],
+    socksProxy: string,
+    options: Pool.Options,
+  ) {
+    this.directAgent = new Agent(options as ConstructorParameters<typeof Agent>[0]);
+    this.proxyAgent = new EnvHttpProxyAgent(proxyOptions);
+    this.socksAgent = new Socks5ProxyAgent(socksProxy, socksProxyAgentOptions(options));
+    this.socksDispatchTimeouts = {
+      ...(options.bodyTimeout === undefined ? {} : { bodyTimeout: options.bodyTimeout }),
+      ...(options.headersTimeout === undefined
+        ? {}
+        : { headersTimeout: options.headersTimeout }),
+    };
+  }
+
+  dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
+    const origin = options.origin;
+    const targetUrl =
+      typeof origin === 'string' || origin instanceof URL
+        ? new URL(options.path, origin)
+        : null;
+    if (targetUrl && shouldBypassProxyForUrl(targetUrl, this.noProxy)) {
+      return this.directAgent.dispatch(options, handler);
+    }
+    if (
+      targetUrl && ((targetUrl.protocol === 'http:' && this.hasHttpProxy) ||
+        (targetUrl.protocol === 'https:' && this.hasHttpsProxy))
+    ) {
+      return this.proxyAgent.dispatch(options, handler);
+    }
+    return this.socksAgent.dispatch({ ...this.socksDispatchTimeouts, ...options }, handler);
+  }
+
+  async close(): Promise<void> {
+    await Promise.all([this.directAgent.close(), this.proxyAgent.close(), this.socksAgent.close()]);
+  }
+
+  async destroy(error?: Error | null): Promise<void> {
+    await Promise.all([
+      this.directAgent.destroy(error ?? null),
+      this.proxyAgent.destroy(error ?? null),
+      this.socksAgent.destroy(error ?? null),
+    ]);
+  }
+}
+
+type ConnectionTestProxyDispatcher =
+  | EnvHttpProxyAgent
+  | NoProxyAwareEnvProxyAgent
+  | NoProxyAwareMixedProxyAgent
+  | NoProxyAwareSocksProxyAgent;
+
+function envProxyAgentOptions(
+  options: Pool.Options,
+  httpProxy: string | undefined,
+  httpsProxy: string | undefined,
+  noProxy: string | null,
+): ConstructorParameters<typeof EnvHttpProxyAgent>[0] {
+  return {
+    ...options,
+    ...(httpProxy ? { httpProxy } : {}),
+    ...(httpsProxy ? { httpsProxy } : {}),
+    ...(noProxy ? { noProxy } : {}),
+  };
+}
+
+function buildConnectionTestProxyDispatcher(
+  env: NodeJS.ProcessEnv = process.env,
+  options: Pool.Options = {},
+): ConnectionTestProxyDispatcher | null {
+  const proxyEnv = mergeProxyAwareEnv(
+    process.platform,
+    resolveSystemProxyEnv(),
+    env,
+  );
+  const allProxy = proxyEnv.ALL_PROXY ?? proxyEnv.all_proxy;
+  const socksProxy = socksProxyUrl(allProxy);
+  const httpProxyFromAll = isHttpOrHttpsProxy(allProxy);
+  const httpProxy = proxyEnv.HTTP_PROXY ?? proxyEnv.http_proxy ?? httpProxyFromAll;
+  const httpsProxy = proxyEnv.HTTPS_PROXY ?? proxyEnv.https_proxy ?? httpProxyFromAll;
+  const noProxy = mergeNoProxyWithLoopbackDefaults(proxyEnv.NO_PROXY ?? proxyEnv.no_proxy);
+  const proxyOptions = envProxyAgentOptions(options, httpProxy, httpsProxy, noProxy);
+  if (socksProxy && (httpProxy || httpsProxy) && (!httpProxy || !httpsProxy)) {
+    return new NoProxyAwareMixedProxyAgent(
+      noProxy,
+      Boolean(httpProxy),
+      Boolean(httpsProxy),
+      proxyOptions,
+      socksProxy,
+      options,
+    );
+  }
+  if (!httpProxy && !httpsProxy && socksProxy) {
+    return new NoProxyAwareSocksProxyAgent(noProxy, socksProxy, options);
+  }
+  if (!httpProxy && !httpsProxy) return null;
+  const proxyAgent = new EnvHttpProxyAgent(proxyOptions);
+  return noProxy?.split(/[\s,]+/).some((token) => token.trim() === '<local>')
+    ? new NoProxyAwareEnvProxyAgent(noProxy, proxyAgent, options)
+    : proxyAgent;
+}
+
+function isHttpOrHttpsProxy(proxyUrl: string | undefined): string | undefined {
+  const trimmed = proxyUrl?.trim();
+  if (!trimmed) return undefined;
+  try {
+    const { protocol } = new URL(trimmed);
+    return protocol === 'http:' || protocol === 'https:' ? trimmed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function socksProxyUrl(proxyUrl: string | undefined): string | undefined {
+  const trimmed = proxyUrl?.trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol === 'socks:' || url.protocol === 'socks5:') return trimmed;
+    if (url.protocol === 'socks5h:') {
+      url.protocol = 'socks5:';
+      return url.toString();
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function proxyDispatcherRequestInit(
+  env: NodeJS.ProcessEnv = process.env,
+  options: Pool.Options = {},
+): {
+  close(): Promise<void>;
+  requestInit: Pick<RequestInit, 'dispatcher'>;
+} {
+  const dispatcher = buildConnectionTestProxyDispatcher(env, options);
+  if (dispatcher == null) {
+    return {
+      async close() {},
+      requestInit: {},
+    };
+  }
+  return {
+    close: () => dispatcher.close(),
+    requestInit: {
+      dispatcher: dispatcher as unknown as NonNullable<RequestInit['dispatcher']>,
+    },
+  };
+}
+
 const AGENT_COMPLETION_DEBOUNCE_MS = 500;
 const AGENT_KILL_GRACE_MS = 2_000;
 // Truncates the assistant reply we surface in the success copy so a
@@ -469,6 +816,7 @@ async function validateLocalOpenAiModel(
   parsed: ParsedBaseUrl,
   signal: AbortSignal,
   start: number,
+  requestInit: Pick<RequestInit, 'dispatcher'> = {},
 ): Promise<ConnectionTestResponse | null> {
   if (input.protocol !== 'openai' || !isLoopbackApiHost(parsed.hostname)) {
     return null;
@@ -478,6 +826,7 @@ async function validateLocalOpenAiModel(
   let response: Response;
   try {
     response = await fetch(url, {
+      ...requestInit,
       method: 'GET',
       headers: { authorization: `Bearer ${String(input.apiKey)}` },
       signal,
@@ -510,11 +859,124 @@ async function validateLocalOpenAiModel(
   };
 }
 
+function isSenseAudioNonChatModel(model: string): boolean {
+  return (
+    model.startsWith('senseaudio-image-') ||
+    model.startsWith('doubao-seedream-') ||
+    model === 'sensenova-u1-fast' ||
+    model.startsWith('doubao-seedance-') ||
+    model.startsWith('senseaudio-asr-') ||
+    model.startsWith('senseaudio-tts-') ||
+    model.startsWith('senseaudio-music-')
+  );
+}
+
+async function validateSenseAudioNonChatModel(
+  input: ProviderTestRequest,
+  signal: AbortSignal,
+  start: number,
+  requestInit: Pick<RequestInit, 'dispatcher'> = {},
+): Promise<ConnectionTestResponse | null> {
+  if (input.protocol !== 'senseaudio' || !isSenseAudioNonChatModel(input.model)) {
+    return null;
+  }
+
+  const url = appendVersionedApiPath(String(input.baseUrl), '/models');
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      ...requestInit,
+      method: 'GET',
+      headers: { authorization: `Bearer ${String(input.apiKey)}` },
+      signal,
+      redirect: 'error',
+    });
+  } catch (err) {
+    const latencyMs = Date.now() - start;
+    const kind = networkErrorToKind(err);
+    return {
+      ok: false,
+      kind,
+      latencyMs,
+      model: input.model,
+      detail: redactSecrets(err instanceof Error ? err.message : String(err), [
+        input.apiKey,
+      ]),
+    };
+  }
+
+  const latencyMs = Date.now() - start;
+  let rawText = '';
+  let data: unknown = {};
+  let parseError: unknown = null;
+  try {
+    rawText = await response.text();
+  } catch {
+    rawText = '';
+  }
+  try {
+    data = rawText ? JSON.parse(rawText) : {};
+  } catch (err) {
+    parseError = err;
+  }
+
+  if (parseError && response.ok) {
+    return {
+      ok: false,
+      kind: 'unknown',
+      latencyMs,
+      model: input.model,
+      status: response.status,
+      detail: redactSecrets(
+        parseError instanceof Error ? parseError.message : String(parseError),
+        [input.apiKey],
+      ),
+    };
+  }
+
+  if (!response.ok) {
+    const redactedDetail = redactSecrets(
+      extractProviderErrorDetail(data, rawText).slice(0, 240),
+      [input.apiKey],
+    );
+    return {
+      ok: false,
+      kind: statusToKind(response.status, redactedDetail),
+      latencyMs,
+      model: input.model,
+      status: response.status,
+      detail: redactedDetail,
+    };
+  }
+
+  const modelIds = extractOpenAiModelIds(data);
+  if (!modelIds.includes(input.model)) {
+    return {
+      ok: false,
+      kind: 'not_found_model',
+      latencyMs,
+      model: input.model,
+      status: response.status,
+      detail: `Model "${input.model}" is not reported by SenseAudio /models.`,
+    };
+  }
+
+  return {
+    ok: true,
+    kind: 'success',
+    latencyMs,
+    model: input.model,
+    status: response.status,
+    detail: 'SenseAudio model is available, but this media model is not chat-testable from Settings.',
+  };
+}
+
 interface ProviderCallShape {
   url: string;
   headers: Record<string, string>;
   body: unknown;
   extractText: (data: unknown) => string;
+  retryBodyOnUnsupportedMaxTokens?: unknown;
 }
 
 function buildProviderCall(input: ProviderTestRequest): ProviderCallShape {
@@ -567,7 +1029,7 @@ function buildProviderCall(input: ProviderTestRequest): ProviderCallShape {
         },
         body: {
           model,
-          max_tokens: PROVIDER_MAX_TOKENS,
+          ...buildOpenAIChatTokenParam(model, PROVIDER_MAX_TOKENS),
           messages: [{ role: 'user', content: SMOKE_PROMPT }],
           stream: false,
         },
@@ -600,17 +1062,22 @@ function buildProviderCall(input: ProviderTestRequest): ProviderCallShape {
         },
         body: {
           ...(usesVersionedOpenAIPath ? { model } : {}),
-          max_tokens: PROVIDER_MAX_TOKENS,
+          ...buildLegacyMaxTokensParam(PROVIDER_MAX_TOKENS),
           messages: [{ role: 'user', content: SMOKE_PROMPT }],
           stream: false,
         },
+        retryBodyOnUnsupportedMaxTokens: {
+          ...(usesVersionedOpenAIPath ? { model } : {}),
+          messages: [{ role: 'user', content: SMOKE_PROMPT }],
+          stream: false,
+          ...buildMaxCompletionTokensParam(PROVIDER_MAX_TOKENS),
+        },
         extractText: extractOpenAIMessageText,
       };
     }
     case 'google': {
-      const trimmedBase = baseUrl.replace(/\/+$/, '');
       return {
-        url: `${trimmedBase}/v1beta/models/${encodeURIComponent(model)}:generateContent`,
+        url: googleGenerateContentUrl(baseUrl, model),
         headers: {
           'content-type': 'application/json',
           'x-goog-api-key': apiKey,
@@ -716,24 +1183,81 @@ export async function testProviderConnection(
     input.signal?.addEventListener('abort', abortFromParent, { once: true });
   }
   const timer = setTimeout(() => controller.abort(), providerTimeoutMs());
+  let proxyDispatcher: ReturnType<typeof proxyDispatcherRequestInit> | null = null;
 
   try {
+    proxyDispatcher = proxyDispatcherRequestInit();
     const modelError = await validateLocalOpenAiModel(
       input,
       validated.parsed,
       controller.signal,
       start,
+      proxyDispatcher.requestInit,
     );
     if (modelError) return modelError;
 
-    const response = await fetch(call.url, {
+    const senseAudioNonChatResult = await validateSenseAudioNonChatModel(
+      input,
+      controller.signal,
+      start,
+      proxyDispatcher.requestInit,
+    );
+    if (senseAudioNonChatResult) return senseAudioNonChatResult;
+
+    const requestInit = {
+      ...proxyDispatcher.requestInit,
       method: 'POST',
       headers: call.headers,
-      body: JSON.stringify(call.body),
       signal: controller.signal,
-      redirect: 'error',
+      redirect: 'error' as const,
+    };
+    let response = await fetch(call.url, {
+      ...requestInit,
+      body: JSON.stringify(call.body),
     });
-    const latencyMs = Date.now() - start;
+    let latencyMs = Date.now() - start;
+    if (
+      !response.ok &&
+      call.retryBodyOnUnsupportedMaxTokens !== undefined
+    ) {
+      let detailText = '';
+      try {
+        detailText = await response.text();
+      } catch {
+        detailText = '';
+      }
+      if (response.status === 400 && isUnsupportedMaxTokensError(detailText)) {
+        console.warn(
+          `[test:provider] ${input.protocol} ${validated.parsed.hostname} model=${input.model} → retrying with max_completion_tokens`,
+        );
+        response = await fetch(call.url, {
+          ...requestInit,
+          body: JSON.stringify(call.retryBodyOnUnsupportedMaxTokens),
+        });
+        latencyMs = Date.now() - start;
+      } else {
+        const redactedDetail = redactSecrets(detailText.slice(0, 240), [
+          input.apiKey,
+        ]);
+        const kind = statusToKind(response.status, redactedDetail);
+        const detail =
+          redactedDetail ||
+          (response.status === 404
+            ? 'HTTP 404 from provider; check the Base URL path.'
+            : '');
+        console.warn(
+          `[test:provider] ${input.protocol} ${validated.parsed.hostname} model=${input.model} → ${response.status} in ${latencyMs}ms (${kind})${detail ? ` ${detail}` : ''}`,
+        );
+        return {
+          ok: false,
+          kind,
+          latencyMs,
+          model,
+          status: response.status,
+          detail,
+        };
+      }
+    }
     if (response.ok) {
       let data: unknown;
       let rawText = '';
@@ -878,6 +1402,7 @@ export async function testProviderConnection(
   } finally {
     clearTimeout(timer);
     input.signal?.removeEventListener('abort', abortFromParent);
+    await proxyDispatcher?.close();
   }
 }
 
@@ -1067,7 +1592,13 @@ function attachAgentStreamHandlers(
       child,
       prompt,
       cwd,
-      model: model ?? null,
+      // Same substitution as the chat-run path in server.ts — adapters whose
+      // CLI rejects the synthetic 'default' (e.g. AMR / vela, which forces
+      // session/set_model before session/prompt) need the def's first
+      // concrete fallback id here too, otherwise Test connection deadlocks
+      // on the same `session/set_model must be called before session/prompt`
+      // error the chat-run path already handles.
+      model: resolveModelForAgent(def as never, model ?? null),
       mcpServers: [],
       send,
     });
@@ -1126,6 +1657,7 @@ async function testAgentConnectionInternal(
       model,
       agentName: input.agentId,
       detail: `Unknown agent id: ${input.agentId}`,
+      diagnostics: { phase: 'binary_resolution' },
     };
   }
   const configuredAgentEnv = agentCliEnvForAgent(
@@ -1141,6 +1673,7 @@ async function testAgentConnectionInternal(
       latencyMs: Date.now() - start,
       model,
       agentName: def.name,
+      diagnostics: { phase: 'binary_resolution' },
     };
   }
 
@@ -1152,7 +1685,37 @@ async function testAgentConnectionInternal(
   let abortHandler: (() => void) | null = null;
   const sink = createAgentSink();
 
-  const resultFromAgentText = (text: string): ConnectionTestResponse => {
+  // Phase tracker for structured diagnostics (#2248). The order matches
+  // the lifecycle: binary_resolution → spawn → connection_smoke_test →
+  // output_parse. Each result helper below stamps the *current* phase
+  // into the response so consumers don't have to scrape `detail` to
+  // know how far the test got. Phase is mutated at the points where
+  // the daemon meaningfully advances (just before spawn, when the
+  // child first produces stdout, etc.) — not on every event.
+  let phase: ConnectionTestPhase = 'binary_resolution';
+  const buildDiagnostics = (
+    overrides: Partial<ConnectionTestDiagnostics> = {},
+  ): ConnectionTestDiagnostics => {
+    const rawStderr = sink.getStderrTail().trim();
+    const rawStdout = sink.getRawStdoutTail().trim();
+    // `exactOptionalPropertyTypes: true` means we can't pass `undefined`
+    // to an optional field directly — conditionally spread instead so
+    // empty values just don't appear in the response.
+    return {
+      phase,
+      ...(executableResolution.launchPath
+        ? { binaryPath: executableResolution.launchPath }
+        : {}),
+      ...(rawStderr ? { stderrTail: redactSecrets(rawStderr) } : {}),
+      ...(rawStdout ? { stdoutTail: redactSecrets(rawStdout) } : {}),
+      ...overrides,
+    };
+  };
+
+  const resultFromAgentText = (
+    text: string,
+    exit?: { code: number | null; signal: NodeJS.Signals | null },
+  ): ConnectionTestResponse => {
     const latencyMs = Date.now() - start;
     const rawSample = truncateSample(text);
     const sample = redactSecrets(rawSample);
@@ -1168,6 +1731,10 @@ async function testAgentConnectionInternal(
         model,
         agentName: def.name,
         detail,
+        diagnostics: buildDiagnostics({
+          phase: 'output_parse',
+          ...(exit ? { exitCode: exit.code, signal: exit.signal } : {}),
+        }),
       };
     }
     if (!isSmokeOkReply(text)) {
@@ -1176,6 +1743,14 @@ async function testAgentConnectionInternal(
       );
     }
     console.log(`[test:agent] ${def.name} → ok in ${(latencyMs / 1000).toFixed(1)}s`);
+    // resultFromChildExit can route ACP forced shutdown (code === null,
+    // signal === 'SIGTERM' + acpCleanCompletion) through this success
+    // helper. Hard-coding `exitCode: 0` would silently overwrite the
+    // SIGTERM signal and violate the raw code/signal contract in
+    // packages/contracts/src/api/connectionTest.ts. Pass through the
+    // real `winner.code` / `winner.signal` when the caller has them and
+    // only synthesize `exitCode: 0` when no exit context is available
+    // (theoretical text-without-exit path).
     return {
       ok: true,
       kind: 'success',
@@ -1183,6 +1758,11 @@ async function testAgentConnectionInternal(
       model,
       agentName: def.name,
       sample,
+      diagnostics: buildDiagnostics(
+        exit
+          ? { phase: 'connection_smoke_test', exitCode: exit.code, signal: exit.signal }
+          : { phase: 'connection_smoke_test', exitCode: 0 },
+      ),
     };
   };
 
@@ -1201,6 +1781,7 @@ async function testAgentConnectionInternal(
         model,
         agentName: def.name,
         detail: auth.message ?? cursorAuthGuidance(),
+        diagnostics: buildDiagnostics(),
       };
     }
     if (detail && isLikelyModelErrorText(detail)) {
@@ -1214,6 +1795,7 @@ async function testAgentConnectionInternal(
         model,
         agentName: def.name,
         detail,
+        diagnostics: buildDiagnostics({ phase: 'output_parse' }),
       };
     }
     console.warn(
@@ -1226,6 +1808,7 @@ async function testAgentConnectionInternal(
       model,
       agentName: def.name,
       detail,
+      diagnostics: buildDiagnostics(),
     };
   };
 
@@ -1240,6 +1823,7 @@ async function testAgentConnectionInternal(
       latencyMs,
       model,
       agentName: def.name,
+      diagnostics: buildDiagnostics(),
     };
   };
 
@@ -1255,6 +1839,10 @@ async function testAgentConnectionInternal(
       );
     } catch (err) {
       const detail = err instanceof Error ? err.message : String(err);
+      // buildArgs runs *after* binary resolution but *before* spawn, so
+      // phase is still 'binary_resolution' here. Stamp diagnostics so the
+      // contract advertised in packages/contracts/src/api/connectionTest.ts
+      // ("Always set on local agent test responses") actually holds.
       return {
         ok: false,
         kind: 'agent_spawn_failed',
@@ -1262,6 +1850,7 @@ async function testAgentConnectionInternal(
         model,
         agentName: def.name,
         detail: redactSecrets(detail),
+        diagnostics: buildDiagnostics(),
       };
     }
     const stdinMode =
@@ -1273,10 +1862,23 @@ async function testAgentConnectionInternal(
         ...(def.env || {}),
       },
       configuredAgentEnv,
+      undefined,
+      { resolvedBin: executableResolution.selectedPath },
     );
     const env = applyAgentLaunchEnv(baseEnv, executableResolution);
     const auth = await probeAgentAuthStatus(input.agentId, executableResolution.launchPath, env);
     if (auth?.status === 'missing') {
+      // Preflight auth probe runs after binary resolution but before the
+      // smoke spawn — phase is still 'binary_resolution'. The smoke
+      // sink is empty here (no spawn happened), so the probe itself is
+      // the only source of stderr/stdout/exit context. Fold what the
+      // probe captured into the diagnostics block; `...overrides` in
+      // buildDiagnostics() lets these win over the empty sink tails.
+      const probeOverrides: Partial<ConnectionTestDiagnostics> = {};
+      if (auth.stdoutTail) probeOverrides.stdoutTail = redactSecrets(auth.stdoutTail);
+      if (auth.stderrTail) probeOverrides.stderrTail = redactSecrets(auth.stderrTail);
+      if (auth.exitCode !== undefined) probeOverrides.exitCode = auth.exitCode;
+      if (auth.signal !== undefined) probeOverrides.signal = auth.signal;
       return {
         ok: false,
         kind: 'agent_auth_required',
@@ -1284,6 +1886,7 @@ async function testAgentConnectionInternal(
         model,
         agentName: def.name,
         detail: auth.message ?? cursorAuthGuidance(),
+        diagnostics: buildDiagnostics(probeOverrides),
       };
     }
     const invocation = createCommandInvocation({
@@ -1291,6 +1894,12 @@ async function testAgentConnectionInternal(
       args,
       env,
     });
+    // We are about to hand off to child_process.spawn(). Any failure
+    // from here on (ENOENT, bad argv, non-zero exit) belongs to the
+    // 'spawn' phase rather than 'binary_resolution', so flip the tracker
+    // *before* spawning. resultFromAgentText flips it again to
+    // 'connection_smoke_test' / 'output_parse' once we get text out.
+    phase = 'spawn';
     child = spawn(invocation.command, invocation.args, {
       env,
       stdio: [stdinMode, 'pipe', 'pipe'],
@@ -1344,6 +1953,9 @@ async function testAgentConnectionInternal(
           model,
           agentName: def.name,
           detail: `${detail}${guidance}`,
+          diagnostics: buildDiagnostics({
+            phase: isMissing ? 'binary_resolution' : 'spawn',
+          }),
         };
       }
 
@@ -1373,10 +1985,11 @@ async function testAgentConnectionInternal(
         (winner.code === 0 && !winner.signal) || acpForcedShutdown;
       if (buffered) {
         const rawSample = truncateSample(buffered);
+        const exitInfo = { code: winner.code, signal: winner.signal };
         if (rawSample && isLikelyModelErrorText(rawSample)) {
-          return resultFromAgentText(buffered);
+          return resultFromAgentText(buffered, exitInfo);
         }
-        if (exitedCleanly) return resultFromAgentText(buffered);
+        if (exitedCleanly) return resultFromAgentText(buffered, exitInfo);
       }
       const stderrTail = sink.getStderrTail().trim();
       const rawStdoutTail = sink.getRawStdoutTail().trim();
@@ -1401,6 +2014,11 @@ async function testAgentConnectionInternal(
           model,
           agentName: def.name,
           detail: auth.message ?? cursorAuthGuidance(),
+          diagnostics: buildDiagnostics({
+            phase: 'connection_smoke_test',
+            exitCode: winner.code,
+            signal: winner.signal,
+          }),
         };
       }
       const claudeDiagnostic = diagnoseClaudeCliFailure({
@@ -1410,6 +2028,7 @@ async function testAgentConnectionInternal(
         stderrTail,
         stdoutTail: rawStdoutTail || buffered,
         env,
+        resolvedBin: executableResolution.selectedPath,
       });
       if (claudeDiagnostic) {
         console.warn(
@@ -1422,6 +2041,11 @@ async function testAgentConnectionInternal(
           model,
           agentName: def.name,
           detail: claudeDiagnostic.detail,
+          diagnostics: buildDiagnostics({
+            phase: 'spawn',
+            exitCode: winner.code,
+            signal: winner.signal,
+          }),
         };
       }
       const detail = redactSecrets(
@@ -1446,6 +2070,11 @@ async function testAgentConnectionInternal(
         agentName: def.name,
         detail:
           `${detail || 'Agent exited without producing assistant text'}${guidance}`,
+        diagnostics: buildDiagnostics({
+          phase: buffered ? 'output_parse' : 'spawn',
+          exitCode: winner.code,
+          signal: winner.signal,
+        }),
       };
     };
 
@@ -1502,6 +2131,10 @@ async function testAgentConnectionInternal(
     return resultFromChildExit(winner);
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
+    // Outer catch — the failure may have happened at any phase between
+    // binary_resolution and output_parse, so stamp the current phase as
+    // observed. buildDiagnostics is defined in the enclosing scope and
+    // is safe to call here.
     return {
       ok: false,
       kind: 'agent_spawn_failed',
@@ -1509,6 +2142,7 @@ async function testAgentConnectionInternal(
       model,
       agentName: def.name,
       detail: redactSecrets(detail),
+      diagnostics: buildDiagnostics(),
     };
   } finally {
     if (timer) clearTimeout(timer);

apps/daemon/src/connectors/routes.ts

@@ -589,7 +589,7 @@ export function registerConnectorRoutes(app: Express, options: RegisterConnector
     }
   });
 
-  app.get('/api/connectors/:connectorId', async (req: Request, res: Response) => {
+  app.get('/api/connectors/:connectorId', async (req: Request<{ connectorId: string }>, res: Response) => {
     try {
       const connectorId = req.params.connectorId;
       if (!connectorId) return options.sendApiError(res, 400, 'CONNECTOR_NOT_FOUND', 'connectorId is required');
@@ -625,7 +625,7 @@ export function registerConnectorRoutes(app: Express, options: RegisterConnector
     }
   });
 
-  app.post('/api/connectors/:connectorId/connect', requireLocalDaemonRequest, async (req: Request, res: Response) => {
+  app.post('/api/connectors/:connectorId/connect', requireLocalDaemonRequest, async (req: Request<{ connectorId: string }>, res: Response) => {
     try {
       const connectorId = req.params.connectorId;
       if (!connectorId) return options.sendApiError(res, 400, 'CONNECTOR_NOT_FOUND', 'connectorId is required');
@@ -653,7 +653,7 @@ export function registerConnectorRoutes(app: Express, options: RegisterConnector
     }
   });
 
-  app.get('/api/connectors/oauth/callback/:connectorId', async (req: Request, res: Response) => {
+  app.get('/api/connectors/oauth/callback/:connectorId', async (req: Request<{ connectorId: string }>, res: Response) => {
     try {
       const connectorId = req.params.connectorId;
       if (!connectorId) return options.sendApiError(res, 400, 'CONNECTOR_NOT_FOUND', 'connectorId is required');
@@ -674,7 +674,7 @@ export function registerConnectorRoutes(app: Express, options: RegisterConnector
     }
   });
 
-  app.post('/api/connectors/:connectorId/authorization/cancel', requireLocalDaemonRequest, async (req: Request, res: Response) => {
+  app.post('/api/connectors/:connectorId/authorization/cancel', requireLocalDaemonRequest, async (req: Request<{ connectorId: string }>, res: Response) => {
     try {
       const connectorId = req.params.connectorId;
       if (!connectorId) return options.sendApiError(res, 400, 'CONNECTOR_NOT_FOUND', 'connectorId is required');
@@ -684,7 +684,7 @@ export function registerConnectorRoutes(app: Express, options: RegisterConnector
     }
   });
 
-  app.delete('/api/connectors/:connectorId/connection', requireLocalDaemonRequest, async (req: Request, res: Response) => {
+  app.delete('/api/connectors/:connectorId/connection', requireLocalDaemonRequest, async (req: Request<{ connectorId: string }>, res: Response) => {
     try {
       const connectorId = req.params.connectorId;
       if (!connectorId) return options.sendApiError(res, 400, 'CONNECTOR_NOT_FOUND', 'connectorId is required');

apps/daemon/src/connectors/service.ts

@@ -58,6 +58,35 @@ function isMissingOrExpiredComposioOAuthState(error: unknown): boolean {
     && error.message === 'Composio OAuth state is missing or expired';
 }
 
+function boundedJsonValueIncludesAuthStaleSignal(value: BoundedJsonValue | undefined): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === 'number') return value === 401;
+  if (typeof value === 'boolean') return false;
+  if (typeof value === 'string') {
+    const normalized = value.toLowerCase();
+    return normalized === '401'
+      || /\bbad credentials\b/.test(normalized)
+      || /\bunauthori[sz]ed\b/.test(normalized)
+      || /\binvalid (?:access )?token\b/.test(normalized)
+      || /\btoken (?:is )?expired\b/.test(normalized)
+      || /\bexpired (?:access )?token\b/.test(normalized);
+  }
+  if (Array.isArray(value)) return value.some(boundedJsonValueIncludesAuthStaleSignal);
+  return Object.values(value).some(boundedJsonValueIncludesAuthStaleSignal);
+}
+
+function isConnectorAuthStaleError(error: unknown, request: Pick<ConnectorExecuteRequest, 'connectorId' | 'toolName'>): boolean {
+  if (!(error instanceof ConnectorServiceError) || error.code !== 'CONNECTOR_EXECUTION_FAILED') return false;
+  const details = error.details;
+  return details?.connectorId === request.connectorId
+    && details.toolName === request.toolName
+    && boundedJsonValueIncludesAuthStaleSignal(details.error);
+}
+
+function connectorAuthExpiredMessage(definition: ConnectorCatalogDefinition): string {
+  return `${definition.name} authorization expired. Reconnect ${definition.name}.`;
+}
+
 function hasStoredComposioConnection(credential: ConnectorCredentialRecord | undefined, providerConnectionId: string): boolean {
   return credential?.credentials.provider === 'composio'
     && credential.credentials.providerConnectionId === providerConnectionId;
@@ -421,6 +450,11 @@ export class ConnectorStatusService {
     return cloneStatus(next);
   }
 
+  markAuthenticationExpired(definition: ConnectorCatalogDefinition, lastError: string, accountLabel?: string): ConnectorConnectionStatus {
+    this.credentialStore?.delete(definition.id);
+    return this.setError(definition, lastError, accountLabel);
+  }
+
   clear(connectorId: string): void {
     this.statuses.delete(connectorId);
   }
@@ -776,7 +810,15 @@ export class ConnectorService {
 
     this.enforceRunLimits(context);
 
-    const providerOutput = await this.executeConnectorProviderTool(request, context, definition, tool);
+    let providerOutput: BoundedJsonObject;
+    try {
+      providerOutput = await this.executeConnectorProviderTool(request, context, definition, tool);
+    } catch (error) {
+      if (isConnectorAuthStaleError(error, request)) {
+        this.statusService.markAuthenticationExpired(definition, connectorAuthExpiredMessage(definition), connector.accountLabel);
+      }
+      throw error;
+    }
     const protectedOutput = protectConnectorOutput(providerOutput);
     const output = protectedOutput.output;
     const outputSummary = summarizeConnectorOutput(output);

apps/daemon/src/cwd-aliases.ts

@@ -28,8 +28,11 @@
 // source root so an environment that puts `skills/` itself behind a
 // symlink (e.g. a content-addressable mount) is followed correctly.
 
-import { cp, lstat, rm, stat } from 'node:fs/promises';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { chmod, cp, lstat, mkdir, readdir, rm, stat, utimes } from 'node:fs/promises';
 import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
 
 export const SKILLS_CWD_ALIAS = '.od-skills';
 
@@ -44,6 +47,53 @@ export interface SkillStagingResult {
   reason?: string;
 }
 
+export function skillCwdAliasSegment(dir: string): string {
+  const folder = path.basename(dir) || 'skill';
+  const normalizedDir = path.resolve(dir).replaceAll('\\', '/');
+  const digest = createHash('sha256').update(normalizedDir).digest('hex').slice(0, 10);
+  return `${folder}-${digest}`;
+}
+
+// copy_file_range(2) — used by fs.cp under the hood — is rejected with
+// these errno codes when source and destination live on different
+// filesystems (commonly EXDEV; a container image layer copied onto a
+// ZFS/overlay bind mount surfaces EPERM). Node doesn't fall back to a
+// userspace copy on any of them, so we do.
+const RECOVERABLE_COPY_CODES = new Set(['EPERM', 'EXDEV', 'ENOTSUP', 'EOPNOTSUPP']);
+
+type SkillCopyFn = (
+  source: string,
+  destination: string,
+  options: { recursive: boolean; dereference: boolean; preserveTimestamps: boolean },
+) => Promise<void>;
+
+// Recursive copy that mirrors `cp({ dereference: true })` without going
+// through copy_file_range. `stat()` (not `lstat`) follows symlinks, so
+// every staged entry lands as a real directory or regular file — keeping
+// `.od-skills/` a self-contained write barrier even on the fallback path.
+async function copyTreeDereferenced(srcDir: string, destDir: string): Promise<void> {
+  await mkdir(destDir, { recursive: true });
+  for (const entry of await readdir(srcDir, { withFileTypes: true })) {
+    const from = path.join(srcDir, entry.name);
+    const to = path.join(destDir, entry.name);
+    const entryStat = await stat(from);
+    if (entryStat.isDirectory()) {
+      await copyTreeDereferenced(from, to);
+    } else if (entryStat.isFile()) {
+      await pipeline(createReadStream(from), createWriteStream(to));
+      // createWriteStream opens the destination with the default 0644, so
+      // restore the source's permission bits (notably the exec bit on
+      // skill helper scripts) and mtime — `fs.cp` preserves these, and
+      // skills shell out to staged scripts. Mask to 0o777 so the
+      // agent-writable staging copy never inherits setuid/setgid/sticky.
+      await chmod(to, entryStat.mode & 0o777);
+      await utimes(to, entryStat.atime, entryStat.mtime);
+    }
+    // Sockets, FIFOs, and devices can't appear in a sane skill folder and
+    // copying them would hang or fail — skip them.
+  }
+}
+
 /**
  * Copy `<sourceDir>` to `<cwd>/.od-skills/<folderName>/` so an agent can
  * reach skill side files via a cwd-relative path. Idempotent and
@@ -60,6 +110,11 @@ export async function stageActiveSkill(
   folderName: string,
   sourceDir: string,
   log: SkillStagingLogger = () => {},
+  // Seam for tests: the real copy_file_range EPERM only reproduces on
+  // specific cross-filesystem mounts (ZFS/overlay), so tests inject a
+  // copy that rejects with a synthetic code to drive the fallback path.
+  nativeCopy: SkillCopyFn = (source, destination, options) =>
+    cp(source, destination, options),
 ): Promise<SkillStagingResult> {
   if (!cwd) {
     return { staged: false, reason: 'no project cwd' };
@@ -115,16 +170,26 @@ export async function stageActiveSkill(
     // reflected and a partially-failed previous run cannot leave junk
     // behind.
     await rm(stagedPath, { recursive: true, force: true });
-    await cp(sourceDir, stagedPath, {
-      recursive: true,
-      // Resolve every symlink we find inside the skill so the staged
-      // copy is a fully self-contained set of regular files. This is
-      // what makes the copy a true write barrier — no entry under
-      // `.od-skills/...` can resolve back to a real file outside the
-      // project cwd.
-      dereference: true,
-      preserveTimestamps: true,
-    });
+    try {
+      await nativeCopy(sourceDir, stagedPath, {
+        recursive: true,
+        // Resolve every symlink we find inside the skill so the staged
+        // copy is a fully self-contained set of regular files. This is
+        // what makes the copy a true write barrier — no entry under
+        // `.od-skills/...` can resolve back to a real file outside the
+        // project cwd.
+        dereference: true,
+        preserveTimestamps: true,
+      });
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code ?? '';
+      if (!RECOVERABLE_COPY_CODES.has(code)) throw err;
+      log(
+        `[od] skill-stage: native copy failed (${code}); retrying with stream copy`,
+      );
+      await rm(stagedPath, { recursive: true, force: true });
+      await copyTreeDereferenced(sourceDir, stagedPath);
+    }
     return { staged: true, stagedPath };
   } catch (err) {
     log(`[od] skill-stage failed: ${(err as Error).message}`);

apps/daemon/src/db.ts

@@ -94,6 +94,7 @@ function migrate(db: SqliteDb): void {
       attachments_json TEXT,
       produced_files_json TEXT,
       feedback_json TEXT,
+      pre_turn_file_names_json TEXT,
       started_at INTEGER,
       ended_at INTEGER,
       position INTEGER NOT NULL,
@@ -115,6 +116,7 @@ function migrate(db: SqliteDb): void {
       text TEXT NOT NULL,
       position_json TEXT NOT NULL,
       html_hint TEXT NOT NULL,
+      style_json TEXT,
       note TEXT NOT NULL,
       status TEXT NOT NULL,
       created_at INTEGER NOT NULL,
@@ -136,6 +138,12 @@ function migrate(db: SqliteDb): void {
       FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
     );
 
+    CREATE TABLE IF NOT EXISTS tabs_state (
+      project_id TEXT PRIMARY KEY,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY(project_id) REFERENCES projects(id) ON DELETE CASCADE
+    );
+
     CREATE INDEX IF NOT EXISTS idx_tabs_project
       ON tabs(project_id, position);
 
@@ -194,6 +202,14 @@ function migrate(db: SqliteDb): void {
       FOREIGN KEY(routine_id) REFERENCES routines(id) ON DELETE CASCADE
     );
 
+    CREATE TABLE IF NOT EXISTS routine_schedule_claims (
+      routine_id TEXT NOT NULL,
+      slot_at INTEGER NOT NULL,
+      claimed_at INTEGER NOT NULL,
+      PRIMARY KEY(routine_id, slot_at),
+      FOREIGN KEY(routine_id) REFERENCES routines(id) ON DELETE CASCADE
+    );
+
     CREATE INDEX IF NOT EXISTS idx_routine_runs_routine
       ON routine_runs(routine_id, started_at DESC);
   `);
@@ -228,6 +244,9 @@ function migrate(db: SqliteDb): void {
   if (!messageCols.some((c: DbRow) => c.name === 'feedback_json')) {
     db.exec(`ALTER TABLE messages ADD COLUMN feedback_json TEXT`);
   }
+  if (!messageCols.some((c: DbRow) => c.name === 'pre_turn_file_names_json')) {
+    db.exec(`ALTER TABLE messages ADD COLUMN pre_turn_file_names_json TEXT`);
+  }
   const routineRunCols = db.prepare(`PRAGMA table_info(routine_runs)`).all() as DbRow[];
   if (!routineRunCols.some((c: DbRow) => c.name === 'error_code')) {
     db.exec(`ALTER TABLE routine_runs ADD COLUMN error_code TEXT`);
@@ -243,6 +262,9 @@ function migrate(db: SqliteDb): void {
   if (!previewCommentCols.some((c: DbRow) => c.name === 'pod_members_json')) {
     db.exec(`ALTER TABLE preview_comments ADD COLUMN pod_members_json TEXT`);
   }
+  if (!previewCommentCols.some((c: DbRow) => c.name === 'style_json')) {
+    db.exec(`ALTER TABLE preview_comments ADD COLUMN style_json TEXT`);
+  }
   const deploymentCols = db.prepare(`PRAGMA table_info(deployments)`).all() as DbRow[];
   if (!deploymentCols.some((c: DbRow) => c.name === 'status')) {
     db.exec(`ALTER TABLE deployments ADD COLUMN status TEXT NOT NULL DEFAULT 'ready'`);
@@ -730,12 +752,23 @@ export function listConversations(db: SqliteDb, projectId: string) {
                  AND m.run_status IS NOT NULL
             )
            WHERE rn = 1
+        ),
+        total_run_durations AS (
+          SELECT m.conversation_id AS conversationId,
+                 SUM(${terminalRunDurationSql('m')}) AS totalDurationMs
+            FROM messages m
+            JOIN project_conversations c ON c.id = m.conversation_id
+           WHERE m.role = 'assistant'
+             AND m.run_status IN ('succeeded', 'failed', 'canceled')
+           GROUP BY m.conversation_id
         )
         SELECT c.id, c.projectId, c.title, c.createdAt, c.updatedAt,
                lr.latestRunStatus, lr.latestRunStartedAt,
-               lr.latestRunEndedAt, lr.latestRunEventsJson
+               lr.latestRunEndedAt, lr.latestRunEventsJson,
+               trd.totalDurationMs
           FROM project_conversations c
           LEFT JOIN latest_runs lr ON lr.conversationId = c.id
+          LEFT JOIN total_run_durations trd ON trd.conversationId = c.id
          ORDER BY c.updatedAt DESC`,
     )
     .all(projectId)).map(normalizeConversation);
@@ -753,6 +786,7 @@ export function getConversation(db: SqliteDb, id: string) {
   return {
     ...normalizeConversation(r),
     latestRun: latestConversationRunSummary(db, r.id) ?? undefined,
+    ...numberProperty('totalDurationMs', totalConversationRunDurationMs(db, r.id)),
   };
 }
 
@@ -769,10 +803,16 @@ function normalizeConversation(r: DbRow) {
     title: r.title ?? null,
     createdAt: Number(r.createdAt),
     updatedAt: Number(r.updatedAt),
+    ...numberProperty('totalDurationMs', r.totalDurationMs),
     latestRun: latestRun ?? undefined,
   };
 }
 
+function numberProperty(key: string, value: unknown) {
+  const n = value == null ? undefined : Number(value);
+  return typeof n === 'number' && Number.isFinite(n) ? { [key]: n } : {};
+}
+
 function latestConversationRunSummary(db: SqliteDb, conversationId: string) {
   const row = db
     .prepare(
@@ -791,6 +831,50 @@ function latestConversationRunSummary(db: SqliteDb, conversationId: string) {
   return conversationRunSummaryFromRow(row);
 }
 
+function totalConversationRunDurationMs(db: SqliteDb, conversationId: string): number | undefined {
+  const row = db
+    .prepare(
+      `SELECT SUM(${terminalRunDurationSql()}) AS totalDurationMs
+         FROM messages
+        WHERE conversation_id = ?
+          AND role = 'assistant'
+          AND run_status IN ('succeeded', 'failed', 'canceled')`,
+    )
+    .get(conversationId) as DbRow | undefined;
+  return row?.totalDurationMs == null ? undefined : Number(row.totalDurationMs);
+}
+
+function terminalRunDurationSql(alias?: string) {
+  const p = alias ? `${alias}.` : '';
+  return `CASE
+            WHEN ${p}started_at IS NOT NULL AND ${p}ended_at IS NOT NULL THEN
+              CASE
+                WHEN CAST(${p}ended_at AS INTEGER) >= CAST(${p}started_at AS INTEGER)
+                  THEN CAST(${p}ended_at AS INTEGER) - CAST(${p}started_at AS INTEGER)
+                ELSE 0
+              END
+            ELSE (
+              SELECT CASE
+                       WHEN json_extract(usage_event.value, '$.durationMs') >= 0
+                         THEN json_extract(usage_event.value, '$.durationMs')
+                       ELSE 0
+                     END
+                FROM json_each(
+                  CASE
+                    WHEN json_valid(${p}events_json) AND json_type(${p}events_json) = 'array'
+                      THEN ${p}events_json
+                    ELSE '[]'
+                  END
+                ) AS usage_event
+               WHERE usage_event.type = 'object'
+                 AND json_extract(usage_event.value, '$.kind') = 'usage'
+                 AND json_type(usage_event.value, '$.durationMs') IN ('integer', 'real')
+               ORDER BY CAST(usage_event.key AS INTEGER) DESC
+               LIMIT 1
+            )
+          END`;
+}
+
 function conversationRunSummaryFromRow(row: DbRow | undefined) {
   if (!row || typeof row.runStatus !== 'string') return null;
   const startedAt = row.startedAt == null ? undefined : Number(row.startedAt);
@@ -874,6 +958,7 @@ export function listMessages(db: SqliteDb, conversationId: string) {
               comment_attachments_json AS commentAttachmentsJson,
               produced_files_json AS producedFilesJson,
               feedback_json AS feedbackJson,
+              pre_turn_file_names_json AS preTurnFileNamesJson,
               created_at AS createdAt, started_at AS startedAt, ended_at AS endedAt,
               position
          FROM messages
@@ -895,7 +980,9 @@ export function upsertMessage(db: SqliteDb, conversationId: string, m: DbRow) {
           SET role = ?, content = ?, agent_id = ?, agent_name = ?,
               run_id = ?, run_status = ?, last_run_event_id = ?,
               events_json = ?, attachments_json = ?, comment_attachments_json = ?,
-              produced_files_json = ?, feedback_json = ?, started_at = ?, ended_at = ?
+              produced_files_json = ?, feedback_json = ?,
+              pre_turn_file_names_json = ?,
+              started_at = ?, ended_at = ?
         WHERE id = ?`,
     ).run(
       m.role,
@@ -910,6 +997,7 @@ export function upsertMessage(db: SqliteDb, conversationId: string, m: DbRow) {
       m.commentAttachments ? JSON.stringify(m.commentAttachments) : null,
       m.producedFiles ? JSON.stringify(m.producedFiles) : null,
       m.feedback ? JSON.stringify(m.feedback) : null,
+      m.preTurnFileNames ? JSON.stringify(m.preTurnFileNames) : null,
       m.startedAt ?? null,
       m.endedAt ?? null,
       m.id,
@@ -921,17 +1009,18 @@ export function upsertMessage(db: SqliteDb, conversationId: string, m: DbRow) {
       )
       .get(conversationId) as DbRow | undefined;
     const position = (max?.m ?? -1) + 1;
-    // 18 values: id, conversation_id, role, content, agent_id, agent_name,
+    // 19 values: id, conversation_id, role, content, agent_id, agent_name,
     // run_id, run_status, last_run_event_id, events_json, attachments_json,
-    // comment_attachments_json, produced_files_json, feedback_json, started_at, ended_at,
-    // position, created_at.
+    // comment_attachments_json, produced_files_json, feedback_json,
+    // pre_turn_file_names_json, started_at, ended_at, position, created_at.
     db.prepare(
       `INSERT INTO messages
          (id, conversation_id, role, content, agent_id, agent_name,
           run_id, run_status, last_run_event_id, events_json,
           attachments_json, comment_attachments_json, produced_files_json,
-          feedback_json, started_at, ended_at, position, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          feedback_json, pre_turn_file_names_json,
+          started_at, ended_at, position, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
     ).run(
       m.id,
       conversationId,
@@ -947,6 +1036,7 @@ export function upsertMessage(db: SqliteDb, conversationId: string, m: DbRow) {
       m.commentAttachments ? JSON.stringify(m.commentAttachments) : null,
       m.producedFiles ? JSON.stringify(m.producedFiles) : null,
       m.feedback ? JSON.stringify(m.feedback) : null,
+      m.preTurnFileNames ? JSON.stringify(m.preTurnFileNames) : null,
       m.startedAt ?? null,
       m.endedAt ?? null,
       position,
@@ -968,6 +1058,7 @@ export function upsertMessage(db: SqliteDb, conversationId: string, m: DbRow) {
               comment_attachments_json AS commentAttachmentsJson,
               produced_files_json AS producedFilesJson,
               feedback_json AS feedbackJson,
+              pre_turn_file_names_json AS preTurnFileNamesJson,
               created_at AS createdAt, started_at AS startedAt, ended_at AS endedAt,
               position
          FROM messages WHERE id = ?`,
@@ -1042,7 +1133,7 @@ export function listPreviewComments(db: SqliteDb, projectId: string, conversatio
               file_path AS filePath, element_id AS elementId, selector, label,
               text, position_json AS positionJson, html_hint AS htmlHint,
               selection_kind AS selectionKind, member_count AS memberCount,
-              pod_members_json AS podMembersJson,
+              pod_members_json AS podMembersJson, style_json AS styleJson,
               note, status, created_at AS createdAt, updated_at AS updatedAt
          FROM preview_comments
         WHERE project_id = ? AND conversation_id = ?
@@ -1065,6 +1156,7 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
   const position = normalizePosition(target.position);
   const selectionKind = target.selectionKind === 'pod' ? 'pod' : 'element';
   const podMembers = selectionKind === 'pod' ? normalizePodMembers(target.podMembers) : [];
+  const style = normalizeAnnotationStyle(target.style);
   const memberCount = selectionKind === 'pod'
     ? (podMembers.length > 0
         ? podMembers.length
@@ -1086,8 +1178,8 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
     `INSERT INTO preview_comments
        (id, project_id, conversation_id, file_path, element_id, selector, label,
         text, position_json, html_hint, selection_kind, member_count, pod_members_json,
-        note, status, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        style_json, note, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(project_id, conversation_id, file_path, element_id) DO UPDATE SET
        selector = excluded.selector,
        label = excluded.label,
@@ -1097,6 +1189,7 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
        selection_kind = excluded.selection_kind,
        member_count = excluded.member_count,
        pod_members_json = excluded.pod_members_json,
+       style_json = excluded.style_json,
        note = excluded.note,
        status = 'open',
        updated_at = excluded.updated_at`,
@@ -1114,6 +1207,7 @@ export function upsertPreviewComment(db: SqliteDb, projectId: string, conversati
     selectionKind,
     selectionKind === 'pod' ? memberCount : null,
     selectionKind === 'pod' ? JSON.stringify(podMembers) : null,
+    style ? JSON.stringify(style) : null,
     note,
     'open',
     createdAt,
@@ -1150,7 +1244,7 @@ function getPreviewComment(db: SqliteDb, projectId: string, conversationId: stri
               file_path AS filePath, element_id AS elementId, selector, label,
               text, position_json AS positionJson, html_hint AS htmlHint,
               selection_kind AS selectionKind, member_count AS memberCount,
-              pod_members_json AS podMembersJson,
+              pod_members_json AS podMembersJson, style_json AS styleJson,
               note, status, created_at AS createdAt, updated_at AS updatedAt
          FROM preview_comments
         WHERE id = ? AND project_id = ? AND conversation_id = ?`,
@@ -1173,6 +1267,7 @@ function normalizePreviewComment(row: DbRow) {
     text: row.text,
     position: parseJsonOrUndef(row.positionJson) ?? { x: 0, y: 0, width: 0, height: 0 },
     htmlHint: row.htmlHint,
+    style: normalizeAnnotationStyle(parseJsonOrUndef(row.styleJson)),
     selectionKind: row.selectionKind === 'pod' ? 'pod' : 'element',
     memberCount:
       normalizedPodMembers && normalizedPodMembers.length > 0
@@ -1214,11 +1309,40 @@ function normalizePodMembers(input: unknown) {
           typeof member.htmlHint === 'string'
             ? compactWhitespace(member.htmlHint).slice(0, 180)
             : '',
+        style: normalizeAnnotationStyle(member.style),
       };
     })
     .filter(Boolean);
 }
 
+function normalizeAnnotationStyle(input: unknown) {
+  if (!input || typeof input !== 'object') return undefined;
+  const raw = input as DbRow;
+  const style: DbRow = {};
+  for (const key of ANNOTATION_STYLE_KEYS) {
+    const value = raw[key];
+    if (typeof value !== 'string') continue;
+    const trimmed = compactWhitespace(value);
+    if (trimmed) style[key] = trimmed.slice(0, 120);
+  }
+  return Object.keys(style).length > 0 ? style : undefined;
+}
+
+const ANNOTATION_STYLE_KEYS = [
+  'color',
+  'backgroundColor',
+  'fontSize',
+  'fontWeight',
+  'lineHeight',
+  'textAlign',
+  'fontFamily',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+  'borderRadius',
+] as const;
+
 function compactWhitespace(value: string): string {
   return value.replace(/\s+/g, ' ').trim();
 }
@@ -1256,6 +1380,7 @@ function normalizeMessage(row: DbRow) {
     commentAttachments: parseJsonOrUndef(row.commentAttachmentsJson),
     producedFiles: parseJsonOrUndef(row.producedFilesJson),
     feedback: parseJsonOrUndef(row.feedbackJson),
+    preTurnFileNames: parseJsonOrUndef(row.preTurnFileNamesJson),
     createdAt: row.createdAt ?? undefined,
     startedAt: row.startedAt ?? undefined,
     endedAt: row.endedAt ?? undefined,
@@ -1440,6 +1565,41 @@ export function insertRoutineRun(db: SqliteDb, r: DbRow) {
   return getRoutineRun(db, r.id);
 }
 
+export function insertScheduledRoutineRun(db: SqliteDb, r: DbRow, slotAt: number) {
+  const insertClaim = db.prepare(
+    `INSERT OR IGNORE INTO routine_schedule_claims
+       (routine_id, slot_at, claimed_at)
+     VALUES (?, ?, ?)`,
+  );
+  const insertRun = db.prepare(
+    `INSERT INTO routine_runs
+       (id, routine_id, trigger, status, project_id, conversation_id,
+        agent_run_id, started_at, completed_at, summary, error, error_code)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  const tx = db.transaction(() => {
+    const claim = insertClaim.run(r.routineId, slotAt, Date.now());
+    if (claim.changes === 0) return false;
+    insertRun.run(
+      r.id,
+      r.routineId,
+      r.trigger,
+      r.status,
+      r.projectId,
+      r.conversationId,
+      r.agentRunId,
+      r.startedAt,
+      r.completedAt ?? null,
+      r.summary ?? null,
+      r.error ?? null,
+      r.errorCode ?? null,
+    );
+    return true;
+  });
+  if (!tx()) return null;
+  return getRoutineRun(db, r.id);
+}
+
 export function updateRoutineRun(db: SqliteDb, id: string, patch: DbRow) {
   const existing = getRoutineRun(db, id);
   if (!existing) return null;
@@ -1449,10 +1609,14 @@ export function updateRoutineRun(db: SqliteDb, id: string, patch: DbRow) {
   };
   db.prepare(
     `UPDATE routine_runs
-        SET status = ?, completed_at = ?, summary = ?, error = ?, error_code = ?
+        SET status = ?, project_id = ?, conversation_id = ?, agent_run_id = ?,
+            completed_at = ?, summary = ?, error = ?, error_code = ?
       WHERE id = ?`,
   ).run(
     merged.status,
+    merged.projectId,
+    merged.conversationId,
+    merged.agentRunId,
     merged.completedAt ?? null,
     merged.summary ?? null,
     merged.error ?? null,
@@ -1488,15 +1652,24 @@ export function listTabs(db: SqliteDb, projectId: string) {
          FROM tabs WHERE project_id = ? ORDER BY position ASC`,
     )
     .all(projectId) as DbRow[];
+  const state = db
+    .prepare(`SELECT project_id FROM tabs_state WHERE project_id = ? LIMIT 1`)
+    .get(projectId) as DbRow | undefined;
   const active = (rows as DbRow[]).find((r: DbRow) => r.isActive) ?? null;
   return {
     tabs: (rows as DbRow[]).map((r: DbRow) => r.name),
     active: active ? active.name : null,
+    hasSavedState: rows.length > 0 || Boolean(state),
   };
 }
 
 export function setTabs(db: SqliteDb, projectId: string, names: string[], activeName: string | null) {
   const tx = db.transaction(() => {
+    db.prepare(
+      `INSERT INTO tabs_state (project_id, updated_at)
+       VALUES (?, ?)
+       ON CONFLICT(project_id) DO UPDATE SET updated_at = excluded.updated_at`,
+    ).run(projectId, Date.now());
     db.prepare(`DELETE FROM tabs WHERE project_id = ?`).run(projectId);
     const ins = db.prepare(
       `INSERT INTO tabs (project_id, name, position, is_active)

apps/daemon/src/deploy-routes.ts

@@ -89,7 +89,7 @@ export function registerDeployRoutes(app: Express, ctx: RegisterDeployRoutesDeps
         PROJECTS_DIR,
         req.params.id,
         fileName,
-        { metadata: deployProject?.metadata },
+        { metadata: deployProject?.metadata, includeProjectFiles: true },
       );
       const project = getProject(db, req.params.id);
       const cloudflarePagesProjectName =
@@ -171,7 +171,7 @@ export function registerDeployRoutes(app: Express, ctx: RegisterDeployRoutesDeps
         PROJECTS_DIR,
         req.params.id,
         fileName,
-        { metadata: preflightProject?.metadata, providerId },
+        { metadata: preflightProject?.metadata, providerId, includeProjectFiles: true },
       );
       res.json(body);
     } catch (err: any) {

apps/daemon/src/deploy.ts

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { hash as blake3Hash } from 'blake3-wasm';
-import { readProjectFile, validateProjectPath } from './projects.js';
+import { listFiles, readProjectFile, validateProjectPath } from './projects.js';
 
 export const VERCEL_PROVIDER_ID = 'vercel-self';
 export const CLOUDFLARE_PAGES_PROVIDER_ID = 'cloudflare-pages';
@@ -29,7 +29,12 @@ type CloudflarePagesConfigHints = {
 };
 type DeployFile = { file: string; data: Buffer | Uint8Array | string; contentType?: string; sourcePath?: string };
 type DeployFilePlan = { entryPath: string; html: string; files: DeployFile[]; missing: string[]; invalid: string[] };
-type DeployOptions = { metadata?: unknown; hookScriptUrl?: string; providerId?: DeployProviderId };
+type DeployOptions = {
+  metadata?: unknown;
+  hookScriptUrl?: string;
+  providerId?: DeployProviderId;
+  includeProjectFiles?: boolean;
+};
 type CloudflarePagesDeploySelection = { zoneId: string; zoneName: string; domainPrefix: string; hostname: string };
 type CloudflareDnsRecord = JsonObject & { id?: string; type?: string; name?: string; content?: string; comment?: string };
 type DeployLinkStatus = 'ready' | 'protected' | 'failed' | 'link-delayed';
@@ -318,6 +323,14 @@ export async function buildDeployFilePlan(projectsRoot: string, projectId: strin
     }
   }
 
+  if (options.includeProjectFiles) {
+    await addVisibleProjectFilesToDeployPlan(files, {
+      projectsRoot,
+      projectId,
+      metadata: options.metadata,
+    });
+  }
+
   return {
     entryPath,
     html,
@@ -341,6 +354,37 @@ export async function buildDeployFileSet(projectsRoot: string, projectId: string
   return plan.files;
 }
 
+async function addVisibleProjectFilesToDeployPlan(
+  files: Map<string, DeployFile>,
+  input: { projectsRoot: string; projectId: string; metadata?: unknown },
+) {
+  if (isLinkedFolderProject(input.metadata)) return;
+  const projectFiles = await listFiles(input.projectsRoot, input.projectId, { metadata: input.metadata });
+  for (const item of projectFiles) {
+    if (!item?.name || files.has(item.name)) continue;
+    const safePath = validateProjectPath(item.name);
+    // The selected entry is already mapped to provider-root index.html. Keep
+    // the original root index reserved so choosing index-v1.html does not get
+    // overwritten by the old launcher at the same deploy path.
+    if (safePath === 'index.html') continue;
+    const projectFile = await readProjectFile(input.projectsRoot, input.projectId, safePath, input.metadata);
+    files.set(safePath, {
+      file: safePath,
+      data: projectFile.buffer,
+      contentType: projectFile.mime,
+      sourcePath: safePath,
+    });
+  }
+}
+
+function isLinkedFolderProject(metadata: unknown) {
+  return Boolean(
+    metadata
+      && typeof metadata === 'object'
+      && typeof (metadata as { baseDir?: unknown }).baseDir === 'string',
+  );
+}
+
 export async function deployToVercel({ config, files, projectId }: { config: DeployConfig; files: DeployFile[]; projectId: string }) {
   if (!config?.token) {
     throw new DeployError('Vercel token is required.', 400);

apps/daemon/src/design-system-rename-args.ts

@@ -0,0 +1,54 @@
+// Pure argument parser for `od design-systems rename <id> --title <new>`.
+// Kept out of cli.ts (a top-level dispatch script that runs on import) so it
+// can be unit-tested directly, mirroring research/cli-args.ts.
+//
+// Accepts the new name either as a `--title <value>` / `--title=<value>` flag
+// or as the trailing positional(s) after the id (so `rename <id> "New name"`
+// works). String flags that take a separate value (`--daemon-url <url>`, etc.)
+// have that value skipped so it is never mistaken for the id or title.
+
+export interface DesignSystemRenameArgs {
+  id: string;
+  title: string;
+}
+
+const STRING_FLAGS_WITH_VALUE = new Set(['daemon-url', 'query', 'tag', 'title']);
+
+// A separate flag value must be a real token, not the next flag. Without this
+// guard, `--title --json` would read "--json" as the title and rename the
+// system to a flag name. A leading dash means the user must use the
+// `--title=<value>` form for a title that genuinely starts with a dash.
+function isFlagValue(token: string | undefined): token is string {
+  return token !== undefined && !token.startsWith('-');
+}
+
+export function parseDesignSystemRenameArgs(args: string[]): DesignSystemRenameArgs | null {
+  let flagTitle: string | undefined;
+  const positionals: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      const key = eq >= 0 ? arg.slice(2, eq) : arg.slice(2);
+      const inlineValue = eq >= 0 ? arg.slice(eq + 1) : undefined;
+      if (key === 'title') {
+        if (inlineValue !== undefined) {
+          flagTitle = inlineValue;
+        } else if (isFlagValue(args[i + 1])) {
+          flagTitle = args[++i];
+        }
+        // else: `--title` with no real value -> leave it unset so the missing
+        // title fails usage validation below instead of swallowing a flag.
+      } else if (inlineValue === undefined && STRING_FLAGS_WITH_VALUE.has(key) && isFlagValue(args[i + 1])) {
+        i++; // consume the separate flag value so it is not read as a positional
+      }
+      continue;
+    }
+    if (arg.startsWith('-')) continue; // short flag, no positional
+    positionals.push(arg);
+  }
+  const id = positionals[0];
+  const title = (flagTitle ?? positionals.slice(1).join(' ') ?? '').trim();
+  if (!id || !title) return null;
+  return { id, title };
+}