The VS Code of video editing, built for agents.
TypeScript
Refactor documentation and enhance instruction clarity
konstantin-paulusf92a8339a419
diff --git a/README.md b/README.mdindex c48a9fcd..b56a0a94 100644--- a/README.md+++ b/README.md@@ -61,7 +61,7 @@ Download the desktop app, it walks you through setting everything up:<a href="https://www.diffusion.studio/download"><img src="https://img.shields.io/badge/Download-Diffusion%20Studio-161616?style=for-the-badge&logo=apple&logoColor=F8F8F8&labelColor=000000" alt="Download Diffusion Studio" /></a>-Use with Claude Code, Codex, Cursor, Copilot, or Gemini CLI. The app registers its MCP server with your agent, so just ask for what you want in plain language. Agents that list a server's prompts also offer `/diffusion:editor` and `/diffusion:watch`, which pull in the editing and watching guidance up front. `dapi` is the same set of tools as a CLI.+Use with Claude Code, Codex, Cursor, Copilot, or Gemini CLI. The app registers its MCP server with your agent, so just ask for what you want in plain language. Every session's instructions carry the editing and watching skills, so the agent reads the guidance it needs up front. `dapi` is the same set of tools as a CLI.## Prompt examplesdiff --git a/apps/desktop/src/dapi/docs.test.ts b/apps/desktop/src/dapi/docs.test.tsindex 97075e28..33342ed6 100644--- a/apps/desktop/src/dapi/docs.test.ts+++ b/apps/desktop/src/dapi/docs.test.ts@@ -2,14 +2,11 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";import { afterAll, beforeAll, describe, expect, it } from "vitest";-import { Client } from "@modelcontextprotocol/sdk/client/index.js";-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";-import { instructions, registerPrompts, SKILLS } from "./docs";+import { instructions } from "./docs";// The docs in miniature, laid out like the repo's `docs/`.const root = mkdtempSync(join(tmpdir(), "dapi-docs-"));@@ -18,36 +15,18 @@ const repoDocs = join(__dirname, "..", "..", "..", "..", "docs");beforeAll(() => {mkdirSync(join(docsDir, "skills"), { recursive: true });- writeFileSync(join(docsDir, "INSTRUCTIONS.md"), "Diffusion Studio is running.\n");+ writeFileSync(join(docsDir, "INSTRUCTIONS.md"), "Diffusion Studio is running.\n\nRead `skills/editor.md`.\n");writeFileSync(join(docsDir, "skills", "editor.md"), "# Editing\n\nHow to edit.\n");writeFileSync(join(docsDir, "skills", "watch.md"), "# Watching\n\nHow to watch.\n");});afterAll(() => rmSync(root, { recursive: true, force: true }));-async function connect(dir: string | null): Promise<Client> {- const server = new McpServer({ name: "test", version: "0" }, { instructions: instructions(dir) });- registerPrompts(server, dir);- const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();- await server.connect(serverTransport);- const client = new Client({ name: "test-client", version: "0" });- await client.connect(clientTransport);- return client;-}-describe("instructions", () => {- it("is INSTRUCTIONS.md followed by where the docs sit on disk", () => {- const text = instructions(docsDir);- expect(text.startsWith("Diffusion Studio is running.")).toBe(true);- expect(text).toContain(`The docs are the files at \`${docsDir}\``);- });-- it("lists the skills, marking the default, with both ways to pull one in", () => {+ it("is INSTRUCTIONS.md verbatim, followed by where the docs sit on disk", () => {const text = instructions(docsDir);- expect(text).toContain("`editor` (the default) —");- expect(text).toContain(`Pull it in with the \`editor\` prompt, or read \`${join(docsDir, "skills", "editor.md")}\`.`);- expect(text).toContain("`watch` —");- expect(text).not.toContain("`watch` (the default)");+ expect(text.startsWith("Diffusion Studio is running.\n\nRead `skills/editor.md`.")).toBe(true);+ expect(text).toContain(`The docs, including every page named above, are the files at \`${docsDir}\``);});it("falls back to a one-liner when nothing is staged", () => {@@ -59,53 +38,19 @@ describe("instructions", () => {it("builds from the repo's own docs without broken instructions", () => {if (!existsSync(repoDocs)) return;const text = instructions(repoDocs);- expect(text).toContain(join(repoDocs, "skills", "editor.md"));+ expect(text).toContain(repoDocs);expect(text).not.toContain("dapi://");expect(text).not.toContain("\\`");});});-describe("prompts", () => {- it("offers one prompt per skill, described the way the instructions describe it", async () => {- const client = await connect(docsDir);- const prompts = (await client.listPrompts()).prompts;- expect(prompts.map((p) => p.name).sort()).toEqual(["editor", "watch"]);- for (const skill of SKILLS) {- expect(prompts.find((p) => p.name === skill.name)?.description).toBe(skill.description);- }- await client.close();- });-- it("returns the page as the prompt, with the coda that says what to do with it", async () => {- const client = await connect(docsDir);- const result = await client.getPrompt({ name: "editor" });- expect(result.messages).toHaveLength(1);- expect(result.messages[0].role).toBe("user");- const text = (result.messages[0].content as { text: string }).text;- expect(text.startsWith("# Editing")).toBe(true);- expect(text).toContain("ask them what they want to make");- await client.close();- });-- it("has no prompts when nothing is staged", async () => {- const client = await connect(null);- await expect(client.listPrompts()).rejects.toThrow();- await client.close();- });-- it("skips a skill whose page the staged tree does not carry", async () => {- const bare = join(root, "bare");- mkdirSync(join(bare, "skills"), { recursive: true });- writeFileSync(join(bare, "skills", "editor.md"), "# Editing\n");- const client = await connect(bare);- expect((await client.listPrompts()).prompts.map((p) => p.name)).toEqual(["editor"]);- await client.close();- });-- it("has a page in the repo's own docs for every skill in the table", () => {+describe("the repo's INSTRUCTIONS.md", () => {+ it("names the skills, and every page it names exists", () => {if (!existsSync(repoDocs)) return;- expect(SKILLS.map((s) => s.name)).toEqual(["editor", "watch"]);- expect(SKILLS.filter((s) => s.default)).toHaveLength(1);- for (const skill of SKILLS) expect(existsSync(join(repoDocs, skill.page))).toBe(true);+ const text = readFileSync(join(repoDocs, "INSTRUCTIONS.md"), "utf8");+ const pages = [...text.matchAll(/`((?:skills|reference|guides|examples|brand)\/[^`]*?\.(?:md|tsx?))`/g)].map((m) => m[1]);+ expect(pages).toContain("skills/editor.md");+ expect(pages).toContain("skills/watch.md");+ for (const page of pages) expect(existsSync(join(repoDocs, ...page.split("/")))).toBe(true);});});diff --git a/apps/desktop/src/dapi/docs.ts b/apps/desktop/src/dapi/docs.tsindex 8c9de05b..be394074 100644--- a/apps/desktop/src/dapi/docs.ts+++ b/apps/desktop/src/dapi/docs.ts@@ -2,103 +2,31 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-import { existsSync, readFileSync } from "node:fs";-import { readFile } from "node:fs/promises";+import { readFileSync } from "node:fs";import { join } from "node:path";-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";-export const INSTRUCTIONS_FILE = "INSTRUCTIONS.md";-export type Skill = {- name: string;- /** The page carrying the guidance, relative to the docs. */- page: string;- description: string;- /** The skill to reach for when the user has not pointed at one. Exactly one. */- default?: boolean;-};--/**- * What the server offers besides the tools. Each entry is both a line in the- * instructions every session receives and a prompt (`/diffusion:editor`), so- * adding a skill is adding a row here and its page under `docs/skills/`.- * Editing is the default; watching is the one you ask for.- */-export const SKILLS: readonly Skill[] = [- {- name: "editor",- page: "skills/editor.md",- default: true,- description:- "Understand, generate, and edit footage with Diffusion Studio: analyze video/audio/images, generate them with AI, and compose video compositions. Use for any media analysis, media generation, or video editing task.",- },- {- name: "watch",- page: "skills/watch.md",- description:- "Watch and understand footage with Diffusion Studio: answer questions about a video or audio file, summarize it, find scenes and moments, pull quotes, and describe what happens and when. Use whenever the user asks what's in a piece of footage, wants a summary or recap, wants to locate a moment, or needs a claim about a video or audio file checked.",- },-];-const FALLBACK_INSTRUCTIONS ="Diffusion Studio, a video editor, is running on this machine and you are connected to it. The tools are the whole API; their descriptions are authoritative.";/*** The text every client gets on connect: INSTRUCTIONS.md from the docs, then- * where the docs sit on disk, then the skills. The docs are plain files, read- * with whatever file tools the agent has; this path is how it finds them.+ * where the docs sit on disk. The page names the skills and everything else+ * it wants read — adding one is editing that file, not this one; the paths in+ * it are relative to the docs, and the sentence below is what anchors them.*/export function instructions(docsDir: string | null): string {const text = docsDir ? readText(join(docsDir, INSTRUCTIONS_FILE)) : null;const parts = [text?.trim() || FALLBACK_INSTRUCTIONS];if (docsDir) {parts.push(- `The docs are the files at \`${docsDir}\`: the tool and JSX reference, guides, runnable examples, and the brand kit (fonts, imagery, components to copy). They belong to the app; read them, never edit them.`,+ `The docs, including every page named above, are the files at \`${docsDir}\`: the skills, the tool and JSX reference, guides, runnable examples, and the brand kit (fonts, imagery, components to copy). They belong to the app; read them, never edit them.`,);- parts.push(skillList(docsDir));}return parts.join("\n\n");}-/**- * The skills as the instructions present them: what each is for, which to- * reach for by default, and both ways to pull one in — the prompt, for agents- * that list them, and the page on disk, for the ones that do not.- */-function skillList(docsDir: string): string {- const lines = SKILLS.map(- (skill) =>- `- \`${skill.name}\`${skill.default ? " (the default)" : ""} — ${skill.description} Pull it in with the \`${skill.name}\` prompt, or read \`${pagePath(docsDir, skill)}\`.`,- );- return ["Before starting on the work itself, pull in the skill that covers it:", ...lines].join("\n");-}--/**- * One prompt per skill, named as the table names it, so an agent that lists a- * server's prompts offers `/diffusion:editor` and `/diffusion:watch` beside- * its own commands. The page is read at call time, so edits show up live.- */-export function registerPrompts(session: McpServer, docsDir: string | null): void {- if (!docsDir) return;- for (const skill of SKILLS) {- const path = pagePath(docsDir, skill);- if (!existsSync(path)) continue; // a page the staged tree does not carry- session.registerPrompt(skill.name, { title: skill.name, description: skill.description }, async () => ({- messages: [{ role: "user", content: { type: "text", text: `${await readFile(path, "utf8")}\n${PROMPT_CODA}` } }],- }));- }-}--// A prompt arrives as a user turn, so the page needs a closing line saying-// what to do with guidance that turned up without a request attached to it.-const PROMPT_CODA =- "\nThe guidance above is in effect for the rest of this conversation. Apply it to what the user asked for; if they have not asked for anything yet, ask them what they want to make.";--function pagePath(docsDir: string, skill: Skill): string {- return join(docsDir, ...skill.page.split("/"));-}-function readText(path: string): string | null {try {return readFileSync(path, "utf8");diff --git a/apps/desktop/src/dapi/server.ts b/apps/desktop/src/dapi/server.tsindex eb0e51e9..efa032f4 100644--- a/apps/desktop/src/dapi/server.ts+++ b/apps/desktop/src/dapi/server.ts@@ -6,7 +6,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { MCP_HOST, MCP_PATH, MCP_PORT, tools } from "@diffusionstudio/dapi";import { mainHandlers } from "./handlers";import { DapiHttpServer } from "./http";-import { instructions, registerPrompts } from "./docs";+import { instructions } from "./docs";import { present, toCallToolResult, toErrorResult } from "./present";import { RendererCalls } from "./renderer-calls";@@ -15,8 +15,8 @@ import type { MainContext, MainToolName } from "./handler";/*** The name the server introduces itself with, and so the namespace an agent- * shows us under: `mcp__diffusion__<tool>` and `/diffusion:<prompt>`. The- * same word as our URL scheme, and not `dapi`, which is the CLI.+ * shows the tools under: `mcp__diffusion__<tool>`. The same word as our URL+ * scheme, and not `dapi`, which is the CLI.*/const SERVER_NAME = "diffusion";@@ -26,7 +26,7 @@ export type DapiServerDeps = {logs(): LogEntry[];/** Called once, on the first connection: an agent is driving, so the UI may step back. */onFirstConnection(): void;- /** The staged docs: INSTRUCTIONS.md and their path for every session, the skill pages as prompts. Null when not staged. */+ /** The staged docs: INSTRUCTIONS.md, their path, and the skill headers, all for every session. Null when not staged. */docsDir: string | null;};@@ -87,14 +87,13 @@ export class DapiServer {this.http.stop();}- /** One MCP server over the whole catalog, plus the skills as prompts. The docs are plain files; the instructions say where. */+ /** One MCP server over the whole catalog. The docs and skills are plain files; the instructions say where. */private createSession(): McpServer {this.instructionsText ??= instructions(this.deps.docsDir);// `name` is the machine identity, and matches the key we write into agent// configs; `title` is what a client shows a person.const session = new McpServer({ name: SERVER_NAME, title: "Diffusion Studio", version: this.deps.version }, { instructions: this.instructionsText });for (const tool of tools) this.register(session, tool);- registerPrompts(session, this.deps.docsDir);return session;}diff --git a/apps/desktop/src/skills-cleanup.ts b/apps/desktop/src/skills-cleanup.tsindex 7d7684d0..b7a54d1f 100644--- a/apps/desktop/src/skills-cleanup.ts+++ b/apps/desktop/src/skills-cleanup.ts@@ -2,17 +2,6 @@* License, v. 2.0. If a copy of the MPL was not distributed with this* file, You can obtain one at http://mozilla.org/MPL/2.0/. */-// Removes the skill directories older builds planted in agents' skill-// folders. The guidance they carried is served over MCP now (see-// `dapi/docs.ts`), so a copy on disk is a second, staler answer to the-// same question — and it points at a `dapi` binary that may no longer be-// where it was linked.-//-// Two kinds were ever installed: real directories copied by the skills CLI-// (`npx skills add diffusionstudio/skills`), and symlinks into the app-// bundle's staged copy. Both go, and nothing else does: a directory has to-// name itself as ours before it is touched.-import { lstatSync, readFileSync, readlinkSync, rmSync } from "node:fs";import { homedir } from "node:os";import { join } from "node:path";diff --git a/docs/INSTRUCTIONS.md b/docs/INSTRUCTIONS.mdindex 6501621f..75039307 100644--- a/docs/INSTRUCTIONS.md+++ b/docs/INSTRUCTIONS.md@@ -1,5 +1,6 @@Diffusion Studio, a video editor, is running on this machine and you are connected to it.-Projects are folders of JSX; `open` a folder once, then write its files and save — the app recompiles and re-renders.+Before starting on the work itself, read the skill page that covers it, and follow it for the rest of the session:-The tools are the whole API, and their descriptions are authoritative. The same tools exist as `dapi` commands for shells and scripts: `media_grab` is `dapi media grab`, a field like `perSheet` is `--per-sheet`, and the result is the same JSON either way. Each tool is documented once for both in the docs, under `reference/tools/`.+- `skills/editor.md` (the default) — Understand, generate, and edit footage with Diffusion Studio: analyze video/audio/images, generate them with AI, and compose video compositions. Use for any media analysis, media generation, or video editing task.+- `skills/watch.md` — Watch and understand footage with Diffusion Studio: answer questions about a video or audio file, summarize it, find scenes and moments, pull quotes, and describe what happens and when. Use whenever the user asks what's in a piece of footage, wants a summary or recap, wants to locate a moment, or needs a claim about a video or audio file checked.