Clarify Section 0 setup language

README.md

@@ -1,17 +1,23 @@
-# Section 0 RTA Handbook
+# Section 0 Shared Docs
 
-This hosted Git repo is intentionally plain Markdown. It has no required RTA
+These documents are available in two ways:
-sidecars. Collaborators clone, edit, commit, and push it as the canonical
+
-documentation source. The projection operator reads a separate projector
+1. Read them in AFFiNE.
-checkout and mirrors the Markdown into AFFiNE as read-only docs.
+   AFFiNE is the shared reading and whiteboard space. The Markdown docs from
+   this repo appear there as read-only copies.
+
+2. Edit them in Git.
+   The editable files live in this plain Markdown repo. Use your normal editor,
+   then commit and push changes.
+
+If you want to change one of these docs, edit the Markdown file. Do not edit
+the AFFiNE copy; it will be refreshed from Git.
 
 ## What To Edit
 
-Edit Markdown files in this Git repo. Do not edit the projected AFFiNE copies
+Edit Markdown files in this Git repo.
-directly; AFFiNE is the shared reading and canvas surface, not the source of
-truth for these files.
 
-Current projected docs:
+Current docs:
 
 - `README.md`
 - `rta/concept.md`
@@ -19,7 +25,7 @@ Current projected docs:
 
 ## First-Time Setup
 
-From any machine that can reach the lab mesh:
+From any machine that can reach the private lab network:
 
 ```sh
 curl -fsSL http://100.64.0.1:30087/section0/rta-handbook/raw/branch/main/scripts/setup-section0-docs.sh | sh
@@ -57,14 +63,13 @@ MESSAGE="Describe the doc change" section0-docs commit
 section0-docs push
 ```
 
-After a push, ask the projection operator to pull and project. For now that is
+After a push, ask Virgil to refresh the AFFiNE copies. For now that refresh is
-manual. The current operator command lives in
+manual. The current refresh command lives in `docs/projection-operations.md`.
-`docs/projection-operations.md`.
 
 ## Contributor Setup
 
-Anonymous clone/read works on the lab mesh. Pushing requires a Gitea account or
+Anonymous clone/read works on the private lab network. Pushing requires an
-token with write access to `section0/rta-handbook`.
+account or access token with write access to `section0/rta-handbook`.
 
 Run this once per checkout:
 
@@ -84,8 +89,9 @@ rather than your normal account password.
 
 ## Source Models
 
-This repo is the Git-backed model: shared docs are canonical in Gitea.
+This repo is the shared Git model: shared docs are edited in Git, then copied
+into AFFiNE for reading.
 
 Personal vault mounts are different: a person keeps custody of their own local
-Obsidian vault and only projects selected Markdown into AFFiNE. See
+Obsidian vault and only shares selected Markdown into AFFiNE. See
-`docs/source-models.md`.
+`docs/source-models.md` for that more advanced case.

scripts/project-section0-rta-handbook.sh

@@ -5,7 +5,7 @@ PROJECTOR_DIR="${PROJECTOR_DIR:-/Users/virgil/Developer/rta/tmp/markdown-project
 HOME_LAB_DIR="${HOME_LAB_DIR:-/Users/virgil/Developer/Virgil-Info/home-lab-v7}"
 
 if [ ! -d "$PROJECTOR_DIR/.git" ]; then
-  echo "Projector checkout not found: $PROJECTOR_DIR" >&2
+  echo "Sync checkout not found: $PROJECTOR_DIR" >&2
   exit 1
 fi
 
@@ -14,17 +14,17 @@ if [ ! -d "$HOME_LAB_DIR" ]; then
   exit 1
 fi
 
-echo "==> Pulling projector checkout"
+echo "==> Pulling the Git docs checkout"
 git -C "$PROJECTOR_DIR" pull --ff-only
 
-echo "==> Checking projector checkout is clean"
+echo "==> Checking the Git docs checkout is clean"
 if [ -n "$(git -C "$PROJECTOR_DIR" status --porcelain)" ]; then
   git -C "$PROJECTOR_DIR" status --short
-  echo "Projector checkout is dirty; projection must read a clean source." >&2
+  echo "Git docs checkout is dirty; refresh must read a clean source." >&2
   exit 1
 fi
 
-echo "==> Projecting Markdown into AFFiNE"
+echo "==> Refreshing AFFiNE from Markdown"
 cd "$HOME_LAB_DIR"
 nix develop --command bash -lc "scripts/ops/sync-obsidian-affine.rb \
   --name section0-rta-handbook \

scripts/setup-section0-docs.sh

@@ -40,7 +40,7 @@ REPO_DIR="$TARGET_DIR"
 
 usage() {
   cat <<USAGE
-section0-docs - helper for Section 0 Git Projection repos
+section0-docs - helper for Section 0 shared Markdown docs
 
 Commands:
   configure set Git author name/email for this repo
@@ -62,8 +62,8 @@ Examples:
   MESSAGE="Update concept notes" section0-docs commit
   section0-docs push
 
-AFFiNE is read-only for this repo. Durable edits happen in Markdown, then the
+AFFiNE is read-only for these docs. Make lasting changes in Markdown; the
-projection operator pulls and projects.
+AFFiNE copies are refreshed from Git.
 USAGE
 }
 
@@ -157,7 +157,7 @@ Contributor setup:
   $COMMAND_NAME configure
   $COMMAND_NAME push-test
 
-AFFiNE updates after the projection operator pulls and runs projection.
+AFFiNE updates after the Markdown docs are refreshed from Git.
 
 If $COMMAND_DIR is not on PATH, add this to your shell profile:
   export PATH="$COMMAND_DIR:\$PATH"