Layout

A project is a git repository of Markdown files. The layout is free: pages at the root, any folders, any names — a page gains children by gaining a sibling folder with the same name, and that is the only structural rule content has. The collections/ folder holds declarations: it tells a reader how to interpret and display the rest. Replaced 2026-10-16 by D37: ownership applies to every document kind, and declaration discovery has no namespace.

X.<ext> owns its sibling folder X/. Markdown type decides whether a document is a page, collection, record or board. An HTML extension makes a web page. Every kind may stand at the root or inside another document's folder. A folder without a sibling document remains a section. collections/ and shtuks/boards/ have no reserved meaning.

my-project/
├── index.md              # the entry page — authored, never generated
├── roadmap.md            # a page
├── roadmap/              # its children
│   ├── q4.md
│   ├── risks.md          # type: Collection; owns risks/
│   ├── risks/
│   │   ├── vendor-lock.md # type: Risk; a record
│   │   └── how-we-score.md # type: Page; a non-record child
│   ├── plan.md           # type: Board; owns plan/
│   ├── plan/
│   │   └── sketch.md
│   ├── mockup.html       # a web page; owns mockup/
│   └── mockup/
│       └── feedback.md
├── tasks.md              # type: Collection; owns tasks/
├── tasks/                # implicit item source and create destination
│   └── first-task.md     # type: Task
└── assets/               # media bytes, content-addressed names

The rules

1. index.md is an ordinary authored page — the project's front door. Nothing generates it, nothing rewrites it. No listing is generated in any folder; navigation is derived and drawn, never written to disk.
2. A collection declaration is a direct collections/<name>.md file with type: Collection. Its preferred implicit source is direct Markdown files in the root /<name>/ folder. An explicit items selector may instead use path, paths, type or query, so items may live elsewhere, in several roots, or be discovered across the bundle. Membership is derived; source files remain ordinary documents. Replaced 2026-10-16 by D37: discovery uses type at any depth, and an implicit source belongs to that declaration. A collection is any type: Collection document. Its address is its own path without .md. Without items, it selects direct Markdown children in its sibling folder whose exact type equals itemType; new records go there too. writeTo overrides creation. Explicit path, paths, type and query selectors keep their grammar and need writeTo to create. A malformed selector never falls back. All destinations receive the same collision and bundle-boundary checks. Selection never moves a file.
3. A dynamic collection uses items.mode: query with the required from scope and a version-1 query — membership is computed on every read, nothing stored.
4. collections/ holds collection declarations. Everything in it is still ordinary readable Markdown, and other product-defined documents may live in their own ordinary folders. Replaced 2026-10-16 by D37: a document's kind, not its containing folder, determines how it opens. One tree follows the files. Collections, boards and web pages stand at their real parent. A collection shows its body above its views, then its non-record children; records remain in its views. A record's children remain ordinary children. Markdown owners use children: order. HTML owners use name order, without new ordering metadata.
5. Deletion is absence. The way back is version history and the folder for deleted things.
6. Own-surface collections remain addressable. service: true, or a feature's recognition of declared types, selectors and relations, derives this fact. Names and paths never do. General Pages, shelves and collection lists omit the declaration and its owned subtree. Dedicated readers, links and search retain the files. Conversations are recognized without adding a service flag; their individual rows remain in the chat list.

Boundary behaviours — items that do not match their schema, nested source folders and foreign files — are declared one by one in Cases.