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
  -> projection registry
  -> 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.

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.