Problem

Seed documents can contain query blocks, but there is no document-level collection experience. A user who wants a database-like collection must create and configure a normal document, then interact with its query through the generic block editor and the document's unrelated Content, Activity, Collaborators, and Attributes views. The result neither looks nor behaves like a collection, and its narrow centered layout wastes the space needed by a table.

Collections also need a durable invariant: every collection has a root query block presented as a table. Existing or malformed collection documents may have no query block or may still use Card/List style. Rendering an error would make those documents unusable, while silently publishing a repair on page load would be surprising.

Solution

image

Treat a normal document with the exact, case-sensitive open-ended text attribute type: "Collection" as a Document Collection. The document machine owns the collection behavior; React renders only what it derives from the machine snapshot.

Creation and identification

Add New Document Collection only to the in-app New dropdown.

Create it as a normal public draft at the currently selected writable location.

Seed type: "Collection" and exactly one root query block.

Seed the query with Table style, empty space and path, Children mode, the standard update-time sort, three columns, and no limit. Empty scope intentionally means the current document and follows the existing publish behavior.

In the file browser, show the Grid 3x3 icon before a collection title. If a document is both private and a collection, prefer the collection icon over the private lock.

Machine-owned collection behavior

Derive whether a document is a collection from the machine's effective metadata; do not store a duplicate kind or presentation value in context.

Derive effective content from the draft while editing and from the published document otherwise.

Select the first root-level query block. Additional query blocks do not control the collection view.

Derive a usable Table query for rendering. If no query exists, derive the standard default query; if the saved query uses Card/List style, derive the same query with Table presentation.

Do not materialize source: document | draft | synthetic or synthetic query state. Those facts are not needed by the UI and are derivable where relevant.

Keep the existing document lifecycle (loading, loaded, editing, publishing, discarding, and error handling) intact. Add only the explicit asynchronous repair workflow needed to create or normalize a local draft.

Expose collection status and the effective query through machine-owned pure selectors. React must not independently inspect raw attributes, choose draft versus published content, manufacture a default query, or decide to repair.

Repair rules

Render the derived table immediately, with no blank or error state, while repair happens.

If an editor opens a collection with no root query, create a local draft containing the default Table query and enter the normal editing state.

If an editor opens a collection whose first root query is Card/List, update that query to Table in a local draft and enter the normal editing state.

Never publish a repair automatically. The existing Publish controls remain the explicit publication step.

Readers get the same usable derived table but never create or modify a repair draft.

A repair failure must not prevent the derived collection table from rendering.

Collection page

Render the existing document header. Title, icon, cover, and summary remain editable for users with edit permission.

Do not mount the block editor for collections.

Do not render the document content tabs/tools, including Content, Activity, Collaborators, and Attributes.

Every main view term renders the same collection table view rather than its usual main content.

Preserve the existing right panel behavior for all routes.

Render the query table across the full width of the main section with modest side padding, rather than inside the centered document-content column.

Use the effective query block's includes, sort, limit, columns, and other persisted table properties. Reuse the existing table controls, filters, properties, and search experience.

Interaction and persistence

Search and ad hoc filters are session-only for editors and readers.

Readers may reorder, resize, hide/show, and sort columns, but those changes remain session-only.

For editors, table changes representable by the query block (including column visibility, order, widths, and saved sorting) are sent as document-machine events, update the query block in the local draft, and use the existing autosave lifecycle. The user publishes later.

The table must not write to draft storage directly; permission and persistence decisions stay in the document machine.

User stories and acceptance criteria

As an author, I can create a Document Collection from the in-app New menu and immediately see an editable header and a full-width table.

As an editor, I can configure persistent table properties and publish them through the normal draft workflow.

As a reader, I can search, filter, and rearrange the table for my session without changing the document.

As an editor opening an older or malformed collection, I see a working table immediately and receive a repair draft I can publish.

As a reader opening that same collection, I see the working table without any background write.

As a user opening any collection view term, I continue to see the table, while the requested right panel still works.

Ordinary documents continue to render the existing document tools, content, editor, and view-specific main content.

Scope

Phase 1: Creation and file-browser identity — one session

Support seeded public drafts in the existing draft-creation path without changing lazy creation for ordinary public documents or existing private-document behavior.

Add the in-app creation option, the canonical attribute/query seed, and Grid 3x3 file-browser treatment.

Update the collection seed from Card to Table.

Phase 2: Machine derivation and repair — one to two sessions

Add pure machine selectors for collection detection, effective content, first root query, repair need, and effective Table query.

Add guarded editor-only local draft creation/normalization and transition into the existing editing lifecycle.

Add machine events for persistent collection query configuration changes.

Cover valid, missing, non-Table, reader, editor, published, and draft cases with machine tests.

Dependencies: the existing document draft/autosave/publish lifecycle and existing query-block conversion utilities.

Phase 3: Collection page integration — one to two sessions

Add the thin collection renderer driven by document-machine selectors.

Reuse the existing header, query result loading, table controls, and right panels.

Apply full-main-section layout and omit the editor and document tools for all main view terms.

Verify editor persistence versus reader session state and regress ordinary documents.

Dependencies: Phase 2 and the existing query table component/API.

Rabbit Holes

Building a general registry/framework for future document types before a second specialized type exists.

Converting the entire document machine to top-level parallel lifecycle/presentation regions; this would destabilize existing snapshot.matches(...) consumers for no current benefit.

Spawning a separate collection child actor when the repair can fit the existing machine lifecycle.

Supporting Card, List, gallery, kanban, calendar, or user-selectable collection views in the first version.

Designing a general document-template system instead of extending the existing draft creation path with initial metadata/content.

Moving query filters or search into persisted document state.

Automatically repairing additional/non-root query blocks, or defining semantics for multiple collection queries.

Reworking query execution, empty-target publishing semantics, or backend APIs.

Adding private Document Collection creation before there is an explicit product design for it.

No Gos

Do not recognize lowercase collection or other variants; only the exact value Collection identifies the type.

Do not add the creation option to native File/OS menus, keyboard shortcuts, web-only menus, or other entry points.

Do not create a custom backend document type. A collection remains a normal document distinguished by an open-ended attribute and query-block content.

Do not store redundant kind, presentation, query source, or synthetic-query state in machine context.

Do not let React independently reproduce collection detection, query selection, normalization, repair, or draft-write rules.

Do not mount or hide a block editor with CSS as a substitute for the collection renderer.

Do not show document content tabs/tools in a collection's main page, and do not let main view terms replace the table.

Do not break or special-case the existing right panel behavior.

Do not automatically publish repairs or table configuration changes.

Do not create repair drafts for readers or persist their table interactions.

Do not render an error/empty collection page merely because its query is missing or uses a non-Table style.

Do not change ordinary or private document creation and rendering behavior beyond the explicit collection icon precedence edge case.

hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/lobby/document-collection?v=bafyreiawrsv76nxydwgom6kgj76dii2nxo4rivbugjkzimuav2qwmecbhi&l

hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/design/stories/authoring/document-or-folder-docs

⚠️ hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/design/stories/organization/as-a-user-i-want-flexible-ways-to-visualize-filter-and-organize-collections-of-documents-whether-i-just-imported-them-or-i-m-querying-existing-content

hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/notes/folders

hm://z6MkuBbsB1HbSNXLvJCRCrPhimY6g7tzhr4qvcYKPuSZzhno/tasks/tables-and-attributes-review