name: fireworks-open-eli5 description: Create evidence-aware, interactive visual explainers as self-contained offline HTML. Use when a user asks to explain a concept, repository module, engineering tradeoff, or incident with a diagram, walkthrough, ELI5 treatment, data/request trace, failure view, or teach-back. Do not use for a plain short answer, ordinary prose rewrite, generic website implementation, or unsupported claims presented as facts. license: Apache-2.0 compatibility: Codex, Claude Code, or another Agent Skills-compatible host with Node.js 18+ and local file access; no npm packages or network access required at render time. Native Pages export optionally requires macOS and Apple Pages.

Fireworks Open ELI5

Turn a difficult system into a truthful visual story. Produce a portable JSON spec first, then a deterministic, self-contained HTML explainer.

Non-negotiable boundary

• Evidence comes before visual polish. Label every evidence item verified, inferred, or analogy.
• Never make an analogy look like implementation truth.
• A generated local HTML file is only generated. It is not published, uploaded, sent, or destination-verified.
• Do not publish, upload, send, or change access without the user's explicit request and the destination workflow's own verification.
• Rendering performs no network calls. A cited URL is a reader-facing link, not a runtime dependency. The optional native Pages action may call only the bundled same-origin helper on 127.0.0.1; it must never contact a remote service.
• Browser-local history, favorites, and annotations are disabled until the reader opts in. They are convenience state, not evidence and never modify the source spec or generated artifact.
• Describe history precisely as same-origin explainers previously opened in that browser. Never claim that it enumerates every generated file.
• PDF export invokes the browser print dialog. PNG exports one scene; PPTX and Pages-compatible DOCX export one scene per slide or page. Native .pages output is allowed only after the installed Pages app really saves it; never rename a DOCX to .pages. Generated downloads are local artifacts only.

Workflow

1. Identify the audience, question, language, and one thing that should travel through the story: a request, packet, decision, event, or user action.

2. Choose exactly one story grammar:

   • concept: intuition → mechanism → boundary.
   • module: entry point → transformations → outputs/dependencies.
   • tradeoff: shared goal → competing options → consequences/decision rule.
   • incident: normal path → break and propagation → detection/recovery.

3. Gather evidence. For repository work, inspect actual files and use local paths. For external claims, use authoritative sources when available. Record uncertainty explicitly.

4. Create a version 1 JSON spec following references/spec-contract.md. Use 3–7 scenes, 2–6 nodes per scene, a complete truth ladder, trace, glossary, teach-back, evidence map, and the required mode-specific modeData. Add failure information to consequential nodes.

5. Validate before rendering:

   node scripts/validate.mjs path/to/spec.json
   

6. Render to a new local file:

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   The renderer refuses an existing path. Only when the user explicitly wants to replace a known regular file, append --force. Forced rendering uses an atomic replacement and still refuses symbolic links and non-file paths.

7. Validate the spec and artifact together:

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. When browser access is available, inspect the local artifact at desktop width and 390px. Confirm one h1, readable labels, no horizontal overflow, keyboard focus, independent tablists, global and scene-local playback, viewport following, active real-edge and evidence-card synchronization, enter/hold/exit animation phases, failure lens, answer reveals, and zero remote resource requests. Every scene evidence card must expose its status, concise core basis, support scope, and a URL or explicit no-locator boundary.

9. Exercise the reader workspace: open and dismiss the modal drawer by mouse and keyboard; confirm focus return; enable the library intentionally; reload and verify favorites and a plain-text annotation; and confirm history contains only same-origin explainers that were actually opened. Use a markup-shaped annotation to verify it stays inert text.

10. Exercise export: confirm the print stylesheet, PNG signature and dimensions, PPTX and DOCX ZIP signatures and required OOXML parts, and the fallback download link when automatic downloads are suppressed. Visually confirm that scene artwork includes a bounded evidence footer with status, core basis, and source locator or boundary. When native Pages is in scope, run through scripts/serve.mjs, verify the .pages package contains Index/Document.iwa, then reopen it in Pages. Fix the spec or template and rerun both validators after any change.

Report language

• Write the final QA, status, handoff, and generated-artifact report in the language of the user's latest substantive request by default.
• An explicit report-language request overrides that default.
• spec.language controls the generated explainer interface only; it does not force the conversation report language.
• In mixed-language conversations, ignore short acknowledgements when choosing the report language. Preserve code, commands, paths, identifiers, exact errors, and source titles when translation would reduce precision.

Read references/reporting.md for the full language selection and delivery-report contract.

Story construction rules

• Write the title as a concrete promise, not a category label.
• Keep the summary to one sentence and every node to one responsibility.
• Prefer 3–5 scenes. Use 6–7 only when omitting a stage would distort causality.
• Edges are relationships or actions. Use short verbs on labels.
• The trace must visit real node IDs in a meaningful order.
• Use failure data only when impact, visible symptom, and fallback are known.
• Keep the simple layer accurate enough to survive the technical layer.
• Put limitations in truthLadder.caveat, not in tiny disclaimers.
• Use source IDs on the scenes or nodes they support.
• Do not cite a source merely because it is adjacent to the claim.

Read references/story-grammars.md for mode patterns, references/evidence-rules.md for claim boundaries, and references/visual-system.md before changing the renderer's visual language. Read references/library-and-export.md before changing persistence, navigation, playback, or export behavior.

Quality gate

The work is ready as a local artifact only when:

• the validator returns ok: true for the spec and rendered HTML;
• all IDs and references resolve;
• every required interactive section has content;
• the selected story mode passes its own semantic contract;
• the HTML is deterministic and carries the spec SHA-256 meta tag;
• the artifact byte-matches the supplied spec and uses trusted CSP hashes;
• the artifact has no external resources, unsafe runtime APIs, or remote fonts;
• persisted reader state is opt-in, namespaced, bounded, same-origin, and kept outside the deterministic spec hash;
• annotations are rendered only as text and cannot create executable markup;
• global and local playback share one state machine and never run together;
• each trace step activates the real outgoing relationship path (or a sink's incoming path), keeps label and arrow state aligned, and highlights only the evidence that supports that step;
• scene evidence cards preserve verified/inferred/analogy boundaries and expose core text plus an actionable locator without fetching remote previews;
• scene PNG, PPTX, and DOCX packages have the expected signatures and structure and contain their evidence footer; a claimed native Pages export has also reopened in Pages;
• mobile uses the stacked flow rather than shrinking the desktop SVG;
• the final report follows the user's current interaction language, names the generated spec and HTML paths, and says whether desktop, mobile, persistence, playback, evidence, and export browser QA were run.

If evidence is incomplete, generate only when the evidence map and caveat make the gap unmistakable. Otherwise stop and report the missing evidence.

English · 简体中文

An open, portable Agent Skill for turning difficult systems into truthful, interactive visual stories. It compiles a versioned JSON story spec into one deterministic, self-contained HTML file that works offline.

The project combines an ELI5 layer with inspectable technical truth: readers can follow a real request or event through the system, inspect the evidence behind each conclusion, explore failure behavior, annotate scenes, and export the result without sending source material to a remote runtime.

A generated Chinese scene showing the graph, local actions, and conclusion-level evidence together.

Why it is different

• Truth Ladder — separates analogy, technical mechanism, and caveats.
• Evidence at the claim — each scene can show source status, core text, support scope, and a URL or explicit no-locator boundary.
• Four story grammars — concept, repository module, engineering tradeoff, and incident, each with a dedicated summary view and semantic validator.
• Detailed playback — global or scene-local traces animate real nodes, relationships, labels, arrow markers, evidence cards, and enter/hold/exit phases while keeping the active scene in view.
• Failure lens and teach-back — impact, symptom, fallback, questions, and answer reveals are part of the explainer rather than an appendix.
• Reader workspace — opt-in same-origin history, favorites, plain-text annotations, and keyboard-accessible scene navigation.
• Local export — PDF, scene PNG, all-scene PPTX, Pages-compatible DOCX, and optional verified native .pages conversion.
• Portable by construction — no runtime packages, remote fonts, remote resources, or network access during render.

Requirements

• Skill runtime: Node.js 18 or newer and local file access.
• Package dependencies: none. There is no npm install, Python runtime, remote font, or remote rendering service.
• Rendering: no browser or network connection is required.
• Reading and export: use a modern browser for the interactive HTML and local PDF, PNG, PPTX, or DOCX export.
• Optional native .pages export: macOS, Apple Pages, and the bundled loopback helper.

The installer and the installed Skill have separate requirements. The skills@1.5.23 CLI used by the release canary requires Node.js 22.20 or newer; the installed Skill still runs on Node.js 18 or newer. Installation needs one-time access to the public GitHub repository; the npx route also needs the npm registry. A public install needs no GitHub account or token.

Install

Natural language (recommended)

Paste one of these requests into your agent. It should inspect SKILL.md, refuse to overwrite an existing installation without permission, and report the final location.

Codex

Install the fireworks-open-eli5 Agent Skill globally from https://github.com/yizhiyanhua-ai/fireworks-open-eli5 using Codex's Skill installer. The repository root (.) is the Skill directory and its installed name must be fireworks-open-eli5. Review SKILL.md first, do not replace an existing copy without asking, verify the installed path, and tell me whether I need a new Codex task before using it.

Claude Code

Install the fireworks-open-eli5 Agent Skill globally for Claude Code from https://github.com/yizhiyanhua-ai/fireworks-open-eli5. Review SKILL.md first, use the Agent Skills CLI when available, and do not replace an existing copy without asking. If the installer requirement is not met, report it without changing my Node.js installation. Verify that Claude Code can discover the Skill and report the installed path.

Install with npx

The open Agent Skills CLI supports both Codex and Claude Code:

# Codex
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -y

# Claude Code
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a claude-code -y

# Both agents
npx skills@latest add yizhiyanhua-ai/fireworks-open-eli5 -g -a codex -a claude-code -y

-g installs at user scope. Remove it for a project-local installation. Check the result with npx skills@latest list -g --json, then start a fresh agent task so the Skill is rediscovered. Review Skills before using them: they run with the permissions of the host agent.

Quick start

node scripts/validate.mjs assets/example-spec.json
node scripts/render.mjs assets/example-spec.json example.html
node scripts/validate.mjs assets/example-spec.json example.html

The commands print compact JSON and exit nonzero on failure. Rendering is create-only by default. Use --force only to intentionally replace a known regular file; symbolic links are always rejected.

Run the complete contributor and distribution gate:

npm run check

This checks JavaScript syntax, focused tests, the canonical example, release package contents, and a render/validate canary from an unpacked archive.

On Node.js 22.20 or newer, also exercise an isolated Codex and Claude Code installation through the pinned Agent Skills CLI release:

npm run check:agent-install

Use as an Agent Skill

After installation, ask for an evidence-aware visual explanation, for example:

Explain how one queued job moves through this repository. Cite real files, let me play the request path, and show what breaks when the lease expires.

Read SKILL.md for the agent workflow and references/spec-contract.md for the version 1 story spec.

Story pipeline

question + audience + evidence
            │
            ▼
  versioned JSON story spec
            │ validate
            ▼
 deterministic HTML renderer
            │
            ├── offline interactive explainer
            ├── print / PDF
            ├── current-scene PNG
            ├── all-scene PPTX
            ├── Pages-compatible DOCX
            └── optional native Pages conversion

The JSON spec is the portable source of truth. The HTML contains its canonical SHA-256, and the validator can byte-compare a supplied spec against a fresh deterministic render.

Reader workspace

Every explainer has a directory drawer. Favorites appear first, followed by independent tabs for the current outline, previously opened explainers, and annotation browsing. A reader can play, favorite, annotate, or export one scene without starting the global trace.

The local library is disabled until the reader selects Enable local library. It records only explainers actually opened at the same scheme, host, and port; it never scans the filesystem. Favorites and annotations are browser-local, unencrypted, and removed when that origin's browser data is cleared. They never modify the source JSON or generated HTML. file:// and unavailable storage degrade to an in-memory session.

See references/library-and-export.md for the persistence, privacy, accessibility, playback, and export contract.

Export

PNG, PPTX, and DOCX are built locally in the browser without third-party libraries. Native Pages conversion is never faked by renaming a DOCX. Serve a trusted explainer directory with:

node scripts/serve.mjs --root /absolute/path/to/explainers --port 8772

The helper binds only to 127.0.0.1, verifies exact origin and a rotating process token, bounds and validates the generated DOCX/PNG structure, serializes conversion, and cleans task-specific temporary files. These controls protect the browser action from cross-site requests; they are not authentication against other local processes.

Security and privacy

The renderer reads local files and writes one local file. Generated HTML uses a hash-whitelisted Content Security Policy, embeds no remote resources, and contains no XHR, WebSocket, eval, or HTML-string DOM insertion. Its only connection is a user-initiated same-origin request to the optional loopback Pages helper. Cited HTTP(S) URLs are ordinary reader-facing links, never runtime dependencies.

Annotations are capped and inserted as text. The validator rejects unsafe source URLs, external resources, runtime tampering, spec-hash drift, and unexpected CSP hashes. See SECURITY.md to report a vulnerability.

Project map

• SKILL.md — agent workflow and delivery boundary
• assets/example-spec.json — complete Chinese DNS example
• assets/explainer-shell.html — offline visual and interaction shell
• scripts/render.mjs — deterministic renderer
• scripts/validate.mjs — spec and output validator
• scripts/serve.mjs — loopback-only native Pages helper
• references/ — evidence, grammar, visual, reporting, workspace, and export contracts
• evals/ — task-quality and trigger evaluation prompts
• tests/ — Node built-in tests and adversarial fixtures

Contributing

Read CONTRIBUTING.md, then run:

npm run check

The release package uses an explicit allowlist and keeps private: true to prevent accidental npm publication. This repository is intended to distribute an Agent Skill, not an npm runti