[Kiran01bm]

Switches the copy-and-swap operator guide and the other operator-facing docs from --quiesced to --block-writes SCHEMA.TABLE, which #260 renamed the flag to.

Why

#263 merged the copy-and-swap guide while it still used --quiesced. That flag no longer exists: the CLI rejects it as an unknown flag. An operator following the guide, the README's migrate row, or the CLI output examples therefore hits a usage error. Some operator-facing prose in the integration and engine-role docs still said "quiesced run" for what the CLI now calls a run that blocks writes.

What

• docs/copy-and-swap.md:
  • "Live or quiesced" becomes "Live or offline", with the offline column headed --block-writes SCHEMA.TABLE.
  • New paragraph on why the flag names the table: any other table stops the run before anything executes.
  • The run and restart examples use --block-writes public.order_archive, and the JSON detail is recaptured from main's build ("writes to the table were blocked for the length of the run").
  • The resume row says to pass --block-writes again.
• README.md migrate row, docs/README.md index, and docs/cli-output-examples.md: --block-writes, with the link pointing to the new #live-or-offline anchor.
• docs/schemabot-integration.md and docs/engine-role.md: operator-facing "quiesced run/row" becomes "a run that blocks writes". Where the docs map to the engine (cutover-unfenced, the Runner), "quiesced target" stays, since that is the engine's own term.
• pkg/migrate/desired_copy_swap.go: one comment says "block-writes acknowledgement".

The guide's outputs were run against PostgreSQL 16 with main's build:

• the logical-decoding refusal;
• the offline run, exit 0;
• the restart example;
• the wrong-table acknowledgement error.

Before / after

An operator on a server without logical decoding, following the guide's offline example:

Before (main)                                   After

guide: "Live or quiesced"                       guide: "Live or offline"
pg-sprite migrate --free-disk 50GiB --quiesced  pg-sprite migrate --free-disk 50GiB
  --alter 'ALTER TABLE public.order_archive …'    --block-writes public.order_archive
                                                  --alter 'ALTER TABLE public.order_archive …'
  → pg-sprite: error: unknown flag --quiesced     → executed-via-copy-and-swap; detail: "writes
    (the flag was renamed; the guide still          to the table were blocked for the length
     shows the old one)                             of the run"

🤖 Generated with Amp (Claude Opus 4.6)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-28T05:38:11.036452Z We couldn’t complete this review. Comment @codex review to try again.	66c34f5	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[JashLal]

🤖 Correctness review performed by Jash’s AI agent at head 66c34f50c039583c8118a072ec52f957f035500d.

Verdict: no actionable defect found in the documentation diff. The offline and restart examples acknowledge the same public.order_archive named by their ALTER; the resume instructions preserve the acknowledgement. The renamed #live-or-offline anchor and changed links agree, while the library-facing “quiesced target” terminology remains where it describes the Runner. The only Go change is a comment.

Verified: reviewed the complete seven-file diff, PR description, existing comments, and reported CI. All 16 checks are successful, including documentation guards, build, PostgreSQL 14–18, Supabase, and the built-artifact smoke test. The separate automated Codex review failed because of usage limits. No local build, tests, or PostgreSQL example runs were performed; exact-head surrounding source and inline-thread retrieval were unavailable. Consequently the CLI’s current acknowledgement enforcement and the recaptured output were not independently reproduced here; the author’s execution report remains supporting evidence, not a test I ran.

No required action items from this review.

Generated by Codex.

[JashLal]

🤖 Product review by Jash’s AI agent at 66c34f5.

OSS adoption: --block-writes SCHEMA.TABLE makes both the affected table and write outage explicit. Updating the runnable examples, restart command, resume instructions, and navigation together removes the old-flag usage-error path without hiding the persistent fence after interruption.

SchemaBot integration: the edits preserve the library terminology and existing outcome, refusal, and recovery contracts; no adapter API changes appear in this diff. The distinction between requested offline mode and the observed writes_blocked result remains documented, so consumers need not infer downtime from human-readable wording. No new integration action identified. This is a documentation review, without a local adapter or database run.

Generated by Codex.

[JashLal]

🤖 Approving on Jash’s behalf after the full-diff documentation review at 66c34f5. No actionable defect found; all 16 reported CI checks pass. Exact-head surrounding source and inline threads were unavailable, and no local build, tests or database examples ran. Verification limits are disclosed in the comments. Generated by Codex.