@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/slides-2/.agents/skills/slide-editing/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: slide-editing
+description: >-
+  Edit individual slides, including content formatting, HTML styling, and
+  bounded source and visual-fidelity checks. Use when changing an existing
+  slide rather than creating a new deck.
+---
+
+# Slide Editing
+
+## Source-backed slides
+
+Generated Slides 2 slides store canonical React in `sourceTsx`; `content` is a
+derived script-free preview. Read `get-slide-source` before a source edit and
+save with `update-slide-source`, passing the returned `revision` and
+`sourceHash`. Use its source-located `edits` for targeted changes or a complete
+`sourceTsx` replacement for a broad rewrite. A stale revision/hash is a
+conflict: re-read and reapply the edit. Never write generated source slides
+through `update-slide` or `patch-deck` HTML fields, because that would leave the
+preview and source inconsistent.
+
+After a successful save, call `get-slide-source` and confirm its source,
+revision, and hash match the update result before claiming the edit persisted.
+An update receipt with `changed: false` means the requested source and derived
+preview already matched, so no revision was created. If a save returns a
+conflict or its response is lost, read the current source before retrying. If
+the intended source is already present, treat the write as recovered; otherwise
+reapply the edit to the latest source with its current revision and hash. Never
+replay stale arguments blindly.
+
+The editor's in-session Undo/Redo and saved deck history are separate. Source
+updates snapshot the deck before writing, subject to the history's coalescing
+cadence. Use `restore-deck-version` to restore a saved deck version; that action
+also snapshots the current deck first so the restore is reversible.
+
+The source renderer bundles bounded React source into a Worker and renders it
+inside the opaque-origin sandbox. Keep source within the `create-deck` skill's
+import, CSS, and asset limits. `Steps`/`Step`, `MorphElement`,
+`useSlidePageNumber()`, `useIsActivePage()`, `cssVarsToString`, and static
+`design`, `meta`, and transition exports are supported; effects and event
+handlers do not provide client-side behavior. `cssVarsToString` returns bounded
+text and does not enable runtime CSS injection. The `create-deck` skill
+documents the exact source contract and static Page[]/notes/transition mapping.
+
+The Slides 2 editor PDF and editable PPTX exports can render the Worker
+artifact in the sandbox. The PPTX menu first calls the `export-pptx` action;
+when a source-only slide returns `source_runtime_export_required`, it renders
+the slides with `get-slide-render` and uses the browser DOM-to-PPTX builder.
+HTML and Google Slides exports still require a static HTML preview and return
+`source_runtime_export_required` when a source slide has none. The public
+shared viewer shows an explicit capability state for source-only slides; it
+does not have viewer authorization to request the Worker artifact by share
+token.
+
+## Source-backed object transforms
+
+Use `transform-slide-objects` for source-backed object insertion, duplication,
+deletion, and canvas arrangement. Call `view-screen` first; for duplicate or
+delete, map the one current selected object's `sourceLine` and `sourceColumn` to
+`target: { line, column }` only when `sourceSelectionStatus` and
+`sourceTargetStatus` report `current`. Then call `get-slide-source` for that
+deck and slide and pass its `revision` and `sourceHash` as `expectedRevision`
+and `expectedSourceHash`. `insert` supports text, rectangle, ellipse, and line
+objects, with optional 1920x1080 canvas bounds; it returns the created object ID
+and source locator. `duplicate` returns the cloned source locator and remaps a
+static ID when the object was inserted by the editor. Duplicate and delete
+require one exact current source locator for a root element or direct JSX child.
+Duplicate rejects custom or dynamic IDs, spread attributes, grouped objects,
+and other uncertain subtrees. Delete removes the selected child, or replaces
+the selected root with a blank canvas. Insertion uses the default slide canvas
+layer.
+
+The geometry operations are move, resize, rotate, align, distribute, group,
+ungroup, and z-order. Selected geometry targets must share a JSX parent.
+Geometry operations require static inline styles with absolute positioning and
+numeric pixel bounds; grouping and z-order also require adjacent objects with
+stable `data-slide-object-id` values. On a stale selection or source conflict,
+refresh `view-screen` and `get-slide-source`, rebuild the operation from current
+locators, and retry; do not replay stale coordinates or revision tokens. Read
+the source back after a successful operation.
+
+## Slides 2 visual controls
+
+For source-backed visual edits, use `view-screen` to confirm the active slide and
+selection, then read with `get-slide-source` and save through
+`update-slide-source` using its returned revision and source hash. Keep React
+source out of the legacy HTML fields on `update-slide` and `patch-deck`.
+When `view-screen` reports a current `selectedTextRange`, pass its source
+line/column, UTF-16 start/end offsets, and `expectedText` as `prevText` to
+`update-slide-source` with a `set-text-range-style` edit. If the range is absent
+or stale, reselect the text or reread the current source before editing.
+
+For Undo, Redo, or Save in the visual editor, use the current
+`view-screen` `Visual editor draft` identity with `control-slide-editor`, then
+call `view-screen` again to confirm the one-shot command result. The editor
+checks the active tab, editor session, history version, and saved source
+revision/hash before applying it. Tab-scoped editor state is a command target,
+not deck authorization; the action separately checks editor access.
+
+For Undo or Redo in the regular DeckEditor, use the `DeckEditor history`
+identity from the latest `view-screen` result with `control-deck-history`.
+Reuse the same command ID to read a queued command's result, and refresh
+`view-screen` before starting another command. The bridge checks deck editor
+access, active tab navigation, editor session, history version, and whether
+the requested direction is available before using the same local operation
+stack as the UI; it confirms the deck save has drained before reporting the
+command as applied.
+
+| Control | Behavior |
+| --- | --- |
+| Preview / Edit | Preview hides the slide rail and editing overlays, closes the inspector, and restarts the active source slide at its first build step. Click, Space, Right/Down, or PageDown advances builds before moving to the next slide; click, Left/Up, or PageUp moves backward through builds before moving to the previous slide. Escape returns to Edit. Edit restores the inspector state from before Preview unless the inspector was toggled with `i` while previewing. |
+| `i` | Show or hide the inspector. It is ignored while typing, composing, or focused on an editor control. The shortcut also works in Preview. |
+| Canvas selection | Click an object to select it; Shift-click toggles its membership. Drag empty canvas to replace the selection with intersecting objects, or click empty canvas to clear it. |
+| Cmd/Ctrl+A | Select all objects on the active slide. It is ignored while commenting, typing, or composing; while overview, command menu, asset browser, or image crop is open; and when focus is on editor controls, menus, or dialogs. |
+| Cmd/Ctrl+S | Save pending source edits. Shift or Alt disables this shortcut. |
+| Arrow-key editing and navigation | With the canvas focused, arrows nudge selected editable objects by 1 px, or 10 px with Shift. Otherwise, Left/Up moves to the previous slide and Right/Down to the next; PageUp/PageDown move previous/next, Space moves next, and Home/End jump to the first/last slide. |
+| Shift and Alt while dragging | Shift constrains a move to its dominant axis, preserves the aspect ratio while resizing, and snaps rotation to 15-degree increments. Alt temporarily bypasses Smart Guides during a move. |
+| Align and Smart Guides | For multiple objects, align to either the selection bounds or slide; one object aligns to the slide. Smart Guides starts on and snaps object edges and centerlines to other objects and the slide within a scale-adjusted 6 CSS px threshold. Toggle it in Arrange; Alt bypasses it for one move. |
+
+The remaining HTML instructions in this skill apply to legacy or imported
+content-backed slides. Their canvas follows the saved aspect ratio: 16:9 is
+960x540, 1:1 is 1080x1080, 9:16 is 540x960, and 4:5 is 864x1080.
+
+## Read before
+
+Read a reference with `docs-search --slug "skill-slide-editing--references-<file>"`,
+for example `skill-slide-editing--references-animations`.
+
+| Situation | Read |
+| --- | --- |
+| Changing only colors, borders, shadows, or backgrounds, or matching every slide to one slide's look | `references/restyling.md` |
+| Adding, changing, or removing click-to-reveal animations | `references/animations.md` |
+| Adding, moving, duplicating, or restyling hand-placed text boxes and other freeform objects | `references/freeform-objects.md` |
+| Adding or editing a video | `references/video.md` |
+
+## Legacy HTML wrapper and styling
+
+These wrapper instructions apply to imported and legacy content-backed slides.
+Their outer `.fmd-slide` div carries the semantic `--deck-*` contract; source-
+backed React pages render through the Worker and do not use that HTML wrapper.
+With a design system linked, map `--deck-*` to `--ds-*`. Without one, write
+literal values: the legacy renderer publishes only `--ds-bg` for unlinked decks,
+so any other `var(--ds-*, ...)` resolves to its fallback.
+
+Keep one deck-level contract: the same canvas, type pairing, palette, and
+accent on every slide, varying composition rather than theme. Never alternate
+light and dark slides or add a one-off font or palette unless asked. For polish
+or "make it beautiful", read `slide-design`; a linked system's tokens still win.
+
+## Updating legacy or imported HTML slides
+
+Use this procedure only for content-backed HTML slides; follow the source-backed workflow above for `sourceTsx`.
+
+1. Call `view-screen` for the active deck, slide ID, HTML, and any
+   `slides-selection` target. The user navigates and reselects between turns:
+   on any turn that says this, here, that slide, or the selected one, call
+   `view-screen` again and never reuse a previous turn's slide ID or
+   selection. If nothing is selected or the target is unclear, ask which slide.
+2. When the edit changes facts, brand language, or layout, follow
+   `creative-context` first. If retrieval yields a new context pack, keep its
+   `contextPackId` with the deck provenance; existing HTML is not proof of
+   which source version shaped it. Keep an approved native template or
+   component when it fits; generate new structure only when the corpus is
+   empty.
+3. Write with `update-slide`: `deckId`, `slideId`, and ordered `edits` (exact
+   replace, insert before/after, replace between markers, regex). Edits apply
+   atomically under the deck lock, so one failed edit writes nothing.
+   - **Selected text:** if `view-screen` returns an exact `selectedText` range,
+     send one literal replace with the selected text as `find` and
+     `expectedMatches: 1`. Use `selectionSlideId` and
+     `selectionSlideContentHash` when present (the selection can be on another
+     slide); otherwise `currentSlideId` and `currentSlideContentHash`. Never
+     pair a `selectionSlideId` with the current slide's hash. Skip `get-deck`, `fullContent`, and layout-fit waits.
+   - **Slides you wrote this run:** you already hold their HTML, so send
+     `edits` directly (one `patch-deck` with `patch-slide` edits for several
+     slides) without re-reading. Read with `get-deck` only if an edit fails to
+     match or the write is rejected as stale; someone may have edited it since.
+   - **Otherwise** (truncated, ambiguous, split by markup, or structural): call
+     `get-deck` with that `slideId` (`compact=false` for full HTML, plus
+     `format=true` for code-style work) and use its `contentHash` as
+     `baseContentHash`.
+   - Use `fullContent` only for an intentional full rewrite, never to make a
+     small change. `format=true` persists readable line breaks.
+4. Read back with `get-deck` (or a thumbnail's `.slide-content`
+   `textContent`), never `document.body.innerText`: thumbnails use
+   `content-visibility: auto`, so their text is empty in a hidden tab, and the
+   canvas shows only the selected slide.
+5. For factual edits, check changed text against the source: quote, speaker,
+   date, metric, and uncertainty status. Visual similarity is not source
+   fidelity.
+
+Never write deck rows directly or add raw full-deck writes. Browser/editor code enqueues granular
+operations through `patch-deck` / `DeckContext.tsx` instead of replacing the
+whole deck JSON.
+
+Report only what writes returned. `patch-deck` lists changed slides in
+`updatedSlideIds` and byte-identical ones in `unchangedSlideIds`; an unchanged
+slide was not restyled. `update-slide` fails with `slide_edit_noop`, and both
+reject a batch where nothing changed, so re-read and send different content
+instead of describing changes that did not land.
+
+## Fit and layout checks
+
+The `create-deck` Fit budget applies: on 16:9 with `64px 80px` padding the
+content area is 800x412px, so use at most two title lines, three short bullets
+or cards, and two or three items per column. When an edit adds or lengthens
+text, redo the height arithmetic and split the slide instead of shrinking.
+Body text stays at least 16px. Never hide overflow with zoom,
+`transform: scale()`, clipping, or scroll; reducing explicit padding is allowed.
+
+After all edits, call `get-layout-overflows` once, and once more only after
+repairing a measured overflow. It reads the open editor's latest measurements
+and cannot trigger new ones, so repeating it this turn changes nothing. If
+status is unknown, name the unmeasured slide numbers and IDs and never claim
+the deck fits.
+
+## Contrast
+
+Run `audit-contrast` as the last step of any turn that created or changed
+slides (after layout repairs, right before the final response) and whenever
+readability or accessibility comes up. If the deck is not open in the editor,
+say contrast was not checked.
+
+Fix failures in one pass by adjusting the role (`--deck-muted`, `--deck-ink`, a
+surface), not one element's hex. Replacement colors must fit the theme:
+
+- Design system linked: pick a passing color from its palette
+  (`get-design-system`). If none passes, keep the token and report it.
+- No design system: reuse a deck color, or shift the failing color's lightness
+  while keeping its hue.
+
+Never add an unrelated hue to pass. Audit once more, then report what remains;
+re-audit once if slides come back skipped as `stale-render`. Skipped slides and
+unverified text (over images, gradients, or effects) were not checked: name
+them, and do not call the deck accessible or those slides fine.
+
+## Flow layout and the editor
+
+Keep generated flex and grid content in normal flow; create a deliberate
+freeform object instead of absolute-positioning a layout child to make it
+draggable. The editor presents flow content as flat objects the way Google
+Slides does, so write markup that maps cleanly:
+
+- A card is one painted box (background, border, or shadow on a single element)
+  that owns its text. Never stack separately positioned text over a card
+  background.
+- Text containers, including `.fmd-text-box`, have no fixed `height`
+  (`min-height` only for a deliberate minimum), so text grows instead of
+  overflowing.
+- Never write `contain` or `contain-intrinsic-size`; they break the editor's
+  measuring and the PPTX export.
+- No inline `<svg>`; the sanitizer removes it. Use styled divs or an `<img>`.
+- Keep nesting shallow. Unpainted wrappers with no direct text (grid rows,
+  columns) are fine; the pointer skips them.
+- Ids belong to freeform objects only. Never stamp `data-slide-object-id` on a
+  flow region: any id marks an object freeform and `export-pptx` rejects it.
+  Preserve existing ids when rewriting a slide, and never save runtime
+  `data-builder-id` values.
+- An empty hidden `.fmd-layout-spacer[data-slide-layout-spacer-for="ID"]`
+  reserves the flow slot of a hand-moved object. Keep it while its owner
+  exists and delete both together.
+- Keep the empty `<span data-slide-number></span>` and
+  `<span data-slide-total></span>` tokens when restyling or rewriting a footer.
+  They are empty in the saved HTML on purpose; never type digits over them.
+- Use `fmd-img-placeholder` divs whose text names the content to show (see
+  `create-deck` `references/slide-templates.md`) for diagrams, charts, and
+  photos, then generate real images; never rebuild complex visuals in HTML/CSS.
+
+Slide writes can return `hygieneWarnings` (inline svg and other markup the
+sanitizer strips, typed page numbers, fixed px heights on text, `contain`,
+stacked absolute text, deep nesting, tiny text). Fix them with `update-slide`
+before finishing; a missing field means the lint found nothing.
+
+## Skipping slides
+
+A `patch-deck` `patch-slide` with `skipped: true` hides a slide from
+Present/Presenter without deleting it; `skipped: false` restores it. The rail's
+right-click Skip slide does the same.
+
+## Transitions
+
+Slide transitions (type and speed, Google Slides catalog) are set with the
+`patch-slide` op of `patch-deck`, or with its `add-slide` op on creation. Read
+`references/transitions.md` before changing them.

package/corpus/templates/slides-2/.agents/skills/slide-editing/references/animations.md

@@ -0,0 +1,33 @@
+# Click-to-reveal animations
+
+Animations are metadata over the final slide HTML, not alternate slide markup.
+Reveal only where the order of ideas carries the argument (a list whose payoff
+is the last item, a build to a conclusion, before/after); a title, single
+quote, or diagram the audience should take in at a glance is stronger shown
+whole. Do not add reveals by default.
+Read the full target slide, keep its existing visual structure, and patch the
+complete ordered `animations` list with `elementPath` values from that exact
+HTML. Elements omitted from the list remain visible immediately, so labels and
+headings need no duplicate markup. Do not add hidden duplicates, layout
+spacers, absolute-positioned copies, transforms, or placeholder content to
+simulate reveals. When content and reveals change together, send both fields in
+one `patch-deck` operation. To remove reveals, send `animations: []` with the
+existing content and verify the persisted slide afterward.
+
+By default each entry waits for its own click. Set `trigger: "with-previous"`
+on an entry to play it in the same click as the entry before it, so the objects
+appear together; the first entry always waits for a click. On a `byParagraph`
+entry the trigger applies to its first paragraph only.
+
+Array order is reveal order, and each entry needs a non-empty `id`, a 0-based
+`elementIndex`, and a `type` of `appear`, `fade`, `slide-up`, or `zoom`; the
+schema rejects the operation otherwise. Nothing checks that ids are unique, but
+the editor keys its reveal list by id, so a duplicate makes "remove" and
+"change type" hit every entry sharing it.
+
+`elementPath` has to come from the exact final HTML because it is positional:
+every segment is a child index, so inserting or removing a sibling anywhere
+along the path retargets it. The runtime resolves the path first and falls back
+to `elementIndex` only when it fails to resolve, which is why a stale path
+silently reveals the wrong element instead of erroring. `get-deck` with
+`compact=true` reports each step's order, id, target, and type for verification.

package/corpus/templates/slides-2/.agents/skills/slide-editing/references/freeform-objects.md

@@ -0,0 +1,22 @@
+# Freeform Canvas Objects
+
+Manual text boxes and other freeform canvas objects are absolutely positioned
+children of `.fmd-slide`. Give each one a stable `data-slide-object-id`:
+
+```html
+<div
+  class="fmd-text-box"
+  data-slide-object-id="slide-object-unique-id"
+  style="position: absolute; left: 160px; top: 120px; width: 420px;"
+>
+  Editable text
+</div>
+```
+
+- Preserve `data-slide-object-id` and the `left`/`top`/`width` of hand-placed
+  objects when updating, moving, resizing, or styling them.
+- Mint a new unique object ID when duplicating an object.
+- Do not use runtime-only `data-builder-id` values in saved slide HTML.
+- A text box (`.fmd-text-box`) with no inline `height` auto-grows with its text
+  from the top edge.
+- Build editable shapes with styled HTML elements such as `div`.

package/corpus/templates/slides-2/.agents/skills/slide-editing/references/restyling.md

@@ -0,0 +1,69 @@
+# Restyling slides and copying a look across the deck
+
+## Style edits
+
+For a request that changes appearance and nothing else — colors, borders,
+shadows, background — send `edits` that change only the requested CSS
+declarations, and leave text, element order, and layout properties (padding,
+margin, gap, font-size, line-height, dimensions, positioning) as they are:
+
+```jsonc
+{
+  "deckId": "...",
+  "slideId": "...",
+  "edits": [
+    {
+      "find": "background:#111111",
+      "replace": "background:#f4f0e8",
+      "occurrence": 1,
+    },
+  ],
+}
+```
+
+Deck palettes usually live in `--deck-*` variables on the `.fmd-slide`
+wrapper; change the variable (`--deck-muted: #647968`) rather than every
+element that uses it.
+
+Use `occurrence: 1` rather than `expectedMatches: 1` when a declaration may
+appear more than once on the slide: the `edits` path refuses an ambiguous
+literal outright, so `expectedMatches` turns a repeated declaration into a
+rejection instead of an edit. Reach for `all: true` when every occurrence on
+that slide really should change.
+
+`objectId` is not a style-edit target. It replaces an element's inner content
+and leaves the element's own `style` attribute untouched, so it cannot move the
+declaration you are usually after.
+
+### Copying one slide's look onto the rest of the deck
+
+"Make every slide match slide 1" is a deck-wide restyle, so it goes through
+**one `patch-deck` call** with a `patch-slide` operation per slide. Do not fan
+out one `update-slide` per slide: that is the batching the agent instructions
+rule out, and because the calls issue in parallel, a mistake in the first one
+repeats across all of them before any rejection comes back.
+
+1. Read the reference and targets together: use one `get-deck` call with
+   `slideIds` and `compact=false` when their IDs are known, or one full-deck
+   `compact=false` read when they are not. Take the reference background from
+   its `.fmd-slide` wrapper — not a child. `deckStyle` summarizes the whole
+   deck, including interior gradients, so it is not a substitute for the
+   wrapper's own value.
+2. Send one `patch-deck` call carrying every affected slide, each as a
+   `patch-slide` with `edits: [{"find":"...","replace":"...","occurrence":1}]`
+   for the declarations that change, then verify once with `get-deck` using the
+   same `slideIds` and `compact=false`. Edits apply to the current HTML and need
+   no `baseContentHash`; regenerating full `fields.content` for a color swap
+   costs tens of seconds per slide.
+
+Use `update-slide` for a focused single-slide edit or when a person is actively
+editing and the smaller scoped mutation matters.
+
+Either way, change only the `.fmd-slide` wrapper's background. Interior card
+fills, image backgrounds, and gradients are separate visual elements; leave them
+alone unless the user asked for those too. A slide whose wrapper carries no
+background declaration needs one added to the wrapper's `style`, not a
+find/replace against a declaration that is not there.
+
+After restyling, check text contrast and fit once with `audit-contrast` and
+`get-layout-overflows` together.

package/corpus/templates/slides-2/.agents/skills/slide-editing/references/transitions.md

@@ -0,0 +1,26 @@
+# Slide transitions
+
+A slide's transition belongs to the boundary before it. It plays across that
+boundary in Present and Presenter view, in either direction, and the later slide
+of the pair supplies the type and speed. Going backward plays it reversed, so the
+slide you leave supplies the transition, not the slide you land on.
+
+Set it with `patch-deck` `patch-slide`, or on creation with a `patch-deck`
+`add-slide` op. `update-slide` does not take transition fields.
+
+- `transition`: one of `none`, `dissolve`, `fade`, `slide-from-right`,
+  `slide-from-left`, `flip`, `cube`, `gallery`. These match the Google Slides
+  Transitions panel. Legacy `instant`, `slide` and `zoom` are accepted and stored
+  as `none`, `slide-from-right` and `dissolve`. `null` resets it to `none`. On
+  `patch-slide`, omitting it keeps the current type; on `add-slide`, omitting it
+  means `none`.
+- `transitionSpeed`: integer 0..49, default 45. Duration is `(5.0 - 0.1 * v)`
+  seconds, so 45 is 0.5 s, 0 is 5.0 s and 49 is 0.1 s. `null` resets it to the
+  default. On `patch-slide`, omitting it keeps the current speed; on `add-slide`,
+  omitting it means 45.
+
+To set a transition on every slide, patch each slide. The editor's Transition
+popover also has Apply to all slides, which writes one batch.
+
+PDF export keeps the transition metadata. PPTX and HTML export do not carry
+transitions.

package/corpus/templates/slides-2/.agents/skills/slide-editing/references/video.md

@@ -0,0 +1,45 @@
+# Video
+
+Slides 2 videos use uploaded MP4 or WebM assets. In the visual editor, upload a
+video from the asset browser, then insert it or replace the selected video.
+Uploads are limited to 50 MB. For agent-authored source, call `list-assets`
+with `media: "video"` (or `media: "all"`) and use the returned `assetId` as an
+`asset://` handle. When selecting media for an existing deck, include its
+`deckId` with global scope so results are limited to assets the deck can use.
+`list-assets` defaults to images. A video poster must also use an uploaded image
+asset handle.
+
+Generated slides store canonical React in `sourceTsx`; do not add HTTPS media
+URLs or edit generated slides through legacy HTML fields. Read the source with
+`get-slide-source`, then save with `update-slide-source` using its current
+`revision` and `sourceHash`. Preserve an existing `data-slide-object-id` when
+replacing a video, then read the source again to verify the save.
+
+```tsx
+export default function Slide() {
+  return (
+    <div style={{ position: "relative", width: "1280px", height: "720px" }}>
+      <video
+        src={"asset://uploaded-video-id"}
+        poster={"asset://uploaded-image-id"}
+        controls
+        playsInline
+        preload="metadata"
+        data-slide-object-id="video-1"
+        style={{
+          position: "absolute",
+          left: "320px",
+          top: "180px",
+          width: "320px",
+          height: "180px",
+          objectFit: "contain",
+        }}
+      />
+    </div>
+  );
+}
+```
+
+`autoPlay`, `muted`, and `loop` are supported static video attributes. Use
+`muted` and `playsInline` with `autoPlay` to meet common browser playback
+policies. Verify the target export before claiming it preserves playable video.

package/corpus/templates/slides-2/.agents/skills/slide-images/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: slide-images
+description: >-
+  Source and generate images for slides with Assets-owned style grounding and
+  provenance. Use when a slide needs a new still image, logo, or approved
+  image asset.
+---
+
+# Slide Images
+
+Images for slides are generated or sourced through the Slides actions and the
+Assets app. The runtime agent must use the Assets-grounded path described below;
+the local CLI is only a developer entry point.
+
+This skill covers still images, not video generation. For video, upload MP4 or
+WebM through the visual editor's asset browser, then use `list-assets` with
+`media: "video"` or `media: "all"` to find the uploaded `assetId` (`list-assets`
+defaults to images). Use that ID in an uploaded `asset://` handle in the
+source-backed React `<video>` element. Read `slide-editing/references/video.md`
+for insertion, poster, and revision-checked source-update guidance. Do not
+invent remote video URLs or pass video through image-generation actions.
+
+When a chat attachment has an HTTPS image URL, import and insert it through
+`generate-image-api` with `generatedImageUrl`, `insertIntoSlide: true`, the
+target `deckId` and `slideId`, and a short descriptive prompt. The action
+registers the image and uses revision-checked source edits for source-backed
+slides; never write a remote image URL directly into slide source or derived
+HTML.
+
+## Scripts
+
+| Script | Purpose | Example |
+|--------|---------|---------|
+| `generate-image` | Local helper for the Assets-grounded generation action | `pnpm action generate-image --prompt "hero image" --count 3` |
+| `search-images` | Search Google Images via the configured provider | `pnpm action search-images --q "Acme logo transparent" --count 5` |
+| `search-logos` | Resolve company domains and canonical logo URLs | `pnpm action search-logos --q "Acme"` |
+| `image-gen-status` | Check configured image providers | `pnpm action image-gen-status` |
+
+## Image Generation Flow
+
+For agent or editor generation, call `generate-image-api`, not a provider or
+legacy image action directly:
+
+1. Resolve the deck's active design system, its `imageStyle`, the current slide
+   role, and any approved Creative Context references.
+2. Call `generate-image-api` with the prompt plus bounded deck and slide
+   context. Assets chooses the library, preset, style anchors, model, and
+   fallback behavior while preserving provenance.
+3. Show each returned variation as an inline rendered preview using markdown
+   image syntax (`![Variation 1](url)`), not a plain link (`[Variation 1](url)`)
+   — the chat renders `![]()` as an actual image but `[]()` as a bare link.
+4. Preserve the returned `assetId`, `runId`, `previewUrl`, and `downloadUrl`.
+5. For direct insertion, call `generate-image-api` with `insertIntoSlide: true`,
+   `deckId`, and `slideId`. The action registers the image in the deck asset
+   collection, then uses `update-slide-source` with its revision and hash for
+   source-backed slides. Only say the image was added when it returns
+   `inserted: true`; a preview URL is not proof of a slide write.
+6. For preview-only variations, after the user chooses one call
+   `generate-image-api` with `generatedImageUrl` set to that preview URL,
+   `insertIntoSlide: true`, the target `deckId` and `slideId`, and the original
+   prompt. This registers the chosen image and follows the same source-safe
+   insertion path; do not put a remote preview URL into slide source or derived
+   HTML directly.
+7. For feedback, refine the same asset rather than starting an unrelated run.
+
+### Context to pass
+
+The image brief should include the visual role, subject, composition/crop,
+format, must-preserve content, and exclusions. Pass `deckId`, `slideId`, and
+`slideContent` so Assets can ground the result in the actual slide. Do not use
+generic style references to override a linked design system or preset.
+
+`search-images` and `search-logos` remain bounded lookup tools for finding
+existing media. They are not a substitute for the active design system or a
+style-generation brief.
+
+Treat both searches as optional enrichment. If a provider is unconfigured or
+unavailable, a search has no matches, or an action returns an error, continue
+the deck with a useful image-free slide using native typography, diagrams, or
+rules. Keep the action error visible; do not retry the lookup in a loop or stop
+deck generation because search failed.
+
+## Logo Lookup
+
+Search the public SVGL catalog with `search-svgl-logos`. Choose the light or
+dark route when a result provides variants, then call `import-svgl-logo` with
+that returned route and title. Pass `deckId` to save it to a deck; omit it for
+the global asset collection. Import validates the download and stores it through
+the existing SVG sanitizer. It returns an `assetId` but does not place the logo
+on a slide. Import requires configured upload storage; if it returns
+`image_upload_storage_unavailable`, use the storage setup flow instead of
+retrying the import. For agent edits, read the target with `get-slide-source`,
+insert the uploaded `asset://` handle through `update-slide-source` using its
+revision and source hash, then read the source back. Never put the remote SVGL
+URL directly in slide source.
+
+Other company-logo searches use the following options:
+
+**Option 1: canonical logo search** (uses Logo.dev search when configured and a bounded domain fallback otherwise):
+```bash
+pnpm action search-logos --q "Acme"
+```
+
+For insertion, pass a returned `logoUrl` to `generate-image-api` as
+`generatedImageUrl` with the target slide IDs and `insertIntoSlide: true`; do not
+write the remote URL directly into slide source or derived HTML. Do not call a
+second logo-provider action for each result.
+
+**Option 2: Google Image Search** (fallback):
+```bash
+pnpm action search-images --q "Acme logo transparent" --count 5
+```
+
+## Asset Library
+
+Use `list-assets` to find an image by its `assetId`. When selecting media for an
+existing deck, include its `deckId` with global scope so results are limited to
+assets the deck can use. Call `update-asset` with `filename` to rename it, or
+with `replacementId` to replace its stored image while preserving the original
+ID and slide references. The replacement must be another uploaded image from
+the same user's global collection. Do not delete the original before the
+replacement action succeeds.
+
+## Important Rules
+
+- Use the active design system, library, preset, and approved style anchors for
+  visual consistency; do not invent a second style language in the prompt
+- Use `<ImagePlaceholder label="..." />` in generated `sourceTsx` slides and
+  `.fmd-img-placeholder` divs only in legacy HTML slides
+- Use one canonical provider action per conceptual search; do not loop legacy
+  provider scripts or manually guess provider URLs. Import selected remote
+  images through `generate-image-api`, or SVGL logos through `import-svgl-logo`,
+  before inserting them.
+- Never claim image insertion from a generation response alone; require the
+  verified `inserted: true` response. Source-backed slides must use registered
+  `asset://` handles and revision-checked `update-slide-source` writes.