rta-handbook/docs/source-models.md

Source Models

The projection system supports two source styles. They solve different social problems.

Git-Backed Shared Docs

Use this for documents multiple collaborators should edit together:

• project specs
• game design docs
• agendas
• operating docs
• shared research summaries

The canonical source is a hosted Git repo in Gitea. Everyone clones, branches, commits, pulls, and pushes using normal developer tools. AFFiNE receives a read-only projection.

Flow:

Gitea repo
  -> collaborator clone/edit/commit/push
  -> projector checkout pull
  -> projection registry
  -> read-only AFFiNE docs

Why this is the default for shared work:

• Git already solves collaborative text editing.
• People can use their own editor, diff, review, and branch workflow.
• File names and directory structure stay visible and portable.
• AFFiNE stays useful as the shared view and whiteboard layer.

Mounted Personal Vaults

Use this when a collaborator wants to share a selected slice of their own knowledge base without moving custody into the shared repo:

• personal research notes
• meeting notes
• private vault excerpts
• owned reference material

The canonical source stays in the person's local vault. Projection is one-way into AFFiNE. Even the owning person should treat the AFFiNE copy as derived.

Flow:

personal Markdown or Obsidian vault
  -> selected include paths
  -> local mount registry
  -> authenticated projection request
  -> read-only AFFiNE docs

Why this exists:

• It preserves local custody.
• It avoids forcing everyone into one giant shared repo.
• It lets people publish useful slices without adopting a new editor.

CLI flow:

section0-docs auth login
section0-docs mount add research ~/Documents/Obsidian/Research
section0-docs mount plan research
section0-docs mount sync research

mount plan prints the exact payload before it is sent. mount status shows the local declaration and the last sync receipt. mount unmount removes the projected AFFiNE docs for that namespace without touching the source folder.

Choosing Between Them

Use Git-backed docs when the document itself is a shared artifact.

Use mounted personal vaults when the document is personally owned but useful to surface in the collective workspace.

If a personal note becomes a shared artifact, copy or adapt the useful content into a Git-backed repo and let that shared repo become canonical.