Improve collaborator setup UX

README.md

@@ -31,6 +31,12 @@ The script clones this repo into:
 ~/Developer/Section0/rta-mock-docs
 ```
 
+It also installs a small helper command at:
+
+```text
+~/.local/bin/rta-mock-docs
+```
+
 Override the destination if you prefer:
 
 ```sh
@@ -41,15 +47,13 @@ TARGET_DIR=~/work/rta-mock-docs \
 ## Daily Flow
 
 ```sh
-cd ~/Developer/Section0/rta-mock-docs
+rta-mock-docs pull
-git pull --ff-only
 
 # Edit Markdown files in your normal editor.
 
-git status
+rta-mock-docs status
-git add path/to/file.md
+MESSAGE="Describe the doc change" rta-mock-docs commit
-git commit -m "Describe the doc change"
+rta-mock-docs push
-git push
 ```
 
 After a push, ask the projection operator to pull and project. For now that is

docs/projection-operations.md

@@ -30,6 +30,17 @@ git push
 The operator keeps a separate checkout so projection never depends on a
 collaborator's dirty working tree.
 
+Nice wrapper:
+
+```sh
+/Users/virgil/Developer/rta/tmp/markdown-projection-gitea/collaborator-checkout/rta-mock-docs/scripts/project-rta-mock-docs.sh
+```
+
+It pulls the projector checkout, checks it is clean, and runs the AFFiNE
+projection command.
+
+Manual equivalent:
+
 ```sh
 git -C /Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs pull --ff-only
 ```
@@ -52,14 +63,34 @@ nix develop --command bash -lc 'scripts/ops/sync-obsidian-affine.rb \
   --apply'
 ```
 
-Expected healthy result:
+Expected healthy result currently includes five docs:
 
 ```text
-docs:       3
+docs:       5
 mark stale: 0
 mode:       one-way read-only AFFiNE docs
 ```
 
+## Push-To-Projection Automation
+
+Pushing to `main` can trigger sync, but it should be implemented as a small
+projection worker, not as a Gitea container hook.
+
+Preferred shape:
+
+```text
+Gitea push webhook
+  -> RTA projection worker endpoint
+  -> pull projector checkout
+  -> validate clean source
+  -> run projection
+  -> emit logs/receipt
+```
+
+This keeps Gitea as Git infrastructure and keeps projection policy in RTA. A
+server-side Git hook inside the Gitea container would be harder to observe,
+harder to recover, and too tightly coupled to the packaged app internals.
+
 ## Rule Of Thumb
 
 If the source repo changes, pull the projector checkout and run projection.

scripts/project-rta-mock-docs.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env sh
+set -eu
+
+PROJECTOR_DIR="${PROJECTOR_DIR:-/Users/virgil/Developer/rta/tmp/markdown-projection-gitea/projector-checkout/rta-mock-docs}"
+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
+  exit 1
+fi
+
+if [ ! -d "$HOME_LAB_DIR" ]; then
+  echo "home-lab-v7 not found: $HOME_LAB_DIR" >&2
+  exit 1
+fi
+
+echo "==> Pulling projector checkout"
+git -C "$PROJECTOR_DIR" pull --ff-only
+
+echo "==> Checking projector 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
+  exit 1
+fi
+
+echo "==> Projecting Markdown into AFFiNE"
+cd "$HOME_LAB_DIR"
+nix develop --command bash -lc "scripts/ops/sync-obsidian-affine.rb \
+  --name rta-mock-docs \
+  --source '$PROJECTOR_DIR' \
+  --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"

scripts/setup-rta-mock-docs.sh

@@ -3,12 +3,20 @@ 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}"
+COMMAND_DIR="${COMMAND_DIR:-$HOME/.local/bin}"
+COMMAND_NAME="${COMMAND_NAME:-rta-mock-docs}"
+COMMAND_PATH="$COMMAND_DIR/$COMMAND_NAME"
+
+step() {
+  printf "\n==> %s\n" "$*"
+}
 
 if ! command -v git >/dev/null 2>&1; then
   echo "git is required but was not found on PATH" >&2
   exit 1
 fi
 
+step "Preparing local Markdown workspace"
 if [ -d "$TARGET_DIR/.git" ]; then
   echo "Repo already exists: $TARGET_DIR"
   git -C "$TARGET_DIR" remote set-url origin "$REPO_URL"
@@ -22,19 +30,82 @@ fi
 
 git -C "$TARGET_DIR" config pull.ff only
 
+step "Installing helper command"
+mkdir -p "$COMMAND_DIR"
+cat > "$COMMAND_PATH" <<EOF
+#!/usr/bin/env sh
+set -eu
+
+REPO_DIR="$TARGET_DIR"
+
+usage() {
+  cat <<USAGE
+rta-mock-docs - helper for the RTA mock docs projection repo
+
+Commands:
+  open      print the repo path
+  pull      pull latest Markdown with --ff-only
+  status    show Git status
+  commit    commit all current changes with MESSAGE
+  push      push current branch
+  help      show this help
+
+Examples:
+  rta-mock-docs pull
+  rta-mock-docs status
+  MESSAGE="Update concept notes" rta-mock-docs commit
+  rta-mock-docs push
+
+AFFiNE is read-only for this repo. Durable edits happen in Markdown, then the
+projection operator pulls and projects.
+USAGE
+}
+
+case "\${1:-help}" in
+  open)
+    printf "%s\n" "\$REPO_DIR"
+    ;;
+  pull)
+    git -C "\$REPO_DIR" pull --ff-only
+    ;;
+  status)
+    git -C "\$REPO_DIR" status --short --branch
+    ;;
+  commit)
+    : "\${MESSAGE:?Set MESSAGE before running commit}"
+    git -C "\$REPO_DIR" add .
+    git -C "\$REPO_DIR" commit -m "\$MESSAGE"
+    ;;
+  push)
+    git -C "\$REPO_DIR" push
+    ;;
+  help|--help|-h)
+    usage
+    ;;
+  *)
+    usage >&2
+    exit 1
+    ;;
+esac
+EOF
+chmod +x "$COMMAND_PATH"
+
 cat <<EOF
 Ready.
 
 Repo: $TARGET_DIR
 Remote: $REPO_URL
+Helper: $COMMAND_PATH
 
 Daily flow:
-  cd "$TARGET_DIR"
+  $COMMAND_NAME pull
-  git pull --ff-only
   # edit Markdown
-  git add .
+  $COMMAND_NAME status
-  git commit -m "Update docs"
+  MESSAGE="Update docs" $COMMAND_NAME commit
-  git push
+  $COMMAND_NAME push
 
 AFFiNE updates after the projection operator pulls and runs projection.
+
+If $COMMAND_DIR is not on PATH, add this to your shell profile:
+  export PATH="$COMMAND_DIR:\$PATH"
 EOF