Add collaborator projection instructions

docs/projection-operations.md

@@ -0,0 +1,68 @@
+# Projection Operations
+
+This repo is projected into AFFiNE manually for now.
+
+Canonical Gitea repo:
+
+```text
+http://100.64.0.1:30087/virgil-admin/rta-mock-docs.git
+```
+
+Projected AFFiNE path:
+
+```text
+Agent Workspace / projected-markdown / mock-rta-docs
+```
+
+## What A Collaborator Does
+
+```sh
+cd ~/Developer/Section0/rta-mock-docs
+git pull --ff-only
+# edit Markdown
+git add .
+git commit -m "Update docs"
+git push
+```
+
+## What The Projection Operator Does
+
+The operator keeps a separate checkout so projection never depends on a
+collaborator's dirty working tree.
+
+```sh
+git -C /Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs pull --ff-only
+```
+
+Then from `home-lab-v7`:
+
+```sh
+cd /Users/virgil/Developer/Virgil-Info/home-lab-v7
+
+nix develop --command bash -lc 'scripts/ops/sync-obsidian-affine.rb \
+  --name rta-mock-docs \
+  --source /Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs \
+  --username projection-bot \
+  --authentik-sub rta-projection-bot \
+  --affine-workspace "Agent Workspace" \
+  --affine-workspace-id 53ea0a0b-eca7-4887-8e31-f5b2a8ab7744 \
+  --affine-user-id ce42f50a-5367-4466-920b-7422c4e27de0 \
+  --affine-namespace projected-markdown/mock-rta-docs \
+  --include "**/*.md" \
+  --apply'
+```
+
+Expected healthy result:
+
+```text
+docs:       3
+mark stale: 0
+mode:       one-way read-only AFFiNE docs
+```
+
+## Rule Of Thumb
+
+If the source repo changes, pull the projector checkout and run projection.
+
+If AFFiNE changes, treat it as a comment or sketch. Move durable edits back to
+Markdown before projecting again.

docs/source-models.md

@@ -0,0 +1,73 @@
+# 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:
+
+```text
+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:
+
+```text
+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.