diff --git a/.claude/README.md b/.claude/README.md
index 324c22a1c..e39d3aeb7 100644
--- a/.claude/README.md
+++ b/.claude/README.md
@@ -116,9 +116,13 @@ Ensures consistent punctuation across documentation.
 
 **File:** `.github/workflows/docs-review.yml`
 
-**Triggers:**
-- **Automatic:** PR creation or reopen for `platform-*` directories
-- **Manual:** Workflow dispatch (see below)
+**Triggers (on-demand only):**
+- **PR comment:** Comment `/editorial-review` on any PR
+- **Manual workflow dispatch:** Via GitHub Actions UI (see below)
+- **Local:** Use `/editorial-review` command in Claude Code CLI
+
+**NOT triggered by:**
+- PR creation, updates, or commits (to conserve tokens)
 
 **How it works:**
 0. Validates bash script syntax (fails fast if scripts have errors)
@@ -187,11 +191,18 @@ When working on API documentation:
 
 ### Working with editorial content
 
-When working on documentation content:
-1. Open PR → Agents automatically review changes
-2. Review inline suggestions on affected lines
-3. Apply fixes individually or batch-apply multiple
-4. Re-run workflow manually from Actions tab if needed
+**Local development (before PR):**
+1. Make doc changes locally
+2. Run `/editorial-review <file>` in Claude Code
+3. Review findings and apply fixes
+4. Commit and push
+
+**PR review (on-demand):**
+1. Open PR with documentation changes
+2. Comment `/editorial-review` to trigger review
+3. Review inline suggestions on affected lines
+4. Apply fixes individually or batch-apply multiple
+5. Comment `/editorial-review` again to verify fixes
 
 ### Testing changes locally
 
diff --git a/.github/scripts/README.md b/.github/scripts/README.md
index 8b867a169..fde01f695 100644
--- a/.github/scripts/README.md
+++ b/.github/scripts/README.md
@@ -93,7 +93,7 @@ Converts Claude agent review findings into GitHub inline suggestions that can be
 ./post-inline-suggestions.sh <review-file> <pr-number>
 ```
 
-### Input Format
+### Input format
 
 The script expects a review file with this format:
 
@@ -131,7 +131,7 @@ corrected text here
 
 Users can then click "Commit suggestion" to apply the fix directly from the PR interface.
 
-### How It Works
+### How it works
 
 1. Parses the structured review file
 2. Groups suggestions by file and line
diff --git a/CLAUDE.md b/CLAUDE.md
index 8463ad63e..e53761bfa 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -8,6 +8,10 @@ This guide covers documentation standards, editorial workflows, and Claude-power
 - **Local review** → Use `/review <file-or-directory>` → See issues before committing
 - **Apply fixes** → Address issues directly in files based on agent feedback
 
+> **Important:** Editorial reviews are **on-demand only**. They do NOT run automatically on PR creation or commits. You must explicitly trigger them by:
+> - Running `/editorial-review` locally in Claude Code, OR
+> - Commenting `/editorial-review` on a PR
+
 ## Workflows and architecture
 
 This repository uses two main Claude-powered workflows:
@@ -118,7 +122,7 @@ The agents provide a structured report with:
 3. Review full list in `all-suggestions-full.txt`
 4. Apply remaining suggestions manually
 
-## Local Review with `/review`
+## Local review with `/review`
 
 Run editorial reviews locally before opening a PR: