Explanations as real pages, not markdown dumps.
artoo generates and manages artifacts: self-contained HTML mini-sites that pair presentation with the research backing it — and knows how to ship them.
There's a growing practice of getting explanations of systems out of LLMs as navigable sites with diagrams and provenance, and of composing reports from multiple assets. artoo is the tool layer for that practice.
What an artifact is
An artifact is a directory marked by an artifact.toml,
living inside whatever repo owns it — a library's explainer lives in
that library's repo, and one repo can hold many artifacts. The
publishable site/ renders from a file:// URL:
vendored assets, system fonts, no bundler, no CDN dependencies.
Get started
uv tool install artoo-artifacts # the command is `artoo`
artoo init site/my-report --kind report --title "Q3 systems report"
artoo status site/my-report
artoo deploy site/my-reportWhat it does
Deployment-aware
Reads your repo's actual GitHub Pages configuration — legacy /docs, Actions workflow, or branch — and routes accordingly. Also ssh/rsync named targets and arbitrary publish commands. Secrets never enter the repo.
Site libraries
Shared components are vendored into each artifact with
name + version + hash recorded in the manifest: self-contained
forever, upgraded deliberately with artoo lib update.
Form follows the evidence
Choose an article, explorer, collection, or deck independently of what the artifact is about. Markdown collections gain deterministic navigation; explorers gain declared search, filters, URL state, and downloads without rebuilding the same controls.
Decks, not styled articles
--kind presentation stamps a working deck on the
built-in artoo-deck library: acts, speaker notes,
landscape print. Structure comes from the markup, and with
JavaScript off it still prints whole.
Repo explainers
artoo generate explainer inventories a repo
deterministically, fans per-area analysis out to a cheap worker,
synthesizes narrative with a strong one, and assembles a multi-page
site with diagrams and a colophon.
No API keys
Generators delegate to agent CLIs you already have —
codex for analysis fan-out, claude for
synthesis. artoo core makes no model calls and holds no keys.
Research stays with the piece
A provider-neutral evidence projection carries source and claim custody into the page. Flip remains an optional adapter; private working material stays behind the publish firewall either way.
Plugins
Generators, deploy adapters, and site libraries are entry-point plugins. The ecosystem grows in separate repos; the core stays small.
Honest by construction
Every generated page carries a colophon: when it was built, from which commit, with which workers. An explainer is a dated snapshot of a moving system, and it says so. Deterministic facts (size, layout, history) come from a no-model inventory pass; narrative traces to per-area analysis briefs kept as research backing.