codex-slides

# Codex Slides

Run Codex Slides as an interactive product inside Codex. The live Browser
workspace is the primary experience; MCP and the bundled CLI are transports
for opening the workspace and performing deterministic operations, not a reason
to hide the presentation workflow in a long-running Codex turn.

## Browser-first default

For every new deck request, unless the user explicitly asks for a headless,
unattended, one-call, or CLI-only run:

1. Call `open_codex_slides` / CLI `open` **without** a project id, immediately
   navigate the returned URL in Codex's in-editor Browser, and verify that the
   Codex Slides home/create screen is visible.
2. Keep the Browser open. Enter the user's request in the home composer, attach
   or assign source files in the UI, and submit it there. This creates a durable
   project before clarification starts. If UI submission is not reliable, use
   `start_project` / CLI `start-project` only as a deterministic fallback, then
   navigate its returned project URL immediately.
3. Continue in the live project workspace. Let Codex Slides show and own each
   checkpoint: requirements/clarifying questions, research progress, editable
   outline confirmation, visual-inspiration or style selection, and rendering.
   Answer or manipulate each step in the Browser; when a choice materially
   changes the result and the user's prompt does not resolve it, leave that
   checkpoint visible and ask the user.
4. During research and rendering, keep the project workspace visible so the
   user sees progress and can steer. Do not leave Codex showing only a generic
   "working" message while a hidden tool completes the whole deck.
5. After rendering, inspect the deck in the same Browser workspace. Use its
   agent composer, slide controls, mark mode, Play, Design Files, and brand
   system for follow-up work. Export only after visual review.

Do not call `deep_research`, `create_outline`, `rank_inspiration`,
`render_deck`, or `create_deck` before opening the Browser for a normal deck
request. Do not default to `create_deck`; it is the explicit unattended fast
path. A user's request such as "make a six-slide deck and show me" still uses
the Browser-first guided flow unless they specifically ask Codex to finish it
in the background without checkpoints.

## Choose a transport

1. Use the `codex_slides` MCP tools when they are exposed in the current
   session and a structured tool call is convenient.
2. Otherwise run `scripts/codex-slides.mjs`. Pass inputs with `--json`,
   `--input-file`, or command flags. It installs, builds, and starts the local
   app when necessary.
3. Do not treat MCP as a prerequisite. Both transports use the same API and
   return the same project URLs.

Every Browser-capable response includes a `browserHandoff`. Follow its exact
URL instead of rebuilding one, because it can focus a slide, panel, version,
mode, checkpoint, conversation, or durable run.

Run this to discover the portable command surface:

```bash
node <skill-dir>/scripts/codex-slides.mjs capabilities
```

Read [references/COMMANDS.md](references/COMMANDS.md) when selecting commands,
constructing JSON inputs, or mapping a CLI command to an MCP tool.
Read [references/CAPABILITY_MATRIX.md](references/CAPABILITY_MATRIX.md) when
auditing a newly added product feature or changing the Browser/CLI/MCP contract.

## Build a deck

- Discover workflow presets with `scenarios` / `list_scenarios`. A scenario owns
  its default page count, aspect, research behavior, model instruction, and
  required/optional source slots. Pass its `scenarioId` to `onboard`,
  `research`, `create`, or `outline`; do not re-create the scenario prompt by
  hand.
- Upload slot files with `upload-material` / `upload_material`, then pass both
  `materialIds` and `materialContexts` (`id`, `name`, `role`). Required slots
  must be satisfied before creation. Keep content sources, datasets, brand
  assets, templates, and visual references in their declared roles.
- Use the Browser-first guided flow above by default. The Browser UI drives the
  staged `clarify -> outline -> inspire -> deck` state and persists the project
  before expensive work starts.
- Search the shared community style library with `templates` / `list_templates`
  (`query` and `communityGroup`), then use `inspiration` / `rank_inspiration`
  when the topic and outline should semantically rank those directions. A chosen
  community style is both prompt context and the first visual reference image.
- Use `start-project` / `start_project` only when Codex needs a deterministic
  fallback to create the same durable project shell before returning to the UI.
- Use `create` / `create_deck` only when the user explicitly requests an
  unattended one-call result or the current Codex surface has no Browser.
- The lower-level `onboard`, `research`, `outline`, `revise-outline`,
  `inspiration`, and `render` operations are for CLI automation, recovery, and
  deterministic mutations. Keep the corresponding Browser project open when
  using them interactively.
- For navigation-independent Deck Agent, outline, or render work, use
  `start_project_run` / CLI `run-start`. Retain its `runId`; use
  `get_project_run`, `wait_project_run`, or `cancel_project_run` (CLI
  `run-status`, `run-wait`, `run-cancel`) after navigation or reconnect.
- Preserve the Markdown research brief and its source links. Do not call a
  brief source-backed when it contains no source links.
- Upload logos, screenshots, PDFs, or other references with `upload-material`
  before creation, editing, or restyling, then pass the returned material ids.

## Operate Design Files

- Use `design-files` / `list_design_files` to inspect the generated and uploaded
  project file inventory. Use `read-design-file` / `read_design_file` for text
  and the returned Browser deep link for visual or binary files.
- In the Browser, every selected Design File exposes its absolute local path for
  copying and a direct download ac