artifact generator & manager v0.1.0 alpha

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-report

What 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.

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

Generator runs are recorded as reporter's-notebook sources and claims (via flip) or plain markdown logs — behind the 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.