Documents

Notes, plans, specs, pages and app records are documents. Each one is its own CRDT that syncs like a session does, so a person and several agents can type in the same paragraph at once and every edit merges.

How it works

Documents merge per character. There are no locks and no "someone else is editing". Each document is a separate CRDT with its own history, so a project of a thousand documents is a thousand small things that sync independently, not one large file (sync).

A path like notes/sync.md is a display path inside a project, not a file on disk. Its extension sets the type: .md is markdown and .html is a page. An app record is a document with a data type and fields instead of text (shared data types). Folders are real: an empty folder you create stays, even after its last document moves away, and a folder that still holds anything cannot be removed.

Every change is kept with who made it, person or agent. You can see a document's history beside it, undo a single change, or restore an earlier version, and nothing is lost by going back (history).

An agent changes a document with a targeted edit: it replaces the exact passage it means to change and leaves the rest alone. It does not rewrite the whole text over someone's typing. Each edit can carry a one-line note on why, shown beside the change and its undo.

Comments belong to the document and anchor to a passage. They move with the document, wherever it goes.

Using it as you build

From the command line, list, read, create and update documents in a project:

mod-next docs list <projectId>
mod-next docs read <documentId>
mod-next docs create <projectId> notes/launch.md --content "# Launch"
mod-next docs update <projectId> <documentId> --content "# Launch, v2"

create and update read standard input when --content is left out, so you can pipe a file in. Comment on a passage and answer a thread:

mod-next comment add <projectId> <documentId> "Is this still true?" --anchor "expires after an hour"
mod-next comment reply <projectId> <commentId> "Yes, checked today."

Agents use the same operations as tools. list_documents and read_document find and read. create_document makes a document, with content for text or dataType and data for a record. patch_document replaces one exact passage and is the tool for most edits; update_document replaces the whole content, and also renames a document or moves it with path, keeping its id. delete_document removes one. save_file brings a PDF or an image into the project as a document, so everyone can open it. move_folder moves or renames a whole folder at once, and refuses the move if any new path is taken.

You decide what goes in documents and how you folder them. You also decide which app draws each type: when two apps can open one, pick under Open with in Settings.

Limits

• Undoing one change is refused if someone has typed over it, or changed that record field, since. Mod says so rather than guessing.
• A repository's code is never stored as documents. It stays in git, as a source. The one exception is an app's own source, which lives as documents once it has been pushed (packages).
• Sharing a single document with someone outside its project comes with the new sharing model (RFC 0345). soon