Core concepts

Baalda uses a small vocabulary consistently, in the app, in this documentation and in the API. These are the terms worth knowing before anything else.

Storage and identity#

Vault

The unit you open, sync and share. Locally it is a folder of Markdown files. Once sync is on, the same word names the team entity behind it, which is an organization on the server. The two are the same thing in its local and synced states.

Remote Vault

What the app calls the server's copy of a synced vault, as distinct from the folder on this computer.

Note

One .md file. Its name is its file name, and renaming the note renames the file.

docIdstring

The stable identity of a note. The file, the Yjs document, the local index row and the server row all reference the same docId, and everything is keyed by it rather than by path, so a rename or a move never forks a note.

revisionstring

A note's current version marker. read_note returns it over MCP, and passing it back as expectedRevision makes a write fail rather than merge if the note changed in between.

.context

The hidden folder inside each vault holding the local SQLite index, the local CRDT history and config.json with the vault id, device id and server URL. It is never indexed as notes and never synced.

Registry

The server's list of what exists in a vault: notes, folders and files, with their ids and paths. Structure syncs through the registry, content syncs through the CRDT.

Sync#

The bridge

The two-way translation between the file on disk and the CRDT document: diff a changed file into operations, and serialize operations back to an atomic write.

Operation

The unit both directions produce. Because every change is an operation rather than a whole-file write, concurrent edits merge.

Vault channel

The always-on WebSocket at /vault-sync that carries structure, file events and vault-wide announcements, separate from the per-note editing sockets at /sync.

Sync token

A short-lived per-document JWT, 10 minutes by default, minted by the server after it computes your permission on that note. The editing socket will not open without one.

Recovery copy

A copy kept on this computer when edits could not be sent before something was removed or revoked, so a change never disappears silently.

Trash

The server's 30-day per-vault holding area for deleted notes, with Restore. A purge leaves a tombstone row behind so a late push into a deleted note is still accepted rather than resurrecting it.

People and access#

Member

Someone in a vault. Roles are owner, admin and member. Owners and admins manage the vault, its members and its access.

Everyone

The vault-wide access row: Can edit, Can view or No access, applied to every folder and note. Setting it rewrites the team's rows across the vault rather than acting as a default that stops at the first override.

New members

What someone sees for content that already existed when they joined. It is snapshotted at join time.

Personal level

One person's absolute level across the vault: Can edit everything, Can view everything or No access. It replaces the vault posture, the owner shortcut and authorship for that person.

Share

A row granting view or edit on a folder, a file or the whole vault, to the team or to one person. Folder grants are inherited, and a file grant can only raise permission.

Locked

A cap that takes edit down to view. It never grants and never removes read.

No access

The only rule in the model that subtracts. On an item it means the item is not shared with the team. On a person it means that person is blocked, which beats role, grants and authorship.

AI#

Local agent

A tool that can read your disk, such as Claude Code. It edits the .md files directly, with no integration.

MCP endpoint

/api/mcp on your server, which any Model Context Protocol client can call. Its tools are limited by the same per-folder permissions a person has.

MCP token

A token minted in Vault Settings, MCP. It is scoped to you in one vault, shown once, and revocable.