diff --git a/README.md b/README.md index 6793982..3b9b903 100644 --- a/README.md +++ b/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 -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. +These documents are available in two ways: + +1. Read them in AFFiNE. + 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 -directly; AFFiNE is the shared reading and canvas surface, not the source of -truth for these files. +Edit Markdown files in this Git repo. -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 -manual. The current operator command lives in -`docs/projection-operations.md`. +After a push, ask Virgil to refresh the AFFiNE copies. For now that refresh is +manual. The current refresh command lives in `docs/projection-operations.md`. ## Contributor Setup -Anonymous clone/read works on the lab mesh. Pushing requires a Gitea account or -token with write access to `section0/rta-handbook`. +Anonymous clone/read works on the private lab network. Pushing requires an +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 -`docs/source-models.md`. +Obsidian vault and only shares selected Markdown into AFFiNE. See +`docs/source-models.md` for that more advanced case. diff --git a/scripts/project-section0-rta-handbook.sh b/scripts/project-section0-rta-handbook.sh index abdbb3e..0582104 100755 --- a/scripts/project-section0-rta-handbook.sh +++ b/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 \ diff --git a/scripts/setup-section0-docs.sh b/scripts/setup-section0-docs.sh index 521d8d2..c8ae22e 100755 --- a/scripts/setup-section0-docs.sh +++ b/scripts/setup-section0-docs.sh @@ -40,7 +40,7 @@ REPO_DIR="$TARGET_DIR" usage() { cat <