diff --git a/.github/workflows/CLAUDE.md b/.github/workflows/CLAUDE.md
new file mode 100644
index 0000000..480ac97
--- /dev/null
+++ b/.github/workflows/CLAUDE.md
@@ -0,0 +1 @@
+When modifying any workflow file in this directory, update README.md to reflect the changes. This includes the mermaid diagram, the workflow table, and the notes section.
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
new file mode 100644
index 0000000..7383163
--- /dev/null
+++ b/.github/workflows/README.md
@@ -0,0 +1,51 @@
+# CI Workflows
+
+```mermaid
+flowchart LR
+    PR["Pull Request"] -->|"*.rs, Cargo.*"| Tests
+    PR -->|"docs/**"| Docs
+
+    Push["Push to main"] --> Release
+    Manual["Manual dispatch"] --> Release
+
+    subgraph Tests["Tests Workflow"]
+        T1["build, check, test, fmt, clippy<br/><i>ubuntu-latest</i>"]
+    end
+
+    subgraph Docs["Docs Workflow"]
+        D1["Build docs via workflow_call"]
+    end
+
+    subgraph Release["Release Workflow"]
+        direction TB
+        R1["Prepare Release<br/><i>ubuntu-latest</i>"]
+        R2["Push Release Branch + Tag<br/><i>gusto-ubuntu</i>"]
+        R3["Build 4 targets in parallel<br/><i>ubuntu-latest + macos-latest</i>"]
+        R4["Create GitHub Release<br/><i>gusto-ubuntu</i>"]
+        R5["Deploy GitHub Pages<br/><i>ubuntu-latest</i>"]
+        R1 --> R2 --> R3 --> R4 --> R5
+    end
+
+    subgraph Pages["Build Github Pages"]
+        direction TB
+        P1["Build Docusaurus site"] --> P2["Deploy to Pages"]
+    end
+
+    Docs --> Pages
+    R5 --> Pages
+```
+
+## Workflow files
+
+| File | Trigger | What it does |
+|---|---|---|
+| `test.yml` | PR (Rust/Cargo files) | cargo build, check, test, fmt, clippy |
+| `docs.yml` | PR (docs/ files) | Calls `gh-page.yml` to verify docs build |
+| `release.yml` | Push to main, manual dispatch | CalVer stamp, cross-compile 4 targets, create GitHub release, deploy Pages |
+| `gh-page.yml` | `workflow_call` only | Build Docusaurus site and deploy to GitHub Pages |
+
+## Notes
+
+- **Runner split**: Most jobs use GitHub-hosted runners (`ubuntu-latest`, `macos-latest`). Jobs that need write access (git push, release creation) use `gusto-ubuntu-default` due to the Gusto org IP allow list.
+- **Version format**: CalVer `YEAR.MONTH.DAY+HHMM` (e.g., `2026.4.7+1823`). The `+HHMM` build metadata is ignored by Cargo for version comparison but ensures unique tags. See the comment in `release.yml` for details.
+- **Pages deployment**: Triggered by the Release workflow via `workflow_call`, not by tag patterns.
diff --git a/.github/workflows/gh-page.yml b/.github/workflows/gh-page.yml
index 7154dd7..a05e555 100644
--- a/.github/workflows/gh-page.yml
+++ b/.github/workflows/gh-page.yml
@@ -1,9 +1,6 @@
 name: Build Github Pages
 
 on:
-  push:
-    tags:
-      - '**[0-9]+.[0-9]+.[0-9]+*'
   workflow_call:
 
 jobs:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 748d25a..8451537 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -161,3 +161,8 @@ jobs:
             --title "v${VERSION}" \
             --notes "" \
             artifacts/*.tar.gz
+
+  pages:
+    name: Deploy Github Pages
+    needs: release
+    uses: ./.github/workflows/gh-page.yml
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 0b57ae7..be0b40e 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -8,14 +8,14 @@ const config: Config = {
   // favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
-  url: 'https://oscope-dev.github.io/',
+  url: 'https://docs.gusto.com',
   // Set the /<baseUrl>/ pathname under which your site is served
   // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/scope',
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'oscope-dev', // Usually your GitHub org/user name.
+  organizationName: 'Gusto', // Usually your GitHub org/user name.
   projectName: 'scope', // Usually your repo name.
 
   onBrokenLinks: 'throw',
@@ -41,7 +41,7 @@ const config: Config = {
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
-            'https://github.com/oscope-dev/scope/tree/main/docs/',
+            'https://github.com/Gusto/scope/tree/main/docs/',
         },
         theme: {
           customCss: './src/css/custom.css',
@@ -72,7 +72,7 @@ const config: Config = {
           label: 'Docs',
         },
         {
-          href: 'https://github.com/oscope-dev/scope',
+          href: 'https://github.com/Gusto/scope',
           label: 'GitHub',
           position: 'right',
         },
@@ -95,7 +95,7 @@ const config: Config = {
           items: [
             {
               label: 'GitHub',
-              href: 'https://github.com/oscope-dev/scope',
+              href: 'https://github.com/Gusto/scope',
             },
           ],
         },