Add collaborator projection instructions

README.md

@@ -1,5 +1,65 @@
 # Mock RTA Knowledge Base
 
-This hosted Git repo is intentionally plain Markdown. It has no RTA sidecars.
-Collaborators clone, edit, commit, and push it as the canonical documentation source.
-The projection operator reads a projector checkout and mirrors it into AFFiNE.
+This hosted Git repo is intentionally plain Markdown. It has no required RTA
+sidecars. Collaborators clone, edit, commit, and push it as the canonical
+documentation source. The projection operator reads a separate projector
+checkout and mirrors the Markdown into AFFiNE as read-only docs.
+
+## What To Edit
+
+Edit Markdown files in this Git repo. Do not edit the projected AFFiNE copies
+directly; AFFiNE is the shared reading and canvas surface, not the source of
+truth for these files.
+
+Current projected docs:
+
+- `README.md`
+- `rta/concept.md`
+- `rta/reports/current-status.md`
+
+## First-Time Setup
+
+From any machine that can reach the lab mesh:
+
+```sh
+curl -fsSL http://100.64.0.1:30087/virgil-admin/rta-mock-docs/raw/branch/main/scripts/setup-rta-mock-docs.sh | sh
+```
+
+The script clones this repo into:
+
+```text
+~/Developer/Section0/rta-mock-docs
+```
+
+Override the destination if you prefer:
+
+```sh
+TARGET_DIR=~/work/rta-mock-docs \
+  curl -fsSL http://100.64.0.1:30087/virgil-admin/rta-mock-docs/raw/branch/main/scripts/setup-rta-mock-docs.sh | sh
+```
+
+## Daily Flow
+
+```sh
+cd ~/Developer/Section0/rta-mock-docs
+git pull --ff-only
+
+# Edit Markdown files in your normal editor.
+
+git status
+git add path/to/file.md
+git commit -m "Describe the doc change"
+git push
+```
+
+After a push, ask the projection operator to pull and project. For now that is
+manual. The current operator command lives in
+`docs/projection-operations.md`.
+
+## Source Models
+
+This repo is the Git-backed model: shared docs are canonical in Gitea.
+
+Personal vault mounts are different: a person keeps custody of their own local
+Obsidian vault and only projects selected Markdown into AFFiNE. See
+`docs/source-models.md`.

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.

scripts/setup-rta-mock-docs.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+set -eu
+
+REPO_URL="${REPO_URL:-http://100.64.0.1:30087/virgil-admin/rta-mock-docs.git}"
+TARGET_DIR="${TARGET_DIR:-$HOME/Developer/Section0/rta-mock-docs}"
+
+if ! command -v git >/dev/null 2>&1; then
+  echo "git is required but was not found on PATH" >&2
+  exit 1
+fi
+
+if [ -d "$TARGET_DIR/.git" ]; then
+  echo "Repo already exists: $TARGET_DIR"
+  git -C "$TARGET_DIR" remote set-url origin "$REPO_URL"
+  git -C "$TARGET_DIR" fetch origin
+  git -C "$TARGET_DIR" checkout main
+  git -C "$TARGET_DIR" pull --ff-only
+else
+  mkdir -p "$(dirname "$TARGET_DIR")"
+  git clone "$REPO_URL" "$TARGET_DIR"
+fi
+
+git -C "$TARGET_DIR" config pull.ff only
+
+cat <<EOF
+Ready.
+
+Repo: $TARGET_DIR
+Remote: $REPO_URL
+
+Daily flow:
+  cd "$TARGET_DIR"
+  git pull --ff-only
+  # edit Markdown
+  git add .
+  git commit -m "Update docs"
+  git push
+
+AFFiNE updates after the projection operator pulls and runs projection.
+EOF