The VS Code of video editing, built for agents.
TypeScript
Update documentation references and refactor knowledge handling
konstantin-paulus7372c4042964
diff --git a/README.md b/README.mdindex 783a5253..3e55eee6 100644--- a/README.md+++ b/README.md@@ -207,9 +207,9 @@ Conventions throughout: every result is one JSON object, the same structured con## Documentation-- [Tool reference](knowledge/reference/tools/README.md): every tool and CLI command, its options, and its output-- [JSX reference](knowledge/reference/jsx/README.md): the composition markup with elements, timing, paints, generative assets, and captions-- [Examples](knowledge/examples/README.md): runnable compositions, from basic scenes and generative assets to three.js and raw WebGPU+- [Tool reference](docs/reference/tools/README.md): every tool and CLI command, its options, and its output+- [JSX reference](docs/reference/jsx/README.md): the composition markup with elements, timing, paints, generative assets, and captions+- [Examples](docs/examples/README.md): runnable compositions, from basic scenes and generative assets to three.js and raw WebGPU## Repository layoutdiff --git a/apps/desktop/.gitignore b/apps/desktop/.gitignoreindex 54f86506..0410c18b 100644--- a/apps/desktop/.gitignore+++ b/apps/desktop/.gitignore@@ -2,4 +2,4 @@ distweboutcli-knowledge+docsdiff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.tsindex 7bddecf7..c5033721 100644--- a/apps/desktop/forge.config.ts+++ b/apps/desktop/forge.config.ts@@ -27,9 +27,9 @@ const config: ForgeConfig = {!path.startsWith('/dist/') &&path !== '/web' &&!path.startsWith('/web/'),- // Staged by scripts/stage-{cli,knowledge}.mjs; end up at- // Contents/Resources/{cli,knowledge}.- extraResource: ['./cli', './knowledge'],+ // Staged by scripts/stage-{cli,docs}.mjs; end up at+ // Contents/Resources/{cli,docs}.+ extraResource: ['./cli', './docs'],osxSign: process.env.SKIP_SIGN ? undefined : {},osxNotarize:process.env.APPLE_ID && process.env.APPLE_PASSWORD && process.env.APPLE_TEAM_IDdiff --git a/apps/desktop/package.json b/apps/desktop/package.jsonindex e0ab164e..9452ceee 100644--- a/apps/desktop/package.json+++ b/apps/desktop/package.json@@ -15,12 +15,12 @@"build": "npm run check && npm run build:main && npm run build:preload && npm run build:agent-host && npm run build:native","build:web": "npm --prefix ../web run build:desktop","stage:cli": "npm --prefix ../cli run build && node scripts/stage-cli.mjs",- "stage:knowledge": "node scripts/stage-knowledge.mjs",+ "stage:docs": "node scripts/stage-docs.mjs","check": "tsc --noEmit","dev": "npm run build && electron-forge start",- "package": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge package",- "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge make",- "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:knowledge && electron-forge publish",+ "package": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && electron-forge package",+ "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && electron-forge make",+ "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && electron-forge publish","make:icns": "sh scripts/make-icns.sh","test": "vitest run","build:agent-host": "esbuild ../../packages/agent-chat/src/bin.ts --bundle --platform=node --format=esm --target=node20 --external:electron '--external:@anthropic-ai/claude-agent-sdk-*' --banner:js=\"import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);\" --outfile=dist/agent-host.mjs"diff --git a/apps/desktop/scripts/stage-knowledge.mjs b/apps/desktop/scripts/stage-docs.mjssimilarity index 55%rename from apps/desktop/scripts/stage-knowledge.mjsrename to apps/desktop/scripts/stage-docs.mjsindex f7f1c7e5..5ddddf07 100644--- a/apps/desktop/scripts/stage-knowledge.mjs+++ b/apps/desktop/scripts/stage-docs.mjs@@ -2,11 +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/. */-// Stages the knowledge base into apps/desktop/knowledge so electron-forge-// can ship it as an app resource (Contents/Resources/knowledge). The app's-// MCP server serves it: INSTRUCTIONS.md on connect, everything else as-// resources under dapi://<path>. The tree is copied as it is in the repo,-// because the relative links between the pages assume that layout.+// Stages the docs into apps/desktop/docs so electron-forge can ship them as+// an app resource (Contents/Resources/docs). The app's MCP server sends+// INSTRUCTIONS.md on connect along with this folder's path; agents read the+// rest as plain files. The tree is copied as it is in the repo, because the+// relative links between the pages assume that layout.import { cpSync, mkdirSync, rmSync } from "node:fs";import { dirname, join } from "node:path";@@ -14,13 +14,13 @@ import { fileURLToPath } from "node:url";const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");const repoRoot = join(desktopDir, "..", "..");-const stageDir = join(desktopDir, "knowledge");+const stageDir = join(desktopDir, "docs");rmSync(stageDir, { recursive: true, force: true });mkdirSync(stageDir, { recursive: true });-cpSync(join(repoRoot, "knowledge"), stageDir, {+cpSync(join(repoRoot, "docs"), stageDir, {recursive: true,filter: (path) => !path.endsWith(".DS_Store") && !path.endsWith(".gitkeep"),});-console.log(`stage-knowledge: staged the knowledge base at ${stageDir}`);+console.log(`stage-docs: staged the docs at ${stageDir}`);diff --git a/apps/desktop/src/dapi/docs.test.ts b/apps/desktop/src/dapi/docs.test.tsnew file mode 100644index 00000000..97075e28--- /dev/null+++ b/apps/desktop/src/dapi/docs.test.ts@@ -0,0 +1,111 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * 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 { 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";++// The docs in miniature, laid out like the repo's `docs/`.+const root = mkdtempSync(join(tmpdir(), "dapi-docs-"));+const docsDir = join(root, "docs");+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, "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", () => {+ 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)");+ });++ it("falls back to a one-liner when nothing is staged", () => {+ const text = instructions(null);+ expect(text).toContain("The tools are the whole API");+ expect(text).not.toContain("skills/editor.md");+ });++ 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).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", () => {+ 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);+ });+});diff --git a/apps/desktop/src/dapi/docs.ts b/apps/desktop/src/dapi/docs.tsnew file mode 100644index 00000000..8c9de05b--- /dev/null+++ b/apps/desktop/src/dapi/docs.ts@@ -0,0 +1,108 @@+/* This Source Code Form is subject to the terms of the Mozilla Public+ * 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 { 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.+ */+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.`,+ );+ 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");+ } catch {+ return null;+ }+}diff --git a/apps/desktop/src/dapi/knowledge.test.ts b/apps/desktop/src/dapi/knowledge.test.tsdeleted file mode 100644index 6a4a0b67..00000000--- a/apps/desktop/src/dapi/knowledge.test.ts+++ /dev/null@@ -1,170 +0,0 @@-/* This Source Code Form is subject to the terms of the Mozilla Public- * 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 { 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, registerResources, SKILLS } from "./knowledge";--import type { KnowledgeDeps } from "./knowledge";--// A knowledge base in miniature, laid out like the repo's `knowledge/`.-const root = mkdtempSync(join(tmpdir(), "dapi-knowledge-"));-const knowledgeDir = join(root, "knowledge");-const projectDir = join(root, "project");--beforeAll(() => {- mkdirSync(join(knowledgeDir, "reference", "jsx"), { recursive: true });- mkdirSync(join(knowledgeDir, "examples", "node_modules"), { recursive: true });- mkdirSync(join(knowledgeDir, "skills"), { recursive: true });- mkdirSync(join(knowledgeDir, "brand", "assets", "logos"), { recursive: true });- writeFileSync(join(knowledgeDir, "INSTRUCTIONS.md"), "Diffusion Studio is running.\n");- writeFileSync(join(knowledgeDir, "reference", "jsx", "text.md"), "# text\n\nThe `<text>` element draws a run of text. It wraps at `width`.\n\n## Props\n");- writeFileSync(join(knowledgeDir, "reference", "README.md"), "---\ntitle: x\n---\n# Reference\n\n| a | b |\n\nEvery page, one per tool.\n");- writeFileSync(join(knowledgeDir, "skills", "editor.md"), "# Editing\n\nHow to edit.\n");- writeFileSync(join(knowledgeDir, "skills", "watch.md"), "# Watching\n\nHow to watch.\n");- writeFileSync(join(knowledgeDir, "examples", "01-hello.tsx"), "export default <scene />;\n");- writeFileSync(join(knowledgeDir, "examples", "tsconfig.json"), "{}\n");- writeFileSync(join(knowledgeDir, "examples", "node_modules", "ignored.md"), "no\n");- writeFileSync(join(knowledgeDir, "brand", "assets", "logos", "icon.svg"), "<svg/>\n");- writeFileSync(join(knowledgeDir, ".DS_Store"), "");- mkdirSync(projectDir);-});--afterAll(() => rmSync(root, { recursive: true, force: true }));--const deps = (projectOpen: boolean, dir: string | null = knowledgeDir): KnowledgeDeps => ({- knowledgeDir: dir,- logs: () => [{ ts: 1, level: "info", message: "hi", source: "" }],- context: async () => ({ rootDir: root, projectDir: projectOpen ? projectDir : null, currentTime: null, fontFamilies: [], generations: [] }),-});--async function connect(d: KnowledgeDeps): Promise<Client> {- const server = new McpServer({ name: "test", version: "0" }, { instructions: instructions(d) });- registerResources(server, d);- registerPrompts(server, d);- 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 tree sits on disk", () => {- const text = instructions(deps(true));- expect(text.startsWith("Diffusion Studio is running.")).toBe(true);- expect(text).toContain(knowledgeDir);- });-- it("lists the skills, marking the default, with both ways to pull one in", () => {- const text = instructions(deps(true));- expect(text).toContain("`editor` (the default) —");- expect(text).toContain("Pull it in with the `editor` prompt, or read `dapi://skills/editor.md`.");- expect(text).toContain("`watch` —");- expect(text).not.toContain("`watch` (the default)");- });-- it("falls back to a one-liner when nothing is staged", () => {- const text = instructions(deps(true, null));- expect(text).toContain("The tools are the whole API");- expect(text).not.toContain("dapi://skills");- });-});--describe("resources", () => {- it("lists every page under dapi://<path>, docs and svg only, no node_modules or dotfiles", async () => {- const client = await connect(deps(true));- const uris = (await client.listResources()).resources.map((r) => r.uri).sort();- expect(uris).toEqual([- "dapi://brand/assets/logos/icon.svg",- "dapi://context",- "dapi://examples/01-hello.tsx",- "dapi://logs",- "dapi://reference/README.md",- "dapi://reference/jsx/text.md",- "dapi://skills/editor.md",- "dapi://skills/watch.md",- ]);- await client.close();- });-- it("describes markdown pages by their first paragraph, skipping headings, frontmatter and tables", async () => {- const client = await connect(deps(true));- const byUri = new Map((await client.listResources()).resources.map((r) => [r.uri, r]));- expect(byUri.get("dapi://reference/jsx/text.md")?.description).toBe("The `<text>` element draws a run of text. It wraps at `width`.");- expect(byUri.get("dapi://reference/README.md")?.description).toBe("Every page, one per tool.");- expect(byUri.get("dapi://examples/01-hello.tsx")?.description).toBeUndefined();- await client.close();- });-- it("reads a page, an svg, and the live state", async () => {- const client = await connect(deps(true));- expect((await client.readResource({ uri: "dapi://reference/jsx/text.md" })).contents[0]).toMatchObject({ mimeType: "text/markdown" });- expect((await client.readResource({ uri: "dapi://brand/assets/logos/icon.svg" })).contents[0]).toMatchObject({ mimeType: "image/svg+xml", text: "<svg/>\n" });- const context = await client.readResource({ uri: "dapi://context" });- expect(JSON.parse((context.contents[0] as { text: string }).text).projectDir).toBe(projectDir);- const logs = await client.readResource({ uri: "dapi://logs" });- expect(JSON.parse((logs.contents[0] as { text: string }).text).entries).toHaveLength(1);- await client.close();- });-- it("serves the repo's own knowledge base without broken instructions", () => {- const repoKnowledge = join(__dirname, "..", "..", "..", "..", "knowledge");- if (!existsSync(repoKnowledge)) return;- const text = instructions(deps(true, repoKnowledge));- expect(text).toContain("dapi://skills/editor.md");- expect(text).not.toContain("\\`");- });-});--describe("prompts", () => {- it("offers one prompt per skill, described the way the instructions describe it", async () => {- const client = await connect(deps(true));- 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(deps(true));- 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(deps(true, 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(deps(true, bare));- expect((await client.listPrompts()).prompts.map((p) => p.name)).toEqual(["editor"]);- await client.close();- });-- it("has a page in the repo's own knowledge base for every skill in the table", () => {- const repoKnowledge = join(__dirname, "..", "..", "..", "..", "knowledge");- if (!existsSync(repoKnowledge)) 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(repoKnowledge, skill.page))).toBe(true);- });-});diff --git a/apps/desktop/src/dapi/knowledge.ts b/apps/desktop/src/dapi/knowledge.tsdeleted file mode 100644index b7ff9aa8..00000000--- a/apps/desktop/src/dapi/knowledge.ts+++ /dev/null@@ -1,207 +0,0 @@-/* This Source Code Form is subject to the terms of the Mozilla Public- * 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, readdirSync, readFileSync, statSync } from "node:fs";-import { readFile } from "node:fs/promises";-import { join, relative, sep } from "node:path";--import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";-import type { LogEntry, ToolOutput } from "@diffusionstudio/dapi";--export type KnowledgeDeps = {- /** The staged `knowledge/` tree. Null when not staged. */- knowledgeDir: string | null;- logs(): LogEntry[];- context(signal: AbortSignal): Promise<ToolOutput<"context">>;-};--export const INSTRUCTIONS_FILE = "INSTRUCTIONS.md";--const RESOURCE_PREFIX = "dapi://";--export type Skill = {- name: string;- /** The page carrying the guidance, relative to the knowledge base. */- 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 `knowledge/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 MIME_TYPES: Record<string, string> = {- ".md": "text/markdown",- ".ts": "text/plain",- ".tsx": "text/plain",- ".svg": "image/svg+xml",-};--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 knowledge- * base, plus where that tree sits on disk, since resources carry text and the- * brand kit has logos, fonts and components meant to be copied.- */-export function instructions(deps: KnowledgeDeps): string {- const text = deps.knowledgeDir ? readText(join(deps.knowledgeDir, INSTRUCTIONS_FILE)) : null;- const parts = [text?.trim() || FALLBACK_INSTRUCTIONS];- if (deps.knowledgeDir) {- parts.push(skillList());- parts.push(- `The resources under \`dapi://\` are the files at \`${deps.knowledgeDir}\`, for anything a resource cannot carry (fonts, imagery, components to copy). They belong to the app; read them, never edit them.`,- );- }- return parts.join("\n\n");-}--export function registerResources(session: McpServer, deps: KnowledgeDeps): void {- for (const file of pages(deps)) {- session.registerResource(file.name, file.uri, { title: file.name, description: file.description, mimeType: file.mimeType }, async () => ({- contents: [{ uri: file.uri, mimeType: file.mimeType, text: await readFile(file.path, "utf8") }],- }));- }-- session.registerResource(- "context",- "dapi://context",- { title: "App context", description: "The open project, the playhead, registered fonts, and where generations stand.", mimeType: "application/json" },- async (uri, extra) => ({- contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await deps.context(extra.signal)) }],- }),- );-- session.registerResource(- "logs",- "dapi://logs",- { title: "App logs", description: "The app's console output, oldest first.", mimeType: "application/json" },- async (uri) => ({- contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ entries: deps.logs() }) }],- }),- );-}--/**- * 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 resource, for the ones that do not.- */-function skillList(): string {- const lines = SKILLS.map(- (skill) =>- `- \`${skill.name}\`${skill.default ? " (the default)" : ""} — ${skill.description} Pull it in with the \`${skill.name}\` prompt, or read \`${RESOURCE_PREFIX}${skill.page}\`.`,- );- 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, like a resource.- */-export function registerPrompts(session: McpServer, deps: KnowledgeDeps): void {- const dir = deps.knowledgeDir;- if (!dir) return;- for (const skill of SKILLS) {- const path = join(dir, ...skill.page.split("/"));- 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.";--type Page = { name: string; uri: string; path: string; mimeType: string; description?: string };--// The listing is the same for every session; walk the staged tree once.-let cache: { dir: string; pages: Page[] } | null = null;--function pages(deps: KnowledgeDeps): Page[] {- if (!deps.knowledgeDir) return [];- if (cache?.dir === deps.knowledgeDir) return cache.pages;- const found: Page[] = [];- collect(deps.knowledgeDir, deps.knowledgeDir, found);- cache = { dir: deps.knowledgeDir, pages: found };- return found;-}--function collect(root: string, dir: string, out: Page[]): void {- let entries: string[];- try {- entries = readdirSync(dir);- } catch {- return;- }- for (const entry of entries.sort()) {- if (entry.startsWith(".") || entry === "node_modules") continue;- const path = join(dir, entry);- let isDirectory: boolean;- try {- isDirectory = statSync(path).isDirectory();- } catch {- continue;- }- if (isDirectory) {- collect(root, path, out);- continue;- }- const mimeType = MIME_TYPES[entry.slice(entry.lastIndexOf("."))];- if (!mimeType) continue;- const name = relative(root, path).split(sep).join("/");- if (name === INSTRUCTIONS_FILE) continue; // already in every session's instructions- out.push({ name, uri: `${RESOURCE_PREFIX}${name}`, path, mimeType, description: mimeType === "text/markdown" ? summary(path) : undefined });- }-}--/**- * A page's first paragraph after its heading, so `resources/list` reads as a- * table of contents without opening anything.- */-function summary(path: string): string | undefined {- const text = readText(path);- if (!text) return undefined;- const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");- const paragraph = body- .split(/\n\s*\n/)- .map((block) => block.trim())- .find((block) => block && !block.startsWith("#") && !block.startsWith("```") && !block.startsWith("|") && !block.startsWith("<"));- if (!paragraph) return undefined;- const line = paragraph.replace(/\s+/g, " ");- return line.length > 200 ? `${line.slice(0, 197).trimEnd()}…` : line;-}--function readText(path: string): string | null {- try {- return readFileSync(path, "utf8");- } catch {- return null;- }-}diff --git a/apps/desktop/src/dapi/server.ts b/apps/desktop/src/dapi/server.tsindex 2f2cdea4..d7035768 100644--- a/apps/desktop/src/dapi/server.ts+++ b/apps/desktop/src/dapi/server.ts@@ -9,12 +9,12 @@ import { tools } from "@diffusionstudio/dapi";import { MCP_HOST, MCP_PATH, MCP_PORT, SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";import { mainHandlers } from "./handlers";import { DapiHttpServer } from "./http";-import { instructions, registerPrompts, registerResources } from "./knowledge";+import { instructions, registerPrompts } from "./docs";import { present, toCallToolResult, toErrorResult } from "./present";import { RendererCalls } from "./renderer-calls";import type { Server, Socket } from "node:net";-import type { GenericTool, LogEntry, ToolName, ToolOutput } from "@diffusionstudio/dapi";+import type { GenericTool, LogEntry, ToolName } from "@diffusionstudio/dapi";import type { MainContext, MainToolName } from "./handler";/**@@ -30,8 +30,8 @@ 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 knowledge base: INSTRUCTIONS.md for every session, the rest as resources. Null when not staged. */- knowledgeDir: string | null;+ /** The staged docs: INSTRUCTIONS.md and their path for every session, the skill pages as prompts. Null when not staged. */+ docsDir: string | null;};/**@@ -127,20 +127,14 @@ export class DapiServer {}}- /** One MCP server over the whole catalog, plus the docs and live state as resources and the skills as prompts. */+ /** One MCP server over the whole catalog, plus the skills as prompts. The docs are plain files; the instructions say where. */private createSession(): McpServer {- const knowledge = {- knowledgeDir: this.deps.knowledgeDir,- logs: this.deps.logs,- context: (signal: AbortSignal) => this.renderer.call("context", {}, signal) as Promise<ToolOutput<"context">>,- };- this.instructionsText ??= instructions(knowledge);+ 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);- registerResources(session, knowledge);- registerPrompts(session, knowledge);+ registerPrompts(session, this.deps.docsDir);return session;}diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.tsindex cbba6bb4..1ae0fc48 100644--- a/apps/desktop/src/main.ts+++ b/apps/desktop/src/main.ts@@ -100,12 +100,12 @@ const pendingDeepLinks = new Map<DeepLinkChannel, string>();const LOG_BUFFER_MAX = 2000;const logBuffer: LogEntry[] = [];-// The knowledge base the MCP server serves: staged into the bundle by-// scripts/stage-knowledge.mjs (Contents/Resources/knowledge) when packaged;-// the repo's own `knowledge/` in development, so edits show up without a-// staging step. Null when neither exists.-function knowledgeDir(): string | null {- const dir = app.isPackaged ? join(process.resourcesPath, "knowledge") : join(app.getAppPath(), "..", "..", "knowledge");+// The docs the MCP instructions point agents at: staged into the bundle by+// scripts/stage-docs.mjs (Contents/Resources/docs) when packaged; the repo's+// own `docs/` in development, so edits show up without a staging step. Null+// when neither exists.+function docsDir(): string | null {+ const dir = app.isPackaged ? join(process.resourcesPath, "docs") : join(app.getAppPath(), "..", "..", "docs");return existsSync(dir) ? dir : null;}@@ -114,7 +114,7 @@ function knowledgeDir(): string | null {const dapi = new DapiServer({version: app.getVersion(),logs: () => logBuffer,- knowledgeDir: knowledgeDir(),+ docsDir: docsDir(),onFirstConnection: enableHeadless,});diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.tsindex 522f5f43..05991a18 100644--- a/apps/desktop/src/projects.ts+++ b/apps/desktop/src/projects.ts@@ -687,9 +687,9 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.## Reference-- [JSX reference](https://github.com/diffusionstudio/editor/blob/main/knowledge/reference/jsx/README.md): elements, timing, paints, generation, captions-- [Tool reference](https://github.com/diffusionstudio/editor/blob/main/knowledge/reference/tools/README.md): every tool and command, its options and its output-- [Examples](https://github.com/diffusionstudio/editor/tree/main/knowledge/examples): runnable compositions to read+- [JSX reference](https://github.com/diffusionstudio/editor/blob/main/docs/reference/jsx/README.md): elements, timing, paints, generation, captions+- [Tool reference](https://github.com/diffusionstudio/editor/blob/main/docs/reference/tools/README.md): every tool and command, its options and its output+- [Examples](https://github.com/diffusionstudio/editor/tree/main/docs/examples): runnable compositions to read`;// ---------------------------------------------------------------------------diff --git a/apps/desktop/src/skills-cleanup.ts b/apps/desktop/src/skills-cleanup.tsindex 3ad56bd4..7d7684d0 100644--- a/apps/desktop/src/skills-cleanup.ts+++ b/apps/desktop/src/skills-cleanup.ts@@ -4,7 +4,7 @@// Removes the skill directories older builds planted in agents' skill// folders. The guidance they carried is served over MCP now (see-// `dapi/knowledge.ts`), so a copy on disk is a second, staler answer to the+// `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.//diff --git a/knowledge/INSTRUCTIONS.md b/docs/INSTRUCTIONS.mdsimilarity index 85%rename from knowledge/INSTRUCTIONS.mdrename to docs/INSTRUCTIONS.mdindex 6143e6d0..6501621f 100644--- a/knowledge/INSTRUCTIONS.md+++ b/docs/INSTRUCTIONS.md@@ -2,4 +2,4 @@ Diffusion Studio, a video editor, is running on this machine and you are connectProjects are folders of JSX; `open` a folder once, then write its files and save — the app recompiles and re-renders.-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 under `dapi://reference/tools/`.+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/`.diff --git a/knowledge/brand/README.md b/docs/brand/README.mdsimilarity index 100%rename from knowledge/brand/README.mdrename to docs/brand/README.mddiff --git a/knowledge/brand/assets/audio/music/.gitkeep b/docs/brand/assets/audio/music/.gitkeepsimilarity index 100%rename from knowledge/brand/assets/audio/music/.gitkeeprename to docs/brand/assets/audio/music/.gitkeepdiff --git a/knowledge/brand/assets/audio/sfx/.gitkeep b/docs/brand/assets/audio/sfx/.gitkeepsimilarity index 100%rename from knowledge/brand/assets/audio/sfx/.gitkeeprename to docs/brand/assets/audio/sfx/.gitkeepdiff --git a/knowledge/brand/assets/audio/voiceovers/.gitkeep b/docs/brand/assets/audio/voiceovers/.gitkeepsimilarity index 100%rename from knowledge/brand/assets/audio/voiceovers/.gitkeeprename to docs/brand/assets/audio/voiceovers/.gitkeepdiff --git a/knowledge/brand/assets/components/callout.tsx b/docs/brand/assets/components/callout.tsxsimilarity index 100%rename from knowledge/brand/assets/components/callout.tsxrename to docs/brand/assets/components/callout.tsxdiff --git a/knowledge/brand/assets/components/lower-third.tsx b/docs/brand/assets/components/lower-third.tsxsimilarity index 100%rename from knowledge/brand/assets/components/lower-third.tsxrename to docs/brand/assets/components/lower-third.tsxdiff --git a/knowledge/brand/assets/components/media-grid.tsx b/docs/brand/assets/components/media-grid.tsxsimilarity index 100%rename from knowledge/brand/assets/components/media-grid.tsxrename to docs/brand/assets/components/media-grid.tsxdiff --git a/knowledge/brand/assets/components/title-card.tsx b/docs/brand/assets/components/title-card.tsxsimilarity index 100%rename from knowledge/brand/assets/components/title-card.tsxrename to docs/brand/assets/components/title-card.tsxdiff --git a/knowledge/brand/assets/components/tokens.ts b/docs/brand/assets/components/tokens.tssimilarity index 100%rename from knowledge/brand/assets/components/tokens.tsrename to docs/brand/assets/components/tokens.tsdiff --git a/knowledge/brand/assets/compositions/end-card.tsx b/docs/brand/assets/compositions/end-card.tsxsimilarity index 100%rename from knowledge/brand/assets/compositions/end-card.tsxrename to docs/brand/assets/compositions/end-card.tsxdiff --git a/knowledge/brand/assets/compositions/product-demo.tsx b/docs/brand/assets/compositions/product-demo.tsxsimilarity index 100%rename from knowledge/brand/assets/compositions/product-demo.tsxrename to docs/brand/assets/compositions/product-demo.tsxdiff --git a/knowledge/brand/assets/compositions/product-tour.tsx b/docs/brand/assets/compositions/product-tour.tsxsimilarity index 100%rename from knowledge/brand/assets/compositions/product-tour.tsxrename to docs/brand/assets/compositions/product-tour.tsxdiff --git a/knowledge/brand/assets/fonts/.gitkeep b/docs/brand/assets/fonts/.gitkeepsimilarity index 100%rename from knowledge/brand/assets/fonts/.gitkeeprename to docs/brand/assets/fonts/.gitkeepdiff --git a/knowledge/brand/assets/imagery/.gitkeep b/docs/brand/assets/imagery/.gitkeepsimilarity index 100%rename from knowledge/brand/assets/imagery/.gitkeeprename to docs/brand/assets/imagery/.gitkeepdiff --git a/knowledge/brand/assets/logos/icon-white.svg b/docs/brand/assets/logos/icon-white.svgsimilarity index 100%rename from knowledge/brand/assets/logos/icon-white.svgrename to docs/brand/assets/logos/icon-white.svgdiff --git a/knowledge/brand/assets/logos/logo-white.svg b/docs/brand/assets/logos/logo-white.svgsimilarity index 100%rename from knowledge/brand/assets/logos/logo-white.svgrename to docs/brand/assets/logos/logo-white.svgdiff --git a/knowledge/brand/design.md b/docs/brand/design.mdsimilarity index 100%rename from knowledge/brand/design.mdrename to docs/brand/design.mddiff --git a/knowledge/brand/library.md b/docs/brand/library.mdsimilarity index 100%rename from knowledge/brand/library.mdrename to docs/brand/library.mddiff --git a/knowledge/brand/video.md b/docs/brand/video.mdsimilarity index 100%rename from knowledge/brand/video.mdrename to docs/brand/video.mddiff --git a/knowledge/brand/voice.md b/docs/brand/voice.mdsimilarity index 100%rename from knowledge/brand/voice.mdrename to docs/brand/voice.mddiff --git a/knowledge/examples/01-basics.tsx b/docs/examples/01-basics.tsxsimilarity index 100%rename from knowledge/examples/01-basics.tsxrename to docs/examples/01-basics.tsxdiff --git a/knowledge/examples/02-genai.tsx b/docs/examples/02-genai.tsxsimilarity index 100%rename from knowledge/examples/02-genai.tsxrename to docs/examples/02-genai.tsxdiff --git a/knowledge/examples/03-ticker.tsx b/docs/examples/03-ticker.tsxsimilarity index 100%rename from knowledge/examples/03-ticker.tsxrename to docs/examples/03-ticker.tsxdiff --git a/knowledge/examples/04-html-in-canvas.tsx b/docs/examples/04-html-in-canvas.tsxsimilarity index 100%rename from knowledge/examples/04-html-in-canvas.tsxrename to docs/examples/04-html-in-canvas.tsxdiff --git a/knowledge/examples/05-anime-timeline.tsx b/docs/examples/05-anime-timeline.tsxsimilarity index 100%rename from knowledge/examples/05-anime-timeline.tsxrename to docs/examples/05-anime-timeline.tsxdiff --git a/knowledge/examples/06-three.tsx b/docs/examples/06-three.tsxsimilarity index 100%rename from knowledge/examples/06-three.tsxrename to docs/examples/06-three.tsxdiff --git a/knowledge/examples/07-webgpu.tsx b/docs/examples/07-webgpu.tsxsimilarity index 100%rename from knowledge/examples/07-webgpu.tsxrename to docs/examples/07-webgpu.tsxdiff --git a/knowledge/examples/08-shader-paint.tsx b/docs/examples/08-shader-paint.tsxsimilarity index 100%rename from knowledge/examples/08-shader-paint.tsxrename to docs/examples/08-shader-paint.tsxdiff --git a/knowledge/examples/09-inspect-variables.tsx b/docs/examples/09-inspect-variables.tsxsimilarity index 100%rename from knowledge/examples/09-inspect-variables.tsxrename to docs/examples/09-inspect-variables.tsxdiff --git a/knowledge/examples/10-typegpu.tsx b/docs/examples/10-typegpu.tsxsimilarity index 100%rename from knowledge/examples/10-typegpu.tsxrename to docs/examples/10-typegpu.tsxdiff --git a/knowledge/examples/11-redraw.tsx b/docs/examples/11-redraw.tsxsimilarity index 100%rename from knowledge/examples/11-redraw.tsxrename to docs/examples/11-redraw.tsxdiff --git a/knowledge/examples/README.md b/docs/examples/README.mdsimilarity index 100%rename from knowledge/examples/README.mdrename to docs/examples/README.mddiff --git a/knowledge/examples/tsconfig.json b/docs/examples/tsconfig.jsonsimilarity index 100%rename from knowledge/examples/tsconfig.jsonrename to docs/examples/tsconfig.jsondiff --git a/knowledge/guides/motion/easings.md b/docs/guides/motion/easings.mdsimilarity index 100%rename from knowledge/guides/motion/easings.mdrename to docs/guides/motion/easings.mddiff --git a/knowledge/guides/prompts/media-listen.md b/docs/guides/prompts/media-listen.mdsimilarity index 100%rename from knowledge/guides/prompts/media-listen.mdrename to docs/guides/prompts/media-listen.mddiff --git a/knowledge/guides/walkthroughs/podcast-clip.md b/docs/guides/walkthroughs/podcast-clip.mdsimilarity index 100%rename from knowledge/guides/walkthroughs/podcast-clip.mdrename to docs/guides/walkthroughs/podcast-clip.mddiff --git a/knowledge/guides/walkthroughs/talking-head.md b/docs/guides/walkthroughs/talking-head.mdsimilarity index 100%rename from knowledge/guides/walkthroughs/talking-head.mdrename to docs/guides/walkthroughs/talking-head.mddiff --git a/knowledge/reference/jsx/README.md b/docs/reference/jsx/README.mdsimilarity index 100%rename from knowledge/reference/jsx/README.mdrename to docs/reference/jsx/README.mddiff --git a/knowledge/reference/jsx/adjustment-layer.md b/docs/reference/jsx/adjustment-layer.mdsimilarity index 100%rename from knowledge/reference/jsx/adjustment-layer.mdrename to docs/reference/jsx/adjustment-layer.mddiff --git a/knowledge/reference/jsx/animations.md b/docs/reference/jsx/animations.mdsimilarity index 100%rename from knowledge/reference/jsx/animations.mdrename to docs/reference/jsx/animations.mddiff --git a/knowledge/reference/jsx/audio-sync.md b/docs/reference/jsx/audio-sync.mdsimilarity index 100%rename from knowledge/reference/jsx/audio-sync.mdrename to docs/reference/jsx/audio-sync.mddiff --git a/knowledge/reference/jsx/audio.md b/docs/reference/jsx/audio.mdsimilarity index 100%rename from knowledge/reference/jsx/audio.mdrename to docs/reference/jsx/audio.mddiff --git a/knowledge/reference/jsx/captions.md b/docs/reference/jsx/captions.mdsimilarity index 100%rename from knowledge/reference/jsx/captions.mdrename to docs/reference/jsx/captions.mddiff --git a/knowledge/reference/jsx/elements.md b/docs/reference/jsx/elements.mdsimilarity index 100%rename from knowledge/reference/jsx/elements.mdrename to docs/reference/jsx/elements.mddiff --git a/knowledge/reference/jsx/errors.md b/docs/reference/jsx/errors.mdsimilarity index 100%rename from knowledge/reference/jsx/errors.mdrename to docs/reference/jsx/errors.mddiff --git a/knowledge/reference/jsx/fonts.md b/docs/reference/jsx/fonts.mdsimilarity index 100%rename from knowledge/reference/jsx/fonts.mdrename to docs/reference/jsx/fonts.mddiff --git a/knowledge/reference/jsx/generate.md b/docs/reference/jsx/generate.mdsimilarity index 100%rename from knowledge/reference/jsx/generate.mdrename to docs/reference/jsx/generate.mddiff --git a/knowledge/reference/jsx/group.md b/docs/reference/jsx/group.mdsimilarity index 100%rename from knowledge/reference/jsx/group.mdrename to docs/reference/jsx/group.mddiff --git a/knowledge/reference/jsx/html.md b/docs/reference/jsx/html.mdsimilarity index 100%rename from knowledge/reference/jsx/html.mdrename to docs/reference/jsx/html.mddiff --git a/knowledge/reference/jsx/image.md b/docs/reference/jsx/image.mdsimilarity index 100%rename from knowledge/reference/jsx/image.mdrename to docs/reference/jsx/image.mddiff --git a/knowledge/reference/jsx/keyframes.md b/docs/reference/jsx/keyframes.mdsimilarity index 100%rename from knowledge/reference/jsx/keyframes.mdrename to docs/reference/jsx/keyframes.mddiff --git a/knowledge/reference/jsx/lifecycle.md b/docs/reference/jsx/lifecycle.mdsimilarity index 100%rename from knowledge/reference/jsx/lifecycle.mdrename to docs/reference/jsx/lifecycle.mddiff --git a/knowledge/reference/jsx/media.md b/docs/reference/jsx/media.mdsimilarity index 100%rename from knowledge/reference/jsx/media.mdrename to docs/reference/jsx/media.mddiff --git a/knowledge/reference/jsx/module.md b/docs/reference/jsx/module.mdsimilarity index 97%rename from knowledge/reference/jsx/module.mdrename to docs/reference/jsx/module.mdindex e204e442..4d94708f 100644--- a/knowledge/reference/jsx/module.md+++ b/docs/reference/jsx/module.md@@ -28,9 +28,9 @@ The component receives no props. [`open`](../tools/open.md) opens the folder —| `assets.yml` | The asset library (see [media.md](./media.md#the-library)). || `assets/` | The library's files: symlinks to media brought in from elsewhere, plus what the app produced itself, generations under `assets/generated/`. Media imported through the app is linked where it lies, never copied. || `cache/` | Derived data (thumbnails, waveforms). Disposable. |-| `README.md` | What the folder holds and how to work in it — including, for agents, that the app's MCP server carries this reference. |+| `README.md` | What the folder holds and how to work in it — including, for agents, where to find this reference. |-Everything is written once and is yours from then on. The reference itself is not copied into the project: the app serves the installed version's as MCP resources under `dapi://reference/`.+Everything is written once and is yours from then on. The reference itself is not copied into the project: it ships with the app, and the MCP server's instructions give agents the path of the installed version's `docs/`.## Idsdiff --git a/knowledge/reference/jsx/paints.md b/docs/reference/jsx/paints.mdsimilarity index 100%rename from knowledge/reference/jsx/paints.mdrename to docs/reference/jsx/paints.mddiff --git a/knowledge/reference/jsx/rect.md b/docs/reference/jsx/rect.mdsimilarity index 100%rename from knowledge/reference/jsx/rect.mdrename to docs/reference/jsx/rect.mddiff --git a/knowledge/reference/jsx/scene.md b/docs/reference/jsx/scene.mdsimilarity index 100%rename from knowledge/reference/jsx/scene.mdrename to docs/reference/jsx/scene.mddiff --git a/knowledge/reference/jsx/sequences.md b/docs/reference/jsx/sequences.mdsimilarity index 100%rename from knowledge/reference/jsx/sequences.mdrename to docs/reference/jsx/sequences.mddiff --git a/knowledge/reference/jsx/shader-paint.md b/docs/reference/jsx/shader-paint.mdsimilarity index 100%rename from knowledge/reference/jsx/shader-paint.mdrename to docs/reference/jsx/shader-paint.mddiff --git a/knowledge/reference/jsx/stage.md b/docs/reference/jsx/stage.mdsimilarity index 100%rename from knowledge/reference/jsx/stage.mdrename to docs/reference/jsx/stage.mddiff --git a/knowledge/reference/jsx/styles.md b/docs/reference/jsx/styles.mdsimilarity index 100%rename from knowledge/reference/jsx/styles.mdrename to docs/reference/jsx/styles.mddiff --git a/knowledge/reference/jsx/surface-paint.md b/docs/reference/jsx/surface-paint.mdsimilarity index 100%rename from knowledge/reference/jsx/surface-paint.mdrename to docs/reference/jsx/surface-paint.mddiff --git a/knowledge/reference/jsx/text.md b/docs/reference/jsx/text.mdsimilarity index 100%rename from knowledge/reference/jsx/text.mdrename to docs/reference/jsx/text.mddiff --git a/knowledge/reference/jsx/timing.md b/docs/reference/jsx/timing.mdsimilarity index 100%rename from knowledge/reference/jsx/timing.mdrename to docs/reference/jsx/timing.mddiff --git a/knowledge/reference/jsx/transitions.md b/docs/reference/jsx/transitions.mdsimilarity index 100%rename from knowledge/reference/jsx/transitions.mdrename to docs/reference/jsx/transitions.mddiff --git a/knowledge/reference/jsx/variables.md b/docs/reference/jsx/variables.mdsimilarity index 100%rename from knowledge/reference/jsx/variables.mdrename to docs/reference/jsx/variables.mddiff --git a/knowledge/reference/jsx/video.md b/docs/reference/jsx/video.mdsimilarity index 100%rename from knowledge/reference/jsx/video.mdrename to docs/reference/jsx/video.mddiff --git a/knowledge/reference/tools/README.md b/docs/reference/tools/README.mdsimilarity index 97%rename from knowledge/reference/tools/README.mdrename to docs/reference/tools/README.mdindex c2efeafd..efa000f1 100644--- a/knowledge/reference/tools/README.md+++ b/docs/reference/tools/README.md@@ -2,7 +2,7 @@Diffusion Studio exposes one set of tools, reachable two ways:-- **MCP.** The running app serves an MCP server at `http://127.0.0.1:3274/mcp` (Streamable HTTP) and on a local socket; `dapi mcp` pipes that socket to stdio for clients that only spawn processes. A connected agent gets every tool in `tools/list`, with the descriptions on these pages, this knowledge base as resources under `dapi://`, and two live resources, `dapi://context` and `dapi://logs`.+- **MCP.** The running app serves an MCP server at `http://127.0.0.1:3274/mcp` (Streamable HTTP) and on a local socket; `dapi mcp` pipes that socket to stdio for clients that only spawn processes. A connected agent gets every tool in `tools/list`, with the descriptions on these pages, and instructions that give the path of these docs in the installed app.- **CLI.** `dapi`, the command-line client shipped with the app, wraps every tool as a command for shells, scripts and CI. `dapi <command> --help` prints the same description and the same field help.Both validate against the same schemas and return the same result, so each tool is documented once, on its own page. The catalog behind all three (server, CLI, these pages) lives in `packages/dapi`.diff --git a/knowledge/reference/tools/capture.md b/docs/reference/tools/capture.mdsimilarity index 100%rename from knowledge/reference/tools/capture.mdrename to docs/reference/tools/capture.mddiff --git a/knowledge/reference/tools/check.md b/docs/reference/tools/check.mdsimilarity index 100%rename from knowledge/reference/tools/check.mdrename to docs/reference/tools/check.mddiff --git a/knowledge/reference/tools/context.md b/docs/reference/tools/context.mdsimilarity index 97%rename from knowledge/reference/tools/context.mdrename to docs/reference/tools/context.mdindex 7445751e..311e2a8b 100644--- a/knowledge/reference/tools/context.md+++ b/docs/reference/tools/context.md@@ -14,7 +14,7 @@ None.## What it does not say-The composition itself — its scenes, what is selected, which scene is active, the work area — is all in the JSX, and a caller that wants any of it reads the file. This report is only what the source cannot say. Over MCP it is also the live resource `dapi://context`.+The composition itself — its scenes, what is selected, which scene is active, the work area — is all in the JSX, and a caller that wants any of it reads the file. This report is only what the source cannot say.## Outputdiff --git a/knowledge/reference/tools/export.md b/docs/reference/tools/export.mdsimilarity index 100%rename from knowledge/reference/tools/export.mdrename to docs/reference/tools/export.mddiff --git a/knowledge/reference/tools/fetch.md b/docs/reference/tools/fetch.mdsimilarity index 100%rename from knowledge/reference/tools/fetch.mdrename to docs/reference/tools/fetch.mddiff --git a/knowledge/reference/tools/fonts.md b/docs/reference/tools/fonts.mdsimilarity index 100%rename from knowledge/reference/tools/fonts.mdrename to docs/reference/tools/fonts.mddiff --git a/knowledge/reference/tools/logs.md b/docs/reference/tools/logs.mdsimilarity index 82%rename from knowledge/reference/tools/logs.mdrename to docs/reference/tools/logs.mdindex c7d8ca17..9e4e7bc2 100644--- a/knowledge/reference/tools/logs.md+++ b/docs/reference/tools/logs.md@@ -14,7 +14,7 @@ Recent console output from the running app (what the devtools console shows: pag| `tail` | `integer` | `-n, --tail <n>` | return only the last n entries || `level` | `"debug" \| "info" \| "warning" \| "error"` | `-l, --level <level>` | minimum level to include: debug, info, warning, or error |-The buffer lives in the app's main process, so the log survives page reloads and project switches. Over MCP the same entries are the live resource `dapi://logs`. Progress of long operations — an export's percentage, a generation landing — shows up here, so polling `logs` is how a caller follows work it started.+The buffer lives in the app's main process, so the log survives page reloads and project switches. Progress of long operations — an export's percentage, a generation landing — shows up here, so polling `logs` is how a caller follows work it started.## Outputdiff --git a/knowledge/reference/tools/media/filmstrip.md b/docs/reference/tools/media/filmstrip.mdsimilarity index 100%rename from knowledge/reference/tools/media/filmstrip.mdrename to docs/reference/tools/media/filmstrip.mddiff --git a/knowledge/reference/tools/media/grab.md b/docs/reference/tools/media/grab.mdsimilarity index 100%rename from knowledge/reference/tools/media/grab.mdrename to docs/reference/tools/media/grab.mddiff --git a/knowledge/reference/tools/media/listen.md b/docs/reference/tools/media/listen.mdsimilarity index 100%rename from knowledge/reference/tools/media/listen.mdrename to docs/reference/tools/media/listen.mddiff --git a/knowledge/reference/tools/media/probe.md b/docs/reference/tools/media/probe.mdsimilarity index 100%rename from knowledge/reference/tools/media/probe.mdrename to docs/reference/tools/media/probe.mddiff --git a/knowledge/reference/tools/media/transcribe.md b/docs/reference/tools/media/transcribe.mdsimilarity index 100%rename from knowledge/reference/tools/media/transcribe.mdrename to docs/reference/tools/media/transcribe.mddiff --git a/knowledge/reference/tools/media/waveform.md b/docs/reference/tools/media/waveform.mdsimilarity index 100%rename from knowledge/reference/tools/media/waveform.mdrename to docs/reference/tools/media/waveform.mddiff --git a/knowledge/reference/tools/models.md b/docs/reference/tools/models.mdsimilarity index 100%rename from knowledge/reference/tools/models.mdrename to docs/reference/tools/models.mddiff --git a/knowledge/reference/tools/open.md b/docs/reference/tools/open.mdsimilarity index 100%rename from knowledge/reference/tools/open.mdrename to docs/reference/tools/open.mddiff --git a/knowledge/reference/tools/report.md b/docs/reference/tools/report.mdsimilarity index 100%rename from knowledge/reference/tools/report.mdrename to docs/reference/tools/report.mddiff --git a/knowledge/reference/tools/screenshot.md b/docs/reference/tools/screenshot.mdsimilarity index 100%rename from knowledge/reference/tools/screenshot.mdrename to docs/reference/tools/screenshot.mddiff --git a/knowledge/reference/tools/voices.md b/docs/reference/tools/voices.mdsimilarity index 100%rename from knowledge/reference/tools/voices.mdrename to docs/reference/tools/voices.mddiff --git a/knowledge/reference/tools/whoami.md b/docs/reference/tools/whoami.mdsimilarity index 100%rename from knowledge/reference/tools/whoami.mdrename to docs/reference/tools/whoami.mddiff --git a/knowledge/skills/editor.md b/docs/skills/editor.mdsimilarity index 100%rename from knowledge/skills/editor.mdrename to docs/skills/editor.mddiff --git a/knowledge/skills/watch.md b/docs/skills/watch.mdsimilarity index 100%rename from knowledge/skills/watch.mdrename to docs/skills/watch.md