Revela

English | 中文

Revela is a Codex plugin for turning source materials, research, data, and intent into trusted, traceable, presentation-ready decision artifacts.

In your local workspace, Revela reviews materials, saves source-linked research, builds an explicit deck-plan.md, generates HTML decks, reviews them, and exports PDF/PPTX/PNG artifacts.

Install

Codex

Requirements:

• The Codex CLI must be installed and the codex command must be available in your shell.
• Your environment must be able to run bun; Revela uses bun ./mcp/revela-server.ts from the installed Codex plugin cache to start the MCP server.
• For interactive Review Apply actions, codex exec must also work because the Review UI uses it after saved comments are applied.

Optional preflight:

codex --version
codex exec --help
bun --version

If npm package checks fail with an npm cache permission error, repair the cache ownership or use a writable cache for local checks:

sudo chown -R "$(id -u):$(id -g)" ~/.npm
npm_config_cache=/tmp/revela-npm-cache bun run smoke:mcp-pack

Install Revela through the Codex Git marketplace:

codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref v0.18.15
codex plugin add revela@revela

The Git marketplace install provides the Codex plugin shell, skills, hooks, and MCP configuration. When Codex starts the Revela MCP server, it runs bun ./mcp/revela-server.ts from the installed plugin cache and resolves the checked-out marketplace runtime.

You do not need to run bun install inside the Codex marketplace clone.

Start a new Codex thread after installing so Codex loads the Revela skills, MCP tools, and hooks.

Codex uses nine Revela skills: revela for routing the next workflow step, revela-spec for writing root-level spec.md, revela-helper for status and active design/domain, revela-design for custom design creation/validation/activation, revela-domain for custom narrative domain creation/validation/activation, revela-research for local and web research saved under researches/ plus the design-aware deck-plan.md handoff, revela-make-deck for generating decks/*.html from an existing plan, revela-review for the Review UI, and revela-export for PDF/PPTX/PNG.

For release-aligned local validation, run bun run smoke:mcp-pack. It packs the current checkout to a temporary npm tarball, extracts it, and starts the MCP server through the packaged Codex plugin launcher path without requiring a registry publish.

Codex Upgrade

In Codex, ask Revela to check the current runtime version; the plugin calls revela_doctor and reports the running version.

For a fixed release tag, reinstall the plugin from that tag:

codex plugin remove revela@revela
codex plugin marketplace remove revela
codex plugin marketplace add https://github.com/cyber-dash-tech/revela --ref vX.Y.Z
codex plugin add revela@revela

For a marketplace entry that intentionally tracks a branch or movable ref, upgrade the marketplace clone and re-add the plugin:

codex plugin marketplace upgrade revela
codex plugin add revela@revela

The Git marketplace ref and .mcp.json plugin launcher are part of the same release artifact. Start a new Codex thread after upgrading so Codex reloads the Revela skills, MCP tools, hooks, and runtime launcher.

Built-In Designs

Revela includes built-in deck designs:

summit

monet

lucent

starter is the clean default presentation style.

To switch designs in Codex, ask:

$revela:revela, use summit as the design.

In Codex, ask Revela to list or switch designs; the plugin uses the active design when making decks.

Domains

Domains add topic-specific communication guidance, such as consulting, product, or investor communication. Use them when you want Revela to adapt deck framing to a specific context.

$revela:revela, list available domains.

In Codex, ask Revela to list or switch domains; the active domain guides deck framing during init, research, and planning.

Quick Start

Use these prompts in Codex from the workspace that contains your source materials.

1. Choose the narrative domain before authoring so Revela frames the audience, decision, risks, and objections for your context.

$revela:revela, use consulting as the domain.

2. Choose the deck design before rendering so generated artifacts use the intended visual language.

$revela:revela, use summit as the design.

3. Create a custom design when you want a different visual direction.

$revela:revela, create a new design named neon-finance with a crisp financial-dashboard style: dark surfaces, precise grids, and bright green accents.

Revela may ask for references or constraints, then creates and validates the design. When it is ready, switch to it:

$revela:revela, use neon-finance as the design.

4. Initialize local material intake. Init scans, extracts, and reviews workspace sources; it does not create a Narrative Vault.

$revela:revela, help me init this workspace from the local materials.

5. Research source-linked deck inputs and save findings.

$revela:revela, research the public evidence and examples needed for this deck.

6. Create or update the deck plan before generating HTML so slide order, chapter structure, source links, unresolved inputs, source limitations, and visual intent are explicit.

$revela:revela, create or update the deck plan before generating HTML.

7. Make an HTML deck from the current deck plan.

$revela:revela, make the deck from the current deck plan.

8. Review the generated deck for Artifact QA and targeted edits.

$revela:revela, review the generated deck.

9. Export a PDF after deck QA passes.

$revela:revela, export the deck to PDF.

10. Export an editable PPTX after deck QA passes.

$revela:revela, export the deck to PPTX.

11. Export per-slide PNG files after deck QA passes.

$revela:revela, export the deck to PNG.

Review A Deck

Use Review after generating an HTML deck:

$revela:revela, review the generated deck.

Review opens a local deck workspace for QA and targeted edits:

• Comment lets you request targeted edits on the deck, such as layout, copy, hierarchy, spacing, or visual changes.