Pause AFFiNE projection in contributor docs

README.md

@@ -2,16 +2,18 @@
 
 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.
+1. Read the current source in Git.
+   This repo is the source of truth for the shared Markdown docs.
 
 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.
+If you want to change one of these docs, edit the Markdown file.
+
+AFFiNE projection is paused while the native writer is rebuilt. Earlier AFFiNE
+copies may exist, but they should be treated as stale research artifacts rather
+than the current reading surface.
 
 ## What To Edit
 
@@ -63,12 +65,12 @@ section0-docs pull
 section0-docs status
 MESSAGE="Describe the doc change" section0-docs commit
 section0-docs push
+section0-docs wait
 ```
 
-By default, `section0-docs push` waits for the projected commit to pass backend
-verification and AFFiNE native read verification. If an already-open AFFiNE tab
-still shows old content, reload the tab or open the printed doc URL in a fresh
-tab.
+`section0-docs push` updates Git. `section0-docs wait` reports projection state;
+for now it should say the AFFiNE writer is frozen. That is expected until the
+native AFFiNE writer replaces the old direct database experiment.
 
 ## Contributor Setup
 

scripts/setup-section0-docs.sh

@@ -60,7 +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
+  wait      show AFFiNE projection state for a pushed commit
   push-test prove write access with a temporary remote branch
   trace     show local/origin state and recent helper events
   help      show this help
@@ -79,8 +79,8 @@ Examples:
   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.
+AFFiNE is read-only for these docs. Make lasting changes in Markdown.
+AFFiNE projection is currently paused until the native writer is ready.
 USAGE
 }
 
@@ -173,6 +173,8 @@ wait_for_projection() {
       backend_ok="\$(printf "%s" "\$status_json" | json_get verification.backend.ok 2>/dev/null || true)"
       native_ok="\$(printf "%s" "\$status_json" | json_get verification.nativeRead.ok 2>/dev/null || true)"
       browser_status="\$(printf "%s" "\$status_json" | json_get verification.browserFreshness.status 2>/dev/null || true)"
+      writer_status="\$(printf "%s" "\$status_json" | json_get writer.status 2>/dev/null || true)"
+      writer_note="\$(printf "%s" "\$status_json" | json_get writer.note 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 []:
@@ -180,7 +182,14 @@ for doc in (data.get("projected") or {}).get("docs") or []:
         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}"
+      printf "  writer: %s\n" "\${writer_status:-unknown}"
       printf "  verification: backend=%s native-read=%s browser=%s\n" "\${backend_ok:-unknown}" "\${native_ok:-unknown}" "\${browser_status:-not_verified}"
+      if [ "\$state" = "writer-frozen" ] || [ "\$writer_status" = "frozen" ]; then
+        echo "AFFiNE projection is paused. Your Git push is still the source of truth."
+        [ -z "\$writer_note" ] || echo "Reason: \$writer_note"
+        json_log "wait.writer_frozen" "\$expected"
+        return 2
+      fi
       if [ "\$projected_commit" = "\$expected" ] && { [ "\$backend_ok" = "True" ] || [ "\$backend_ok" = "true" ]; } && { [ "\$native_ok" = "True" ] || [ "\$native_ok" = "true" ]; }; then
         echo "Projected and verified through AFFiNE backend and native read."
         [ -z "\$readme_url" ] || echo "Doc: \$readme_url"