Skip to content

lee-w/ras

v0.14.0

RAISE A SLIDE: turn briefs into rehearsable Marp presentations.

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.

Quick start with an AI host

Install RAS as a plugin in your AI host (see Use with Codex, Claude Code, or open models below), then ask for a talk: /ras:create a 15-minute talk on retries for junior engineers, or say the same thing in plain words. In a chat-only interface, run node scripts/ras.mjs prompt create --chat '…' and paste its output instead.

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.

CommandResult
npm run buildHTML and notes in dist/
npm run checkFresh build, automated checks, PNG previews
npm run exportChecks, then PDF with verified page count
npm run previewLocal preview at http://127.0.0.1:4173
npm run doctorNode/browser/config diagnosis
npm run statusCurrent machine/review states and stale evidence
npm run review:record -- <review.json>Record an actual visual or factual review
npm run memory -- listRead the selected project's saved preferences
npm run blogDraft a generic Markdown article in blog/index.md from slides.md; --screenshots, --out <dir>, --force

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.

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 above run inside an initialized presentation project.

Upgrade an existing deck

A deck keeps the RAS tools it was created with. To bring an existing deck's tools up to this repository's version, run from this repository:

node scripts/ras.mjs upgrade ../my-talk           # list changes only
node scripts/ras.mjs upgrade ../my-talk --yes     # apply them
cd ../my-talk
npm ci            # only when package.json or package-lock.json changed
npm run export

Without --yes (or with --dry-run) the command writes nothing; it prints the deck's current and new slide-kit versions and lists each kit file as added, updated, merged, or unchanged. Kit files are the files init generates as tooling: scripts/, package.json, package-lock.json, justfile, licenses/, README.md, and the copied guides. Kit files that differ from this version, including hand-edited ones, are replaced. Before writing, the command copies every file it replaces to .ras/upgrade-backup-<timestamp>/ and prints that path. ras.config.json and .gitignore keep your values and only gain missing entries. Content (slides.md, brief.md, outline.md, sources.md, review.md, theme.css, assets/, .ras/, dist/, and any other file) is never touched. If upgrade adds a new configuration key, the changed ras.config.json makes existing checks and reviews stale; rerun npm run check and redo the review. Directories whose package.json is not named @ras/slide-kit are refused.

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:blog, /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/, roles/, 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 routing in the root SKILL.md:

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 root skill's routing 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. Each operation expands only the references and roles it uses. Add --profile <path> to append a speaker profile such as profiles/wei.md as a final "Active profile" section. 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

RoleResponsibility
🎧 CHU²Decisive producer: brief, argument, coordination, completion
🎤 LAYERCalm writer: slide text, transitions, speaker notes
🎹 PAREOBright, attentive designer: theme, hierarchy, layout decisions
🎸 LOCKEarnest implementer: Marp source, builds, concrete repairs
🥁 MASKINGDirect, dependable reviewer: clarity, pacing, evidence, rendered pages, image rights

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.

Each role owns one set of deck files and a checkable deliverable; see the role table. Creation follows CHU² → LAYER → PAREO → LOCK → MASKING → CHU², with MASKING inspecting the rendered pages against PAREO's written layout decisions. 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 language follows the interaction rules. 🎧 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.

A speaker profile is your own Markdown file of preferences that hold across your decks; point a deck at it with profile in ras.config.json or pass --profile (see memory layers). The Wei profile is an example, not a default: it 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.

Every supplied or selected image follows image rights and credits; unknown rights or missing credits keep the deck unverified. 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 .ras/memory.json, which the deck's Git repository tracks. 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.

Documentation guide

DocumentContents
WorkflowRoles, operation routes, delivery, and where each rule lives
Marp authoringSlides, notes, themes, Mermaid, and local assets
Review and verificationMachine checks, visual/factual review, and record freshness
Image rights and creditsUse basis for supplied images, rightsholder credits, and final-output checks
Project memoryMemory layers, remember, retro, storage scope, and precedence
Wei profileAn example speaker profile, with its style study and legacy deck format notes
DevelopmentLocal checks, CI, versions, and releases
DependenciesPinned versions, CVE notes, and fonts
Validation recordExecuted checks, historical evidence, and testing limits

Development

npm ci
npm run validate
npm test

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