diff --git a/README.md b/README.md
index 2320f39..b857d67 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,15 @@ npm run smoke
 
 For a reviewer-facing walkthrough, see [`docs/tutorials/review-agent-tool-expansion.md`](docs/tutorials/review-agent-tool-expansion.md). It demonstrates a prompt revision that expands browser and shell tool language, removes an explicit secret-handling guardrail, and changes the output contract.
 
+For a release-gate style demo that writes review artifacts to a temporary directory, run:
+
+```bash
+npm run build
+bash examples/release-gate-demo.sh
+```
+
+The demo intentionally expects the compare command to exit `2` because `--fail-on high` catches the risky prompt expansion. See [`docs/tutorials/prompt-release-gate.md`](docs/tutorials/prompt-release-gate.md) for the walkthrough and [`docs/promo/release-gate-social-hooks.md`](docs/promo/release-gate-social-hooks.md) for grounded launch copy.
+
 To generate the walkthrough evidence in one command:
 
 ```bash
diff --git a/docs/promo/release-gate-social-hooks.md b/docs/promo/release-gate-social-hooks.md
new file mode 100644
index 0000000..5de1fe1
--- /dev/null
+++ b/docs/promo/release-gate-social-hooks.md
@@ -0,0 +1,21 @@
+# PromptDiff Release Gate Social Hooks
+
+Use these only with the checked-in `examples/release-gate-demo.sh` workflow.
+
+## Short posts
+
+1. Prompt changes can add tool access, remove guardrails, or change output contracts without looking dramatic in a normal diff. PromptDiff turns that into a local report reviewers can inspect.
+2. A small release gate for prompts: compare old/new files, fail on high-severity findings, and attach the Markdown report to the review.
+3. PromptDiff is deliberately boring: local files in, deterministic Markdown or JSON out, no telemetry or hidden network calls.
+
+## Demo thread
+
+1. Start with the risky prompt pair in `examples/prompts/tool-expansion-old.md` and `examples/prompts/tool-expansion-new.md`.
+2. Run `bash examples/release-gate-demo.sh`.
+3. Show the exit code of `2` from `--fail-on high`, then open the generated Markdown report.
+4. Point at the concrete categories: broader tool language, removed secret handling, and output contract changes.
+5. Close with the safe check command against `examples/prompts/safe.md` and `examples/rules.json`.
+
+## Video beat
+
+Open on a normal prompt diff, then switch to the generated report. The useful moment is not "AI review"; it is the named checklist that a human reviewer can act on before a prompt ships.
diff --git a/docs/tutorials/prompt-release-gate.md b/docs/tutorials/prompt-release-gate.md
new file mode 100644
index 0000000..f6da4f5
--- /dev/null
+++ b/docs/tutorials/prompt-release-gate.md
@@ -0,0 +1,26 @@
+# Prompt Release Gate
+
+This recipe shows how to use PromptDiff as a local prompt release gate before a prompt revision reaches review.
+
+## Inputs
+
+- Old prompt: `examples/prompts/tool-expansion-old.md`
+- New prompt: `examples/prompts/tool-expansion-new.md`
+- Rules file: `examples/rules.json`
+
+The new prompt intentionally expands tool language, changes the expected output shape, and removes a secret-handling guardrail. That makes it useful as a deterministic fixture for demos and CI examples.
+
+## Run the demo
+
+```sh
+npm run build
+bash examples/release-gate-demo.sh
+```
+
+The compare command is expected to exit `2` because `--fail-on high` is enabled. The script treats that as the correct gate behavior and verifies that the Markdown report was written.
+
+## What to attach to a review
+
+Attach the generated `tool-expansion-review.md` report when the gate fails. It gives reviewers a stable summary of the risky changes without requiring them to infer policy impact from a text diff alone.
+
+Use the rules check output when you want to show that a known-safe prompt still satisfies required phrases, forbidden phrases, and required sections.
diff --git a/examples/release-gate-demo.sh b/examples/release-gate-demo.sh
new file mode 100755
index 0000000..28d9573
--- /dev/null
+++ b/examples/release-gate-demo.sh
@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="${TMPDIR:-/tmp}/promptdiff-release-gate-demo"
+
+rm -rf "$OUT_DIR"
+mkdir -p "$OUT_DIR"
+cd "$ROOT_DIR"
+
+npm run build
+
+set +e
+node dist/cli.js compare \
+  examples/prompts/tool-expansion-old.md \
+  examples/prompts/tool-expansion-new.md \
+  --out "$OUT_DIR/tool-expansion-review.md" \
+  --fail-on high
+COMPARE_STATUS=$?
+set -e
+
+test "$COMPARE_STATUS" -eq 2
+test -s "$OUT_DIR/tool-expansion-review.md"
+grep -qi "tool" "$OUT_DIR/tool-expansion-review.md"
+grep -qi "high" "$OUT_DIR/tool-expansion-review.md"
+
+node dist/cli.js check examples/prompts/safe.md --rules examples/rules.json --out "$OUT_DIR/rules-check.md"
+test -s "$OUT_DIR/rules-check.md"
+grep -qi "PromptDiff" "$OUT_DIR/rules-check.md"
+
+echo "Review report: $OUT_DIR/tool-expansion-review.md"
+echo "Rules check: $OUT_DIR/rules-check.md"
+echo "Gate exit: $COMPARE_STATUS"