RAS — RAISE A SLIDE

English · 臺灣華語

Turn a topic or outline into a presentation you can rehearse and deliver. RAS is an independent AI plugin plus a portable Marp project kit, inspired by RAISE A SUILEN. Each generated presentation is a self-contained project.

Original RAS code, documentation, and templates use the MIT licence. This is an unofficial project with no affiliation, sponsorship, or endorsement from the franchise or its rights holders. See rights and affiliation; the software licence does not grant third-party character or trademark rights.

What it does

• Create a narrative outline, slide text, and speaker notes from a brief.
• Revise an existing talk while preserving its voice and reveal sequence.
• Build HTML, export PDF/notes, and render every page for inspection.
• Check slide counts, local resources, font loading, text size, overflow, and clipping.
• Keep facts and asset provenance separate from rehearsal cues.
• Verify supplied images' use terms and required creator/rightsholder credits.

The AI host supplies the model and tools. The JavaScript scripts build and verify slides; they do not call an AI API. The plugin's creative workflow requires an AI host, while an exported project builds on its own.

Browse the documentation locally

From this repository, run npm ci once, then:

npm run docs

Open English documentation or 臺灣華語文件. The language switcher keeps the current page while translating navigation and content. Mermaid renders locally. Refresh after editing Markdown; use PORT to select a different port. This command previews the repository documentation. Deck preview commands below run inside an initialized presentation project.

Start a standalone deck

Requires Node.js 22.18+ and npm. From this repository:

node scripts/ras.mjs init ../my-talk
cd ../my-talk
npm ci
npm run doctor
npm run export
npm run preview

Edit brief.md, slides.md, sources.md, and theme.css. The initial deck is a runnable ten-page example, Give one idea a stage. Replace it with your talk. The generator copies the build tools and preserves the locked dependency graph in the new project. The project remains usable after moving it away from this repository.

The install needs network access for npm dependencies and Puppeteer's browser. If the browser was not installed, run npx puppeteer browsers install chrome. Alternatively set RAS_BROWSER_PATH to a Chrome/Chromium executable. Once installed, builds use local fonts, images, and pre-rendered Mermaid diagrams.

Generated projects also include an optional Just command entry point. Inside the generated project, just deps installs its dependencies, just doctor diagnoses the environment, and just build (or just export) exports HTML, notes, and PDF. just html performs the HTML-only build, and just preview starts the preview server. The npm commands remain available without installing Just.

Preview reuses output whose build hash matches the current source, preserving an exported PDF and its verification evidence. Changed source or missing HTML triggers a fresh HTML build. Explicit HTML builds and checks replace dist/ and remove any previous PDF; export again afterward if needed.

dist/ is generated output and is replaced on every build. Keep source assets in assets/, not in dist/. The preview serves dist/; rebuild after edits and refresh the page. Set PORT for a different local port. Marp HTML supports keyboard navigation and presenter view. HTML contains speaker notes; PDF is the audience-only handout.

Use with Codex, Claude Code, or open models

All entry points read the same skills and workflow. Model selection belongs to the host; RAS has no vendor API key or model requirement. A model needs file/shell tools to complete the whole production flow. Plain chat can draft the files; rendering and verification then happen through the standalone JavaScript tools.

Claude Code

Load this repository as a local plugin:

claude --plugin-dir /path/to/ras

Then use /ras:create, /ras:outline, /ras:revise, /ras:review, /ras:export, /ras:remember, or /ras:retro. Each operation is a shared skill, so no separate command definitions are needed. Claude Code automatically scans the plugin's skills/ directory; the Claude manifest does not need a skills field. The skills and interface fields in this repository belong to .codex-plugin/plugin.json.

Codex

The repository includes a portable plugin.json and a compatible .codex-plugin/plugin.json for plugin packaging. For immediate local use, install the project skill bundle described below, or point Codex directly to the operation skill. Creating this repository does not automatically install it in Codex.

For a project-local skills fallback, copy SKILL.md, skills/, references/, agents/, profiles/, templates/, scripts/, docs/, LICENSE, NOTICE.md, the package manifests, and .gitignore together under the project's .agents/skills/ras/, and start a new session. Preserve this bundle's relative paths; copying a SKILL.md alone loses its supporting files.

Use natural language or the model-side router:

ras:create brief.md
ras:create Explain retry policies to junior engineers in 15 minutes --plan
ras:outline talks/retries Discuss the narrative for a 15-minute retry-policy talk before drafting slides
ras:revise talks/retries/slides.md Shorten the opening to two minutes
ras:review talks/retries/slides.md
ras:export talks/retries/slides.md
ras:remember In talks/retries, introduce the problem before showing code
ras:retro Review this session for reusable lessons in talks/retries

Host command discovery varies. The router does not register native slash commands or promise autocomplete. You can also point the AI directly to the relevant skills/<operation>/SKILL.md in this repository.

Open models and hosts without plugin discovery

Export a complete prompt, with the selected skill, shared rules, and role instructions expanded from their source files. This needs only Node.js:

node /path/to/ras/scripts/ras.mjs prompt create \
  'Explain retries to junior engineers in 15 minutes. Create ./talk.' > ras-request.md

For direct Ollama / local chat, use explicit chat mode:

node /path/to/ras/scripts/ras.mjs prompt create --chat \
  'Explain retries to junior engineers in 15 minutes.' > ras-chat.md
ollama run YOUR_MODEL < ras-chat.md

You can also paste ras-chat.md into a local chat interface. Supply the contents of any brief/source files that the model cannot read. Save its labelled drafts into a deck created with init, then run npm run export. Chat mode explicitly returns file contents and commands; it cannot write files, browse sources, inspect images, or export on its own. prompt outline, prompt revise, prompt review, prompt export, prompt remember, and prompt retro expand the matching shared operations; --plan remains plan-only for creation. Memory prompts in chat mode propose entries and saving steps without claiming to persist them.

For a tool-capable model through Codex's local provider instead:

codex exec --oss --local-provider ollama -m YOUR_MODEL \
  --sandbox workspace-write --skip-git-repo-check - < ras-request.md

Start the local provider and install a suitable model first. Codex also accepts --local-provider lmstudio. RAS does not select/download a model or modify your provider configuration. Models differ in tool use, context capacity, and writing quality; this adapter does not certify every model.

The production team

Roles are responsibilities, not five compulsory agent calls. The host may execute them sequentially. The speaker controls what the talk says. Character theming stays in the collaboration; the slide theme is chosen per presentation.

Creation follows CHU² → LAYER → PAREO → LOCK → visual inspection → MASKING → CHU². Review findings return to the responsible role, then the changed deck is rebuilt and rechecked. Each handoff carries artifact paths and actual evidence. The shared workflow defines the shorter revision, review, export, and plan-only routes. Role files provide distinct voices and original example lines. Ask for plain output to omit the character labels and mannerisms. A single model uses successive passes and reports that honestly.

Collaboration defaults to Taiwanese Mandarin, independently of slide language; an explicit request can change the conversation language. 🎧 CHU² frames the aim and delivery, while working roles respond to the preceding pass's concrete finding in their own rhythm. For example, 🎤 LAYER can propose keeping the conclusion on the slide and moving background into notes; 🎸 LOCK then picks up that decision and explains the edit and checks. These are illustrative exchanges, not claims that any work has run. All seven operations and portable prompts share the same interaction rules.

The optional Wei profile captures short sentences, large type, progressive reveals, code/diagrams, and purposeful humour from the reference decks. Conference/company branding and personal artwork belong in individual projects.

Quality and scope

Machine checks alone leave visual and factual review pending. Inspect the latest PNGs and sources, then use review:record with the hashes captured before review and actual page coverage/observations. status detects stale records when source, brief, outline, or sources change. Export includes those states and stays available for drafts. Live talk duration remains an estimate until rehearsed. See the review contract.

Follow image rights and credits for every supplied or selected image, including screenshots and backgrounds. Record the use basis and whether a credit is required in sources.md; inspect required notices in the audience HTML/PDF. Unknown rights or missing credits keep the deck unverified. These are reviewer checks, not an automatic legal clearance by the build scripts. Generated projects include the same guide. licenses/README.md explains the licence scope; licenses/ras/MIT.txt retains the standard MIT licence for the included RAS tools and templates. The speaker chooses terms for their own content. Build/export preserves the directory in dist/licenses/.

ras:remember saves an explicitly requested preference in the selected project's ignored .ras/memory.json. ras:retro proposes lessons from the actual session and saves the candidates the user selects. Relevant saved entries guide later operations without overriding the current brief. No home-directory memory store is read, and memories are not included in slide exports. See project memory.

First-version scope: new talks, revision, review, and HTML/PDF export. Legacy sample conversions validate the style; bulk migration of the three old talks is deferred. The starter theme bundles pinned Noto Sans TC Variable for Taiwanese Mandarin written in traditional characters, including headings and code comments. Mermaid embeds its label fonts. Other scripts and custom branding can supply project-local fonts and licences. See Marp authoring.

Repository source excludes historical slide excerpts, character artwork, employer logos, third-party memes, and font files. Keep reference fixtures outside this repository; dependencies and generated output are ignored. Font packages are installed as dependencies and their notices are retained in generated output. npm run validate checks staged blobs, tracked working copies, and non-ignored untracked files against a source-path allowlist and requires regular UTF-8 text files. Unknown formats/directories, binary content, and symlinks are rejected, including unstaged edits to tracked files. Deleted working copies are still checked through their indexed content. Without Git metadata, source-file checks are explicitly reported as skipped; metadata and skill checks still run. File provenance still needs review.

See the first-version validation record for executed checks and the limits of model/host testing.

Development

npm ci
npm run validate
npm test
npm run test:mutation

GitHub CI runs these checks plus a standalone starter export on Ubuntu/macOS with Node 22.18.0 and 26.9.0. Pull requests run CI directly; pushes to main run the same CI before the version/release job. Conventional Commits drive version updates across the npm manifests and all three plugin manifests, a changelog, and a GitHub Release. See repository automation for setup, local commands, and release permissions.

The scripts use project-relative paths and a configurable browser. Behavioural tests cover source parsing, independent initialization, missing assets, and layout failure detection. Browser tests require an installed Chrome/Chromium.

Dependency overrides pin patched @xmldom/xmldom and align puppeteer-core with Puppeteer 25. See dependency pins and CVE references. Use the current generated reports as test evidence.

References

• Marp CLI
• Marpit notes and rendering
• Mermaid CLI
• OpenAI plugin packaging
• Claude Code plugins
• RAISE A SUILEN