From 265652e7f450d8a4043dae486959ad44f2c75ce5 Mon Sep 17 00:00:00 2001
From: PandaHUN777 <117030640+PandaHUN777@users.noreply.github.com>
Date: Thu, 1 Oct 2026 23:19:21 +0200
Subject: [PATCH] docs: add GitHub Action consumer example

---
 docs/GITHUB_ACTION.md               |  4 ++
 examples/github-action-consumer.yml | 59 +++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 examples/github-action-consumer.yml

diff --git a/docs/GITHUB_ACTION.md b/docs/GITHUB_ACTION.md
index 31aa1c96..293fc863 100644
--- a/docs/GITHUB_ACTION.md
+++ b/docs/GITHUB_ACTION.md
@@ -18,6 +18,10 @@ AETHERXGLOBAL/execsurface@v0.1.0-alpha.5
 
 Do not use `@main` as the normal consumer path.
 
+## Copy-ready consumer example
+
+See [the external consumer workflow](../examples/github-action-consumer.yml) for a complete check-only example. Initialize the workflow once, create and review the baseline explicitly, then commit it for the workflow to check. The workflow never creates, changes, or approves a baseline.
+
 ## Minimal workflow
 
 ```yaml
diff --git a/examples/github-action-consumer.yml b/examples/github-action-consumer.yml
new file mode 100644
index 00000000..cf6015b8
--- /dev/null
+++ b/examples/github-action-consumer.yml
@@ -0,0 +1,59 @@
+# Copy this file to .github/workflows/execsurface.yml in a consumer repository.
+# One-time setup: execsurface init --command "git diff --check" --github-actions
+# Create a baseline explicitly with:
+#   execsurface learn --output execsurface.lock.json -- /bin/bash -lc "git diff --check"
+# Review and commit the baseline deliberately; this workflow only checks it.
+# Stable public-alpha channel: @v0.1
+# Immutable Alpha.5 review pin: replace @v0.1 with @v0.1.0-alpha.5.
+# Full behavior and limitations: ../docs/GITHUB_ACTION.md
+
+name: ExecSurface
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  execsurface:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check out the consumer repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Check the explicitly reviewed baseline
+        id: execsurface
+        uses: AETHERXGLOBAL/execsurface@v0.1
+        with:
+          command: "git diff --check"
+          baseline: execsurface.lock.json
+          fail-on-review: "true"
+          upload-artifact: "false"
+
+      - name: Report the ExecSurface verdict
+        if: always()
+        shell: bash
+        env:
+          VERDICT: ${{ steps.execsurface.outputs.verdict }}
+          EXIT_CODE: ${{ steps.execsurface.outputs.exit-code }}
+        run: |
+          case "$VERDICT" in
+            pass)
+              echo "ExecSurface: PASS"
+              ;;
+            review)
+              echo "::warning::ExecSurface: REVIEW (fail-on-review is enabled; exit $EXIT_CODE)"
+              ;;
+            block)
+              echo "::error::ExecSurface: BLOCK (exit $EXIT_CODE)"
+              exit 20
+              ;;
+            error)
+              echo "::error::ExecSurface: ERROR (exit $EXIT_CODE)"
+              exit 2
+              ;;
+            *)
+              echo "::error::ExecSurface returned an unknown verdict"
+              exit 2
+              ;;
+          esac