What I do with all the HTML I get from AI

Just want to give you my journey here with AI tools. I've been using all the chat systems, chatgpt, claude web, gemini web.. and then more recently using more claude code CLI and codex CLI.. and now been using the Claude Harness/App and the Codex Harness/App.. but in any case, for the longest time, I was doing work in each, and then copying and pasting data in/out.. pasting it into other chats, pasting it into Google Docs or notes or obsidian.. trying to reliably get my info "out" of the AI systems and into a format that I can either archive or easily share with friends.

I know there's been the share button for these chats for a long time but something doesn't sit right with it for me. The chats either get lost for me, or I'm not confident or sure what version they're displaying, or if they're displaying the conversation all the way, or only at a certain point, or if they're still updating after the fact. I'm sure I could dig into the documentation on this and get a sense for it, but will it change? Will it ever be intuitive to me? I'm not sure it will. I'm also not sure that it will stay the same once I look into it, and I'm not sure that it's the same between all these systems. I'm also not sure that I can paste these links into other AI's or LLM's and have them evaluate it or work off it or build it. It's a mess.

Obsidian was another one of those.. I'd been using it for notes for a while, and honestly it's a great app, but I kept feeling like I was fighting markdown more than working in it. To get any of the nicer features — the rendering, dataview queries, themes — I'd be installing and configuring plugins, then updating them, then debugging when one broke after an Obsidian update. It felt brittle. The .md files were portable, but the experience that made Obsidian useful in the first place lived in a stack of plugins I had to keep babysitting. I wasn't sure what I'd actually saved.

Around then I came across Steph Ango's essay "File over app." Steph runs Obsidian, and the essay's principle is right — your work should live in files you control, in formats that outlive any specific app. But my struggle with Obsidian was the same principle taken one step further than I think the essay intends. The .md files were portable. The experience wasn't. The themes, the plugins, the rendered output all lived in the app, not the file. If I wanted my notes to look and behave the same in five years, the open file format alone wasn't going to do it.

Now, also, around the same time, they put out artifacts, and those were quite neat, but again.. didn't really know how to use them or put them into my workflow. When Claude Design came out, though, I knew something was different.. because it could give these beautiful and editable interfaces, and it could be downloaded as html or "handed off" to claude code for implementation. That was huge, because up until that point I was getting designs and throwing it into my claude code projects to try and get it to implement into my react-based apps and systems. But throughout here it's been a fight. It's been a fight between making and doing "work" inside of one system, and then getting it into a format that AI can natively talk to and work on and iterate on with me.

Putting things into HTML has been a huge shift for me. Even just with the chat conversations, I was always trying to get the data "out" by asking Claude or ChatGPT for a summary in markdown or to make me a PDF version. Or copying and pasting stuff into notes or word or Google Docs.. it never looked good. The only way I could get pixel perfect looking stuff is if I asked to do a react/html render and then use something like playwright to "print" to a jpeg or pdf.

For example, one thing I always do is make maps in QGIS that are jpegs or PDFs. I would constantly be going back and forth between the app and chat agents. I'm sure there is a way that I could have wired something up so that the codex or claude code CLI could have talked to QGIS and made edits, maybe through a database, but this is still so clunky. So I decided to try to create a sort of GIS system inside react (with Postgres on the backend and tools like GDAL) so I could get the exact interface I wanted.. but this started to get clunky too. Furthermore since I was trying to share content with other users.. stuff like maps, and tables, often related.. I was trying to bring a portal that connected up to my working react GIS system so I could share content with my end users (which would have usually been maps or excel tables, with no real provenance or unique identifiers other than file names and "v1, v2, v3" type stuff).

I was also really interested in Claude Design's ability to work with maps. Cartography. Like, it was a way of iterating through things so much faster than I could have previously done it with either illustrator or qgis.. So then it hit me.. why not embrace HTML for this? If Claude Design is using HTML as its substrate, then why don't I setup my work to be more friendly to that?

So I started doing that. Instead of trying to convert what Claude Design or Claude Code or any chat LLM was giving me into something else, I just kept it as HTML. But raw HTML by itself has its own problems. I still couldn't reliably tell what I was looking at — where it came from, whether it was complete, what version it was, whether the page would even render the same next month. The same things that didn't sit right about chat share-links didn't sit right about loose HTML files either.

So I started writing down what HTML would need to be to be trustworthy as an artifact — the same way a PDF is trustworthy as "this is what was sent, that's the file." First version of the rules was rough. Just: save it as one HTML file, put a small JSON manifest at the top naming what the file is and where it came from, don't reach out to the network so it works the same on disk as on a server, put the content into the HTML body so it still renders when JavaScript isn't running.

Then I started using it for real work — capsules of QGIS-style maps, capsules of chat conversations I wanted to keep, capsules of decision matrices, capsules of design systems Claude Design gave me — and stuff broke. A photo capsule rendered blank on iPhone because Claude had put the photo inside a <script> block and iOS didn't run inline scripts. A markdown export silently crashed because of a JavaScript newline bug. An LLM lied about where the data came from because the manifest field was too easy to make up.

Each failure became a numbered rule. Twelve so far, over about five weeks. The most important one is rule 12: render the content into the HTML at build time, don't make JavaScript do it at runtime. Capsules are archives, not apps. The whole point is that the file still works when nothing else does.

Today the format is a one-page spec (CAPSULE_CORE.md), a small Python compiler and validator with 26 conformance checks, and a working corpus across the kinds of stuff I actually do. The LLMs I use all produce conformant capsules when I paste the one-page spec into a system prompt — Claude, ChatGPT, Gemini, Codex. And it works in compilers I build too: Mintel, the mining-intel app I work on, is the first independent producer that validates clean at 26/26.

What I want for it: not much. It stays a research project. The spec rule for itself is "no addition without empirical pressure" — change it when real producers and recipients push on it, not when something sounds like a good idea on a Tuesday. If you have HTML artifacts piling up — from any AI tool that defaults to "save as HTML" — this might be useful. The spec is one page. The examples show what conformant capsules look like. The research log is where the iterations live.