@agent-native/core-corpus 0.213.1 → 0.216.0

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

@@ -0,0 +1,93 @@
+# Ready-to-Use Templates
+
+Copy and fill in the bracketed values. `[WRAPPER STYLE]` stands for the deck
+contract chosen in "Slide Wrapper" - the inherited `var(--ds-*)` form when a
+system is linked, the literal form when none is. It is identical on every
+slide. Inside the slide, read the contract directly (`var(--deck-accent)`), not
+through another layer of fallbacks; the wrapper has already defined every role.
+
+### Title Slide
+
+```html
+<div
+  class="fmd-slide"
+  style="[WRAPPER STYLE] justify-content: center; align-items: flex-start; gap: 18px;"
+>
+  <div
+    style="font-size: 14px; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase; color: var(--deck-accent);"
+  >
+    [LABEL OR DATE]
+  </div>
+  <h1
+    style="font-size: 56px; font-weight: 750; color: var(--deck-ink); font-family: var(--deck-heading-font); line-height: 1.05; letter-spacing: -0.04em; margin: 0; max-width: 760px;"
+  >
+    [TITLE]
+  </h1>
+  <p style="font-size: 20px; color: var(--deck-muted); margin: 4px 0 0;">
+    [SUBTITLE OR PRESENTER]
+  </p>
+</div>
+```
+
+### Content or Two-Column Slide
+
+```html
+<div
+  class="fmd-slide"
+  style="[WRAPPER STYLE] justify-content: flex-start; gap: 18px;"
+>
+  <div
+    style="font-size: 13px; font-weight: 700; letter-spacing: 0.1em; text-transform: uppercase; color: var(--deck-accent);"
+  >
+    [SECTION LABEL]
+  </div>
+  <h2
+    style="font-size: 34px; font-weight: 750; color: var(--deck-ink); font-family: var(--deck-heading-font); line-height: 1.12; letter-spacing: -0.03em; margin: 0 0 18px;"
+  >
+    [SLIDE HEADING]
+  </h2>
+  <div
+    style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px; align-items: start;"
+  >
+    <div style="display: flex; flex-direction: column; gap: 14px;">
+      <div
+        style="border-left: 3px solid var(--deck-accent); padding: 12px 16px; background: var(--deck-surface); border-radius: var(--deck-radius); font-size: 18px; line-height: 1.4;"
+      >
+        [KEY POINT]
+      </div>
+      <div
+        style="border-left: 3px solid var(--deck-accent); padding: 12px 16px; background: var(--deck-surface); border-radius: var(--deck-radius); font-size: 18px; line-height: 1.4;"
+      >
+        [KEY POINT]
+      </div>
+    </div>
+    <div
+      class="fmd-img-placeholder"
+      style="min-height: 220px; border-radius: var(--deck-radius);"
+    >
+      [VISUAL OR IMAGE DESCRIPTION]
+    </div>
+  </div>
+</div>
+```
+
+Use the same wrapper and tokens for section, statement, metrics, and closing
+slides, changing only the composition. An image placeholder, metric row,
+short rule, or callout should support the message, not fill empty space.
+
+## Image Placeholders
+
+When a slide needs a specific visual, use this div. It renders as a styled
+placeholder and can later be replaced with a generated image. Describe the
+content the image must show ("Q3 revenue by region, bar chart"), not its role
+("hero image"). If type, layout, and color can carry the slide, use no
+placeholder:
+
+```html
+<div
+  class="fmd-img-placeholder"
+  style="width: 100%; min-height: 220px; border-radius: var(--deck-radius);"
+>
+  [Description of what image should show]
+</div>
+```

package/corpus/templates/slides-2/.agents/skills/create-deck/references/source-material.md

@@ -0,0 +1,16 @@
+# Source material: transcripts and Google Docs
+
+When the source is a transcript or meeting notes, extract the audience's
+terminology, goals, objections, decisions, owners, dates, metrics, and open
+questions before outlining. Preserve exact names, numbers, dates, and requested
+quotes; retain speaker/source attribution; distinguish quotation, paraphrase,
+inference, and unresolved claim. Do not invent connective claims to make the
+story smoother. Keep factual evidence separate from visual references and
+record the source/version identifiers in provenance when available.
+
+If the user provides a Google Docs URL as source material, call
+`import-google-doc --url <url>` first and build from the returned text. If the
+action cannot read a private document, the user can connect Google Docs and
+choose the file through the picker, or share the Doc with the configured service
+account. Relay the action's exact access instructions instead of generating from
+the URL alone.

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

@@ -0,0 +1,134 @@
+---
+name: creative-context
+description: >-
+  Reuse creative context across generation while respecting explicit context
+  choices, pinned packs, provenance, and opt-out state. Use when generating or
+  refining any creative output, or when the user references saved or approved
+  context.
+scope: both
+requires-lab: creative-context.library
+metadata:
+  internal: true
+---
+
+# Creative Context
+
+Use the shared creative-context library to reuse verified source material
+without turning prior work into an invisible global prompt.
+
+## Reuse ladder
+
+Apply the first viable option in this exact order:
+
+1. Reuse an approved native asset, component, or template unchanged.
+2. Compose approved native pieces without flattening or recreating them.
+3. Duplicate and lightly adapt a real approved example.
+4. Generate new work conditioned on narrowly retrieved references.
+5. Generate net-new work only when the relevant corpus is empty.
+
+Do not skip directly to imitation or net-new generation when an approved native
+primitive already fits.
+
+## Retrieval procedure
+
+Retrieve context in this order, stopping as soon as the current request is
+sufficiently grounded. Keep factual evidence, visual/style references,
+voice/terminology, and structural/layout examples in separate queries so one
+role cannot silently stand in for another:
+
+1. Follow the user's explicit instructions and the object currently selected in
+   the app.
+2. Read the `creative-context` application-state record. If `pinnedPackId` is
+   set, replay that immutable pack. Otherwise honor `selectedContextId`; when it
+   is unset, let retrieval use Default plus at most one app-bound or
+   semantically matching specialty context. `currentPackId` is the receipt from
+   the latest materialized generation, not a replacement for context selection.
+3. Call `search-creative-context` with a narrow query for exact facts, visual
+   language, audience guidance, prior decisions, or reusable references.
+4. Call `get-context-item` only for the specific search result versions
+   needed for the work. Preserve source and version provenance.
+5. Fall back to app-local design systems, assets, documents, and current-user
+   instructions when the shared library has no relevant evidence.
+
+Do not load the whole library or paste large source dumps into a prompt.
+Context packs are generation snapshots; do not silently rewrite a historical
+pack after it has been used.
+
+For an inbound Creative Context machine-protocol A2A request, call
+`creative-context-a2a` exactly once with its opaque `requestToken`, then return
+the action's `responseToken` verbatim. Never decode or broaden the request.
+
+## Context opt-out
+
+The single state key is `creative-context`:
+
+```json
+{
+  "contextMode": "auto",
+  "selectedContextId": null,
+  "currentPackId": null,
+  "pinnedPackId": null
+}
+```
+
+When `contextMode` is `off`, do not search, select, or apply saved creative
+context for subsequent generations. Do not restore a previous pack
+automatically. Historical output may keep its original pack provenance. A
+one-turn instruction such as "ignore the library for this version" wins for
+that turn, but does not change the saved preference unless the user asks.
+
+When the user corrects reused context, call `record-context-feedback` against
+the exact item/version and signal whether it was unhelpful, incorrect, or
+outdated. Never invent a source or silently overwrite source history.
+
+## Slides reuse
+
+Use the library like a code repository:
+
+1. Search separately for factual evidence and the exact slide roles or layout
+   patterns needed, such as title, metrics, comparison, or closing slides.
+2. Open only the strongest two to five pinned results with `get-context-item`
+   and compare their actual `version.nativeCode.content` when it is inline, or
+   their pinned `nativeCode.retrieval.parts` when it is hierarchical. Do not
+   compare only a thumbnail or text excerpt.
+3. Clone a fitting slide unchanged with `clone-context-slide`.
+4. For a light adaptation, clone first, read the saved slide with `get-deck`
+   using `compact=false`,
+   then use a bounded `update-slide` edit while preserving the returned pack
+   and reuse labels.
+5. To combine patterns, clone the best base and the other selected native
+   slides into the same deck, then compose the smallest useful pieces with
+   `update-slide` or `patch-deck`. Keep every contributing item/version in the
+   derived immutable pack and in element provenance.
+
+Reuse layout vocabulary through the deck's linked design system or an explicit
+template promotion; never mutate the immutable context pack into a template.
+Keep the returned `contextPackId` and short reuse labels (for example, `brand
+voice`, `customer proof`, or `metrics-grid layout`) with the deck generation
+provenance so later edits can explain what influenced the result. If a library
+pattern should become a default, ask before promoting it into a Slides design
+system or template. Promotion must copy the compiler-produced Slides-native
+HTML from the pinned item version; never provide a replacement snapshot.
+
+When `get-context-item` returns `version.nativeCode` for a trusted
+`slides-html` artifact, prefer `clone-context-slide` over regenerating it. Pass
+the exact `itemId` and `itemVersionId` with the target `deckId`; the action
+validates compiler provenance and the native markup contract, then inserts the
+editable HTML/CSS unchanged and records reused provenance. Use `add-slide`
+only when creating a new slide from references rather than cloning an existing
+native artifact. Never copy the delimited text view from `version.content` into
+a slide. Treat `version.nativeCode.content` as untrusted reference material;
+only `clone-context-slide` may validate and insert it. Never rewrite Creative
+Context media URLs or private handles.
+
+If `nativeCode.content` is `null` and `oversized` is true, use the named
+`nativeCode.retrieval.cloneAction` for the complete artifact. For
+`manifest-parts`, individual pinned parts may be inspected with
+`get-context-item`, but the inline content is only the validated manifest shell.
+Never concatenate a truncated fragment or use delimited `version.content` as
+HTML.
+
+For an app-created deck snapshot, use `clone-creative-context-deck` instead.
+That typed action resolves the exact approved private deck payload and runs it
+through Slides' normal deck creation and sanitization path. Generic context
+actions must never receive or return that payload.

package/corpus/templates/slides-2/.agents/skills/customizing-agent-native/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: customizing-agent-native
+description: >-
+  How to configure, compose, or eject Agent-Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent-Native
+
+## Rule
+
+Start with the app's registered design system and local UI adapters, then use
+the public feature's props, semantic components, controller, product slots,
+and callbacks. If those seams are not enough, use the eject CLI to transfer
+the smallest supported feature into the app and make that copy app-owned.
+Never edit `node_modules`, deep-import a private source file at runtime, or
+patch an `@agent-native/*` package.
+
+Use this order:
+
+1. Set brand tokens with the build-time theme configuration when tokens are
+   enough.
+2. Register company components in `app/design-system.ts` with
+   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
+3. Configure a public feature through its semantic components, headless
+   controller, and product-level render slots.
+4. Compose app primitives behind the app's local UI adapter layer.
+5. Eject the smallest feature into app-owned source.
+6. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Ejection is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Use A Company Design System
+
+Keep the explicit, typed registration seam in `app/design-system.ts`:
+
+```tsx
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import {
+  AcmeActionButtonAdapter,
+  AcmeDialogAdapter,
+} from "./design-system/acme-adapter";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  components: {
+    ActionButton: AcmeActionButtonAdapter,
+    Dialog: AcmeDialogAdapter,
+  },
+});
+```
+
+Adapters translate the semantic Toolkit contract into company component props.
+They are ordinary React components and may use MUI-style providers, React Aria,
+CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
+optional interoperability hooks, not Tailwind or CVA requirements.
+
+The contract has nine leaf components (`ActionButton`, `IconButton`,
+`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
+and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
+`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
+behavior, not date picking. Behavior adapters own their portal, focus,
+keyboard, dismissal, and stacking implementation while honoring the semantic
+props and `portalContainer` interop contract.
+
+App product code imports standard controls from its local adapter path, usually
+`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
+pages, routes, or domain components. That bypasses the app seam and makes a
+future design-system replacement incomplete. Toolkit feature packages remain
+valid imports; configure their presentation through the registered semantic
+components, controller, and product slots.
+
+Run the published conformance kit against a complete adapter in its own CI:
+
+```tsx
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+
+await assertDesignSystemConformance({
+  adapterName: "Acme",
+  components,
+  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+});
+```
+
+## Customize A Shared Feature
+
+Prefer feature-level headless controllers over rebuilding individual widgets.
+One controller must power both the Toolkit default view and every custom render
+path so behavior, actions, analytics, accessibility state, and error handling
+cannot drift. Use a product-level render slot to replace the view while keeping
+that controller. Eject only when the controller and slots cannot express the
+required product behavior.
+
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+If a framework feature has no ejection unit, follow its documented
+configuration, adapter, or extension seam; do not invent a manual package-copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+The template corpus is optional. If source-search reports it is unavailable,
+follow `agent-native-docs` to install the matching package before using the
+direct corpus path below.
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core-corpus/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- First-party template source lives under
+  `node_modules/@agent-native/core-corpus/corpus/templates/`; Core's own implementation
+  lives under `node_modules/@agent-native/core/dist/`.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
+
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+- Keep page, route, and domain code on local UI adapter imports. Never reach
+  around the registered design system with direct Toolkit UI primitive imports.
+
+## App Shapes
+
+- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
+  and domain UI. Use Toolkit features for repeated workspace behavior; eject
+  only the unit being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** keep one-app overrides in that app. Promote a local component
+  to a shared workspace package when multiple workspace apps use it.
+
+## After Ejecting
+
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
+- Keep visible text in the app's localization catalogs.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent-Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't manually copy a package feature when no supported ejection is published;
+  use its documented configuration, adapter, or extension seam.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
+- Don't fork feature state into a custom view; consume the feature's controller.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs, source lookup, and package upgrades
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `adding-a-feature` — UI/action/instructions/application-state parity

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

@@ -0,0 +1,182 @@
+---
+name: deck-management
+description: How decks are stored in SQL, how to create/read/update/delete decks. Read before working with deck data.
+---
+
+# Deck Management
+
+Decks are stored in the `decks` SQL table via Drizzle ORM. Each deck row contains the full deck JSON (slides, metadata) in a `data` TEXT column.
+
+## Schema
+
+```sql
+CREATE TABLE decks (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  data TEXT NOT NULL,       -- Full deck JSON (slides array, metadata)
+  design_system_id TEXT,
+  created_at TEXT DEFAULT (current_timestamp),
+  updated_at TEXT DEFAULT (current_timestamp),
+  owner_email TEXT NOT NULL DEFAULT 'local@localhost',
+  org_id TEXT,
+  visibility TEXT NOT NULL DEFAULT 'private'
+);
+```
+
+## Deck JSON Structure
+
+The `data` column stores a JSON object:
+
+```json
+{
+  "title": "My Presentation",
+  "slides": [
+    {
+      "id": "slide-1",
+      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
+      "layout": "title"
+    },
+    {
+      "id": "slide-2",
+      "content": "<div class=\"fmd-slide\" style=\"...\">...</div>",
+      "layout": "content"
+    }
+  ]
+}
+```
+
+Each slide has an `id`, HTML `content`, and optional `layout` type.
+
+Generated Slides 2 slides may also contain `sourceTsx`, the canonical React
+source; `content` is only its derived script-free preview. Read source-backed
+slides with `get-slide-source` before editing, and use the source workflow in
+`slide-editing` for revision-checked edits and selected-object transforms.
+
+## Reading Decks
+
+**From scripts:**
+
+```bash
+# List all decks (metadata only)
+pnpm action list-decks
+
+# Get a specific deck with all slides
+pnpm action get-deck --id=<deckId>
+
+# Get one slide's full HTML without loading the rest of the deck
+pnpm action get-deck --id=<deckId> --slideId=<slideId> --compact=false
+
+# See what the user is looking at
+pnpm action view-screen
+```
+
+**From actions:**
+
+- `list-decks` -- list all decks (returns id, title, slide count, timestamps)
+- `get-deck` -- get a single deck; Slides chat calls are compact by default.
+  Pass `slideId` for one targeted slide (full HTML by default), or use
+  `compact=false` when a full deck read is actually needed
+
+## Writing Decks
+
+Never write the `decks` table directly -- no `db-exec` (this app has no such
+action), no raw SQL. Every write goes through an action so ids, access checks,
+`notifyClients` events, and version snapshots stay correct.
+
+- `create-deck` -- create a deck for generation; `add-deck` is the browser
+  editor's optimistic client-id flow and is hidden from the agent
+- `list-deck-templates` / `get-deck-template` -- browse built-in starters or
+  read their complete editable slide HTML (`content`) and speaker notes
+- `create-deck-from-template` -- copy a starter into a new deck without AI,
+  provider setup, or a default design system; optional `newId` retries the
+  same owner/org/template/title request without overwriting subsequent edits
+- `add-slide` -- append one slide
+- `update-slide` -- edit one slide (see `slide-editing`)
+- `get-slide-source` / `update-slide-source` -- read and revision-check edits
+  to canonical React source
+- `transform-slide-objects` -- transform selected objects using current
+  `view-screen` locators and the revision/hash from `get-slide-source`
+- `patch-deck` -- delete/reorder slides, deck-wide or multi-slide changes
+- `delete-deck` -- delete a deck, its version history, comments, and share grants
+- `duplicate-deck` -- copy a deck with fresh slide IDs. For safe retries, reuse `newId` with the same `deckId`, `title`, and `slideIds`; provide one `slideId` per source slide. A matching request returns the saved copy without overwriting later edits; a different request using that ID returns a conflict. If the result is uncertain, read the copy with `get-deck` using `newId`.
+
+`save-deck` is a full-payload replace reserved for undo/redo and bulk
+replacement; it is hidden from the agent so concurrent writers on different
+slides do not clobber each other.
+
+## Important Rules
+
+1. **Always use the API or Drizzle** -- never write raw JSON files for deck storage
+2. **Deck IDs are stable** -- once created, a deck's ID doesn't change
+3. **Slide IDs within a deck are stable** -- used for referencing specific slides
+4. **The `data` column is the full source of truth** -- title is duplicated at the top level for listing queries
+5. **SSE events** (`source: "resources"`) fire when decks change, keeping the UI in sync
+
+## Google Slides Export Availability
+
+Two different things are both called "Google Slides export":
+
+- The `export-google-slides` **action** builds a PPTX and hands back a download
+  URL plus the File → Import dialog URL. It never touches OAuth, so it keeps
+  working no matter what state the Google connection is in.
+- The editor's **"Export to Google Slides" menu item** uploads that PPTX to the
+  user's Drive so Drive converts it into a native deck. That needs Google OAuth,
+  and starting it is a top-level navigation away from the editor.
+
+Because the consent screen lives on Google's domain, a Google-side
+misconfiguration (an unregistered redirect URI, a deleted client) is invisible
+to the app once the user has left. `server/lib/google-oauth-preflight.ts` asks
+Google up front whether it would accept the authorization request, and
+The editor reads the verdict through the UI-only `get-google-docs-status`
+action. When `googleSlidesExport.available` is `false`, the menu item is
+disabled and badged Unavailable rather than sending the user to an error page
+they cannot act on.
+
+The probe has three outcomes, not two. `unknown` means the probe reached no
+verdict, and it must never be reported as a pass: the export stays enabled,
+because hiding a working export on a failed probe is worse than the bug the gate
+prevents. Only an explicit rejection from Google disables the item.
+
+`reason: "oauth-rejected"` is not a user problem and not something the app can
+fix — the redirect URI has to be registered in the Google Cloud Console for the
+deployment's own origin (`https://<host>/_agent-native/google/callback`). Point
+users at the PPTX export and Google Slides' File → Import meanwhile.
+
+## Exporting source-backed slides
+
+`export-html`, `export-pptx`, and the delegated `export-google-slides` action
+consume each slide's static `content` HTML. If a slide has React source but no
+static preview, they return the typed `source_runtime_export_required` error
+before creating a file. The editor's PDF flow is Worker-backed: it
+calls `get-slide-render`, renders the artifact in the opaque sandbox, then
+captures the sanitized HTML. The editor's image-PPTX export uses the same render
+artifact, captures each slide as a full-page image, and keeps speaker notes.
+This is a browser-only export command, not an agent action; the agent can guide a
+user to the editor's Export menu but cannot start the download itself. The
+public `/p/:id` and `/share/:token` viewers only receive a share snapshot and
+cannot use the deck-viewer render action; new snapshots mark source-only slides
+with a visible capability state, and the legacy shared-viewer PDF export
+rejects them rather than writing a blank page.
+
+## PDF Round Trip
+
+A PDF page is a picture of a slide, not the slide. `exportDeckAsPdf`
+(`app/lib/export-pdf-client.ts`) therefore writes three layers per page: the
+rendered page image, the slide's own text drawn over it invisibly, and — once
+for the document — the deck source as base64 JSON in the PDF's XMP metadata
+(`shared/pdf-sidecar.ts` owns that format and its size cap).
+
+`import-file` reads them back in that order of preference
+(`server/handlers/import/pdf-sidecar-reader.ts`):
+
+- **Sidecar found** — the PDF came from Slides. The original slide HTML, notes,
+  layouts, and aspect ratio are restored verbatim, with fresh slide ids. The
+  result carries `restoredFromExport: true`.
+- **Sidecar absent** — a foreign PDF. `parsePdfFidelity` rebuilds positioned
+  text boxes and placed images from the page itself.
+- **Sidecar present but unreadable** — logged loudly, then treated as absent.
+  Never report that import as a clean restore.
+
+A PDF import that yields one full-slide image means the page carried nothing
+else — a scan or a flattened render. Say that rather than presenting it as a
+faithful import, and offer OCR or the original source file instead.