@agent-native/core-corpus 0.213.1 → 0.216.0

package/corpus/templates/slides-2/.agents/skills/context-awareness/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: context-awareness
+description: >-
+  How the agent knows what the user is looking at. Use when exposing UI state to
+  the agent, implementing view-screen or navigate actions, wiring navigation
+  state, or debugging agent context issues.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Context Awareness
+
+## Rule
+
+Apps can sync semantic navigation state when the route changes by using the
+shared route-state hook. When screen context is available, Core includes a
+`<current-screen>` snapshot in each agent turn, so the agent can get basic
+route context without first calling another tool. Apps can add concise
+visible-record details to that snapshot and expose selection in tab-scoped
+state.
+
+## Why
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.
+
+## The Core Patterns
+
+### 1. Navigation State (`navigation` key)
+
+Use the shared route-state hook to write a tab-scoped `navigation` key as the
+route changes. Include semantic screen state such as the view, open IDs, active
+tab, and focused object.
+
+**UI side** — use `useAgentRouteState` in the app's route-state hook. The app
+can wrap it in an app-owned `useNavigationState` hook to map route paths to
+semantic views and consume the agent's `navigate` command.
+
+```tsx
+// app/hooks/use-navigation-state.ts
+import { useAgentRouteState } from "@agent-native/core/client/navigation";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view:
+        pathname === "/"
+          ? "home"
+          : pathname === "/sign-in"
+            ? "sign-in"
+            : pathname.replace(/^\/+/, ""),
+      // Optional semantic alias. Raw query params are already exposed in
+      // <current-url> and controllable with set-search-params.
+      label: searchParams.get("label"),
+    }),
+    getCommandPath: (command: any) =>
+      command.path ?? `/${command.view === "home" ? "home" : command.view}`,
+  });
+}
+```
+
+The default scaffold uses `/home` for home and `/sign-in` for authentication;
+`/` redirects according to the configured home route. Map navigation to the
+app's actual routes and pass an explicit `path` for destinations that do not
+follow the `/<view>` convention.
+
+`TAB_ID` comes from the framework's `getBrowserTabId()` (see the scaffolded `app/lib/tab-id.ts`; never redefine it). The server resolves tab-scoped `application_state` writes and page-local WebMCP calls (`X-Agent-Native-Browser-Tab`) against this same id, so a hand-rolled random id silently breaks selection sync for hidden and background tabs.
+
+**Agent side** — read before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// e.g. { view: "thread", threadId: "abc123", subject: "Re: Q3 Planning" }
+```
+
+**What to include in navigation state:**
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`, `issueKey`)
+- Semantic aliases — label names, active tabs, focused row, or stable filter names the agent should reason about
+- Focused object IDs and active tabs that are not already represented by URL state
+
+Keep text-selection ranges and excerpts in the tab-scoped `selection` key, not
+in `navigation`.
+
+Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
+
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
+### Selection state
+
+For app-owned per-tab selection, suffix the key with `TAB_ID`; `requestSource`
+labels the write origin but does not scope the key. Keep the value to stable ids
+and a short label or excerpt, never the full document:
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+import { TAB_ID } from "@/lib/tab-id";
+
+await writeClientAppState(
+  `selection:${TAB_ID}`,
+  { kind: "text", id: "artifact-123", text: "short excerpt" },
+  { requestSource: TAB_ID },
+);
+```
+
+A server action can read that tab's value with
+`readAppStateForCurrentTab("selection")`. A `view-screen` result may include the
+selection and a specific next action when that helps the agent target an edit.
+
+### 2. Current URL (`__url__` key)
+
+`AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.
+
+Use this for URL-reachable filters and search state. The agent can update it with the built-in `set-search-params` and `set-url-path` tools; do not duplicate the whole query string into `navigation`.
+
+### Settings page (`settings-view` key)
+
+The redesigned Settings shell writes tab-scoped `settings-view` = `{ page, sub, label }` (for example `{ page: "integrations", sub: "builder", label: "Connections › Integrations › Builder.io" }`) and deletes it when Settings closes. `<current-url>` shows it as a `settingsPage:` line, because a legacy or mounted pathname doesn't name the page the shell resolved. To send the user to a page, call the built-in `open-settings-page` tool with a page id (plus `sub` or `anchor`); it resolves old tab and section ids through the same redirect table as links. A template's own `navigate` action only needs a Settings branch for its app areas (`/settings/app/<area>`), built with `buildSettingsRoute`.
+
+### 3. The `view-screen` Action
+
+Use a `view-screen` action for a concise snapshot of visible record data the
+agent needs in addition to basic navigation. Read navigation and selection
+state, then query the relevant summaries through existing data helpers or
+Drizzle. Do not add REST wrappers just so `view-screen` can read app data.
+
+```ts
+// actions/view-screen.ts
+import { defineAction } from "@agent-native/core/action";
+import {
+  readAppState,
+  readAppStateForCurrentTab,
+} from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return a concise snapshot of the current screen.",
+  schema: z.object({}),
+  http: false,
+  readOnly: true,
+  run: async () => {
+    const navigation = await readAppState("navigation");
+    const screen: Record<string, unknown> = {};
+    if (navigation) screen.navigation = navigation;
+
+    const selection = await readAppStateForCurrentTab("selection");
+    if (selection) screen.selection = selection;
+
+    // Add concise visible-record summaries using the app's existing data helpers.
+    return screen;
+  },
+});
+```
+
+Core builds the `<current-screen>` block for each agent turn by running the
+surfaced `view-screen` action. If no such action is available, it falls back to
+the current tab's `navigation` state. The scaffold action returns navigation;
+extend it with concise, relevant visible-record details when the app has them.
+The agent can use the injected snapshot directly and call `view-screen` again
+when it needs a fresh read after context has changed.
+
+### 4. The `navigate` Action
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+**Agent side:**
+
+```ts
+import { writeAppStateForCurrentTab } from "@agent-native/core/application-state";
+
+// Navigate the user to a specific thread
+await writeAppStateForCurrentTab("navigate", {
+  view: "inbox",
+  path: "/inbox/abc123",
+  threadId: "abc123",
+});
+```
+
+**UI side** — use `useAgentRouteState`, shown above. It polls command keys,
+dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
+
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
+Keep `path` router-local. A segment matching the app mount prefix remains part
+of the local route unless a matching `view` route or explicit `publicPath`
+identifies the mounted URL. Carry the mounted form separately in `publicPath`;
+never infer that `path` is mounted from its prefix alone.
+
+## Jitter Prevention
+
+Agent-side application-state writes are tagged with
+`requestSource: "agent"`. The UI uses `useDbSync({ ignoreSource: TAB_ID })` so
+it ignores its own writes while still picking up changes from agents, other
+tabs, and scripts.
+
+Import `useAgentRouteState` and `useSemanticNavigationState` from
+`@agent-native/core/client/navigation`. Import
+`setClientAppState`, `writeClientAppState`, `readClientAppState`, and
+`deleteClientAppState` from `@agent-native/core/client/hooks`; avoid the
+deprecated `@agent-native/core/client` barrel. Pass `{ requestSource: TAB_ID }`
+on UI writes when pairing with `useDbSync({ ignoreSource: TAB_ID })`; pass
+`{ keepalive: true }` for short-lived writes such as selection cleanup during
+unload.
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  ignoreSource: TAB_ID,  // ignore events from this tab's own writes
+});
+```
+
+The UI sends its browser tab ID in `X-Agent-Native-Browser-Tab`; when a write
+has a `requestSource`, the client sends it in `X-Request-Source` and the server
+records it as the event origin. `useDbSync` ignores events whose origin matches
+`ignoreSource`, preventing a tab from refetching after its own state writes.
+
+## Gold-Standard Example: Mail Template
+
+The mail template demonstrates these patterns working together:
+
+**Navigation state shape:**
+```json
+{ "view": "inbox", "threadId": "thread-123", "focusedEmailId": "msg-456", "label": "important" }
+```
+
+**view-screen output:**
+- Reads navigation state
+- Reads `__url__` if URL query filters matter
+- Fetches email list matching current view/filter state
+- Fetches thread messages if a thread is open
+- Returns everything as a single JSON snapshot
+
+**navigate command:**
+- `{ "view": "starred" }` — switch to starred view
+- `{ "view": "inbox", "threadId": "thread-123" }` — open a specific thread
+- For pure query-filter changes, use `set-search-params`
+
+## Do
+
+- Use the auto-injected `<current-screen>` block for basic context — call `view-screen` only when you need richer data
+- Include semantic route state in the `navigation` key (view, item IDs, active tab, focused row)
+- Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
+- Add concise visible-record details to `view-screen` for views where the agent needs them beyond the injected navigation context
+- Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
+- Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
+
+## Don't
+
+- Don't assume the user is on a specific page — use `<current-screen>` or read
+  navigation state when context is missing or stale
+- Don't hardcode navigation paths in scripts — read the current state and branch
+- Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
+- Don't ignore the `<current-screen>` block — it tells you where the user is
+- Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
+- Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.
+
+## Related Skills
+
+- **adding-a-feature** — Context awareness is area 4 of the four-area checklist
+- **real-time-sync** — How `useDbSync` delivers app-state changes to the UI
+- **actions** — How to create the `view-screen` and `navigate` actions
+- **storing-data** — Application-state is one of the core SQL stores

package/corpus/templates/slides-2/.agents/skills/create-deck/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: create-deck
+description: >-
+  Create source-backed slide decks from a prompt or reference. Use before
+  creating a deck, writing React slide pages, or continuing live generation.
+---
+
+# Creating a Deck
+
+All slide generation happens in agent chat. The agent authors React source and
+calls deterministic actions to validate and save it; the UI never calls an LLM.
+The Home prompt flow counts as started only after agent chat confirms delivery.
+If delivery fails or the handoff throws, return a setup failure and keep the
+prompt open instead of leaving an empty deck looking like a generated result.
+
+## Workflow
+
+1. Read `creative-context` and retrieve factual evidence separately from visual
+   structure. Respect `contextMode: "off"`. For a new deck, call
+   `list-slide-themes` once unless Home already supplied a selected design
+   system or a reference controls the style. If themes are available, offer
+   their names and short descriptions plus “none” with a topic-specific
+   recommendation; resolve a theme the prompt already names without asking
+   again. Read the selected guide with `get-slide-theme` before authoring.
+2. Unless Home already supplied a user-selected system or a reference controls
+   the visual style, call `get-workspace-defaults` once. A normal
+   `create-deck` call resolves and links its effective default. Home's
+   `promptDraft` is already persisted with only the user's explicit selection;
+   if its context asks for a usable workspace default, link that existing deck
+   with `patch-deck` and `patch-deck-fields` before adding slides. Do not create
+   a second deck. Call `get-design-system` once for the effective selection and
+   use its hydrated context.
+3. Plan the outline and theme contract: topic, audience, thesis, one message per
+   page, visual direction, approximate page count, text density, motion, and
+   known fit risks. If the prompt lacks its topic or audience, ask for those
+   essentials before drafting. Bundle any other missing high-impact choices,
+   including visual direction, page count, text density, motion, and a pending
+   theme choice, into one concise, topic-specific follow-up with a recommended
+   direction. Do not ask for details the user already supplied.
+4. When all pages can be authored before any deck exists, call `create-deck`
+   once with every ordered page so the deck is saved atomically. In the Home
+   prompt flow, an empty deck may already be persisted before the agent starts;
+   use its supplied deck ID and call `add-slide` sequentially, without creating
+   another deck. Before the first Home `add-slide`, call `get-deck` with
+   `{ id: deckId, compact: "true" }` and apply its `designSystem.agentContext`
+   and `deckStyle`; if the design system scope is `summary`, call
+   `get-design-system` once with its ID. For other genuinely live generation,
+   create the empty deck with `slides: []`, then add one `sourceTsx` component
+   per page. Do not issue
+   parallel writes to the same deck. Pass presenter notes through `notes`,
+   outside the component source. Before the first incremental write, assign
+   each planned page a distinct stable `slideId`. Reuse its ID and exact source
+   or content and notes
+   on retry. If `duplicate_slide_id` is returned, call `get-deck` with
+   `slideIds: [slideId]` and `compact: false`, then treat it as saved only when
+   the persisted source or content and notes match; otherwise stop and report
+   the conflict. Identical slide content can still represent separate pages,
+   so keep their IDs distinct. Omitting
+   `slideId` remains supported, but the action generates an ID that cannot be
+   reused safely after an unclear result.
+5. For source files using `export default [Cover, Body]` or a local const such
+   as `const pages: Page[] = [Cover, Body]; export default pages;`, `create-deck`
+   splits the local static components into separate ordered SQL slides
+   (maximum 40).
+   An optional static `export const notes = [...]` maps by page index; missing
+   entries remain empty. A static `Cover.transition = {...}` is preserved as
+   that page's transition override, with the module `transition` export as the
+   default. Module-level static exports such as `meta` remain in each split
+   page's source. For live `add-slide`, send one component per call; a named
+   default component may use `Slide.transition = {...}` for its static page
+   override, which takes precedence over the module `transition` export.
+6. Read the first new page with `get-slide-source` and inspect its derived
+   preview with `get-deck`. Reuse the visual contract on later pages. After all
+   writes, call `get-deck` once with `compact=true` and the created slide IDs to
+   confirm the persisted count and IDs. Then call `get-layout-overflows` and
+   `audit-contrast` once each; repeat only after a repair has produced a new
+   measurement.
+7. If `create-deck` returns `postProcessStatus: "failed"`, the deck write still
+   committed. Read the deck, then call `navigate` if the connected browser did
+   not move to it; do not repeat creation. Otherwise, if the browser does not
+   consume the navigation command, call `navigate` with the deck id.
+
+When continuing generation, call `get-deck` first and treat persisted
+`generationContext` as canonical. Continue the original outline instead of
+replacing it with a new topic inferred from the follow-up.
+
+## Built-in templates
+
+When the user wants to browse or choose a built-in starter, use
+`list-deck-templates` to find its exact ID. For an exact copy, call
+`create-deck-from-template`; it creates an independent SQL deck without AI,
+provider setup, or the workspace default design system. If the user wants new
+content in a starter's visual style, call `get-deck-template` to inspect its
+slides and notes, then author a new source-backed deck with `create-deck` or
+`add-slide`. Do not replace the starter or imply that copying it generated new
+content. Built-in starters are shared catalog entries, so no owner filter is
+needed when listing or reading them. The copy action checks the caller-scoped
+saved row before reporting success. Supply a stable `newId` when a retry may be
+needed; a matching retry returns the existing copy without overwriting edits,
+and a mismatched owner, organization, template version, or original title is a
+conflict. If readback fails, use the returned `deckId` to inspect the saved
+deck before starting another copy.
+
+Apply a selected bundled visual theme through the `design-systems` skill; it is
+distinct from a copyable deck template and a linked SQL design system. Include
+`export const meta = { theme: "<theme-id>" };`
+in every generated slide module so each saved slide retains the selected theme
+ID in its static metadata. A `create-deck` page array preserves that module
+export on every split page.
+
+## Source contract
+
+Each generated SQL slide stores one default-exported React page component in
+`sourceTsx`. The action validates it, saves the canonical source, and derives
+the `content` preview. React modules that need imports have an empty derived
+HTML preview; the editor and presenter render their Worker artifact inside an
+opaque-origin sandbox. Never write generated slides via `content`; that field
+is for imported or legacy HTML and the derived static preview only.
+
+The Slides 2 editor's browser PDF export calls `get-slide-render` and captures
+its Worker-rendered sandbox output. The editor's editable PPTX export first
+calls the `export-pptx` action, then uses the browser DOM-to-PPTX builder when
+that action returns `source_runtime_export_required` for a source slide that
+needs Worker rendering. The `export-pptx` action attempts bounded server-side
+static rendering for source-only slides first. `export-html` and
+`export-google-slides` require a saved static `content` preview, as do source
+slides the PPTX evaluator cannot render. The public shared viewer cannot call
+`get-slide-render` because it has only a share token, not deck viewer access.
+New share snapshots mark source-only slides and show a capability message
+instead of a blank slide; the shared PresentationView PDF path also rejects
+those slides. Recreate older share links created before this marker was added
+to identify source-only pages.
+
+The supported module uses one default component and may import React plus these
+eleven Worker-supported values from `@open-slide/core`: `CANVAS_WIDTH`,
+`CANVAS_HEIGHT`, `defaultDesign`, `designToCssVars`, `Step`, `Steps`,
+`useSlidePageNumber`, `useIsActivePage`, `ImagePlaceholder`, `MorphElement`, and
+`cssVarsToString`. `cssVarsToString` is a pure, bounded serializer for safe CSS
+custom-property maps; its output is text and does not enable runtime stylesheet
+injection. Use the `ImagePlaceholder` prop `hint` to name the real image the
+user needs, with optional pixel `width` and `height`. Each supplied dimension
+sets that CSS dimension directly; the Worker does not infer an aspect ratio,
+and it shows the size caption only when both dimensions are supplied. The
+Worker renders the static image-slot treatment; it does not load media into the
+placeholder. Put uploaded image `asset://` handles on `<img src>` and use the
+editor's image actions to replace a placeholder. For videos, use a static React
+`<video>` element with an uploaded asset handle; see
+`slide-editing/references/video.md` for the source and editing workflow. Use
+inline style objects or static CSS blocks to style the slide.
+`defaultDesign` is frozen in the Worker, and
+`designToCssVars(defaultDesign)` can be spread into an inline `style` object.
+The module may also export static `design`, `meta`, and `transition` objects.
+Do not add other modules, dynamic imports, browser APIs, top-level effects, or
+event handlers. The source is validated before it is bundled for a bounded
+Worker render; it is not evaluated by the server or same-origin app. A Worker
+timeout, size limit, and output sanitizer fail the render instead of
+substituting a blank success.
+
+Slide components render to static markup in a bounded Worker, so React effects
+do not run. For motion, use sanitized CSS `@keyframes` or the existing
+`<Steps>`/`<Step>` reveals. Step fades honor
+`prefers-reduced-motion: reduce` and become instant cuts automatically.
+
+The Worker supports `Steps`/`Step`, `useSlidePageNumber()`, and
+`useIsActivePage()`. These provide page context and reveal state in static
+markup. A render artifact carries validated module or page transition metadata
+for the presenter host. `MorphElement` adds the stable `data-slides2-morph` marker
+used by cross-page matching. With one native DOM child, it places the marker on
+that child and merges `className` and `style` without adding a wrapper; other
+child shapes use a wrapper.
+
+Use standard JSX and inline `style` objects. `className` works when paired with
+a static CSS string in a local `const` whose name includes `style`, `css`, or
+`keyframe`; that CSS is sanitized and scoped to the slide root before it is
+injected in the iframe. Tailwind utility classes have no stylesheet in the
+frame, so they render unstyled. Do not use CSS imports, `<style>` elements,
+`@import`, remote fonts, or CSS resource URLs. Images use uploaded `asset://`
+handles only. Videos use uploaded MP4 or WebM `asset://` handles only. Use the
+editor's asset browser to upload a video, then call `list-assets` with
+`media: "video"` or `media: "all"` to find registered uploads; the action
+defaults to images. When selecting media for an existing deck, include its
+`deckId` with global scope so results are limited to assets the deck can use.
+In new `sourceTsx`, use the returned `assetId` as the
+`<video>` `src` handle, and use an uploaded image handle for an optional
+`poster`. Do not invent or embed remote media URLs, or use image-generation
+actions for video. When changing an existing source-backed slide, read it with
+`get-slide-source`, save with `update-slide-source` using the returned
+`revision` and `sourceHash`, then read it back. Do not write source-backed
+slides through legacy `content` fields. Keep local style rules and markup
+self-contained; the action rejects arbitrary module imports, dynamic CSS
+access, and network-capable asset references.
+
+For a non-system typeface, search with `search-google-fonts`, then import the
+chosen family and variant with `import-google-font({ deckId, family, variant })`.
+The import validates and stores the font binary through configured file
+storage. Apply its returned `family` and `assetId` to `displayFont` or
+`bodyFont` through the visual editor or `update-deck-design-tokens`; the
+renderer loads only those registered handles. Source code still cannot declare
+`@font-face`, remote font URLs, CSS imports, or other network-capable CSS.
+
+For multi-page generation, `create-deck` accepts a static
+`export default [Cover, Body] satisfies Page[]` of local component functions
+and splits it into ordered SQL slides (up to 40 per module). This is a
+per-module fan-out bound; it is not a persisted deck or rendering limit. An
+optional static
+`export const notes = [...]` maps by page index; missing entries stay empty,
+and the array may be shorter than the page list. Each saved slide gets its own
+default component source, revision, hash, and derived preview; the original
+file module is not stored as a shared object. For live `add-slide`, send one
+default-exported component per call. Presenter notes may also be passed
+through the slide action's `notes` field.
+
+## Theme and composition
+
+Use the same canvas, typography pairing, palette, spacing scale, and accent on
+every page; vary composition, not the deck theme. With a linked design system,
+use the shared deck-token variables. Without one, choose subject-appropriate
+values once and repeat them across pages.
+
+```tsx
+export default function Cover() {
+  return (
+    <main
+      style={{
+        width: 1920,
+        height: 1080,
+        boxSizing: "border-box",
+        padding: "128px 160px",
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: "center",
+        gap: 32,
+        "--deck-bg": "#10261C",
+        "--deck-ink": "#F2EFE6",
+        "--deck-muted": "#A8B8AC",
+        "--deck-accent": "#7FB069",
+        "--deck-heading-font": "Georgia, serif",
+        "--deck-body-font": "Arial, sans-serif",
+        background: "var(--deck-bg)",
+        color: "var(--deck-ink)",
+        fontFamily: "var(--deck-body-font)",
+      }}
+    >
+      <h1 style={{ color: "var(--deck-accent)", fontSize: 88 }}>
+        A clear thesis
+      </h1>
+      <p style={{ fontSize: 36 }}>One message, composed for the room.</p>
+    </main>
+  );
+}
+```
+
+At the native 1920×1080 canvas, keep body text at least 32px and split dense
+material across more pages instead of shrinking it. Keep content in normal
+flex/grid flow, leave text containers free to grow, and do not hide overflow
+with transforms, clipping, or scrolling. Use images for complex visuals rather
+than approximating them with piles of CSS shapes.
+
+Read `design-systems` before theme work, `slide-design` for visual craft,
+`slide-editing` before editing an existing slide, and
+`references/reference-inputs.md` or `references/source-material.md` when their
+inputs apply. `references/slide-templates.md` contains legacy HTML examples;
+use them only when preserving or editing imported HTML slides.

package/corpus/templates/slides-2/.agents/skills/create-deck/references/reference-inputs.md

@@ -0,0 +1,72 @@
+# Reference decks, attached documents, and workspace defaults
+
+## Reference Decks
+
+The user can pick an existing deck as a style reference when starting a new one.
+When they do, a `## Reference Deck` block is already in your context holding one
+worked HTML example per layout.
+
+Treat it as a pattern library, not an outline. The most common failure here is
+walking the reference deck slide by slide and swapping in new copy, which
+produces a deck with the wrong shape for its own content. Instead:
+
+1. Plan the new deck from the user's request alone — story, slide count, order.
+2. For each slide you decided to write, pick the pattern that fits that content.
+3. Reuse a pattern as often as the content warrants, or never.
+4. When nothing fits, compose a new slide from the same type scale, spacing,
+   color, and markup conventions rather than bending content to a near-miss.
+
+The block deliberately omits the reference deck's slide sequence. Call
+`get-deck --id <reference deck id> --compact false` only if you need full slide
+HTML to see how that deck handled a case the patterns do not cover.
+
+A reference deck and a design system are independent: the design system wins on
+tokens (color, type, spacing, imagery, and slide defaults), the reference deck
+wins on slide-level composition and markup idiom. Apply both when both are
+present. Generic templates in this skill are fallback patterns only. Never let
+a reference screenshot or deck silently transfer its brand tokens.
+
+Decks the user has starred are their intended reference decks. `list-decks`
+reports `starred` so you can offer them when the user asks for something "like
+our usual deck".
+
+## Attached Reference Documents
+
+A PDF, PPTX, or DOCX attached to a new-deck prompt is read before your run
+starts. Its extracted content and, for a PDF, its measured visual language —
+page proportions, painted backgrounds, the ranked type scale with families,
+sizes, weights and colors, median text margins, paragraph alignment — arrive as
+an `## Attached Reference Documents` block.
+
+That block is the reference. Do not call `import-file` for a file listed there,
+and never generate as if the attachment were missing: if the file could not be
+read, the run would have been stopped before it reached you, so a file you can
+see in that block was read successfully.
+
+When the user attached the file as a visual or style reference, match the
+measured type scale, weights, colors, alignment, and margins. A deck generated
+from a style reference must not come out looking like one generated without it.
+Structure and wording still come from the user's request, not from the
+reference's own page order.
+
+The fallback visual language in this skill applies only when no reference
+document, reference deck, or design system is present.
+
+## Workspace Defaults
+
+A workspace admin can flag one deck and one design system as the workspace
+default. Use `get-workspace-defaults` once when needed to identify a workspace
+reference deck or design system; `create-deck` also applies the effective design
+system default when no override is passed.
+
+- `referenceDeck` — call `get-deck-reference-context --id <id>` and treat the
+  result exactly like a user-picked reference deck.
+- `designSystem` — pass its id as `designSystemId` to `create-deck`, unless the
+  caller already has a personal default, which `create-deck` applies on its own.
+- Either field can come back `{ unavailable: true }`. That means the default
+  exists but this user cannot open it, which is a misconfiguration, not an
+  absent default. Generate without it and tell the user their workspace default
+  is not shared with them, rather than silently producing an off-brand deck.
+
+An explicit request always wins over the workspace default. Do not re-apply a
+workspace default to an existing deck the user is editing.