Five ways to use a Capsule
Save what's worth saving.
A Capsule is one sealed HTML file that holds a snapshot — structured, readable, and built to outlast the tool it came from. An atomic unit of preserved work, ready to share, archive, or re-read years from now. Five use cases below; two commitments at the bottom make them last.
Use case 01 · The origin
Save the parts of an AI conversation worth keeping.
You finish a chat with Claude, ChatGPT, Gemini. You worked through a decision, found sources, weighed trade-offs, landed somewhere. The conversation matters. It will close. The canvas will mutate. The share link will rot.
A Capsule is what you save. Manifest with provenance (which model, what date, what conversation source). Data block with the structured content — decisions, sources, conclusions, open questions. Rendered HTML that reads on its own without the runtime. Integrity hash that proves the bytes haven't drifted.
One file. Drop it in a folder, attach it to email, hand it to someone who can continue the work. The model behind the conversation can change; the platform can disappear; the share link can break. The file still opens.
Use case 02 · File over app
Notes that outgrew markdown.
Markdown is excellent until you need a manifest, an integrity hash, embedded media, declared capabilities, or a runtime that actually does something with the content.
A Capsule is what notes become when they reach that point. The plain text is still there — rendered into the HTML at build time, readable in any browser. On top: structured fields the runtime can use. A decision table the reader can sort. References that copy as citations. Exports that produce JSON for downstream tools. An "about" panel showing where this came from.
The file is still one document; it opens like a webpage; it survives a copy / paste / email / share without dropping any of the structure. If you're already in the file-over-app school — Obsidian, Tana, plain markdown notes in a git repo — a Capsule is what an individual note becomes when it deserves more rigor than markdown can give it.
Use case 03 · Time-bounded snapshots
Capture a moment of work without a database.
You want to capture a moment of work — what you knew on this date, what you decided here, what was true then. The state of a property dossier on the day you took it to LOI. The shape of a research conclusion at week three. A bug investigation right before the fix shipped.
A Capsule packages it: structured data in a JSON block, human-readable rendering, provenance metadata, an integrity hash. No schema migrations, because the data block belongs to this snapshot — if next month's snapshot has a different shape, it's a different capsule. No database to maintain. No live query that might return different results tomorrow.
The cost is what a snapshot always costs: it doesn't auto-update. The benefit is what a snapshot always gives: it stays exactly the way it was when you sealed it.
Use case 04 · Offline, portable, self-contained
An app that runs from a thumb drive.
Put a Capsule on a USB stick. Hand it to someone. They double-click and it opens in their browser. No installation, no account, no internet. An interactive family photo album with navigation, EXIF / location views, face annotations. A reference manual that works in airplane mode. A small DAW with bundled stems and live mixing.
Capsules at tier 4 — the top of the interactivity stack — are full apps. They just happen to be apps that fit in a single HTML file with their data baked in. Open one in 2026 or 2035; if the browser engine still renders HTML and runs JavaScript, the app works. No backend, no API to maintain, no DLC to download.
The trade-off is the size budget (everything's inline, so the file is bigger than a typical webpage) and the lack of live data (it's a snapshot, not a service). Those are the same trade-offs PDFs make. Capsules just make them for richer content.
Use case 05 · Discovery + collaboration
Share with a domain-aware registry.
A Capsule is portable, but sometimes you want it discoverable — not just by people you email it to, but by everyone working in the same domain.
A registry like MinDev hosts capsules from people working in geological exploration. Each capsule keeps its integrity hash. Each gets a stable URL. Each can be discussed in conversations attached to it.
The format is hosting-agnostic — the same Capsule works on any host, on a thumb drive, in your email. Hosts add discovery and discussion; they don't change what the file IS. The host-vs-format split is documented in the hosting pattern for anyone building a registry in their own domain.
Why not just use…
Why not markdown, a notes app, a database, or a PDF?
vs Markdown
Markdown is great. We're not anti-markdown. But markdown has no manifest, no integrity hash, no embedded media, no structured data block, no declared capabilities, no runtime. Markdown is content with formatting; a Capsule is content plus structure plus provenance plus interactivity, packaged in one HTML file.
If you're in the file-over-app school, a Capsule is what a note becomes when it deserves more rigor than markdown can give it — and many capsule data blocks ARE compiled from markdown source.
vs A notes app
Notion, Obsidian, Tana, Apple Notes — those are working surfaces. You edit, link, restructure, iterate, leave things half-done. A Capsule isn't a working surface; it's a sealed output. The two layers complement; they don't compete.
You probably use both. Edit in your notes app of choice; emit a Capsule when something in there is finished enough to share or preserve, with provenance and integrity your notes app didn't carry. The Capsule is what one of your notes becomes when it leaves the editing layer for good.
vs A database
A database is for live, queryable, mutable data — what's true now. A Capsule is for a frozen snapshot — what was true then. The cost: it doesn't auto-update. The benefit: no schema migrations, no server to maintain, no live query that might return different results tomorrow, no account required to read it.
Use a database when you need the live state. Use a Capsule when you want to share or preserve a moment.
vs A PDF
PDFs were the previous answer to "portable finished work." They're closed, lossy, and not machine-readable. A Capsule gives the same role — portable, archive-able, single file — to HTML, which is open, programmable, re-readable, and inspectable.
PDFs are great for print fidelity. Capsules are great for screen-native, machine-readable, re-rendered, interactive content. Both serve "seal this and send it" — just for different content shapes.
Different problems, different formats. A Capsule is the answer when you want structured, durable, single-file, AI-readable — any one of those is what makes it different from any one alternative.
Why a Capsule lasts
Two commitments that make every use case above durable.
A minimum floor.
Even if JavaScript doesn't run — iOS QuickLook, email preview, screen reader, ten-year-old browser — the substance is in the HTML. The runtime is enhancement, not requirement. Apps when alive. Documents when dormant.
See the five tiers of capsule interactivity →A sealed boundary.
A Capsule's substance lives in the file. No network fetches. No live data. No external dependencies. If a "Capsule" depends on a server somewhere, it's not a Capsule — it's a web app or a live dashboard, which is a different category of artifact entirely.
See the capsule boundary →Together: the boundary makes the floor possible; the floor is what makes a Capsule honest about what it can promise.
What this is not
Four lines of fence-posting.
- Not an app pretending to be a document. A document that can wake up into an app.
- Not a standard you have to comply with. A loose discipline.
- Not anti-platform. Anti-context-loss.
- Not finished. Active research.
Go deeper
Three ways to read the project.
What I do with all the HTML I get from AI
First-person account of why this discipline exists — from copy-pasting between AI tools, through the Obsidian / plugin shelf, to landing on HTML as the substrate worth writing a contract for.
Read essay → Long-form explorationObservations · questions · answers
The full editorial walk-through with sourced quotes (Karpathy, Thariq, Kepano, htmlbin, html-docs, Workplane). Five observations, three questions, nine answers. Where the framing got worked out before this landing got stripped down.
Read the exploration → Research logF1 — F28 · methodology and findings
The empirical-pressure-driven spec evolution: what was investigated, what was observed, what was spec-changed in response. Includes producer-population reads, host-vs-registry distinction, the genre-tension resolution, and the upstream-feedback-discipline pattern.
Read the log →About this page
This page is itself a Capsule per Core v0.3.0. Five required blocks, all inline. No network, no analytics. v2 — forked from the original landing sketch; v0.3.0 applies the HTML Capsule design system.
Loading manifest…