Despite running markdown.org, I don't think Markdown is a great format because it's a mix of slightly incompatible standards and ad-hoc extensions and doesn't support interactive components. For planning and documentation HTML is a far superior tool.
The browser is a great tool for viewing text-like formats, and way less annoying than the IDE's built-in Markdown preview. Static pages running directly off file:/// are great for cross-linking and creating navigation, and you can embed interactive components, built on the fly, right in the page.
All the planning and research for the Frenzi application went into a folder of static HTML pages written by AI agents, and I started a second one, the Playground, for my own experiments. This is how that system evolved and what it can do.
The research directory
Each day gets a folder named by its date, and each page in it gets a number and a title. Every folder has a small index page listing its pages, and the front page of the whole thing links to all of them.
research/
├── index.html
├── 20260122/
│ ├── index.html
│ ├── 20260122 - 0003 - Database Diagram Web Component Prototype.html
│ └── 20260122 - 0004 - Voice Edit Panel Web Component Prototype.html
├── 20260123/
│ ├── index.html
│ ├── 20260123 - 0005 - PDF Export for Docs Widgets.html
│ └── 20260123 - 0006 - Diagram Editor Web Component Plan.html
└── ...
docs/
├── stylesheet.css
└── scripts/
├── voice-edit-panel.js
├── pdf-export.js
├── diagram-editor.js
└── ...
Every page follows the same template: a <base> tag pointing back at the root so that every page can use the same paths, one stylesheet, the same handful of scripts, then a title, a breadcrumb, one intro paragraph and the sections. The last section of each page is a record of the prompts that created and updated it.
<base href="../..">
<link rel="stylesheet" href="docs/stylesheet.css">
<script src="docs/scripts/voice-edit-panel.js"></script>
<script src="docs/scripts/pdf-export.js"></script>
<script src="docs/scripts/notifications.js"></script>
<script src="docs/scripts/contents-widget.js"></script>
<script src="docs/scripts/link-popup.js"></script>
None of this needs a build step. The rules for it all live in the agent's rules files, so you can just ask for a page about something and it lands in the right folder with the right name, and everything that links to it gets updated.
The index
The front page is the most important page. It starts with a search box, then the favourites, then a section for each day, newest first. Each day is a grid of cards, one per page, with the page's title, a two or three sentence description, and links straight to its main sections. Each day's section can show as cards, as a plain list, or be hidden, and it remembers which.
The search works off an index of every page, with keywords, kept in the front page itself. The agent is told to look through the same index before starting a new task, so it finds the research that's already been done instead of repeating it.
Favourites and topics
Favourites are organised by topic. Saying "favourite this in Tools" puts the page in the Tools list, which is a coloured card at the top of the index, and the page's own card further down gets the same colours and a star, as does its title. New topics get a new colour pair from a palette written in a comment on the index page, so the agent can make one up when you ask for it.

In-page editing
The first component was for editing. An "Edit with voice" button sits in the top corner of every page, and clicking it pops up a panel with a prompt in it. With Listen ticked you just talk, and the dictation is added to the prompt. Select some text on the page and it's added as a quoted block, ready for you to say what should change about it.

Pressing Copy gives you a prompt that you paste into an AI agent, which then edits the HTML.
This is a set of instructions for editing the page: research/20260122/20260122 - 0004 - Voice Edit Panel Web Component Prototype.html
Date: January 22, 2026
Location:
file:///.../research/20260122/20260122%20-%200004%20-%20Voice%20Edit%20Panel%20Web%20Component%20Prototype.html
Edits:
Move the demo section up so it comes straight after the overview.
Below are quoted blocks from the page with instructions for what to change.
----- QUOTED TEXT (from page) -----
The quick brown fox jumps over the lazy dog.
----- INSTRUCTIONS (for quoted text) -----
Change this to a sentence about a cat, and make it bold.
This enables rapid iteration, because you can select parts of the page and then say what the change you require is. Combined with dictation, it lets you stay in the zone and focus on the content, rather than switching between thinking about the content and thinking about HTML markup.
Components
I quickly realised that there was the potential here to make interactive components embedded in the page. To keep the architecture clean, each could be its own self-contained JavaScript file, along with a way of embedding it in the page.
The diagram editor is a good example. It draws rectangles, circles, lines and text, which you can drag, resize and edit the properties of, with snapping to guides, panning and zooming.

The script goes in the head, and the diagram itself is a call placed in the page where it should appear, holding everything about the diagram as a plain object. Each embedded component gets a layoutKey which is unique to it.
<script src="docs/scripts/diagram-editor.js"></script>
...
<script>
DiagramEditorRenderHere({
"layoutKey": "20260123-0006-diagram-editor-example",
"title": "Diagram editor example",
"width": 980,
"height": 560,
"padding": 28,
"pan": {
"x": 34,
"y": 57
},
"zoom": 0,
"snapEnabled": true,
"snapThresholdPx": 8,
"shapes": [
{
"id": "rect-1",
"type": "rect",
"props": {
"centerX": 260,
"centerY": 220,
"width": 240,
"height": 160,
"cornerRadius": 10,
"fillColor": "#dbeafe",
"borderColor": "#0f172a",
"borderThickness": 2,
"optionalGradient": "#3b82f6"
}
},
...
]
});
</script>
Copy prompt
The workflow I already had was making edits in the page, copying the prompt, and pasting it into an AI agent to actually update the HTML. I continued that here: if you make any changes in the diagram editor, a Copy prompt button appears, and the prompt it copies describes the changes, with a command to embed them back into the page.
This is a set of instructions to edit this page.
Target page:
research/20260123/20260123 - 0006 - Diagram Editor Web Component Plan.html
Component:
DiagramEditorRenderHere (layoutKey: 20260123-0006-diagram-editor-example)
Edits:
Update the inline DiagramEditorRenderHere({...}) call for layoutKey '20260123-0006-diagram-editor-example' to use this updated configuration object (shapes array, pan/zoom, snap settings).
New configuration (paste this over the existing object literal):
{
"layoutKey": "20260123-0006-diagram-editor-example",
"title": "Diagram editor example",
"width": 980,
"height": 560,
"padding": 28,
"pan": {
"x": 34,
"y": 57
},
"zoom": 0,
"snapEnabled": true,
"snapThresholdPx": 8,
"shapes": [
{
"id": "rect-1",
"type": "rect",
"props": {
"centerX": 300,
"centerY": 220,
...
So the page stays the only copy of the diagram. The editor never saves anything itself; the agent puts the new version into the HTML, and the next time the page loads, that's what you see.
A page about each component
To keep things organised, and to have something the agent can refer to when it needs to use a particular component in a page, I found the best thing to do was to use the system itself to make a page about the component. That page has a demo of the component, an explanation of its architecture and data formats, and how it is embedded in a page. It was also where I could review and refine the overall structure and data formats, and iterate on those before starting to use the component in earnest on other pages.
There were times when a component needed to be enhanced after it was first made. To keep things consistent, I would generally update the page about the component, and if necessary all of the instances of the component in other pages, at the same time, because you want them to stay aligned.
Where there's a larger improvement, making a new version of the component may be the appropriate path, or at least making a new page about the updates to get them refined, and then going through and updating the component on each of the pages it's embedded in.
Pop-ups
Pop-ups were something I added just for fun, but they turned out to be really useful. The pop-up component adds a small button next to every link, which opens the linked page in a window over the current page instead of going to it. You can also drag a link onto the page to open it in a pop-up.
The windows can be moved, resized, zoomed, and popped out into a real browser window. When they are minimised, they live in a tray in the bottom right. The pop-ups on each page are remembered in local storage, so when you come back to a page, the pages you had open next to it are still there.

The pop-ups have their own Copy prompt buttons too, which ask the agent to make the open windows a permanent part of the page, so that a page about some work can open with the pages it depends on already beside it.
PDF download
On the diagram editor I added a PDF download button. After experimenting with the jsPDF library, I decided to instead just embed PDF generation directly into the component, because the basic PDF format is not that difficult to write.
Then I wanted a PDF download for the page itself, and this required more thought. The end result was that the PDF rendering became its own component, which goes through the page, and because the HTML is simple and standard, it can read the markup of the page and add the correct things into the PDF: headings, text, tables and code. Tabs come out one after another, each under its own heading, and anything marked data-pdf-exclude, like the pop-up buttons, is left out.
Because I already had the PDF generation for the diagram editor, I could build on it, moving the diagram-to-PDF code into the main PDF download component. All the components then got an interface which produces a version of what the component is showing in the diagram editor's format. So effectively each component can produce a diagram version of how it looks, and the PDF generation for the page just asks each of the components embedded in the page how it would display in the PDF, as a diagram.
var diagramData = {
title: title,
width: diagramWidth,
height: diagramHeight,
shapes: shapes
};
container.setAttribute("data-pdf-diagram", JSON.stringify(diagramData));
This doesn't have to look exactly the same as it appears on screen, as long as the information is there and it looks pleasant, because the diagram format doesn't have a hundred percent parity with what an embedded JavaScript component can do in a page.
More components
Here are some of the other components, each with its own page about it.
In the research directory
- Database diagram - tables and relationships, with dragging, zooming and an optional physics layout
- State diagram - states and the transitions between them
- Network flow diagram - entities left to right, with rows of messages between them
- Tree diagram - a hierarchical table with columns and expandable rows
- Schedule grid - a schedule of developers and tasks with their dependencies
- Test runner - in-browser tests showing pass, mismatch and error
- UI preview - Frenzi's own reactive UI components running live in the page
- Theme editor - an interactive editor for Frenzi's UI themes
- Search - full-text search with saved searches and filters for dates and favourites
- Contents - a table of contents built from the headings, in a resizable panel on the left
- Notifications - errors and status messages from every component in one place (see Notifications below)
In the Playground
- Mandelbrot Explorer, Game Of Life Player and Graph Plotter
- Chess Game App, with legal moves and a small built-in engine
- Drum Machine and Piano Roll
- 6502 Emulator and Basic Interpreter
- Video Crop Tool, Painting App and Floorplan Editor
- Windowing Environment - a desktop running many of the others in windows
Towards an "operating system"
The components started out needing a small amount of local state, for example which view was selected. That's easy enough with local storage, using a unique key for that instance of that component on that page.
research-index-section-february-12-2026 list
research-index-fav-panel-planning scroll
diagram-editor-height-20260123-0006-diagram-editor-example 560
contents-widget-/.../research/20260123/20260123 - 0006 - Diagram Editor Web Component Plan.html-width 260
The key starts with the name of the component, then says which instance it is: the day section or topic on the index, the layoutKey of an embedded component, which by convention starts with the page's date and number, or the path of the page itself.
However, as more components were added to the pages, they needed to work together, and some standards had to come in. This took a few iterations to get right. Each iteration meant grinding through all of the existing pages that used components, updating them and their markup to conform to the evolving standard, before it settled down. In the end there was:
- A consistent standard for the markup, so that components can read the page. The PDF download is the main example: it builds the PDF from the page's own headings, text, tables and code.
- A standard for components to save their own local data within the page, without clashing with each other.
- A way for components to check which other components are available, if they need to use features from them.
- Shared areas on the page that components register with when they need interactive parts. The top corner is the obvious one, with the buttons for editing with voice, downloading a PDF and the notifications.
The top corner
The set of buttons in the top corner started out with just the voice editing, but more started to appear, for example the PDF download for the page, and the notifications. At this stage you either position the buttons absolutely and hope for the best, or you have some system for multiple components to cooperatively share a resource, which lets those components register their needs. Here that means asking for a button to be displayed in the top corner, and the system adds the buttons next to each other as they are registered.
if (!window.DocsTopRightTools) {
window.DocsTopRightTools = {
EnsureContainer: _ensureTopRightToolsContainer,
Mount: _mountTopRightTool
};
}
var mount = window.DocsTopRightTools.Mount;
var host = mount(_PDF_EXPORT_BUTTON_ID);
if (!host) return;
Working together
There are a few things that make the components work together:
- A common way of embedding them - one script, and a call placed in the page with a
layoutKeyand a plain object describing it. - Checking whether other components are there - and adding facilities from them if they are. For example, the PDF download button only appears on the individual embedded components if the PDF download component is in the page, and the voice editing prompt lists the open pop-ups if the pop-up component is in the page.
- Sharing resources - which can be done to a certain degree by cooperative naming, for instance making sure that your local storage name is not going to clash with anyone else's.
if (typeof window !== "undefined" && window.PdfExport) {
const pdfButton = document.createElement("button");
pdfButton.type = "button";
pdfButton.textContent = "Download PDF";
...
Part of it is having very loose coupling: if you would use another component and it is not present, you should still work, just without that feature. If the top corner doesn't exist, the notifications don't try to register a button there.
There are a few other shared resources too. The windows stack in agreed layers, with the top corner above the page and the pop-ups above that. Dropping things on the page goes through a registry, where each component says what kind of thing it accepts and with what priority, so the pop-ups taking dropped links don't stop another component from taking dropped files. And the notifications are a shared place for any component to report errors, rather than each one inventing its own.
Notifications
The notifications component puts a bell in the top corner with a count, and opening it lists every notification with its type, the component it came from and when it arrived. Components send to it through a small API, checking first that it's in the page:
if (window.PageNotifications) {
PageNotifications.Error('TestRunner', 'test-1', 'Test failed', 'Expected 3, got 2', container);
}
The page content can report too, with no script at all. Any element can carry a data-page-notification attribute holding the type, a short text and the details, and the component picks them all up when the page loads. That makes it a natural fit for task lists: each task that's done reports a success, each one still to do reports an error, and the bell shows how much is outstanding.
<tr data-page-notification='{"type":"error","component":"Tasks","item":"task-6","text":"Write Building tools in bulk","details":"Not done: the stub is live and waiting for dictation."}' style="background:#fef2f2;">

Like the other components, the panel has a Copy prompt button. It turns the notifications into a prompt for an AI agent, so a page of failing tests or unfinished tasks becomes a list of things for the agent to work through, and "Errors only" narrows it down to the problems.
Keeping things consistent
At the time, the AI agents were not so good at keeping things consistent, so that's one of the things I kept having to ask for: to remember to make the intermediate index pages for each date folder, to add the card on the front page, to keep the card's links in step with the page's headings, and to star a favourite everywhere it appears.
Most of that went into the rules files, but it also helped to put the instructions where the agent would be looking at the time, as HTML comments in the pages themselves, telling it to copy them into any page it makes.
<!--
═══════════════════════════════════════════════════════════════════════════
VIRAL INSTRUCTIONS - Update research index card when H2 headings change
═══════════════════════════════════════════════════════════════════════════
**AI AGENT**: These are VIRAL INSTRUCTIONS - copy them into any research HTML file you create or edit.
**AI AGENT**: This document must have a navigation card on `research/index.html`.
The card’s bullet links MUST match this document’s top-level `<h2 id="...">...</h2>` headings
(text + `#id`, same order).
**AI AGENT**: When editing this document, if you add/remove/rename/reorder any `<h2>` section or change
any `<h2>` `id`, you MUST immediately update this document’s card in `research/index.html` to match.
-->
What I also found was that the index page started getting quite long, with a couple of hundred cards after a few weeks. That means every so often you want to start a new research directory rather than letting this one go on forever. Because everything is self-contained in one folder, the rules files, the stylesheet, the scripts and the index, starting a new one is a matter of copying the folder and clearing out the date folders. The Playground began that way, and when the research directory gained new components, a page in the Playground worked out how to bring them across.
Running locally
Running completely locally, just from the file system, in general works great, but there are a few things to watch out for.
I did not want to require a small server to be run, so that means we cannot use things like fetch(). If you want anything that loads local data, you have to make a JavaScript file that you can include, which puts the data into a global variable or calls a function which is available. You cannot just have raw JSON data and expect to be able to load it from the file system within a page.
window.Dictionary = byLen;
window.DictionaryMeta = {
name: "placeholder-mini",
note: "Replace scripts/dictionary-scowl-7.js with a generated SCOWL dictionary for real gameplay."
};
})();
The search index is the same idea: it's a JavaScript array written into the front page itself.
Browsers also differ in how they treat local storage for file:/// pages, which is one more reason for every key to say which page it belongs to. And microphone permission isn't remembered for a local file, so the voice editing panel warns you, and you can still type, or use the operating system's own dictation.
Multi-user
I run this through Git, which works just fine for having multiple users in most situations.
A future direction will be to allow this to run through cloud storage, which will need some reorganisation. It will have to act more like a CRDT, with each user having a separate set of files, and the end result being those files combined in some way in the browser, so that people don't step on each other's work.
See also
- My AI workflow in 2026 - coming to trust AI agents with real work, and where planning in HTML fits in