asset-import

name	asset-import
description	Import local or attached media files, readable user-provided paths, existing ChatCut assets, and public media URLs into a ChatCut project from WorkBuddy.

Asset Import for WorkBuddy

Choose the source path

1. First inspect the targeted project's asset library with read_project view:"assets"; reuse a matching existing asset when possible.
2. For a public media URL, use the current ChatCut download/import tool and verify the returned asset.
3. For a local attachment or path readable by WorkBuddy, use the package command chatcut-upload-media with an import_media session.
4. If WorkBuddy cannot read the file or run the local upload dependencies, fall back to manual upload in the already-open ChatCut editor, then re-read the project assets.

Attachments in the initial prompt

When the user includes source media in the first prompt, treat that attachment as the intended source and retain its readable local path for the automated upload attempt.

If no project is targeted yet, create or target the intended project according to the expert's project-selection rules. Before checking local upload dependencies, ask WorkBuddy to surface the project using the exact returned browserHandoff.url when present, otherwise the returned editorUrl, preserving every query parameter. A present_files.previewed entry only confirms that WorkBuddy accepted the request, not that its browser UI appeared. In the next user-visible message, always include the clean returned editorUrl as a clickable “Open ChatCut editor” fallback and say to use it if the editor did not open automatically. Never expose the handoff URL or its launch/authentication parameters to the user.

Read view:"assets" before import and retain the existing asset ids. This baseline lets you identify files added manually without asking the user for an asset id.

Do not bulk-import a large folder without editorial need. When selection matters, inspect a bounded sample and choose the originals needed for the requested edit. Do not locally concatenate, pre-trim, burn captions, or flatten source files before importing them.

chatcut-upload-media is the only supported local upload command in this WorkBuddy expert. WorkBuddy adds the package bin/ directory to PATH, so invoke the command by name from any working directory. Do not search the filesystem for upload-media.mjs, do not guess the plugin installation directory, and never use direct-uploader, curl, or a hand-written presigned-upload flow.

Local file flow

chatcut-upload-media requires the package command itself, node, ffmpeg, and ffprobe on PATH. Check that all four commands are executable before creating a short-lived import session. For example, use command -v on macOS/Linux or Get-Command in PowerShell.

If the source path is unreadable or any of these commands is unavailable, do not install dependencies, ask the user to install FFmpeg, search for hidden package files, or improvise another upload protocol. Use the manual editor upload fallback below. The local command is a convenience path; missing host dependencies must not block the editing workflow.

1. Call import_media with {"action":"create_session"}.
2. Use the returned short-lived import token and endpoint. The token is only for this helper; never print it to the user or save it in the package.
3. Run the package command directly. On Windows PowerShell:

chatcut-upload-media --token "<token>" --endpoint "<endpoint>" "C:\absolute\path\source-1.mp4" "C:\absolute\path\source-2.wav" --json-out "$env:TEMP\chatcut-imports.json"

On macOS or Linux:

chatcut-upload-media --token "<token>" --endpoint "<endpoint>" "/absolute/path/source-1.mp4" "/absolute/path/source-2.wav" --json-out "${TMPDIR:-/tmp}/chatcut-imports.json"

4. Read the JSON output and use each returned assetId. A registered placeholder may be available before all bytes finish uploading.
5. Use track_progress with target:"transcription" before transcript/caption work, and target:"upload" before byte-dependent frame decode or cloud export.
6. Verify with read_project view:"assets".

The command invokes this package's official skills/asset-import/scripts/upload-media.mjs helper. If chatcut-upload-media is not found, do not search for the helper, ask the user to reinstall the package, or improvise a second upload protocol. Use the manual editor upload fallback.

If the user says the source must not be uploaded, stop before this flow and explain that the hosted WorkBuddy connector cannot perform a cloud-ready ChatCut edit with those bytes.

Manual editor upload fallback

Use this fallback when WorkBuddy has the attachment or local path but cannot complete the automated local upload.

1. Ensure a concrete project is created or targeted and record the current asset ids with read_project view:"assets".
2. Hand the editor to the user. Use the exact returned browserHandoff.url when present, otherwise editorUrl, and call WorkBuddy's present_files, preserving every query parameter. Treat this only as an attempt to open the editor. In the next user-visible message, always include the clean returned editorUrl as a clickable “Open ChatCut editor” fallback and say to use it if the editor did not open automatically. Never show the handoff URL or claim that the browser appeared based only on present_files.previewed.
3. Tell the user that WorkBuddy cannot transfer the local file automatically in the current environment. Ask them to drag the original file into the editor's media/assets panel or use its upload button. Mention the known local path when it helps them find the file.
4. Stop and wait for the user to confirm that the editor upload is complete. Do not use present_files on the local media as an upload attempt; that tool only opens or presents files.
5. After the user replies, read view:"assets" again and identify newly added assets by comparing against the baseline. Do not ask the user for an assetId. If no new asset is visible yet, say that plainly and let the user finish or retry the editor upload.
6. Once the asset appears, use track_progress for transcription or upload state as required, then continue the requested edit.