Skip to content

The VS Code of video editing, built for agents.

TypeScript

Refactor knowledge base integration and update documentation

konstantin-paulus4d4cdda91e4c
diff --git a/README.md b/README.md
index 027019a2..37436f54 100644
--- a/README.md
+++ b/README.md
@@ -205,9 +205,9 @@ Conventions throughout: single results are one JSON value, collections are JSON
## Documentation
-- [CLI reference](reference/README.md): every command, its options, and its output
-- [JSX reference](reference/jsx/README.md): the composition markup with elements, timing, paints, generative assets, and captions
-- [Examples](examples/README.md): runnable compositions, from basic scenes and generative assets to three.js and raw WebGPU
+- [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
## Repository layout
diff --git a/apps/desktop/.gitignore b/apps/desktop/.gitignore
index 5f140748..54f86506 100644
--- a/apps/desktop/.gitignore
+++ b/apps/desktop/.gitignore
@@ -2,5 +2,4 @@ dist
web
out
cli
-docs
-skills
+knowledge
diff --git a/apps/desktop/forge.config.ts b/apps/desktop/forge.config.ts
index 5cfa8ce6..7bddecf7 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,docs,skills}.mjs; end up at
- // Contents/Resources/{cli,docs,skills}.
- extraResource: ['./cli', './docs', './skills'],
+ // Staged by scripts/stage-{cli,knowledge}.mjs; end up at
+ // Contents/Resources/{cli,knowledge}.
+ extraResource: ['./cli', './knowledge'],
osxSign: process.env.SKIP_SIGN ? undefined : {},
osxNotarize:
process.env.APPLE_ID && process.env.APPLE_PASSWORD && process.env.APPLE_TEAM_ID
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 09d4b1e6..553d10e8 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -15,13 +15,12 @@
"build": "npm run check && npm run build:main && npm run build:preload && 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:docs": "node scripts/stage-docs.mjs",
- "stage:skills": "node scripts/stage-skills.mjs",
+ "stage:knowledge": "node scripts/stage-knowledge.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:docs && npm run stage:skills && electron-forge package",
- "make": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge make",
- "publish": "npm run build && npm run build:web && npm run stage:cli && npm run stage:docs && npm run stage:skills && electron-forge publish",
+ "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",
"make:icns": "sh scripts/make-icns.sh",
"test": "vitest run"
},
diff --git a/apps/desktop/scripts/stage-docs.mjs b/apps/desktop/scripts/stage-docs.mjs
deleted file mode 100644
index 602fb4ec..00000000
--- a/apps/desktop/scripts/stage-docs.mjs
+++ /dev/null
@@ -1,26 +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/. */
-
-// Stages the authoring docs into apps/desktop/docs so electron-forge can ship
-// them as an app resource (Contents/Resources/docs). The layout mirrors the
-// repo — reference/ beside examples/ — because the relative links between the
-// pages assume it. scaffold() copies the tree into each project's
-// .diffusion/docs, so what an agent reads in a project is exactly what was
-// staged here (see src/projects.ts).
-
-import { cpSync, mkdirSync, rmSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
-const repoRoot = join(desktopDir, "..", "..");
-const stageDir = join(desktopDir, "docs");
-
-rmSync(stageDir, { recursive: true, force: true });
-mkdirSync(stageDir, { recursive: true });
-for (const name of ["reference", "examples"]) {
- cpSync(join(repoRoot, name), join(stageDir, name), { recursive: true });
-}
-
-console.log(`stage-docs: staged docs at ${stageDir}`);
diff --git a/apps/desktop/scripts/stage-knowledge.mjs b/apps/desktop/scripts/stage-knowledge.mjs
new file mode 100644
index 00000000..f7f1c7e5
--- /dev/null
+++ b/apps/desktop/scripts/stage-knowledge.mjs
@@ -0,0 +1,26 @@
+/* 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/. */
+
+// 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.
+
+import { cpSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
+const repoRoot = join(desktopDir, "..", "..");
+const stageDir = join(desktopDir, "knowledge");
+
+rmSync(stageDir, { recursive: true, force: true });
+mkdirSync(stageDir, { recursive: true });
+cpSync(join(repoRoot, "knowledge"), stageDir, {
+ recursive: true,
+ filter: (path) => !path.endsWith(".DS_Store") && !path.endsWith(".gitkeep"),
+});
+
+console.log(`stage-knowledge: staged the knowledge base at ${stageDir}`);
diff --git a/apps/desktop/scripts/stage-skills.mjs b/apps/desktop/scripts/stage-skills.mjs
deleted file mode 100644
index 119d3b20..00000000
--- a/apps/desktop/scripts/stage-skills.mjs
+++ /dev/null
@@ -1,51 +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/. */
-
-// Stages the agent skills into apps/desktop/skills so electron-forge can ship
-// them as an app resource (Contents/Resources/skills). The app symlinks agent
-// skill directories at these staged copies (see src/skills-install.ts), so
-// auto-updates keep installed skills in lockstep with the dapi they document.
-//
-// Prefers a sibling checkout of diffusionstudio/skills next to the repo root
-// (the dev setup); falls back to a shallow clone (CI).
-
-import { execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const SKILLS_REPO = "https://github.com/diffusionstudio/skills.git";
-
-const desktopDir = join(dirname(fileURLToPath(import.meta.url)), "..");
-const repoRoot = join(desktopDir, "..", "..");
-const stageDir = join(desktopDir, "skills");
-const sibling = join(repoRoot, "..", "skills");
-
-let sourceDir = sibling;
-let tempDir = null;
-if (!existsSync(join(sibling, "editor", "SKILL.md"))) {
- tempDir = mkdtempSync(join(tmpdir(), "stage-skills-"));
- execFileSync("git", ["clone", "--depth", "1", SKILLS_REPO, tempDir], { stdio: "inherit" });
- sourceDir = tempDir;
-}
-
-// A skill is a top-level directory with a SKILL.md.
-const skills = readdirSync(sourceDir, { withFileTypes: true })
- .filter((e) => e.isDirectory() && !e.name.startsWith("."))
- .filter((e) => existsSync(join(sourceDir, e.name, "SKILL.md")))
- .map((e) => e.name);
-
-if (skills.length === 0) {
- throw new Error(`stage-skills: no skills found in ${sourceDir}`);
-}
-
-rmSync(stageDir, { recursive: true, force: true });
-mkdirSync(stageDir, { recursive: true });
-for (const name of skills) {
- cpSync(join(sourceDir, name), join(stageDir, name), { recursive: true });
-}
-if (tempDir) rmSync(tempDir, { recursive: true, force: true });
-
-console.log(`stage-skills: staged ${skills.join(", ")} at ${stageDir}`);
diff --git a/apps/desktop/src/dapi/knowledge.test.ts b/apps/desktop/src/dapi/knowledge.test.ts
index 32c449cb..93f8ed33 100644
--- a/apps/desktop/src/dapi/knowledge.test.ts
+++ b/apps/desktop/src/dapi/knowledge.test.ts
@@ -2,7 +2,7 @@
* 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 { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+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";
@@ -13,33 +13,32 @@ import { instructions, registerResources } from "./knowledge";
import type { KnowledgeDeps } from "./knowledge";
-// A staged bundle in miniature: docs with a reference page, an example and a
-// stray file that is not a doc; a skill with frontmatter and a reference.
+// A knowledge base in miniature, laid out like the repo's `knowledge/`.
const root = mkdtempSync(join(tmpdir(), "dapi-knowledge-"));
-const docsDir = join(root, "docs");
-const skillsDir = join(root, "skills");
+const knowledgeDir = join(root, "knowledge");
const projectDir = join(root, "project");
beforeAll(() => {
- mkdirSync(join(docsDir, "reference", "jsx"), { recursive: true });
- mkdirSync(join(docsDir, "examples", "node_modules"), { recursive: true });
- writeFileSync(join(docsDir, "reference", "README.md"), "# Reference\n");
- writeFileSync(join(docsDir, "reference", "jsx", "text.md"), "# text\n");
- writeFileSync(join(docsDir, "examples", "01-hello.tsx"), "export default <scene />;\n");
- writeFileSync(join(docsDir, "examples", "package.json"), "{}\n");
- writeFileSync(join(docsDir, "examples", "node_modules", "ignored.md"), "no\n");
- mkdirSync(join(skillsDir, "editor", "references"), { recursive: true });
- writeFileSync(join(skillsDir, "editor", "SKILL.md"), "---\nname: editor\ndescription: trigger text\n---\n\n# Footage analysis\n\nProbe first.\n");
- writeFileSync(join(skillsDir, "editor", "references", "easings.md"), "# Easings\n");
+ 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\n---\nname: editor\npath: dapi://skills/editor.md\n---\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, "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);
- writeFileSync(join(projectDir, "AGENTS.md"), "# Project\n");
});
afterAll(() => rmSync(root, { recursive: true, force: true }));
-const deps = (projectOpen: boolean): KnowledgeDeps => ({
- docsDir,
- skillsDir,
+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: [] }),
});
@@ -55,56 +54,61 @@ async function connect(d: KnowledgeDeps): Promise<Client> {
}
describe("instructions", () => {
- it("is the preamble followed by the skill without its frontmatter", () => {
+ it("is INSTRUCTIONS.md followed by where the tree sits on disk", () => {
const text = instructions(deps(true));
- expect(text.startsWith("Diffusion Studio, a video editor")).toBe(true);
- expect(text).toContain("dapi://docs/reference/README.md");
- expect(text.endsWith("# Footage analysis\n\nProbe first.")).toBe(true);
- expect(text).not.toContain("trigger text");
+ expect(text.startsWith("Diffusion Studio is running.")).toBe(true);
+ expect(text).toContain("path: dapi://skills/editor.md");
+ expect(text).toContain(knowledgeDir);
});
- it("falls back to the preamble alone when nothing is staged", () => {
- const text = instructions({ ...deps(true), skillsDir: null });
- expect(text.startsWith("Diffusion Studio, a video editor")).toBe(true);
- expect(text).not.toContain("Footage analysis");
+ 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 the staged docs and skill references, docs only, no node_modules", async () => {
+ 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://docs/examples/01-hello.tsx",
- "dapi://docs/reference/README.md",
- "dapi://docs/reference/jsx/text.md",
+ "dapi://examples/01-hello.tsx",
"dapi://logs",
- "dapi://project/AGENTS.md",
- "dapi://skills/editor/SKILL.md",
- "dapi://skills/editor/references/easings.md",
+ "dapi://reference/README.md",
+ "dapi://reference/jsx/text.md",
+ "dapi://skills/editor.md",
]);
await client.close();
});
- it("reads a file, the live state, and the open project's AGENTS.md", async () => {
+ it("describes markdown pages by their first paragraph, skipping headings, frontmatter and tables", async () => {
const client = await connect(deps(true));
- expect((await client.readResource({ uri: "dapi://docs/reference/jsx/text.md" })).contents[0]).toMatchObject({
- mimeType: "text/markdown",
- text: "# text\n",
- });
- expect((await client.readResource({ uri: "dapi://docs/examples/01-hello.tsx" })).contents[0]).toMatchObject({ mimeType: "text/plain" });
+ 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);
- expect((await client.readResource({ uri: "dapi://project/AGENTS.md" })).contents[0]).toMatchObject({ text: "# Project\n" });
await client.close();
});
- it("explains a missing project instead of failing silently", async () => {
- const client = await connect(deps(false));
- await expect(client.readResource({ uri: "dapi://project/AGENTS.md" })).rejects.toThrow(/No project open/);
- 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("\\`");
});
});
diff --git a/apps/desktop/src/dapi/knowledge.ts b/apps/desktop/src/dapi/knowledge.ts
index fbdb3daf..afaa7309 100644
--- a/apps/desktop/src/dapi/knowledge.ts
+++ b/apps/desktop/src/dapi/knowledge.ts
@@ -2,11 +2,12 @@
* 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/. */
-// What an agent needs to know besides the tools: the server's instructions,
-// which every client receives on connect, and resources for the docs the app
-// ships, the skill's references, and the live state agents poll. All of it
-// comes from the files staged into the app bundle, so what an agent reads is
-// exactly what the installed version documents.
+// What an agent needs to know besides the tools, served from the knowledge
+// base staged into the app bundle (the repo's `knowledge/`): INSTRUCTIONS.md
+// is the server's instructions, which every client receives on connect, and
+// every other page is a resource under `dapi://<path>`, so what an agent
+// reads is exactly what the installed version documents. Two live
+// resources sit beside them for the state agents poll.
import { readdirSync, readFileSync, statSync } from "node:fs";
import { readFile } from "node:fs/promises";
@@ -16,47 +17,43 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { LogEntry, ToolOutput } from "@diffusionstudio/dapi";
export type KnowledgeDeps = {
- /** `Contents/Resources/docs`: `reference/` and `examples/`. Null when not staged. */
- docsDir: string | null;
- /** `Contents/Resources/skills`: one folder per skill with a SKILL.md. Null when not staged. */
- skillsDir: string | null;
+ /** The staged `knowledge/` tree. Null when not staged. */
+ knowledgeDir: string | null;
logs(): LogEntry[];
context(signal: AbortSignal): Promise<ToolOutput<"context">>;
};
-const DOC_EXTENSIONS = new Set([".md", ".ts", ".tsx"]);
+export const INSTRUCTIONS_FILE = "INSTRUCTIONS.md";
-const PREAMBLE = `Diffusion Studio, a video editor, is running on this machine and you are connected to it. The tools are the whole API: their names, descriptions and input schemas are authoritative and match the \`dapi\` command line one to one (\`media_grab\` is \`dapi media grab\`), so anything written for the CLI applies to the tools. Projects are folders of JSX; \`open\` a folder once, then write its files and save — the app recompiles and re-renders.
+const MIME_TYPES: Record<string, string> = {
+ ".md": "text/markdown",
+ ".ts": "text/plain",
+ ".tsx": "text/plain",
+ ".svg": "image/svg+xml",
+};
-Read the resources before relying on memory: \`dapi://docs/reference/README.md\` covers every tool, \`dapi://docs/reference/jsx/README.md\` is the JSX contract, \`dapi://docs/examples/\` holds complete compositions, and the skill's own references (brand, easings, worked examples) live under \`dapi://skills/\`. \`dapi://context\` reports the open project, the playhead and generation state; \`dapi://logs\` is the app's console; \`dapi://project/AGENTS.md\` is the open project's own entry point.`;
+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: a preamble about this server, then the editor skill. */
+/**
+ * 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 parts = [PREAMBLE];
- // Resources carry text; brand logos, fonts, and components to copy into a
- // project are files, so say where the same trees sit on disk.
- const onDisk = [deps.docsDir && `the docs at \`${deps.docsDir}\``, deps.skillsDir && `the skills at \`${deps.skillsDir}\``].filter(Boolean);
- if (onDisk.length > 0) parts.push(`The same files are on disk, for anything a resource cannot carry (logos, fonts, components to copy): ${onDisk.join(" and ")}. They belong to the app; read them, never edit them.`);
- const skill = deps.skillsDir ? readSkill(join(deps.skillsDir, "editor", "SKILL.md")) : null;
- if (skill) parts.push("The editor skill's guidance follows.", skill);
- return parts.join("\n\n");
-}
-
-function readSkill(path: string): string | null {
- let text: string;
- try {
- text = readFileSync(path, "utf8");
- } catch {
- return null;
+ const text = deps.knowledgeDir ? readText(join(deps.knowledgeDir, INSTRUCTIONS_FILE)) : null;
+ const parts = [text?.trim() || FALLBACK_INSTRUCTIONS];
+ if (deps.knowledgeDir) {
+ 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.`,
+ );
}
- // Drop the YAML frontmatter: the name and trigger description are for the
- // skills index, not for an agent already connected.
- return text.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+ return parts.join("\n\n");
}
export function registerResources(session: McpServer, deps: KnowledgeDeps): void {
- for (const file of staticFiles(deps)) {
- session.registerResource(file.name, file.uri, { title: file.name, mimeType: file.mimeType }, async () => ({
+ 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") }],
}));
}
@@ -78,35 +75,23 @@ export function registerResources(session: McpServer, deps: KnowledgeDeps): void
contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ entries: deps.logs() }) }],
}),
);
-
- session.registerResource(
- "project-agents",
- "dapi://project/AGENTS.md",
- { title: "Open project's AGENTS.md", description: "The agent entry point the app writes into every project.", mimeType: "text/markdown" },
- async (uri, extra) => {
- const { projectDir } = await deps.context(extra.signal);
- if (!projectDir) throw new Error("No project open — run open first");
- return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: await readFile(join(projectDir, "AGENTS.md"), "utf8") }] };
- },
- );
}
-type StaticFile = { name: string; uri: string; path: string; mimeType: string };
+type Page = { name: string; uri: string; path: string; mimeType: string; description?: string };
-// The listing is the same for every session; walk the staged trees once.
-let cache: { key: string; files: StaticFile[] } | null = null;
+// The listing is the same for every session; walk the staged tree once.
+let cache: { dir: string; pages: Page[] } | null = null;
-function staticFiles(deps: KnowledgeDeps): StaticFile[] {
- const key = `${deps.docsDir}\n${deps.skillsDir}`;
- if (cache?.key === key) return cache.files;
- const files: StaticFile[] = [];
- if (deps.docsDir) collect(deps.docsDir, deps.docsDir, "dapi://docs", files);
- if (deps.skillsDir) collect(deps.skillsDir, deps.skillsDir, "dapi://skills", files);
- cache = { key, files };
- return files;
+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, uriBase: string, out: StaticFile[]): void {
+function collect(root: string, dir: string, out: Page[]): void {
let entries: string[];
try {
entries = readdirSync(dir);
@@ -123,17 +108,38 @@ function collect(root: string, dir: string, uriBase: string, out: StaticFile[]):
continue;
}
if (isDirectory) {
- collect(root, path, uriBase, out);
+ collect(root, path, out);
continue;
}
- const extension = entry.slice(entry.lastIndexOf("."));
- if (!DOC_EXTENSIONS.has(extension)) continue;
+ const mimeType = MIME_TYPES[entry.slice(entry.lastIndexOf("."))];
+ if (!mimeType) continue;
const name = relative(root, path).split(sep).join("/");
- out.push({
- name,
- uri: `${uriBase}/${name}`,
- path,
- mimeType: extension === ".md" ? "text/markdown" : "text/plain",
- });
+ if (name === INSTRUCTIONS_FILE) continue; // already in every session's instructions
+ out.push({ name, uri: `dapi://${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.ts
index 4f726ff7..b37dfcc6 100644
--- a/apps/desktop/src/dapi/server.ts
+++ b/apps/desktop/src/dapi/server.ts
@@ -23,10 +23,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 docs (`reference/`, `examples/`), served as resources. Null when not staged. */
- docsDir: string | null;
- /** The staged skills; the editor skill is the server's instructions. Null when not staged. */
- skillsDir: string | null;
+ /** The staged knowledge base: INSTRUCTIONS.md for every session, the rest as resources. Null when not staged. */
+ knowledgeDir: string | null;
};
/**
@@ -113,8 +111,7 @@ export class DapiServer {
/** One MCP server over the whole catalog, plus the docs and live state as resources. */
private createSession(): McpServer {
const knowledge = {
- docsDir: this.deps.docsDir,
- skillsDir: this.deps.skillsDir,
+ knowledgeDir: this.deps.knowledgeDir,
logs: this.deps.logs,
context: (signal: AbortSignal) => this.renderer.call("context", {}, signal) as Promise<ToolOutput<"context">>,
};
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index a0421d5a..3cadaec0 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -99,11 +99,12 @@ const pendingDeepLinks = new Map<DeepLinkChannel, string>();
const LOG_BUFFER_MAX = 2000;
const logBuffer: LogEntry[] = [];
-// A folder staged into the app bundle by scripts/stage-*.mjs (Contents/
-// Resources/<name> when packaged, apps/desktop/<name> in dev), or null when
-// it has not been staged.
-function stagedResource(name: string): string | null {
- const dir = app.isPackaged ? join(process.resourcesPath, name) : join(app.getAppPath(), name);
+// 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");
return existsSync(dir) ? dir : null;
}
@@ -112,8 +113,7 @@ function stagedResource(name: string): string | null {
const dapi = new DapiServer({
version: app.getVersion(),
logs: () => logBuffer,
- docsDir: stagedResource("docs"),
- skillsDir: stagedResource("skills"),
+ knowledgeDir: knowledgeDir(),
onFirstConnection() {
enableHeadless();
if (mainWindow && !mainWindow.isDestroyed()) {
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index ecfd6086..6b93c379 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -5,7 +5,7 @@
import { app, dialog, shell, type BrowserWindow } from "electron";
import { execFile } from "node:child_process";
import { watch, type FSWatcher } from "node:fs";
-import { cp, mkdir, readdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
import { createRequire } from "node:module";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { nanoid } from "nanoid";
@@ -565,6 +565,14 @@ a plain npm package whose entry file is a [Solid](https://www.solidjs.com)
component; the app compiles it and renders every element into an editable node
on the canvas.
+## Agents
+
+Everything an agent needs is in the app's MCP server (\`dapi\`): its tools
+are the API, its instructions say how to work, and its resources are the
+authoring reference for the installed version. If it is not among your tools,
+add it — the app serves it at \`${MCP_URL}\` while it is running — and start
+a new session.
+
## Structure
| Path | What it is |
@@ -575,7 +583,6 @@ on the canvas.
| \`assets.yml\` | The asset library: for every asset its library path, where its bytes are, and what it was found to be. Written by the app; hand edits are read on the next load. |
| \`assets/\` | The library's files: put one here and it is taken in while the app watches, and the app writes its own here too — generations under \`assets/generated/\`. Media imported through the app is linked where it lies instead, never copied. |
| \`cache/\` | Derived data (thumbnails, waveforms). Disposable, and not checked in. |
-| \`AGENTS.md\` | The agent entry point: how to connect to the app, whose MCP server carries the authoring reference, and how to work here. |
## Authoring
@@ -662,61 +669,9 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.
## Reference
-- [JSX reference](https://github.com/diffusionstudio/editor/blob/main/reference/jsx/README.md): elements, timing, paints, generation, captions
-- [CLI reference](https://github.com/diffusionstudio/editor/blob/main/reference/README.md): every command, its options and its output
-- [Examples](https://github.com/diffusionstudio/editor/tree/main/examples): runnable compositions to read
-`;
-
-/**
- * The agent entry point, written once like the README: the file coding agents
- * load without being asked, and therefore the one place a project is reliably
- * discovered from. It points at the app rather than carrying docs of its own:
- * the reference lives in the app's MCP server, so it is always the installed
- * version's, and being the author's file after the first write, an agent can
- * append project conventions to it while the pointer stays put.
- */
-const AGENTS = `# Authoring this project
-
-A Diffusion Studio project: a video composition authored as code. The entry
-(\`index.tsx\`) default-exports a Solid component that renders a \`<stage>\`;
-the app compiles it and renders every element into an editable node on the
-canvas. The source is the document in both directions: saving recompiles and
-remounts the project, and edits made in the app land back in the JSX as props
-on the element they were authored as.
-
-## Connect to the app
-
-The authoring reference lives in the app, not in this folder, so it is always
-the installed version's. Connect to the app's MCP server at
-\`${MCP_URL}\` — \`dapi open <this folder>\` launches the app and opens the
-project, or launch the app and open it there. The server's instructions say
-how to work; its resources are the docs; its tools are the API.
-
-| Read | For |
-| ---- | --- |
-| \`dapi://docs/reference/jsx/README.md\` | The JSX contract — elements, props, pipeline. Start here. |
-| \`dapi://docs/reference/jsx/timing.md\` | \`start\`/\`end\`/\`sourceIn\`/\`sourceOut\`, and the time formats. |
-| \`dapi://docs/reference/jsx/generate.md\` | Declaring AI-generated assets (\`generate.*\`). |
-| \`dapi://docs/reference/jsx/variables.md\` | \`@inspect\` variables: annotated consts as live inspector controls. |
-| \`dapi://docs/reference/README.md\` | Every tool, its arguments and its output. |
-| \`dapi://docs/examples/\` | Complete compositions, basics through shaders. |
-| \`dapi://context\` | What the app has open, where its playhead sits, and where generations stand. |
-
-Without MCP, the same tools are the \`dapi\` command line, with the same
-descriptions under \`--help\`. Every command is an npm script here:
-\`npm run\` lists them, \`npm run <name> -- <args>\` runs one.
-
-## Working here
-
-- Verify visually with the \`capture\` tool (\`npm run capture -- <sceneId>\`):
- it renders the scene's frames exactly as an export encodes them. Do not
- export a video to check work.
-- Position and size are explicit, in pixels. There is no layout pass and no CSS.
-- A composition you author from scratch marks one scene \`active\` and gives
- \`<stage>\` a \`camera\` framing it, or the project opens on an empty timeline
- with the frame off screen.
-- Times are seconds (\`1.5\`), frames (\`"45f"\`), or \`"MM:SS"\`.
-- Types are stripped at compile time, never checked: run \`npx tsc --noEmit\`.
+- [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
`;
// ---------------------------------------------------------------------------
@@ -725,25 +680,10 @@ descriptions under \`--help\`. Every command is an npm script here:
/**
* The project-relative folder the app owns outright, ignored by git and by
* the project watcher. Earlier versions copied the authoring docs into it;
- * the docs now live in the app's MCP server, so the folder is only cleared.
+ * the docs now live in the app's MCP server.
*/
const APP_DIR = ".diffusion";
-/**
- * Removes the docs copy earlier versions kept in `.diffusion/docs`. They
- * would describe an app that is no longer installed, and an agent that finds
- * them would trust them over the server. Best-effort: nothing depends on it.
- */
-async function removeLegacyDocs(dir: string): Promise<void> {
- const appDir = join(dir, APP_DIR);
- await rm(join(appDir, "docs"), { recursive: true, force: true });
- try {
- await rmdir(appDir);
- } catch {
- // Not empty, or never there.
- }
-}
-
async function writeIfMissing(dir: string, name: string, content: string): Promise<void> {
const path = join(dir, name);
if (await exists(path)) return;
@@ -794,9 +734,7 @@ export async function scaffold(dir: string, displayName = basename(dir)): Promis
await writeIfMissing(dir, "tsconfig.json", TSCONFIG);
await writeIfMissing(dir, ".gitignore", GITIGNORE);
await writeIfMissing(dir, "README.md", readme(displayName));
- await writeIfMissing(dir, "AGENTS.md", AGENTS);
- await removeLegacyDocs(dir).catch(() => {});
if (!(await exists(join(dir, MANIFEST_FILE)))) {
await writeManifest(dir, EMPTY_MANIFEST);
diff --git a/docs/mcp-server.md b/docs/mcp-server.md
index dd5bb157..7e0b37f1 100644
--- a/docs/mcp-server.md
+++ b/docs/mcp-server.md
@@ -153,7 +153,7 @@ Main keeps a map of in-flight calls. Before sending it waits for the renderer to
This does mean main sees payloads, which the current design deliberately avoids. The cost is one structured-clone copy over Electron IPC per call. Frame data crosses as `Uint8Array` rather than base64 strings to keep that copy cheap; base64 encoding happens once, in main, only for the blocks that are inlined.
-**Resources and instructions.** Every session carries `instructions`: a short preamble about this server followed by the editor skill's `SKILL.md`, read from the staged skills folder, so an agent that connects knows how to work with the app without a separate skills install. The staged docs are served as resources (`dapi://docs/reference/…`, `dapi://docs/examples/…`) alongside the skill's references (`dapi://skills/editor/…`), and three live ones: `dapi://context` (what `context` returns), `dapi://logs`, and `dapi://project/AGENTS.md` for the open project. Implemented in `apps/desktop/src/dapi/knowledge.ts`.
+**Resources and instructions.** Every session carries `instructions`: `knowledge/INSTRUCTIONS.md`, an orientation and an index of the skills to read, so an agent that connects knows how to work with the app without a separate skills install. The rest of the knowledge base is served as resources under `dapi://<path>` (`dapi://reference/…`, `dapi://examples/…`, `dapi://guides/…`, `dapi://brand/…`, `dapi://skills/…`), and two live ones: `dapi://context` (what `context` returns) and `dapi://logs`. Implemented in `apps/desktop/src/dapi/knowledge.ts`.
**HTTP.** Beside the socket, main serves the same sessions over Streamable HTTP at `http://127.0.0.1:3274/mcp` (`apps/desktop/src/dapi/http.ts`; the constants live in `@diffusionstudio/dapi/socket`). One MCP server per session, keyed by the transport's session id; the SDK's DNS-rebinding protection is on with the loopback hosts allowed. This is the transport agents register: a URL that is the same on every machine.
@@ -179,7 +179,7 @@ Removed from the CLI package: `cli-client.ts`, `cli-channels.ts`, the tRPC and `
### 4. Skill and reference docs
-*Superseded on `mcp-support`: with the server carrying the skill as `instructions` and the docs as resources, the two external copies are gone. The app no longer symlinks skills into agent directories (`skills-install.ts` is deleted, with its onboarding row), and it no longer copies `reference/` and `examples/` into every project's `.diffusion/docs` (the scaffold removes a copy left by an earlier version). A project's `AGENTS.md` now points at the server: the URL, the resource URIs to read first, and the CLI as the no-MCP fallback. Only the staged copies inside the app bundle remain, and they are what the server serves, so an agent can only ever read the installed version's docs. The skill text itself still comes from the skills repo at staging time and is what step 5 updates.*
+*Superseded on `mcp-support`: with the server carrying the skill as `instructions` and the docs as resources, the two external copies are gone. The app no longer symlinks skills into agent directories (`skills-install.ts` is deleted, with its onboarding row), and it no longer copies `reference/` and `examples/` into every project's `.diffusion/docs` (a copy left by an earlier version is left alone). Projects get no `AGENTS.md` any more; their README says everything goes through the server and gives the URL, which is enough for an agent that lacks it to add it. Only the staged copies inside the app bundle remain, and they are what the server serves, so an agent can only ever read the installed version's docs. The knowledge base now lives in this repo under `knowledge/` (instructions, skills, guides, reference, examples, brand) and is staged whole by `scripts/stage-knowledge.mjs`; the separate skills repo is no longer a source.*
`apps/desktop/skills/editor/SKILL.md` currently says the CLI is self-describing via `--help`. It changes to name the MCP tools and to say that `tools/list` is authoritative, with a short fallback paragraph for environments without MCP (use `dapi call`). The per-command files in `reference/` become per-tool, and their option tables are generated from the catalog so they cannot drift either. `reference/README.md` loses the sentence about "every command talks to the running app over a local socket" and gains one about the server.
diff --git a/knowledge/INSTRUCTIONS.md b/knowledge/INSTRUCTIONS.md
index 84c192e0..873e3fad 100644
--- a/knowledge/INSTRUCTIONS.md
+++ b/knowledge/INSTRUCTIONS.md
@@ -1,6 +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.
+Projects are folders of JSX; `open` a folder once, then write its files and save — the app recompiles and re-renders.
---
name: editor
@@ -9,7 +9,7 @@ description: >-
CLI: analyze video/audio/images, generate them with AI, and compose video
compositions. Use for any media analysis, media generation, or video editing
task.
-path: /skills/editor.md
+path: dapi://skills/editor.md
---
name: watch
description: >-
@@ -19,5 +19,5 @@ description: >-
whenever the user asks what's in a piece of footage, wants a summary or
recap, wants to locate a moment ("where does X happen", "find the scene
where..."), or needs a claim about a video or audio file checked.
-path: /skills/watch.md
+path: dapi://skills/watch.md
---
diff --git a/knowledge/examples/tsconfig.json b/knowledge/examples/tsconfig.json
index bbcb6f5a..a6d24286 100644
--- a/knowledge/examples/tsconfig.json
+++ b/knowledge/examples/tsconfig.json
@@ -1,5 +1,5 @@
{
- "extends": "../tsconfig.base.json",
+ "extends": "../../tsconfig.base.json",
"compilerOptions": {
"jsx": "preserve",
"jsxImportSource": "@diffusionstudio/jsx",
diff --git a/knowledge/guides/motion/easings.md b/knowledge/guides/motion/easings.md
new file mode 100644
index 00000000..677718e1
--- /dev/null
+++ b/knowledge/guides/motion/easings.md
@@ -0,0 +1,22 @@
+# Easings
+
+Six go-to cubic beziers, in mirrored pairs. Choose from the intended weight, energy, and continuity of the action — never leave a move on linear or a default curve.
+
+| Easing | Value | Use for |
+| --- | --- | --- |
+| `snappyOut` | `cubicBezier(0,0.6,0.4,1)` | Energetic entrances that settle softly |
+| `expoOut` | `cubicBezier(0,1,0,1)` | Dramatic reveals, scale pops, counters |
+| `snappyIn` | `cubicBezier(0.6,0,1,0.4)` | Wind-ups that exit at full speed |
+| `expoIn` | `cubicBezier(1,0,1,0)` | Anticipation into a hard exit or cut |
+| `outIn` | `cubicBezier(0,0.7,1,0.3)` | Motion carried across a cut, whip feel |
+| `inOut` | `cubicBezier(0.7,0,0.3,1)` | A-to-B moves at rest on both ends |
+
+Across a cut, alternate them so objects are at their highest velocity at the moment of the cut: ease in to animate out, followed by ease out for the reveal.
+
+Motion graphics are motion: this is not a presentation or a static website. Elements that fade in, sit still, and fade out read as slides. Keep energy in the frame — overlap entrances and exits, stagger siblings by a few frames, keep something moving during holds (a slow drift, scale, or counter), and drive every move with one of these curves.
+
+## Pixel snapping
+
+There is no sub-pixel rendering: everything lands on whole pixels, so a move slower than roughly one pixel per frame sits still and then jumps rather than gliding. Before committing to a move, divide its travel in pixels by its duration in frames — `y: -10` over `3400ms` is a tenth of a pixel per frame, a stutter, not a drift. The same math applies to scale and rotation: measure the travel of the edge that moves most, not the property value.
+
+Slow holds are where this bites. Keep the drift above the limit by moving further or over a shorter stretch, or carry the hold with something that isn't tied to position at all — opacity, blur, color, a counter.
diff --git a/knowledge/reference/jsx/README.md b/knowledge/reference/jsx/README.md
index fc4887dd..2a232ea1 100644
--- a/knowledge/reference/jsx/README.md
+++ b/knowledge/reference/jsx/README.md
@@ -62,7 +62,7 @@ Everything below runs in the app, on open and again on every save of a project f
2. **Compile**: the entry file bundles with esbuild + `babel-preset-solid` in `universal` mode, so JSX compiles against the editor's renderer runtime instead of the DOM. `solid-js`, `solid-js/store` and `@diffusionstudio/jsx` are external — the app supplies its own instances; everything else is bundled. A compile error is reported and the canvas keeps the last good render.
3. **Evaluate**: the app imports the module. Top-level code runs to completion. The module's **default export** is the project component.
4. **Mount**: the component tree renders **directly into the world**. There is no staging tree: each element materializes as an entity as it is created, and the root `<stage>` is the one already there. Mounting is synchronous, and a throw part-way through leaves nothing behind — the document is disposed and the previous render stays on the canvas.
-5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`dapi context`](../context.md) reports where each generation stands.
+5. **Resolve**: every `src` resolves in the background — a path or asset id is loaded, a `generate.*` declaration is generated in dependency order, a `<captions>` without a `src` transcribes its scene. Each element renders a generating state until its asset lands, and an element that fails carries the reason (see [generate.md](./generate.md), [errors.md](./errors.md)). Non-blocking: the composition is on the canvas and editable while this runs, and [`dapi context`](../tools/context.md) reports where each generation stands.
6. **Live**: the reactive graph keeps running for as long as the project is open — signals, effects, `useTicker` (see [lifecycle.md](./lifecycle.md)). Export, capture and the next open re-execute the same module.
A save replaces the whole run: the old mount is disposed and the new one takes the stage. Scenes are rebuilt rather than accumulated, and the entities the previous render owned go with it.
diff --git a/knowledge/reference/jsx/errors.md b/knowledge/reference/jsx/errors.md
index 1ba9689b..3dc3099d 100644
--- a/knowledge/reference/jsx/errors.md
+++ b/knowledge/reference/jsx/errors.md
@@ -4,9 +4,9 @@ Where each [pipeline](./README.md#pipeline) stage fails, and with what effect:
| Stage | Where it surfaces | Effect |
| ----- | ----------------- | ------ |
-| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`dapi logs`](../logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |
+| **Compile** (syntax, an unresolved import, a PascalCase composition tag, a control-flow component with no import) | A "Project failed to compile" toast, with the compiler's message; also on the app console ([`dapi logs`](../tools/logs.md)) | Nothing is remounted. The canvas keeps the last good render, so a project in the middle of an edit is never blanked. |
| **Evaluate / mount** (a throw at module scope or during render, a root that is not `<stage>`, a tag the host does not know, an element parented into its own subtree) | A "Project failed to render" toast with the thrown message | The half-built document is disposed — **nothing is left behind** — and the previous render stays on the canvas. |
-| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`dapi context`](../context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |
+| **Source resolution** (a path that does not exist, an unreachable URL, a per-model constraint on `aspectRatio` / `duration` / a feature flag, a caption with no audible audio in its scene) | The element on the canvas, and `generations` in [`dapi context`](../tools/context.md) | Per element, not per mount: everything else stays mounted and playable. The element stops showing its generating state and is left without a paint, carrying the reason — see below. |
Runtime errors are reported against the compiled module. Since types are stripped rather than checked, run `npx tsc --noEmit` in the project folder to catch what the compile will not.
diff --git a/knowledge/reference/jsx/fonts.md b/knowledge/reference/jsx/fonts.md
index dce05467..d65fa0fc 100644
--- a/knowledge/reference/jsx/fonts.md
+++ b/knowledge/reference/jsx/fonts.md
@@ -1,6 +1,6 @@
# Fonts
-Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
+Both text paths draw with fonts **installed on the machine**. Discover what is available with [`dapi fonts`](../tools/fonts.md) (filter by family, weight, or style); the active project's families are also on [`dapi context`](../tools/context.md) as `fontFamilies`. macOS resolves these families for both the native renderer and the browser, so there is nothing to bundle or load.
## Native `<text>`
@@ -22,7 +22,7 @@ In [`<html>`](./html.md) you style text with ordinary CSS, so **use a locally in
</html>
```
-Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`dapi fonts`](../fonts.md) is the safer default for anything you have to be able to re-render on demand.
+Remote web fonts work too (a Google Fonts `<link>`, or an `@font-face` with a `url()` source). However the cost is that every render then depends on the network and on the font host staying up, so a local family from [`dapi fonts`](../tools/fonts.md) is the safer default for anything you have to be able to re-render on demand.
If you want to pin an exact variant, declare an `@font-face` whose source is the CSS `local()` string that `dapi fonts` reports for that variant (never a `url()`):
diff --git a/knowledge/reference/jsx/generate.md b/knowledge/reference/jsx/generate.md
index 70e24003..1c50607b 100644
--- a/knowledge/reference/jsx/generate.md
+++ b/knowledge/reference/jsx/generate.md
@@ -34,11 +34,11 @@ export default function Project() {
Declarations are **pure**: calling `generate.*` validates its options and returns a ref; nothing is requested until an element carrying it mounts. A ref that is never used by a mounted element (directly or as an input to another asset) is never generated. Declarations may live at module scope or inside components.
-Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`dapi context`](../context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).
+Generation is **asynchronous and non-blocking**: the element is on the canvas immediately, showing a generating state, and its paint attaches when the asset lands. [`dapi context`](../tools/context.md) reports where each one stands — generating, failed with the reason, or done with the library path it landed as — and a declaration that fails leaves its element carrying an [`error`](./errors.md#failed-sources).
## Declaration options
-Run [`dapi models <type>`](../models.md) to discover valid `model` ids and per-model constraints; [`dapi voices`](../voices.md) lists voices.
+Run [`dapi models <type>`](../tools/models.md) to discover valid `model` ids and per-model constraints; [`dapi voices`](../tools/voices.md) lists voices.
```ts
type AssetInput = string | AssetRef; // path, URL, asset id, or another declaration
diff --git a/knowledge/reference/jsx/html.md b/knowledge/reference/jsx/html.md
index 229cfcf6..df9df88a 100644
--- a/knowledge/reference/jsx/html.md
+++ b/knowledge/reference/jsx/html.md
@@ -75,7 +75,7 @@ Like all paints, `<htmlPaint>` stacks with siblings in document order and clips
## Persistence and export
-The module is re-executed in every context: on reload, export, and [`dapi capture`](../capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).
+The module is re-executed in every context: on reload, export, and [`dapi capture`](../tools/capture.md) the engine re-executes it and rebuilds the DOM content in that context. Exports wait for the browser's rendering update before sampling each frame, so the drawn HTML appears in the output; ticker-driven signals follow the playhead and animate frame-accurately. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree).
## Requirements and limitations
diff --git a/knowledge/reference/jsx/media.md b/knowledge/reference/jsx/media.md
index fc639481..0b6a594a 100644
--- a/knowledge/reference/jsx/media.md
+++ b/knowledge/reference/jsx/media.md
@@ -58,7 +58,7 @@ mkdir -p assets/b-roll && ln -s ~/Movies/drone.mp4 assets/b-roll/
<video src="b-roll/drone.mp4" width={1920} height={1080} />
```
-Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`dapi fetch`](../fetch.md) writes to disk and nothing else, so `-o assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.
+Link rather than copy: the bytes stay where they are, the project holds nothing but a name for them, and the library still gets a portable path to reach them by. Give `ln -s` an absolute target — a relative link is read against the folder the link sits in, so it breaks as soon as the project moves. A directory of numbered frames is taken in whole, as one [image sequence](#image-sequences), rather than as a file each, and a link to that directory does the same. [`dapi fetch`](../tools/fetch.md) writes to disk and nothing else, so `-o assets/b-roll/` is how a download becomes an asset; `generate.*` results arrive under `assets/generated/` on their own.
A link is the project's, and what it points at is not. Deleting a linked asset in the panel removes the link and stops there.
diff --git a/knowledge/reference/jsx/module.md b/knowledge/reference/jsx/module.md
index 8f85bc9a..bb5de2e6 100644
--- a/knowledge/reference/jsx/module.md
+++ b/knowledge/reference/jsx/module.md
@@ -14,7 +14,7 @@ export default function Project() {
}
```
-The component receives no props. [`dapi open <dir>`](../open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.
+The component receives no props. [`dapi open <dir>`](../tools/open.md) opens the folder — creating it, and an `index.tsx` holding an empty stage, if it is not a project yet.
## The folder
@@ -28,9 +28,9 @@ The component receives no props. [`dapi open <dir>`](../open.md) opens the folde
| `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. |
-| `AGENTS.md` | The agent entry point: how to connect to the app, whose MCP server carries this reference, and how to work here. |
+| `README.md` | What the folder holds and how to work in it — including, for agents, that the app's MCP server carries 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://docs/`.
+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/`.
## Ids
@@ -40,7 +40,7 @@ Every composition element carries an `id`, and the app stamps one onto every ele
<rect id="k3f9x1" x={40} y={40} width={640} height={360} fill="#FF0055" />
```
-An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`dapi capture`](../capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.
+An id is what makes an element addressable: it is how an entity is traced back to the JSX that produced it, so a change made on the canvas can be written to the element it came from, and it is what [`dapi capture`](../tools/capture.md) takes to render one node. It is also how elements point at each other within a render — [`syncTo`](./audio-sync.md) names the id of the clip it aligns against.
**Ids are yours to write.** Any string is valid, and `id="hero"` is worth more to read than anything minted. The stamp only fills in elements that have none, so renaming one by hand is safe. Ids are stripped at compile time and never reach the runtime as a prop; what survives is the stamp that carries them.
diff --git a/knowledge/reference/jsx/shader-paint.md b/knowledge/reference/jsx/shader-paint.md
index 965ca2a0..389fb84f 100644
--- a/knowledge/reference/jsx/shader-paint.md
+++ b/knowledge/reference/jsx/shader-paint.md
@@ -96,7 +96,7 @@ Swapping `wgsl` recompiles the pipeline asynchronously; the media shows unshaded
## Errors and limitations
-- WGSL compile errors are reported on the app console ([`dapi logs`](../logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.
+- WGSL compile errors are reported on the app console ([`dapi logs`](../tools/logs.md)) with line numbers relative to your source; the paint renders as passthrough until a fix lands.
- Pipeline compilation is asynchronous. Live playback may show the first frames unshaded; exports wait for compilation, so rendered output is always shaded.
- One shader reads one media paint; shaders do not chain and do not read solid/gradient/html/surface paints or the composited stack (over those the shader runs procedurally and stacks on top).
- For full custom pipelines (own vertex stage, WebGL, three.js) use [`<surface>`](./surface-paint.md), which owns its canvas outright.
diff --git a/knowledge/reference/jsx/stage.md b/knowledge/reference/jsx/stage.md
index 7e2c1634..15b5a7cb 100644
--- a/knowledge/reference/jsx/stage.md
+++ b/knowledge/reference/jsx/stage.md
@@ -42,4 +42,4 @@ The stage takes no timing, no transform and no paints — it is not a node, it i
A root's place on the canvas is its own `x`/`y`, in the same document space the camera matrix moves through. Roots that do not say where they sit all sit at the origin, on top of each other; give each after the first an `x` clear of the ones before it, as the example above does.
-Which scene the playhead, the timeline and [`dapi capture`](../capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.
+Which scene the playhead, the timeline and [`dapi capture`](../tools/capture.md) are pointed at is a scene's `active`, not the stage's business. At most one scene carries it, and only a direct child of `<stage>` can.
diff --git a/knowledge/reference/jsx/surface-paint.md b/knowledge/reference/jsx/surface-paint.md
index 843d6ed6..415072e4 100644
--- a/knowledge/reference/jsx/surface-paint.md
+++ b/knowledge/reference/jsx/surface-paint.md
@@ -126,7 +126,7 @@ Like all paints it stacks with siblings in document order and clips to the paren
## Persistence and export
-The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).
+The module is re-executed in every context, so the drawing is reproducible rather than ephemeral: on reload, export, and [`dapi capture`](../tools/capture.md) the engine re-runs your drawing code against a fresh canvas driven by that context's playhead, so ticker surfaces animate in exports. The bitmap itself is not stored; your code reproduces it. This assumes the module's structure is deterministic (`Math.random()`/`Date.now()` must not decide the shape of the tree; using them inside a draw effect is fine).
**Async setup has to be held.** Because that re-execution is a fresh mount, a model, a texture, or a device your drawing waits for is fetched again there — and sampling begins as soon as the render returns, so the first frames are written from a canvas nothing has drawn into yet. Hand the promise to [`useTicker().hold`](./lifecycle.md#hold) and those frames wait for it:
diff --git a/knowledge/reference/jsx/text.md b/knowledge/reference/jsx/text.md
index b93ed70e..8e9d1fe0 100644
--- a/knowledge/reference/jsx/text.md
+++ b/knowledge/reference/jsx/text.md
@@ -18,7 +18,7 @@ All [common props](./elements.md#common-props), plus:
| ---- | ---- | ------- | ------- |
| children | `string` (or expressions resolving to strings) | **required** | The text content, alongside any `<textRange>`, paint, `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children. |
| `color` | `string` | none | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). A text with neither `color` nor a paint child draws no glyphs. |
-| `fontFamily` | `string` | `Inter` | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |
+| `fontFamily` | `string` | `Inter` | A family available on the machine ([`dapi fonts`](../tools/fonts.md)); see [fonts.md](./fonts.md). |
| `fontSize` | `number` | `16` | Px. |
| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`–`900`. |
| `fontStyle` | `"normal" \| "italic" \| "oblique"` | `"normal"` | |
diff --git a/knowledge/reference/jsx/timing.md b/knowledge/reference/jsx/timing.md
index adbed9f6..b795f66a 100644
--- a/knowledge/reference/jsx/timing.md
+++ b/knowledge/reference/jsx/timing.md
@@ -62,4 +62,4 @@ The canonical internal unit is frames at **30 fps**; all formats are converted o
| `"MM:SS"` | `"02:30"` | Minutes and seconds. |
| `"HH:MM:SS"` | `"01:02:30"` | Hours, minutes, seconds. |
-CLI flags documented as taking a `Time` value (e.g. `--time` on [`capture`](../capture.md) and [`media grab`](../media/grab.md)) accept the same formats. Times in command **output** are plain seconds.
+CLI flags documented as taking a `Time` value (e.g. `--time` on [`capture`](../tools/capture.md) and [`media grab`](../tools/media/grab.md)) accept the same formats. Times in command **output** are plain seconds.
diff --git a/knowledge/reference/tools/README.md b/knowledge/reference/tools/README.md
index 7316bedc..ef0f979c 100644
--- a/knowledge/reference/tools/README.md
+++ b/knowledge/reference/tools/README.md
@@ -2,7 +2,7 @@
Reference for `dapi`, the Diffusion Studio CLI. Every canvas and project command talks to the running app over a local socket. Responses are JSON written to stdout; errors are human-readable messages on stderr with a non-zero exit.
-Each feature command has its own file (linked below). The JSX code syntax specified in [jsx/](./jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.
+Each feature command has its own file (linked below). The JSX code syntax specified in [jsx/](../jsx/README.md) is **pseudo-SVG**, mirroring SVG's shape-and-paint model with the editor's own tags and props rather than the SVG spec.
A project is a folder of that JSX, and **the source is the document**: the app compiles the entry file and renders every element into an editable node, and edits made on the canvas are written back to the element that authored them. So the loop is `dapi open <dir>` once, then edit the files — there is no command that pushes content into the app. What the commands do is read the running app ([`context`](./context.md), [`capture`](./capture.md), [`logs`](./logs.md)), inspect media, and list what a declaration may name.
@@ -16,7 +16,7 @@ A project is a folder of that JSX, and **the source is the document**: the app c
How the surface is divided:
-- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](./jsx/generate.md)). `models` and `voices` list what those declarations can reference.
+- AI asset generation (image / video / speech / audio) is declared in the project module (`generate.*`, see [jsx/generate.md](../jsx/generate.md)). `models` and `voices` list what those declarations can reference.
- Inspecting an existing asset (probe / transcribe / listen / filmstrip / waveform / grab) lives under `media`.
## Commands
diff --git a/knowledge/reference/tools/context.md b/knowledge/reference/tools/context.md
index 89f1277d..8b5a86aa 100644
--- a/knowledge/reference/tools/context.md
+++ b/knowledge/reference/tools/context.md
@@ -52,4 +52,4 @@ blocking: generation is asynchronous, so poll this until nothing is
[`dapi media probe`](./media/probe.md) and its siblings; a `failed` row's
`error` is the same message the element carries as its `error` prop, which is
what keeps it from being generated again (see
-[jsx/errors.md](./jsx/errors.md#failed-sources)).
+[jsx/errors.md](../jsx/errors.md#failed-sources)).
diff --git a/knowledge/reference/tools/fonts.md b/knowledge/reference/tools/fonts.md
index 8dc60dfd..42736ebe 100644
--- a/knowledge/reference/tools/fonts.md
+++ b/knowledge/reference/tools/fonts.md
@@ -1,6 +1,6 @@
# `dapi fonts`
-Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](./jsx/text.md).
+Lists local fonts available on this machine. macOS only. Does not require the app to be running. Font families listed here are valid `fontFamily` values on [`<text>`](../jsx/text.md).
## Options
diff --git a/knowledge/reference/tools/models.md b/knowledge/reference/tools/models.md
index f8ece42c..b7b93c8a 100644
--- a/knowledge/reference/tools/models.md
+++ b/knowledge/reference/tools/models.md
@@ -1,6 +1,6 @@
# `dapi models [type]`
-Lists the generation models available for a media type, including each model's capabilities. Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](./jsx/generate.md)).
+Lists the generation models available for a media type, including each model's capabilities. Use it to discover valid model ids and the per-model constraints (durations, aspect ratios, features) to set on an asset declaration (see [jsx/generate.md](../jsx/generate.md)).
There are no CLI commands that generate; asset generation is declared in the project module and produced on mount.
diff --git a/knowledge/reference/tools/voices.md b/knowledge/reference/tools/voices.md
index a49f6973..f6600c77 100644
--- a/knowledge/reference/tools/voices.md
+++ b/knowledge/reference/tools/voices.md
@@ -1,6 +1,6 @@
# `dapi voices`
-Lists the speech voices available for `generate.voice` declarations (see [jsx/generate.md](./jsx/generate.md)).
+Lists the speech voices available for `generate.voice` declarations (see [jsx/generate.md](../jsx/generate.md)).
## Input
diff --git a/knowledge/skills/editor.md b/knowledge/skills/editor.md
index a3210bc7..26154020 100644
--- a/knowledge/skills/editor.md
+++ b/knowledge/skills/editor.md
@@ -4,7 +4,7 @@ How to understand source material before editing it. Inspect only the modalities
- **Always probe first.** `dapi media probe <id|path>` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
- **Get the lay of the land.** Render a `dapi media waveform` (audio) and a `dapi media filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
-- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](references/examples/prompts/media-listen.md) for prompt patterns.
+- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.
- **Transcribe speech.** For speech, `dapi media transcribe` prints the full transcript with word-level start/end times directly — read any segment straight from it.
- **Sample the video against the audio.** Use `dapi media grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g. `-t '00:32' '00:45' ...`. When you need a visual pass without such cues, reach for `--auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.
@@ -25,7 +25,7 @@ How to understand source material before editing it. Inspect only the modalities
- Don't darken, blur, or cover the picture to make something on top of it legible
- Let visuals, sound, and voice carry context; let text punctuate rather than explain. Do not add copy, eyebrows, labels, underlines, or brand color highlights unless the brief or explicit video guidance calls for them; examples alone are not instructions.
- Choose easing from the intended weight, energy, and continuity of the action.
-- When the brief, project, or user specifies branding, follow it. Only when none is specified, fall back to the [Diffusion Studio brand](references/brand/README.md) — its design, voice, video, and library references, and the components and compositions bundled with them.
+- When the brief, project, or user specifies branding, follow it. Only when none is specified, fall back to the [Diffusion Studio brand](../brand/README.md) — its design, voice, video, and library references, and the components and compositions bundled with them.
# Verification
@@ -47,7 +47,7 @@ How to confirm a change actually produced what you intended. A clean save does n
- Hoist the properties that define the composition's look — title copy, font family and size, accent colors, key padding — into top-level consts annotated with `@inspect`, so they become live controls in the app's inspector.
- For anything 3D, use Three.js drawn into a `<surface>` tag.
- For motion graphics, overlays and UI-heavy graphics, the `<html>` tag driven by a paused [anime.js](https://animejs.com) timeline
-- Before animating anything, read the [easings reference](references/easings.md) and choose easings deliberately — default or linear easing is what makes motion read as a slideshow.
+- Before animating anything, read the [easings reference](../guides/motion/easings.md) and choose easings deliberately — default or linear easing is what makes motion read as a slideshow.
- Add auto captions last, after everything else is assembled, so they transcribe the finished audio at its final placement.
- Open the application in the background (`dapi open -b`) for tasks that don't require an editing UI.
- Only render (export) the result when prompted.
@@ -55,11 +55,13 @@ How to confirm a change actually produced what you intended. A clean save does n
# Docs
-Every project carries its own authoring reference, written by the app for the installed version, and its `AGENTS.md` points at it. Read it there and trust it over memory; it is app-owned, so never edit it.
+The authoring reference is served by the app for the installed version: read it there and trust it over memory.
-- [Installation guide, read when dapi is unavailable](references/installation.md)
-- [Easings: which cubic-bezier to use and when](references/easings.md)
-- [Diffusion Studio brand — the fallback when no other branding is specified](references/brand/README.md)
+- [JSX reference — elements, timing, paints, generation, captions](../reference/jsx/README.md)
+- [Tool reference — every tool, its arguments and its output](../reference/tools/README.md)
+- [Examples — complete compositions, basics through shaders](../examples/README.md)
+- [Easings: which cubic-bezier to use and when](../guides/motion/easings.md)
+- [Diffusion Studio brand — the fallback when no other branding is specified](../brand/README.md)
# Examples
@@ -67,9 +69,9 @@ Read worked example(s) that match your context.
## Video editing
-- [Long-form talking head](references/examples/video-editing/talking-head.md)
-- [Podcast clipping](references/examples/video-editing/podcast-clip.md)
+- [Long-form talking head](../guides/walkthroughs/talking-head.md)
+- [Podcast clipping](../guides/walkthroughs/podcast-clip.md)
## Prompts
-- [Writing prompts for `dapi media listen`](references/examples/prompts/media-listen.md)
+- [Writing prompts for `dapi media listen`](../guides/prompts/media-listen.md)
diff --git a/knowledge/skills/watch.md b/knowledge/skills/watch.md
index 178f9a32..caeee52a 100644
--- a/knowledge/skills/watch.md
+++ b/knowledge/skills/watch.md
@@ -4,7 +4,7 @@ How to understand source material. Inspect only the modalities the question turn
- **Always probe first.** `dapi media probe <id|path>` reports the container and its tracks, telling you up front whether the file has a video track, an audio track, or both. Everything after branches on that.
- **Get the lay of the land.** Render a `dapi media waveform` (audio) and a `dapi media filmstrip` (video) for a fast, cheap overview of where the loud and quiet stretches fall, and where the visual scene changes are. A filmstrip shows coarse structure and scene state, not crop, framing, readability, or an exact cut frame.
-- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](references/media-listen.md) for prompt patterns.
+- **Listen to the audio.** Run `dapi media listen` with a prompt tailored to the context (what you actually need to know), and explicitly ask the model to include timestamps in its answer. See [media-listen.md](../guides/prompts/media-listen.md) for prompt patterns.
- **Transcribe speech.** For speech, `dapi media transcribe` prints the full transcript with word-level start/end times directly — read any segment straight from it.
- **Sample the video against the audio.** Use `dapi media grab` to pull frames. When the audio has already pointed you at specific moments, feed those timestamps straight in from the transcript or listen output, e.g. `-t '00:32' '00:45' ...`. When you need a visual pass without such cues, reach for `--auto`: it scans the footage and keeps only the frames where the picture settles into a new visual state, dropping near-duplicates.
diff --git a/package.json b/package.json
index 59bfec16..695bd2f6 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"release": "node scripts/release.mjs",
"postinstall": "patch-package",
"lint": "npm run lint --workspaces --if-present",
- "check": "npm run check --workspaces --if-present && tsc -p examples --noEmit"
+ "check": "npm run check --workspaces --if-present"
},
"devDependencies": {
"patch-package": "^8.0.1"