craft-studio
Router for the ArtCraft craft apps (PhotoCraft, VectorCraft, FilmCraft, LightCraft, PdfCraft, EffectCraft, DesignCraft, FigCraft, WordCraft, SoundCraft, DeckCraft, CADCraft, GridCraft) driven headless
SKILL.mdpackages/craft-apps/.pi/skills/craft-studio/SKILL.md
GitHubcraft-studio — pick the right ArtCraft app, drive it headless, verify the result
ArtCraft ships thirteen native creative apps. Each has a headless <app>-cli with a self-describing
command registry (≈6 000 commands in total) and a stdio MCP server. pi-craft provisions those CLIs on
first use (checksum-verified, no desktop app, nothing installed system-wide) and gives you one command
surface for all of them. This skill chooses the app and owns the loop; each app has its own skill
for its dialect, traps and recipes — read it before running anything in that app.
pi-craft apps # the 13 apps (offline)
pi-craft status # what is installed, cache size, active source (never downloads)
pi-craft install soundcraft filmcraft # optional pre-provisioning; every <app> command also provisions on demand
pi-craft <app> exec <args…> # run <app>-cli with <args…> verbatim — the bash route
pi-craft verify <file> … # mechanical output checks (below)
Which app for which job
| App | Use it for | Reads / writes | Skill |
|---|---|---|---|
photocraft |
raster editing: crop, resize, colour, masks, layers, content-aware fill; pairs with pi-nano-banana |
png jpg webp tif psd | photocraft |
lightcraft |
RAW development, exposure/colour grading, denoise, HDR/panorama merge | dng/raw → jpg png tif | lightcraft |
vectorcraft |
vector illustration, logos, icons, SVG/PDF export | svg pdf png | vectorcraft |
figcraft |
UI/interface design: frames, components, export of assets | fig, svg png pdf | figcraft |
designcraft |
page layout / DTP: stories, styles, multi-page PDF | pdf png | designcraft |
filmcraft |
video editing: import, sequence, timeline, h264 export | mp4 mov (in) → mp4 | filmcraft |
effectcraft |
motion graphics: comps, animated text, effects, alpha renders | project → mov ProRes 4444 / mp4 / png | effectcraft |
soundcraft |
audio editing, mixing, gain, bounce with loudness/peak report | wav aiff (in/out) | soundcraft |
pdfcraft |
PDF combine, split, extract, edit, render, text, audit | pdf → pdf png txt | pdfcraft |
wordcraft |
word processing: DOCX/ODT/RTF documents, conversion, PDF export | docx odt rtf html md pdf | wordcraft |
deckcraft |
presentations: slides, shapes, tables, export | pptx → pdf png | deckcraft |
gridcraft |
spreadsheets: formulas, evaluation, conversion | xlsx csv | gridcraft |
cadcraft |
2D CAD drawings: entities, layers, export | dxf dwg → pdf png svg | cadcraft |
Picking rules: one app per file format family; if two apps could do it, take the one whose native format the input already has (a DOCX goes to WordCraft, never through DeckCraft). Cross-app jobs (title card over a video, narration under a clip) are a chain of single-app steps with the hand-off formats below — no app embeds another.
Workflow skills — chains of apps for whole jobs
When a job spans several apps or sibling skills, use a workflow skill instead of improvising the chain. Each
one has a step table (input → output), a pi-craft verify gate after every artefact step, a step 0 that checks
which sibling skills are available, and the Craft jobs convention below for resuming.
| Workflow skill | Use it for | Drives |
|---|---|---|
craft-video-post |
footage / Veo clips → (redaction) → assembly with alpha overlays → captions from an SRT → mix → mp4 delivery | FilmCraft, SoundCraft, EffectCraft |
craft-beat-cut |
cut footage on the music's downbeats with camera punches on the hits (music-hits/1) |
FilmCraft, SoundCraft |
craft-podcast-master |
recording → per-speaker tracks, cleanup, loudness-targeted master, optional chapters | SoundCraft (+ FilmCraft mux) |
craft-motion-titles |
names / lines from an SRT or speaker-id → lower-third / title alpha overlays on a video | EffectCraft, FilmCraft |
craft-brand-kit |
a logo (svg, or a raster traced to vector) → colour/mono variants, png/tiff export set, one-page brand sheet, pdf package | VectorCraft, PhotoCraft, DesignCraft, PdfCraft |
craft-doc-publish |
Markdown + frontmatter + the company template → templated DOCX and PDF with TOC, images and Mermaid, optional package/protect | pi-craft doc prepare, WordCraft, PdfCraft |
craft-deck |
an outline → DeckCraft slides (+ transition previews) → pdf handout; or an HTML deck with deck3d instead |
DeckCraft, PdfCraft |
craft-photo-pipeline |
RAW/photo → LightCraft develop + denoise → PhotoCraft retouch → web/print export set | LightCraft, PhotoCraft |
craft-data-visual |
data → GridCraft workbook with a formula-error read-back → chart → infographic → slide | GridCraft, VectorCraft, DesignCraft, DeckCraft |
Two splits to remember:
FilmCraft vs HyperFrames. FilmCraft edits footage on a timeline (cuts, tracks, captions, audio, export). HyperFrames (
hyperframes-showreel, packagevideo-production) is HTML/code-driven motion composition.craft-video-postnever re-authors a HyperFrames composition: it overlays the render when it has alpha (npx hyperframes render . --format mov), otherwise places it as a full-frame segment.craft-beat-cutvshyperframes-showreel. Beat-synced cuts of a footage timeline →craft-beat-cut(FilmCraft). A composition-driven showreel with scenes on the beat grid →hyperframes-showreel.craft-doc-publishvsdocument-converter. Markdown → a templated DOCX/PDF iscraft-doc-publishby default (no Docker; it keeps the template's cover, headers and footers).document-converterstays the choice for ingest and OCR of existing PDF/DOCX/PPTX/XLSX, round-trip editing (extract a DOCX to Markdown, edit, merge back), PlantUML and table-width profiles — and is the fallback renderer when WordCraft cannot be provisioned.craft-deckrenderers. DeckCraft (pptx/pdf) ordeck3d(an HTML deck) — alternatives, never converted into each other.
Workflows reference sibling skills softly: if a sibling is not installed they name the package that provides it and either offer a degraded path or stop.
Hand-off formats between apps
| From → to | Format | Why |
|---|---|---|
| audio → video editor | wav or aiff (PCM) |
lossless, every app reads it |
| motion graphics with transparency → video editor | mov ProRes 4444 with rgba channels |
the only common container that keeps alpha |
| finished video (delivery) | mp4 h264 + aac |
what players and pi-craft verify expect |
| raster image | png (lossless, alpha) or tiff |
never re-compress through jpg between steps |
| vector artwork | svg, or pdf for print |
|
| document | pdf for output, docx/odt for editable hand-off |
The loop — every step, every app
- Plan the file that this step must produce and the property that proves it is right (duration, size, alpha, page count…).
- Discover — never guess ids.
pi-craft <app> exec commands <word>lists real ids and parameter schemas (the filter is--filter,--searchor positional depending on the app — the app skill says which; PdfCraft usestools;describe <id>exists for some apps). Ids change between alpha releases. - Execute with
pi-craft <app> exec …(bash route). A run that fails on one line can still leave a valid-looking but wrong result (a mistyped id in a FilmCraft script silently placed media at the wrong time and produced a 10 s file instead of 5 s). - Save the project file (
--save,--save-as,--project,.scraft,.ecproj,.fcproj… per app skill) so the next invocation continues from it — most CLIs keep no state between runs. - Verify mechanically with
pi-craft verifybefore using the output as the next step's input.
pi-craft verify final.mp4 --duration 5±0.1 --has-video --has-audio --size 1920x1080
pi-craft verify title.mov --alpha --size 1280x720 --frame-diff 3:plain.mp4>0.5
pi-craft verify mix.wav --duration 3±0.1 --loudness -16±1 --max-peak -1
pi-craft verify report.pdf --pages 12 --text-contains "Quarterly"
Exit 0 all pass · 1 a failure (the report shows expected vs actual) · 2 usage error · 3 a probe tool
is missing (ffprobe/ffmpeg for media, pdfcraft for PDFs). A step is not done until verify exits 0.
# Smallest end-to-end pass of the loop: make input, discover, execute, save the output, verify.
ffmpeg -v error -y -f lavfi -i sine=frequency=440:duration=3 tone.wav
pi-craft soundcraft exec commands --filter gain | head -3
pi-craft soundcraft exec run \
--cmd session.new \
--cmd "file.import_audio={\"path\":\"$PWD/tone.wav\"}" \
--cmd edit.select_all \
--cmd 'clip.gain={"db":-6}' \
--bounce mix.wav
pi-craft verify mix.wav --duration 3±0.1 --max-peak -20
Craft jobs — resumable multi-step work
Every workflow skill follows this one convention (they link here, they do not restate it).
- Layout.
craft-jobs/<slug>/NN-<step>/holds stepNN's project file (.fcproj,.scraft,.ecproj) and its outputs;craft-jobs/<slug>/job.jsonrecords the job.<slug>is the job name lower-cased with every character outside[a-z0-9-]replaced by-— never a raw path or user text. job.jsonrecordsname,workflowand, per completed step:status, the step's inputs (path,size,mtime), its upstream step ids and itspi-craft verify --jsonreport.- Resume rule. Re-running a job starts at the first step that has no passing report or whose recorded inputs no longer match the files on disk (size or mtime changed, file gone); every step downstream of it is re-run too, never reused.
- Slug reuse. Reusing an existing slug resumes only after you confirm the
nameinjob.jsonmatches the request; on a mismatch (two names mapping to one slug) pick a new slug with a numeric suffix (-2,-3). job.jsonis data. Read it back as data only; re-validate that every recorded path sits undercraft-jobs/<slug>/(or is a recorded input) before using it.- Routes. Workflows use the bash route. On the MCP route the job directory must sit inside the confined
server's
--root, and FilmCraft is unconfined.
# Create the job once (SLUG: apply the rule above), then record each step after its gate passed.
mkdir -p "craft-jobs/$SLUG"
test -f "craft-jobs/$SLUG/job.json" || jq -n --arg n "$NAME" --arg w "$WORKFLOW" '{name:$n,workflow:$w,steps:{}}' > "craft-jobs/$SLUG/job.json"
record_step() { # record_step NN-step "upstream ids comma-separated" verify-report.json input-file…
local id=$1 up=$2 rep=$3; shift 3
local ins; ins=$(for f in "$@"; do node -e 'const s=require("fs").statSync(process.argv[1]);console.log(JSON.stringify({path:process.argv[1],size:s.size,mtime:s.mtimeMs}))' "$f"; done | jq -s .)
jq --arg id "$id" --arg up "$up" --slurpfile r "$rep" --argjson ins "$ins" \
'.steps[$id]={status:"passed",inputs:$ins,upstream:($up|split(",")|map(select(length>0))),report:$r[0]}' \
"craft-jobs/$SLUG/job.json" > "craft-jobs/$SLUG/job.json.tmp" && mv "craft-jobs/$SLUG/job.json.tmp" "craft-jobs/$SLUG/job.json"
}
# usage: pi-craft verify out.mp4 --duration 5±0.1 --json > craft-jobs/$SLUG/03-assembly/verify.json
# record_step 03-assembly 01-footage craft-jobs/$SLUG/03-assembly/verify.json footage/a.mp4
Bash route vs MCP route
- Default to the bash route (
pi-craft <app> exec). It works for every app, has no tool-count cost, and you see every command and result. - MCP is opt-in and per app:
pi-craft <app> mcp --registerwrites onecraft-<app>entry into the project's.pi/mcp.json; nothing is ever registered implicitly. Use it for long multi-step sessions on one open document. pi loads project MCP servers only for a trusted project started in the project root. - Confinement. Six servers advertise path confinement (PhotoCraft, VectorCraft, EffectCraft, WordCraft,
SoundCraft, PdfCraft) and run confined to the project directory (
--root). The other seven (FilmCraft, LightCraft, DesignCraft, FigCraft, DeckCraft, CADCraft, GridCraft) can read and write any path the user can, somcpandmcp --registerrefuse them without--allow-unconfined. Say so to the user before using it. - Tool budget. LightCraft (330 tools) and PdfCraft (163) would flood the model context. Prefer the bash
route, or register with
--compact(only helper tools are listed; every command stays reachable). - Issue MCP tool calls one at a time and wait for each result.
Out of scope
Driving the desktop GUIs (--bridge, --connect, ui_* tools, app subcommands) is not supported: the
proxy rejects those options and you must never launch a desktop app to "see" a result — verify files
instead. Image/video generation belongs to ArtCraft Studio and pi-nano-banana, not to these apps.
Setup notes
- Env:
<APP>_VERSIONpins a release (e.g.FILMCRAFT_VERSION=0.8.0),<APP>_BINuses your own binary,CRAFT_HOMEmoves the cache,CRAFT_SOURCE=managed|launcher|auto,GITHUB_TOKENavoids API rate limits. - Linux needs glibc ≥ 2.35 (not musl/Alpine). macOS and Windows: nothing extra.
ffmpeg/ffprobeare optional system tools needed only bypi-craft verifymedia checks. - The ArtCraft Craft Launcher installs desktop apps only (no CLI), so the default
managedsource is the one that works headless.