From d086243fe175f128f5d0432200cf3cc941b5fd77 Mon Sep 17 00:00:00 2001 From: virgil Date: Sun, 7 Jun 2026 03:40:02 -0700 Subject: [PATCH] Add collaborator projection instructions --- README.md | 66 ++++++++++++++++++++++++++++-- docs/projection-operations.md | 68 +++++++++++++++++++++++++++++++ docs/source-models.md | 73 ++++++++++++++++++++++++++++++++++ scripts/setup-rta-mock-docs.sh | 40 +++++++++++++++++++ 4 files changed, 244 insertions(+), 3 deletions(-) create mode 100644 docs/projection-operations.md create mode 100644 docs/source-models.md create mode 100755 scripts/setup-rta-mock-docs.sh diff --git a/README.md b/README.md index f602971..f36a0c1 100644 --- a/README.md +++ b/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`. diff --git a/docs/projection-operations.md b/docs/projection-operations.md new file mode 100644 index 0000000..ca5e5fa --- /dev/null +++ b/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. diff --git a/docs/source-models.md b/docs/source-models.md new file mode 100644 index 0000000..0de2023 --- /dev/null +++ b/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. diff --git a/scripts/setup-rta-mock-docs.sh b/scripts/setup-rta-mock-docs.sh new file mode 100755 index 0000000..8b132f3 --- /dev/null +++ b/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 <