The question comes before the file tree
Our Project Reading Kit describes a fictional field-notes application. The question is small: can a researcher collect notes offline and give a colleague a readable summary? The example is not a customer story, a shipped application or evidence of a productivity gain.
Download its six documents, or read the overview in the browser. The purpose is to give you something concrete to explore in the Markdown app you already use.
The README gives you a route
The overview links to the specification, architecture, plan and decision log. Its table says which question each document answers. That is more useful to a new reader than a list of filenames whose roles they have to infer.
A README is an entrance, not a promise that all context belongs on one enormous page. In this example, the reading path follows the reader's questions.
The specification establishes the boundary
The specification includes source preservation and an offline acceptance criterion. It explicitly leaves out sync and shared editing. These are proposed requirements, not checked accomplishments.
Its unresolved question asks whether a summary should be one file or a folder. The document should make that uncertainty visible rather than quietly treating delivery as solved.
The architecture needs a paragraph, not just arrows
The flowchart puts human review between notes and summary. The text underneath says the diagram does not imply automatic analysis. That explanation limits what a reader should infer from the picture.
Follow the local-file decision from there. It explains the offline rationale and its cost: delivery and backup still need explicit action. Local storage is not the same as automatic backup.
Return to the requirement after reading the reason
Go back to the specification's acceptance criteria. Now a line about preserving sources has an architectural reason behind it. The plan can be read against that requirement rather than judged only by whether its steps look plausible.
This is the reading experience Aero Markdown is being built to support: a folder tree for the set, an outline for the current document, and links for the explanation's route. The Mac app is not available yet; the example files work independently of it.
What this example deliberately does not prove
It does not show every team should use the same folder structure. It does not measure comprehension, speed or time saved. A folder with poor filenames or broken references can still be difficult to read.
Use the relative-link guide to inspect paths, the Mermaid guide for the diagram, or the agent review pack to practise reviewing a proposal whose scope changes.