Overview
A solo vault has one hard problem, thinking. A shared vault adds a second, coordination without corruption. Two people editing one note, racing to name the same idea, or independently splitting the same atom will destroy link density and provenance unless the architecture designs the conflict out. This page covers the multi-author layer on top of vault-architecture. The review gate that enforces it is in vault-pull-request-review.
Use Git as the substrate, not a file syncing service
File replicators resolve concurrent edits by last write wins, which for a team is silent data loss: two people edit one note, and one person’s paragraph disappears with no record. Git gives a shared vault three things no replicator can.
- A merge model. Edits to different regions of a file merge; edits to the same region surface a conflict for a human instead of vanishing.
- Immutable history. This is what actually enforces the immutable pre-decision section from decision-journals. A hindsight rewrite shows up as a diff against a section that should never have changed.
- Review gates. A second author can check atomicity, sources, and naming before a note lands.
Commit the vault spec and the tooling. Ignore per-user editor state (workspace.json, caches, local trash) and keep shared plugin configuration tracked so the team runs the same templates and queries. Branching conventions carry over from git, and schema changes travel the same path as any other change, using the moves in vault-evolution.
Design the conflicts out with atomicity and append conventions
Atomicity is a concurrency discipline as much as a thinking one. Two people editing two atoms never conflict; one 2,000-word note that three people need to touch is a permanent merge hotspot.
- Append-only regions get an append convention. Decision outcomes, map link lists, and daily notes take one bullet per line, newest at the bottom, and never reflow existing lines. Git merges disjoint appends cleanly; a reflow turns a clean append into a conflict.
- Frontmatter keeps a fixed field order, so a one-field change is a one-line diff. Do not auto-bump
modifiedon every keystroke, which manufactures conflicts on otherwise-untouched notes. - Split high-traffic maps early. A map three people edit weekly wants to be three sub-maps, per linking-and-tags.
When a conflict does happen, the note’s author arbitrates, not whoever pulled last.
Hold one naming authority over the namespace
Filenames are the vault’s primary keys. Two authors independently creating compound-interest-beats-linear.md and compound-interest-outpaces-linear-saving.md for one idea split the link density across two notes that should be one.
Keep a lightweight naming ledger where an author proposes a title before writing when the idea might already exist. One maintainer owns the taxonomy: the domain tag tree, the note-type prefixes, and the map names. A fork between #domain/finance/macro and #domain/macro-finance is expensive to reconcile later.
Renames are a scope-freeze operation. A rename breaks every inbound link until the links are rewritten, so state the path list and the referring notes, get sign-off, then commit the rename and the link updates together so history stays bisectable.
Keep atoms communal and decisions owned
Anyone may improve any atom. Permanent notes are the communal core, with contribution history attributed in an append-only authors field rather than reconstructed from the log.
Decision notes have exactly one owner, the person who made the decision. A reviewer may comment on a pre-decision section and never edit it. Active project workspaces and inbox captures can carry a light owner convention so two people are not racing in the same scratch space.
Arbitrate atom splits before they fork
Two authors who both notice that an atom holds two ideas will split it two different ways, and the vault ends up with three notes where it needed two. Treat a split like a rename: the person proposing it names the seam and the two resulting titles in the ledger, the note’s author confirms, and the split lands as one change with its link rewrites. The audit surfaces the candidates; people agree the cut. See vault-audit.