Concepts
Writes, changes and locks
People and AI write to the brain directly, and every write carries a reason, a source and an author. Each change lands in the project's changes feed, where one click undoes it; a locked block refuses every writer.
The brain only works if people dare to let AI write to it. So there is no approval queue that nobody reads. Instead every write is visible, explained and reversible, and the few things that must not move are locked.
One way in for every write
Whether a write comes from the editor in the browser, an AI over MCP, the API, the review widget or an app, it goes through the same path, in a fixed order:
- Locks. A locked block, or a locked passage, refuses the write. One rule for everyone, owners included.
- The schema gatekeeper. The value is checked against the block type's schema, and the diagrams and charts in the body are checked too. An invalid write is refused with a list of
issuesthat say what to fix. - Lifecycle. A stub that gets real content becomes assumed; see Lifecycle.
- Provenance. The new version records its source, its reason, its batch and who wrote it.
- The write, with a version check: a write that names the version it read is refused when someone else changed the block since, instead of overwriting their change.
Before that path, an AI writing over MCP passes the write gate: for the canonical entities it must have read a briefing for the task. See Briefings and the write gate.
Writes land directly. A reason is not a formality: it is what a person reads in the changes feed when deciding whether to keep the change.
The changes feed
Every project has a changes feed at /<organisation>/<project>/changes. It lists every version written to the project, grouped by day:
- Who and from where: the editor, an AI over MCP, the widget, the API, an app's episode or the system. You can filter by source and by person.
- Why: the reason given with the write.
- What: a line diff of the body.
- Undo: one click puts the block back to its previous version.
Writes that belong together share a batch. An ingest_text run that turned a meeting transcript into ten block changes, for example, reverts as a whole in one action. Ingestion never rewrites a validated block: such an update comes back as held, for a person or a session to apply with a reason, and an update of a block that already says something is folded into its text instead of replacing it.
People who only read have their own view: the book's What changed page (/<organisation>/<project>/book/changes) shows the same history as a reading aid, with the reasons and links into the chapters, and without undo.
Deleting
Deleting a block archives it. It leaves the book and waits in the project's archive (/<organisation>/<project>/archive, also reachable from What changed). Anyone who can edit restores it from there, or undoes the archive in the changes feed. Other blocks keep their references to it, so a restore has nothing to rebuild. An AI only deletes when you ask it to.
Archiving also ends the page's public link, if it had one; restoring the page does not make it public again.
Erasing is for good. Only an owner or admin erases a block, from the archive:
- The block goes with every earlier version and its history in the changes feed. One line in the activity log keeps who erased it, and when.
- Nobody can restore it afterwards, an admin neither. The server's backups keep a copy for at most fourteen days; getting it back from there is a step on the server, not in the app.
- To confirm, you type the block's key. Within fourteen days of archiving, the server refuses an erase without it.
Deleting a project or an organisation erases its blocks the same way, with their history. It also revokes the project's API keys and clears its pending hand-offs and skill proposals. An organisation's org project cannot be deleted on its own.
Locks
A lock is the one hard gate.
- Who: owners and admins lock and unlock, from the block's page or with
lock_blockandunlock_block. An API key can never lock or unlock. - What it refuses: every update, archive and restore, from everyone, owners included, people and AI alike. The refusal quotes the note left with the lock.
- Passages: a lock can cover only certain passages of a body. Then an edit is refused only when it changes a locked passage.
- Changing a locked block means: unlock, edit, lock again. Each step is in the changes feed.
Organisation blocks add one more rule: a project can never edit a block it inherits from its organisation, locked or not. It can override fields with a reason, or ask the block's owner.
What belongs behind a lock
Legal texts, approved positioning, the tone of voice, signed-off decisions: anything a reviewer has agreed and that must not drift without them. A convention ("please don't change this") is not a lock; a lock is.
Over the API
The REST API returns the same refusals with status codes: 403 with code: "BLOCK_LOCKED" for a lock, 409 for a version conflict, 400 with issues for a schema failure. See Endpoints.
Next
- Experts and skills: the method an AI follows before it writes.
- The editors: agents that keep the brain in shape, and what they never do.
- Briefings and the write gate: read before you write.
Last updated: