From README to architecture: reading a connected project
Explore an original fictional project through its specification, architecture, plan and decision log.
Read the articleTHE READING SIDE
Markdown, local files, and the reading side.
Reading projects, reviewing agent documents, and keeping context. Practical examples and reference files from the people building Aero Markdown.
FEATURED STORY · 4 MIN READ
From README to architecture: reading a connected project
Explore an original fictional project through its specification, architecture, plan and decision log.
Read the storyA FEW THINGS TO READ
From the journal.
A closer look at the files and ideas around the reader.
13 articles
A Markdown rendering reference you can inspect
An original synthetic document for checking tables, code, Mermaid, math, local images and relative links. A reference, not a ranking.
Read the articleA place to read what your coding agent writes
A practical reading workflow for local plans, reports, and READMEs, with a clear distinction between reloading a file and opening a new one.
Read the articleWhy offline documentation matters
Local files, relative links, and a document that stays available on your Mac.
Read the articleA Markdown reader and an editor have different jobs
Choose a source view for changing Markdown and a rendered page for reading it. A practical distinction for READMEs, reports, and linked documentation.
Read the articleWhat breaks when a Markdown folder moves? A small file-path experiment
Move one documentation folder, then one file, and see which relative Markdown links and images break. A small, reproducible file-path experiment.
Read the articleDesign a Markdown documentation folder that can travel
Design a Markdown documentation folder that still works when moved or shared: a root entry page, relative links, local assets and a simple manifest.
Read the articleAn agent report that a human can actually review
A before-and-after example of an AI agent implementation report rewritten so a human can review it: summary, changes, evidence and open risks.
Read the articleHow to test a long Markdown document without inventing a speed score
A reproducible protocol for opening, searching and navigating a very long Markdown file, so a reader comparison measures behaviour instead of guessing speed.
Read the articleWhat to check before approving an AI implementation plan
A checklist for reviewing an AI implementation plan before you approve it, applied to two fictional plan versions with different scope and risks.
Read the articleWhen code changes but the Markdown still describes yesterday
When code changes but the Markdown still describes yesterday: a fictional example of documentation drift and a review path back to the source code.
Read the articleHow to test a Markdown specification handoff with a real recipient
A consent-aware protocol and sample package for testing whether someone can follow a Markdown specification handoff. No participant results are claimed.
Read the articleHow Aero Markdown is designed to render local documents offline
How Aero Markdown is designed to render Markdown offline: bundled highlighting, Mermaid and KaTeX, local files only, and where the browser tool differs.
Read the article