nexu-io/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 Browser

This specialized skill remains for compatibility. The canonical
`codex-slides` sibling skill owns the full workflow and portable CLI.

1. Call `open_codex_slides` when the MCP tool is available. Otherwise run
   `node ../codex-slides/scripts/codex-slides.mjs open --json '<input>'` from
   this skill directory. Pass `projectId` when the user named a deck;
   otherwise omit it for the create workspace.
   Use `view:"scenarios"` for the 24-workflow catalog,
   `view:"design-files"` plus `projectId` and optional `filePath` for project
   files, or `view:"brand-system"` plus `projectId` for the brand editor.
2. Navigate the returned resource link in the Codex in-editor Browser. Do not
   stop after printing the URL and do not ask the user to open it manually.

# Codex Slides Deck

The canonical `codex-slides` sibling skill owns the complete workflow. Use the
`codex_slides` MCP tools when available; otherwise run its self-contained CLI
at `../codex-slides/scripts/codex-slides.mjs`. Keep the live workspace available
in the in-editor Browser whenever visual review helps.

## Choose the flow

- Default to the live Browser workflow: open the Codex Slides home screen,
  submit the request there, then operate the created project through clarify,
  outline confirmation, style selection, rendering, and review. Keep the
  Browser visible throughout.
- If Browser UI submission fails, use `start_project` / CLI `start-project` to

# Codex Slides Known Errors

Classify the failure before retrying. Preserve the same project id and run id;
do not recreate a deck merely because a Browser tab closed or a wait timed out.

## Runtime and installation

- **Plugin version contract fails:** `.codex-plugin/plugin.json` must start with
  the exact root `package.json` version plus `+codex.`. The desktop package must
  use the same product version.
- **App is unreachable:** inspect `CODEX_SLIDES_URL` and `CODEX_SLIDES_LOG`.
  The local MCP launcher may need to prepare dependencies or a standalone build.
- **Installed skill or tool inventory looks stale:** reinstall/upgrade the
  plugin and start a new Codex task so the versioned plugin cache is refreshed.

# Codex Slides Research

The canonical `codex-slides` sibling skill owns the complete workflow. Use
`deep_research` when MCP is available; otherwise run CLI command `research` at
`../codex-slides/scripts/codex-slides.mjs`. Preserve its Markdown and citations
so the user can review or edit the evidence before slide generation.

For the default interactive workflow, first open the Codex Slides home screen
in the Codex Browser, submit the research request there, and keep the created
project visible while its research, outline, style, and render checkpoints
advance. Use the lower-level sequence below only for CLI automation, recovery,
or a user-requested headless workflow:

1. If a research workflow fits, call `list_scenarios` / CLI `scenarios` and

# Codex Slides Structured Intake

The Codex Slides Browser owns the canonical intake form. Structured intake must
produce one durable project and one shared clarification state, not a separate
chat-only questionnaire.

## Flow

1. Call `open_codex_slides` without a project id and follow its
   `browserHandoff` to the home/create workspace.
2. When a workflow preset fits, call `list_scenarios`, then open the selected
   scenario deep link. Use product-owned defaults and source slots.
3. Submit the user's topic and available files in the Browser. Assign every
   uploaded file its scenario role; do not flatten datasets, source decks,

# Codex Slides Verification

Use two signals before reporting a presentation task complete:

1. Read canonical project state with `get_project`, and read a named durable job
   with `get_project_run` or `wait_project_run` when a `runId` was returned.
2. Follow the returned `browserHandoff` and inspect the exact visible result in
   the Codex in-editor Browser.

## Verification sequence

1. Confirm the project id rather than guessing from a similar title.
2. For a durable run, require a terminal `complete` status. Treat `error` and
   `cancelled` as incomplete; a timed-out wait leaves the run active.