docs: promote review fix quickstart update to main

AGENTS.md

@@ -21,6 +21,9 @@ These rules apply to AI agents working in this repository.
   - `build/`
   - `revert/`
 - Prefer small PRs with one clear purpose.
+- Promotion PRs from `dev` to `main` should use a merge commit, not squash
+  merge. If a promotion is squashed, sync `main` back into `dev` before opening
+  the next promotion PR.
 
 ## Docs-first and issue-first workflow
 

README.md

@@ -34,6 +34,7 @@ Codeflow helps Pi Coding Agent follow a conservative repository lifecycle:
   -> fix valid review findings
   -> /flow-check
   -> /flow-commit
+  -> /flow-pr
   -> /flow-watch
   -> /flow-fix-comments
 ```

docs/RELEASE_PROCESS.md

@@ -12,6 +12,25 @@ The release process is planned for a future milestone.
 CI validation should pass before merging feature work into `dev` and before
 promoting `dev` to `main`.
 
+## Promotion merge policy
+
+Use a merge commit for `dev` to `main` promotion PRs. Squash-merging promotion
+PRs makes `main` and `dev` diverge, which can create conflicts on the next
+promotion PR even when file content is already aligned.
+
+Open the promotion PR from `dev` itself, or from a branch that preserves `dev`
+ancestry. Do not copy the `dev` tree onto `main` as a single-parent commit.
+
+Before opening a promotion PR, fetch and confirm `main` is already in `dev`:
+
+```sh
+git fetch origin --prune
+git merge-base --is-ancestor origin/main origin/dev
+```
+
+If the check fails because a previous promotion was squashed, sync `main` back
+into `dev` before opening the next promotion PR.
+
 No automated publishing should be added until implementation, CI, and security
 review are ready.
 

docs/USAGE.md

@@ -84,15 +84,42 @@ resolution.
     /flow-comments
     ```
 
-13. After fixing valid review comments and running checks again, preview and
-    apply safe replies or resolutions:
+13. After fixing valid review comments, run checks again:
+
+    ```text
+    /flow-check
+    ```
+
+14. Stage the intended review-fix changes.
+
+15. Prepare a fresh commit payload for the review-fix commit.
+
+16. Commit the review fix:
+
+    ```text
+    /flow-commit --payload .pi/codeflow/commit-payload.json
+    ```
+
+17. Update the PR with the review-fix commit:
+
+    ```text
+    /flow-pr --payload .pi/codeflow/pr-payload.json
+    ```
+
+18. Watch checks for the updated PR:
+
+    ```text
+    /flow-watch --required
+    ```
+
+19. Preview and apply safe replies or resolutions:
 
     ```text
     /flow-fix-comments --dry-run --payload .pi/codeflow/review-comment-fix.json
     /flow-fix-comments --apply --payload .pi/codeflow/review-comment-fix.json
     ```
 
-14. Final human review and merge remain outside Codeflow.
+20. Final human review and merge remain outside Codeflow.
 
 ## Recommended AI-agent workflow