@feimacode/open-design-agent-kit 0.2.0 → 0.3.0-beta.3

package/assets/claude-skills/open-design/SKILL.md

@@ -17,20 +17,46 @@ Follow this flow:
    - **Claude Code:** run `npx @feimacode/open-design-agent-kit init --tools claude` in the project root, or `claude mcp add open-design -- npx -y @feimacode/open-design-agent-kit-mcp`.
    - **Codex CLI:** run `npx @feimacode/open-design-agent-kit init --tools codex` in the project root.
    - **Any other MCP-capable agent** (Cursor, etc.): register `npx -y @feimacode/open-design-agent-kit-mcp` as a stdio MCP server using this agent's own MCP config mechanism.
+   - **Claude Desktop Chat or claude.ai** (no Open Design tools in the chat): don't make anything yet. Tell the user what's missing: connect a folder to the chat (Claude Desktop, with the Open Design plugin installed), or install the Open Design desktop extension (`open-design-<version>.mcpb` from the project's GitHub releases) to use it in Claude Desktop without a folder. Only if they want to go ahead anyway, make one self-contained HTML page and publish it with your own Artifact tool, and say it skips Open Design's design systems, checks and exports.
 
    Run the command yourself if you have shell access; otherwise tell the user the exact command to run and wait for their confirmation before continuing. Skip this step entirely once the tools are available.
+
+   **In Claude Desktop** (a chat or Cowork session with a folder the user connected), the server runs on the user's machine and starts in their home folder, and your file tools see the folder under a different path. Before any other Open Design tool, call `set_open_design_workspace` with the folder's path on the user's machine (the one `get_device_info` lists under `connectedFolders`). Every path other tools return is relative to that folder: join it onto your own path for the folder when you read or write files. If a tool says it would be working in the home folder, this is what it's asking for.
+
+   **In Claude Desktop Chat with no folder** (`use_open_design_managed_workspace` is in your tools), your own file tools, if you have any, can't reach the server's files. Call `use_open_design_managed_workspace` first with a short name for the design, and tell the user the folder's absolute path from its result (under `~/Open Design/` by default), so they can open it. Then save every design file with `write_open_design_file` (the whole file each time, under the output directory) instead of your own file tools, and register, check and export as usual. Show the design with `show_open_design_artifact` after each round; don't keep a per-round Claude artifact preview here. The managed folder is the source of truth: to edit, send the full new file through `write_open_design_file`. If the chat has a connected folder, use `set_open_design_workspace` instead.
 1. Call `list_open_design_skills` (optionally with a `query` and/or an exact `mode`) to find a skill or design template that matches what the user wants. Pick the best match by name/description/triggers, and prefer a result's `examplePrompt` (adapted to the user's specifics) over inventing your own brief when one is present and closely fits.
-2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
+2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. For **phone screens** (the Mobile app surface, or a brief like "a budgeting app that feels like Monzo"), look in the `Mobile Apps` category first, with the app's name as `query`: those systems are adapted from the real iOS apps (tab bars, sheets, iOS point sizes). Use `<app>-ios` (e.g. `spotify-ios`) for phone screens even when a web system of the same brand exists (`spotify`); the web one stays the right choice for web pages. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
 3. Call `prepare_open_design_brief` with the chosen `skillId`, optional `designSystemId` (per step 2), and the user's `brief` (their request, in their own words). This returns `instructions` to follow, a `suggestedEntryPath`, and the `designSystemId`/`designSystemName` actually used (whether explicit or defaulted from active) — mention which one it was if it wasn't obvious from the conversation. It does NOT write any files.
 4. Follow the returned `instructions` and author the artifact's entry file (plus any supporting files) yourself, using your own file-editing tools. Do not look for a separate tool to write the design content.
 5. Call `register_open_design_artifact` with the entry path, a `kind`, a `title`, and any `supportingFiles`, so the artifact is recognized and gets its manifest sidecar written.
-6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. Don't describe the screenshots to the user unless they ask. If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
+6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. **3D designs are the exception:** when the check returns a 3D review sheet, a clean check isn't the end. Get the critique the check result asks for (the `3d-object` skill's scorecard, from a subagent where your host has one), then fix, re-check and re-critique for up to three critique rounds, which replace the two-fix-round limit. Don't describe the screenshots to the user unless they ask: each run's screenshots are saved for them, and the browser preview's Checks panel shows them before and after (the result also lists the saved paths). If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
 7. Optionally call `get_open_design_artifact` to confirm what was written before telling the user it's done.
+8. After the first artifact you register in a session, call `open_open_design_preview` with its entry path, unless the user said they don't want it, so they can see it. It opens a live browser preview that reloads whenever the file changes, so don't call it again after edits; call it again only to switch to another artifact. Mention that they can click **Comment** in the preview to leave comments on elements.
+
+   **In Claude Desktop Chat** (a chat conversation, not the Code tab or a terminal), call `show_open_design_artifact` with the entry path instead: it shows the design inline in the conversation, where the user can comment and click **Ask Claude to apply**. Call it after every `register_open_design_artifact`, including after applying comments, since the inline page doesn't reload by itself. If its result says the host doesn't show MCP Apps, fall back to `open_open_design_preview` as above. Its export buttons post a request in the chat: run `export_open_design_artifact` with the format named and tell the user the path. For an exploration, pass `explorationId` to show the directions side by side; when the user picks one with **Take this one**, ask which next step they want before calling `choose_open_design_direction`. A style-tile exploration also offers **Use as design system**, which asks directly for `choose_open_design_direction` with `next: "save-design-system"`.
+
+   **Picking by eye in Claude Desktop Chat.** Two more tools are listed only where the host shows MCP Apps inline, so use them only when they are in your tool list: `show_open_design_examples` shows the remixable examples as a gallery of live previews (filter by `query`, `mode` or `surface`), and `show_open_design_design_systems` shows design systems as tiles (pass `ids` for a shortlist). Use them when the user wants to choose a starting example or a brand look and hasn't named one. Picks arrive as chat messages naming the tool to call: "Remix this" means `remix_open_design_example` with that skillId (ask what to make first if the user hasn't said); "Use this design system" means `set_active_design_system` with that id. Elsewhere, keep to `list_open_design_skills` and `list_open_design_design_systems`.
+
+<!-- claude-only -->
+**The artifact preview (Claude Code and Claude Desktop).** If you have an Artifact tool, keep one private Claude artifact per design as the user's preview, so they can look at it on claude.ai without opening files:
+- Publish it with `publish_open_design_artifact` and `provider: "claude-artifact"`, and follow what it returns: publish the file by its path, then record the link. Later publishes go to the recorded link, so the same artifact gets a new version and an open tab shows it.
+- Publish after the first successful registration and check of a design, and after each round of the user's feedback you've applied, not after every small edit. For an exploration, wait until the user picks a direction, then preview what you build from it.
+- Give the link the first time; after that, just say the preview was updated. `get_open_design_artifact` returns it as `previewUrl`.
+- Take feedback in chat. When the user wants to share, they share this same artifact from claude.ai: don't make a second one.
+- It's private, so it needs no confirmation and carries no badge. Without an Artifact tool, skip all of this.
+
+**Sync to continue elsewhere (Claude Code and Claude Desktop).** The preview artifact can also carry the design's working files (entry, manifest, comments, supporting files), so the design can be picked up on another device, in a new cloud session, or in a chat without this folder:
+- When the user says they'll continue somewhere else (their laptop, another session, a chat without the folder), offer sync once. Turn it on only after they agree: publish the preview with `sync: true`. Later preview publishes keep it up to date without asking; `sync: false` turns it off. Pass on what the instructions tell you to say: anyone they share the artifact with can read the files, and earlier versions keep their copy.
+- **Picking a design back up:** when the user gives a Claude artifact link for a design that isn't here, read the artifact with your Artifact tool (it saves the page to a file), then call `restore_open_design_artifact` with that file's path and the link. In Claude Desktop with a folder, save or copy the page into the connected folder and pass that path, as for other kit paths. If it lists files that differ from the local ones, ask which to keep before calling again with `overwrite: true`. Then carry on as usual: the next preview publish updates the same artifact.
+- **Without Open Design's tools** (a chat where you have an Artifact tool but none of the `*_open_design_*` tools): to change a synced design, read the artifact and find its `<script type="application/od-sync+json">` block. Take the text of the file named by its `entry` from `files`, edit it, and publish to the same artifact URL a page made of the edited entry followed by the block, with that file's `content` replaced by the edited text and its `sha256` set to `null`. Leave the rest of the block as it is, and keep every `</` inside it written as `<\/`. A later restore reports the file as edited outside the kit. A page published without the block holds only the preview, with nothing to edit.
+<!-- /claude-only -->
 
 When a request names a **kind of thing to make** (a prototype or landing page, mobile app, slides, document, wireframe, animation, résumé, research synthesis, data report, poster or flier, social post, diagram, 3D object), call `list_open_design_skills` with `surface` set to that kind first (`surface: "list"` shows the ids). Pick from its entries, ask only the surface's questions the request doesn't answer, and follow the surface's prompt when it names one. A request for one specific template or style still goes straight to it. Never pick an entry marked `stub: true`: it only advertises an upstream skill and has no instructions here.
 
 For **engineering documents** (an RFC, ADR, postmortem, PR explainer or changelog page), use the matching skill (`od:prototype:rfc`, `adr`, `postmortem`, `pr-explainer`, `changelog-page`). Gather the facts yourself first, from git (`git log`, `git diff`, `gh pr view` when available) and the files involved, and register what you read as `sources`. Never invent incident facts, dates or numbers: ask for them. To turn a **folder of Markdown docs** into pages, follow the docs flow (load the `open-design-docs` skill): one page per file, one template for the set, and on a re-run only the pages whose Markdown changed.
 
+For a **recurring design** ("every week", "on a schedule", "each month from the new numbers") or a prompt that says "Run the Open Design job <path>", load the `open-design-recurring` skill: the job lives in `.open-design/jobs/<id>.job.md`, each run starts with `start_open_design_job_run` (stop when it returns `skip`) and ends with `finish_open_design_job_run`, and job runs never publish publicly or post to social networks.
+
 If the request is **based on a document** (it names or attaches a report, spec, spreadsheet, PDF or existing deck, or points at repository files such as `CHANGELOG.md`, `docs/adr/`, an RFC or a metrics CSV), generate from it rather than from memory: pass those workspace paths as `sources` to `prepare_open_design_brief`. Typical examples: "a release deck from CHANGELOG.md", "an architecture review from docs/adr/", "a board update from metrics/q3.xlsx", "turn docs/q3-report.docx into a pitch". The tool extracts each document (DOCX, PPTX, XLSX, PDF with `pdftotext`, Markdown, text, CSV) to Markdown and returns instructions that make you **write an outline first and stop for the user's approval** before building. Follow them: read the extracted text by line range, write `outline.md`, show it, and wait (unless the user said to just build it). Then register with the same `sources`; its result lists numbers on the page that it couldn't find in the sources, so check and fix each one. Use `read_open_design_source` on its own to look inside a document before deciding how to use it. For a whole folder of files (such as `docs/adr/`), pass the relevant files individually (up to 10).
 
 When the user wants to **choose colors and fonts**, a palette or a type pairing, or a look for a new brand ("show me some color and type options", "what could our brand look like?"), run the exploration with the style-tile skill (`skillId: "od:design-system:style-tile"`): it makes compact tiles (palette with contrast, type specimen, components) instead of pages, 4 by default. To vary the active design system rather than replace it ("the same but warmer"), use `axis: "custom"` with one direction per variation. When the user picks a tile, call `choose_open_design_direction` with `next: "save-design-system"`: the tile's tokens are copied verbatim into the new system, which then becomes active.
@@ -39,10 +65,12 @@ If the user explicitly asks for **options to compare** ("show me three direction
 1. Call `prepare_open_design_exploration` with the `skillId` and the user's `brief` (and `count` 2–4 if they gave a number; default 3). The tool picks deliberately different directions itself: visual styles when no design system is active, layout/narrative structures when one is (so the brand is kept), or pass `axis: "custom"` with `customDirections` when the user named what should vary ("three hero concepts"). Pass `directionIds` only when the brief's tone clearly calls for specific ones (e.g. `editorial-monocle` for a magazine, `brutalist-experimental` for an art or agency site). If the result says the active design system was set aside, tell the user.
 2. For each returned direction, follow `sharedInstructions` followed by that direction's own `instructions`, write its file at its `suggestedEntryPath`, and call `register_open_design_artifact` with the `explorationId` and that direction's `directionId`. Directions are quick **sketches** (one screen, or a cover plus two slides), not full builds. If you can delegate work to sub-agents, generate the directions in parallel, passing each one `sharedInstructions` plus its own `instructions`.
 3. Call `compare_open_design_exploration` with `contactSheet: true`. If you can view images, open the contact sheet and check the directions really look different (layout and hero pattern, not just colour); regenerate any that resembles another.
-4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, briefly describe how each direction differs, and ask which one to take forward.
+4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, each on its own line, briefly describe how each direction differs, and ask which one to take forward.
 5. When the user picks one, call `choose_open_design_direction` with `next`: `build-out` (build the chosen sketch out at full fidelity), `merge` (the same, taking named aspects from other directions via `mergeFrom`, e.g. "B with A's hero"), or `save-design-system` (turn the direction into a reusable custom design system). Follow the returned `instructions` and register the result as they say.
 
-Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. This host has no live preview editor — after registering an artifact, just tell the user where it was written; there is nothing further to open automatically.
+Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. After registering or updating an artifact, tell the user where it was written, with its workspace-relative entry path (e.g. `.open-design/coffee-poster/coffee-poster.html`) on its own line: in Claude Desktop's Code tab, clicking that path opens it in the Browser pane. Don't open the HTML file in a browser yourself: `open_open_design_preview` (or `show_open_design_artifact` in Claude Desktop Chat) is how it is shown.
+
+**Comments from the preview.** When the user says they left comments (or pastes the preview's "Apply my comments" instruction, or the inline preview posts it), call `get_open_design_artifact` for that entry. Its `openComments` lists each comment's note and the element it points at (`selector`, `text`, `htmlHint`, `rect`); screenshots of up to 4 commented elements are attached as images, and every comment's `screenshot` path is listed. Change only those elements, with your own file-editing tools, then call `register_open_design_artifact` again with the comments' ids as `resolvedCommentIds` so their pins leave the preview, and run the check as in step 6. In Claude Desktop Chat, then call `show_open_design_artifact` again so the user sees the result.
 
 If the user wants to start from or riff on an existing example rather than build something new, prefer `remix_open_design_example` (skillId must have a non-empty `exampleArtifactPath`) over `prepare_open_design_brief` — it copies a working starting artifact into the project and tells you to modify it rather than regenerate from scratch. See [references/remixable-examples.md](references/remixable-examples.md) for the full list of what's available to remix, grouped by mode — check it before calling `list_open_design_skills` with `remixableOnly: true` if a quick skim already answers the question.
 
@@ -64,6 +92,10 @@ For a **poster, flyer, certificate or other print piece**, or when the user want
 
 When the user wants to **share** a design with people who don't have this project open: for a link ("publish this", "deploy it", "give me a link to send the team", "host it somewhere"), call `publish_open_design_artifact` with its `entryPath` (pass `provider` only if they already said where; otherwise it returns the choices to show them). It builds a deploy-ready folder and returns step-by-step instructions to run with your terminal under the user's own CLI login, or as a temporary no-account link. Follow them exactly: they stop for the user's explicit yes before anything goes online, and after a successful deploy you call the tool again with `published` to record the link. For a single file to attach or send ("export it as one HTML file"), call `export_open_design_artifact` with `format: "standalone"` instead; nothing goes online. The `open-design-publish` skill walks through the whole flow.
 
+<!-- claude-only -->
+If you have an Artifact tool (Claude Code or Claude Desktop), offer a Claude artifact first: `provider: "claude-artifact"` returns one file to publish by its path with your Artifact tool, private to the user until they share it from claude.ai, so there's no confirmation step; record its link the same way. PNG, PDF and PowerPoint exports stay files on disk.
+<!-- /claude-only -->
+
 For **Figma**: to turn a frame into code, call `pull_open_design_figma_frame` with the frame link ("Copy link to selection"); to put a finished design into Figma as editable layers, call `push_open_design_artifact_to_figma` with its `entryPath`. Both work through the user's Figma connection, and fall back to a token or the import plugin.
 
 When a step would **hand work to another service** (import into Canva, read or push a Figma frame, save to Google Drive, write a Notion page, share in Slack, or post to a social network), call `list_open_design_integrations` first with the `capability` (plus `platform` for a social post). Then:

package/assets/claude-skills/open-design/references/remixable-examples.md

@@ -1,6 +1,6 @@
 # Remixable Open Design examples
 
-192 vendored examples have an actual rendered starting artifact you can copy into the workspace and modify, via `remix_open_design_example` with the `id` shown below as `skillId`, instead of generating from scratch with `prepare_open_design_brief`.
+193 vendored examples have an actual rendered starting artifact you can copy into the workspace and modify, via `remix_open_design_example` with the `id` shown below as `skillId`, instead of generating from scratch with `prepare_open_design_brief`.
 
 ## prototype
 
@@ -12,6 +12,7 @@
 - **od:prototype:competitive-teardown-analyst-dossier** — Competitive Teardown — analyst dossier style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The analyst dossier style variant.
 - **od:prototype:competitive-teardown-radar-map** — Competitive Teardown — radar map style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The radar map style variant.
 - **od:prototype:competitive-teardown-war-room-grid** — Competitive Teardown — war room grid style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The war room grid style variant.
+- **od:prototype:3d-scene:example** — Courtyard at dusk — 3D scene: A small stone courtyard at dusk built from a scene spec: a Poly Haven sky, cobblestone and stone-wall textures, a brass lantern and two wooden planters (all CC0), with a 10-second camera flythrough.
 - **od:prototype:critique:example** — critique: Run a 5-dimension expert design review on any HTML artifact in the project — Philosophy / Visual hierarchy / Detail / Functionality / Innovation, each scored 0–10. Outputs a single self-contained HTML report with a radar chart, evidence-backed scores, and three lists: Keep / Fix / Quick-wins. Use when the brief asks for a "design review", "design critique", "5 维度评审", "design audit", or "what's wrong with my design".
 - **od:prototype:dashboard:example** — dashboard: Admin / analytics dashboard in a single HTML file. Fixed left sidebar, top bar with user/search, main grid of KPI cards and one or two charts. Use when the brief asks for a "dashboard", "admin", "analytics", or "control panel" screen.
 - **od:prototype:data-report:example** — Data Visualization Report: Turns CSV, Excel, or JSON data into a polished visual report page.

package/assets/claude-skills/open-design-campaign/SKILL.md

@@ -50,6 +50,10 @@ Ask which channels the campaign needs, unless the brief says. Offer this menu (f
 
 Call `export_open_design_artifact` with `presets` set to the chosen formats, `data: "<campaign folder>/copy.csv"`, `nameField: "locale"` and `checkOnly: true`. Fix every **error** in the findings (per shape and per row). For a shape that looks wrong or has errors, call `adapt_open_design_artifact` with those format ids and tune it in the same file. Tiny ad sizes usually need their own `@container` rule: headline and call to action only. Repeat until there are no errors.
 
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish this design as its private artifact preview (the master) once every shape is clean: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->
+
 ## 5. Other pieces (optional)
 
 If the user wants a landing page or an email, build each with its own skill (`od:prototype:saas-landing` or `od:prototype:web-prototype`, and `od:prototype:email-campaign`) using the same design system and the first row of the copy deck. Register each with the same `collectionId` and `collectionName`, and `screenRole` `landing` or `email`. Check each with `check_open_design_artifact`.
@@ -58,4 +62,7 @@ If the user wants a landing page or an email, build each with its own skill (`od
 
 1. Export the master: `export_open_design_artifact` with the same `presets`, `data` and `nameField: "locale"`, plus `campaignSheet: true`. This writes one image (or print PDF) per shape per row, named `<name>-<locale>-<format>`, and `exports/campaign-sheet.png`, which shows every shape and every other piece, with a red dot on any that still has errors. If the export says the outputs are over the limit, export one batch of locales at a time.
 2. If there's an email, export it with `format: "email"` (and `baseUrl` once its images are hosted).
-3. Show the user the campaign sheet, list the files per channel, and mention anything still flagged.
+3. Show the user the campaign sheet, list the files per channel, and mention anything still flagged. The export also writes `exports/campaign-sheet.json`, which lists each tile in sheet order with its errors.
+<!-- claude-only -->
+4. In Claude Desktop Chat, call `show_open_design_artifact` with the master's `entryPath` and `campaign: true`: the sheet shows inline tile by tile, with each tile's errors. A page-type piece opens when clicked, and "Fix this piece" posts the tile and its errors in the chat; fix that piece, export again with `campaignSheet: true`, and show the sheet again. If the result says the host doesn't show MCP Apps, just show `exports/campaign-sheet.png` as above.
+<!-- /claude-only -->

package/assets/claude-skills/open-design-deck-from-source/SKILL.md

@@ -34,6 +34,10 @@ Build from the approved outline. Use numbers, names and quotes exactly as in the
 
 Call `register_open_design_artifact` with the same `sources`. For every number its result says it couldn't find in the sources, check it: fix it, or say in that slide's notes how it was derived. Register again after fixing.
 
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish this design as its private artifact preview once it's registered: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->
+
 ## 6. Hand it over
 
 Tell the user where the deck and its outline are, mention any images reused from the documents, and offer to export it as PowerPoint or PDF with `export_open_design_artifact`. PowerPoint exports include the speaker notes.

package/assets/claude-skills/open-design-explore/SKILL.md

@@ -44,3 +44,7 @@ Give the user the comparison page path (it opens in any browser straight from th
 ## 5. Take the choice forward
 
 Call `choose_open_design_direction` with the `explorationId`, the chosen `directionId`, `next` (`build-out`, `merge` with `mergeFrom`, or `save-design-system`) and the user's own adjustments as `notes`. Follow the returned `instructions` and register the result as they say.
+
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish the result as its private artifact preview (the built-out design, not the sketches) once it's registered: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->

package/assets/claude-skills/open-design-new/SKILL.md

@@ -28,4 +28,12 @@ Ask only the questions the request doesn't already answer, all at once, in one s
 - If the surface has a `prompt` (for example `open-design-poster` or `open-design-social-post`), follow that flow from its first step with the user's request as the brief. In Copilot Chat it's the `/` command of the same name; in Claude Code and Codex it's the skill of the same name.
 - Otherwise pick the entry that best fits the request. Entries come in curated order: the recipe first, then its remixable example when there is one. To start from a rendered example (an entry with an `exampleArtifactPath`), call `remix_open_design_example`; otherwise call `prepare_open_design_brief` with its id and the brief, and follow the general Open Design flow: write the files, register the artifact, then check it with `check_open_design_artifact` before saying it's done.
 
+<!-- claude-only -->
+**Picking by eye (Claude Desktop Chat).** When the user wants to choose a starting example from pictures, and `show_open_design_examples` is in your tool list (it is listed only where the host shows MCP Apps inline), call it with `surface` set to the chosen id instead of listing entries in text. "Remix this" posts the pick in the chat; then call `remix_open_design_example` with the skillId it names. Without that tool, keep to the text list above.
+<!-- /claude-only -->
+
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish this design as its private artifact preview once it's registered and checked: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->
+
 Never pick an entry marked `stub: true`.

package/assets/claude-skills/open-design-poster/SKILL.md

@@ -60,6 +60,10 @@ Call `register_open_design_artifact` with the entry path, kind `html`, a title,
 
 Call `check_open_design_artifact` with the entry path. It returns the poster as an image plus preflight findings. Fix every **error** in its findings (text cut off, overlapping or in the bleed, a QR code that doesn't decode), and fix warnings where you reasonably can (sizes that don't scale with the poster, small type, low contrast, low-resolution images). Look at the image too: the headline should dominate and nothing important should be cramped or cut. Check again until there are no errors (at most two fix rounds; tell the user about anything left).
 
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish this design as its private artifact preview once the check is clean: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->
+
 ## 6. Other shapes
 
 When the user wants other sizes, or before the final export of a print piece, call `export_open_design_artifact` with `shapeSheet: true` and `checkOnly: true` (add `presets` with just the shapes they care about, or leave it out for every shape). It writes one image of the poster at each shape, marking shapes with errors; show it to the user. If you can view images, look at it too: the headline should dominate every shape and nothing important should be cropped.

package/assets/claude-skills/open-design-preview/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: "open-design-preview"
+description: Open an Open Design artifact in a live browser preview, where you can see it update as it changes, click elements to comment on them, and compare check screenshots before and after — use whenever the user asks to see, show, preview or open an Open Design artifact, or wants to comment on one visually
+argument-hint: which design to show (e.g. "the landing page"); leave empty for the most recent one or a list
+---
+
+<!-- generated:curated-entry -->
+
+Show an Open Design artifact in the browser preview.
+
+Request: "$ARGUMENTS" — or, if that is empty, the user's request in this conversation (if it isn't clear, ask the user: "Which design should the preview show?")
+
+1. Work out which artifact is meant. Registered artifacts are the files under the Open Design output folder (default `.open-design/`) that have a `.artifact.json` file next to them. Use the one the request names; if it names none, use the one you made or changed most recently in this conversation. If that still doesn't settle it, call `open_open_design_preview` without `entryPath`: the preview then lists every design, and the user picks there.
+2. Call `open_open_design_preview` with that `entryPath`.
+3. Tell the user in one or two sentences what happened, using the tool's result: where the preview opened (or the URL to open, when it couldn't open a window), that it reloads by itself when the design changes, and that they can click **Comment**, then an element, to leave a comment, and **Send to agent** when they want you to apply them.

package/assets/claude-skills/open-design-publish/SKILL.md

@@ -23,6 +23,9 @@ If the request names a design, find its entry file (`get_open_design_artifact`,
 
 Call `publish_open_design_artifact` with the `entryPath`. Pass `provider` only if the user already said where:
 
+<!-- claude-only -->
+- `claude-artifact`: only if you have an Artifact tool (Claude Code or Claude Desktop). A private Claude artifact the user can open, and share from claude.ai when they want to. Offer it first when you have one. Add `sync: true` only if the user agreed to carry the design's working files in it, to continue on another device or session; it's stored, so later publishes keep it until `sync: false`.
+<!-- /claude-only -->
 - `netlify-temporary` or `cloudflare-temporary`: no account, the link lasts about an hour unless claimed
 - `netlify`, `vercel`, `cloudflare-pages` or `github-pages`: the user's own account, a link that lasts
 
@@ -30,8 +33,16 @@ Without a provider, the tool returns the choices: show them to the user and call
 
 ## 4. Follow the returned instructions exactly
 
+<!-- claude-only -->
+For `claude-artifact`, they name one file: publish it by its path with your Artifact tool, without reading it into the conversation, and mention what they say won't load in the artifact. There's no confirmation step, since the artifact stays private until the user shares it. For the other providers:
+<!-- /claude-only -->
+
 They check the host's CLI, then **stop for the user's explicit yes** before anything goes online. That stop is mandatory: say what goes out, who can see it, how long it lasts, and that the small "Made with Open Design" footer badge is included unless they ask for `badge: false`. Deploy only the bundle folder the tool names.
 
 ## 5. Finish
 
 Give the user the link. For a temporary link, also give the claim URL and when it expires, for them only. Then record it by calling `publish_open_design_artifact` again with `published`, as the instructions show, so a later publish updates the same site.
+
+<!-- claude-only -->
+For an artifact, also say it's private until they share it from claude.ai. With sync on, also say what the instructions name: anyone it's shared with can read the design's working files, and earlier versions keep their copy. To pick a synced design up elsewhere, read the artifact with your Artifact tool and pass the saved page's path and the link to `restore_open_design_artifact`.
+<!-- /claude-only -->

package/assets/claude-skills/open-design-recurring/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: "open-design-recurring"
+description: Set up a design that rebuilds itself on a schedule (a weekly report deck, next week's social posts, a refreshed one-pager), or run one such job — one job file, one supervised run, then a one-line prompt for the scheduler — use whenever the user wants a design made again every day, every week or every month, on a schedule, or as a recurring job, or when a prompt says "Run the Open Design job <path>", even if they don't mention Open Design
+argument-hint: what to make and how often (e.g. "a KPI deck from data/kpis.csv every Monday"), or "Run the Open Design job <path>"
+---
+
+<!-- generated:curated-entry -->
+
+Recurring Open Design jobs: one job file describes what to make each period, and a scheduler runs it.
+
+Request: "$ARGUMENTS" — or, if that is empty, the user's request in this conversation (if it isn't clear, ask the user: "What should be rebuilt, from which sources, and how often?")
+
+If the request names a job file (".open-design/jobs/<id>.job.md", usually "Run the Open Design job …"), go to **Run**. Otherwise go to **Set up**.
+
+If `start_open_design_job_run` isn't one of your tools (VS Code has no scheduler, so it doesn't offer it), you can still write the job file in **Set up**, but say that scheduled runs need Claude Code or Claude Desktop with the Open Design MCP server, and stop there.
+
+## Run
+
+1. Call `start_open_design_job_run` with the job path (and `runNow: true` only when the person asked for a fresh run in this conversation, never from a scheduled prompt).
+2. If it returns `skip`, report the reason in one line and stop. Make no changes.
+3. If it asks you to check out the state branch, do that and call it again.
+4. Otherwise follow its steps in order. This run is unattended: don't ask questions, never publish publicly and never post to social networks.
+5. End with `finish_open_design_job_run`, follow the steps it returns, and reply with its summary.
+
+## Set up
+
+### 1. Agree the job
+
+With the person, settle:
+
+- **What** to make, and with which recipe: `open-design-deck-from-source` for a report deck or one-pager from data, `open-design-social-post` for a batch of posts, `open-design-poster` for a print piece, `open-design-docs` for pages from Markdown.
+- **Sources**: workspace files (a CSV, a CHANGELOG, a report), or data a connector pulls (a sheet in Google Drive, a Notion database). Each connector source needs a `snapshot` workspace path the pulled data is saved to, so every number stays traceable.
+- **How often**: `day`, `week` or `month`, and the time zone (an IANA name such as `Europe/Berlin`).
+- **One file or one per period**: `mode: update` rewrites the same design each period (a living report); `mode: series` keeps one file per period, with `{period}` in the target (a weekly social batch).
+- **Outputs**: export formats (`pdf`, `png`, `pptx`, `standalone` …). PNG, PDF, PowerPoint and video need a browser; runs without one record them as skipped.
+- **Delivery**: `preview` (the private Claude artifact, the default), `pr` (a pull request from the state branch), or a connector action such as "Post the preview link to #design in Slack". Never a public publish or a social post: the scheduler's prompt can't stand in for the person's yes, so the job tools refuse those.
+- **Checks**: `best-effort` (default) or `required`, which holds back the PR and connector deliveries when a run had no browser for the visual check.
+
+### 2. Write the job file
+
+Write `.open-design/jobs/<id>.job.md` (the id is lowercase with hyphens and matches the file name):
+
+```markdown
+---
+id: weekly-kpis
+title: Weekly KPI deck
+recipe: open-design-deck-from-source
+period: week
+timezone: Europe/Berlin
+mode: update
+target: .open-design/weekly-kpis/weekly-kpis.html
+outputs: [pdf]
+sources:
+  - data/kpis.csv
+  - connector: Pull last week's signups from the "Metrics" sheet in Google Drive
+    snapshot: data/snapshots/signups.csv
+deliver: [preview, pr]
+checks: best-effort
+---
+
+A five-slide KPI update for the leadership team: headline numbers first, then
+signups, revenue and churn against last week, with one takeaway per slide.
+```
+
+The brief is the body: write everything a run needs to decide without asking, since nobody answers questions mid-run.
+
+### 3. One supervised run
+
+Run it now, with the person watching: call `start_open_design_job_run` and follow **Run**. Here you may ask questions; fold the answers back into the brief so later runs don't need them. If the start result lists problems by field, fix the job file and start again.
+
+<!-- claude-only -->
+When the run publishes the private preview, add its link to the job's frontmatter as `preview: { url: "<link>" }`, so every later run republishes the same artifact.
+<!-- /claude-only -->
+
+### 4. Schedule it
+
+Give the person the exact prompt to save, and the steps for where they work:
+
+> Run the Open Design job `.open-design/jobs/<id>.job.md`
+
+- **Claude Code cloud scheduled task** (claude.ai/code/routines, or `/schedule`): runs without their computer. The repository needs the Open Design MCP server and skills committed (`npx @feimacode/open-design-agent-kit init --tool claude`, then commit `.mcp.json` and `.claude/skills`, and the job file). There's no browser by default, so PNG, PDF and PowerPoint outputs are skipped unless the environment's setup script installs one. The run log lives on the state branch `claude/open-design-job-<id>`. Schedule a few minutes past the hour, mid-period.
+- **Claude Desktop local scheduled task** (Code tab, Routines, New, Local): runs on their computer with local files and Chrome, only while the app is open and the computer is awake; a missed run gets one catch-up run, which the job skips if the period is already done. Tell them to click **Run now** once and approve each tool, so later runs aren't stopped by a prompt.
+- **`/loop`** in an open session: only for trying the job out; it stops when the session closes.
+- **Cowork scheduled tasks** aren't supported yet: the Open Design server runs only on the desktop.
+
+Point them to the [recurring jobs guide](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/recurring-jobs.md) for details.

package/assets/claude-skills/open-design-social-post/SKILL.md

@@ -44,6 +44,10 @@ Author the files yourself with your own file-editing tools, following the return
 
 Call `register_open_design_artifact` with the entry path, kind `html`, a title, `sourceSkillId` set to the row's `skillId`, and the same `format` you passed to the brief, so the export can find the right size.
 
+<!-- claude-only -->
+**Artifact preview.** If you have an Artifact tool, publish this design as its private artifact preview once it's registered and checked: call `publish_open_design_artifact` with `provider: "claude-artifact"` and follow what it returns. Publish again after each round of feedback you apply; it goes to the same artifact. Give the link once, then just say the preview was updated.
+<!-- /claude-only -->
+
 ## 4. Export
 
 - **Image formats**: call `export_open_design_artifact` with the entry path and the row's export arguments. If its preflight reports errors (text cut off, a card that isn't the canvas size) or it returns warnings (failed fonts or images, over budget), fix the artifact and export again. Before exporting, call `check_open_design_artifact` to see the post as an image with its preflight findings, without writing files; fix every error first.

package/assets/codex-skills/open-design/SKILL.md

@@ -19,20 +19,32 @@ Follow this flow:
    - **Claude Code:** run `npx @feimacode/open-design-agent-kit init --tools claude` in the project root, or `claude mcp add open-design -- npx -y @feimacode/open-design-agent-kit-mcp`.
    - **Codex CLI:** run `npx @feimacode/open-design-agent-kit init --tools codex` in the project root.
    - **Any other MCP-capable agent** (Cursor, etc.): register `npx -y @feimacode/open-design-agent-kit-mcp` as a stdio MCP server using this agent's own MCP config mechanism.
+   - **Claude Desktop Chat or claude.ai** (no Open Design tools in the chat): don't make anything yet. Tell the user what's missing: connect a folder to the chat (Claude Desktop, with the Open Design plugin installed), or install the Open Design desktop extension (`open-design-<version>.mcpb` from the project's GitHub releases) to use it in Claude Desktop without a folder. Only if they want to go ahead anyway, make one self-contained HTML page and publish it with your own Artifact tool, and say it skips Open Design's design systems, checks and exports.
 
    Run the command yourself if you have shell access; otherwise tell the user the exact command to run and wait for their confirmation before continuing. Skip this step entirely once the tools are available.
+
+   **In Claude Desktop** (a chat or Cowork session with a folder the user connected), the server runs on the user's machine and starts in their home folder, and your file tools see the folder under a different path. Before any other Open Design tool, call `set_open_design_workspace` with the folder's path on the user's machine (the one `get_device_info` lists under `connectedFolders`). Every path other tools return is relative to that folder: join it onto your own path for the folder when you read or write files. If a tool says it would be working in the home folder, this is what it's asking for.
+
+   **In Claude Desktop Chat with no folder** (`use_open_design_managed_workspace` is in your tools), your own file tools, if you have any, can't reach the server's files. Call `use_open_design_managed_workspace` first with a short name for the design, and tell the user the folder's absolute path from its result (under `~/Open Design/` by default), so they can open it. Then save every design file with `write_open_design_file` (the whole file each time, under the output directory) instead of your own file tools, and register, check and export as usual. Show the design with `show_open_design_artifact` after each round; don't keep a per-round Claude artifact preview here. The managed folder is the source of truth: to edit, send the full new file through `write_open_design_file`. If the chat has a connected folder, use `set_open_design_workspace` instead.
 1. Call `list_open_design_skills` (optionally with a `query` and/or an exact `mode`) to find a skill or design template that matches what the user wants. Pick the best match by name/description/triggers, and prefer a result's `examplePrompt` (adapted to the user's specifics) over inventing your own brief when one is present and closely fits.
-2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
+2. There is an **active design system**, persisted per project (a local `.open-design/config.json` file). If the user mentions a brand, company, industry, or visual style that differs from what's active, call `list_open_design_design_systems` (optionally with a `query` and/or an exact `category` — call with no arguments first to see categories, and check each result's `active` flag) to find the right one, and pass its id explicitly to `prepare_open_design_brief` — doing so also makes it the new active one going forward, so you don't need to re-specify it on later requests in this project. For **phone screens** (the Mobile app surface, or a brief like "a budgeting app that feels like Monzo"), look in the `Mobile Apps` category first, with the app's name as `query`: those systems are adapted from the real iOS apps (tab bars, sheets, iOS point sizes). Use `<app>-ios` (e.g. `spotify-ios`) for phone screens even when a web system of the same brand exists (`spotify`); the web one stays the right choice for web pages. If the user hasn't mentioned any direction, just omit `designSystemId` from `prepare_open_design_brief` and it will silently use whatever is currently active (or none). Only call `set_active_design_system` directly when the user wants to pin a look before generating anything ("let's use the Starbucks look from now on").
 3. Call `prepare_open_design_brief` with the chosen `skillId`, optional `designSystemId` (per step 2), and the user's `brief` (their request, in their own words). This returns `instructions` to follow, a `suggestedEntryPath`, and the `designSystemId`/`designSystemName` actually used (whether explicit or defaulted from active) — mention which one it was if it wasn't obvious from the conversation. It does NOT write any files.
 4. Follow the returned `instructions` and author the artifact's entry file (plus any supporting files) yourself, using your own file-editing tools. Do not look for a separate tool to write the design content.
 5. Call `register_open_design_artifact` with the entry path, a `kind`, a `title`, and any `supportingFiles`, so the artifact is recognized and gets its manifest sidecar written.
-6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. Don't describe the screenshots to the user unless they ask. If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
+6. Call `check_open_design_artifact` with the entry path before telling the user it's done (after creating an artifact, and again after a substantial edit). It renders the artifact and returns screenshots plus preflight findings: fix every **error**, then look at the screenshots for what the checks can't measure — balance, hierarchy, crowded or empty areas, text over busy imagery — and fix what's clearly wrong. Re-check after fixing, but stop after two fix rounds and tell the user about anything left. **3D designs are the exception:** when the check returns a 3D review sheet, a clean check isn't the end. Get the critique the check result asks for (the `3d-object` skill's scorecard, from a subagent where your host has one), then fix, re-check and re-critique for up to three critique rounds, which replace the two-fix-round limit. Don't describe the screenshots to the user unless they ask: each run's screenshots are saved for them, and the browser preview's Checks panel shows them before and after (the result also lists the saved paths). If it returns `no-browser`, skip checking and tell the user once that visual checks need Chrome, Edge or Chromium installed.
 7. Optionally call `get_open_design_artifact` to confirm what was written before telling the user it's done.
+8. After the first artifact you register in a session, call `open_open_design_preview` with its entry path, unless the user said they don't want it, so they can see it. It opens a live browser preview that reloads whenever the file changes, so don't call it again after edits; call it again only to switch to another artifact. Mention that they can click **Comment** in the preview to leave comments on elements.
+
+   **In Claude Desktop Chat** (a chat conversation, not the Code tab or a terminal), call `show_open_design_artifact` with the entry path instead: it shows the design inline in the conversation, where the user can comment and click **Ask Claude to apply**. Call it after every `register_open_design_artifact`, including after applying comments, since the inline page doesn't reload by itself. If its result says the host doesn't show MCP Apps, fall back to `open_open_design_preview` as above. Its export buttons post a request in the chat: run `export_open_design_artifact` with the format named and tell the user the path. For an exploration, pass `explorationId` to show the directions side by side; when the user picks one with **Take this one**, ask which next step they want before calling `choose_open_design_direction`. A style-tile exploration also offers **Use as design system**, which asks directly for `choose_open_design_direction` with `next: "save-design-system"`.
+
+   **Picking by eye in Claude Desktop Chat.** Two more tools are listed only where the host shows MCP Apps inline, so use them only when they are in your tool list: `show_open_design_examples` shows the remixable examples as a gallery of live previews (filter by `query`, `mode` or `surface`), and `show_open_design_design_systems` shows design systems as tiles (pass `ids` for a shortlist). Use them when the user wants to choose a starting example or a brand look and hasn't named one. Picks arrive as chat messages naming the tool to call: "Remix this" means `remix_open_design_example` with that skillId (ask what to make first if the user hasn't said); "Use this design system" means `set_active_design_system` with that id. Elsewhere, keep to `list_open_design_skills` and `list_open_design_design_systems`.
 
 When a request names a **kind of thing to make** (a prototype or landing page, mobile app, slides, document, wireframe, animation, résumé, research synthesis, data report, poster or flier, social post, diagram, 3D object), call `list_open_design_skills` with `surface` set to that kind first (`surface: "list"` shows the ids). Pick from its entries, ask only the surface's questions the request doesn't answer, and follow the surface's prompt when it names one. A request for one specific template or style still goes straight to it. Never pick an entry marked `stub: true`: it only advertises an upstream skill and has no instructions here.
 
 For **engineering documents** (an RFC, ADR, postmortem, PR explainer or changelog page), use the matching skill (`od:prototype:rfc`, `adr`, `postmortem`, `pr-explainer`, `changelog-page`). Gather the facts yourself first, from git (`git log`, `git diff`, `gh pr view` when available) and the files involved, and register what you read as `sources`. Never invent incident facts, dates or numbers: ask for them. To turn a **folder of Markdown docs** into pages, follow the docs flow (load the `open-design-docs` skill): one page per file, one template for the set, and on a re-run only the pages whose Markdown changed.
 
+For a **recurring design** ("every week", "on a schedule", "each month from the new numbers") or a prompt that says "Run the Open Design job <path>", load the `open-design-recurring` skill: the job lives in `.open-design/jobs/<id>.job.md`, each run starts with `start_open_design_job_run` (stop when it returns `skip`) and ends with `finish_open_design_job_run`, and job runs never publish publicly or post to social networks.
+
 If the request is **based on a document** (it names or attaches a report, spec, spreadsheet, PDF or existing deck, or points at repository files such as `CHANGELOG.md`, `docs/adr/`, an RFC or a metrics CSV), generate from it rather than from memory: pass those workspace paths as `sources` to `prepare_open_design_brief`. Typical examples: "a release deck from CHANGELOG.md", "an architecture review from docs/adr/", "a board update from metrics/q3.xlsx", "turn docs/q3-report.docx into a pitch". The tool extracts each document (DOCX, PPTX, XLSX, PDF with `pdftotext`, Markdown, text, CSV) to Markdown and returns instructions that make you **write an outline first and stop for the user's approval** before building. Follow them: read the extracted text by line range, write `outline.md`, show it, and wait (unless the user said to just build it). Then register with the same `sources`; its result lists numbers on the page that it couldn't find in the sources, so check and fix each one. Use `read_open_design_source` on its own to look inside a document before deciding how to use it. For a whole folder of files (such as `docs/adr/`), pass the relevant files individually (up to 10).
 
 When the user wants to **choose colors and fonts**, a palette or a type pairing, or a look for a new brand ("show me some color and type options", "what could our brand look like?"), run the exploration with the style-tile skill (`skillId: "od:design-system:style-tile"`): it makes compact tiles (palette with contrast, type specimen, components) instead of pages, 4 by default. To vary the active design system rather than replace it ("the same but warmer"), use `axis: "custom"` with one direction per variation. When the user picks a tile, call `choose_open_design_direction` with `next: "save-design-system"`: the tile's tokens are copied verbatim into the new system, which then becomes active.
@@ -41,10 +53,12 @@ If the user explicitly asks for **options to compare** ("show me three direction
 1. Call `prepare_open_design_exploration` with the `skillId` and the user's `brief` (and `count` 2–4 if they gave a number; default 3). The tool picks deliberately different directions itself: visual styles when no design system is active, layout/narrative structures when one is (so the brand is kept), or pass `axis: "custom"` with `customDirections` when the user named what should vary ("three hero concepts"). Pass `directionIds` only when the brief's tone clearly calls for specific ones (e.g. `editorial-monocle` for a magazine, `brutalist-experimental` for an art or agency site). If the result says the active design system was set aside, tell the user.
 2. For each returned direction, follow `sharedInstructions` followed by that direction's own `instructions`, write its file at its `suggestedEntryPath`, and call `register_open_design_artifact` with the `explorationId` and that direction's `directionId`. Directions are quick **sketches** (one screen, or a cover plus two slides), not full builds. If you can delegate work to sub-agents, generate the directions in parallel, passing each one `sharedInstructions` plus its own `instructions`.
 3. Call `compare_open_design_exploration` with `contactSheet: true`. If you can view images, open the contact sheet and check the directions really look different (layout and hero pattern, not just colour); regenerate any that resembles another.
-4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, briefly describe how each direction differs, and ask which one to take forward.
+4. Show the user the comparison page path (`compareFile`; it opens in any browser straight from the file system and shows every direction side by side) and the contact sheet path, each on its own line, briefly describe how each direction differs, and ask which one to take forward.
 5. When the user picks one, call `choose_open_design_direction` with `next`: `build-out` (build the chosen sketch out at full fidelity), `merge` (the same, taking named aspects from other directions via `mergeFrom`, e.g. "B with A's hero"), or `save-design-system` (turn the direction into a reusable custom design system). Follow the returned `instructions` and register the result as they say.
 
-Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. This host has no live preview editor — after registering an artifact, just tell the user where it was written; there is nothing further to open automatically.
+Generated artifacts land under the project's Open Design output directory (default `.open-design/`) so they stay visible and trackable in version control like any other project file. After registering or updating an artifact, tell the user where it was written, with its workspace-relative entry path (e.g. `.open-design/coffee-poster/coffee-poster.html`) on its own line: in Claude Desktop's Code tab, clicking that path opens it in the Browser pane. Don't open the HTML file in a browser yourself: `open_open_design_preview` (or `show_open_design_artifact` in Claude Desktop Chat) is how it is shown.
+
+**Comments from the preview.** When the user says they left comments (or pastes the preview's "Apply my comments" instruction, or the inline preview posts it), call `get_open_design_artifact` for that entry. Its `openComments` lists each comment's note and the element it points at (`selector`, `text`, `htmlHint`, `rect`); screenshots of up to 4 commented elements are attached as images, and every comment's `screenshot` path is listed. Change only those elements, with your own file-editing tools, then call `register_open_design_artifact` again with the comments' ids as `resolvedCommentIds` so their pins leave the preview, and run the check as in step 6. In Claude Desktop Chat, then call `show_open_design_artifact` again so the user sees the result.
 
 If the user wants to start from or riff on an existing example rather than build something new, prefer `remix_open_design_example` (skillId must have a non-empty `exampleArtifactPath`) over `prepare_open_design_brief` — it copies a working starting artifact into the project and tells you to modify it rather than regenerate from scratch. See [references/remixable-examples.md](references/remixable-examples.md) for the full list of what's available to remix, grouped by mode — check it before calling `list_open_design_skills` with `remixableOnly: true` if a quick skim already answers the question.
 

package/assets/codex-skills/open-design/references/remixable-examples.md

@@ -1,6 +1,6 @@
 # Remixable Open Design examples
 
-192 vendored examples have an actual rendered starting artifact you can copy into the workspace and modify, via `remix_open_design_example` with the `id` shown below as `skillId`, instead of generating from scratch with `prepare_open_design_brief`.
+193 vendored examples have an actual rendered starting artifact you can copy into the workspace and modify, via `remix_open_design_example` with the `id` shown below as `skillId`, instead of generating from scratch with `prepare_open_design_brief`.
 
 ## prototype
 
@@ -12,6 +12,7 @@
 - **od:prototype:competitive-teardown-analyst-dossier** — Competitive Teardown — analyst dossier style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The analyst dossier style variant.
 - **od:prototype:competitive-teardown-radar-map** — Competitive Teardown — radar map style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The radar map style variant.
 - **od:prototype:competitive-teardown-war-room-grid** — Competitive Teardown — war room grid style: Positioning map, feature matrix, pricing comparison and opportunity windows: turns competitor research into a product decision report. The war room grid style variant.
+- **od:prototype:3d-scene:example** — Courtyard at dusk — 3D scene: A small stone courtyard at dusk built from a scene spec: a Poly Haven sky, cobblestone and stone-wall textures, a brass lantern and two wooden planters (all CC0), with a 10-second camera flythrough.
 - **od:prototype:critique:example** — critique: Run a 5-dimension expert design review on any HTML artifact in the project — Philosophy / Visual hierarchy / Detail / Functionality / Innovation, each scored 0–10. Outputs a single self-contained HTML report with a radar chart, evidence-backed scores, and three lists: Keep / Fix / Quick-wins. Use when the brief asks for a "design review", "design critique", "5 维度评审", "design audit", or "what's wrong with my design".
 - **od:prototype:dashboard:example** — dashboard: Admin / analytics dashboard in a single HTML file. Fixed left sidebar, top bar with user/search, main grid of KPI cards and one or two charts. Use when the brief asks for a "dashboard", "admin", "analytics", or "control panel" screen.
 - **od:prototype:data-report:example** — Data Visualization Report: Turns CSV, Excel, or JSON data into a polished visual report page.

package/assets/codex-skills/open-design-campaign/SKILL.md

@@ -57,4 +57,4 @@ If the user wants a landing page or an email, build each with its own skill (`od
 
 1. Export the master: `export_open_design_artifact` with the same `presets`, `data` and `nameField: "locale"`, plus `campaignSheet: true`. This writes one image (or print PDF) per shape per row, named `<name>-<locale>-<format>`, and `exports/campaign-sheet.png`, which shows every shape and every other piece, with a red dot on any that still has errors. If the export says the outputs are over the limit, export one batch of locales at a time.
 2. If there's an email, export it with `format: "email"` (and `baseUrl` once its images are hosted).
-3. Show the user the campaign sheet, list the files per channel, and mention anything still flagged.
+3. Show the user the campaign sheet, list the files per channel, and mention anything still flagged. The export also writes `exports/campaign-sheet.json`, which lists each tile in sheet order with its errors.

package/assets/codex-skills/open-design-preview/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: open-design-preview
+description: Open an Open Design artifact in a live browser preview, where you can see it update as it changes, click elements to comment on them, and compare check screenshots before and after — use whenever the user asks to see, show, preview or open an Open Design artifact, or wants to comment on one visually
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Show an Open Design artifact in the browser preview.
+
+Request: the rest of the user's message (if there is none, ask the user: "Which design should the preview show?")
+
+1. Work out which artifact is meant. Registered artifacts are the files under the Open Design output folder (default `.open-design/`) that have a `.artifact.json` file next to them. Use the one the request names; if it names none, use the one you made or changed most recently in this conversation. If that still doesn't settle it, call `open_open_design_preview` without `entryPath`: the preview then lists every design, and the user picks there.
+2. Call `open_open_design_preview` with that `entryPath`.
+3. Tell the user in one or two sentences what happened, using the tool's result: where the preview opened (or the URL to open, when it couldn't open a window), that it reloads by itself when the design changes, and that they can click **Comment**, then an element, to leave a comment, and **Send to agent** when they want you to apply them.

package/assets/codex-skills/open-design-recurring/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: open-design-recurring
+description: Set up a design that rebuilds itself on a schedule (a weekly report deck, next week's social posts, a refreshed one-pager), or run one such job — one job file, one supervised run, then a one-line prompt for the scheduler — use whenever the user wants a design made again every day, every week or every month, on a schedule, or as a recurring job, or when a prompt says "Run the Open Design job <path>", even if they don't mention Open Design
+---
+
+<!-- generated:open-design-agent-kit -->
+
+Recurring Open Design jobs: one job file describes what to make each period, and a scheduler runs it.
+
+Request: the rest of the user's message (if there is none, ask the user: "What should be rebuilt, from which sources, and how often?")
+
+If the request names a job file (".open-design/jobs/<id>.job.md", usually "Run the Open Design job …"), go to **Run**. Otherwise go to **Set up**.
+
+If `start_open_design_job_run` isn't one of your tools (VS Code has no scheduler, so it doesn't offer it), you can still write the job file in **Set up**, but say that scheduled runs need Claude Code or Claude Desktop with the Open Design MCP server, and stop there.
+
+## Run
+
+1. Call `start_open_design_job_run` with the job path (and `runNow: true` only when the person asked for a fresh run in this conversation, never from a scheduled prompt).
+2. If it returns `skip`, report the reason in one line and stop. Make no changes.
+3. If it asks you to check out the state branch, do that and call it again.
+4. Otherwise follow its steps in order. This run is unattended: don't ask questions, never publish publicly and never post to social networks.
+5. End with `finish_open_design_job_run`, follow the steps it returns, and reply with its summary.
+
+## Set up
+
+### 1. Agree the job
+
+With the person, settle:
+
+- **What** to make, and with which recipe: `open-design-deck-from-source` for a report deck or one-pager from data, `open-design-social-post` for a batch of posts, `open-design-poster` for a print piece, `open-design-docs` for pages from Markdown.
+- **Sources**: workspace files (a CSV, a CHANGELOG, a report), or data a connector pulls (a sheet in Google Drive, a Notion database). Each connector source needs a `snapshot` workspace path the pulled data is saved to, so every number stays traceable.
+- **How often**: `day`, `week` or `month`, and the time zone (an IANA name such as `Europe/Berlin`).
+- **One file or one per period**: `mode: update` rewrites the same design each period (a living report); `mode: series` keeps one file per period, with `{period}` in the target (a weekly social batch).
+- **Outputs**: export formats (`pdf`, `png`, `pptx`, `standalone` …). PNG, PDF, PowerPoint and video need a browser; runs without one record them as skipped.
+- **Delivery**: `preview` (the private Claude artifact, the default), `pr` (a pull request from the state branch), or a connector action such as "Post the preview link to #design in Slack". Never a public publish or a social post: the scheduler's prompt can't stand in for the person's yes, so the job tools refuse those.
+- **Checks**: `best-effort` (default) or `required`, which holds back the PR and connector deliveries when a run had no browser for the visual check.
+
+### 2. Write the job file
+
+Write `.open-design/jobs/<id>.job.md` (the id is lowercase with hyphens and matches the file name):
+
+```markdown
+---
+id: weekly-kpis
+title: Weekly KPI deck
+recipe: open-design-deck-from-source
+period: week
+timezone: Europe/Berlin
+mode: update
+target: .open-design/weekly-kpis/weekly-kpis.html
+outputs: [pdf]
+sources:
+  - data/kpis.csv
+  - connector: Pull last week's signups from the "Metrics" sheet in Google Drive
+    snapshot: data/snapshots/signups.csv
+deliver: [preview, pr]
+checks: best-effort
+---
+
+A five-slide KPI update for the leadership team: headline numbers first, then
+signups, revenue and churn against last week, with one takeaway per slide.
+```
+
+The brief is the body: write everything a run needs to decide without asking, since nobody answers questions mid-run.
+
+### 3. One supervised run
+
+Run it now, with the person watching: call `start_open_design_job_run` and follow **Run**. Here you may ask questions; fold the answers back into the brief so later runs don't need them. If the start result lists problems by field, fix the job file and start again.
+
+### 4. Schedule it
+
+Give the person the exact prompt to save, and the steps for where they work:
+
+> Run the Open Design job `.open-design/jobs/<id>.job.md`
+
+- **Claude Code cloud scheduled task** (claude.ai/code/routines, or `/schedule`): runs without their computer. The repository needs the Open Design MCP server and skills committed (`npx @feimacode/open-design-agent-kit init --tool claude`, then commit `.mcp.json` and `.claude/skills`, and the job file). There's no browser by default, so PNG, PDF and PowerPoint outputs are skipped unless the environment's setup script installs one. The run log lives on the state branch `claude/open-design-job-<id>`. Schedule a few minutes past the hour, mid-period.
+- **Claude Desktop local scheduled task** (Code tab, Routines, New, Local): runs on their computer with local files and Chrome, only while the app is open and the computer is awake; a missed run gets one catch-up run, which the job skips if the period is already done. Tell them to click **Run now** once and approve each tool, so later runs aren't stopped by a prompt.
+- **`/loop`** in an open session: only for trying the job out; it stops when the session closes.
+- **Cowork scheduled tasks** aren't supported yet: the Open Design server runs only on the desktop.
+
+Point them to the [recurring jobs guide](https://github.com/feimacode/open-design-agent-kit/blob/main/docs/guides/recurring-jobs.md) for details.