@agent-native/core 0.122.3 → 0.123.0

package/docs/content/template-slides-agent.mdx

@@ -0,0 +1,102 @@
+---
+title: "Slides: Talking to the Agent & Creative Context"
+description: "What the agent sees in Slides, useful prompts by task, how it reuses existing brand assets before generating something new, and adding a custom widget."
+---
+
+# Talking to the Agent & Creative Context
+
+Slides' agent creates, edits, imports, exports, and styles decks through the same actions the UI uses, so anything you can click, you can also ask for. This page covers what it sees automatically, prompts organized by task, and how it decides whether to reuse existing work before generating something new — useful whether you're a day-to-day user or building on top of Slides.
+
+## How the agent sees your screen
+
+The agent always knows which deck is open, which slide you're on, and the full list of slides in that deck — you don't have to say "slide 4," it already knows what's there. When you're mid-edit in the visual editor, it also sees your active selection: the specific element you clicked, the tool you're using, and computed style details, so "make this bigger" acts on the thing you actually selected rather than guessing.
+
+The chat lives in the sidebar for quick back-and-forth; Slides also has a full-page Agent view for longer sessions with more room to work.
+
+### Selection-aware edits
+
+Select text (or an element) on a slide and hit `Cmd+I` to focus the agent on exactly what you highlighted. "Make this punchier" or "translate just this" then operates on your selection only, not the whole slide.
+
+## Useful prompts by task
+
+**Generate**
+
+- "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
+- "Summarize this PDF as a 6-slide deck." (attach the PDF)
+- "Turn this Google Doc into a deck."
+
+**Edit and restyle**
+
+- "Add a pricing slide after slide 3."
+- "Make the title on this slide bigger and change the accent color to green."
+- "Replace the word 'customers' with 'members' everywhere in this deck."
+
+**Images and logos**
+
+- "Generate a hero image for the current slide — dark, minimal, cinematic."
+- "Find the logo for stripe.com and add it to slide 2."
+- "Make that image darker, more navy."
+
+**Import and export**
+
+- "Import this PPTX and turn each slide into an editable slide here."
+- "Export this deck as PowerPoint."
+- "Get this ready to open in Google Slides."
+
+## The Creative Context reuse ladder
+
+Before generating something new, the agent works down a fixed list — it stops at the first option that genuinely fits, rather than jumping straight to generating from scratch:
+
+<Diagram id="doc-block-slides6" title="The reuse ladder" summary="The agent stops at the first rung that fits instead of defaulting to net-new generation.">
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-box">1. Reuse an approved slide or asset unchanged</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box">2. Compose a couple of approved pieces together</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box">
+    3. Duplicate and lightly adapt a real approved example
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box">
+    4. Generate new content grounded in a few specific references
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-box">
+    5. Generate net-new — only when nothing relevant exists yet
+  </div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+```
+
+</Diagram>
+
+In practice: ask for a "metrics slide" and the agent looks for one it's already used successfully before drafting a new layout. If you turn this off for a deck ("ignore the library for this version"), the agent won't quietly turn it back on later — you have to opt back in.
+
+## Submitting a deck to the shared Library
+
+Once a deck is in good shape, submit its current version to the shared Creative Context Library from the deck's Context tab so other decks — and other apps — can reuse its slides later. Each submission freezes one exact version; further edits to your working deck don't retroactively change what other decks already reused.
+
+## When the agent needs the real Google Drive API
+
+The built-in import and export actions cover Google Docs and Slides' common cases. For an unusual Google Drive request — an exact file metadata field, an export format the canned actions don't expose, or scanning a large number of files at once — the agent can call the real Google Drive API directly using your connected Google Docs account, and stage large results instead of pasting them into the conversation. See the [Developer Guide](/docs/template-slides-developers) for the action names behind this.
+
+## Extensions: adding a custom widget to Slides
+
+Slides supports the same sandboxed extension widgets as other Agent-Native apps — small mini-apps with access to your deck data and actions. Install or build one from **Settings → Extensions**; see the [extensions](/docs/extensions) docs for how to write one.
+
+## What's next
+
+- [**Design Systems & Media**](/docs/template-slides-design-and-media) — what the reuse ladder draws on
+- [**Generating & Editing Decks**](/docs/template-slides-editing) — the editor itself
+- [**Developer Guide**](/docs/template-slides-developers) — every action referenced above
+- [**Slides overview**](/docs/template-slides) — back to the app summary

package/docs/content/template-slides-design-and-media.mdx

@@ -0,0 +1,94 @@
+---
+title: "Slides: Design Systems & Media"
+description: "Save a reusable design system for your brand, index an existing Figma file or codebase with Builder, generate or find images and logos, and move decks in and out of other formats."
+---
+
+# Design Systems & Media
+
+This page covers keeping decks on-brand and adding visuals in [Slides](/docs/template-slides): saving a reusable design system, building one from assets you already have, generating or finding images, and moving decks in and out of other formats.
+
+## Saved design systems
+
+A design system is a reusable bundle of brand identity: primary/accent/background colors, heading and body fonts, spacing, logos, reference images for image generation, and free-form custom instructions ("always lowercase the section labels," "never use stock photography"). Save one and every new deck can use it instead of generic defaults; mark one as your default so new decks pick it up automatically.
+
+Once a design system is linked to a deck, the **Tweaks** panel gives you quick live overrides — an accent color swatch, title casing, background warmth — without editing the saved system directly. A change you keep persists back to the design system.
+
+## Building a design system from what you already have
+
+<Diagram id="doc-block-slides4" title="From brand source to applied design system" summary="Figma files, a connected codebase, or a design.md go through Builder's indexing instead of a one-shot local token guess, so the docs and token values stay grounded in the real source.">
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">Figma file (.fig)</div>
+    <div class="diagram-node">Connected code / GitHub repo</div>
+    <div class="diagram-node">design.md</div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Builder Design System Intelligence</span
+    ><small class="diagram-muted">indexes tokens, components, docs</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">
+    Design system<br /><small class="diagram-muted">linked to your decks</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">Applied on generation</div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+Bring a raw Figma file, point at a connected codebase or GitHub repo, or write a `design.md` describing your brand, and Slides sends it to Builder's Design System Intelligence — Builder is the source of truth for the resulting docs, extracted tokens, and usage guidance, not a one-time local guess. You can still describe a brand in plain language (company name, notes, a website URL) for a lighter-weight system the agent drafts directly, but a Figma file, a codebase, or a `design.md` always goes through the Builder-indexed path so the result reflects your real components and docs rather than an approximation.
+
+## Generating and finding images
+
+Ask the agent for an image and it generates a few variations styled to match your design system's reference images, shows them to you in chat, and drops the one you pick into the slide. Follow-up requests ("make it darker," "try a different angle") refine the same image without starting over.
+
+<Callout id="doc-block-slides5" tone="info">
+
+Image generation runs in the background. The agent generates a few candidates and comes back with the results a little later — it isn't instant, and a first reply of "generating a few options" is expected, not a stall.
+
+</Callout>
+
+For company logos, ask "find the logo for stripe.com" — Slides resolves the domain to a canonical logo. For anything else, a general image search works the same way a Google Images search would.
+
+## Moving decks in and out of other formats
+
+| Direction | Formats                      | What happens                                                                                                                                       |
+| --------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Import    | PPTX, DOCX, PDF, Google Docs | Converted into editable slides — a PDF or DOCX becomes one slide per page or section, a PPTX keeps its original slide breakdown and speaker notes. |
+| Export    | PPTX                         | Native, editable text, shapes, and images — not a flattened image of each slide.                                                                   |
+| Export    | Google Slides                | Slides generates the same PPTX and hands you a ready import link, since Google Slides has no direct "open this URL" import.                        |
+| Export    | Standalone HTML              | A single self-contained file with built-in keyboard navigation you can host or email anywhere — no app required to view it.                        |
+
+Bringing in a GitHub repo, a codebase, or a website URL is a different feature from importing a deck's content: those three feed the design-system indexing above, not slide-by-slide content import.
+
+## What's next
+
+- [**Generating & Editing Decks**](/docs/template-slides-editing) — the editor, presenting, and sharing
+- [**Talking to the Agent & Creative Context**](/docs/template-slides-agent) — how the agent reuses existing assets before generating new ones
+- [**Developer Guide**](/docs/template-slides-developers) — the design-system, image, and import/export action reference
+- [**Assets**](/docs/template-assets) — where image generation and brand libraries can live across apps
+- [**Slides overview**](/docs/template-slides) — back to the app summary

package/docs/content/template-slides-developers.mdx

@@ -0,0 +1,488 @@
+---
+title: "Slides: Developer Guide"
+description: "The Slides data model, persistence model, full action inventory, routes, and where to make common changes when forking or extending the template."
+---
+
+# Developer Guide
+
+This page is for anyone forking the Slides template or extending it: the SQL data model, how concurrent writers are kept safe, every agent-callable action, the route map, and where to make common changes.
+
+## Quick start
+
+```bash
+npx @agent-native/core@latest create my-slides --standalone --template slides
+```
+
+See [Getting started](/docs/getting-started) for the rest of the setup (`cd`, `pnpm install`, `pnpm dev`) and the framework fundamentals.
+
+## Persistence model
+
+Each deck is one JSON blob in `decks.data`. Every write goes through a server-side read-modify-write action that holds a per-deck lock, so concurrent writers — a human and the agent, or two humans — touching different slides of the same deck never overwrite each other's work.
+
+- **Agent actions** (`add-slide`, `update-slide`) use their own dedicated, granular actions and share that same lock.
+- **The browser editor** enqueues granular ops — `patch-slide`, `delete-slide`, `reorder-slides`, `add-slide`, `patch-deck-fields` — through `patch-deck` instead of a full-deck PUT.
+
+<Callout id="doc-block-slides10" tone="warning">
+
+If you're extending the editor's save path, enqueue a new op through `patch-deck`. Do not add a new full-deck PUT — that would reintroduce the last-write-wins race the lock exists to prevent.
+
+</Callout>
+
+## Data model
+
+All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
+
+<DataModel
+  id="doc-block-slides7"
+  title="Slides data model"
+  summary={
+    "A deck owns its slides as JSON in decks.data; comments, versions, shares, and design systems hang off it."
+  }
+  entities={[
+    {
+      id: "decks",
+      name: "decks",
+      note: "Slides live as JSON in data; carries ownableColumns",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+          note: "e.g. deck-1712345-abc",
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "JSON: { title, slides: [{ id, content, layout }] }",
+        },
+        {
+          name: "design_system_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "created_at",
+          type: "text",
+        },
+        {
+          name: "updated_at",
+          type: "text",
+        },
+      ],
+    },
+    {
+      id: "slide_comments",
+      name: "slide_comments",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "deck_id",
+          type: "text",
+          fk: "decks.id",
+        },
+        {
+          name: "slide_id",
+          type: "text",
+          note: "Slide the comment lives on",
+        },
+        {
+          name: "thread_id",
+          type: "text",
+          note: "Threading",
+        },
+        {
+          name: "parent_id",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "content",
+          type: "text",
+        },
+        {
+          name: "quoted_text",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "author_email",
+          type: "text",
+        },
+        {
+          name: "author_name",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "resolved",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "deck_versions",
+      name: "deck_versions",
+      note: "Point-in-time snapshots for restore",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "deck_id",
+          type: "text",
+          fk: "decks.id",
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "Full deck JSON",
+        },
+        {
+          name: "change_label",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "design_systems",
+      name: "design_systems",
+      note: "Reusable brand tokens; ownableColumns",
+      fields: [
+        {
+          name: "id",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "description",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "data",
+          type: "text",
+          note: "colors / typography / spacing",
+        },
+        {
+          name: "assets",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "custom_instructions",
+          type: "text",
+        },
+        {
+          name: "is_default",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "deck_share_links",
+      name: "deck_share_links",
+      note: "Persisted public share-link snapshots",
+      fields: [
+        {
+          name: "token",
+          type: "text",
+          pk: true,
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "slides",
+          type: "text",
+          note: "JSON slides snapshot",
+        },
+        {
+          name: "aspect_ratio",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "created_at",
+          type: "text",
+        },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "decks",
+      to: "slide_comments",
+      kind: "1-n",
+      label: "comments",
+    },
+    {
+      from: "decks",
+      to: "deck_versions",
+      kind: "1-n",
+      label: "snapshots",
+    },
+    {
+      from: "design_systems",
+      to: "decks",
+      kind: "1-n",
+      label: "applied to",
+    },
+  ]}
+/>
+
+Framework shares tables (`deck_shares`, `design_system_shares`) map principals — users or orgs — to viewer / editor / admin roles per resource, and are created via the shared `createSharesTable` helper rather than hand-written.
+
+#### Slide structure
+
+Each slide inside `decks.data` is:
+
+```json
+{
+  "id": "slide-1",
+  "layout": "title",
+  "content": "<div class=\"fmd-slide\" style=\"...\">...</div>"
+}
+```
+
+`content` is raw HTML — the renderer provides the fixed aspect ratio and background, and the HTML provides everything inside. Rich embedding is supported too: hand-drawn diagrams and live-rendered charts can live inside a slide alongside plain HTML.
+
+## Action inventory
+
+### Deck lifecycle
+
+- `create-deck` — new deck, optionally pre-populated with slides, or an atomic bulk replace of an existing deck's slides
+- `get-deck` — full deck JSON, or a compact slide-summary view
+- `list-decks` — every deck the caller can see, with light/compact/full-slide projections for cheap polling
+- `duplicate-deck` — copy a deck with fresh slide ids
+- `update-deck-aspect-ratio` — 16:9, 1:1, 9:16, or 4:5
+
+`add-deck`, `save-deck`, and `delete-deck` back the browser editor's optimistic-create, undo/redo, and delete flows — the agent uses `create-deck`, `add-slide`/`update-slide`/`patch-deck`, and the framework's own sharing actions instead.
+
+### Slide edits
+
+- `add-slide` — append (or insert at a position) one slide; how the agent builds a deck slide by slide
+- `update-slide` — surgical find/replace or full-content slide edit
+- `patch-deck` — the granular op queue the browser editor uses instead of a full-deck PUT
+
+### History
+
+- `list-deck-versions`, `get-deck-version`, `restore-deck-version` — every write snapshots first, so any point in time can be listed and restored
+
+### Comments
+
+- `list-slide-comments`, `add-slide-comment`, `update-slide-comment`, `delete-slide-comment`
+
+### Import
+
+- `import-pptx`, `import-docx`, `import-google-doc` — dedicated single-format importers
+- `import-file` — one entry point for PPTX, DOCX, or PDF, or a Figma `.fig` file (which routes into Builder design-system indexing instead of a slide import)
+- `extract-pdf` — CLI-only raw text dump of a PDF, mostly for local debugging
+
+### Export
+
+- `export-pptx` — native, editable PowerPoint
+- `export-google-slides` — generates the same PPTX plus a ready Google Slides import link
+- `export-html` — a standalone, self-contained HTML file with built-in keyboard navigation
+
+### Images
+
+- `generate-image` — agent-facing, deck-aware, and delegates to the Images app over A2A for brand-grounded generation when it's configured
+- `edit-image`, `check-image-gen`, `image-gen-status`, `search-images`, `search-logos`
+
+### Design systems
+
+- `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `set-default-design-system`, `apply-design-system` (link one to a deck)
+- `analyze-brand-assets`, `import-document`, `import-from-url` — gather raw brand signals (website CSS/fonts, uploaded document metadata) for a **local**, agent-drafted design system
+- `index-design-system-with-builder`, `import-design-project` — the Builder-indexed path for Figma files, connected code/GitHub repos, and `design.md`; `import-design-project` forks from an existing design system rather than a raw source
+
+### Creative Context
+
+- `clone-context-slide` — insert one pinned Library slide into a deck unchanged, without regenerating its HTML/CSS
+- `clone-creative-context-deck` — recreate one exact governed deck version
+- Retrieval and Library submission (search, fetching a context item, managing Library membership) are shared framework actions the agent calls the same way in every app that supports Creative Context — see the `creative-context` skill for the retrieval procedure and reuse ladder.
+
+### Escalation and staged data
+
+- `provider-api-catalog`, `provider-api-docs`, `provider-api-request` — raw Google Drive API access when a canned import/export action is too narrow; Slides resolves auth from the user's connected Google Docs account
+- `list-staged-datasets`, `query-staged-dataset`, `delete-staged-dataset` — aggregate a large staged provider result without re-fetching it
+
+### Navigation and context
+
+- `view-screen` — what the user is currently looking at: open deck, current slide, and any active visual selection
+- `navigate` — move the UI to a deck, slide, or view
+
+## Routes reference
+
+| Route                  | Renders                                                                 |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `/`                    | Deck list                                                               |
+| `/deck/:id`            | The editor                                                              |
+| `/deck/:id/present`    | Full-screen presentation                                                |
+| `/p/:id`               | Public/agent-readable live deck preview — distinct from `/share/:token` |
+| `/share/:token`        | Public read-only snapshot, frozen at share time                         |
+| `/slide`               | Single-slide embed used for chat previews                               |
+| `/design-systems`      | Manage saved design systems                                             |
+| `/agent`               | Full-page Agent tab                                                     |
+| `/extensions`, `/team` | Redirect into the relevant `/settings` tab                              |
+
+## Customizing it
+
+The Slides template is fully forkable. Key places to look when extending it:
+
+#### Actions — `templates/slides/actions/`
+
+Every agent-callable operation lives here as a TypeScript file, mounted automatically at `POST /_agent-native/actions/:name` and callable from the CLI as `pnpm action <name>`. Add a new file here to give the agent a new capability.
+
+<AnnotatedCode
+  id="doc-block-slides9"
+  title="Anatomy of a slide edit action"
+  filename="actions/update-slide.ts (simplified)"
+  language="ts"
+  code={
+    'import { defineAction } from "@agent-native/core";\nimport { assertAccess } from "@agent-native/core/sharing";\nimport { eq } from "drizzle-orm";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\nimport { notifyClients } from "../server/handlers/decks.js";\nimport { withDeckLock } from "./patch-deck.js";\n\nexport default defineAction({\n  description:\n    "Surgically edit a slide\'s content using search-replace or full replacement. " +\n    "Syncs live to open editors. Prefer this over full deck rewrites.",\n  schema: z.object({\n    deckId: z.string(),\n    slideId: z.string(),\n    find: z.string().optional(),\n    replace: z.string().optional(),\n    fullContent: z.string().optional(),\n  }),\n  run: async ({ deckId, slideId, find, replace, fullContent }) => {\n    await assertAccess("deck", deckId, "editor");\n    return withDeckLock(deckId, async () => {\n      const db = getDb();\n      const [row] = await db\n        .select()\n        .from(schema.decks)\n        .where(eq(schema.decks.id, deckId));\n      if (!row) throw new Error(`Deck ${deckId} not found`);\n\n      const deck = JSON.parse(row.data);\n      const slide = deck.slides.find((s: { id: string }) => s.id === slideId);\n      if (!slide) throw new Error(`Slide ${slideId} not found`);\n\n      if (fullContent) {\n        slide.content = fullContent;\n      } else if (find) {\n        const idx = slide.content.indexOf(find);\n        if (idx === -1) return { ok: false, message: "Text not found" };\n        slide.content =\n          slide.content.slice(0, idx) +\n          (replace ?? "") +\n          slide.content.slice(idx + find.length);\n      }\n\n      deck.updatedAt = new Date().toISOString();\n      await db\n        .update(schema.decks)\n        .set({ data: JSON.stringify(deck), updatedAt: deck.updatedAt })\n        .where(eq(schema.decks.id, deckId));\n\n      notifyClients(deckId, { slideId, actor: "agent" });\n      return { ok: true, deckId, slideId };\n    });\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "22",
+      label: "Access check",
+      note: "`assertAccess` throws before anything else runs if the caller isn't at least an editor on this deck.",
+    },
+    {
+      lines: "23-29",
+      label: "Per-deck lock",
+      note: "`withDeckLock` serializes this against every other write to the same deck — `add-slide` and the browser's `patch-deck` share the same lock, so two writers touching different slides never clobber each other.",
+    },
+    {
+      lines: "35-44",
+      label: "Surgical edit",
+      note: "A `find`/`replace` pair changes only the matched text; `fullContent` swaps the whole slide. Prefer the narrower form for real edits.",
+    },
+    {
+      lines: "47-50",
+      label: "SQL is the source of truth",
+      note: "The whole deck is one JSON blob in `decks.data` — there's no separate `slides` table, so every write reads, edits, and rewrites that one column.",
+    },
+    {
+      lines: "52",
+      label: "Live sync",
+      note: "`notifyClients` pushes the change to any open editor immediately; polling is the fallback path. See [Real-Time Collaboration](/docs/real-time-collaboration).",
+    },
+  ]}
+/>
+
+The real action also records Creative Context reuse provenance and waits briefly for the editor to report a layout-overflow measurement — trimmed here to the core read-modify-write shape.
+
+#### Layout
+
+<FileTree
+  id="doc-block-slides8"
+  title="templates/slides/ shape"
+  entries={[
+    {
+      path: "actions/create-deck.ts",
+      note: "New deck, optionally pre-populated with slides, or an atomic bulk replace",
+    },
+    {
+      path: "actions/add-slide.ts",
+      note: "Append one slide; used for streaming generation",
+    },
+    {
+      path: "actions/update-slide.ts",
+      note: "Find/replace or full-content slide edit",
+    },
+    {
+      path: "actions/patch-deck.ts",
+      note: "Granular ops the browser editor uses instead of a full-deck PUT",
+    },
+    {
+      path: "actions/generate-image.ts",
+      note: "Agent-facing image generation, deck-aware, optional A2A delegation to Images",
+    },
+    {
+      path: "actions/index-design-system-with-builder.ts",
+      note: "Starts Builder design-system indexing from Figma, GitHub, or code",
+    },
+    {
+      path: "app/routes/deck.$id.tsx",
+      note: "The deck editor",
+    },
+    {
+      path: "app/routes/deck.$id_.present.tsx",
+      note: "Full-screen presentation mode",
+    },
+    {
+      path: "app/routes/agent.tsx",
+      note: "Full-page Agent tab",
+    },
+    {
+      path: "app/routes/p.$id.tsx",
+      note: "Public/agent-readable single-deck preview",
+    },
+    {
+      path: "app/routes/share.$token.tsx",
+      note: "Public read-only snapshot page",
+    },
+    {
+      path: "app/components/editor/",
+      note: "Slide canvas, toolbar, sidebar, and panels",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "decks, slide_comments, deck_versions, design_systems, deck_share_links",
+    },
+    {
+      path: ".agents/skills/create-deck/SKILL.md",
+      note: "Exact slide HTML templates for every layout",
+    },
+    {
+      path: ".agents/skills/creative-context/SKILL.md",
+      note: "The reuse ladder and retrieval procedure",
+    },
+  ]}
+/>
+
+Most editor UI customization happens under `app/components/editor/`: the slide canvas, toolbar, sidebar, bubble menu, slash menu, and the panels for image generation, search, and history.
+
+#### Skills — `templates/slides/.agents/skills/`
+
+Agent skills that explain patterns when the agent needs to modify code:
+
+- `create-deck` — how to create a new deck, with exact slide HTML templates for every layout
+- `slide-editing` — how to edit individual slides
+- `deck-management` — how decks are stored and accessed
+- `slide-images`, `image-generation-via-a2a` — image generation and search
+- `design-systems` — design-system data shape and how tokens apply to generated slides
+- `creative-context` — the reuse ladder, retrieval procedure, and Library submission
+
+#### AGENTS.md
+
+`templates/slides/AGENTS.md` is the short router the agent reads on every conversation. It points at the skills under `.agents/skills/` and lays out the core rules, persistence model, and application-state contract. Update the relevant skill whenever you add or change a slide layout, image path, or design-system source.
+
+## What's next
+
+- [**Generating & Editing Decks**](/docs/template-slides-editing) — the user-facing editing, presenting, and sharing flow
+- [**Design Systems & Media**](/docs/template-slides-design-and-media) — the design-system and import/export flow this data model backs
+- [**Talking to the Agent & Creative Context**](/docs/template-slides-agent) — the reuse ladder these actions implement
+- [**Sharing**](/docs/sharing) — the share-grant model `deck_shares` and `design_system_shares` build on
+- [**Real-Time Collaboration**](/docs/real-time-collaboration) — the Yjs pipeline decks share with other collaborative surfaces
+- [**Slides overview**](/docs/template-slides) — back to the app summary