diff --git a/README.md b/README.md
index 8eb1259..2445a7e 100644
--- a/README.md
+++ b/README.md
@@ -272,6 +272,71 @@ Errors and exit codes:
 - Error `code` values: `CONFIG`, `AUTH`, `NOT_FOUND`, `VALIDATION`, `CONVERT`,
   `IO`, `NETWORK`, `API`.
 
+## GitHub Actions
+
+markfluence can run in CI to keep Confluence pages in sync with markdown in
+your repo: on a push to your default branch, publish the changed docs. You
+will need to know the Confluence `page_id` for each page you want to update.
+
+### Credentials
+
+Store environment variables as [encrypted secret][secrets] (never commit them).
+markfluence reads them straight from the environment — no `.env` in CI.
+
+- `CONFLUENCE_TOKEN`
+- `CONFLUENCE_URL`
+- `CONFLUENCE_USERNAME`
+
+[secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
+
+### Workflow
+
+```yaml
+name: Publish docs to Confluence
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**.md']        # only when docs change
+
+# Avoid overlapping publishes racing on the same pages.
+concurrency:
+  group: confluence-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+
+      # No release binaries are published yet, so install from source. Pin a tag
+      # (…@v1.2.3) once releases exist, rather than @latest, for reproducibility.
+      - name: Install markfluence
+        run: go install github.com/mozilla/markfluence@latest
+
+      - name: Publish
+        env:
+          CONFLUENCE_URL: ${{ secrets.CONFLUENCE_URL }}
+          CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }}
+          CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }}
+        run:
+          markfluence update --page-id=12345 --force docs/some_doc.md
+```
+
+Notes:
+
+- **Exit codes.** `update` exits non-zero if any file fails, so the job fails
+  loudly. Add `--json` to get machine-readable per-file results on stdout (see
+  [`--json` output](#--json-output)) if a later step needs to parse them.
+
+A reusable composite/Docker action wrapping this is tracked in
+[#29](https://github.com/mozilla/markfluence/issues/29).
+
 ## Markdown page structure
 
 Each Markdown file is one Confluence page: an optional YAML **frontmatter** block
@@ -363,7 +428,8 @@ URL; **heading anchors** are rewritten to Confluence's anchor scheme.
 **Comment directives:**
 - `<!-- confluence-toc -->` — table-of-contents macro.
 - `<!-- markfluence-version -->` — replaced with the build stamp,
-  `markfluence vVERSION COMMITDATE`.
+  `markfluence VERSION (SHA, DATE)` (the same string `markfluence --version`
+  prints).
 
 **Raw Confluence storage format.** You can paste Confluence
 [storage format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html)