diff --git a/scripts/setup-section0-docs.sh b/scripts/setup-section0-docs.sh
index f8a0c8d..7ae6649 100755
--- a/scripts/setup-section0-docs.sh
+++ b/scripts/setup-section0-docs.sh
@@ -7,6 +7,7 @@ COMMAND_DIR="${COMMAND_DIR:-$HOME/.local/bin}"
 COMMAND_NAME="${COMMAND_NAME:-section0-docs}"
 COMMAND_PATH="$COMMAND_DIR/$COMMAND_NAME"
 SERVER_URL="${SECTION0_SERVER_URL:-https://ops.virgil.info/md-to-section0-api}"
+STATUS_URL="${SECTION0_STATUS_URL:-https://ops.virgil.info/section0/projection-status.json}"
 
 step() {
   printf "\n==> %s\n" "$*"
@@ -39,6 +40,7 @@ set -eu
 
 REPO_DIR="$TARGET_DIR"
 SERVER_URL="$SERVER_URL"
+STATUS_URL="$STATUS_URL"
 SESSION_DIR="\${SECTION0_SESSION_DIR:-\$HOME/.config/section0-docs}"
 SESSION_PATH="\$SESSION_DIR/session.json"
 EVENTS_PATH="\$SESSION_DIR/events.jsonl"
@@ -58,6 +60,7 @@ Commands:
   status    show Git status
   commit    commit all current changes with MESSAGE
   push      push current branch
+  wait      wait for a pushed commit to reach AFFiNE
   push-test prove write access with a temporary remote branch
   trace     show local/origin state and recent helper events
   help      show this help
@@ -74,6 +77,7 @@ Examples:
   section0-docs trace
   MESSAGE="Update concept notes" section0-docs commit
   section0-docs push
+  section0-docs wait
 
 AFFiNE is read-only for these docs. Make lasting changes in Markdown; the
 AFFiNE copies are refreshed from Git.
@@ -147,6 +151,54 @@ http_json() {
   curl --connect-timeout 5 --max-time 15 -fsS "\$@"
 }
 
+projection_status() {
+  http_json "\$STATUS_URL"
+}
+
+wait_for_projection() {
+  expected="\${1:-}"
+  [ -n "\$expected" ] || expected="\$(git -C "\$REPO_DIR" rev-parse --short HEAD)"
+  timeout_seconds="\${SECTION0_WAIT_TIMEOUT_SECONDS:-180}"
+  started_at="\$(date +%s)"
+  echo "Waiting for AFFiNE projection:"
+  echo "  commit: \$expected"
+  echo "  status: \$STATUS_URL"
+  while :; do
+    status_json="\$(projection_status 2>/dev/null || true)"
+    if [ -n "\$status_json" ]; then
+      state="\$(printf "%s" "\$status_json" | json_get state 2>/dev/null || true)"
+      origin_commit="\$(printf "%s" "\$status_json" | json_get source.originCommit 2>/dev/null || true)"
+      projected_commit="\$(printf "%s" "\$status_json" | json_get projected.commit 2>/dev/null || true)"
+      completed_at="\$(printf "%s" "\$status_json" | json_get projected.completedAt 2>/dev/null || true)"
+      readme_url="\$(printf "%s" "\$status_json" | python3 -c 'import json,sys
+data=json.load(sys.stdin)
+for doc in (data.get("projected") or {}).get("docs") or []:
+    if doc.get("sourcePath") == "README.md":
+        print(doc.get("url",""))
+        break' 2>/dev/null || true)"
+      printf "  origin=%s projected=%s state=%s%s\n" "\${origin_commit:-unknown}" "\${projected_commit:-none}" "\${state:-unknown}" "\${completed_at:+ completed=\$completed_at}"
+      if [ "\$projected_commit" = "\$expected" ]; then
+        echo "Projected and verified in AFFiNE."
+        [ -z "\$readme_url" ] || echo "Doc: \$readme_url"
+        echo "If a browser tab still shows old content, reload the AFFiNE tab or open the doc URL in a fresh tab."
+        json_log "wait.complete" "\$expected"
+        return 0
+      fi
+    else
+      echo "  projection status not reachable yet"
+    fi
+    now="\$(date +%s)"
+    elapsed=\$((now - started_at))
+    if [ "\$elapsed" -ge "\$timeout_seconds" ]; then
+      echo "Timed out after \${timeout_seconds}s waiting for projection of \$expected." >&2
+      echo "Run again later: section0-docs wait" >&2
+      json_log "wait.timeout" "\$expected"
+      return 1
+    fi
+    sleep "\${SECTION0_WAIT_INTERVAL_SECONDS:-5}"
+  done
+}
+
 install_git_credential() {
   remote="\$1"
   username="\$2"
@@ -364,7 +416,15 @@ case "\${1:-help}" in
     origin_head="\$(git -C "\$REPO_DIR" rev-parse --short origin/main 2>/dev/null || true)"
     json_log "push.complete" "\${origin_head:-\$before}"
     echo "Pushed commit: \${origin_head:-\$before}"
-    echo "AFFiNE updates after the operator refresh runs."
+    if [ "\${SECTION0_WAIT_AFTER_PUSH:-1}" = "1" ]; then
+      wait_for_projection "\${origin_head:-\$before}"
+    else
+      echo "AFFiNE updates after the operator refresh runs."
+      echo "To watch it: section0-docs wait"
+    fi
+    ;;
+  wait)
+    wait_for_projection "\${2:-}"
     ;;
   push-test)
     branch="section0-smoke-\${USER:-user}-\$(date +%Y%m%d%H%M%S)"
@@ -376,6 +436,7 @@ case "\${1:-help}" in
   trace)
     echo "Repo: \$REPO_DIR"
     echo "Remote: \$(git -C "\$REPO_DIR" remote get-url origin)"
+    echo "Projection status: \$STATUS_URL"
     echo "Branch: \$(git -C "\$REPO_DIR" branch --show-current)"
     echo "Local HEAD: \$(git -C "\$REPO_DIR" rev-parse --short HEAD)"
     git -C "\$REPO_DIR" fetch origin >/dev/null 2>&1 || true
@@ -416,12 +477,14 @@ Daily flow:
   $COMMAND_NAME status
   MESSAGE="Update docs" $COMMAND_NAME commit
   $COMMAND_NAME push
+  $COMMAND_NAME wait
 
 Contributor setup:
   $COMMAND_NAME configure
   $COMMAND_NAME push-test
 
-AFFiNE updates after the Markdown docs are refreshed from Git.
+By default, push waits until the operator projection status says the commit has
+been projected and verified in AFFiNE.
 
 If $COMMAND_DIR is not on PATH, add this to your shell profile:
   export PATH="$COMMAND_DIR:\$PATH"