Fireworks Open ELI5

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 runtime library.

License and attribution

Apache-2.0. See LICENSE and NOTICE.

Fireworks Open ELI5 is an independent implementation inspired by the Anthropic
community eli5 skill and is not endorsed by Anthropic.