@writepanda/mcp 1.216.0 → 1.218.0

package/bin/server.mjs

@@ -626,8 +626,15 @@ const MOTION_ELEMENT_PROPS = {
 	sound: {
 		type: "string",
 		enum: ["auto", "none", "pop", "whoosh", "hit", "tick", "bell"],
-		description: "Role for project_compose_soundtrack.",
+		description: "Role for project_compose_soundtrack (not a sound of its own; that is soundUrl).",
 	},
+	soundUrl: {
+		type: ["string", "null"],
+		description:
+			"The element's own sound, kept on it through moves and trims: bundled:sound/<id> or a path; null/none = silent. Omit = default graphic sound (click on chip/steps/count/lowerThird/highlight/endCard/sticker, or the workspace default).",
+	},
+	soundVolume: { type: "number", description: "0-1." },
+	soundBeats: { type: "boolean", description: "steps: play soundUrl as each item steps in." },
 	zIndex: {
 		type: "number",
 		description:
@@ -815,18 +822,18 @@ const TOOLS = [
 	{
 		name: "system_get_transcription_provider",
 		description:
-			"Transcription provider (local default, deepgram, elevenlabs; ready = cloud ones with a key). Local is weak on Tamil / Telugu / Kannada / Malayalam.",
+			"Transcription provider (local default, apple, deepgram, elevenlabs; ready = cloud ones with a key + whether Apple speech runs here; apple.languages = what Apple can do on this Mac, fillers:false = leaves out um/uh). Local is weak on Tamil / Telugu / Kannada / Malayalam; Apple doesn't support them.",
 		inputSchema: { type: "object", properties: {} },
 		command: "system.get-transcription-provider",
 	},
 	{
 		name: "system_set_transcription_provider",
 		description:
-			"Set the transcription provider. Cloud needs its key saved (else falls back to local), uploads audio and bills the user: ASK first.",
+			"Set the transcription provider. apple = Apple's on-device speech (Macs; macOS 26 + Apple silicon: 4-9x faster than local for English/German/Spanish/French/Italian/Portuguese/Chinese/Japanese/Korean, keeps fewer fillers; no Tamil/Telugu/Kannada/Malayalam), needs a chosen language, only when the user wants it. Cloud needs its key saved (else falls back to local), uploads audio and bills the user: ASK first.",
 		inputSchema: {
 			type: "object",
 			properties: {
-				provider: { type: "string", enum: ["local", "deepgram", "elevenlabs"] },
+				provider: { type: "string", enum: ["local", "apple", "deepgram", "elevenlabs"] },
 			},
 			required: ["provider"],
 		},
@@ -917,7 +924,7 @@ const TOOLS = [
 	{
 		name: "connector_list",
 		description:
-			"List MCP connectors and their state. If the one needed isn't connected, tell the user its howToConnect line; you cannot connect connectors.",
+			"List MCP connectors and their state. If the one needed isn't connected, tell the user its howToConnect line; you cannot connect connectors. status \"connected, last check failed\" (connected:false, lastCheck with reason, host and fix) means PandaStudio's own last use of it failed.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1085,7 +1092,7 @@ const TOOLS = [
 	{
 		name: "workspace_capture_brand",
 		description:
-			"Capture a brand kit (colours, fonts, logo, screenshots) from a website. ASYNC: { jobId }; first run is slow.",
+			"Capture a brand kit (colours, fonts, logo, screenshots) from a website using the app’s bundled browser. ASYNC: { jobId }; requires site network access, no npm CLI setup.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1136,12 +1143,39 @@ const TOOLS = [
 								motionBlurAmount: { type: "number" },
 							},
 						},
+						graphicSound: {
+							type: ["object", "null"],
+							description: "Default graphic sound for new graphics.",
+							properties: {
+								soundUrl: { type: ["string", "null"] },
+								volume: { type: "number" },
+								scope: { type: "string", enum: ["cards", "all"] },
+							},
+						},
 					},
 				},
 			},
 		},
 		command: "workspace.set-project-defaults",
 	},
+	{
+		name: "workspace_set_default_graphic_sound",
+		description:
+			"Set the sound NEW motion graphics and motion elements start with (existing ones keep theirs). none = silent; scope cards (default) or all; reset = built-in click on cards and callouts.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				sound: {
+					type: "string",
+					description: 'bundled:sound/<id>, a bundled id, a path, or "none".',
+				},
+				volume: { type: "number", description: "0-1." },
+				scope: { type: "string", enum: ["cards", "all"] },
+				reset: { type: "boolean" },
+			},
+		},
+		command: "workspace.set-default-graphic-sound",
+	},
 
 	// ── YouTube publishing (v1.19) ──────────────────────────────────
 	// Connect Google accounts per workspace, publish exports, edit
@@ -1436,10 +1470,48 @@ const TOOLS = [
 		},
 		command: "project.show",
 	},
+	{
+		name: "matte_status",
+		description:
+			"Read baked matte status: none, baking with percent, ready; engine (vision | rvm), quality, fallbackReason.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clip: { type: "string" },
+				source: { type: "string", enum: ["camera", "main"] },
+			},
+			required: ["clip"],
+		},
+		command: "matte.status",
+	},
+	{
+		name: "matte_bake",
+		description:
+			"Bake a camera/source matte. Returns jobId; use job_wait to await, job_cancel to cancel. engine auto = Apple Vision on macOS 12+ (about 1 s per video-second), RVM elsewhere; an explicit engine/quality becomes the source's matte and rebakes if different.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clip: { type: "string" },
+				source: { type: "string", enum: ["camera", "main"] },
+				engine: { type: "string", enum: ["auto", "vision", "rvm"] },
+				quality: {
+					type: "string",
+					enum: ["accurate", "balanced"],
+					description: "Apple Vision only. balanced is ~3x faster with softer edges.",
+				},
+			},
+			required: ["id", "clip"],
+		},
+		command: "matte.bake",
+	},
 	{
 		name: "project_read",
 		description:
-			"Full project JSON plus clipStates (per clip: transcribed, audioCleaned), editedDurationMs and isInActiveWorkspace (false: tell the user before export). Clips: project.mainTrack.clips; regions: project.editor.*Regions. Pass project.revision as expectedRevision on writes.",
+			"Full project JSON plus clipStates (per clip: transcribed, audioCleaned, matte.main/camera bake status), editedDurationMs and isInActiveWorkspace (false: tell the user before export). Clips: project.mainTrack.clips; regions: project.editor.*Regions. Pass project.revision as expectedRevision on writes.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1455,7 +1527,8 @@ const TOOLS = [
 	},
 	{
 		name: "project_new",
-		description: "Create a project; withMedia imports videos as clips.",
+		description:
+			"Create a project; withMedia imports videos as clips, or AUDIO files (MP3 / WAV / M4A / AAC / FLAC / OGG) as an audio-only podcast project. speakers = one audio file per speaker (host first): a multi-speaker audio clip synced by audio.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1463,7 +1536,17 @@ const TOOLS = [
 				parentProjectId: { type: "string" },
 				originKind: { type: "string", enum: ["agent", "recipe"] },
 				name: { type: "string" },
-				withMedia: { type: "array", items: { type: "string" } },
+				withMedia: {
+					type: "array",
+					items: { type: "string" },
+					description: "Videos, or audio files (an audio-only project). Not both.",
+				},
+				speakers: {
+					type: "array",
+					items: { type: "string" },
+					description: "2-4 audio files, one per speaker, host first.",
+				},
+				autoSync: { type: "boolean", description: "speakers: sync by audio (default true)." },
 			},
 			required: ["name"],
 		},
@@ -1472,17 +1555,23 @@ const TOOLS = [
 	{
 		name: "project_fork_from_shot",
 		description:
-			"Fork an export's AI shot (entry.generatedShots) into a new 9:16 project over the shot's range; keeps timing edits, drops all overlays. revision_mismatch = source edited since: confirm, then force.",
+			"Fork an AI shot into a new 9:16 project over the shot's range; keeps timing edits, drops all overlays. From an export: exportId + shotId (entry.generatedShots). From an unexported project: projectId + shotId (export_generate_shots with projectId), or projectId + sourceStartMs/sourceEndMs + title. revision_mismatch = source edited since export: confirm, then force.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				folderId: { type: ["string", "null"], description: "Folder UUID" },
-				exportId: { type: "string" },
+				exportId: { type: "string", description: "Export entry id (or use projectId)." },
+				projectId: { type: "string", description: "Project id or path (no export needed)." },
 				shotId: { type: "string" },
+				sourceStartMs: {
+					type: "number",
+					description: "With projectId, no shotId: shot start on the SOURCE timeline (ms).",
+				},
+				sourceEndMs: { type: "number", description: "With projectId, no shotId: shot end (ms)." },
+				title: { type: "string", description: "Title for a source-range fork." },
 				aspectRatio: { type: "string", description: "Default 9:16." },
 				force: { type: "boolean" },
 			},
-			required: ["exportId", "shotId"],
 		},
 		command: "project.fork-from-shot",
 	},
@@ -1503,13 +1592,13 @@ const TOOLS = [
 	{
 		name: "project_add_clip",
 		description:
-			"Append or insert a video clip, or a still image shown for durationMs, on the main track (later content moves with it). atMs (edited time) inserts at that moment, splitting the clip under it; add replaceToMs to replace [atMs, replaceToMs) with the clip (e.g. a re-recorded take).",
+			"Append or insert a video clip, an audio file (audio-only projects only), or a still image shown for durationMs, on the main track (later content moves with it). atMs (edited time) inserts at that moment, splitting the clip under it; add replaceToMs to replace [atMs, replaceToMs) with the clip (e.g. a re-recorded take).",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
-				media: { type: "string", description: "Video or image path." },
+				media: { type: "string", description: "Video, audio (audio-only project) or image path." },
 				durationMs: { type: "number", description: "Images, default 5000." },
 				fill: { type: "boolean", description: "Images: cover the frame (default true)." },
 				webcam: { type: "string", description: "Guest source: a two-speaker podcast clip." },
@@ -1548,7 +1637,7 @@ const TOOLS = [
 	{
 		name: "project_add_podcast_clip",
 		description:
-			"Combine 2-4 separate recordings (media = host, guests in order) into one podcast clip, auto-synced by audio.",
+			"Combine 2-4 separate recordings (media = host, guests in order) into one podcast clip, auto-synced by audio. All audio files = an audio-only multi-speaker clip.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1725,7 +1814,7 @@ const TOOLS = [
 	{
 		name: "project_add_motion_graphic",
 		description:
-			"Place a motion graphic, video or image as an overlay, from fromJob (a render job) or file. Plays a click SFX unless soundUrl is null.",
+			"Place a motion graphic, video or image as an overlay, from fromJob (a render job) or file. It owns its sound (moves with it): omit soundUrl for the default graphic sound (a click on card/callout templates or the workspace default), null = silent.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1737,6 +1826,11 @@ const TOOLS = [
 				atMs: { type: "number", description: "Default end of timeline." },
 				soundUrl: { type: ["string", "null"], description: "bundled:sound/<id>; null = silent." },
 				soundVolume: { type: "number", description: "0-1." },
+				soundBeats: {
+					type: "boolean",
+					description:
+						"Beat templates (flowchart, comparison, list, glow-steps): sound on each step.",
+				},
 				loop: { type: "boolean", description: "Else hold the last frame." },
 				muted: { type: "boolean", description: "Own audio; default true." },
 				volume: { type: "number", description: "0-1, when unmuted." },
@@ -2528,6 +2622,27 @@ const TOOLS = [
 		},
 		command: "project.track-focus-face",
 	},
+	{
+		name: "project_track_region",
+		description:
+			"Track this area: a focus region follows whatever is inside its box (a moving window, a dragged card, a scrolling email) forward and backward from atMs, by correlation tracking; stops where the content is lost and holds there. Writes keyframes (tracking: area). Needs the media engine. Returns { keyframes, samples, lostForwardAtMs, lostBackwardAtMs }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionId: { type: "string", description: "editor.spotlightRegions[].id" },
+				atMs: {
+					type: "number",
+					description: "Edited ms of the frame the box marks. Default the region start.",
+				},
+				stepMs: { type: "number", minimum: 20, maximum: 1000, description: "Default 66." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["regionId"],
+		},
+		command: "project.track-region",
+	},
 	{
 		name: "project_set_overlay_mask",
 		description:
@@ -2686,6 +2801,44 @@ const TOOLS = [
 		},
 		command: "project.apply-edit-plan",
 	},
+	{
+		name: "audio_preview_mix",
+		description:
+			"Render final export audio only to temporary .m4a plus description and voice/music/SFX stem RMS/masking flags. Edited-time range, default whole project, max 10 minutes. Async: job.wait.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				fromMs: { type: "number", minimum: 0 },
+				toMs: { type: "number", minimum: 0 },
+			},
+			required: ["id"],
+		},
+		command: "audio.preview-mix",
+	},
+	{
+		name: "audio_describe",
+		description:
+			"Numeric audio evidence for a local audio/video path OR project id/range: loudness, true peak, clipping, silence, speech/music estimate, tempo/beats, attacks, spectral brightness and summary. No song/sound identification. Async: job.wait; first 10 minutes maximum.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: { type: "string" },
+				id: { type: "string" },
+				fromMs: { type: "number", minimum: 0 },
+				toMs: { type: "number", minimum: 0 },
+			},
+			oneOf: [
+				{
+					required: ["path"],
+					not: { anyOf: [{ required: ["id"] }, { required: ["fromMs"] }, { required: ["toMs"] }] },
+				},
+				{ required: ["id"], not: { required: ["path"] } },
+			],
+		},
+		command: "audio.describe",
+	},
+
 	{
 		name: "audio_probe",
 		description:
@@ -2720,6 +2873,31 @@ const TOOLS = [
 		},
 		command: "project.set-region-sound",
 	},
+	{
+		name: "project_set_graphic_sound",
+		description:
+			"Set the sound a graphic owns (motion graphic overlay or motion element): plays when it appears, or with beats on each step/item/card, and moves with it. none = silent.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				overlayId: { type: "string", description: "Overlay id or motion element id." },
+				sound: {
+					type: "string",
+					description: 'bundled:sound/<id>, a bundled id, a path, or "none".',
+				},
+				volume: { type: "number", description: "0-1." },
+				beats: {
+					type: "boolean",
+					description: "Each beat (flowchart, comparison, list, glow-steps; steps elements).",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["overlayId"],
+		},
+		command: "project.set-graphic-sound",
+	},
 	{
 		name: "project_add_trim",
 		description: "Mark a span the exporter skips (manual cut).",
@@ -2774,6 +2952,24 @@ const TOOLS = [
 		},
 		command: "project.add-freeze-frame",
 	},
+	{
+		name: "project_remove_pause",
+		description:
+			"Remove inserted pauses (transcript_insert_pause / transcript_space_out) by regionId(s), by the word they follow (afterWordId), or all=true. Freeze frames and speed changes are never touched. Returns { removed, notFound }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				regionId: { type: "string" },
+				regionIds: { type: "array", items: { type: "string" } },
+				afterWordId: { type: "string" },
+				all: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.remove-pause",
+	},
 	{
 		name: "project_add_reverse",
 		description:
@@ -3141,7 +3337,7 @@ const TOOLS = [
 				patch: {
 					type: "object",
 					description:
-						"e.g. { depth: 4 }; null clears a value. zIndex (overlay / annotation / fx): stack order, higher on top; overlays, annotations and front motion elements share one stack at group base + zIndex (B-roll 0, overlays 1000, annotations 2000, motion elements 3000).",
+						"e.g. { depth: 4 }. Annotation: fontSize, fontFamily, textColor (alias color), backgroundColor, fontWeight, fontStyle, textDecoration, textAlign, flat or nested under style/styles; merges into canonical style, preserving other fields. Flat wins over styles, then style. null clears a value. zIndex (overlay / annotation / fx): stack order, higher on top; overlays, annotations and front motion elements share one stack at group base + zIndex (B-roll 0, overlays 1000, annotations 2000, motion elements 3000).",
 				},
 				expectedRevision: { type: "number" },
 			},
@@ -3397,7 +3593,8 @@ const TOOLS = [
 	},
 	{
 		name: "project_set_wallpaper",
-		description: "Set the background wallpaper.",
+		description:
+			"Set the background: a wallpaper value, or source=desktop (a kept still of the user's desktop wallpaper) / source=edges (Match video edges: a soft gradient from the video's border colours, slowly following the content; same in preview and export).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3405,14 +3602,66 @@ const TOOLS = [
 				path: { type: "string" },
 				wallpaper: {
 					type: "string",
-					description: "Bundled id (e.g. gradient-blue) or 'none'.",
+					description:
+						"Bundled id (e.g. gradient-blue), color, CSS gradient or 'none'. Omit with source.",
 				},
+				source: { type: "string", enum: ["desktop", "edges"] },
 				expectedRevision: { type: "number" },
 			},
-			required: ["wallpaper"],
 		},
 		command: "project.set-wallpaper",
 	},
+	{
+		name: "project_set_cover_art",
+		description:
+			"Audio-only project: cover art image (square; shown on the audio canvas, embedded in MP3 / M4A exports). image='none' removes it.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				image: { type: "string", description: "Absolute PNG / JPEG / WebP path, or 'none'." },
+				expectedRevision: { type: "number" },
+			},
+			required: ["image"],
+		},
+		command: "project.set-cover-art",
+	},
+	{
+		name: "project_set_episode_info",
+		description:
+			"Audio-only project: show name, episode title and number (canvas titles + exported ID3 / M4A tags). Empty string clears.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				show: { type: "string" },
+				title: { type: "string" },
+				episode: { type: "string" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-episode-info",
+	},
+	{
+		name: "project_set_audio_stage",
+		description:
+			"Audio-only project canvas: style waveform (cover art + live waveform + speaker) or cover (still), accent #rrggbb, showTitle, showSpeaker.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				style: { type: "string", enum: ["waveform", "cover"] },
+				accent: { type: "string", description: "#rrggbb or 'none'." },
+				showTitle: { type: "boolean" },
+				showSpeaker: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "project.set-audio-stage",
+	},
 	{
 		name: "project_set_style",
 		description:
@@ -3428,6 +3677,11 @@ const TOOLS = [
 				motionBlurAmount: { type: "number", description: "0-100." },
 				showBlur: { type: "boolean", description: "Blurred background." },
 				cursorScale: { type: "number", description: "0-5, 0 = off." },
+				cursorStyle: {
+					type: "string",
+					enum: ["classic", "modern", "bold", "soft"],
+					description: "Drawn-cursor style set (needs cursorScale > 0).",
+				},
 				cursorHideIdle: { type: "boolean" },
 				cursorIdleSeconds: { type: "number", description: "0.5-10, default 2." },
 				cursorHideDuringZoom: { type: "boolean" },
@@ -3804,13 +4058,13 @@ const TOOLS = [
 	{
 		name: "system_set_transcription_preferences",
 		description:
-			"Save workspace language and provider atomically. Confirm consent to upload audio for cloud. Cloud cannot use auto.",
+			"Save workspace language and provider atomically. Confirm consent to upload audio for cloud. Cloud and apple cannot use auto.",
 		inputSchema: {
 			type: "object",
 			required: ["language", "provider"],
 			properties: {
 				language: { type: "string" },
-				provider: { type: "string", enum: ["local", "deepgram", "elevenlabs"] },
+				provider: { type: "string", enum: ["local", "apple", "deepgram", "elevenlabs"] },
 			},
 		},
 		command: "system.set-transcription-preferences",
@@ -3829,12 +4083,13 @@ const TOOLS = [
 				language: {
 					type: "string",
 					description:
-						"Per-run spoken language name (english, tamil, etc.). Cloud cannot use auto.",
+						"Per-run spoken language name (english, tamil, etc.). Cloud and apple cannot use auto.",
 				},
 				provider: {
 					type: "string",
-					enum: ["local", "deepgram", "elevenlabs"],
-					description: "Per-run provider. Audio is sent to the selected cloud provider.",
+					enum: ["local", "apple", "deepgram", "elevenlabs"],
+					description:
+						"Per-run provider. apple stays on this Mac. Audio is sent to the selected cloud provider.",
 				},
 				force: { type: "boolean", description: "Re-transcribe clips that already have words." },
 			},
@@ -3896,9 +4151,58 @@ const TOOLS = [
 		},
 		command: "transcript.insert-words",
 	},
+	{
+		name: "transcript_insert_pause",
+		description:
+			"Add a natural pause after a word: ms of extra time filled with the take's own room tone (silence only if the take has no pause anywhere); video holds the frame. Everything after moves later. A pause already after that word gets the new length. Can't go inside a speed change. Returns { regionId, anchorMs, roomTone, updated }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				afterWordId: {
+					type: "string",
+					description: "Word the pause follows (or its transcript_get prefix).",
+				},
+				sourceMs: { type: "number", description: "Or pause at this SOURCE ms instead." },
+				ms: {
+					type: "number",
+					minimum: 30,
+					maximum: 60000,
+					description: "Pause length, output ms (250, 500, 1000, 2000 typical).",
+				},
+				expectedRevision: { type: "number" },
+			},
+			required: ["ms"],
+		},
+		command: "transcript.insert-pause",
+	},
+	{
+		name: "transcript_space_out",
+		description:
+			"Natural pacing for TTS / ElevenLabs narration that runs sentences together: tops up the gap after commas, sentences and at paragraph / speaker changes to the preset's target with room-tone pauses (natural: 0.15 / 0.42 / 0.7 s; tight: 0.12 / 0.35 / 0.6; relaxed: 0.2 / 0.5 / 0.8). Never shortens a gap; rerunning changes nothing. dryRun returns the plan (pauses, addedMs, items) without writing. One revision.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				preset: {
+					type: "string",
+					enum: ["natural", "relaxed", "tight"],
+					description: "Default natural.",
+				},
+				fromMs: { type: "number", description: "Edited-time window start." },
+				toMs: { type: "number", description: "Edited-time window end (exclusive)." },
+				dryRun: { type: "boolean" },
+				expectedRevision: { type: "number" },
+			},
+		},
+		command: "transcript.space-out",
+	},
 	{
 		name: "transcript_restore_words",
-		description: "Restore deleted words (removes their time from the covering cuts).",
+		description:
+			"Restore cut words (removes their time from every covering cut, silence cuts included). wordsRestored counts words that were cut and now are not; notCut lists ids that were not cut.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -3988,7 +4292,7 @@ const TOOLS = [
 	{
 		name: "transcript_remove_silences",
 		description:
-			"Remove measured quiet runs with a 50ms decay hold. Returns snapped/skipped/warnings; snapToAudio=false uses legacy timing.",
+			"Remove measured quiet runs inside transcript pauses (never into a word) with a 50ms decay hold. Counts only visible time (nothing under a head trim or existing cut). Returns snapped/skipped/warnings; snapToAudio=false uses legacy timing.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4011,30 +4315,76 @@ const TOOLS = [
 	},
 
 	// ── audio ───────────────────────────────────────────────────────
+	{
+		name: "audio_enhance",
+		description:
+			"Enhance voice: THE audio cleanup step (one call). Runs the studio chain on speech, per source (a podcast's host and each guest separately): noise removal, coughs/bumps out of pauses, mouth-click repair, broadcast tone, boom control, level riding (lifts very quiet speech too), de-esser, quieter pauses, -16 LUFS / -1 dBTP. strength: natural (default), light (gentle tidy), strong (assertive broadcast). keepBackground true for vlogs / ambience where the room is part of the video (no noise removal, event remover or pause expander; level, EQ and loudness still run). Enhance voice already removes room echo with the Studio AI model; only use echo when the result reports the model did not run (fallback) (denoiser deepfilternet3, or keepBackground); when the model runs, echo is skipped and the result says echoSkipped: ai-model-removes-echo (relay echoSkippedReason, do not retry). restore true = Restore voice quality (TF-Restormer) for thin, muffled or call-quality mics only (Apple silicon; slow; never on a good mic). reference = a clip id or file whose voice tone to match. off true restores the original audio. The noise-removal engine is automatic. Every run processes the original media, so running again replaces the result (never stacks). ASYNC: { jobId }, job_wait; the result reports before/after loudness (LUFS, LRA, true peak, speech over pauses, tone deviation) and the engine per source: tell the user.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				path: { type: "string" },
+				clipId: { type: "string", description: "Only this clip. Default: every clip." },
+				source: {
+					type: "string",
+					description: '"all" (default), "host", or a guest speaker id ("guest", "guest-2").',
+				},
+				strength: {
+					type: "string",
+					enum: ["light", "natural", "strong"],
+					default: "natural",
+				},
+				keepBackground: {
+					type: "boolean",
+					default: false,
+					description: "Keep the room sound (vlogs, ambience).",
+				},
+				echo: {
+					type: "boolean",
+					default: false,
+					description:
+						"Reduce room echo. Enhance voice already removes room echo with the Studio AI model; only use echo when the result reports the model did not run (fallback). Skipped (echoSkipped) whenever the model runs.",
+				},
+				restore: {
+					type: "boolean",
+					default: false,
+					description: "Restore voice quality for a thin / low-bandwidth mic (TF-Restormer).",
+				},
+				reference: { type: "string", description: "Clip id or audio/video file to sound like." },
+				off: { type: "boolean", description: "Remove the enhancement (original audio)." },
+				preset: {
+					type: "string",
+					enum: ["voice", "noise-reduction", "podcast", "off"],
+					description: "Deprecated (2.1). Use strength / keepBackground / off.",
+				},
+			},
+		},
+		command: "audio.enhance",
+	},
 	{
 		name: "audio_clean",
 		description:
-			"Denoise each clip’s audio, optionally reducing room echo. Speech below -30 LUFS is boosted to -16 LUFS / -1.5 dBTP by default; warnings explain boosts. Original kept; audio_reset_clean restores it. ASYNC: { jobId }, job_wait. Concurrent saves are merged and retried (three attempts); exhausted conflicts report code revision_conflict / status 409.",
+			"Deprecated alias of audio_enhance strength light (noise removal, gentle level and tone, -16 LUFS), echo true adds Reduce echo only when the Studio AI model does not run (it already removes room echo; the result then says echoSkipped); clips already enhanced are skipped unless clipId is given. Prefer audio_enhance. ASYNC: { jobId }, job_wait.",
 		inputSchema: {
 			type: "object",
 			properties: {
 				id: { type: "string" },
 				path: { type: "string" },
 				clipId: { type: "string" },
-				echo: { type: "boolean", description: "Only when the user mentions echo / reverb." },
-				normalize: {
+				echo: {
 					type: "boolean",
-					description: "Default true: boost very quiet speech. Set false to opt out.",
+					description:
+						"Enhance voice already removes room echo with the Studio AI model; only use echo when the result reports the model did not run (fallback).",
 				},
+				normalize: { type: "boolean", description: "Ignored (quiet speech is always lifted)." },
 			},
 		},
 		command: "audio.clean",
 	},
-
 	{
 		name: "audio_normalize",
 		description:
-			"Normalize a clip’s active audio without denoising. Default -16 LUFS, -1.5 dBTP ceiling. Silent audio skipped with warnings. Original kept. ASYNC: job_wait.",
+			"Loudness only: normalize a clip's audio to targetLufs (default -16, -1.5 dBTP ceiling) with no other processing. An enhanced clip is skipped (audio_enhance already sets -16 LUFS); prefer audio_enhance. Silent audio skipped with warnings. Original kept. ASYNC: job_wait.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4050,7 +4400,7 @@ const TOOLS = [
 	{
 		name: "audio_reset_clean",
 		description:
-			"Restore original clip audio by clearing cleaned/normalized audio and echo metadata. Optional clipId; otherwise all clips. Keeps generated files. Synchronous.",
+			"Alias of audio_enhance off: restore the original audio on one clip (clipId) or all clips, every podcast speaker included. Keeps generated files. Synchronous.",
 		inputSchema: {
 			type: "object",
 			properties: { id: { type: "string" }, path: { type: "string" }, clipId: { type: "string" } },
@@ -4312,10 +4662,32 @@ const TOOLS = [
 				fps: { type: "number", description: "1-60, default 30." },
 				systemAudio: { type: "boolean", description: "Mic is never captured." },
 				countdownSeconds: { type: "number", description: "0-10, default 0." },
+				cleanDesktop: {
+					type: "boolean",
+					description:
+						"Hide desktop icons for a whole-display recording (restored on stop/crash/quit). Default: the user's setting. Result tip = ask the user to turn on Do Not Disturb.",
+				},
 			},
 		},
 		command: "recording.start",
 	},
+	{
+		name: "recording_get_clean_desktop",
+		description: "Clean-desktop recording setting. Returns { cleanDesktop, supported }.",
+		inputSchema: { type: "object", properties: {} },
+		command: "recording.get-clean-desktop",
+	},
+	{
+		name: "recording_set_clean_desktop",
+		description:
+			"Turn clean desktop on/off: hide desktop icons while a whole display is recorded (macOS Finder desktop, Windows shell toggle); always restored. On by default. Returns { cleanDesktop }.",
+		inputSchema: {
+			type: "object",
+			properties: { enabled: { type: "boolean" } },
+			required: ["enabled"],
+		},
+		command: "recording.set-clean-desktop",
+	},
 	{
 		name: "recording_get_countdown",
 		description: "Recorder HUD countdown preference (not recording_start's).",
@@ -4337,7 +4709,7 @@ const TOOLS = [
 	{
 		name: "recording_stop",
 		description:
-			"Stop the recording and (by default) create a project from it. Returns { screenPath, projectId }; tell the user any warnings.",
+			"Stop the recording and (by default) create a project from it. Returns { screenPath, projectId }; tell the user any warnings and health events (e.g. it stopped early on a nearly full disk).",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -4347,6 +4719,28 @@ const TOOLS = [
 		},
 		command: "recording.stop",
 	},
+	{
+		name: "recording_unfinished",
+		description:
+			"Recordings that started but never finished (crash, force-quit, power loss). Recover with recording_recover.",
+		inputSchema: { type: "object", properties: {} },
+		command: "recording.unfinished",
+	},
+	{
+		name: "recording_recover",
+		description:
+			"Rebuild an unfinished recording (screen, mic, camera, cursor, aligned) and by default create a project. Tell the user any warnings.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				recordingId: { type: "number", description: "From recording_unfinished." },
+				name: { type: "string" },
+				createProject: { type: "boolean", description: "Default true." },
+			},
+			required: ["recordingId"],
+		},
+		command: "recording.recover",
+	},
 	{
 		name: "media_generate_presenter",
 		description:
@@ -4750,7 +5144,7 @@ const TOOLS = [
 	{
 		name: "media_import",
 		description:
-			"Download an https video, image or audio file (e.g. expiring generated-media URLs); returns { path, kind }. 2 GB max.",
+			"Download an https video, image or audio file (e.g. expiring generated-media URLs); returns { path, kind }. 2 GB max. An audio file (kind audio) becomes an audio-only podcast project with project_new withMedia.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5332,7 +5726,8 @@ const TOOLS = [
 	},
 	{
 		name: "llm_generate_timestamps",
-		description: "Generate YouTube chapter timestamps from the transcript.",
+		description:
+			"Generate YouTube chapter timestamps for the edited video: edited-timeline times from the words that survive the cuts (first 0:00, each >= 10 s, all before the end); the local LLM only writes labels.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5348,7 +5743,7 @@ const TOOLS = [
 	{
 		name: "export_start",
 		description:
-			"Render the project to MP4. ASYNC: { jobId, outputPath, quality }; job_wait. Tell the user any warning and the result's loudness before / after. Free trial: draft (720p) only (system_status license.exportQuality); standard/high/ultra fail with quality_requires_license.",
+			"Render the project to MP4, or audio only (format mp3 / wav / m4a: same mix, loudness-normalised, tagged, cover art embedded). Audio-only projects as video: audiogram=true (waveform + captions) or cover, aspectRatio, rangeStartMs/rangeEndMs for a clip. ASYNC: { jobId, outputPath }; job_wait. Tell the user any warning and the result's loudness before / after. Free trial: draft (720p) only (system_status license.exportQuality); standard/high/ultra fail with quality_requires_license.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -5369,6 +5764,27 @@ const TOOLS = [
 					type: ["number", "string"],
 					description: "30 | 60 | source | auto; omit = project setting.",
 				},
+				format: {
+					type: "string",
+					enum: ["mp4", "mp3", "wav", "m4a"],
+					description: "mp4 video (default) or audio only.",
+				},
+				bitrate: { type: "number", description: "MP3 128 | 192 (default) | 320 kbps; M4A 96-320." },
+				channels: { type: "string", enum: ["stereo", "mono"] },
+				audiogram: {
+					type: ["boolean", "string"],
+					description: "Audio-only project as video: true / waveform (audiogram) | cover.",
+				},
+				aspectRatio: { type: "string", description: "This export only: 1:1 | 9:16 | 16:9." },
+				rangeStartMs: { type: "number", description: "Clip start, edited ms." },
+				rangeEndMs: { type: "number", description: "Clip end, edited ms." },
+				captions: {
+					type: "boolean",
+					description: "Force captions on (default true for audiogram).",
+				},
+				title: { type: "string", description: "Audio tag: episode title." },
+				show: { type: "string", description: "Audio tag: show name." },
+				episode: { type: "string", description: "Audio tag: episode number." },
 			},
 		},
 		command: "export.start",
@@ -5524,13 +5940,22 @@ const TOOLS = [
 	{
 		name: "export_generate_shots",
 		description:
-			"Suggest 3-5 short clips from an export's transcript (local AI, 1-2 min); shot ids feed project_fork_from_shot. On model_missing ask the user to download it (Settings, AI Model).",
+			"Suggest 3-5 short clips (local AI, 1-2 min) from an export's transcript (id) or straight from a transcribed project that was never exported (projectId); shot ids feed project_fork_from_shot with the same exportId or projectId. Project shots also carry sourceStartMs/sourceEndMs. On model_missing ask the user to download it (Settings, AI Model).",
 		inputSchema: {
 			type: "object",
 			properties: {
-				id: { type: "string", description: "Export entry id." },
+				id: { type: "string", description: "Export entry id (or use projectId)." },
+				projectId: {
+					type: "string",
+					description: "Project id or path: find shots in its transcript.",
+				},
+				render: {
+					type: "boolean",
+					description:
+						"Audio-only project: also export each shot as a 9:16 audiogram Short (ASYNC jobId).",
+				},
+				aspectRatio: { type: "string", description: "With render: 9:16 (default) | 1:1 | 16:9." },
 			},
-			required: ["id"],
 		},
 		command: "export.generate-shots",
 	},
@@ -5750,6 +6175,20 @@ const TOOLS = [
 		command: "timeline.edited-to-source",
 	},
 
+	...["read", "search"].map((action) => ({
+		name: `agent_session_${action}`,
+		description:
+			action === "read"
+				? "Read saved agent conversation with tool-call status."
+				: "Search saved Home and project conversations, newest first.",
+		inputSchema: {
+			type: "object",
+			properties:
+				action === "read" ? { sessionId: { type: "string" } } : { query: { type: "string" } },
+			...(action === "read" ? { required: ["sessionId"] } : {}),
+		},
+		command: `agent.session-${action}`,
+	})),
 	// ── escape hatch ────────────────────────────────────────────────
 	// Non-UI admin / diagnostic verbs have no static schema, to keep the
 	// per-turn tool list small; agents find them with system_list_commands and
@@ -5804,7 +6243,7 @@ Before an editing pass, read the skill's "Which tool for which moment" section (
 3. Fix misheard names / brands with transcript_find_replace (transcript_insert_words for dropped words).
 4. transcript_find_issues, then transcript_delete_words on each duplicate take / false start (keep the LAST take; keep severity "low" ones).
 5. transcript_remove_silences.
-6. audio_clean clips not yet cleaned.
+6. audio_enhance (Enhance voice) on clips not yet enhanced: strength natural; keepBackground true for vlogs / ambience; no echo (Enhance voice already removes room echo with the Studio AI model; only use echo when the result reports the model did not run (fallback)).
 7. The style, after steps 2-5 (they shift the timeline). The user's named style, recipe, creator or a saved memory wins. Otherwise call recipe_pick: it returns the recipes that fit this project's format and footage, each with pickWhen, plus defaultId. Read the transcript, choose the ONE candidate whose pickWhen matches what is said (defaultId when none clearly fits), do its "before" step if any, then recipe_apply_style + recipe_render and follow the prompt: the recipe decides the style (captions, pacing, kinds of moves, music, transitions). Graphics inside it are designed by you: a named template is the reference look; author your own (motion_render_html, same palette and type) when a beat needs something the template can't show. (An app without recipe_pick, 2.0.5 and older: recipe_list with format short or long, and choose by description and footage.) Tell the user which recipe and why in one line and name one or two alternatives. Only when no candidate exists or the user asked for a plain clean-up: captions (caption_toggle, template glowStack), a few motion graphics, emphasis zooms.
 8. B-roll, last: pick the moments yourself from what's said (any language), check them with project_check_broll, show the user your moments and ASK: their own images, generated on their image connector (only if one is connected; it uses their credits), or no B-roll. Never generate or invent images without their answer. Place what they give with project_add_broll. Nobody to ask: skip it and say so.
 9. llm_generate_title / description / timestamps, then preview_show and ask before export_start. Never export before the user has seen the preview.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@writepanda/mcp",
-	"version": "1.216.0",
+	"version": "1.218.0",
 	"description": "Model Context Protocol server for PandaStudio. Exposes the desktop video editor's automation surface to Cursor, Continue, Cline, Claude Desktop, and any MCP-compliant client.",
 	"keywords": [
 		"pandastudio",