Collections are declarations, and roots remain free

Decided

15 August 2026

State

binding

The canonical declaration namespace is collections/. A direct child named collections/<name>.md with type: Collection is discoverable as a collection declaration. Each declaration is an ordinary Markdown file with the collection's schema and views. Replaced 2026-10-16 by D37: declarations are discovered by type at any depth, without a reserved containing folder.

The dividing principle: outside collections/ the item layout is free — folders and files may use any arrangement, useful to anyone in any tool. The preferred absent-items source is the root folder matching the declaration stem; an explicit selector may choose another path, several paths, a type scan or a strict query. A collection declaration is a statement about interpretation and display, and the items it describes stay readable without it. Replaced 2026-10-16 by D37: an implicit source is the declaration's sibling folder, not a root inferred from a namespace.

One tree has one ownership rule: X.<ext> owns the sibling folder X/. Markdown type identifies pages, collections, records and boards. An HTML extension identifies a web page. These kinds may contain each other at any depth. A folder without a sibling document is a section. collections/ and shtuks/boards/ are ordinary names, not discovery rules.

A collection is any document with type: Collection. Its address is its own extensionless path. Without items, exact-itemType direct Markdown children in its sibling folder form its membership and new records go there. writeTo overrides the create destination. Explicit path, paths, type and query selectors retain their grammar; creation then requires writeTo. A malformed selector matches nothing. Every destination receives the same collision and bundle-boundary checks. Membership remains derived, and a selector gives no ownership over files it selects elsewhere.

A feature's own surface is derived, not a service folder. service: true or the shared feature-recognition seam identifies an own-surface collection from its declared types, selectors and relations. A title or path never does. General Pages, shelves and collection lists omit that declaration and its owned subtree; dedicated readers, addresses and search retain all the files. Conversations are recognized without marking their declaration service, and their individual rows remain in the chat list.

The declaration still describes interpretation and display. Its records remain ordinary readable documents without it. The active layout is described in Layout.