fix(plugins): deliver browser exports from the downloads folder

claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "chatcut",
   "displayName": "ChatCut",
-  "version": "1.10.22",
+  "version": "1.10.23",
   "description": "ChatCut plugin for editable video editing and creation workflows from Claude Code.",
   "author": {
     "name": "ChatCut",
@@ -36,7 +36,8 @@
       "oauth_resource": "https://api.chatcut.io/api/external-mcp/mcp",
       "headers": {
         "x-chatcut-mcp-client": "claude_code",
-        "x-chatcut-mcp-surface": "embedded-preview"
+        "x-chatcut-mcp-surface": "embedded-preview",
+        "x-chatcut-plugin-version": "1.10.23"
       }
     }
   },

claude/README.md

@@ -33,7 +33,12 @@ The plugin includes workflow skills and one remote MCP server at
 instructions and content needed for the requested operation to ChatCut. Imported
 media, transcripts, generated assets, and edits can become part of your ChatCut
 project. Generation, translation, and transcription are processed through
-ChatCut's service.
+ChatCut's service. Requests to that server carry static headers naming the
+client, editor surface, and plugin version.
+
+Video and audio exports render in your open ChatCut editor tab and download
+through that browser. To deliver the file, the agent looks for it by name in
+your downloads folder; it does not read other files there.
 
 Optional forms load public catalog images and audio previews directly from
 `cdn.jsdelivr.net`, outside the declared MCP connection. These requests expose

claude/skills/chatcut-plugin-basics-claude/SKILL.md

@@ -75,7 +75,7 @@ Visual understanding has two distinct surfaces:
 - To inspect raw imported or attached source media, use host-native file capabilities on the source bytes when available (for example extract stills with `ffmpeg` and read the images). Do not create a temporary timeline just to inspect source assets.
 - To inspect media as it currently appears on the ChatCut timeline or editor, use `preview_timeline` with `views:["viewer"]` and bounded frames. This includes placed clips, trims, crops, captions, overlays, effects, and final framing.
 
-Export runs through the connector: load `export`, call `submit_export`, then use `track_export`. Download the finished render locally and deliver the local path, local-file preview link, and render metadata as concise text. Do not create an export preview card.
+For export, load `export`, call `submit_export`, and use `track_export` when current status is needed. Video/audio render locally by default in the connected editor tab: open the intended project/timeline in the Browser pane using the handoff below and keep that tab open until delivery finishes. In the Browser pane every finished export opens a save dialog in the Claude window, so tell the user to click Save when you submit. Deliver the file you find by name in the user's downloads folder, as `export` describes, with its local path, local-file preview link, and render metadata as concise text; do not switch to cloud rendering just to get a download URL. Do not create an export preview card.
 
 ## Data Model
 
@@ -263,7 +263,7 @@ If a ChatCut tool returns a pricing or billing URL, present it as an external br
 
 ChatCut plugin access is based on connector authentication and the user's accessible projects. Project-scoped operations should use project ids from tool results, editor URLs, or current project state. Do not guess hidden ids.
 
-There is no editor-action bridge: the agent cannot ask the editor UI to pick, relink, upload, export, or capture local files for it. Local files, attached files, browser-held files, and public URLs must enter the project through a supported media import path before timeline use:
+There is no editor-action bridge: the agent cannot ask the editor UI to pick, relink, upload, or capture local files for it. Export requests use `submit_export`, which can start the connected editor tab's local renderer. Local files, attached files, browser-held files, and public URLs must enter the project through a supported media import path before timeline use:
 
 - Browser-pane local import (`asset-import` skill: loopback helper + synthetic drop) — the sanctioned Claude Code path for handing local files to the visible editor; behaves like the user dragging from Finder.
 - Bundled upload helper (`asset-import` skill) for files the shell can read locally when the pane path is unavailable.
@@ -278,7 +278,7 @@ For raw source-frame inspection, use the local source file directly with host-na
 
 In ChatCut plugin workflows, local `ffmpeg`/`ffprobe` is for read-only source inspection and non-editorial diagnostics only: probing metadata, checking streams, or extracting still frames from locally readable source files. Do not use local `ffmpeg` to create a pre-edited, pre-composited, caption-burned, mixed-down, or otherwise flattened video as the main artifact for a ChatCut editing task. Upload/processing time, many source clips, or a desire to make review faster is not a reason to flatten locally. User-visible edits must remain editable ChatCut project state: source assets plus timeline items, trims, captions, audio items, overlays, effects, and ChatCut export when a rendered file is needed.
 
-Export and capture flows remain connector-only: do not ask the browser/editor tab to export or capture as a substitute for `submit_export`.
+Capture flows remain connector-only; do not ask the browser/editor tab to capture as a substitute.
 
 ChatCut native internal chat components do not render directly in this host. Convert those moments into ordinary chat or the `widget-forms` Claude Code adapter.
 

claude/skills/export/SKILL.md

@@ -5,14 +5,38 @@ description: Hosted ChatCut plugin sessions only (the `chatcut` MCP server). If
 
 # Export
 
-Export only when the user asks for a render, download, or final standalone deliverable. A review checkpoint normally stays as an editable ChatCut timeline.
+Export only when the user asks for a render, download, or final standalone deliverable. A review checkpoint normally stays as an editable ChatCut timeline. To check your own work, use `preview_timeline` for the picture and a `format:"audio"` export to hear sound; never make a full-resolution export for a self-check (see `verification`).
 
-Use `submit_export` with the current tool schema. Confirm the target timeline, range, resolution, codec, and format from project state and user intent; do not guess a non-active timeline. Record every returned `renderId`.
+Use `submit_export` with the current tool schema. Confirm the target timeline, range, resolution, codec, and format from project state and user intent; do not guess a non-active timeline. Give each export a short, distinctive `name`. Record every returned `renderId` and `expectedFilename`.
 
-Use `track_export` for status. It is the render-job tracker; do not use generation/transcription `track_progress` for exports. For the latest project export, use the tool's latest-render option when available rather than guessing an id.
+Video and audio render locally by default: omit `renderMode`, and the connected ChatCut editor tab renders the timeline on the user's device. Open the project through the browser handoff in the plugin basics skill, activate the requested timeline, and keep that tab open until delivery finishes. If no capable editor is connected, resolve the reported browser or timeline issue and retry locally; there is no automatic cloud retry. Media the editor can already read needs no upload for a local export.
 
-When a render completes, return its `downloadUrl`. In Claude Code, download the completed file to a collision-safe local path and provide the path, local-file preview link, and concise render metadata. In Codex, surface the completed download URL through the host's normal file/link delivery. Do not claim delivery from a queued or running render.
+Use `track_export` for browser and cloud export status; do not use generation/transcription `track_progress`. Pass the returned `renderId`, or use the latest-render option for the latest project export. A `wait` call is a single status read; honor its check-back interval. If submission timed out or its acknowledgement is uncertain, check the latest export before resubmitting so the same export does not start twice.
 
-For subtitle or NLE XML export, use the corresponding `submit_export` format and report warnings about unsupported or dropped elements. For transparent Motion Graphic delivery, use the dedicated MG export tool exposed by the current manifest and track the returned render ids.
+## Delivery
 
-If cloud rendering is blocked by media that is not remotely readable, use `asset-import` when the user permits upload. Otherwise report the blocker; do not flatten or substitute the edit locally without user intent.
+A completed browser export (`source:"browser"`) has no `downloadUrl`: the rendering tab hands the file to that browser's downloads. Completion does not prove the file was saved, so deliver it only after finding it.
+
+1. Look in the user's downloads folder (usually `~/Downloads`) for `expectedFilename`, allowing a browser suffix such as ` (1)` before the extension. Without `expectedFilename`, look for the completed `track_export` entry's `name` (the submitted name plus `.mp4`, `.webm`, or `.mp3`) and take the newest match modified after you submitted. Search for that name only; do not list or read other files there. If you cannot read files on the user's computer, give the user the file name instead.
+2. Found: give the user the path and concise render metadata. In Claude Code, also provide a local-file preview link; in Codex, show the local file through its normal file delivery. If the user asked for a specific folder, copy the file there.
+3. Not found: follow the result's `deliveryGuidance` when present, asking the user for the one step that matches the browser that rendered it, then look again:
+   - Chrome: allow "Download multiple files" from the prompt in the address bar (once; the site stays allowed), then click **Download again** in the editor's Export queue.
+   - Claude desktop Browser pane or WorkBuddy: click **Save** in the save dialog; it defaults to Downloads.
+   - Codex in-app browser: click **Download again** in the editor's Export queue.
+   - Otherwise: ask where the browser saved the file.
+
+If reading the downloads folder needs the user's approval (a macOS privacy prompt or a host permission prompt), tell them you are looking there for the exported file. If the status says the export was written to a file the user picked, that file is the delivery. Do not skip these steps to switch to cloud, and never use cloud just to get a link or to check your own work.
+
+If the user says they cannot complete the local step (opening the editor, or the download step above), or it still fails after they tried, explain the local blocker in one sentence and ask whether to export in the cloud; after they agree, export with `renderMode:"cloud"` and deliver its `downloadUrl`. Do not offer cloud before the user has had that chance. Only when cloud cannot do it either (for example 4K, media that exists only on the user's computer and cannot be uploaded, or a refused or failed cloud render), tell the user that ChatCut Desktop renders on their computer. Once open, Desktop connects itself to Codex, Claude Code, and WorkBuddy; in Codex, the ChatCut Desktop plugin's `connect-chatcut-desktop` skill covers installing it.
+
+A completed result with a `downloadUrl` (cloud video/audio, subtitles, XML): use the host's normal file/link delivery. If the user asked for a specific local path, download it there yourself. In Claude Code, download it to that path or a collision-safe local path and provide the path and a local-file preview link.
+
+Queued or running exports are not delivered. Report any warnings and their effect on the output.
+
+## Other Formats
+
+Subtitle and NLE XML exports use the corresponding `submit_export` format and can complete synchronously with a URL/path; report warnings about unsupported or dropped elements. An archive runs through the editor's bundle pipeline and may return no `renderId`; then check its progress in the editor rather than promising `track_export` support. For transparent Motion Graphic delivery, use the dedicated MG export tool exposed by the current manifest and track the returned render ids.
+
+## Cloud Rendering
+
+Use `renderMode:"cloud"` only when the user asks for it, or as the fallback above after the user agrees. If a cloud render is blocked by media that is not remotely readable, use `asset-import` when the user permits upload, or report the blocker; do not flatten or substitute the edit locally without user intent.

claude/skills/known-errors/SKILL.md

@@ -27,6 +27,6 @@ Treat the active MCP tool schema and returned structured error as authoritative.
 ## Verification And Export
 
 - A successful mutation is not visual proof; load `verification` when the result must be seen.
-- Use `track_export` for render jobs. If cloud render cannot read an asset, resolve remote readiness through `asset-import` only with user permission, or report the limitation.
+- Use `track_export` for render jobs. A failed local export is not by itself a reason to switch to cloud: fix the reported browser or timeline issue and retry locally. A blocked local export, or a completed one whose file is missing, follows the `export` fallback order: cloud only with the user's agreement, and ChatCut Desktop only when cloud cannot do it. If a cloud render cannot read an asset, resolve remote readiness through `asset-import` only with user permission, or report the limitation.
 
 On auth or project-access errors, verify the exact project id and that the editor and plugin use the same ChatCut account before attempting code or infrastructure debugging.

claude/skills/verification/SKILL.md

@@ -10,6 +10,8 @@ Use both structural and visual evidence when the requested result is visible:
 1. Re-read the affected scope with `read_project`, `preview_timeline`, `inspect_item`, `browse_assets`, or `inspect_asset` as appropriate. Use the latest response for ids, tracks, timing, and readiness.
 2. Inspect composed timeline frames through the visual tool exposed by the current manifest. Successful rendering or mutation metadata is not visual proof until the returned pixels are inspected.
 
+Check your own work the cheapest way that answers the question: `preview_timeline` frames for the picture, a `format:"audio"` export to hear audio, and a local `480p` range export to watch motion. Never make a full-resolution or cloud export for a self-check.
+
 Use local source bytes for raw source understanding when the original path is available. Use `inspect_asset` when the original is not locally available. Source frames help select moments but do not prove timeline composition; use composed timeline frames for trims, layers, captions, effects, crops, transitions, and Motion Graphics.
 
 If signed frame URLs are returned and the host cannot inspect them directly, download the complete shell-quoted URLs into a temporary directory and inspect those files. Do not report visual success from URLs alone.

codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "chatcut",
-  "version": "1.10.20",
+  "version": "1.10.21",
   "description": "ChatCut Codex plugin for editable video editing and creation workflows from Codex.",
   "author": {
     "name": "ChatCut",

codex/.mcp.json

@@ -2,7 +2,8 @@
   "mcpServers": {
     "chatcut": {
       "http_headers": {
-        "x-chatcut-mcp-surface": "codex"
+        "x-chatcut-mcp-surface": "codex",
+        "x-chatcut-plugin-version": "1.10.21"
       },
       "oauth_resource": "https://api.chatcut.io/api/external-mcp/mcp",
       "url": "https://api.chatcut.io/api/external-mcp/mcp"

codex/skills/chatcut-plugin-basics/SKILL.md

@@ -69,7 +69,7 @@ Visual understanding has two distinct surfaces:
 - To inspect raw imported or attached source media, use Codex-native visual/file capabilities on the source bytes when available. Do not create a temporary timeline just to inspect source assets.
 - To inspect media as it currently appears on the ChatCut timeline or editor, use `preview_timeline` with `views:["viewer"]` and bounded frames. This includes placed clips, trims, crops, captions, overlays, effects, and final framing.
 
-Export is a connector boundary in Codex sessions: load `export`, call `submit_export`, then use `track_export` when needed so Codex returns the finished render `downloadUrl`.
+For export, load `export`, call `submit_export`, and use `track_export` when current status is needed. Video/audio render locally by default in the connected editor tab: open the intended project/timeline through the browser handoff below and keep that tab open until delivery finishes. The delivered file is the one Codex finds by name in the user's downloads folder, as `export` describes; do not switch to cloud rendering just to get a download URL.
 
 ## Data Model
 
@@ -245,7 +245,7 @@ If a ChatCut tool returns a pricing or billing URL, present it as an external br
 
 ChatCut plugin access is based on connector authentication and the user's accessible projects. Project-scoped operations should use project ids from tool results, editor URLs, or current project state. Do not guess hidden ids.
 
-Codex cannot ask the editor UI to pick, relink, upload, export, or capture local files for it; there is no editor-action bridge. Local files, attached files, browser-held files, and public URLs must enter the project through the appropriate media import or asset acquisition path before timeline use:
+Codex cannot ask the editor UI to pick, relink, upload, or capture local files for it. Export requests use `submit_export`, which can start the connected editor tab's local renderer. Local files, attached files, browser-held files, and public URLs must enter the project through the appropriate media import or asset acquisition path before timeline use:
 
 - The `asset-import` skill for files Codex can read locally.
 - `import_media` for client-held bytes.
@@ -257,7 +257,7 @@ For raw source-frame inspection, use the local source file directly with Codex-n
 
 In ChatCut plugin workflows, local `ffmpeg`/`ffprobe` is for read-only source inspection and non-editorial diagnostics only: probing metadata, checking streams, or extracting still frames from locally readable source files. Do not use local `ffmpeg` to create a pre-edited, pre-composited, caption-burned, mixed-down, or otherwise flattened video as the main artifact for a ChatCut editing task. Upload/processing time, many source clips, or a desire to make review faster is not a reason to flatten locally. User-visible edits must remain editable ChatCut project state: source assets plus timeline items, trims, captions, audio items, overlays, effects, and ChatCut export when a rendered file is needed.
 
-Codex cannot ask the browser/editor tab to pick, relink, upload, export, or capture local files as a substitute for connector import/export flows.
+Codex cannot ask the browser/editor tab to pick, relink, upload, or capture local files as a substitute for connector import flows.
 
 ChatCut native internal chat components do not render directly in Codex. Convert those moments into ordinary Codex chat or the available structured follow-up/form capability.