From 2fa27db9d3167c8640b768bf7b98472a0d531c6f Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Thu, 11 Jun 2026 17:35:44 -0400
Subject: [PATCH 01/10] docs: restructure surface docs into landing + workflow
 + sub-components
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each surface in workflows-overview/ now lives in its own subfolder with
three pages — a landing that mirrors the Companies pattern, a workflow
page for the drop-in flow component, and a sub-components page with
human-readable section headings.

- New top-level landings: companies, employees, contractors, payroll
- Per-surface landings for company-onboarding, information-requests,
  employee-onboarding, employee-self-onboarding, contractor-onboarding,
  contractor-payments, run-payroll, off-cycle-payroll, dismissal-payroll,
  transition-payroll
- New LinkCardGrid component drives each landing's card grid
- Surfaces sidebar entry is a non-collapsible section header; active
  state styling pins highlight to the actual current page only
- Renamed sub-component headings from Component.Name to human-readable
  equivalents (Company.AssignSignatory -> Assign a signatory, etc.)
- Updated SurfacesGrid card targets, README.md, and inbound cross-refs

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                                     |  16 +-
 docs-site/sidebars.ts                         | 224 +++++++++++++++---
 .../src/components/LinkCardGrid/index.tsx     |  34 +++
 .../components/LinkCardGrid/styles.module.css |  84 +++++++
 .../src/components/SurfacesGrid/index.tsx     |  45 ++++
 .../components/SurfacesGrid/styles.module.css |  61 +++++
 docs-site/src/css/custom.css                  |  14 +-
 docs/integration-guide/composition.md         |   2 +-
 docs/workflows-overview/companies.mdx         |  19 ++
 .../company-onboarding/company-onboarding.mdx | 111 +++++++++
 .../sub-components.md}                        | 118 ++++-----
 .../company-onboarding/workflow.md            |  34 +++
 .../contractor-onboarding.mdx                 |  61 +++++
 .../sub-components.md}                        |  68 ++----
 .../contractor-onboarding/workflow.md         |  36 +++
 .../contractor-payments.mdx                   |  56 +++++
 .../sub-components.md}                        | 134 +++--------
 .../contractor-payments/workflow.md           |  81 +++++++
 docs/workflows-overview/contractors.mdx       |  19 ++
 .../dismissal-payroll/dismissal-payroll.mdx   |  37 +++
 .../dismissal-payroll/sub-components.md       |  24 ++
 .../workflow.md}                              |  60 ++---
 .../employee-onboarding.mdx                   |  78 ++++++
 ...ployee-onboarding.md => sub-components.md} |  87 +++----
 .../employee-onboarding/workflow.md           |  38 +++
 .../employee-self-onboarding.mdx              |  71 ++++++
 .../sub-components.md}                        |  97 +++-----
 .../employee-self-onboarding/workflow.md      |  37 +++
 docs/workflows-overview/employees.mdx         |  19 ++
 .../information-requests.md                   | 141 -----------
 .../information-requests.mdx                  |  41 ++++
 .../information-requests/sub-components.md    |  94 ++++++++
 .../information-requests/workflow.md          |  55 +++++
 docs/workflows-overview/off-cycle-payroll.md  | 172 --------------
 .../off-cycle-payroll/off-cycle-payroll.mdx   |  46 ++++
 .../off-cycle-payroll/sub-components.md       | 114 +++++++++
 .../off-cycle-payroll/workflow.md             |  71 ++++++
 docs/workflows-overview/payroll.mdx           |  31 +++
 .../run-payroll/run-payroll.mdx               |  86 +++++++
 .../sub-components.md}                        | 155 +++++-------
 .../run-payroll/workflow.md                   |  58 +++++
 .../transition-payroll/sub-components.md      |  58 +++++
 .../transition-payroll/transition-payroll.mdx |  36 +++
 .../workflow.md}                              |  96 ++------
 docs/workflows-overview/workflows-overview.md |  56 -----
 .../workflows-overview/workflows-overview.mdx |  11 +
 46 files changed, 2141 insertions(+), 945 deletions(-)
 create mode 100644 docs-site/src/components/LinkCardGrid/index.tsx
 create mode 100644 docs-site/src/components/LinkCardGrid/styles.module.css
 create mode 100644 docs-site/src/components/SurfacesGrid/index.tsx
 create mode 100644 docs-site/src/components/SurfacesGrid/styles.module.css
 create mode 100644 docs/workflows-overview/companies.mdx
 create mode 100644 docs/workflows-overview/company-onboarding/company-onboarding.mdx
 rename docs/workflows-overview/{company-onboarding.md => company-onboarding/sub-components.md} (93%)
 create mode 100644 docs/workflows-overview/company-onboarding/workflow.md
 create mode 100644 docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
 rename docs/workflows-overview/{contractor-onboarding.md => contractor-onboarding/sub-components.md} (85%)
 create mode 100644 docs/workflows-overview/contractor-onboarding/workflow.md
 create mode 100644 docs/workflows-overview/contractor-payments/contractor-payments.mdx
 rename docs/workflows-overview/{contractor-payments.md => contractor-payments/sub-components.md} (64%)
 create mode 100644 docs/workflows-overview/contractor-payments/workflow.md
 create mode 100644 docs/workflows-overview/contractors.mdx
 create mode 100644 docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
 create mode 100644 docs/workflows-overview/dismissal-payroll/sub-components.md
 rename docs/workflows-overview/{dismissal-payroll.md => dismissal-payroll/workflow.md} (69%)
 create mode 100644 docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
 rename docs/workflows-overview/employee-onboarding/{employee-onboarding.md => sub-components.md} (88%)
 create mode 100644 docs/workflows-overview/employee-onboarding/workflow.md
 create mode 100644 docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
 rename docs/workflows-overview/{employee-onboarding/employee-self-onboarding.md => employee-self-onboarding/sub-components.md} (65%)
 create mode 100644 docs/workflows-overview/employee-self-onboarding/workflow.md
 create mode 100644 docs/workflows-overview/employees.mdx
 delete mode 100644 docs/workflows-overview/information-requests.md
 create mode 100644 docs/workflows-overview/information-requests/information-requests.mdx
 create mode 100644 docs/workflows-overview/information-requests/sub-components.md
 create mode 100644 docs/workflows-overview/information-requests/workflow.md
 delete mode 100644 docs/workflows-overview/off-cycle-payroll.md
 create mode 100644 docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
 create mode 100644 docs/workflows-overview/off-cycle-payroll/sub-components.md
 create mode 100644 docs/workflows-overview/off-cycle-payroll/workflow.md
 create mode 100644 docs/workflows-overview/payroll.mdx
 create mode 100644 docs/workflows-overview/run-payroll/run-payroll.mdx
 rename docs/workflows-overview/{run-payroll.md => run-payroll/sub-components.md} (73%)
 create mode 100644 docs/workflows-overview/run-payroll/workflow.md
 create mode 100644 docs/workflows-overview/transition-payroll/sub-components.md
 create mode 100644 docs/workflows-overview/transition-payroll/transition-payroll.mdx
 rename docs/workflows-overview/{transition-payroll.md => transition-payroll/workflow.md} (54%)
 delete mode 100644 docs/workflows-overview/workflows-overview.md
 create mode 100644 docs/workflows-overview/workflows-overview.mdx

diff --git a/README.md b/README.md
index b7a303ad7..a7cd052a7 100644
--- a/README.md
+++ b/README.md
@@ -54,17 +54,17 @@ See the [SDK Dev App README](sdk-app/README.md) for full setup and usage details
   - [Proxy Examples](docs/reference/proxy-examples.md)
 - [Workflows Overview](docs/workflows-overview/workflows-overview.md)
   - [Company Onboarding](docs/workflows-overview/company-onboarding.md)
-  - [Contractor Onboarding](docs/workflows-overview/contractor-onboarding.md)
-  - [Contractor Payments](docs/workflows-overview/contractor-payments.md)
-  - [Employee Onboarding](docs/workflows-overview/employee-onboarding/employee-onboarding.md)
-    - [Employee Self-Onboarding](docs/workflows-overview/employee-onboarding/employee-self-onboarding.md)
+  - [Contractor Onboarding](docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx)
+  - [Contractor Payments](docs/workflows-overview/contractor-payments/contractor-payments.mdx)
+  - [Employee Onboarding](docs/workflows-overview/employee-onboarding/employee-onboarding.mdx)
+    - [Employee Self-Onboarding](docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx)
   - [Employee Dashboard](docs/workflows-overview/employee-dashboard.md)
   - [Employee Termination](docs/workflows-overview/employee-termination.md)
   - [Information Requests](docs/workflows-overview/information-requests.md)
-  - [Run Payroll](docs/workflows-overview/run-payroll.md)
-  - [Off-Cycle Payroll (Bonus & Correction)](docs/workflows-overview/off-cycle-payroll.md)
-  - [Dismissal Payroll](docs/workflows-overview/dismissal-payroll.md)
-  - [Transition Payroll](docs/workflows-overview/transition-payroll.md)
+  - [Run Payroll](docs/workflows-overview/run-payroll/run-payroll.mdx)
+  - [Off-Cycle Payroll (Bonus & Correction)](docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx)
+  - [Dismissal Payroll](docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx)
+  - [Transition Payroll](docs/workflows-overview/transition-payroll/transition-payroll.mdx)
 - [Hooks (Experimental)](docs/hooks/hooks.md)
   - [useEmployeeDetailsForm](docs/hooks/useEmployeeDetailsForm.md)
   - [useCompensationForm](docs/hooks/useCompensationForm.md)
diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index fabef36c8..efea1fb17 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -6,95 +6,249 @@ const sidebars: SidebarsConfig = {
       type: 'category',
       label: 'Getting Started',
       link: { type: 'doc', id: 'getting-started/getting-started' },
-      collapsed: false,
+      collapsed: true,
       items: ['getting-started/authentication', 'getting-started/proxy-security-partner-guidance'],
     },
+    // {
+    //   type: 'category',
+    //   label: 'Deciding to build with the SDK',
+    //   link: { type: 'doc', id: 'deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk' },
+    //   items: [
+    //     'deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api',
+    //     'deciding-to-build-with-the-sdk/component-types',
+    //   ],
+    // },
     {
       type: 'category',
-      label: 'Deciding to build with the SDK',
-      link: { type: 'doc', id: 'deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk' },
-      items: [
-        'deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api',
-        'deciding-to-build-with-the-sdk/component-types',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Workflows',
+      label: 'Surfaces',
       link: { type: 'doc', id: 'workflows-overview/workflows-overview' },
-      collapsed: false,
+      collapsible: false,
       items: [
         {
           type: 'category',
           label: 'Companies',
+          link: { type: 'doc', id: 'workflows-overview/companies' },
           items: [
             {
-              type: 'doc',
-              id: 'workflows-overview/company-onboarding',
-              label: 'Company onboarding',
+              type: 'category',
+              label: 'Onboard a company',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/company-onboarding/company-onboarding',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/company-onboarding/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/company-onboarding/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/information-requests',
+              type: 'category',
               label: 'Information requests',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/information-requests/information-requests',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/information-requests/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/information-requests/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
           ],
         },
         {
           type: 'category',
           label: 'Employees',
+          link: { type: 'doc', id: 'workflows-overview/employees' },
           items: [
             {
-              type: 'doc',
-              id: 'workflows-overview/employee-onboarding/employee-onboarding',
-              label: 'Employee onboarding',
+              type: 'category',
+              label: 'Onboard an employee',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/employee-onboarding/employee-onboarding',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/employee-onboarding/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/employee-onboarding/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/employee-onboarding/employee-self-onboarding',
+              type: 'category',
               label: 'Employee self-onboarding',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/employee-self-onboarding/employee-self-onboarding',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/employee-self-onboarding/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/employee-self-onboarding/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
           ],
         },
         {
           type: 'category',
           label: 'Contractors',
+          link: { type: 'doc', id: 'workflows-overview/contractors' },
           items: [
             {
-              type: 'doc',
-              id: 'workflows-overview/contractor-onboarding',
-              label: 'Conractor onboarding',
+              type: 'category',
+              label: 'Contractor onboarding',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/contractor-onboarding/contractor-onboarding',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/contractor-onboarding/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/contractor-onboarding/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/contractor-payments',
+              type: 'category',
               label: 'Contractor payments',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/contractor-payments/contractor-payments',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/contractor-payments/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/contractor-payments/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
           ],
         },
         {
           type: 'category',
           label: 'Payroll',
+          link: { type: 'doc', id: 'workflows-overview/payroll' },
           items: [
             {
-              type: 'doc',
-              id: 'workflows-overview/run-payroll',
+              type: 'category',
               label: 'Payroll processing',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/run-payroll/run-payroll',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/run-payroll/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/run-payroll/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/off-cycle-payroll',
+              type: 'category',
               label: 'Off-cycle payroll',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/off-cycle-payroll/off-cycle-payroll',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/off-cycle-payroll/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/off-cycle-payroll/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/dismissal-payroll',
+              type: 'category',
               label: 'Dismissal payroll',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/dismissal-payroll/dismissal-payroll',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/dismissal-payroll/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/dismissal-payroll/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
             {
-              type: 'doc',
-              id: 'workflows-overview/transition-payroll',
+              type: 'category',
               label: 'Transition payroll',
+              link: {
+                type: 'doc',
+                id: 'workflows-overview/transition-payroll/transition-payroll',
+              },
+              items: [
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/transition-payroll/workflow',
+                  label: 'Workflow',
+                },
+                {
+                  type: 'doc',
+                  id: 'workflows-overview/transition-payroll/sub-components',
+                  label: 'Sub-components',
+                },
+              ],
             },
           ],
         },
diff --git a/docs-site/src/components/LinkCardGrid/index.tsx b/docs-site/src/components/LinkCardGrid/index.tsx
new file mode 100644
index 000000000..c8d83d737
--- /dev/null
+++ b/docs-site/src/components/LinkCardGrid/index.tsx
@@ -0,0 +1,34 @@
+import Link from '@docusaurus/Link'
+import clsx from 'clsx'
+import type { ReactNode } from 'react'
+import styles from './styles.module.css'
+
+export interface LinkCardItem {
+  title: string
+  description: string
+  to: string
+}
+
+interface LinkCardGridProps {
+  items: LinkCardItem[]
+  columns?: 1 | 2 | 3
+}
+
+const columnClass = {
+  1: 'cols1',
+  2: 'cols2',
+  3: 'cols3',
+} as const
+
+export default function LinkCardGrid({ items, columns = 2 }: LinkCardGridProps): ReactNode {
+  return (
+    <div className={clsx(styles.grid, styles[columnClass[columns]])}>
+      {items.map(({ title, description, to }) => (
+        <Link key={`${title}-${to}`} to={to} className={styles.card}>
+          <h3 className={styles.title}>{title}</h3>
+          <p className={styles.description}>{description}</p>
+        </Link>
+      ))}
+    </div>
+  )
+}
diff --git a/docs-site/src/components/LinkCardGrid/styles.module.css b/docs-site/src/components/LinkCardGrid/styles.module.css
new file mode 100644
index 000000000..66ad1adb0
--- /dev/null
+++ b/docs-site/src/components/LinkCardGrid/styles.module.css
@@ -0,0 +1,84 @@
+.grid {
+  display: grid;
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.cols1 {
+  grid-template-columns: 1fr;
+}
+
+.cols2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+
+.cols3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+
+@media (min-width: 600px) and (max-width: 996px) {
+  .cols3 {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 996px) {
+  .cols2 {
+    grid-template-columns: 1fr;
+  }
+}
+
+@media (max-width: 600px) {
+  .cols3 {
+    grid-template-columns: 1fr;
+  }
+}
+
+.grid .card {
+  display: block;
+  padding: 2rem;
+  background-color: #ffffff;
+  border: 1px solid #ebedf0;
+  border-radius: 16px;
+  text-decoration: none;
+  color: inherit;
+  transition: border-color 0.15s ease;
+}
+
+.grid .card:hover {
+  border-color: #d0d3d8;
+  text-decoration: none;
+  color: inherit;
+}
+
+[data-theme='dark'] .grid .card {
+  background-color: rgba(255, 255, 255, 0.03);
+  border-color: rgba(255, 255, 255, 0.1);
+}
+
+[data-theme='dark'] .grid .card:hover {
+  border-color: rgba(255, 255, 255, 0.22);
+}
+
+.grid .card .title {
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: 0 0 0.5rem 0;
+  color: #1b1b1d;
+}
+
+[data-theme='dark'] .grid .card .title {
+  color: #ffffff;
+}
+
+.grid .card .description {
+  font-size: 0.95rem;
+  line-height: 1.6;
+  color: #525860;
+  margin: 0;
+}
+
+[data-theme='dark'] .grid .card .description {
+  color: rgba(255, 255, 255, 0.65);
+}
diff --git a/docs-site/src/components/SurfacesGrid/index.tsx b/docs-site/src/components/SurfacesGrid/index.tsx
new file mode 100644
index 000000000..cc13d8392
--- /dev/null
+++ b/docs-site/src/components/SurfacesGrid/index.tsx
@@ -0,0 +1,45 @@
+import Link from '@docusaurus/Link'
+import type { ReactNode } from 'react'
+import styles from './styles.module.css'
+
+interface Surface {
+  title: string
+  description: string
+  to: string
+}
+
+const surfaces: Surface[] = [
+  {
+    title: 'Companies',
+    description: 'Stand up a new company and request the information needed to run payroll.',
+    to: '/workflows-overview/companies',
+  },
+  {
+    title: 'Employees',
+    description: 'Onboard employees, manage their details, and handle terminations.',
+    to: '/workflows-overview/employees',
+  },
+  {
+    title: 'Contractors',
+    description: 'Onboard contractors and pay them on or off cycle.',
+    to: '/workflows-overview/contractors',
+  },
+  {
+    title: 'Payroll',
+    description: 'Run regular, off-cycle, dismissal, and transition payrolls.',
+    to: '/workflows-overview/payroll',
+  },
+]
+
+export default function SurfacesGrid(): ReactNode {
+  return (
+    <div className={styles.grid}>
+      {surfaces.map(({ title, description, to }) => (
+        <Link key={title} to={to} className={styles.card}>
+          <h3 className={styles.title}>{title}</h3>
+          <p className={styles.description}>{description}</p>
+        </Link>
+      ))}
+    </div>
+  )
+}
diff --git a/docs-site/src/components/SurfacesGrid/styles.module.css b/docs-site/src/components/SurfacesGrid/styles.module.css
new file mode 100644
index 000000000..9958bd58f
--- /dev/null
+++ b/docs-site/src/components/SurfacesGrid/styles.module.css
@@ -0,0 +1,61 @@
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+@media (max-width: 996px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}
+
+.grid .card {
+  display: block;
+  padding: 2rem;
+  background-color: #ffffff;
+  border: 1px solid #ebedf0;
+  border-radius: 16px;
+  text-decoration: none;
+  color: inherit;
+  transition: border-color 0.15s ease;
+}
+
+.grid .card:hover {
+  border-color: #d0d3d8;
+  text-decoration: none;
+  color: inherit;
+}
+
+[data-theme='dark'] .grid .card {
+  background-color: rgba(255, 255, 255, 0.03);
+  border-color: rgba(255, 255, 255, 0.1);
+}
+
+[data-theme='dark'] .grid .card:hover {
+  border-color: rgba(255, 255, 255, 0.22);
+}
+
+.grid .card .title {
+  font-size: 1.25rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin: 0 0 0.5rem 0;
+  color: #1b1b1d;
+}
+
+[data-theme='dark'] .grid .card .title {
+  color: #ffffff;
+}
+
+.grid .card .description {
+  font-size: 0.95rem;
+  line-height: 1.6;
+  color: #525860;
+  margin: 0;
+}
+
+[data-theme='dark'] .grid .card .description {
+  color: rgba(255, 255, 255, 0.65);
+}
diff --git a/docs-site/src/css/custom.css b/docs-site/src/css/custom.css
index eeaaf8733..780b29e76 100644
--- a/docs-site/src/css/custom.css
+++ b/docs-site/src/css/custom.css
@@ -380,18 +380,19 @@ aside.theme-doc-sidebar-container {
   margin-top: 1rem;
 }
 
-.menu__list-item-collapsible > .menu__link--active {
+.menu__list-item-collapsible > .menu__link--active:not([aria-current='page']) {
   background-color: transparent;
   color: inherit;
 }
 
-.menu__list-item-collapsible--active > .menu__link {
+.menu__list-item-collapsible > .menu__link--sublist[aria-current='page'] {
   color: var(--ifm-color-primary);
+  font-weight: 500;
 }
 
-.menu__list-item-collapsible > .menu__link--sublist.menu__link--active {
-  color: var(--ifm-color-primary);
-  font-weight: 500;
+.menu__link--sublist.menu__link--active:not([aria-current='page']) {
+  color: var(--gusto-sidebar-category-color);
+  font-weight: normal;
 }
 
 .menu__list .menu__list {
@@ -416,8 +417,7 @@ aside.theme-doc-sidebar-container {
   background-color: transparent;
 }
 
-.menu__list-item-collapsible:has(> .menu__link--sublist.menu__link--active),
-.menu__list-item-collapsible--active {
+.menu__list-item-collapsible:has(> .menu__link--sublist[aria-current='page']) {
   --ifm-menu-link-sublist-icon: url('data:image/svg+xml;utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="%23f15e49" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"><path d="m6 15 6-6 6 6"/></svg>');
   --ifm-menu-link-sublist-icon-filter: none;
 }
diff --git a/docs/integration-guide/composition.md b/docs/integration-guide/composition.md
index de3b43a1a..276806379 100644
--- a/docs/integration-guide/composition.md
+++ b/docs/integration-guide/composition.md
@@ -56,6 +56,6 @@ function MyApp({ employeeId, startDate }) {
 
 ![](https://files.readme.io/6fb4afca5b75cc9aac151e2ed873aa988b7ffc35dbcb3566b874d7cd8d323e64-image.png)
 
-Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../workflows-overview/employee-onboarding/employee-onboarding.md)).
+Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../workflows-overview/employee-onboarding/sub-components.md)).
 
 Because each step is available for direct use in isolation, it is also possible to rearrange steps, compose them with your own content, or [integrate them with your routing infrastructure as outlined here](./routing.md). For example, we could place this compensation form inside of an existing page inline with our own components, or we could use this as a step in a different flow entirely.
diff --git a/docs/workflows-overview/companies.mdx b/docs/workflows-overview/companies.mdx
new file mode 100644
index 000000000..9b040031e
--- /dev/null
+++ b/docs/workflows-overview/companies.mdx
@@ -0,0 +1,19 @@
+---
+title: Companies
+description: SDK surface for onboarding a new company to Gusto Embedded Payroll and handling outstanding information requests.
+order: 1
+---
+
+The Companies surface covers everything required to onboard a new company to Gusto Embedded Payroll and to manage ongoing company-level interactions like outstanding information requests.
+
+## Company onboarding
+
+Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.
+
+[Read more →](./company-onboarding/company-onboarding.mdx)
+
+## Information requests
+
+A standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.
+
+[Read more →](./information-requests/information-requests.mdx)
diff --git a/docs/workflows-overview/company-onboarding/company-onboarding.mdx b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
new file mode 100644
index 000000000..d9e781c28
--- /dev/null
+++ b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
@@ -0,0 +1,111 @@
+---
+title: Onboard a company
+description: Onboard a company to Gusto Embedded Payroll — industry, signatory, locations, federal and state taxes, pay schedule, bank account, and document signing.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+Company Onboarding walks a company through everything required before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire company onboarding experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Assign a signatory',
+      description: 'Choose between creating a new signatory or inviting someone to become the signatory.',
+      to: './sub-components#assign-a-signatory',
+    },
+    {
+      title: 'Create a signatory',
+      description: 'Standalone form for creating a new signatory with full personal details.',
+      to: './sub-components#create-a-signatory',
+    },
+    {
+      title: 'Invite a signatory',
+      description: 'Standalone form for inviting someone to become the company signatory.',
+      to: './sub-components#invite-a-signatory',
+    },
+    {
+      title: 'Industry',
+      description: "Select and save the company's industry classification (NAICS code).",
+      to: './sub-components#industry',
+    },
+    {
+      title: 'Documents',
+      description: 'Read and sign required company documents, with signatory management.',
+      to: './sub-components#documents',
+    },
+    {
+      title: 'Documents list',
+      description: 'Standalone list of company documents to be signed.',
+      to: './sub-components#documents-list',
+    },
+    {
+      title: 'Sign a document',
+      description: 'Standalone form for signing an individual company document.',
+      to: './sub-components#sign-a-document',
+    },
+    {
+      title: 'Federal taxes',
+      description: 'Add company federal tax info — EIN, tax payer type, filing form, legal name.',
+      to: './sub-components#federal-taxes',
+    },
+    {
+      title: 'Pay schedule',
+      description: 'Create, edit, and preview a company pay schedule.',
+      to: './sub-components#pay-schedule',
+    },
+    {
+      title: 'Locations',
+      description: 'Manage company addresses, including mailing and filing.',
+      to: './sub-components#locations',
+    },
+    {
+      title: 'Location form',
+      description: 'Standalone form for creating or editing a single company location.',
+      to: './sub-components#location-form',
+    },
+    {
+      title: 'Bank account',
+      description: "Manage the company's bank account, including micro-deposit verification.",
+      to: './sub-components#bank-account',
+    },
+    {
+      title: 'State taxes',
+      description: 'Manage state tax setup across applicable states.',
+      to: './sub-components#state-taxes',
+    },
+    {
+      title: 'State taxes form',
+      description: 'Standalone form for editing state tax requirements for a specific state.',
+      to: './sub-components#state-taxes-form',
+    },
+    {
+      title: 'State taxes list',
+      description: 'Standalone list of state tax requirements for the company.',
+      to: './sub-components#state-taxes-list',
+    },
+    {
+      title: 'Onboarding overview',
+      description: 'Summary of completed steps and remaining requirements for the company.',
+      to: './sub-components#onboarding-overview',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/company-onboarding.md b/docs/workflows-overview/company-onboarding/sub-components.md
similarity index 93%
rename from docs/workflows-overview/company-onboarding.md
rename to docs/workflows-overview/company-onboarding/sub-components.md
index 8b68c1393..92e1beda9 100644
--- a/docs/workflows-overview/company-onboarding.md
+++ b/docs/workflows-overview/company-onboarding/sub-components.md
@@ -1,60 +1,16 @@
 ---
-title: Company Onboarding
-description: Workflow for onboarding a company to Gusto Embedded Payroll — industry, signatory, locations, federal taxes, bank account, and document signing subcomponents.
-order: 1
+title: Sub-components
+description: Standalone sub-components for company onboarding — render in isolation or compose into a custom workflow.
+order: 2
 ---
 
-The Company Onboarding workflow provides components for managing company-related onboarding tasks. These components can be used individually or composed into a complete workflow.
+# Company Onboarding sub-components
 
-### Implementation
+Company onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
-```jsx title="App.tsx"
-import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <CompanyOnboarding.OnboardingFlow
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name               | Type   | Description                                                     |
-| ------------------ | ------ | --------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier.                              |
-| defaultValues      | object | Default values for individual flow step components              |
-| onEvent Required   |        | See events table for each subcomponent to see available events. |
-
-## Using Company Subcomponents
-
-Company onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [CompanyOnboarding.AssignSignatory](#companyassignsignatory)
-- [CompanyOnboarding.CreateSignatory](#companycreatesignatory)
-- [CompanyOnboarding.InviteSignatory](#companyinvitesignatory)
-- [CompanyOnboarding.Industry](#companyindustry)
-- [CompanyOnboarding.DocumentSigner](#companydocumentsigner)
-- [CompanyOnboarding.DocumentList](#companydocumentlist)
-- [CompanyOnboarding.SignatureForm](#companysignatureform)
-- [CompanyOnboarding.FederalTaxes](#companyfederaltaxes)
-- [CompanyOnboarding.PaySchedule](#companypayschedule)
-- [CompanyOnboarding.Locations](#companylocations)
-- [CompanyOnboarding.LocationForm](#companylocationform)
-- [CompanyOnboarding.BankAccount](#companybankaccount)
-- [CompanyOnboarding.StateTaxes](#companystatetaxes)
-- [CompanyOnboarding.StateTaxesForm](#companystatetaxesform)
-- [CompanyOnboarding.StateTaxesList](#companystatetaxeslist)
-- [CompanyOnboarding.OnboardingOverview](#companyonboardingoverview)
-
-> Legacy imports via `Company.*` (e.g. `Company.OnboardingFlow`) continue to work.
+---
 
-### Company.AssignSignatory
+## Assign a signatory
 
 A component allowing users to choose between creating a new signatory with full details or inviting someone else to become the signatory.
 
@@ -89,7 +45,9 @@ function MyComponent() {
 | COMPANY_SIGNATORY_UPDATED             | Fired when an existing signatory is updated (create mode) | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
 | COMPANY_SIGNATORY_INVITED             | Fired when a signatory invitation is sent (invite mode)   | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite)        |
 
-### Company.CreateSignatory
+---
+
+## Create a signatory
 
 A standalone form for creating a new signatory with full personal details including name, contact information, SSN, and home address. Use this component when you want to provide only the create signatory flow without the invite option.
 
@@ -120,7 +78,9 @@ function MyComponent() {
 | COMPANY_SIGNATORY_UPDATED     | Fired when an existing signatory is updated successfully | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
 | COMPANY_CREATE_SIGNATORY_DONE | Fired when the create signatory process is complete      | None                                                                                                                                                         |
 
-### Company.InviteSignatory
+---
+
+## Invite a signatory
 
 A standalone form for inviting someone else to become the company signatory. The invited person will receive an email to complete their signatory information. Use this component when you want to provide only the invite signatory flow without the create option.
 
@@ -149,7 +109,9 @@ function MyComponent() {
 | COMPANY_SIGNATORY_INVITED     | Fired when a signatory is successfully invited to the company | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite) |
 | COMPANY_INVITE_SIGNATORY_DONE | Fired when the invite signatory process is complete           | None                                                                                                                                                  |
 
-### Company.Industry
+---
+
+## Industry
 
 A component for selecting and saving the company's industry classification (NAICS code). The selector presents a searchable list of industry options for the company.
 
@@ -174,7 +136,9 @@ function MyComponent() {
 | ------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | COMPANY_INDUSTRY_SELECTED | Fired when an industry is selected and saved | `industry` field from the [Update industry selection API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-industry_selection) |
 
-### Company.DocumentSigner
+---
+
+## Documents
 
 Provides an interface for company representatives to read and sign required company documents. The component handles document listing, signatory management, and document signing workflow.
 
@@ -212,7 +176,9 @@ function MyComponent() {
 | COMPANY_SIGNATORY_UPDATED             | Fired when an existing signatory is updated successfully         | [Response from the update signatory API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-signatories-signatory_uuid) |
 | COMPANY_SIGNATORY_INVITED             | Fired when a signatory is successfully invited to the company    | [Response from the invite signatory API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_uuid-signatories-invite)        |
 
-### Company.DocumentList
+---
+
+## Documents list
 
 A standalone component that displays the list of company documents to be signed and lets the user manage signatories. This is the lower-level building block used internally by `Company.DocumentSigner` for its list view. Use this component directly when you need full control over navigation between the document list and the signature form.
 
@@ -242,7 +208,9 @@ function MyComponent() {
 | COMPANY_FORM_EDIT_SIGNATORY | Fired when user requests to change the document signatory       | Current signatory entity                                                                                                     |
 | COMPANY_FORMS_DONE          | Fired when user completes the document signing process          | None                                                                                                                         |
 
-### Company.SignatureForm
+---
+
+## Sign a document
 
 A standalone form for signing an individual company document. This is the lower-level building block used internally by `Company.DocumentSigner` for its signing view. Use this component directly when you need full control over navigation between the document list and the signature form (e.g. you are routing the user yourself after they select a form from `Company.DocumentList`).
 
@@ -276,7 +244,9 @@ function MyComponent() {
 | COMPANY_SIGN_FORM_DONE | Fired when the form signing process is complete            | None                                                                                                                          |
 | COMPANY_SIGN_FORM_BACK | Fired when the user navigates back from the signature form | None                                                                                                                          |
 
-### Company.FederalTaxes
+---
+
+## Federal taxes
 
 A component for adding company federal tax information including EIN, tax payer type, filing form, and legal name.
 
@@ -305,7 +275,9 @@ function MyComponent() {
 | COMPANY_FEDERAL_TAXES_UPDATED | Fired when federal tax details are successfully updated | [Response from the update federal tax details API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-federal_tax_details) |
 | COMPANY_FEDERAL_TAXES_DONE    | Fired when the federal tax update process is complete   | None                                                                                                                                                          |
 
-### Company.PaySchedule
+---
+
+## Pay schedule
 
 A component for managing company pay schedules, including creating, editing, and viewing pay schedules with preview functionality.
 
@@ -332,7 +304,9 @@ function MyComponent() {
 | PAY_SCHEDULE_CREATED | Fired when a new pay schedule is successfully created       | [Response from the create pay schedule API request](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-pay_schedules)                |
 | PAY_SCHEDULE_UPDATED | Fired when an existing pay schedule is successfully updated | [Response from the update pay schedule API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-pay_schedules-pay_schedule_id) |
 
-### Company.Locations
+---
+
+## Locations
 
 An orchestrated component for managing company addresses, including mailing and filing address. Internally uses a state machine to switch between a list view and a create/edit form. For more granular control, you can use `Company.LocationForm` directly.
 
@@ -362,7 +336,9 @@ function MyComponent() {
 | COMPANY_LOCATION_UPDATED | Fired when locations has been successfully edited       | [Response from the update a location API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id)                   |
 | COMPANY_LOCATION_DONE    | Fired when user chooses to proceed to a next step       | None                                                                                                                                                |
 
-### Company.LocationForm
+---
+
+## Location form
 
 A standalone form component for creating a new company location or editing an existing one. This is the lower-level building block used internally by `Company.Locations` for its create/edit views. Use this component directly when you need full control over navigation between the list and form views.
 
@@ -398,7 +374,9 @@ function MyComponent() {
 | COMPANY_LOCATION_UPDATED | Fired when a location has been successfully edited | [Response from the update a location API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-locations-location_id)                   |
 | CANCEL                   | Fired when the user cancels editing                | None                                                                                                                                                |
 
-### Company.BankAccount
+---
+
+## Bank account
 
 A component for managing company bank account
 
@@ -428,7 +406,9 @@ function MyComponent() {
 | COMPANY_BANK_ACCOUNT_VERIFIED | Fired when bank account has been successfully verifyed                           | [Response from the verify a company bank account API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-bank-accounts-verify) |
 | COMPANY_BANK_ACCOUNT_DONE     | Fired when user chooses to proceed to a next step                                | None                                                                                                                                                              |
 
-### Company.StateTaxes
+---
+
+## State taxes
 
 An orchestrated component for managing company state taxes setup. Internally uses a state machine to switch between a list view and an edit form. For more granular control, you can use `CompanyOnboarding.StateTaxesList` or `CompanyOnboarding.StateTaxesForm` directly.
 
@@ -455,7 +435,9 @@ function MyComponent() {
 | COMPANY_STATE_TAX_UPDATED | Fired when a state tax setup has been successfully submitted        | [Response from the create a company update state tax requirements API](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-tax_requirements-state) |
 | COMPANY_STATE_TAX_DONE    | Fired when user chooses to proceed to a next step                   | None                                                                                                                                                                           |
 
-### Company.StateTaxesForm
+---
+
+## State taxes form
 
 A standalone form component for editing state tax requirements for a specific state. This is the lower-level building block used internally by `Company.StateTaxes` for its edit view. Use this component directly when you need full control over navigation between the list and form views.
 
@@ -488,7 +470,9 @@ function MyComponent() {
 | COMPANY_STATE_TAX_UPDATED | Fired when a state tax setup has been successfully submitted | [Response from the create a company update state tax requirements API](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_uuid-tax_requirements-state) |
 | CANCEL                    | Fired when the user cancels editing                          | None                                                                                                                                                                           |
 
-### Company.StateTaxesList
+---
+
+## State taxes list
 
 A standalone component that displays the list of state tax requirements for a company. This is the lower-level building block used internally by `Company.StateTaxes` for its list view. Use this component directly when you need full control over navigation between the list and form views.
 
@@ -516,7 +500,9 @@ function MyComponent() {
 | COMPANY_STATE_TAX_EDIT | Fired when a user chooses to edit requirements for a specific state | `{ state: string }` |
 | COMPANY_STATE_TAX_DONE | Fired when user chooses to proceed to a next step                   | None                |
 
-### Company.OnboardingOverview
+---
+
+## Onboarding overview
 
 Displays the company's overall onboarding status. Shows completed steps and remaining requirements, providing a high-level summary of where the company is in the onboarding process. Used as the landing/summary screen of the onboarding flow.
 
diff --git a/docs/workflows-overview/company-onboarding/workflow.md b/docs/workflows-overview/company-onboarding/workflow.md
new file mode 100644
index 000000000..a57f6bac1
--- /dev/null
+++ b/docs/workflows-overview/company-onboarding/workflow.md
@@ -0,0 +1,34 @@
+---
+title: Workflow
+description: Drop-in CompanyOnboarding.OnboardingFlow component that renders the entire company onboarding experience.
+order: 1
+---
+
+# Company Onboarding workflow
+
+The Company Onboarding workflow renders the entire onboarding experience as a single component. Drop it into your app and it walks the user through every required step.
+
+---
+
+## Implementation
+
+```jsx title="App.tsx"
+import { CompanyOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <CompanyOnboarding.OnboardingFlow
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name               | Type   | Description                                                     |
+| ------------------ | ------ | --------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier.                              |
+| defaultValues      | object | Default values for individual flow step components              |
+| onEvent Required   |        | See events table for each subcomponent to see available events. |
diff --git a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
new file mode 100644
index 000000000..6a1c39a09
--- /dev/null
+++ b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
@@ -0,0 +1,61 @@
+---
+title: Contractor onboarding
+description: Workflow for onboarding a contractor — profile, address, payment method, new hire reporting, and submission.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Contractor Onboarding workflow collects everything required to set a contractor up for payment: profile, address, payment method, new hire reporting, and final submission. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire contractor onboarding experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Contractors list',
+      description: 'List of contractors for a company with actions to add, edit, delete, and continue onboarding.',
+      to: './sub-components#contractors-list',
+    },
+    {
+      title: 'Profile',
+      description: 'Form for creating and editing a contractor profile — individual or business, with self-onboarding option.',
+      to: './sub-components#profile',
+    },
+    {
+      title: 'Address',
+      description: "Form for collecting and updating a contractor's mailing address.",
+      to: './sub-components#address',
+    },
+    {
+      title: 'Payment method',
+      description: "Configure the contractor's payment method — direct deposit or check.",
+      to: './sub-components#payment-method',
+    },
+    {
+      title: 'New hire report',
+      description: 'Handle new hire reporting requirements for the contractor.',
+      to: './sub-components#new-hire-report',
+    },
+    {
+      title: 'Submit contractor',
+      description: 'Finalize contractor onboarding — update status and optionally invite the contractor for self-onboarding.',
+      to: './sub-components#submit-contractor',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/contractor-onboarding.md b/docs/workflows-overview/contractor-onboarding/sub-components.md
similarity index 85%
rename from docs/workflows-overview/contractor-onboarding.md
rename to docs/workflows-overview/contractor-onboarding/sub-components.md
index 561aa0a64..8ee270055 100644
--- a/docs/workflows-overview/contractor-onboarding.md
+++ b/docs/workflows-overview/contractor-onboarding/sub-components.md
@@ -1,52 +1,18 @@
 ---
-title: Contractor Onboarding
-description: Workflow for onboarding a contractor — profile, address, payment, and document signing — composable as a full flow or individual subcomponents.
+title: Sub-components
+description: Standalone sub-components for contractor onboarding — render in isolation or compose into a custom workflow.
 order: 2
 ---
 
-The Contractor Onboarding workflow provides components for managing contractor-related onboarding tasks. These components can be used individually or composed into a complete workflow.
+# Contractor Onboarding sub-components
 
-### Implementation
-
-```jsx
-import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <ContractorOnboarding.OnboardingFlow
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name               | Type   | Description                                                                                           |
-| ------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier.                                                                    |
-| defaultValues      | object | Default values containing `profile` and/or `address` sub-objects for individual flow step components. |
-| onEvent Required   |        | See events table for each subcomponent to see available events.                                       |
-
-Events from subcomponents bubble up through the `onEvent` handler.
-
-## Using Contractor Subcomponents
-
-Contractor onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [ContractorOnboarding.ContractorList](#contractorcontractorlist)
-- [ContractorOnboarding.ContractorProfile](#contractorcontractorprofile)
-- [ContractorOnboarding.Address](#contractoraddress)
-- [ContractorOnboarding.PaymentMethod](#contractorpaymentmethod)
-- [ContractorOnboarding.NewHireReport](#contractornewhirereport)
-- [ContractorOnboarding.ContractorSubmit](#contractorcontractorsubmit)
+Contractor onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
 > Legacy imports via `Contractor.*` (e.g. `Contractor.OnboardingFlow`) continue to work.
 
-### Contractor.ContractorList
+---
+
+## Contractors list
 
 Displays a list of contractors for a company, allowing users to add new contractors, edit existing ones, delete contractors, and continue the onboarding process.
 
@@ -80,7 +46,9 @@ function MyComponent() {
 | CONTRACTOR_DELETED             | Fired when a contractor is deleted              | { contractorId: string } |
 | CONTRACTOR_ONBOARDING_CONTINUE | Fired when user chooses to continue onboarding  | None                     |
 
-### Contractor.ContractorProfile
+---
+
+## Profile
 
 A comprehensive form for creating and editing contractor profiles. Supports both individual and business contractor types, with different field sets for each. Includes options for wage type, self-onboarding invitations, and start date.
 
@@ -114,7 +82,9 @@ function MyComponent() {
 | CONTRACTOR_UPDATED      | Fired when an existing contractor is updated        | [Response from the update contractor API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid)         |
 | CONTRACTOR_PROFILE_DONE | Fired when the contractor profile step is complete  | { contractorId: string, selfOnboarding: boolean }                                                                                               |
 
-### Contractor.Address
+---
+
+## Address
 
 A form for collecting and updating a contractor's mailing address.
 
@@ -141,7 +111,9 @@ function MyComponent() {
 | CONTRACTOR_ADDRESS_UPDATED | Fired when the contractor address is updated | [Response from the create or update a contractor's address API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid-address) |
 | CONTRACTOR_ADDRESS_DONE    | Fired when the address step is complete      | None                                                                                                                                                                  |
 
-### Contractor.PaymentMethod
+---
+
+## Payment method
 
 Manages the contractor's payment method, including adding a bank account for direct deposit or selecting check as the payment method.
 
@@ -168,7 +140,9 @@ function MyComponent() {
 | CONTRACTOR_PAYMENT_METHOD_UPDATED | Fired when the payment method is updated                | [Response from the update a contractor's payment method API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_id-payment_method) |
 | CONTRACTOR_PAYMENT_METHOD_DONE    | Fired when the payment method step is complete          | None                                                                                                                                                                    |
 
-### Contractor.NewHireReport
+---
+
+## New hire report
 
 Handles new hire reporting requirements for the contractor. Behavior varies based on whether the contractor is going through admin onboarding or self-onboarding.
 
@@ -195,7 +169,9 @@ function MyComponent() {
 | CONTRACTOR_NEW_HIRE_REPORT_UPDATED | Fired when the new hire report is updated       | [Response from the update contractor API request](https://docs.gusto.com/embedded-payroll/reference/put-v1-contractors-contractor_uuid) |
 | CONTRACTOR_NEW_HIRE_REPORT_DONE    | Fired when the new hire report step is complete | None                                                                                                                                    |
 
-### Contractor.ContractorSubmit
+---
+
+## Submit contractor
 
 Finalizes the contractor onboarding process. Updates the onboarding status and, in the self-onboarding flow, can trigger an invitation to the contractor.
 
diff --git a/docs/workflows-overview/contractor-onboarding/workflow.md b/docs/workflows-overview/contractor-onboarding/workflow.md
new file mode 100644
index 000000000..c75d36c07
--- /dev/null
+++ b/docs/workflows-overview/contractor-onboarding/workflow.md
@@ -0,0 +1,36 @@
+---
+title: Workflow
+description: Drop-in ContractorOnboarding.OnboardingFlow component that renders the entire contractor onboarding experience.
+order: 1
+---
+
+# Contractor Onboarding workflow
+
+The Contractor Onboarding workflow renders the full onboarding experience as a single component. Drop it into your app and it walks the user through every step required to bring a contractor onto the company.
+
+---
+
+## Implementation
+
+```jsx
+import { ContractorOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <ContractorOnboarding.OnboardingFlow
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name               | Type   | Description                                                                                           |
+| ------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier.                                                                    |
+| defaultValues      | object | Default values containing `profile` and/or `address` sub-objects for individual flow step components. |
+| onEvent Required   |        | See events table for each subcomponent to see available events.                                       |
+
+Events from subcomponents bubble up through the `onEvent` handler.
diff --git a/docs/workflows-overview/contractor-payments/contractor-payments.mdx b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
new file mode 100644
index 000000000..4d509257a
--- /dev/null
+++ b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
@@ -0,0 +1,56 @@
+---
+title: Contractor payments
+description: Workflow for creating, managing, and viewing contractor payment groups.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Contractor Payments workflow lets a company create, manage, and view contractor payment groups. The full experience can be dropped in as a single component, or assembled from individual sub-components — payment list, payment creation, history, summary, and individual payment statements.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire contractor payments experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Payments list',
+      description: 'List of contractor payment groups, with the ability to create new payments and filter by date range.',
+      to: './sub-components#payments-list',
+    },
+    {
+      title: 'Create payment',
+      description: 'Form for creating a contractor payment group — payment date, individual contractor edits, preview, and submission blockers.',
+      to: './sub-components#create-payment',
+    },
+    {
+      title: 'Payment history',
+      description: 'Detailed view of a payment group and its individual contractor payments, with cancellation when permitted.',
+      to: './sub-components#payment-history',
+    },
+    {
+      title: 'Payment summary',
+      description: 'Confirmation screen after payment creation — totals, debit details, and wire transfer instructions when applicable.',
+      to: './sub-components#payment-summary',
+    },
+    {
+      title: 'Payment statement',
+      description: 'Individual contractor payment statement with detailed payment information and breakdown.',
+      to: './sub-components#payment-statement',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/contractor-payments.md b/docs/workflows-overview/contractor-payments/sub-components.md
similarity index 64%
rename from docs/workflows-overview/contractor-payments.md
rename to docs/workflows-overview/contractor-payments/sub-components.md
index fb2109af2..ab9e20c69 100644
--- a/docs/workflows-overview/contractor-payments.md
+++ b/docs/workflows-overview/contractor-payments/sub-components.md
@@ -1,45 +1,16 @@
 ---
-title: Contractor Payments
-description: Workflow for creating, managing, and viewing contractor payment groups via Contractor.PaymentFlow, with subcomponents for list, create, history, and summary.
-order: 3
+title: Sub-components
+description: Standalone sub-components for contractor payments — render in isolation or compose into a custom workflow.
+order: 2
 ---
 
-The Contractor Payments workflow provides components for creating, managing, and viewing contractor payment groups. These components can be used individually or composed into a complete payment workflow through the `Contractor.PaymentFlow` component.
+# Contractor Payments sub-components
 
-### Implementation
+Contractor payment components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
-```jsx
-import { Contractor } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <Contractor.PaymentFlow companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365" onEvent={() => {}} />
-  )
-}
-```
-
-#### Props
-
-| Name               | Type   | Description                                                     |
-| ------------------ | ------ | --------------------------------------------------------------- |
-| companyId Required | string | The associated company identifier.                              |
-| onEvent Required   |        | See events table for each subcomponent to see available events. |
-
-Events from subcomponents bubble up through the `onEvent` handler.
-
-## Using Contractor Payment Subcomponents
-
-Contractor payment components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- Contractor.PaymentsList
-- Contractor.CreatePayment
-- Contractor.PaymentHistory
-- Contractor.PaymentSummary
-- Contractor.PaymentStatement
+---
 
-### Contractor.PaymentsList
+## Payments list
 
 Displays a list of contractor payment groups for a company, allowing users to view payment history, create new payments, and filter by date range. Includes alerts for pending information requests and wire transfer requirements.
 
@@ -69,7 +40,9 @@ function MyComponent() {
 | CONTRACTOR_PAYMENT_VIEW        | Fired when user selects a payment group to view   | { paymentId: string } |
 | CONTRACTOR_PAYMENT_RFI_RESPOND | Fired when user clicks to respond to an RFI alert | None                  |
 
-### Contractor.CreatePayment
+---
+
+## Create payment
 
 A comprehensive form for creating contractor payment groups. Allows selecting payment date, editing individual contractor payments with hours, wages, bonuses, and reimbursements. Supports preview before submission and handles submission blockers like Fast ACH thresholds.
 
@@ -102,15 +75,17 @@ function MyComponent() {
 
 #### Features
 
-- **Payment Date Selection**: Choose the payment date with automatic validation
-- **Contractor Payment Editing**: Edit hours (for hourly contractors), wages (for fixed contractors), bonuses, and reimbursements
-- **Payment Method Selection**: Choose between Direct Deposit, Check, or Historical Payment per contractor
-- **Real-time Totals**: View totals for wages, bonuses, reimbursements, and overall total
-- **Preview Mode**: Review payment details, debit information, and submission deadlines before finalizing
-- **Submission Blockers**: Handle Fast ACH thresholds with options to wire funds or switch to 4-day direct deposit
-- **Wire Transfer Support**: Integrated wire transfer instructions when required
+- **Payment date selection**: Choose the payment date with automatic validation
+- **Contractor payment editing**: Edit hours (for hourly contractors), wages (for fixed contractors), bonuses, and reimbursements
+- **Payment method selection**: Choose between Direct Deposit, Check, or Historical Payment per contractor
+- **Real-time totals**: View totals for wages, bonuses, reimbursements, and overall total
+- **Preview mode**: Review payment details, debit information, and submission deadlines before finalizing
+- **Submission blockers**: Handle Fast ACH thresholds with options to wire funds or switch to 4-day direct deposit
+- **Wire transfer support**: Integrated wire transfer instructions when required
+
+---
 
-### Contractor.PaymentHistory
+## Payment history
 
 Displays detailed information about a specific contractor payment group, including all individual contractor payments. Allows viewing individual payment details and canceling payments when permitted.
 
@@ -138,12 +113,14 @@ function MyComponent() {
 
 #### Features
 
-- **Payment Group Overview**: View debit date and overall payment group information
-- **Detailed Payment Table**: Shows contractor name, wage type, payment method, hours, wages, bonuses, reimbursements, and totals
-- **Payment Actions**: View individual payment details or cancel payments when allowed
-- **Cancellation Support**: Cancel individual payments within a payment group when permitted
+- **Payment group overview**: View debit date and overall payment group information
+- **Detailed payment table**: Shows contractor name, wage type, payment method, hours, wages, bonuses, reimbursements, and totals
+- **Payment actions**: View individual payment details or cancel payments when allowed
+- **Cancellation support**: Cancel individual payments within a payment group when permitted
+
+---
 
-### Contractor.PaymentSummary
+## Payment summary
 
 Displays a summary of a created payment group, including payment details, contractor information, and wire transfer requirements if applicable. Used as a confirmation screen after payment creation.
 
@@ -177,12 +154,14 @@ function MyComponent() {
 
 #### Features
 
-- **Success Confirmation**: Displays confirmation message with number of payments scheduled
-- **Payment Summary**: Shows payment totals, debit information, and payment dates
-- **Wire Transfer Details**: If wire transfer is required, displays wire instructions with confirmation workflow
-- **Bank Account Information**: Shows the debit bank account details
+- **Success confirmation**: Displays confirmation message with number of payments scheduled
+- **Payment summary**: Shows payment totals, debit information, and payment dates
+- **Wire transfer details**: If wire transfer is required, displays wire instructions with confirmation workflow
+- **Bank account information**: Shows the debit bank account details
+
+---
 
-### Contractor.PaymentStatement
+## Payment statement
 
 Displays an individual contractor payment statement with detailed payment information and breakdown.
 
@@ -200,48 +179,3 @@ function MyComponent() {
 | ------------------------ | ------ | --------------------------------------------- |
 | **paymentId** (Required) | string | The individual contractor payment identifier. |
 | **onEvent** (Required)   |        | See events table for available events.        |
-
-## Payment Workflow
-
-The contractor payments workflow follows these typical steps:
-
-1. **View Payment List**: Start with `PaymentsList` to see existing payment groups and create new payments
-2. **Create Payment**: Use `CreatePayment` to build a payment group:
-   - Select payment date
-   - Edit individual contractor payments (hours, wages, bonuses, reimbursements)
-   - Preview payment details
-   - Handle submission blockers (Fast ACH, wire transfers)
-   - Submit payment group
-3. **View Summary**: After creation, `PaymentSummary` shows confirmation and wire transfer instructions if needed
-4. **View History**: Use `PaymentHistory` to see details of a payment group and manage individual payments
-5. **View Statement**: Use `PaymentStatement` to see detailed information for an individual contractor payment
-
-## Important Notes
-
-### Payment Timing
-
-- Direct deposit payments submitted before 4pm PT on a business day take 2 business days to complete
-- Fast ACH (2-day) payments have threshold limits; exceeding the threshold requires wire transfer or switching to 4-day processing
-
-### Payment Requirements
-
-- Only active contractors with completed onboarding can receive payments
-- At least one contractor payment must be included in a payment group
-- Bank account must be set up for the company to process payments
-
-### Submission Blockers
-
-Payment submission may be blocked by:
-
-- **Fast ACH Threshold Exceeded**: Payment amount exceeds the fast ACH limit
-  - Options: Wire transfer (fastest) or switch to 4-day direct deposit
-- **Needs Earned Access for Fast ACH**: Company hasn't earned access to faster payments yet
-  - Must use standard 4-day processing
-
-### Wire Transfers
-
-When wire transfer is required:
-
-- Instructions are provided in the payment flow
-- Must be completed by specified deadline to ensure timely payment
-- Confirmation workflow tracks wire transfer submission
diff --git a/docs/workflows-overview/contractor-payments/workflow.md b/docs/workflows-overview/contractor-payments/workflow.md
new file mode 100644
index 000000000..d93d8a7b6
--- /dev/null
+++ b/docs/workflows-overview/contractor-payments/workflow.md
@@ -0,0 +1,81 @@
+---
+title: Workflow
+description: Drop-in Contractor.PaymentFlow component that renders the entire contractor payments experience.
+order: 1
+---
+
+# Contractor Payments workflow
+
+The Contractor Payments workflow renders the full payments experience — view, create, preview, submit, and review payment groups — as a single component. Drop it into your app and the user walks through every step required to pay contractors.
+
+---
+
+## Implementation
+
+```jsx
+import { Contractor } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <Contractor.PaymentFlow companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365" onEvent={() => {}} />
+  )
+}
+```
+
+#### Props
+
+| Name               | Type   | Description                                                     |
+| ------------------ | ------ | --------------------------------------------------------------- |
+| companyId Required | string | The associated company identifier.                              |
+| onEvent Required   |        | See events table for each subcomponent to see available events. |
+
+Events from subcomponents bubble up through the `onEvent` handler.
+
+---
+
+## Payment workflow
+
+The contractor payments workflow follows these typical steps:
+
+1. **View payment list**: Start with `PaymentsList` to see existing payment groups and create new payments.
+2. **Create payment**: Use `CreatePayment` to build a payment group:
+   - Select payment date
+   - Edit individual contractor payments (hours, wages, bonuses, reimbursements)
+   - Preview payment details
+   - Handle submission blockers (Fast ACH, wire transfers)
+   - Submit payment group
+3. **View summary**: After creation, `PaymentSummary` shows confirmation and wire transfer instructions if needed.
+4. **View history**: Use `PaymentHistory` to see details of a payment group and manage individual payments.
+5. **View statement**: Use `PaymentStatement` to see detailed information for an individual contractor payment.
+
+---
+
+## Important notes
+
+### Payment timing
+
+- Direct deposit payments submitted before 4pm PT on a business day take 2 business days to complete.
+- Fast ACH (2-day) payments have threshold limits; exceeding the threshold requires wire transfer or switching to 4-day processing.
+
+### Payment requirements
+
+- Only active contractors with completed onboarding can receive payments.
+- At least one contractor payment must be included in a payment group.
+- A bank account must be set up for the company to process payments.
+
+### Submission blockers
+
+Payment submission may be blocked by:
+
+- **Fast ACH threshold exceeded**: Payment amount exceeds the fast ACH limit
+  - Options: Wire transfer (fastest) or switch to 4-day direct deposit
+- **Needs earned access for Fast ACH**: Company hasn't earned access to faster payments yet
+  - Must use standard 4-day processing
+
+### Wire transfers
+
+When wire transfer is required:
+
+- Instructions are provided in the payment flow.
+- Must be completed by specified deadline to ensure timely payment.
+- Confirmation workflow tracks wire transfer submission.
diff --git a/docs/workflows-overview/contractors.mdx b/docs/workflows-overview/contractors.mdx
new file mode 100644
index 000000000..e08990599
--- /dev/null
+++ b/docs/workflows-overview/contractors.mdx
@@ -0,0 +1,19 @@
+---
+title: Contractors
+description: SDK surface for onboarding contractors and paying them on or off cycle.
+order: 3
+---
+
+The Contractors surface covers everything required to bring a contractor onto a company and to pay them once they're active. The two flows can be used independently or composed together as part of a broader contractor management experience.
+
+## Contractor onboarding
+
+Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.
+
+[Read more →](./contractor-onboarding/contractor-onboarding.mdx)
+
+## Contractor payments
+
+Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.
+
+[Read more →](./contractor-payments/contractor-payments.mdx)
diff --git a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
new file mode 100644
index 000000000..86a32656c
--- /dev/null
+++ b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
@@ -0,0 +1,37 @@
+---
+title: Dismissal payroll
+description: Guided workflow for running a terminated employee's final payroll — surfaces unprocessed termination pay periods and transitions into the standard payroll flow.
+order: 3
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Dismissal Payroll workflow provides a guided experience for running a terminated employee's final payroll. It presents unprocessed termination pay periods for the employee, creates an off-cycle payroll for the selected period, and then transitions into the standard payroll execution flow. Like all off-cycle payroll types, the dismissal flow shares the same execution steps as regular payrolls — the only difference is how the payroll is created.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that handles pay period selection and hands off to the standard payroll execution.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Sub-components',
+      description:
+        "Dismissal payroll is delivered as a single orchestrated flow. After creation, it reuses the standard payroll processing sub-components for configuration, overview, submission, and receipts.",
+      to: './sub-components',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/dismissal-payroll/sub-components.md b/docs/workflows-overview/dismissal-payroll/sub-components.md
new file mode 100644
index 000000000..b92def182
--- /dev/null
+++ b/docs/workflows-overview/dismissal-payroll/sub-components.md
@@ -0,0 +1,24 @@
+---
+title: Sub-components
+description: Dismissal payroll is delivered as a single orchestrated flow and reuses the standard payroll processing sub-components for execution.
+order: 2
+---
+
+# Dismissal Payroll sub-components
+
+The Dismissal Payroll workflow is delivered as a single orchestrated flow ([`Payroll.DismissalFlow`](./workflow)) and does not export its own standalone sub-components. After the dismissal payroll is created, the flow internally renders [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) with `isDismissalPayroll` enabled to deliver the standard configuration → overview → submission → receipts experience.
+
+---
+
+## Building a custom dismissal experience
+
+If you want to build a custom dismissal-creation step in front of the standard execution UI:
+
+1. Create the off-cycle payroll yourself with `off_cycle_reason: "Dismissed employee"` via the [Create off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls).
+2. Render [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) directly with the resulting `payrollId` and `isDismissalPayroll={true}`.
+
+For the individual execution sub-components, see the [Payroll Processing sub-components](../run-payroll/sub-components):
+
+- [Configuration](../run-payroll/sub-components#configuration)
+- [Overview](../run-payroll/sub-components#overview)
+- [Receipts](../run-payroll/sub-components#receipts)
diff --git a/docs/workflows-overview/dismissal-payroll.md b/docs/workflows-overview/dismissal-payroll/workflow.md
similarity index 69%
rename from docs/workflows-overview/dismissal-payroll.md
rename to docs/workflows-overview/dismissal-payroll/workflow.md
index a43bc516f..1f803633d 100644
--- a/docs/workflows-overview/dismissal-payroll.md
+++ b/docs/workflows-overview/dismissal-payroll/workflow.md
@@ -1,16 +1,20 @@
 ---
-title: Dismissal Payroll
-description: Guided workflow for running a terminated employee's final payroll — surfaces unprocessed termination pay periods and transitions into the standard payroll flow.
-order: 6
+title: Workflow
+description: Drop-in Payroll.DismissalFlow component that runs a terminated employee's final payroll.
+order: 1
 ---
 
-The Dismissal Payroll workflow provides a guided experience for running a terminated employee's final payroll. It presents unprocessed termination pay periods for the employee, creates an off-cycle payroll for the selected period, and then transitions into the standard [Payroll Processing](./run-payroll.md) flow for configuration, review, and submission. Like all off-cycle payroll types, the dismissal flow shares the same execution steps as regular payrolls — the only difference is how the payroll is created.
+# Dismissal Payroll workflow
 
-This workflow is typically launched from the [Employee Termination](./employee-termination.md) flow when the user selects the "Dismissal payroll" option for the employee's final paycheck.
+The Dismissal Payroll workflow renders the full final-paycheck experience for a terminated employee as a single component. It surfaces unprocessed termination pay periods, lets the user pick one, creates an off-cycle payroll for it, and then hands off to the standard payroll execution.
+
+This workflow is typically launched from the [Employee Termination](../employee-termination.md) flow when the user selects the "Dismissal payroll" option for the employee's final paycheck.
 
 > **Important**: Make sure employees are paid on time by checking your [state's requirement guide](https://support.gusto.com/article/100895878100000/Final-paychecks). Some states require employees to receive their final wages within 24 hours (unless they consent otherwise), in which case running a dismissal payroll may be the only option.
 
-### Implementation
+---
+
+## Implementation
 
 ```jsx
 import { Payroll } from '@gusto/embedded-react-sdk'
@@ -43,38 +47,32 @@ Events emitted during the pay period selection phase:
 | ----------------------------- | -------------------------------------------------- | ----------------------- |
 | DISMISSAL_PAY_PERIOD_SELECTED | Fired when user selects a pay period and continues | { payrollUuid: string } |
 
-Once the payroll is created, all standard [run payroll events](./run-payroll.md) are emitted during execution (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Using Dismissal Subcomponents
-
-The dismissal payroll workflow is delivered as a single orchestrated flow (`Payroll.DismissalFlow`). After the dismissal payroll is created, the flow transitions into the standard payroll execution experience and uses the [Run Payroll subcomponents](./run-payroll.md#available-subcomponents) for configuration, overview, submission, and receipts.
-
-### Available Subcomponents
+Once the payroll is created, all standard [run payroll events](../run-payroll/workflow#events) are emitted during execution (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
 
-- `Payroll.DismissalFlow` (the entire dismissal flow — see [Implementation](#implementation) above)
-
-For the execution phase, the dismissal flow internally renders [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) with `isDismissalPayroll` enabled. If you want to build a custom dismissal-creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created. See the [Run Payroll docs](./run-payroll.md) for individual execution subcomponents (`Payroll.PayrollConfiguration`, `Payroll.PayrollOverview`, `Payroll.PayrollReceipts`).
+---
 
-## Workflow Steps
+## Workflow steps
 
 The flow adapts based on whether a `payrollId` is provided:
 
 **Without `payrollId` (default)**:
 
-1. **Pay Period Selection**: Displays unprocessed termination pay periods for the employee. The user selects which period to run the final payroll for.
+1. **Pay period selection**: Displays unprocessed termination pay periods for the employee. The user selects which period to run the final payroll for.
 2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
 
 **With `payrollId`**:
 
 1. **Execution**: Skips pay period selection and goes directly to payroll execution for the specified payroll.
 
+---
+
 ## Integration with Employee Termination
 
-The dismissal payroll flow integrates with the [Employee Termination workflow](./employee-termination.md):
+The dismissal payroll flow integrates with the [Employee Termination workflow](../employee-termination.md):
 
-- When the user selects the "Dismissal payroll" option during termination, the `EMPLOYEE_TERMINATION_RUN_PAYROLL` event is emitted with `{ employeeId, companyId, payrollUuid, termination }`
-- Your application should handle this event by rendering `Payroll.DismissalFlow` with the appropriate `companyId` and `employeeId`
-- The dismissal flow fetches the employee's unprocessed termination pay periods and guides the user through the final payroll
+- When the user selects the "Dismissal payroll" option during termination, the `EMPLOYEE_TERMINATION_RUN_PAYROLL` event is emitted with `{ employeeId, companyId, payrollUuid, termination }`.
+- Your application should handle this event by rendering `Payroll.DismissalFlow` with the appropriate `companyId` and `employeeId`.
+- The dismissal flow fetches the employee's unprocessed termination pay periods and guides the user through the final payroll.
 
 ```jsx
 import { useState } from 'react'
@@ -110,13 +108,23 @@ function TerminationPage({ companyId, employeeId }) {
 }
 ```
 
-## Pay Period Selection
+---
+
+## Pay period selection
 
 The pay period selection step fetches unprocessed termination pay periods for the employee and presents them as options. Each option shows the pay period date range. When only one pay period is available, it is automatically pre-selected.
 
 Upon selection and submission, the component creates an off-cycle payroll with the `"Dismissed employee"` off-cycle reason using the selected pay period's start and end dates.
 
-## API Reference
+---
+
+## Skipping a dismissal payroll
+
+If someone accidentally selects dismissal payroll as the final paycheck option and doesn't want to run a dismissal payroll, they can use the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid) to bypass the requirement.
+
+---
+
+## API reference
 
 The dismissal payroll uses these API endpoints:
 
@@ -125,7 +133,3 @@ The dismissal payroll uses these API endpoints:
 - **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
 - **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
 - **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
-
-### Skipping a Dismissal Payroll
-
-If someone accidentally selects dismissal payroll as the final paycheck option and doesn't want to run a dismissal payroll, they can use the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid) to bypass the requirement.
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
new file mode 100644
index 000000000..f356ef591
--- /dev/null
+++ b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
@@ -0,0 +1,78 @@
+---
+title: Onboard and employee to payroll
+description: Admin-driven workflow for onboarding an employee to payroll — profile, compensation, taxes, payment method, and document signing, with optional I-9 step.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Employee Onboarding workflow provides a complete experience for an admin to onboard a new employee to a company. It collects every piece of information required for the employee to be added to payroll, and can be composed end-to-end as a full workflow or rendered piece by piece as standalone sub-components.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire admin-driven employee onboarding experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Employees list',
+      description: 'List of employees with their onboarding status and actions to edit or remove.',
+      to: './sub-components#employees-list',
+    },
+    {
+      title: 'Profile',
+      description: 'Collect basic employee info — name, addresses, email, SSN, date of birth.',
+      to: './sub-components#profile',
+    },
+    {
+      title: 'Compensation',
+      description: 'Configure job title, employee type, compensation amount, and pay period.',
+      to: './sub-components#compensation',
+    },
+    {
+      title: 'Federal taxes',
+      description: "Form for the employee's federal tax (W-4) withholding configuration.",
+      to: './sub-components#federal-taxes',
+    },
+    {
+      title: 'State taxes',
+      description: "Form for the employee's state tax configuration across applicable states.",
+      to: './sub-components#state-taxes',
+    },
+    {
+      title: 'Payment method',
+      description: 'Configure employee bank accounts, including split-paycheck setup.',
+      to: './sub-components#payment-method',
+    },
+    {
+      title: 'Deductions',
+      description:
+        'Configure additional withholdings from employee pay — percentage or fixed amount, recurring or one-time.',
+      to: './sub-components#deductions',
+    },
+    {
+      title: 'Documents',
+      description:
+        'Configure which documents are included in the employee onboarding experience, including the I-9.',
+      to: './sub-components#documents',
+    },
+    {
+      title: 'Onboarding summary',
+      description: "Summary of the employee's current onboarding state.",
+      to: './sub-components#onboarding-summary',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.md b/docs/workflows-overview/employee-onboarding/sub-components.md
similarity index 88%
rename from docs/workflows-overview/employee-onboarding/employee-onboarding.md
rename to docs/workflows-overview/employee-onboarding/sub-components.md
index 3b98701b6..f364cffdd 100644
--- a/docs/workflows-overview/employee-onboarding/employee-onboarding.md
+++ b/docs/workflows-overview/employee-onboarding/sub-components.md
@@ -1,59 +1,18 @@
 ---
-title: Employee Onboarding
-description: Complete workflow for onboarding an employee to payroll — profile, compensation, taxes, payment method, and document signing, with optional I-9 step.
-order: 0
+title: Sub-components
+description: Standalone sub-components for admin-driven employee onboarding — render in isolation or compose into a custom workflow.
+order: 2
 ---
 
-The Employee Onboarding workflow provides a complete experience for onboarding an employee to a company. It is used to collect all required information for an employee to be added to payroll.
-
-### Implementation
-
-```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <EmployeeOnboarding.OnboardingFlow
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      withEmployeeI9
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name                    | Type    | Default | Description                                                                                                                                                          |
-| ----------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| employeeId              | string  |         | The associated employee identifier.                                                                                                                                  |
-| companyId Required      | string  |         | The associated company identifier.                                                                                                                                   |
-| defaultValues           | object  |         | Default values for individual flow step components                                                                                                                   |
-| onEvent Required        |         |         | See events table for each subcomponent to see available events.                                                                                                      |
-| isSelfOnboardingEnabled | boolean | true    | When true, presents the self-onboarding toggle allowing the admin to opt the employee into self-onboarding. When false, the option to self-onboard is not available. |
-| withEmployeeI9          | boolean | false   | When true, enables the Employee Documents step in the onboarding flow, allowing the admin to configure I-9 document requirements.                                    |
-
-## Using Employee Subcomponents
+# Employee Onboarding sub-components
 
 Employee onboarding components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
-### Available Subcomponents
-
-- [EmployeeOnboarding.EmployeeList](#employeelist)
-- [EmployeeOnboarding.Profile](#employeeprofile)
-- [EmployeeOnboarding.Compensation](#employeecompensation)
-- [EmployeeOnboarding.FederalTaxes](#employeeonboardingfederaltaxes--employeemanagementfederaltaxes)
-- [EmployeeOnboarding.StateTaxes / EmployeeManagement.StateTaxes](#employeeonboardingstatetaxes--employeemanagementstatetaxes)
-- [EmployeeOnboarding.PaymentMethod](#employeepaymentmethod)
-- [EmployeeOnboarding.Deductions](#employeedeductions)
-- [EmployeeOnboarding.EmployeeDocuments](#employeeemployeedocuments)
-- [EmployeeOnboarding.OnboardingSummary](#employeeonboardingsummary)
-
-> Legacy imports via `Employee.*` (e.g. `Employee.EmployeeList`) continue to work.
+---
 
-### Employee.List
+## Employees list
 
-Displays a list of employees containing their full name, and their current onboarding status. An onboarding status. This list also contains actions that allow for the editing or removal of an employee.
+Displays a list of employees containing their full name and their current onboarding status. The list also includes actions for editing or removing an employee.
 
 ```jsx
 import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
@@ -84,7 +43,9 @@ function MyApp() {
 | EMPLOYEE_ONBOARDING_STATUS_UPDATED | Fired after the "Review" or "Cancel self-onboarding" action updates the employee's onboarding status | The updated `EmployeeOnboardingStatus` record       |
 | EMPLOYEE_DELETED                   | Fired after selecting delete from the employee actions menu and the delete operation completes       | `{ employeeId: string }`                            |
 
-### Employee.Profile
+---
+
+## Profile
 
 Used to collect basic information about the employee:
 
@@ -136,7 +97,9 @@ function MyComponent() {
 | EMPLOYEE_PROFILE_DONE         | Fired after form submission and all api calls have finished and we are ready to advance to the next step | Called with an object aggregated with the responses above. This either includes all of the responses for creating new entities (if it is creating a new employee) or all the responses for updating entities (if it is updating an existing employee) |
 | CANCEL                        | Fired when user clicks cancel button                                                                     | None                                                                                                                                                                                                                                                  |
 
-### Employee.Compensation
+---
+
+## Compensation
 
 Collects details related to the role of the employee and their compensation:
 
@@ -180,7 +143,9 @@ function MyComponent() {
 | EMPLOYEE_COMPENSATION_UPDATED | Fired after updating compensation details                                                      | Response from the Update a compensation endpoint |
 | EMPLOYEE_COMPENSATION_DONE    | Fired when compensation setup is complete and we are ready to advance to the next step         | None                                             |
 
-### EmployeeOnboarding.FederalTaxes / EmployeeManagement.FederalTaxes
+---
+
+## Federal taxes
 
 Provides required form inputs for employee federal tax configuration. The component ships in two journey-scoped variants that share the same form rendering but differ in CTAs and emitted events; pick the variant that matches your screen instead of toggling a prop.
 
@@ -228,7 +193,9 @@ function ManagementEditScreen() {
 | EMPLOYEE_FEDERAL_TAXES_DONE    | Onboarding only        | Fired after a successful save, signalling the parent flow can advance to the next step             | None                                                                                                                                                                                                      |
 | CANCEL                         | Management only        | Fired when the user clicks the Cancel button                                                       | None                                                                                                                                                                                                      |
 
-### EmployeeOnboarding.StateTaxes / EmployeeManagement.StateTaxes
+---
+
+## State taxes
 
 Provides required form inputs for employee state tax configuration. The component ships in two journey-scoped variants that share the same form rendering but differ in CTAs, emitted events, and visible questions; pick the variant that matches your screen instead of toggling a prop.
 
@@ -277,7 +244,9 @@ function ManagementEditScreen() {
 | EMPLOYEE_STATE_TAXES_DONE    | Onboarding only        | Fired after a successful save, signalling the parent flow can advance to the next step | None                                                   |
 | CANCEL                       | Management only        | Fired when the user clicks the Cancel button                                           | None                                                   |
 
-### Employee.PaymentMethod
+---
+
+## Payment method
 
 Used for configuring employee bank account(s). Bank accounts created with this component will be used to pay the employee when payroll is run. Payments can be split across multiple accounts.
 
@@ -308,7 +277,9 @@ function MyComponent() {
 | EMPLOYEE_PAYMENT_METHOD_UPDATED | Fired when the employee updates the payment method by selecting the continue CTA or if they opt to split paychecks and save the split paycheck form | Response from the Update payment method endpoint |
 | EMPLOYEE_PAYMENT_METHOD_DONE    | Fired when the continue CTA is selected on the payment details step, all API calls are finished, and we are ready to advance to the next step       | None                                             |
 
-### Employee.Deductions
+---
+
+## Deductions
 
 Used for configuring additional withholdings from employee pay. Deductions can be set by percentage or fixed amount, and can be either recurring or one-time.
 
@@ -339,7 +310,9 @@ function MyComponent() {
 | EMPLOYEE_DEDUCTION_DELETED | Fired after deleting a deduction                                                       | Response from the Update a garnishment endpoint with active:false |
 | EMPLOYEE_DEDUCTION_DONE    | Fired when deductions setup is complete and user is ready to navigate to the next step | None                                                              |
 
-### Employee.EmployeeDocuments
+---
+
+## Documents
 
 Used during admin onboarding to configure which documents are included in the employee's self-onboarding experience. When the employee has been invited to self-onboard, this step allows the admin to enable or disable the I-9 (Employment Eligibility Verification) form. When the employee is not self-onboarding, this step displays a read-only summary of the documents that will be part of the onboarding process.
 
@@ -372,7 +345,9 @@ function MyComponent() {
 | EMPLOYEE_ONBOARDING_DOCUMENTS_CONFIG_UPDATED | Fired after the admin toggles the I-9 inclusion checkbox and the configuration is successfully updated | Response from the [Update an employee's onboarding documents config](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-onboarding_documents_config) endpoint |
 | EMPLOYEE_DOCUMENTS_CONTINUE                  | Fired when the admin clicks continue and is ready to advance to the next step                          | None                                                                                                                                                                                      |
 
-### Employee.OnboardingSummary
+---
+
+## Onboarding summary
 
 Displays the current state of employee onboarding.
 
diff --git a/docs/workflows-overview/employee-onboarding/workflow.md b/docs/workflows-overview/employee-onboarding/workflow.md
new file mode 100644
index 000000000..2c8333c15
--- /dev/null
+++ b/docs/workflows-overview/employee-onboarding/workflow.md
@@ -0,0 +1,38 @@
+---
+title: Workflow
+description: Drop-in EmployeeOnboarding.OnboardingFlow component that renders the entire admin-driven employee onboarding experience.
+order: 1
+---
+
+# Employee Onboarding workflow
+
+The Employee Onboarding workflow renders the full admin-driven onboarding experience as a single component. Drop it into your app and it walks the admin through every step required to add an employee to payroll.
+
+---
+
+## Implementation
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <EmployeeOnboarding.OnboardingFlow
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      withEmployeeI9
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name                    | Type    | Default | Description                                                                                                                                                          |
+| ----------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| employeeId              | string  |         | The associated employee identifier.                                                                                                                                  |
+| companyId Required      | string  |         | The associated company identifier.                                                                                                                                   |
+| defaultValues           | object  |         | Default values for individual flow step components                                                                                                                   |
+| onEvent Required        |         |         | See events table for each subcomponent to see available events.                                                                                                      |
+| isSelfOnboardingEnabled | boolean | true    | When true, presents the self-onboarding toggle allowing the admin to opt the employee into self-onboarding. When false, the option to self-onboard is not available. |
+| withEmployeeI9          | boolean | false   | When true, enables the Employee Documents step in the onboarding flow, allowing the admin to configure I-9 document requirements.                                    |
diff --git a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
new file mode 100644
index 000000000..257899c7d
--- /dev/null
+++ b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
@@ -0,0 +1,71 @@
+---
+title: Employee self-onboarding
+description: Employee-driven onboarding flow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+When an admin opts an employee into self-onboarding, the employee completes their own onboarding steps — profile, tax, payment method, and document signing — rather than the admin entering everything on their behalf. The workflow can be composed end-to-end as a single component, or built from standalone sub-components when you need full control over the surrounding experience.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire employee-driven self-onboarding experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Welcome screen',
+      description: 'Guidance for the employee on what to expect from self-onboarding and what to have on hand.',
+      to: './sub-components#welcome-screen',
+    },
+    {
+      title: 'Profile',
+      description: "Collect the employee's basic info — name, email, SSN, date of birth, home address.",
+      to: './sub-components#profile',
+    },
+    {
+      title: 'Federal taxes',
+      description: "Form for the employee's federal tax (W-4) withholding configuration.",
+      to: './sub-components#federal-taxes',
+    },
+    {
+      title: 'State taxes',
+      description: "Form for the employee's state tax configuration across applicable states.",
+      to: './sub-components#state-taxes',
+    },
+    {
+      title: 'Payment method',
+      description: 'Configure employee bank accounts, including split-paycheck setup.',
+      to: './sub-components#payment-method',
+    },
+    {
+      title: 'Sign documents',
+      description: 'Read and sign required employment documents, with optional I-9 routing.',
+      to: './sub-components#sign-documents',
+    },
+    {
+      title: 'Employment eligibility',
+      description: "Collect the employee's I-9 employment eligibility details — citizenship status and supporting documents.",
+      to: './sub-components#employment-eligibility',
+    },
+    {
+      title: 'Onboarding summary',
+      description: "Summary of the employee's current onboarding state.",
+      to: './sub-components#onboarding-summary',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/employee-onboarding/employee-self-onboarding.md b/docs/workflows-overview/employee-self-onboarding/sub-components.md
similarity index 65%
rename from docs/workflows-overview/employee-onboarding/employee-self-onboarding.md
rename to docs/workflows-overview/employee-self-onboarding/sub-components.md
index 6174b9842..efddcdba1 100644
--- a/docs/workflows-overview/employee-onboarding/employee-self-onboarding.md
+++ b/docs/workflows-overview/employee-self-onboarding/sub-components.md
@@ -1,55 +1,18 @@
 ---
-title: Employee Self-Onboarding
-description: Employee-driven onboarding flow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information.
-order: 0
+title: Sub-components
+description: Standalone sub-components for employee-driven self-onboarding — render in isolation or compose into a custom workflow.
+order: 2
 ---
 
-In the case an employer elects to allow the employee to self-onboard, they can be provided with the self-onboarding workflow. This workflow places the responsibility of submitting some required information on the employee.
+# Employee Self-Onboarding sub-components
 
-### Implementation
-
-```jsx
-import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <EmployeeOnboarding.SelfOnboardingFlow
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      employeeId="4b3f930f-82cd-48a8-b797-798686e12e5e"
-      withEmployeeI9
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name                | Type    | Default | Description                                                                                                                                       |
-| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| employeeId Required | string  |         | The associated employee identifier.                                                                                                               |
-| companyId Required  | string  |         | The associated company identifier.                                                                                                                |
-| onEvent Required    |         |         | See events table for each subcomponent to see available events.                                                                                   |
-| withEmployeeI9      | boolean | false   | When true, the Document Signer step checks if the employee has I-9 enabled and routes to the Employment Eligibility and I-9 signature form steps. |
-
-## Using Self-Onboarding Subcomponents
-
-Like Employee onboarding, self-onboarding components can be used to compose your own workflow, or be rendered in isolation. Many of these components are the same as the ones used for general employee onboarding, however some fields are hidden and shown based on the current user type. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [EmployeeOnboarding.Landing](#employeeonboardinglanding)
-- [EmployeeOnboarding.Profile](#employeeonboardingprofile)
-- [EmployeeOnboarding.FederalTaxes](#employeeonboardingfederaltaxes)
-- [EmployeeOnboarding.StateTaxes](#employeeonboardingstatetaxes)
-- [EmployeeOnboarding.PaymentMethod](#employeeonboardingpaymentmethod)
-- [EmployeeOnboarding.DocumentSigner](#employeeonboardingdocumentsigner)
-- [EmployeeOnboarding.EmploymentEligibility](#employeeonboardingemploymenteligibility)
-- [EmployeeOnboarding.OnboardingSummary](#employee-onboarding-summary)
+Like the admin-driven employee onboarding, self-onboarding components can be used to compose your own workflow or be rendered in isolation. Many of these components are the same as the ones used for general employee onboarding; some fields are hidden or shown based on the current user type. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
 > Legacy imports via `Employee.*` (e.g. `Employee.Landing`) continue to work.
 
-### EmployeeOnboarding.Landing
+---
+
+## Welcome screen
 
 Displays guidance on what to expect from the workflow and what information the employee will be required to have on hand and provide.
 
@@ -81,11 +44,13 @@ function MyApp() {
 | ------------------------------ | --------------------------------------------------------------------------------------------- | ---- |
 | EMPLOYEE_SELF_ONBOARDING_START | Fired when the employee selects the get started CTA and is ready to navigate to the next step | None |
 
-### EmployeeOnboarding.Profile
+---
+
+## Profile
 
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Profile in Employee Onboarding sub-components](../employee-onboarding/sub-components#profile) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
 
-When used in self onboarding, used to collect basic information about the employee:
+When used in self-onboarding, this component collects basic information about the employee:
 
 - First and last name
 - Email address
@@ -93,7 +58,7 @@ When used in self onboarding, used to collect basic information about the employ
 - Date of birth
 - And home address
 
-For self onboarding, you need to be sure to set the `employeeId` property. The `isAdmin` property should be left out or set to false (which is the setting by default). The following example has the Profile component configured for self onboarding:
+For self-onboarding, set the `employeeId` property and leave `isAdmin` out (or set it to `false`, the default). The example below has the Profile component configured for self-onboarding:
 
 ```jsx
 import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
@@ -109,9 +74,11 @@ function MyApp() {
 }
 ```
 
-### EmployeeOnboarding.FederalTaxes
+---
+
+## Federal taxes
 
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Federal taxes in Employee Onboarding sub-components](../employee-onboarding/sub-components#federal-taxes) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
 
 Provides required form inputs for employee federal tax configuration.
 
@@ -128,9 +95,11 @@ function MyComponent() {
 }
 ```
 
-### EmployeeOnboarding.StateTaxes
+---
+
+## State taxes
 
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [State taxes in Employee Onboarding sub-components](../employee-onboarding/sub-components#state-taxes) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
 
 Provides required form inputs for employee state tax configuration.
 
@@ -147,9 +116,11 @@ function MyComponent() {
 }
 ```
 
-### EmployeeOnboarding.PaymentMethod
+---
 
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+## Payment method
+
+_See [Payment method in Employee Onboarding sub-components](../employee-onboarding/sub-components#payment-method) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
 
 Used for configuring employee bank account(s). Bank accounts created with this component will be used to pay the employee when payroll is run. Payments can be split across multiple accounts.
 
@@ -166,7 +137,9 @@ function MyComponent() {
 }
 ```
 
-### EmployeeOnboarding.DocumentSigner
+---
+
+## Sign documents
 
 Provides the employee with an interface to read and sign required employment documents. When `withEmployeeI9` is enabled and the employee has I-9 configured, the Document Signer will first route the employee through the Employment Eligibility step and then present the I-9 form for signature alongside other required documents.
 
@@ -201,7 +174,9 @@ function MyComponent() {
 | EMPLOYEE_SIGN_FORM                   | Fired when the user submits the form to sign                                                   | Response from the [Sign an employee form](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-forms-form_id-sign) endpoint                                                                          |
 | EMPLOYEE_FORMS_DONE                  | Fired when the user is done signing forms and is ready to advance to the next step in the flow | None                                                                                                                                                                                                                           |
 
-### EmployeeOnboarding.EmploymentEligibility
+---
+
+## Employment eligibility
 
 A standalone form for collecting an employee's I-9 employment eligibility (Section 1) details, including authorization status (citizen, non-citizen national, permanent resident, alien) and supporting document information when applicable. This is the lower-level building block used internally by `EmployeeOnboarding.DocumentSigner` when `withEmployeeI9` is enabled. Use this component directly when you want to collect I-9 details outside of the document-signing flow or compose a custom routing experience.
 
@@ -231,13 +206,15 @@ function MyComponent() {
 | ------------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | EMPLOYEE_EMPLOYMENT_ELIGIBILITY_DONE | Fired when the employee completes the employment eligibility form | Response from the [Create or update an employee's I-9 authorization](https://docs.gusto.com/embedded-payroll/reference/put-v1-employees-employee_id-i9_authorization) endpoint |
 
-### Employee Onboarding Summary
+---
+
+## Onboarding summary
 
-_See component documentation in the Employee Onboarding section for a complete list of props and events since this component is used in both employee onboarding and employee self onboarding._
+_See [Onboarding summary in Employee Onboarding sub-components](../employee-onboarding/sub-components#onboarding-summary) for a complete list of props and events — this component is used in both employee onboarding and employee self-onboarding._
 
 Displays the current state of employee onboarding.
 
-The `isAdmin` property should be left out or set to false (which is the setting by default). The following example has the OnboardingSummary component configured for self onboarding:
+For self-onboarding, leave `isAdmin` out (or set it to `false`, the default). The example below has the OnboardingSummary component configured for self-onboarding:
 
 ```jsx
 import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
diff --git a/docs/workflows-overview/employee-self-onboarding/workflow.md b/docs/workflows-overview/employee-self-onboarding/workflow.md
new file mode 100644
index 000000000..7aec01eef
--- /dev/null
+++ b/docs/workflows-overview/employee-self-onboarding/workflow.md
@@ -0,0 +1,37 @@
+---
+title: Workflow
+description: Drop-in EmployeeOnboarding.SelfOnboardingFlow component that renders the entire employee-driven self-onboarding experience.
+order: 1
+---
+
+# Employee Self-Onboarding workflow
+
+The Employee Self-Onboarding workflow renders the full employee-driven onboarding experience as a single component. Drop it into your app and the employee walks themselves through every required step.
+
+---
+
+## Implementation
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <EmployeeOnboarding.SelfOnboardingFlow
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      employeeId="4b3f930f-82cd-48a8-b797-798686e12e5e"
+      withEmployeeI9
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name                | Type    | Default | Description                                                                                                                                       |
+| ------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| employeeId Required | string  |         | The associated employee identifier.                                                                                                               |
+| companyId Required  | string  |         | The associated company identifier.                                                                                                                |
+| onEvent Required    |         |         | See events table for each subcomponent to see available events.                                                                                   |
+| withEmployeeI9      | boolean | false   | When true, the Document Signer step checks if the employee has I-9 enabled and routes to the Employment Eligibility and I-9 signature form steps. |
diff --git a/docs/workflows-overview/employees.mdx b/docs/workflows-overview/employees.mdx
new file mode 100644
index 000000000..5e76d4b3a
--- /dev/null
+++ b/docs/workflows-overview/employees.mdx
@@ -0,0 +1,19 @@
+---
+title: Employees
+description: SDK surface for onboarding new employees — admin-driven and employee-driven (self-onboarding) flows.
+order: 2
+---
+
+The Employees surface covers everything required to onboard new employees, whether the company admin drives the experience end-to-end or the employee completes onboarding themselves.
+
+## Employee onboarding
+
+An admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.
+
+[Read more →](./employee-onboarding/employee-onboarding.mdx)
+
+## Employee self-onboarding
+
+An employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.
+
+[Read more →](./employee-self-onboarding/employee-self-onboarding.mdx)
diff --git a/docs/workflows-overview/information-requests.md b/docs/workflows-overview/information-requests.md
deleted file mode 100644
index 1cc553842..000000000
--- a/docs/workflows-overview/information-requests.md
+++ /dev/null
@@ -1,141 +0,0 @@
----
-title: Information Requests
-description: Standalone surface for viewing and responding to outstanding information requests Gusto has issued for a company, such as missing tax or identity documents.
-order: 8
----
-
-The Information Requests workflow surfaces outstanding information requests that Gusto has issued for a company (for example, a request for a missing tax document or identity verification artifact) and lets the user respond to them. Information requests can also block payroll processing, in which case they are surfaced inline within `Payroll.PayrollBlockerList`; this flow provides a dedicated, standalone surface for managing them.
-
-### Implementation
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return (
-    <InformationRequests.InformationRequestsFlow
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name               | Type     | Default | Description                                                                                                                                                                               |
-| ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required | string   |         | The associated company identifier.                                                                                                                                                        |
-| onEvent            | function |         | See events table for each subcomponent to see available events.                                                                                                                           |
-| withAlert          | boolean  | `true`  | When true, the submission success alert is rendered at the top of the flow. Set to false when embedding in a parent (e.g. `Payroll.PayrollBlockerList`) that renders the alert elsewhere. |
-| dictionary         | object   |         | Optional translations for component text.                                                                                                                                                 |
-
-#### Events
-
-Events emitted by the flow (and by its subcomponents — they bubble up through `onEvent`):
-
-| Event type                      | Description                                                                         | Data                                                  |
-| ------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| INFORMATION_REQUEST_RESPOND     | Fired when the user clicks "Respond" on a request and the form modal opens          | { requestId: string }                                 |
-| INFORMATION_REQUEST_FORM_DONE   | Fired when an information request is successfully submitted                         | Response from the Submit information request endpoint |
-| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the response form (closes the modal without submitting) | None                                                  |
-
-## Workflow Steps
-
-1. **List**: The user sees all open and submitted information requests for the company, with status badges and a "Respond" CTA on each open request.
-2. **Respond**: Selecting "Respond" opens a modal with a dynamically rendered form built from the request's required questions (text, document upload). Persona-style questions and other unsupported response types fall back to a guidance message rather than rendering the form.
-3. **Submit**: On successful submit, a dismissible success alert appears at the top of the list (when `withAlert` is true) and the modal closes.
-
-## Using Information Requests Subcomponents
-
-Information requests components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [InformationRequests.InformationRequestList](#informationrequestsinformationrequestlist)
-- [InformationRequests.InformationRequestForm](#informationrequestsinformationrequestform)
-
-### InformationRequests.InformationRequestList
-
-Displays a list of information requests for a company, including status badges (Open / Submitted) and a "Respond" CTA for open requests. Used as the top-level surface of `InformationRequests.InformationRequestsFlow`, but can be rendered directly when you want to host the response form yourself (e.g. in a custom modal or page).
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return (
-    <InformationRequests.InformationRequestList
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name                     | Type     | Description                               |
-| ------------------------ | -------- | ----------------------------------------- |
-| **companyId** (Required) | string   | The associated company identifier.        |
-| **onEvent** (Required)   | function | See events table for available events.    |
-| dictionary               | object   | Optional translations for component text. |
-
-#### Events
-
-| Event type                  | Description                                             | Data                  |
-| --------------------------- | ------------------------------------------------------- | --------------------- |
-| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on an open request | { requestId: string } |
-
-### InformationRequests.InformationRequestForm
-
-The dynamic response form for a single information request. Renders supported question types (text and document upload) based on the request's `requiredQuestions` payload from the API and submits responses via the [Submit information request endpoint](https://docs.gusto.com/embedded-payroll/reference/post-information-requests-submit). Use this component directly when you have built your own list/routing surface and need to host the form (typically inside a modal or page you control).
-
-```jsx
-import { InformationRequests } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return (
-    <InformationRequests.InformationRequestForm
-      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
-      requestId="information-request-uuid"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
-
-| Name                     | Type     | Description                                              |
-| ------------------------ | -------- | -------------------------------------------------------- |
-| **companyId** (Required) | string   | The associated company identifier.                       |
-| **requestId** (Required) | string   | The identifier of the information request to respond to. |
-| **onEvent** (Required)   | function | See events table for available events.                   |
-| dictionary               | object   | Optional translations for component text.                |
-
-#### Events
-
-| Event type                      | Description                                   | Data                                                  |
-| ------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
-| INFORMATION_REQUEST_FORM_DONE   | Fired when the form is successfully submitted | Response from the Submit information request endpoint |
-| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the form          | None                                                  |
-
-#### Supported Response Types
-
-The form currently renders inputs for the following `responseType` values:
-
-- **`text`** — single-line text input (max 5,000 characters)
-- **`document`** — file upload restricted to JPEG, PNG, or PDF
-
-Requests with unsupported response types (e.g. `persona`-driven identity verification) display a guidance message instead of the form. In those cases the user must complete the request through the partner's own integration with the underlying provider.
-
-## Integration with Payroll Blockers
-
-Information requests can also block payroll processing. When that happens they are surfaced inside [`Payroll.PayrollBlockerList`](./run-payroll.md#payrollpayrollblockerlist), which embeds `InformationRequests.InformationRequestsFlow` with `withAlert={false}` so the blocker list owns the success alert UX. If you build your own blocker resolution surface, you can use the same pattern.
-
-## API Reference
-
-The information requests workflow uses these API endpoints:
-
-- **List information requests**: `GET /v1/companies/{company_uuid}/information_requests`
-- **Submit an information request**: `POST /v1/information_requests/{information_request_uuid}/submit`
diff --git a/docs/workflows-overview/information-requests/information-requests.mdx b/docs/workflows-overview/information-requests/information-requests.mdx
new file mode 100644
index 000000000..11897a3e9
--- /dev/null
+++ b/docs/workflows-overview/information-requests/information-requests.mdx
@@ -0,0 +1,41 @@
+---
+title: Information Requests
+description: Standalone surface for viewing and responding to outstanding information requests Gusto has issued for a company.
+order: 8
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Information Requests surface lets a company view and respond to outstanding information requests Gusto has issued — for example, a request for a missing tax document or identity verification artifact. Information requests can also block payroll processing, in which case they surface inline within `Payroll.PayrollBlockerList`; this surface is the dedicated, standalone version.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the full list-and-respond experience for outstanding information requests.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Information requests list',
+      description: 'List of information requests for a company with status badges and a "Respond" CTA.',
+      to: './sub-components#information-requests-list',
+    },
+    {
+      title: 'Information request form',
+      description: 'Dynamic response form for a single information request, rendered from the required questions.',
+      to: './sub-components#information-request-form',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/information-requests/sub-components.md b/docs/workflows-overview/information-requests/sub-components.md
new file mode 100644
index 000000000..0aaa7ec7c
--- /dev/null
+++ b/docs/workflows-overview/information-requests/sub-components.md
@@ -0,0 +1,94 @@
+---
+title: Sub-components
+description: Standalone sub-components for information requests — render the list or response form individually.
+order: 2
+---
+
+# Information Requests sub-components
+
+Information requests components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+---
+
+## Information requests list
+
+Displays a list of information requests for a company, including status badges (Open / Submitted) and a "Respond" CTA for open requests. Used as the top-level surface of `InformationRequests.InformationRequestsFlow`, but can be rendered directly when you want to host the response form yourself (e.g. in a custom modal or page).
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return (
+    <InformationRequests.InformationRequestList
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name                     | Type     | Description                               |
+| ------------------------ | -------- | ----------------------------------------- |
+| **companyId** (Required) | string   | The associated company identifier.        |
+| **onEvent** (Required)   | function | See events table for available events.    |
+| dictionary               | object   | Optional translations for component text. |
+
+#### Events
+
+| Event type                  | Description                                             | Data                  |
+| --------------------------- | ------------------------------------------------------- | --------------------- |
+| INFORMATION_REQUEST_RESPOND | Fired when the user clicks "Respond" on an open request | { requestId: string } |
+
+---
+
+## Information request form
+
+The dynamic response form for a single information request. Renders supported question types (text and document upload) based on the request's `requiredQuestions` payload from the API and submits responses via the [Submit information request endpoint](https://docs.gusto.com/embedded-payroll/reference/post-information-requests-submit). Use this component directly when you have built your own list/routing surface and need to host the form (typically inside a modal or page you control).
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return (
+    <InformationRequests.InformationRequestForm
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      requestId="information-request-uuid"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name                     | Type     | Description                                              |
+| ------------------------ | -------- | -------------------------------------------------------- |
+| **companyId** (Required) | string   | The associated company identifier.                       |
+| **requestId** (Required) | string   | The identifier of the information request to respond to. |
+| **onEvent** (Required)   | function | See events table for available events.                   |
+| dictionary               | object   | Optional translations for component text.                |
+
+#### Events
+
+| Event type                      | Description                                   | Data                                                  |
+| ------------------------------- | --------------------------------------------- | ----------------------------------------------------- |
+| INFORMATION_REQUEST_FORM_DONE   | Fired when the form is successfully submitted | Response from the Submit information request endpoint |
+| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the form          | None                                                  |
+
+#### Supported Response Types
+
+The form currently renders inputs for the following `responseType` values:
+
+- **`text`** — single-line text input (max 5,000 characters)
+- **`document`** — file upload restricted to JPEG, PNG, or PDF
+
+Requests with unsupported response types (e.g. `persona`-driven identity verification) display a guidance message instead of the form. In those cases the user must complete the request through the partner's own integration with the underlying provider.
+
+## API Reference
+
+The information requests workflow uses these API endpoints:
+
+- **List information requests**: `GET /v1/companies/{company_uuid}/information_requests`
+- **Submit an information request**: `POST /v1/information_requests/{information_request_uuid}/submit`
diff --git a/docs/workflows-overview/information-requests/workflow.md b/docs/workflows-overview/information-requests/workflow.md
new file mode 100644
index 000000000..2eaf376bd
--- /dev/null
+++ b/docs/workflows-overview/information-requests/workflow.md
@@ -0,0 +1,55 @@
+---
+title: Workflow
+description: Drop-in InformationRequests.InformationRequestsFlow component for viewing and responding to outstanding information requests.
+order: 1
+---
+
+# Information Requests workflow
+
+The Information Requests workflow renders the full list-and-respond experience as a single component. Drop it into your app and the user can view outstanding requests and submit responses without any additional wiring.
+
+---
+
+## Implementation
+
+```jsx
+import { InformationRequests } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return (
+    <InformationRequests.InformationRequestsFlow
+      companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name               | Type     | Default | Description                                                                                                                                                                               |
+| ------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required | string   |         | The associated company identifier.                                                                                                                                                        |
+| onEvent            | function |         | See events table for each subcomponent to see available events.                                                                                                                           |
+| withAlert          | boolean  | `true`  | When true, the submission success alert is rendered at the top of the flow. Set to false when embedding in a parent (e.g. `Payroll.PayrollBlockerList`) that renders the alert elsewhere. |
+| dictionary         | object   |         | Optional translations for component text.                                                                                                                                                 |
+
+#### Events
+
+Events emitted by the flow (and by its subcomponents — they bubble up through `onEvent`):
+
+| Event type                      | Description                                                                         | Data                                                  |
+| ------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| INFORMATION_REQUEST_RESPOND     | Fired when the user clicks "Respond" on a request and the form modal opens          | { requestId: string }                                 |
+| INFORMATION_REQUEST_FORM_DONE   | Fired when an information request is successfully submitted                         | Response from the Submit information request endpoint |
+| INFORMATION_REQUEST_FORM_CANCEL | Fired when the user cancels the response form (closes the modal without submitting) | None                                                  |
+
+## Workflow Steps
+
+1. **List**: The user sees all open and submitted information requests for the company, with status badges and a "Respond" CTA on each open request.
+2. **Respond**: Selecting "Respond" opens a modal with a dynamically rendered form built from the request's required questions (text, document upload). Persona-style questions and other unsupported response types fall back to a guidance message rather than rendering the form.
+3. **Submit**: On successful submit, a dismissible success alert appears at the top of the list (when `withAlert` is true) and the modal closes.
+
+## Integration with Payroll Blockers
+
+Information requests can also block payroll processing. When that happens they are surfaced inside [`Payroll.PayrollBlockerList`](../run-payroll/sub-components#blockers), which embeds `InformationRequests.InformationRequestsFlow` with `withAlert={false}` so the blocker list owns the success alert UX. If you build your own blocker resolution surface, you can use the same pattern.
diff --git a/docs/workflows-overview/off-cycle-payroll.md b/docs/workflows-overview/off-cycle-payroll.md
deleted file mode 100644
index 34e02ac9a..000000000
--- a/docs/workflows-overview/off-cycle-payroll.md
+++ /dev/null
@@ -1,172 +0,0 @@
----
-title: Off-Cycle Payroll (Bonus & Correction)
-description: Workflow for running payrolls outside the regular pay schedule — bonus or correction — then transitioning into the standard payroll processing execution.
-order: 5
----
-
-The Off-Cycle Payroll workflow provides a complete experience for running payrolls outside of a company's regular pay schedule. It supports two off-cycle reasons: **Bonus** (paying a bonus, gift, or commission) and **Correction** (running a correction payment). The flow guides users through configuring pay period dates, selecting a reason, choosing employees, setting deduction and tax withholding preferences, and then executing the payroll.
-
-After creation, the flow transitions into the standard [Payroll Processing](./run-payroll.md) execution experience (configuration, overview, submission, and receipts). All off-cycle payroll types share the same execution steps as regular payrolls — the only difference is how the payroll is created.
-
-### Implementation
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return <Payroll.OffCycleFlow companyId="your-company-id" onEvent={() => {}} />
-}
-```
-
-#### Props
-
-| Name               | Type                        | Description                                                                                                |
-| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| companyId Required | string                      | The associated company identifier.                                                                         |
-| onEvent Required   | function                    | See events table for each subcomponent to see available events.                                            |
-| payrollType        | `'bonus'` \| `'correction'` | Optional pre-selected off-cycle reason. When provided, the creation form starts with this reason selected. |
-
-#### Events
-
-Events emitted during the creation phase:
-
-| Event type        | Description                                 | Data                    |
-| ----------------- | ------------------------------------------- | ----------------------- |
-| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
-
-Additional events are available when using the standalone subcomponents (`Payroll.OffCycleReasonSelection` and `Payroll.OffCycleDeductionsSetting`) — see their individual event tables below.
-
-Once the payroll is created and the flow transitions to execution, all standard [run payroll events](./run-payroll.md) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Workflow Steps
-
-1. **Creation**: User configures pay period dates, selects a reason (bonus or correction), chooses employees, and sets deduction/withholding preferences
-2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts
-
-## Off-Cycle Reasons
-
-The creation form presents two reasons with different defaults:
-
-| Reason     | Description                                        | Default Deductions         | Default Withholding |
-| ---------- | -------------------------------------------------- | -------------------------- | ------------------- |
-| Bonus      | Pay a bonus, gift, or commission                   | Skip regular deductions    | Supplemental rate   |
-| Correction | Run a payroll outside of your regular pay schedule | Include regular deductions | Regular rate        |
-
-When the user changes the reason, deduction and withholding defaults update automatically.
-
-## Using Off-Cycle Subcomponents
-
-Off-cycle components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.OffCycleCreation](#payrolloffcyclecreation)
-- [Payroll.OffCycleReasonSelection](#payrolloffcyclereasonselection)
-- [Payroll.OffCycleDeductionsSetting](#payrolloffcycledeductionssetting)
-
-After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
-
-### Payroll.OffCycleCreation
-
-The main creation form for off-cycle payrolls. Includes reason selection, pay period date configuration, employee selection, deduction settings, and tax withholding configuration.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return <Payroll.OffCycleCreation companyId="your-company-id" onEvent={() => {}} />
-}
-```
-
-#### Props
-
-| Name               | Type                        | Description                                                |
-| ------------------ | --------------------------- | ---------------------------------------------------------- |
-| companyId Required | string                      | The associated company identifier.                         |
-| onEvent Required   | function                    | See events table for available events.                     |
-| payrollType        | `'bonus'` \| `'correction'` | Optional pre-selected payroll type. Defaults to `'bonus'`. |
-| dictionary         | object                      | Optional translations for component text.                  |
-
-#### Events
-
-| Event type        | Description                                 | Data                    |
-| ----------------- | ------------------------------------------- | ----------------------- |
-| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
-
-#### Form Fields
-
-- **Check-only payroll**: Toggle for check-only payments — when enabled, all employees will be paid by check (not direct deposit), the check date can be set to today or any future date, and start/end dates are not required
-- **Start date**: Beginning of the pay period (required unless check-only; cannot be in the future for correction payrolls)
-- **End date**: End of the pay period (required unless check-only; must be on or after start date)
-- **Payment date (check date)**: The date employees will be paid (must be at least 2 business days from today for direct deposit, unless check-only)
-- **Reason**: Bonus or Correction payment
-- **Employee selection**: Include all employees or select specific employees
-- **Deductions and contributions**: Include or skip regular deductions (see [OffCycleDeductionsSetting](#payrolloffcycledeductionssetting))
-- **Tax withholding rates**: Configure withholding pay period and rate type (regular or supplemental)
-
-### Payroll.OffCycleReasonSelection
-
-Presents the reason selection UI for choosing between a bonus and correction payment.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return <Payroll.OffCycleReasonSelection companyId="your-company-id" onEvent={() => {}} />
-}
-```
-
-#### Props
-
-| Name               | Type     | Description                               |
-| ------------------ | -------- | ----------------------------------------- |
-| companyId Required | string   | The associated company identifier.        |
-| onEvent Required   | function | See events table for available events.    |
-| dictionary         | object   | Optional translations for component text. |
-
-#### Events
-
-| Event type              | Description                      | Data                                                  |
-| ----------------------- | -------------------------------- | ----------------------------------------------------- |
-| OFF_CYCLE_SELECT_REASON | Fired when user selects a reason | { reason: 'bonus' \| 'correction', defaults: object } |
-
-The `defaults` object contains `{ skipDeductions: boolean, withholdingType: 'supplemental' | 'regular' }`.
-
-### Payroll.OffCycleDeductionsSetting
-
-Allows users to choose whether to include or skip regular deductions and contributions for the off-cycle payroll. Taxes are always included regardless of the selection.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return <Payroll.OffCycleDeductionsSetting skipRegularDeductions={true} onEvent={() => {}} />
-}
-```
-
-#### Props
-
-| Name                           | Type     | Description                                             |
-| ------------------------------ | -------- | ------------------------------------------------------- |
-| skipRegularDeductions Required | boolean  | Whether regular deductions are currently being skipped. |
-| onEvent Required               | function | See events table for available events.                  |
-| dictionary                     | object   | Optional translations for component text.               |
-
-#### Events
-
-| Event type                  | Description                             | Data                               |
-| --------------------------- | --------------------------------------- | ---------------------------------- |
-| OFF_CYCLE_DEDUCTIONS_CHANGE | Fired when deduction preference changes | { skipRegularDeductions: boolean } |
-
-#### Deduction Options
-
-- **Include**: Make all the regular deductions and contributions
-- **Skip**: Block all deductions and contributions, except 401(k). Taxes will be included.
-
-## API Reference
-
-The off-cycle payroll creation uses the [Create an off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls). After creation, the standard payroll execution endpoints apply:
-
-- **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
-- **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
-- **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
diff --git a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
new file mode 100644
index 000000000..0c33e84b1
--- /dev/null
+++ b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
@@ -0,0 +1,46 @@
+---
+title: Off-cycle payroll
+description: Workflow for running payrolls outside the regular pay schedule — bonus or correction — then transitioning into the standard payroll execution.
+order: 2
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay schedule. It supports two off-cycle reasons — **Bonus** (paying a bonus, gift, or commission) and **Correction** (running a correction payment) — and guides users through configuring pay period dates, selecting a reason, choosing employees, and setting deduction and tax withholding preferences. After creation, the flow transitions into the standard payroll execution experience.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that creates the off-cycle payroll and hands off to the standard execution flow.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Off-cycle creation',
+      description: 'Main creation form — reason, pay period dates, employee selection, deductions, and tax withholding.',
+      to: './sub-components#off-cycle-creation',
+    },
+    {
+      title: 'Reason selection',
+      description: 'Reason selection UI for choosing between a bonus and correction payment.',
+      to: './sub-components#reason-selection',
+    },
+    {
+      title: 'Deductions setting',
+      description: 'Choose whether to include or skip regular deductions for the off-cycle payroll.',
+      to: './sub-components#deductions-setting',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/off-cycle-payroll/sub-components.md b/docs/workflows-overview/off-cycle-payroll/sub-components.md
new file mode 100644
index 000000000..99662bc4b
--- /dev/null
+++ b/docs/workflows-overview/off-cycle-payroll/sub-components.md
@@ -0,0 +1,114 @@
+---
+title: Sub-components
+description: Standalone sub-components for off-cycle payroll — render in isolation or compose into a custom workflow.
+order: 2
+---
+
+# Off-Cycle Payroll sub-components
+
+Off-cycle components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+After creation, the off-cycle flow hands off to the shared [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
+
+---
+
+## Off-cycle creation
+
+The main creation form for off-cycle payrolls. Includes reason selection, pay period date configuration, employee selection, deduction settings, and tax withholding configuration.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return <Payroll.OffCycleCreation companyId="your-company-id" onEvent={() => {}} />
+}
+```
+
+#### Props
+
+| Name               | Type                        | Description                                                |
+| ------------------ | --------------------------- | ---------------------------------------------------------- |
+| companyId Required | string                      | The associated company identifier.                         |
+| onEvent Required   | function                    | See events table for available events.                     |
+| payrollType        | `'bonus'` \| `'correction'` | Optional pre-selected payroll type. Defaults to `'bonus'`. |
+| dictionary         | object                      | Optional translations for component text.                  |
+
+#### Events
+
+| Event type        | Description                                 | Data                    |
+| ----------------- | ------------------------------------------- | ----------------------- |
+| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
+
+#### Form fields
+
+- **Check-only payroll**: Toggle for check-only payments — when enabled, all employees will be paid by check (not direct deposit), the check date can be set to today or any future date, and start/end dates are not required
+- **Start date**: Beginning of the pay period (required unless check-only; cannot be in the future for correction payrolls)
+- **End date**: End of the pay period (required unless check-only; must be on or after start date)
+- **Payment date (check date)**: The date employees will be paid (must be at least 2 business days from today for direct deposit, unless check-only)
+- **Reason**: Bonus or Correction payment
+- **Employee selection**: Include all employees or select specific employees
+- **Deductions and contributions**: Include or skip regular deductions (see [Deductions setting](#deductions-setting))
+- **Tax withholding rates**: Configure withholding pay period and rate type (regular or supplemental)
+
+---
+
+## Reason selection
+
+Presents the reason selection UI for choosing between a bonus and correction payment.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return <Payroll.OffCycleReasonSelection companyId="your-company-id" onEvent={() => {}} />
+}
+```
+
+#### Props
+
+| Name               | Type     | Description                               |
+| ------------------ | -------- | ----------------------------------------- |
+| companyId Required | string   | The associated company identifier.        |
+| onEvent Required   | function | See events table for available events.    |
+| dictionary         | object   | Optional translations for component text. |
+
+#### Events
+
+| Event type              | Description                      | Data                                                  |
+| ----------------------- | -------------------------------- | ----------------------------------------------------- |
+| OFF_CYCLE_SELECT_REASON | Fired when user selects a reason | { reason: 'bonus' \| 'correction', defaults: object } |
+
+The `defaults` object contains `{ skipDeductions: boolean, withholdingType: 'supplemental' | 'regular' }`.
+
+---
+
+## Deductions setting
+
+Allows users to choose whether to include or skip regular deductions and contributions for the off-cycle payroll. Taxes are always included regardless of the selection.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return <Payroll.OffCycleDeductionsSetting skipRegularDeductions={true} onEvent={() => {}} />
+}
+```
+
+#### Props
+
+| Name                           | Type     | Description                                             |
+| ------------------------------ | -------- | ------------------------------------------------------- |
+| skipRegularDeductions Required | boolean  | Whether regular deductions are currently being skipped. |
+| onEvent Required               | function | See events table for available events.                  |
+| dictionary                     | object   | Optional translations for component text.               |
+
+#### Events
+
+| Event type                  | Description                             | Data                               |
+| --------------------------- | --------------------------------------- | ---------------------------------- |
+| OFF_CYCLE_DEDUCTIONS_CHANGE | Fired when deduction preference changes | { skipRegularDeductions: boolean } |
+
+#### Deduction options
+
+- **Include**: Make all the regular deductions and contributions
+- **Skip**: Block all deductions and contributions, except 401(k). Taxes will be included.
diff --git a/docs/workflows-overview/off-cycle-payroll/workflow.md b/docs/workflows-overview/off-cycle-payroll/workflow.md
new file mode 100644
index 000000000..467e8cae4
--- /dev/null
+++ b/docs/workflows-overview/off-cycle-payroll/workflow.md
@@ -0,0 +1,71 @@
+---
+title: Workflow
+description: Drop-in Payroll.OffCycleFlow component that creates the off-cycle payroll and hands off to the standard execution flow.
+order: 1
+---
+
+# Off-Cycle Payroll workflow
+
+The Off-Cycle Payroll workflow renders the full off-cycle experience — bonus or correction creation, then payroll execution — as a single component. After creation, the flow transitions into the standard [Payroll Processing](../run-payroll/run-payroll.mdx) execution experience (configuration, overview, submission, and receipts). All off-cycle payroll types share the same execution steps as regular payrolls — the only difference is how the payroll is created.
+
+---
+
+## Implementation
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return <Payroll.OffCycleFlow companyId="your-company-id" onEvent={() => {}} />
+}
+```
+
+#### Props
+
+| Name               | Type                        | Description                                                                                                |
+| ------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| companyId Required | string                      | The associated company identifier.                                                                         |
+| onEvent Required   | function                    | See events table for each subcomponent to see available events.                                            |
+| payrollType        | `'bonus'` \| `'correction'` | Optional pre-selected off-cycle reason. When provided, the creation form starts with this reason selected. |
+
+#### Events
+
+Events emitted during the creation phase:
+
+| Event type        | Description                                 | Data                    |
+| ----------------- | ------------------------------------------- | ----------------------- |
+| OFF_CYCLE_CREATED | Fired when the off-cycle payroll is created | { payrollUuid: string } |
+
+Additional events are available when using the standalone subcomponents — see [Sub-components](./sub-components).
+
+Once the payroll is created and the flow transitions to execution, all standard [run payroll events](../run-payroll/workflow#events) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
+
+---
+
+## Workflow steps
+
+1. **Creation**: User configures pay period dates, selects a reason (bonus or correction), chooses employees, and sets deduction/withholding preferences.
+2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
+
+---
+
+## Off-cycle reasons
+
+The creation form presents two reasons with different defaults:
+
+| Reason     | Description                                        | Default Deductions         | Default Withholding |
+| ---------- | -------------------------------------------------- | -------------------------- | ------------------- |
+| Bonus      | Pay a bonus, gift, or commission                   | Skip regular deductions    | Supplemental rate   |
+| Correction | Run a payroll outside of your regular pay schedule | Include regular deductions | Regular rate        |
+
+When the user changes the reason, deduction and withholding defaults update automatically.
+
+---
+
+## API reference
+
+The off-cycle payroll creation uses the [Create an off-cycle payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-v1-companies-company_id-payrolls). After creation, the standard payroll execution endpoints apply:
+
+- **Calculate payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate`
+- **Submit payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/submit`
+- **Cancel payroll**: `PUT /v1/companies/{company_id}/payrolls/{payroll_id}/cancel`
diff --git a/docs/workflows-overview/payroll.mdx b/docs/workflows-overview/payroll.mdx
new file mode 100644
index 000000000..292ff560a
--- /dev/null
+++ b/docs/workflows-overview/payroll.mdx
@@ -0,0 +1,31 @@
+---
+title: Payroll
+description: SDK surface for running payroll — regular, off-cycle, dismissal, and transition payrolls — and managing payroll history.
+order: 4
+---
+
+The Payroll surface covers every way a company runs payroll: the regular pay-schedule flow, off-cycle payrolls (bonus or correction), the dismissal payroll for terminated employees, and the transition payroll for pay-schedule changes. All payroll types share the same execution steps; they differ only in how the payroll is created.
+
+## Payroll processing
+
+The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.
+
+[Read more →](./run-payroll/run-payroll.mdx)
+
+## Off-cycle payroll
+
+Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.
+
+[Read more →](./off-cycle-payroll/off-cycle-payroll.mdx)
+
+## Dismissal payroll
+
+Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.
+
+[Read more →](./dismissal-payroll/dismissal-payroll.mdx)
+
+## Transition payroll
+
+Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.
+
+[Read more →](./transition-payroll/transition-payroll.mdx)
diff --git a/docs/workflows-overview/run-payroll/run-payroll.mdx b/docs/workflows-overview/run-payroll/run-payroll.mdx
new file mode 100644
index 000000000..73b0b3f2f
--- /dev/null
+++ b/docs/workflows-overview/run-payroll/run-payroll.mdx
@@ -0,0 +1,86 @@
+---
+title: Payroll processing
+description: End-to-end workflow for running payroll — select a payroll, configure employee compensation, review details, confirm wire transfers, and submit for processing.
+order: 1
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Payroll Processing workflow guides a company through running a regular payroll: selecting a payroll, configuring employee compensation, reviewing payroll details, confirming wire transfers, and submitting. The full experience can be dropped in as a single component, or assembled from individual sub-components for full control over the surrounding UI.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that renders the entire payroll processing experience end to end.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Landing',
+      description: 'Main landing page for payroll, with tabs for running payroll and viewing history.',
+      to: './sub-components#landing',
+    },
+    {
+      title: 'Payroll list',
+      description: 'List of available payrolls with status, blockers, and actions to run or skip.',
+      to: './sub-components#payroll-list',
+    },
+    {
+      title: 'History',
+      description: 'Historical payroll records with filtering, summary views, and cancellation when applicable.',
+      to: './sub-components#history',
+    },
+    {
+      title: 'Configuration',
+      description: 'Review and edit employee compensation before calculating the payroll.',
+      to: './sub-components#configuration',
+    },
+    {
+      title: 'Edit employee',
+      description: "Edit an individual employee's pay rate, hours, bonuses, and other compensation within a payroll.",
+      to: './sub-components#edit-employee',
+    },
+    {
+      title: 'Overview',
+      description: 'Final review and submission screen, with processing status and confirmation after submission.',
+      to: './sub-components#overview',
+    },
+    {
+      title: 'Execution flow',
+      description: 'Shared inner flow — configuration → overview → submission → receipt — reusable across all payroll types.',
+      to: './sub-components#execution-flow',
+    },
+    {
+      title: 'Receipts',
+      description: 'Detailed receipt for a completed payroll — payments, deductions, taxes, and totals.',
+      to: './sub-components#receipts',
+    },
+    {
+      title: 'Blockers',
+      description: 'List of blockers preventing payroll from being processed and information for resolving them.',
+      to: './sub-components#blockers',
+    },
+    {
+      title: 'Recovery cases',
+      description: 'Open recovery cases for a company with an in-modal resubmit workflow.',
+      to: './sub-components#recovery-cases',
+    },
+    {
+      title: 'Wire transfer confirmation',
+      description: 'Wire transfer confirmation workflow for payroll funding, including instructions and confirmation modal.',
+      to: './sub-components#wire-transfer-confirmation',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/run-payroll.md b/docs/workflows-overview/run-payroll/sub-components.md
similarity index 73%
rename from docs/workflows-overview/run-payroll.md
rename to docs/workflows-overview/run-payroll/sub-components.md
index e320c001e..d38cbce3c 100644
--- a/docs/workflows-overview/run-payroll.md
+++ b/docs/workflows-overview/run-payroll/sub-components.md
@@ -1,77 +1,16 @@
 ---
-title: Payroll Processing
-description: End-to-end workflow for running payroll — select a payroll, configure employee compensation, review details, confirm wire transfers, and submit for processing.
-order: 3
+title: Sub-components
+description: Standalone sub-components for payroll processing — render in isolation or compose into a custom workflow.
+order: 2
 ---
 
-The Run Payroll workflow provides a complete experience for running payroll for a company. It guides users through selecting a payroll, configuring employee compensation, reviewing payroll details, and submitting the payroll for processing.
+# Payroll Processing sub-components
 
-### Implementation
+Run payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
 
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyApp() {
-  return <Payroll.PayrollFlow companyId="your-company-id" onEvent={() => {}} />
-}
-```
-
-#### Props
-
-| Name                        | Type                                     | Description                                                                                                                             |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required          | string                                   | The associated company identifier.                                                                                                      |
-| onEvent Required            | function                                 | See events table for each subcomponent to see available events.                                                                         |
-| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                     |
-| defaultValues               | object                                   | Optional default values for the workflow.                                                                                               |
-| dictionary                  | object                                   | Optional translations for component text.                                                                                               |
-| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
-
-#### ConfirmWireDetailsProps
-
-| Prop      | Type                                   | Required | Description                                                                                                          |
-| --------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
-| companyId | string                                 | Yes      | The company identifier for fetching wire transfer information.                                                       |
-| wireInId  | string                                 | No       | Specific wire-in request identifier. If not provided, your component should handle the first active wire-in request. |
-| onEvent   | (type: string, data?: unknown) => void | No       | Optional callback to emit events back to the parent flow.                                                            |
-
-#### Events
+---
 
-| Event type                     | Description                                               | Data                                                                                                                                                                                     |
-| ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| RUN_PAYROLL_SELECTED           | Fired when user selects a payroll to run                  | { payrollId: string }                                                                                                                                                                    |
-| RUN_PAYROLL_BACK               | Fired when user navigates back from payroll configuration | None                                                                                                                                                                                     |
-| RUN_PAYROLL_CALCULATED         | Fired when payroll calculations are completed             | None                                                                                                                                                                                     |
-| RUN_PAYROLL_EDIT               | Fired when user makes changes to payroll configuration    | None                                                                                                                                                                                     |
-| RUN_PAYROLL_EMPLOYEE_EDITED    | Fired when user selects an employee to edit               | { employeeId: string }                                                                                                                                                                   |
-| RUN_PAYROLL_EMPLOYEE_SAVED     | Fired when employee payroll changes are saved             | { payrollPrepared: object, employee: object }                                                                                                                                            |
-| RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels employee payroll editing          | None                                                                                                                                                                                     |
-| RUN_PAYROLL_SUBMITTED          | Fired when payroll is successfully submitted              | [Response from the Submit payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-submit)                                    |
-| RUN_PAYROLL_PROCESSED          | Fired when payroll processing is completed                | None                                                                                                                                                                                     |
-| RUN_PAYROLL_PROCESSING_FAILED  | Fired when payroll processing fails                       | Error details                                                                                                                                                                            |
-| RUN_PAYROLL_CANCELLED          | Fired when a payroll is cancelled                         | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
-| RUN_PAYROLL_SUMMARY_VIEWED     | Fired when user views payroll summary                     | { payrollId: string }                                                                                                                                                                    |
-| RUN_PAYROLL_RECEIPT_VIEWED     | Fired when user views payroll receipt                     | { payrollId: string }                                                                                                                                                                    |
-
-## Using Payroll Subcomponents
-
-Run payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.PayrollLanding](#payrollpayrolllanding)
-- [Payroll.PayrollList](#payrollpayrolllist)
-- [Payroll.PayrollHistory](#payrollpayrollhistory)
-- [Payroll.PayrollConfiguration](#payrollpayrollconfiguration)
-- [Payroll.PayrollEditEmployee](#payrollpayrolleditemployee)
-- [Payroll.PayrollOverview](#payrollpayrolloverview)
-- [Payroll.PayrollExecutionFlow](#payrollpayrollexecutionflow)
-- [Payroll.PayrollReceipts](#payrollpayrollreceipts)
-- [Payroll.PayrollBlockerList](#payrollpayrollblockerlist)
-- [Payroll.RecoveryCases](#payrollrecoverycases)
-- [Payroll.ConfirmWireDetails](#payrollconfirmwiredetails)
-
-### Payroll.PayrollLanding
+## Landing
 
 Provides the main landing page for payroll operations, including tabs for running payroll and viewing payroll history.
 
@@ -85,13 +24,13 @@ function MyComponent() {
 
 #### Props
 
-| Name                        | Type                                     | Description                                                                                                                             |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required          | string                                   | The associated company identifier.                                                                                                      |
-| onEvent Required            | function                                 | See events table for available events.                                                                                                  |
-| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                     |
-| dictionary                  | object                                   | Optional translations for component text.                                                                                               |
-| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+| Name                        | Type                                     | Description                                                                                                                              |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required          | string                                   | The associated company identifier.                                                                                                       |
+| onEvent Required            | function                                 | See events table for available events.                                                                                                   |
+| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                      |
+| dictionary                  | object                                   | Optional translations for component text.                                                                                                |
+| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops). |
 
 #### Events
 
@@ -100,7 +39,9 @@ function MyComponent() {
 | RUN_PAYROLL_SUMMARY_VIEWED | Fired when user views payroll summary | { payrollId: string } |
 | RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string } |
 
-### Payroll.PayrollList
+---
+
+## Payroll list
 
 Displays a list of available payrolls that can be run, including pay period dates and status information. Users can run payrolls, submit calculated payrolls, skip payrolls, and view any payroll blockers.
 
@@ -131,7 +72,9 @@ function MyComponent() {
 | PAYROLL_SKIPPED               | Fired when a payroll is successfully skipped | { payrollId: string } |
 | RUN_PAYROLL_BLOCKERS_VIEW_ALL | Fired when user views all payroll blockers   | None                  |
 
-### Payroll.PayrollHistory
+---
+
+## History
 
 Displays historical payroll records with advanced filtering and management capabilities:
 
@@ -164,7 +107,9 @@ function MyComponent() {
 | RUN_PAYROLL_RECEIPT_VIEWED | Fired when user views payroll receipt | { payrollId: string }                                                                                                                                                                    |
 | RUN_PAYROLL_CANCELLED      | Fired when a payroll is cancelled     | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
 
-### Payroll.PayrollConfiguration
+---
+
+## Configuration
 
 Handles the configuration phase of payroll processing, allowing users to review and modify employee compensation before calculating the payroll.
 
@@ -205,7 +150,9 @@ function MyComponent() {
 | RUN_PAYROLL_PROCESSING_FAILED | Fired when payroll processing fails           | Error details                        |
 | RUN_PAYROLL_BLOCKERS_VIEW_ALL | Fired when user views all payroll blockers    | None                                 |
 
-### Payroll.PayrollEditEmployee
+---
+
+## Edit employee
 
 Used for editing individual employee compensation details within a payroll. This component allows modification of employee pay rates, hours, bonuses, and other compensation elements.
 
@@ -242,7 +189,9 @@ function MyComponent() {
 | RUN_PAYROLL_EMPLOYEE_SAVED     | Fired when employee payroll compensation changes are saved    | { payrollPrepared: [Response from the Update payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls), employee: object } |
 | RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels editing employee payroll compensation | None                                                                                                                                                                       |
 
-### Payroll.PayrollOverview
+---
+
+## Overview
 
 Displays the final payroll overview before submission, including totals, employee details, and submission controls. Once submitted, it tracks the processing status and displays confirmation when complete.
 
@@ -262,16 +211,16 @@ function MyComponent() {
 
 #### Props
 
-| Name                        | Type                                     | Description                                                                                                                             |
-| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| companyId Required          | string                                   | The associated company identifier.                                                                                                      |
-| payrollId Required          | string                                   | The associated payroll identifier.                                                                                                      |
-| onEvent Required            | function                                 | See events table for available events.                                                                                                  |
-| alerts                      | array                                    | Optional array of alert objects to display.                                                                                             |
-| showBackButton              | boolean                                  | Optional flag to show back button.                                                                                                      |
-| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                     |
-| dictionary                  | object                                   | Optional translations for component text.                                                                                               |
-| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+| Name                        | Type                                     | Description                                                                                                                              |
+| --------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required          | string                                   | The associated company identifier.                                                                                                       |
+| payrollId Required          | string                                   | The associated payroll identifier.                                                                                                       |
+| onEvent Required            | function                                 | See events table for available events.                                                                                                   |
+| alerts                      | array                                    | Optional array of alert objects to display.                                                                                              |
+| showBackButton              | boolean                                  | Optional flag to show back button.                                                                                                       |
+| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                      |
+| dictionary                  | object                                   | Optional translations for component text.                                                                                                |
+| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops). |
 
 #### Events
 
@@ -286,9 +235,11 @@ function MyComponent() {
 | RUN_PAYROLL_RECEIPT_GET        | Fired when user requests payroll receipt     | { payrollId: string }                                                                                                                                 |
 | RUN_PAYROLL_PDF_PAYSTUB_VIEWED | Fired when user views employee paystub PDF   | { employeeId: string }                                                                                                                                |
 
-### Payroll.PayrollExecutionFlow
+---
+
+## Execution flow
 
-The shared execution flow that runs the **configuration → overview → submission → receipt** steps for a single payroll. This is the inner flow that powers the back half of `Payroll.PayrollFlow`, and it is also reused by the [off-cycle](./off-cycle-payroll.md), [dismissal](./dismissal-payroll.md), and [transition](./transition-payroll.md) flows after they have created their respective payrolls.
+The shared execution flow that runs the **configuration → overview → submission → receipt** steps for a single payroll. This is the inner flow that powers the back half of `Payroll.PayrollFlow`, and it is also reused by the [off-cycle](../off-cycle-payroll/off-cycle-payroll.mdx), [dismissal](../dismissal-payroll/dismissal-payroll.mdx), and [transition](../transition-payroll/transition-payroll.mdx) flows after they have created their respective payrolls.
 
 Use this component directly when you have built your own payroll-creation step (e.g. a custom intake form) and want to hand the user off to the standard execution experience without re-implementing it. The flow ships with breadcrumb navigation, the standard wire-confirmation UX, and emits the same `RUN_PAYROLL_*` events as the full `PayrollFlow`.
 
@@ -317,14 +268,16 @@ function MyComponent() {
 | initialState                | `'configuration'` \| `'overview'`        | `'configuration'` | Where the flow starts. Use `'overview'` when you want to drop the user directly on the review screen (e.g. resuming an already-calculated payroll).                                         |
 | isDismissalPayroll          | boolean                                  | `false`           | When true, surfaces dismissal-specific copy and breadcrumbs (used by `Payroll.DismissalFlow`).                                                                                              |
 | withReimbursements          | boolean                                  | `true`            | Optional flag to show/hide reimbursement fields throughout the flow.                                                                                                                        |
-| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` |                   | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops).                                                     |
+| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` |                   | Optional custom component to replace the default wire details confirmation UI. See [Workflow props](./workflow#confirmwiredetailsprops).                                                    |
 | prefixBreadcrumbs           | `FlowBreadcrumb[]`                       | `[]`              | Optional breadcrumbs prepended to the flow's own breadcrumb trail. Useful when embedding inside a parent flow (e.g. an off-cycle creation step) so the breadcrumb history remains coherent. |
 
 #### Events
 
-Emits the same events as `Payroll.PayrollFlow` during execution — see the [main events table](#events) at the top of this page (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_EMPLOYEE_EDIT`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`, `RUN_PAYROLL_RECEIPT_VIEWED`).
+Emits the same events as `Payroll.PayrollFlow` during execution — see the [main events table](./workflow#events) on the workflow page (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_EMPLOYEE_EDIT`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`, `RUN_PAYROLL_RECEIPT_VIEWED`).
 
-### Payroll.PayrollReceipts
+---
+
+## Receipts
 
 Displays a detailed receipt for a completed payroll, including all payment information, deductions, taxes, and totals. This component provides a comprehensive view of a processed payroll for record-keeping and review purposes.
 
@@ -352,7 +305,9 @@ function MyComponent() {
 | ---------------- | ------------------------------ | ---- |
 | RUN_PAYROLL_BACK | Fired when user navigates back | None |
 
-### Payroll.PayrollBlockerList
+---
+
+## Blockers
 
 Displays a list of blockers that prevent payroll from being processed. Blockers indicate issues that must be resolved before a payroll can be calculated or submitted, such as missing employee information, invalid tax setups, or incomplete company configuration.
 
@@ -376,7 +331,9 @@ function MyComponent() {
 
 This component does not emit any events. It displays blockers fetched from the API and provides information to help users resolve issues.
 
-### Payroll.RecoveryCases
+---
+
+## Recovery cases
 
 Displays open recovery cases for a company and provides an in-modal resubmit workflow for resolving them. Recovery cases are issues that arise after a payroll has been submitted (for example, a returned ACH transfer) and must be resolved before subsequent payrolls can run cleanly. The component is also embedded inside `Payroll.PayrollBlockerList`, but can be used standalone when you want a dedicated recovery cases surface.
 
@@ -403,7 +360,9 @@ function MyComponent() {
 | RECOVERY_CASE_RESUBMIT_DONE   | Fired when the user successfully resubmits a recovery case       | Resubmit result payload    |
 | RECOVERY_CASE_RESUBMIT_CANCEL | Fired when the user cancels the resubmit modal                   | None                       |
 
-### Payroll.ConfirmWireDetails
+---
+
+## Wire transfer confirmation
 
 Provides the wire transfer confirmation workflow for payroll funding. This component displays a banner when wire transfers are awaiting funds and allows users to view wire instructions and confirm transfer details through a modal interface.
 
diff --git a/docs/workflows-overview/run-payroll/workflow.md b/docs/workflows-overview/run-payroll/workflow.md
new file mode 100644
index 000000000..bc620aa56
--- /dev/null
+++ b/docs/workflows-overview/run-payroll/workflow.md
@@ -0,0 +1,58 @@
+---
+title: Workflow
+description: Drop-in Payroll.PayrollFlow component that renders the entire payroll processing experience.
+order: 1
+---
+
+# Payroll Processing workflow
+
+The Payroll Processing workflow renders the full regular-payroll experience as a single component. Drop it into your app and the user walks through selecting a payroll, configuring employee compensation, reviewing details, confirming wire transfers, and submitting.
+
+---
+
+## Implementation
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyApp() {
+  return <Payroll.PayrollFlow companyId="your-company-id" onEvent={() => {}} />
+}
+```
+
+#### Props
+
+| Name                        | Type                                     | Description                                                                                                                             |
+| --------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| companyId Required          | string                                   | The associated company identifier.                                                                                                      |
+| onEvent Required            | function                                 | See events table for each subcomponent to see available events.                                                                         |
+| withReimbursements          | boolean                                  | Optional flag to show/hide reimbursements fields. Defaults to true.                                                                     |
+| defaultValues               | object                                   | Optional default values for the workflow.                                                                                               |
+| dictionary                  | object                                   | Optional translations for component text.                                                                                               |
+| ConfirmWireDetailsComponent | `ComponentType<ConfirmWireDetailsProps>` | Optional custom component to replace the default wire details confirmation UI. See [ConfirmWireDetailsProps](#confirmwiredetailsprops). |
+
+#### ConfirmWireDetailsProps
+
+| Prop      | Type                                   | Required | Description                                                                                                          |
+| --------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| companyId | string                                 | Yes      | The company identifier for fetching wire transfer information.                                                       |
+| wireInId  | string                                 | No       | Specific wire-in request identifier. If not provided, your component should handle the first active wire-in request. |
+| onEvent   | (type: string, data?: unknown) => void | No       | Optional callback to emit events back to the parent flow.                                                            |
+
+#### Events
+
+| Event type                     | Description                                               | Data                                                                                                                                                                                     |
+| ------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RUN_PAYROLL_SELECTED           | Fired when user selects a payroll to run                  | { payrollId: string }                                                                                                                                                                    |
+| RUN_PAYROLL_BACK               | Fired when user navigates back from payroll configuration | None                                                                                                                                                                                     |
+| RUN_PAYROLL_CALCULATED         | Fired when payroll calculations are completed             | None                                                                                                                                                                                     |
+| RUN_PAYROLL_EDIT               | Fired when user makes changes to payroll configuration    | None                                                                                                                                                                                     |
+| RUN_PAYROLL_EMPLOYEE_EDITED    | Fired when user selects an employee to edit               | { employeeId: string }                                                                                                                                                                   |
+| RUN_PAYROLL_EMPLOYEE_SAVED     | Fired when employee payroll changes are saved             | { payrollPrepared: object, employee: object }                                                                                                                                            |
+| RUN_PAYROLL_EMPLOYEE_CANCELLED | Fired when user cancels employee payroll editing          | None                                                                                                                                                                                     |
+| RUN_PAYROLL_SUBMITTED          | Fired when payroll is successfully submitted              | [Response from the Submit payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-submit)                                    |
+| RUN_PAYROLL_PROCESSED          | Fired when payroll processing is completed                | None                                                                                                                                                                                     |
+| RUN_PAYROLL_PROCESSING_FAILED  | Fired when payroll processing fails                       | Error details                                                                                                                                                                            |
+| RUN_PAYROLL_CANCELLED          | Fired when a payroll is cancelled                         | { payrollId: string, result: [Response from the Cancel payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/put-api-v1-companies-company_id-payrolls-payroll_id-cancel) } |
+| RUN_PAYROLL_SUMMARY_VIEWED     | Fired when user views payroll summary                     | { payrollId: string }                                                                                                                                                                    |
+| RUN_PAYROLL_RECEIPT_VIEWED     | Fired when user views payroll receipt                     | { payrollId: string }                                                                                                                                                                    |
diff --git a/docs/workflows-overview/transition-payroll/sub-components.md b/docs/workflows-overview/transition-payroll/sub-components.md
new file mode 100644
index 000000000..d0a5e5310
--- /dev/null
+++ b/docs/workflows-overview/transition-payroll/sub-components.md
@@ -0,0 +1,58 @@
+---
+title: Sub-components
+description: Standalone sub-components for transition payroll — render in isolation or compose into a custom workflow.
+order: 2
+---
+
+# Transition Payroll sub-components
+
+Transition payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../../integration-guide/composition.md).
+
+After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](../run-payroll/sub-components#execution-flow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
+
+---
+
+## Transition creation
+
+The creation form for transition payrolls. Displays the transition pay period and pay schedule information, and allows configuration of check date, deductions, and tax withholding.
+
+```jsx
+import { Payroll } from '@gusto/embedded-react-sdk'
+
+function MyComponent() {
+  return (
+    <Payroll.TransitionCreation
+      companyId="your-company-id"
+      startDate="2025-01-16"
+      endDate="2025-01-31"
+      payScheduleUuid="pay-schedule-uuid"
+      onEvent={() => {}}
+    />
+  )
+}
+```
+
+#### Props
+
+| Name                     | Type     | Description                                  |
+| ------------------------ | -------- | -------------------------------------------- |
+| companyId Required       | string   | The associated company identifier.           |
+| startDate Required       | string   | The start date of the transition pay period. |
+| endDate Required         | string   | The end date of the transition pay period.   |
+| payScheduleUuid Required | string   | The UUID of the associated pay schedule.     |
+| onEvent Required         | function | See events table for available events.       |
+| dictionary               | object   | Optional translations for component text.    |
+
+#### Events
+
+| Event type         | Description                                  | Data                    |
+| ------------------ | -------------------------------------------- | ----------------------- |
+| TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
+
+#### Form fields
+
+- **Pay period** (read-only): Displays the transition pay period start and end dates
+- **Pay schedule** (read-only): Shows the name of the associated pay schedule, when available
+- **Check date**: The date employees will be paid (must be at least 2 business days from today for ACH processing)
+- **Deductions and contributions**: Include or skip regular deductions. Defaults to including deductions.
+- **Tax withholding rates**: Configure withholding pay period frequency and rate type (regular or supplemental). Defaults to regular rate with every-other-week frequency.
diff --git a/docs/workflows-overview/transition-payroll/transition-payroll.mdx b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
new file mode 100644
index 000000000..ad850aa75
--- /dev/null
+++ b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
@@ -0,0 +1,36 @@
+---
+title: Transition payroll
+description: Workflow for running payrolls that cover gaps between old and new pay schedules, plus the alert surfaced inside the payroll landing for unprocessed transition periods.
+order: 4
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The Transition Payroll workflow handles payrolls that cover gaps between old and new pay schedules. When a company changes its pay schedule, there may be workdays that fall between the end of the old schedule and the start of the new one — transition payrolls ensure employees are paid for those days. The SDK provides a flow component for running a specific transition payroll and an integrated alert (rendered inside `Payroll.PayrollLanding`) that surfaces unprocessed transition periods.
+
+## Workflow
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Workflow',
+      description:
+        'A single drop-in component that creates the transition payroll and hands off to the standard execution flow.',
+      to: './workflow',
+    },
+  ]}
+/>
+
+## Sub-components
+
+<LinkCardGrid
+  columns={1}
+  items={[
+    {
+      title: 'Transition creation',
+      description: 'Creation form for a transition payroll — pay period, check date, deductions, and tax withholding.',
+      to: './sub-components#transition-creation',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/transition-payroll.md b/docs/workflows-overview/transition-payroll/workflow.md
similarity index 54%
rename from docs/workflows-overview/transition-payroll.md
rename to docs/workflows-overview/transition-payroll/workflow.md
index 0199ac0aa..8e007a3b5 100644
--- a/docs/workflows-overview/transition-payroll.md
+++ b/docs/workflows-overview/transition-payroll/workflow.md
@@ -1,17 +1,18 @@
 ---
-title: Transition Payroll
-description: Workflow for running payrolls that cover gaps between old and new pay schedules, including an alert surfaced in PayrollLanding for unprocessed transition periods.
-order: 7
+title: Workflow
+description: Drop-in Payroll.TransitionFlow component that creates a transition payroll and hands off to the standard execution flow.
+order: 1
 ---
 
-The Transition Payroll workflow handles payrolls that cover gaps between old and new pay schedules. When a company changes its pay schedule, there may be workdays that fall between the end of the old schedule and the start of the new one. Transition payrolls ensure employees are paid for those days.
+# Transition Payroll workflow
 
-The SDK provides a flow component and an integrated alert for transition payrolls:
+The Transition Payroll workflow renders the full experience — creation, then standard payroll execution — for a transition payroll covering the gap between an old and new pay schedule.
 
-- **`Payroll.TransitionFlow`**: A full creation-to-execution flow for running a specific transition payroll. After creation, the flow transitions into the standard [Payroll Processing](./run-payroll.md) execution experience — the same steps used by regular and other off-cycle payrolls.
-- **Transition Payroll Alert**: An alert automatically rendered within `Payroll.PayrollLanding` when there are unprocessed transition pay periods. It surfaces upcoming transition periods and allows users to run or skip them. This is not a standalone export — it is built into the landing page.
+After creation, the flow transitions into the standard [Payroll Processing](../run-payroll/run-payroll.mdx) execution experience — the same steps used by regular and other off-cycle payrolls.
 
-### Implementation
+---
+
+## Implementation
 
 ```jsx
 import { Payroll } from '@gusto/embedded-react-sdk'
@@ -47,84 +48,33 @@ Events emitted during the creation phase:
 | ------------------ | -------------------------------------------- | ----------------------- |
 | TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
 
-Once the payroll is created and the flow transitions to execution, all standard [run payroll events](./run-payroll.md) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
-
-## Workflow Steps
-
-1. **Creation**: Displays the transition details (pay period dates, pay schedule name) and allows the user to configure the check date, deduction preferences, and tax withholding rates
-2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts
-
-## Using Transition Subcomponents
-
-Transition payroll components can be used to compose your own workflow, or can be rendered in isolation. For guidance on creating a custom workflow, see [docs on composition](../integration-guide/composition.md).
-
-### Available Subcomponents
-
-- [Payroll.TransitionCreation](#payrolltransitioncreation)
-
-After creation, the flow hands off to the shared [`Payroll.PayrollExecutionFlow`](./run-payroll.md#payrollpayrollexecutionflow) for the configuration → overview → submission → receipts steps. If you build your own creation step in front of the standard execution UI, render `Payroll.PayrollExecutionFlow` directly with the payroll you created.
-
-### Payroll.TransitionCreation
-
-The creation form for transition payrolls. Displays the transition pay period and pay schedule information, and allows configuration of check date, deductions, and tax withholding.
-
-```jsx
-import { Payroll } from '@gusto/embedded-react-sdk'
-
-function MyComponent() {
-  return (
-    <Payroll.TransitionCreation
-      companyId="your-company-id"
-      startDate="2025-01-16"
-      endDate="2025-01-31"
-      payScheduleUuid="pay-schedule-uuid"
-      onEvent={() => {}}
-    />
-  )
-}
-```
-
-#### Props
+Once the payroll is created and the flow transitions to execution, all standard [run payroll events](../run-payroll/workflow#events) are emitted (e.g. `RUN_PAYROLL_CALCULATED`, `RUN_PAYROLL_SUBMITTED`, `RUN_PAYROLL_PROCESSED`).
 
-| Name                     | Type     | Description                                  |
-| ------------------------ | -------- | -------------------------------------------- |
-| companyId Required       | string   | The associated company identifier.           |
-| startDate Required       | string   | The start date of the transition pay period. |
-| endDate Required         | string   | The end date of the transition pay period.   |
-| payScheduleUuid Required | string   | The UUID of the associated pay schedule.     |
-| onEvent Required         | function | See events table for available events.       |
-| dictionary               | object   | Optional translations for component text.    |
-
-#### Events
+---
 
-| Event type         | Description                                  | Data                    |
-| ------------------ | -------------------------------------------- | ----------------------- |
-| TRANSITION_CREATED | Fired when the transition payroll is created | { payrollUuid: string } |
+## Workflow steps
 
-#### Form Fields
+1. **Creation**: Displays the transition details (pay period dates, pay schedule name) and allows the user to configure the check date, deduction preferences, and tax withholding rates.
+2. **Execution**: The standard payroll execution flow takes over — configure employee compensation, review, submit, and view receipts.
 
-- **Pay period** (read-only): Displays the transition pay period start and end dates
-- **Pay schedule** (read-only): Shows the name of the associated pay schedule, when available
-- **Check date**: The date employees will be paid (must be at least 2 business days from today for ACH processing)
-- **Deductions and contributions**: Include or skip regular deductions. Defaults to including deductions.
-- **Tax withholding rates**: Configure withholding pay period frequency and rate type (regular or supplemental). Defaults to regular rate with every-other-week frequency.
+---
 
-## Transition Payroll Alert
+## Transition payroll alert
 
-The transition payroll alert is automatically rendered within `Payroll.PayrollLanding` when there are unprocessed transition pay periods. It looks ahead 90 days for upcoming transition periods, groups them by pay schedule, and presents options to run or skip each one.
+The transition payroll alert is automatically rendered within [`Payroll.PayrollLanding`](../run-payroll/sub-components#landing) when there are unprocessed transition pay periods. It looks ahead 90 days for upcoming transition periods, groups them by pay schedule, and presents options to run or skip each one.
 
 The alert explains why transition payrolls are needed and warns that skipping means employees will not be paid for the transition period.
 
 > **Important**: Transition pay periods should be resolved (either run or skipped) before the company runs regular payrolls. The Gusto API may enforce this requirement by returning errors when attempting to process regular payrolls while unresolved transition periods exist.
 
-### Alert Events
+### Alert events
 
 | Event type                 | Description                                         | Data                                                                         |
 | -------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
 | RUN_TRANSITION_PAYROLL     | Fired when user chooses to run a transition payroll | { startDate: string, endDate: string, payScheduleUuid: string \| undefined } |
 | TRANSITION_PAYROLL_SKIPPED | Fired when a transition payroll is skipped          | { startDate: string, endDate: string, payScheduleUuid: string \| undefined } |
 
-### Handling the Run Transition Event
+### Handling the run transition event
 
 When the `RUN_TRANSITION_PAYROLL` event is emitted from the Payroll Landing page, your application should render the `Payroll.TransitionFlow` component with the provided dates and pay schedule UUID:
 
@@ -159,11 +109,15 @@ function PayrollPage({ companyId }) {
 
 > **Note**: The example guards on `data.payScheduleUuid` because `Payroll.TransitionFlow` requires it as a prop. In practice, `payScheduleUuid` is expected to be present for transition pay periods, but the event type allows `undefined`. If you need to handle the undefined case, add your own fallback logic (e.g. displaying an error or refetching pay schedule data).
 
-### Skipping a Transition Payroll
+---
+
+## Skipping a transition payroll
 
 Users can skip transition payrolls directly from the alert. A confirmation dialog warns that skipping means employees will not be paid for the transition period and that it is the employer's responsibility to ensure proper payment. Upon confirmation, the payroll is skipped via the [Skip a payroll endpoint](https://docs.gusto.com/embedded-payroll/reference/post-companies-payroll-skip-company_uuid).
 
-## API Reference
+---
+
+## API reference
 
 The transition payroll uses these API endpoints:
 
diff --git a/docs/workflows-overview/workflows-overview.md b/docs/workflows-overview/workflows-overview.md
deleted file mode 100644
index 9eee825d8..000000000
--- a/docs/workflows-overview/workflows-overview.md
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Workflows Overview
-description: Index of every pre-built workflow in the SDK — onboarding, payroll, contractors, time off, and more — each rendering a multi-step experience as one component.
-order: 4
----
-
-## Introduction to Workflows
-
-Workflows are pre-built UI experiences you can use to quickly and easily incorporate essential payroll functionality into your build, such as onboarding an employee or running payroll.
-
-### Available Workflows
-
-- Company Onboarding
-- Employee Onboarding
-- Employee Self Onboarding
-- Payroll Processing
-- Off-Cycle Payroll (Bonus & Correction)
-- Dismissal Payroll
-- Transition Payroll
-- Contractor Onboarding
-- Contractor Payments
-- Employee Termination
-- Time Off Policy Management
-- Information Requests
-
-### Why should I use a Workflow?
-
-Workflows are incredibly simple to add to your application. A single React component placed in your app can encapsulate an entire complex multi step user experience.
-
-### How to use Workflows
-
-In this example we incorporate the entire employee onboarding flow in our application. This component represents multiple steps including inputting profile details, taxes, and payment info. It can be implemented as follows:
-
-```jsx
-import { EmployeeOnboarding, GustoProvider } from '@gusto/embedded-react-sdk'
-
-function MyApp({ companyId }) {
-  return (
-    <GustoProvider
-      config={{
-        baseUrl: `/myapp/`,
-      }}
-    >
-      <EmployeeOnboarding.OnboardingFlow companyId={companyId} onEvent={() => {...}} />
-    </GustoProvider>
-  )
-}
-```
-
-This example renders a fully functional flow with the following steps:
-
-![](https://files.readme.io/ef7be0a7bb31a99a6b2ac03f1fcb8fe85d6e0301b90aa8ced632e465d0b3dc99-image.png)
-
-As can be seen, using workflow components can allow for implementing complex flows in a simple way.
-
-The following documents in this section will provide more detailed usage examples and implementation guidelines for each flow.
diff --git a/docs/workflows-overview/workflows-overview.mdx b/docs/workflows-overview/workflows-overview.mdx
new file mode 100644
index 000000000..7f8fb3eaa
--- /dev/null
+++ b/docs/workflows-overview/workflows-overview.mdx
@@ -0,0 +1,11 @@
+---
+title: Surfaces
+description: Pre-built React experiences covering company, employee, contractor, and payroll workflows.
+order: 4
+---
+
+import SurfacesGrid from '@site/src/components/SurfacesGrid'
+
+The SDK ships pre-built surfaces for the four core areas of running payroll: companies, employees, contractors, and payroll itself. Each surface is a single React component that drops a full multi-step experience into your app.
+
+<SurfacesGrid />

From 51c4a0a7413bb98660df794f0eefae27ab73f309 Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Thu, 11 Jun 2026 17:39:24 -0400
Subject: [PATCH 02/10] style(docs): apply prettier formatting to surface
 landing mdx files

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../company-onboarding/company-onboarding.mdx |  3 ++-
 .../contractor-onboarding.mdx                 |  9 ++++---
 .../contractor-payments.mdx                   | 15 ++++++++----
 .../dismissal-payroll/dismissal-payroll.mdx   |  2 +-
 .../employee-self-onboarding.mdx              |  9 ++++---
 .../information-requests.mdx                  |  6 +++--
 .../off-cycle-payroll/off-cycle-payroll.mdx   |  6 +++--
 .../run-payroll/run-payroll.mdx               | 24 ++++++++++++-------
 .../transition-payroll/transition-payroll.mdx |  3 ++-
 9 files changed, 51 insertions(+), 26 deletions(-)

diff --git a/docs/workflows-overview/company-onboarding/company-onboarding.mdx b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
index d9e781c28..9cac27107 100644
--- a/docs/workflows-overview/company-onboarding/company-onboarding.mdx
+++ b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
@@ -29,7 +29,8 @@ Company Onboarding walks a company through everything required before they can r
   items={[
     {
       title: 'Assign a signatory',
-      description: 'Choose between creating a new signatory or inviting someone to become the signatory.',
+      description:
+        'Choose between creating a new signatory or inviting someone to become the signatory.',
       to: './sub-components#assign-a-signatory',
     },
     {
diff --git a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
index 6a1c39a09..fe386d173 100644
--- a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
+++ b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
@@ -29,12 +29,14 @@ The Contractor Onboarding workflow collects everything required to set a contrac
   items={[
     {
       title: 'Contractors list',
-      description: 'List of contractors for a company with actions to add, edit, delete, and continue onboarding.',
+      description:
+        'List of contractors for a company with actions to add, edit, delete, and continue onboarding.',
       to: './sub-components#contractors-list',
     },
     {
       title: 'Profile',
-      description: 'Form for creating and editing a contractor profile — individual or business, with self-onboarding option.',
+      description:
+        'Form for creating and editing a contractor profile — individual or business, with self-onboarding option.',
       to: './sub-components#profile',
     },
     {
@@ -54,7 +56,8 @@ The Contractor Onboarding workflow collects everything required to set a contrac
     },
     {
       title: 'Submit contractor',
-      description: 'Finalize contractor onboarding — update status and optionally invite the contractor for self-onboarding.',
+      description:
+        'Finalize contractor onboarding — update status and optionally invite the contractor for self-onboarding.',
       to: './sub-components#submit-contractor',
     },
   ]}
diff --git a/docs/workflows-overview/contractor-payments/contractor-payments.mdx b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
index 4d509257a..574dbcb85 100644
--- a/docs/workflows-overview/contractor-payments/contractor-payments.mdx
+++ b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
@@ -29,27 +29,32 @@ The Contractor Payments workflow lets a company create, manage, and view contrac
   items={[
     {
       title: 'Payments list',
-      description: 'List of contractor payment groups, with the ability to create new payments and filter by date range.',
+      description:
+        'List of contractor payment groups, with the ability to create new payments and filter by date range.',
       to: './sub-components#payments-list',
     },
     {
       title: 'Create payment',
-      description: 'Form for creating a contractor payment group — payment date, individual contractor edits, preview, and submission blockers.',
+      description:
+        'Form for creating a contractor payment group — payment date, individual contractor edits, preview, and submission blockers.',
       to: './sub-components#create-payment',
     },
     {
       title: 'Payment history',
-      description: 'Detailed view of a payment group and its individual contractor payments, with cancellation when permitted.',
+      description:
+        'Detailed view of a payment group and its individual contractor payments, with cancellation when permitted.',
       to: './sub-components#payment-history',
     },
     {
       title: 'Payment summary',
-      description: 'Confirmation screen after payment creation — totals, debit details, and wire transfer instructions when applicable.',
+      description:
+        'Confirmation screen after payment creation — totals, debit details, and wire transfer instructions when applicable.',
       to: './sub-components#payment-summary',
     },
     {
       title: 'Payment statement',
-      description: 'Individual contractor payment statement with detailed payment information and breakdown.',
+      description:
+        'Individual contractor payment statement with detailed payment information and breakdown.',
       to: './sub-components#payment-statement',
     },
   ]}
diff --git a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
index 86a32656c..ccf593022 100644
--- a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
+++ b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
@@ -30,7 +30,7 @@ The Dismissal Payroll workflow provides a guided experience for running a termin
     {
       title: 'Sub-components',
       description:
-        "Dismissal payroll is delivered as a single orchestrated flow. After creation, it reuses the standard payroll processing sub-components for configuration, overview, submission, and receipts.",
+        'Dismissal payroll is delivered as a single orchestrated flow. After creation, it reuses the standard payroll processing sub-components for configuration, overview, submission, and receipts.',
       to: './sub-components',
     },
   ]}
diff --git a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
index 257899c7d..68e11c1ef 100644
--- a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
+++ b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
@@ -29,12 +29,14 @@ When an admin opts an employee into self-onboarding, the employee completes thei
   items={[
     {
       title: 'Welcome screen',
-      description: 'Guidance for the employee on what to expect from self-onboarding and what to have on hand.',
+      description:
+        'Guidance for the employee on what to expect from self-onboarding and what to have on hand.',
       to: './sub-components#welcome-screen',
     },
     {
       title: 'Profile',
-      description: "Collect the employee's basic info — name, email, SSN, date of birth, home address.",
+      description:
+        "Collect the employee's basic info — name, email, SSN, date of birth, home address.",
       to: './sub-components#profile',
     },
     {
@@ -59,7 +61,8 @@ When an admin opts an employee into self-onboarding, the employee completes thei
     },
     {
       title: 'Employment eligibility',
-      description: "Collect the employee's I-9 employment eligibility details — citizenship status and supporting documents.",
+      description:
+        "Collect the employee's I-9 employment eligibility details — citizenship status and supporting documents.",
       to: './sub-components#employment-eligibility',
     },
     {
diff --git a/docs/workflows-overview/information-requests/information-requests.mdx b/docs/workflows-overview/information-requests/information-requests.mdx
index 11897a3e9..15bcea801 100644
--- a/docs/workflows-overview/information-requests/information-requests.mdx
+++ b/docs/workflows-overview/information-requests/information-requests.mdx
@@ -29,12 +29,14 @@ The Information Requests surface lets a company view and respond to outstanding
   items={[
     {
       title: 'Information requests list',
-      description: 'List of information requests for a company with status badges and a "Respond" CTA.',
+      description:
+        'List of information requests for a company with status badges and a "Respond" CTA.',
       to: './sub-components#information-requests-list',
     },
     {
       title: 'Information request form',
-      description: 'Dynamic response form for a single information request, rendered from the required questions.',
+      description:
+        'Dynamic response form for a single information request, rendered from the required questions.',
       to: './sub-components#information-request-form',
     },
   ]}
diff --git a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
index 0c33e84b1..8349f1928 100644
--- a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
+++ b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
@@ -29,7 +29,8 @@ The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay
   items={[
     {
       title: 'Off-cycle creation',
-      description: 'Main creation form — reason, pay period dates, employee selection, deductions, and tax withholding.',
+      description:
+        'Main creation form — reason, pay period dates, employee selection, deductions, and tax withholding.',
       to: './sub-components#off-cycle-creation',
     },
     {
@@ -39,7 +40,8 @@ The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay
     },
     {
       title: 'Deductions setting',
-      description: 'Choose whether to include or skip regular deductions for the off-cycle payroll.',
+      description:
+        'Choose whether to include or skip regular deductions for the off-cycle payroll.',
       to: './sub-components#deductions-setting',
     },
   ]}
diff --git a/docs/workflows-overview/run-payroll/run-payroll.mdx b/docs/workflows-overview/run-payroll/run-payroll.mdx
index 73b0b3f2f..d26c3a310 100644
--- a/docs/workflows-overview/run-payroll/run-payroll.mdx
+++ b/docs/workflows-overview/run-payroll/run-payroll.mdx
@@ -29,7 +29,8 @@ The Payroll Processing workflow guides a company through running a regular payro
   items={[
     {
       title: 'Landing',
-      description: 'Main landing page for payroll, with tabs for running payroll and viewing history.',
+      description:
+        'Main landing page for payroll, with tabs for running payroll and viewing history.',
       to: './sub-components#landing',
     },
     {
@@ -39,7 +40,8 @@ The Payroll Processing workflow guides a company through running a regular payro
     },
     {
       title: 'History',
-      description: 'Historical payroll records with filtering, summary views, and cancellation when applicable.',
+      description:
+        'Historical payroll records with filtering, summary views, and cancellation when applicable.',
       to: './sub-components#history',
     },
     {
@@ -49,27 +51,32 @@ The Payroll Processing workflow guides a company through running a regular payro
     },
     {
       title: 'Edit employee',
-      description: "Edit an individual employee's pay rate, hours, bonuses, and other compensation within a payroll.",
+      description:
+        "Edit an individual employee's pay rate, hours, bonuses, and other compensation within a payroll.",
       to: './sub-components#edit-employee',
     },
     {
       title: 'Overview',
-      description: 'Final review and submission screen, with processing status and confirmation after submission.',
+      description:
+        'Final review and submission screen, with processing status and confirmation after submission.',
       to: './sub-components#overview',
     },
     {
       title: 'Execution flow',
-      description: 'Shared inner flow — configuration → overview → submission → receipt — reusable across all payroll types.',
+      description:
+        'Shared inner flow — configuration → overview → submission → receipt — reusable across all payroll types.',
       to: './sub-components#execution-flow',
     },
     {
       title: 'Receipts',
-      description: 'Detailed receipt for a completed payroll — payments, deductions, taxes, and totals.',
+      description:
+        'Detailed receipt for a completed payroll — payments, deductions, taxes, and totals.',
       to: './sub-components#receipts',
     },
     {
       title: 'Blockers',
-      description: 'List of blockers preventing payroll from being processed and information for resolving them.',
+      description:
+        'List of blockers preventing payroll from being processed and information for resolving them.',
       to: './sub-components#blockers',
     },
     {
@@ -79,7 +86,8 @@ The Payroll Processing workflow guides a company through running a regular payro
     },
     {
       title: 'Wire transfer confirmation',
-      description: 'Wire transfer confirmation workflow for payroll funding, including instructions and confirmation modal.',
+      description:
+        'Wire transfer confirmation workflow for payroll funding, including instructions and confirmation modal.',
       to: './sub-components#wire-transfer-confirmation',
     },
   ]}
diff --git a/docs/workflows-overview/transition-payroll/transition-payroll.mdx b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
index ad850aa75..452bf183b 100644
--- a/docs/workflows-overview/transition-payroll/transition-payroll.mdx
+++ b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
@@ -29,7 +29,8 @@ The Transition Payroll workflow handles payrolls that cover gaps between old and
   items={[
     {
       title: 'Transition creation',
-      description: 'Creation form for a transition payroll — pay period, check date, deductions, and tax withholding.',
+      description:
+        'Creation form for a transition payroll — pay period, check date, deductions, and tax withholding.',
       to: './sub-components#transition-creation',
     },
   ]}

From 7cd0c3411ec28ad8a6a650aad7cbbbde74c8ea1f Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Thu, 11 Jun 2026 18:04:43 -0400
Subject: [PATCH 03/10] fix(docs-site): prepend /docs/ routeBasePath to
 SurfacesGrid card links

Card links were missing the docs plugin's routeBasePath, so each Surfaces
homepage card resolved to a non-existent URL.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs-site/src/components/SurfacesGrid/index.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs-site/src/components/SurfacesGrid/index.tsx b/docs-site/src/components/SurfacesGrid/index.tsx
index cc13d8392..fb921415a 100644
--- a/docs-site/src/components/SurfacesGrid/index.tsx
+++ b/docs-site/src/components/SurfacesGrid/index.tsx
@@ -12,22 +12,22 @@ const surfaces: Surface[] = [
   {
     title: 'Companies',
     description: 'Stand up a new company and request the information needed to run payroll.',
-    to: '/workflows-overview/companies',
+    to: '/docs/workflows-overview/companies',
   },
   {
     title: 'Employees',
     description: 'Onboard employees, manage their details, and handle terminations.',
-    to: '/workflows-overview/employees',
+    to: '/docs/workflows-overview/employees',
   },
   {
     title: 'Contractors',
     description: 'Onboard contractors and pay them on or off cycle.',
-    to: '/workflows-overview/contractors',
+    to: '/docs/workflows-overview/contractors',
   },
   {
     title: 'Payroll',
     description: 'Run regular, off-cycle, dismissal, and transition payrolls.',
-    to: '/workflows-overview/payroll',
+    to: '/docs/workflows-overview/payroll',
   },
 ]
 

From 3b41b525c96b4fc63f02865bdc709e87054e01ea Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 14:51:43 -0400
Subject: [PATCH 04/10] docs: unify landing pages with LinkCardGrid

Convert workflow-overview landing pages (employees, companies, contractors,
payroll) to use LinkCardGrid for consistent card UI. Switch single-item grids
to columns={2} so cards keep half-width instead of stretching. Remove empty
sub-components section from dismissal payroll landing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/workflows-overview/companies.mdx         | 30 +++++++----
 .../company-onboarding/company-onboarding.mdx |  2 +-
 .../contractor-onboarding.mdx                 |  2 +-
 .../contractor-payments.mdx                   |  2 +-
 docs/workflows-overview/contractors.mdx       | 30 +++++++----
 .../dismissal-payroll/dismissal-payroll.mdx   | 16 +-----
 .../employee-onboarding.mdx                   |  4 +-
 .../employee-self-onboarding.mdx              |  2 +-
 docs/workflows-overview/employees.mdx         | 30 +++++++----
 .../information-requests.mdx                  |  2 +-
 .../off-cycle-payroll/off-cycle-payroll.mdx   |  2 +-
 docs/workflows-overview/payroll.mdx           | 54 +++++++++++--------
 .../run-payroll/run-payroll.mdx               |  2 +-
 .../transition-payroll/transition-payroll.mdx |  4 +-
 14 files changed, 100 insertions(+), 82 deletions(-)

diff --git a/docs/workflows-overview/companies.mdx b/docs/workflows-overview/companies.mdx
index 9b040031e..2f5bc3d8f 100644
--- a/docs/workflows-overview/companies.mdx
+++ b/docs/workflows-overview/companies.mdx
@@ -4,16 +4,24 @@ description: SDK surface for onboarding a new company to Gusto Embedded Payroll
 order: 1
 ---
 
-The Companies surface covers everything required to onboard a new company to Gusto Embedded Payroll and to manage ongoing company-level interactions like outstanding information requests.
-
-## Company onboarding
-
-Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
-[Read more →](./company-onboarding/company-onboarding.mdx)
-
-## Information requests
-
-A standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.
+The Companies surface covers everything required to onboard a new company to Gusto Embedded Payroll and to manage ongoing company-level interactions like outstanding information requests.
 
-[Read more →](./information-requests/information-requests.mdx)
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Company onboarding',
+      description:
+        'Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.',
+      to: './company-onboarding/company-onboarding',
+    },
+    {
+      title: 'Information requests',
+      description:
+        'Standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.',
+      to: './information-requests/information-requests',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/company-onboarding/company-onboarding.mdx b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
index 9cac27107..574bf8dfb 100644
--- a/docs/workflows-overview/company-onboarding/company-onboarding.mdx
+++ b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
@@ -11,7 +11,7 @@ Company Onboarding walks a company through everything required before they can r
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
index fe386d173..00db90b1e 100644
--- a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
+++ b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
@@ -11,7 +11,7 @@ The Contractor Onboarding workflow collects everything required to set a contrac
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/contractor-payments/contractor-payments.mdx b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
index 574dbcb85..67759e949 100644
--- a/docs/workflows-overview/contractor-payments/contractor-payments.mdx
+++ b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
@@ -11,7 +11,7 @@ The Contractor Payments workflow lets a company create, manage, and view contrac
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/contractors.mdx b/docs/workflows-overview/contractors.mdx
index e08990599..7767e1e76 100644
--- a/docs/workflows-overview/contractors.mdx
+++ b/docs/workflows-overview/contractors.mdx
@@ -4,16 +4,24 @@ description: SDK surface for onboarding contractors and paying them on or off cy
 order: 3
 ---
 
-The Contractors surface covers everything required to bring a contractor onto a company and to pay them once they're active. The two flows can be used independently or composed together as part of a broader contractor management experience.
-
-## Contractor onboarding
-
-Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
-[Read more →](./contractor-onboarding/contractor-onboarding.mdx)
-
-## Contractor payments
-
-Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.
+The Contractors surface covers everything required to bring a contractor onto a company and to pay them once they're active. The two flows can be used independently or composed together as part of a broader contractor management experience.
 
-[Read more →](./contractor-payments/contractor-payments.mdx)
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Contractor onboarding',
+      description:
+        'Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.',
+      to: './contractor-onboarding/contractor-onboarding',
+    },
+    {
+      title: 'Contractor payments',
+      description:
+        'Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.',
+      to: './contractor-payments/contractor-payments',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
index ccf593022..c01b42a12 100644
--- a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
+++ b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
@@ -11,7 +11,7 @@ The Dismissal Payroll workflow provides a guided experience for running a termin
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
@@ -21,17 +21,3 @@ The Dismissal Payroll workflow provides a guided experience for running a termin
     },
   ]}
 />
-
-## Sub-components
-
-<LinkCardGrid
-  columns={1}
-  items={[
-    {
-      title: 'Sub-components',
-      description:
-        'Dismissal payroll is delivered as a single orchestrated flow. After creation, it reuses the standard payroll processing sub-components for configuration, overview, submission, and receipts.',
-      to: './sub-components',
-    },
-  ]}
-/>
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
index f356ef591..bc93d954c 100644
--- a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
+++ b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
@@ -1,5 +1,5 @@
 ---
-title: Onboard and employee to payroll
+title: Onboard an employee to payroll
 description: Admin-driven workflow for onboarding an employee to payroll — profile, compensation, taxes, payment method, and document signing, with optional I-9 step.
 order: 1
 ---
@@ -11,7 +11,7 @@ The Employee Onboarding workflow provides a complete experience for an admin to
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
index 68e11c1ef..fdff1e0d2 100644
--- a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
+++ b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
@@ -11,7 +11,7 @@ When an admin opts an employee into self-onboarding, the employee completes thei
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/employees.mdx b/docs/workflows-overview/employees.mdx
index 5e76d4b3a..1365f8913 100644
--- a/docs/workflows-overview/employees.mdx
+++ b/docs/workflows-overview/employees.mdx
@@ -4,16 +4,24 @@ description: SDK surface for onboarding new employees — admin-driven and emplo
 order: 2
 ---
 
-The Employees surface covers everything required to onboard new employees, whether the company admin drives the experience end-to-end or the employee completes onboarding themselves.
-
-## Employee onboarding
-
-An admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
-[Read more →](./employee-onboarding/employee-onboarding.mdx)
-
-## Employee self-onboarding
-
-An employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.
+The Employees surface covers everything required to onboard new employees, whether the company admin drives the experience end-to-end or the employee completes onboarding themselves.
 
-[Read more →](./employee-self-onboarding/employee-self-onboarding.mdx)
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Employee onboarding',
+      description:
+        'Admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.',
+      to: './employee-onboarding/employee-onboarding',
+    },
+    {
+      title: 'Employee self-onboarding',
+      description:
+        'Employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.',
+      to: './employee-self-onboarding/employee-self-onboarding',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/information-requests/information-requests.mdx b/docs/workflows-overview/information-requests/information-requests.mdx
index 15bcea801..d63f7a8ca 100644
--- a/docs/workflows-overview/information-requests/information-requests.mdx
+++ b/docs/workflows-overview/information-requests/information-requests.mdx
@@ -11,7 +11,7 @@ The Information Requests surface lets a company view and respond to outstanding
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
index 8349f1928..87affd1b8 100644
--- a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
+++ b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
@@ -11,7 +11,7 @@ The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/payroll.mdx b/docs/workflows-overview/payroll.mdx
index 292ff560a..6f9d88252 100644
--- a/docs/workflows-overview/payroll.mdx
+++ b/docs/workflows-overview/payroll.mdx
@@ -4,28 +4,36 @@ description: SDK surface for running payroll — regular, off-cycle, dismissal,
 order: 4
 ---
 
-The Payroll surface covers every way a company runs payroll: the regular pay-schedule flow, off-cycle payrolls (bonus or correction), the dismissal payroll for terminated employees, and the transition payroll for pay-schedule changes. All payroll types share the same execution steps; they differ only in how the payroll is created.
-
-## Payroll processing
-
-The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.
-
-[Read more →](./run-payroll/run-payroll.mdx)
-
-## Off-cycle payroll
-
-Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
-[Read more →](./off-cycle-payroll/off-cycle-payroll.mdx)
-
-## Dismissal payroll
-
-Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.
-
-[Read more →](./dismissal-payroll/dismissal-payroll.mdx)
-
-## Transition payroll
-
-Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.
+The Payroll surface covers every way a company runs payroll: the regular pay-schedule flow, off-cycle payrolls (bonus or correction), the dismissal payroll for terminated employees, and the transition payroll for pay-schedule changes. All payroll types share the same execution steps; they differ only in how the payroll is created.
 
-[Read more →](./transition-payroll/transition-payroll.mdx)
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Payroll processing',
+      description:
+        'The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.',
+      to: './run-payroll/run-payroll',
+    },
+    {
+      title: 'Off-cycle payroll',
+      description:
+        'Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.',
+      to: './off-cycle-payroll/off-cycle-payroll',
+    },
+    {
+      title: 'Dismissal payroll',
+      description:
+        'Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.',
+      to: './dismissal-payroll/dismissal-payroll',
+    },
+    {
+      title: 'Transition payroll',
+      description:
+        'Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.',
+      to: './transition-payroll/transition-payroll',
+    },
+  ]}
+/>
diff --git a/docs/workflows-overview/run-payroll/run-payroll.mdx b/docs/workflows-overview/run-payroll/run-payroll.mdx
index d26c3a310..b7280138c 100644
--- a/docs/workflows-overview/run-payroll/run-payroll.mdx
+++ b/docs/workflows-overview/run-payroll/run-payroll.mdx
@@ -11,7 +11,7 @@ The Payroll Processing workflow guides a company through running a regular payro
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
diff --git a/docs/workflows-overview/transition-payroll/transition-payroll.mdx b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
index 452bf183b..e0180eaba 100644
--- a/docs/workflows-overview/transition-payroll/transition-payroll.mdx
+++ b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
@@ -11,7 +11,7 @@ The Transition Payroll workflow handles payrolls that cover gaps between old and
 ## Workflow
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Workflow',
@@ -25,7 +25,7 @@ The Transition Payroll workflow handles payrolls that cover gaps between old and
 ## Sub-components
 
 <LinkCardGrid
-  columns={1}
+  columns={2}
   items={[
     {
       title: 'Transition creation',

From cb2f1deba80f44a603b21d86fab141f3ddeb6108 Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:01:11 -0400
Subject: [PATCH 05/10] fix(docs): restore .mdx extension on cross-doc
 LinkCardGrid links

Docusaurus broken-link check requires the .mdx suffix for sibling
document references.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/workflows-overview/companies.mdx   | 4 ++--
 docs/workflows-overview/contractors.mdx | 4 ++--
 docs/workflows-overview/employees.mdx   | 4 ++--
 docs/workflows-overview/payroll.mdx     | 8 ++++----
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/workflows-overview/companies.mdx b/docs/workflows-overview/companies.mdx
index 2f5bc3d8f..421ca0895 100644
--- a/docs/workflows-overview/companies.mdx
+++ b/docs/workflows-overview/companies.mdx
@@ -15,13 +15,13 @@ The Companies surface covers everything required to onboard a new company to Gus
       title: 'Company onboarding',
       description:
         'Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.',
-      to: './company-onboarding/company-onboarding',
+      to: './company-onboarding/company-onboarding.mdx',
     },
     {
       title: 'Information requests',
       description:
         'Standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.',
-      to: './information-requests/information-requests',
+      to: './information-requests/information-requests.mdx',
     },
   ]}
 />
diff --git a/docs/workflows-overview/contractors.mdx b/docs/workflows-overview/contractors.mdx
index 7767e1e76..45dd06f23 100644
--- a/docs/workflows-overview/contractors.mdx
+++ b/docs/workflows-overview/contractors.mdx
@@ -15,13 +15,13 @@ The Contractors surface covers everything required to bring a contractor onto a
       title: 'Contractor onboarding',
       description:
         'Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.',
-      to: './contractor-onboarding/contractor-onboarding',
+      to: './contractor-onboarding/contractor-onboarding.mdx',
     },
     {
       title: 'Contractor payments',
       description:
         'Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.',
-      to: './contractor-payments/contractor-payments',
+      to: './contractor-payments/contractor-payments.mdx',
     },
   ]}
 />
diff --git a/docs/workflows-overview/employees.mdx b/docs/workflows-overview/employees.mdx
index 1365f8913..4723f9259 100644
--- a/docs/workflows-overview/employees.mdx
+++ b/docs/workflows-overview/employees.mdx
@@ -15,13 +15,13 @@ The Employees surface covers everything required to onboard new employees, wheth
       title: 'Employee onboarding',
       description:
         'Admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.',
-      to: './employee-onboarding/employee-onboarding',
+      to: './employee-onboarding/employee-onboarding.mdx',
     },
     {
       title: 'Employee self-onboarding',
       description:
         'Employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.',
-      to: './employee-self-onboarding/employee-self-onboarding',
+      to: './employee-self-onboarding/employee-self-onboarding.mdx',
     },
   ]}
 />
diff --git a/docs/workflows-overview/payroll.mdx b/docs/workflows-overview/payroll.mdx
index 6f9d88252..9dfb0b235 100644
--- a/docs/workflows-overview/payroll.mdx
+++ b/docs/workflows-overview/payroll.mdx
@@ -15,25 +15,25 @@ The Payroll surface covers every way a company runs payroll: the regular pay-sch
       title: 'Payroll processing',
       description:
         'The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.',
-      to: './run-payroll/run-payroll',
+      to: './run-payroll/run-payroll.mdx',
     },
     {
       title: 'Off-cycle payroll',
       description:
         'Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.',
-      to: './off-cycle-payroll/off-cycle-payroll',
+      to: './off-cycle-payroll/off-cycle-payroll.mdx',
     },
     {
       title: 'Dismissal payroll',
       description:
         'Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.',
-      to: './dismissal-payroll/dismissal-payroll',
+      to: './dismissal-payroll/dismissal-payroll.mdx',
     },
     {
       title: 'Transition payroll',
       description:
         'Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.',
-      to: './transition-payroll/transition-payroll',
+      to: './transition-payroll/transition-payroll.mdx',
     },
   ]}
 />

From 34aefa7a52621e4ad253e4efca21e6b143c00dfd Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:15:38 -0400
Subject: [PATCH 06/10] fix(docs): use category slugs for LinkCardGrid links

The sidebar maps each *-onboarding.mdx into a category-with-link, which
relocates the doc's route to the category path (e.g. /workflows-overview/
employee-onboarding instead of .../employee-onboarding/employee-onboarding).
Target the category slug directly so the Docusaurus broken-link check
passes. Verified with a local build.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/workflows-overview/companies.mdx                     | 4 ++--
 .../company-onboarding/company-onboarding.mdx             | 2 --
 .../contractor-onboarding/contractor-onboarding.mdx       | 2 --
 .../contractor-payments/contractor-payments.mdx           | 2 --
 docs/workflows-overview/contractors.mdx                   | 4 ++--
 .../dismissal-payroll/dismissal-payroll.mdx               | 2 --
 .../employee-onboarding/employee-onboarding.mdx           | 2 --
 .../employee-self-onboarding/employee-self-onboarding.mdx | 2 --
 docs/workflows-overview/employees.mdx                     | 4 ++--
 .../information-requests/information-requests.mdx         | 2 --
 .../off-cycle-payroll/off-cycle-payroll.mdx               | 2 --
 docs/workflows-overview/payroll.mdx                       | 8 ++++----
 docs/workflows-overview/run-payroll/run-payroll.mdx       | 2 --
 .../transition-payroll/transition-payroll.mdx             | 2 --
 14 files changed, 10 insertions(+), 30 deletions(-)

diff --git a/docs/workflows-overview/companies.mdx b/docs/workflows-overview/companies.mdx
index 421ca0895..d948281c2 100644
--- a/docs/workflows-overview/companies.mdx
+++ b/docs/workflows-overview/companies.mdx
@@ -15,13 +15,13 @@ The Companies surface covers everything required to onboard a new company to Gus
       title: 'Company onboarding',
       description:
         'Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.',
-      to: './company-onboarding/company-onboarding.mdx',
+      to: '/docs/workflows-overview/company-onboarding',
     },
     {
       title: 'Information requests',
       description:
         'Standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.',
-      to: './information-requests/information-requests.mdx',
+      to: '/docs/workflows-overview/information-requests',
     },
   ]}
 />
diff --git a/docs/workflows-overview/company-onboarding/company-onboarding.mdx b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
index 574bf8dfb..d3c51c5e0 100644
--- a/docs/workflows-overview/company-onboarding/company-onboarding.mdx
+++ b/docs/workflows-overview/company-onboarding/company-onboarding.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 Company Onboarding walks a company through everything required before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
index 00db90b1e..d6e4d2441 100644
--- a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
+++ b/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Contractor Onboarding workflow collects everything required to set a contractor up for payment: profile, address, payment method, new hire reporting, and final submission. The same building blocks can be composed end-to-end as a full workflow or rendered individually as standalone sub-components.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/contractor-payments/contractor-payments.mdx b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
index 67759e949..5618bf6df 100644
--- a/docs/workflows-overview/contractor-payments/contractor-payments.mdx
+++ b/docs/workflows-overview/contractor-payments/contractor-payments.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Contractor Payments workflow lets a company create, manage, and view contractor payment groups. The full experience can be dropped in as a single component, or assembled from individual sub-components — payment list, payment creation, history, summary, and individual payment statements.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/contractors.mdx b/docs/workflows-overview/contractors.mdx
index 45dd06f23..2321a78e6 100644
--- a/docs/workflows-overview/contractors.mdx
+++ b/docs/workflows-overview/contractors.mdx
@@ -15,13 +15,13 @@ The Contractors surface covers everything required to bring a contractor onto a
       title: 'Contractor onboarding',
       description:
         'Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.',
-      to: './contractor-onboarding/contractor-onboarding.mdx',
+      to: '/docs/workflows-overview/contractor-onboarding',
     },
     {
       title: 'Contractor payments',
       description:
         'Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.',
-      to: './contractor-payments/contractor-payments.mdx',
+      to: '/docs/workflows-overview/contractor-payments',
     },
   ]}
 />
diff --git a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
index c01b42a12..c1ca005ce 100644
--- a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
+++ b/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Dismissal Payroll workflow provides a guided experience for running a terminated employee's final payroll. It presents unprocessed termination pay periods for the employee, creates an off-cycle payroll for the selected period, and then transitions into the standard payroll execution flow. Like all off-cycle payroll types, the dismissal flow shares the same execution steps as regular payrolls — the only difference is how the payroll is created.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
index bc93d954c..73cf4fa27 100644
--- a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
+++ b/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Employee Onboarding workflow provides a complete experience for an admin to onboard a new employee to a company. It collects every piece of information required for the employee to be added to payroll, and can be composed end-to-end as a full workflow or rendered piece by piece as standalone sub-components.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
index fdff1e0d2..ca2c51aaf 100644
--- a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
+++ b/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 When an admin opts an employee into self-onboarding, the employee completes their own onboarding steps — profile, tax, payment method, and document signing — rather than the admin entering everything on their behalf. The workflow can be composed end-to-end as a single component, or built from standalone sub-components when you need full control over the surrounding experience.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/employees.mdx b/docs/workflows-overview/employees.mdx
index 4723f9259..38a9437c5 100644
--- a/docs/workflows-overview/employees.mdx
+++ b/docs/workflows-overview/employees.mdx
@@ -15,13 +15,13 @@ The Employees surface covers everything required to onboard new employees, wheth
       title: 'Employee onboarding',
       description:
         'Admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.',
-      to: './employee-onboarding/employee-onboarding.mdx',
+      to: '/docs/workflows-overview/employee-onboarding',
     },
     {
       title: 'Employee self-onboarding',
       description:
         'Employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.',
-      to: './employee-self-onboarding/employee-self-onboarding.mdx',
+      to: '/docs/workflows-overview/employee-self-onboarding',
     },
   ]}
 />
diff --git a/docs/workflows-overview/information-requests/information-requests.mdx b/docs/workflows-overview/information-requests/information-requests.mdx
index d63f7a8ca..f13055643 100644
--- a/docs/workflows-overview/information-requests/information-requests.mdx
+++ b/docs/workflows-overview/information-requests/information-requests.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Information Requests surface lets a company view and respond to outstanding information requests Gusto has issued — for example, a request for a missing tax document or identity verification artifact. Information requests can also block payroll processing, in which case they surface inline within `Payroll.PayrollBlockerList`; this surface is the dedicated, standalone version.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
index 87affd1b8..ca77f5939 100644
--- a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
+++ b/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Off-Cycle Payroll workflow runs payrolls outside of a company's regular pay schedule. It supports two off-cycle reasons — **Bonus** (paying a bonus, gift, or commission) and **Correction** (running a correction payment) — and guides users through configuring pay period dates, selecting a reason, choosing employees, and setting deduction and tax withholding preferences. After creation, the flow transitions into the standard payroll execution experience.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/payroll.mdx b/docs/workflows-overview/payroll.mdx
index 9dfb0b235..d6eccc196 100644
--- a/docs/workflows-overview/payroll.mdx
+++ b/docs/workflows-overview/payroll.mdx
@@ -15,25 +15,25 @@ The Payroll surface covers every way a company runs payroll: the regular pay-sch
       title: 'Payroll processing',
       description:
         'The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.',
-      to: './run-payroll/run-payroll.mdx',
+      to: '/docs/workflows-overview/run-payroll',
     },
     {
       title: 'Off-cycle payroll',
       description:
         'Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.',
-      to: './off-cycle-payroll/off-cycle-payroll.mdx',
+      to: '/docs/workflows-overview/off-cycle-payroll',
     },
     {
       title: 'Dismissal payroll',
       description:
         'Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.',
-      to: './dismissal-payroll/dismissal-payroll.mdx',
+      to: '/docs/workflows-overview/dismissal-payroll',
     },
     {
       title: 'Transition payroll',
       description:
         'Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.',
-      to: './transition-payroll/transition-payroll.mdx',
+      to: '/docs/workflows-overview/transition-payroll',
     },
   ]}
 />
diff --git a/docs/workflows-overview/run-payroll/run-payroll.mdx b/docs/workflows-overview/run-payroll/run-payroll.mdx
index b7280138c..40e4b24a2 100644
--- a/docs/workflows-overview/run-payroll/run-payroll.mdx
+++ b/docs/workflows-overview/run-payroll/run-payroll.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Payroll Processing workflow guides a company through running a regular payroll: selecting a payroll, configuring employee compensation, reviewing payroll details, confirming wire transfers, and submitting. The full experience can be dropped in as a single component, or assembled from individual sub-components for full control over the surrounding UI.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[
diff --git a/docs/workflows-overview/transition-payroll/transition-payroll.mdx b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
index e0180eaba..ac55911ab 100644
--- a/docs/workflows-overview/transition-payroll/transition-payroll.mdx
+++ b/docs/workflows-overview/transition-payroll/transition-payroll.mdx
@@ -8,8 +8,6 @@ import LinkCardGrid from '@site/src/components/LinkCardGrid'
 
 The Transition Payroll workflow handles payrolls that cover gaps between old and new pay schedules. When a company changes its pay schedule, there may be workdays that fall between the end of the old schedule and the start of the new one — transition payrolls ensure employees are paid for those days. The SDK provides a flow component for running a specific transition payroll and an integrated alert (rendered inside `Payroll.PayrollLanding`) that surfaces unprocessed transition periods.
 
-## Workflow
-
 <LinkCardGrid
   columns={2}
   items={[

From 93295893bc4a740cd9738ac2139b033725a7d925 Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:25:36 -0400
Subject: [PATCH 07/10] docs: rename "deciding-to-build-with-the-sdk" to
 "build-methods"

Rename the section directory and its three pages around their new purpose:
- build-pathways-sdk-flows-api.md -> workflows.md (explains workflows)
- component-types.md -> sub-components.md (explains sub-components)
- deciding-to-build-with-the-sdk.md -> hooks.md (explains hooks)

Rewrite each page to cover its new topic and add a build-methods.md
landing page with a side-by-side comparison and "when to pick which"
decision guide. Wire the new landing page into the sidebar.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs-site/sidebars.ts                         | 15 +++---
 docs/build-methods/build-methods.md           | 40 ++++++++++++++
 docs/build-methods/hooks.md                   | 53 +++++++++++++++++++
 docs/build-methods/sub-components.md          | 42 +++++++++++++++
 docs/build-methods/workflows.md               | 39 ++++++++++++++
 .../build-pathways-sdk-flows-api.md           | 23 --------
 .../component-types.md                        | 18 -------
 .../deciding-to-build-with-the-sdk.md         | 30 -----------
 8 files changed, 180 insertions(+), 80 deletions(-)
 create mode 100644 docs/build-methods/build-methods.md
 create mode 100644 docs/build-methods/hooks.md
 create mode 100644 docs/build-methods/sub-components.md
 create mode 100644 docs/build-methods/workflows.md
 delete mode 100644 docs/deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api.md
 delete mode 100644 docs/deciding-to-build-with-the-sdk/component-types.md
 delete mode 100644 docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md

diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index efea1fb17..c093a22bd 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -9,15 +9,12 @@ const sidebars: SidebarsConfig = {
       collapsed: true,
       items: ['getting-started/authentication', 'getting-started/proxy-security-partner-guidance'],
     },
-    // {
-    //   type: 'category',
-    //   label: 'Deciding to build with the SDK',
-    //   link: { type: 'doc', id: 'deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk' },
-    //   items: [
-    //     'deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api',
-    //     'deciding-to-build-with-the-sdk/component-types',
-    //   ],
-    // },
+    {
+      type: 'category',
+      label: 'Build methods',
+      link: { type: 'doc', id: 'build-methods/build-methods' },
+      items: ['build-methods/workflows', 'build-methods/sub-components', 'build-methods/hooks'],
+    },
     {
       type: 'category',
       label: 'Surfaces',
diff --git a/docs/build-methods/build-methods.md b/docs/build-methods/build-methods.md
new file mode 100644
index 000000000..bb03f020d
--- /dev/null
+++ b/docs/build-methods/build-methods.md
@@ -0,0 +1,40 @@
+---
+title: Build methods
+description: Three ways to build with the Gusto Embedded React SDK — workflows, sub-components, and hooks — and how to pick the right one for each surface.
+order: 0
+---
+
+# Build methods
+
+The SDK exposes the same payroll surfaces at three levels of integration depth. Each one trades control for effort: workflows do the most for you, hooks give you the most say.
+
+| Method                                | What you write                                             | What the SDK handles                                                         | Customizable                                          |
+| ------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
+| [Workflows](./workflows.md)           | A single component drop-in, plus IDs and an event handler  | Step routing, data fetching, validation, submission, error handling, layout  | Theming, copy, the surface's public props             |
+| [Sub-components](./sub-components.md) | One component per step, wired together by your own routing | Data fetching, validation, submission, error handling, the step's own layout | The above, plus step order and which steps to include |
+| [Hooks](./hooks.md)                   | Your own layout, your own copy, your own field arrangement | Data fetching, validation, submission, error handling                        | Everything visual                                     |
+
+## When to pick which
+
+**Pick a workflow when…**
+
+- You want a complete surface live as quickly as possible.
+- The default order of steps and the default copy work for the experience you're building.
+- You don't need to insert your own screens into the middle of the flow.
+
+**Pick sub-components when…**
+
+- You want to reorder, remove, or insert your own steps in between the SDK's steps.
+- You only need part of a surface — for example, an "Edit profile" page that reuses the Profile step without the rest of onboarding.
+- You're building a multi-step experience whose shape doesn't match any of the shipped workflows but whose individual steps do.
+
+**Pick hooks when…**
+
+- The default layout of a sub-component doesn't fit the design you need.
+- You want to control labels, helper text, field grouping, or where the submit button lives.
+- You're embedding fields into a form shell that's already part of your app (a side panel, a wizard with its own chrome, a multi-column layout).
+- You need to do something between validation and submission — e.g. show a confirmation step or capture additional data.
+
+## You can mix and match
+
+These methods aren't mutually exclusive across a single app — or even a single surface. A common pattern is to start with the workflow drop-in to get something shipping, then swap one or two steps out for sub-components or hooks as the design evolves. The data model and event shapes are consistent across all three layers, so moving down a level doesn't require rewriting how the rest of the app integrates.
diff --git a/docs/build-methods/hooks.md b/docs/build-methods/hooks.md
new file mode 100644
index 000000000..b817ef492
--- /dev/null
+++ b/docs/build-methods/hooks.md
@@ -0,0 +1,53 @@
+---
+title: Hooks
+description: Headless React hooks that handle data fetching, validation, submission, and error handling — you own the layout, copy, and ordering around them.
+order: 2
+---
+
+# Hooks
+
+Hooks are the headless layer of the SDK. They handle data fetching, validation, submission, and error handling, and hand back exactly what's needed to render a step — but no layout, no chrome, no fixed copy. You decide how the markup is arranged and what the labels say.
+
+Hooks are the deepest level of control the SDK exposes. Reach for them when [sub-components](./sub-components.md) don't give you enough say over layout or copy, when you need to slot fields into an existing form shell, or when you're building a screen that doesn't map cleanly onto a single sub-component.
+
+> Hooks are an experimental feature. APIs may change between minor versions during 0.x.x releases.
+
+## Two kinds of hooks
+
+- **Form hooks** return pre-bound Field components, form actions, and metadata. You arrange the fields, label them, and decide when to call submit. Validation, submission, and error handling are wired up for you.
+- **Data hooks** return fetched, decorated data plus the actions valid for it. You render it however you like.
+
+Both follow the same loading/error conventions: a discriminated `isLoading` union plus a shared `errorHandling` contract that surfaces server validation back into the form.
+
+## Example
+
+A form hook returns pre-bound Field components and a `handleSubmit` action — drop them into whatever layout you want:
+
+```jsx
+import { GustoProvider, useEmployeeDetailsForm } from '@gusto/embedded-react-sdk'
+
+function App({ companyId }) {
+  return (
+    <GustoProvider config={{ apiToken: '...' }}>
+      <EmployeeDetails companyId={companyId} />
+    </GustoProvider>
+  )
+}
+
+function EmployeeDetails({ companyId }) {
+  const form = useEmployeeDetailsForm({ companyId })
+
+  if (form.isLoading) return null
+
+  return (
+    <form onSubmit={form.handleSubmit}>
+      <form.FirstNameField />
+      <form.LastNameField />
+      <form.EmailField />
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+See the [hooks reference](../hooks/hooks.md) for the full list of available form and data hooks, along with the return shape, props, and events for each.
diff --git a/docs/build-methods/sub-components.md b/docs/build-methods/sub-components.md
new file mode 100644
index 000000000..badfdae88
--- /dev/null
+++ b/docs/build-methods/sub-components.md
@@ -0,0 +1,42 @@
+---
+title: Sub-components
+description: The individual steps that make up each workflow — render them standalone or compose them into a custom multi-step experience.
+order: 1
+---
+
+# Sub-components
+
+Each workflow is assembled from a set of sub-components — Profile, Compensation, Federal Taxes, Documents, and so on. Every sub-component is also exported on its own, so you can render any single step in isolation or compose them into a multi-step experience of your own design.
+
+Sub-components sit between [workflows](./workflows.md) and [hooks](./hooks.md): more control than a workflow, less work than a fully headless hook integration. Reach for them when the built-in workflow's order or set of steps doesn't match what you want to render, or when you only need part of a surface (for example, an in-app "Edit profile" page that reuses the Profile step without the rest of onboarding).
+
+## What a sub-component gives you
+
+- A standalone React component for one logical step
+- The same data fetching, validation, and submission as the workflow uses
+- Step-level events on `onEvent` (entity created, entity updated, "done" with that step)
+- No assumption about what step comes next — that's yours to wire up
+
+## Example
+
+Render the Profile step in isolation:
+
+```jsx
+import { Employee } from '@gusto/embedded-react-sdk'
+
+function EditProfilePage({ companyId, employeeId }) {
+  return (
+    <Employee.Profile
+      companyId={companyId}
+      employeeId={employeeId}
+      isAdmin
+      onEvent={(eventType, data) => {
+        // Handle EMPLOYEE_PROFILE_DONE here to advance,
+        // close a modal, or refresh upstream state.
+      }}
+    />
+  )
+}
+```
+
+Each surface page lists every sub-component it exposes, the props each accepts, and the events each emits. For guidance on composing several sub-components into a custom multi-step flow, see the [composition guide](../integration-guide/composition.md).
diff --git a/docs/build-methods/workflows.md b/docs/build-methods/workflows.md
new file mode 100644
index 000000000..a2b19caaa
--- /dev/null
+++ b/docs/build-methods/workflows.md
@@ -0,0 +1,39 @@
+---
+title: Workflows
+description: Drop-in React components that render a complete multi-step Gusto Embedded experience end to end — routing, data fetching, validation, and error handling included.
+order: 0
+---
+
+# Workflows
+
+A workflow is a single React component that renders a complete multi-step experience end to end. It manages routing between steps, data fetching, validation, submission, and error handling internally. Supply IDs and an event handler — the workflow handles the rest.
+
+Workflows are the fastest way to ship a complete surface. The tradeoff is composition: the order and presence of steps is fixed, so reach for [sub-components](./sub-components.md) when you need to reorder, insert, or replace steps, and [hooks](./hooks.md) when you need to own the layout entirely.
+
+## What a workflow includes
+
+- A single component that mounts the full flow
+- Built-in step routing, including back/next behavior and conditional steps
+- Data fetching for every step from the Gusto API
+- Validation and submission for every step
+- A unified `onEvent` callback that fires at meaningful checkpoints (step completed, entity created, flow finished)
+
+## Example
+
+```jsx
+import { EmployeeOnboarding } from '@gusto/embedded-react-sdk'
+
+function EmployeeOnboardingPage({ companyId }) {
+  return (
+    <EmployeeOnboarding.OnboardingFlow
+      companyId={companyId}
+      onEvent={(eventType, data) => {
+        // React to flow events — e.g. record analytics or
+        // navigate elsewhere when onboarding completes.
+      }}
+    />
+  )
+}
+```
+
+Each surface in the SDK ships a workflow. See the [Surfaces section](../workflows-overview/workflows-overview.mdx) for the full list, with the props and events each one accepts.
diff --git a/docs/deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api.md b/docs/deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api.md
deleted file mode 100644
index 9ba390213..000000000
--- a/docs/deciding-to-build-with-the-sdk/build-pathways-sdk-flows-api.md
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: Build Pathways - SDK, Flows, & API
-description: Compare the three Gusto Embedded Payroll build pathways — custom API, Flows via iframe, and the React SDK — with tradeoffs around coverage, speed, and customizability.
-order: 0
----
-
-## How do I decide how I want to build payroll on GEP?
-
-Payroll is a very comprehensive product, involving multiple workflows and UI aspects that must be built in order for your customers to:
-
-1. Provide all the inputs into payroll (e.g. employees, addresses, pay schedules, etc.)
-2. Run the various types of payrolls (e.g. regular, off cycle, dismissal etc.)
-3. Manage payroll and the associated data afterward.
-
-An approximation of the most important workflows in a comprehensive payroll product can be found in our Flows list - [see here and try them out](https://docs.gusto.com/embedded-payroll/docs/flow-types)!
-
-Of course, this can be very time consuming to build. To cover this ground, GEP offers _three_ approaches to building your payroll product, which you can mix-and-match for various aspects of your application - depending on your needs for each workflow:
-
-| Approach          | Pros                                                                                                                                           | Cons                                                                            | Documentation                                                                                                                                                                                |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Custom (API only) | Full coverage for all of GEP’s capabilities<br/>Full customization of your application                                                         | Requires you to build the UI<br/>Requires understanding of individual endpoints | [GEP API Reference](https://docs.gusto.com/embedded-payroll/reference)                                                                                                                       |
-| Flows via iframe  | Fastest way to deploy any given workflow - all of the needed logic and API linkage already built in                                            | Limited customizability beyond basic look and feel                              | [List of available Flows via iframe](https://docs.gusto.com/embedded-payroll/docs/flow-types)<br/>[Flow customization options](https://docs.gusto.com/embedded-payroll/docs/customize-flows) |
-| React SDK         | Strikes the balance between Custom (API only) and Flows - enables more customization than Flows, and abstracts away logic around API endpoints | Workflows are limited but planned on our developer roadmap                      | See the other sections of this guide!                                                                                                                                                        |
diff --git a/docs/deciding-to-build-with-the-sdk/component-types.md b/docs/deciding-to-build-with-the-sdk/component-types.md
deleted file mode 100644
index c75f205e8..000000000
--- a/docs/deciding-to-build-with-the-sdk/component-types.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: Component Types
-description: How the SDK organizes UI into Workflow components (end-to-end, off-the-shelf flows) and Building Block components (granular pieces with more customization).
-order: 1
----
-
-## SDK Component Types and “Altitude”
-
-Given that a UI “component” can be anything ranging from a table to an entire end-to-end workflow reflecting the various steps of a user journey (e.g. employee onboarding), we wanted to provide more optionality for our developers by building a mix of components in terms of complexity/granularity.
-
-For each domain in the payroll application (e.g. run payroll, company onboarding, etc.), we include:
-
-- **“Workflow”** SDK components function as a full, off-the-shelf-ready solutions that can either serve as the entirety or the starting point for your build. This component would still have many of the customization and flexibility of the individual SDK components, but would lack the following capabilities:
-  - Cannot re-order or remove fields
-  - Has less flexibility to support A/B testing due to rigidity of the sub-components
-- **“Building Block”** SDK components that represent the individual pieces of the Workflow above. Using these would provide more customization and flexibility, but would be more time-consuming compared to the ready-built Workflow above.
-
-While we generally recommend using the Workflow approach, your build needs may vary and we recommend discussing with a dedicated specialist from our side to determine what makes sense given your goals and your current application.
diff --git a/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md b/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md
deleted file mode 100644
index ef02fec5d..000000000
--- a/docs/deciding-to-build-with-the-sdk/deciding-to-build-with-the-sdk.md
+++ /dev/null
@@ -1,30 +0,0 @@
----
-title: Deciding to build with the SDK
-description: Considerations for choosing the React SDK over Flows or a custom API build — React stack fit, abstraction over endpoints, theming, coverage, and customization depth.
-order: 1
----
-
-## How do I know if the GEP React SDK is right for me?
-
-While it’s possible to mix and match the build approach _across_ the domain of your payroll application, you would still generally want to match your needs to the best approach out of the possible build options (SDK, Flows, or build your own UI) for any given domain within the payroll application. As our SDK components are still in an early phase of development, many components may not yet be available via SDK (discuss with your Gusto point of contact if you’d like to inquire about a specific component).
-
-Here are some considerations when deciding whether or not to use the React SDK for any given payroll workflow for your application:
-
-**You should use the React SDK if…**
-
-- If you already use React in your application, or are open to introducing React into your stack ([Learn how to add React to existing projects](https://react.dev/learn/add-react-to-an-existing-project))
-- You want to use pre-built components that abstract API endpoint complexity
-- You already capture info required for a particular workflow (e.g. company onboarding)
-- You want to customize components to your application’s theme and layout
-- You’re just starting out with building embedded payroll on GEP, or the components you want to use are currently available via the SDK library
-
-**You may benefit from a different build approach if…**
-
-- You need to deploy a proof of concept as soon as possible, even if the resulting application feels inconsistent in look and feel and non-integrated with the rest of your application (e.g. data that you already have may be requested again).
-  - If your number one priority is speed, you may need to use [Flows](https://docs.gusto.com/embedded-payroll/docs/flows-intro) instead, as it is still the fastest way to deploy any given workflow.
-- You have very deep customization needs that may not be met by the React SDK (if in doubt, ask your Gusto Embedded point of contact!). You may need to create a custom, API-only build to accommodate your requirements, but we would still highly recommend using SDK or Flow components where possible to reduce your build workload.
-- The SDK component you need currently does not yet exist: we are actively working on several components to cover the rest of our application - for what’s currently available, see the Workflows Overview section and reach out to your Gusto Embedded point of contact for more information!
-
-### How can I learn more about React SDK?
-
-As a Gusto Embedded partner, we will provide consultation with a GEP Solutions Architect to ensure we can find the right solution for you. We recommend starting with the documentation sections provided, and please reach out to your Gusto Embedded representative to learn more!

From 43df4f1e9dbbf16def7d169a162e5e01f487b798 Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:30:30 -0400
Subject: [PATCH 08/10] fix(docs): add trailing slashes to LinkCardGrid
 category links

Each category landing (company-onboarding, etc.) is emitted at
.../company-onboarding/index.html, so its canonical URL ends with a
slash. The absolute hrefs from the surface landing pages omitted the
slash, which left the in-app pathname without one. The relative
./workflow and ./sub-components links on the destination then resolved
up a directory and 404'd. Direct navigation worked only because the
browser canonicalized the URL on load.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/workflows-overview/companies.mdx   | 4 ++--
 docs/workflows-overview/contractors.mdx | 4 ++--
 docs/workflows-overview/employees.mdx   | 4 ++--
 docs/workflows-overview/payroll.mdx     | 8 ++++----
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/workflows-overview/companies.mdx b/docs/workflows-overview/companies.mdx
index d948281c2..930168835 100644
--- a/docs/workflows-overview/companies.mdx
+++ b/docs/workflows-overview/companies.mdx
@@ -15,13 +15,13 @@ The Companies surface covers everything required to onboard a new company to Gus
       title: 'Company onboarding',
       description:
         'Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.',
-      to: '/docs/workflows-overview/company-onboarding',
+      to: '/docs/workflows-overview/company-onboarding/',
     },
     {
       title: 'Information requests',
       description:
         'Standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.',
-      to: '/docs/workflows-overview/information-requests',
+      to: '/docs/workflows-overview/information-requests/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/contractors.mdx b/docs/workflows-overview/contractors.mdx
index 2321a78e6..a05ac0ebd 100644
--- a/docs/workflows-overview/contractors.mdx
+++ b/docs/workflows-overview/contractors.mdx
@@ -15,13 +15,13 @@ The Contractors surface covers everything required to bring a contractor onto a
       title: 'Contractor onboarding',
       description:
         'Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.',
-      to: '/docs/workflows-overview/contractor-onboarding',
+      to: '/docs/workflows-overview/contractor-onboarding/',
     },
     {
       title: 'Contractor payments',
       description:
         'Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.',
-      to: '/docs/workflows-overview/contractor-payments',
+      to: '/docs/workflows-overview/contractor-payments/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/employees.mdx b/docs/workflows-overview/employees.mdx
index 38a9437c5..49eb1ee0d 100644
--- a/docs/workflows-overview/employees.mdx
+++ b/docs/workflows-overview/employees.mdx
@@ -15,13 +15,13 @@ The Employees surface covers everything required to onboard new employees, wheth
       title: 'Employee onboarding',
       description:
         'Admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.',
-      to: '/docs/workflows-overview/employee-onboarding',
+      to: '/docs/workflows-overview/employee-onboarding/',
     },
     {
       title: 'Employee self-onboarding',
       description:
         'Employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.',
-      to: '/docs/workflows-overview/employee-self-onboarding',
+      to: '/docs/workflows-overview/employee-self-onboarding/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/payroll.mdx b/docs/workflows-overview/payroll.mdx
index d6eccc196..e594accda 100644
--- a/docs/workflows-overview/payroll.mdx
+++ b/docs/workflows-overview/payroll.mdx
@@ -15,25 +15,25 @@ The Payroll surface covers every way a company runs payroll: the regular pay-sch
       title: 'Payroll processing',
       description:
         'The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.',
-      to: '/docs/workflows-overview/run-payroll',
+      to: '/docs/workflows-overview/run-payroll/',
     },
     {
       title: 'Off-cycle payroll',
       description:
         'Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.',
-      to: '/docs/workflows-overview/off-cycle-payroll',
+      to: '/docs/workflows-overview/off-cycle-payroll/',
     },
     {
       title: 'Dismissal payroll',
       description:
         'Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.',
-      to: '/docs/workflows-overview/dismissal-payroll',
+      to: '/docs/workflows-overview/dismissal-payroll/',
     },
     {
       title: 'Transition payroll',
       description:
         'Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.',
-      to: '/docs/workflows-overview/transition-payroll',
+      to: '/docs/workflows-overview/transition-payroll/',
     },
   ]}
 />

From 1daa86c72453e04e85337e4edf06a077e161791b Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:33:30 -0400
Subject: [PATCH 09/10] docs: rename workflows-overview route/directory to
 surfaces

The directory was already labeled "Surfaces" in the sidebar; rename
docs/workflows-overview to docs/surfaces and the index file to
surfaces.mdx so the URL matches: /docs/workflows-overview/* ->
/docs/surfaces/*. Update sidebar IDs, SurfacesGrid links, footer link,
NotFound page link, landing-page LinkCardGrid hrefs, and cross-doc
references in build-methods and composition guides.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs-site/docusaurus.config.ts                |  2 +-
 docs-site/sidebars.ts                         | 70 +++++++++----------
 .../src/components/SurfacesGrid/index.tsx     |  8 +--
 docs-site/src/pages/index.tsx                 |  2 +-
 .../src/theme/NotFound/Content/index.tsx      |  2 +-
 docs/build-methods/workflows.md               |  2 +-
 docs/integration-guide/composition.md         |  2 +-
 .../companies.mdx                             |  4 +-
 .../company-onboarding/company-onboarding.mdx |  0
 .../company-onboarding/sub-components.md      |  0
 .../company-onboarding/workflow.md            |  0
 .../contractor-onboarding.mdx                 |  0
 .../contractor-onboarding/sub-components.md   |  0
 .../contractor-onboarding/workflow.md         |  0
 .../contractor-payments.mdx                   |  0
 .../contractor-payments/sub-components.md     |  0
 .../contractor-payments/workflow.md           |  0
 .../contractors.mdx                           |  4 +-
 .../dismissal-payroll/dismissal-payroll.mdx   |  0
 .../dismissal-payroll/sub-components.md       |  0
 .../dismissal-payroll/workflow.md             |  0
 .../employee-dashboard.md                     |  0
 .../employee-management.md                    |  0
 .../employee-onboarding.mdx                   |  0
 .../employee-onboarding/sub-components.md     |  0
 .../employee-onboarding/workflow.md           |  0
 .../employee-self-onboarding.mdx              |  0
 .../sub-components.md                         |  0
 .../employee-self-onboarding/workflow.md      |  0
 .../employee-termination.md                   |  0
 .../employees.mdx                             |  4 +-
 .../information-requests.mdx                  |  0
 .../information-requests/sub-components.md    |  0
 .../information-requests/workflow.md          |  0
 .../off-cycle-payroll/off-cycle-payroll.mdx   |  0
 .../off-cycle-payroll/sub-components.md       |  0
 .../off-cycle-payroll/workflow.md             |  0
 .../payroll.mdx                               |  8 +--
 .../run-payroll/run-payroll.mdx               |  0
 .../run-payroll/sub-components.md             |  0
 .../run-payroll/workflow.md                   |  0
 .../surfaces.mdx}                             |  0
 .../time-off.md                               |  0
 .../transition-payroll/sub-components.md      |  0
 .../transition-payroll/transition-payroll.mdx |  0
 .../transition-payroll/workflow.md            |  0
 46 files changed, 54 insertions(+), 54 deletions(-)
 rename docs/{workflows-overview => surfaces}/companies.mdx (89%)
 rename docs/{workflows-overview => surfaces}/company-onboarding/company-onboarding.mdx (100%)
 rename docs/{workflows-overview => surfaces}/company-onboarding/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/company-onboarding/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/contractor-onboarding/contractor-onboarding.mdx (100%)
 rename docs/{workflows-overview => surfaces}/contractor-onboarding/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/contractor-onboarding/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/contractor-payments/contractor-payments.mdx (100%)
 rename docs/{workflows-overview => surfaces}/contractor-payments/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/contractor-payments/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/contractors.mdx (88%)
 rename docs/{workflows-overview => surfaces}/dismissal-payroll/dismissal-payroll.mdx (100%)
 rename docs/{workflows-overview => surfaces}/dismissal-payroll/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/dismissal-payroll/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-dashboard.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-management/employee-management.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-onboarding/employee-onboarding.mdx (100%)
 rename docs/{workflows-overview => surfaces}/employee-onboarding/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-onboarding/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-self-onboarding/employee-self-onboarding.mdx (100%)
 rename docs/{workflows-overview => surfaces}/employee-self-onboarding/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-self-onboarding/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/employee-termination.md (100%)
 rename docs/{workflows-overview => surfaces}/employees.mdx (89%)
 rename docs/{workflows-overview => surfaces}/information-requests/information-requests.mdx (100%)
 rename docs/{workflows-overview => surfaces}/information-requests/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/information-requests/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/off-cycle-payroll/off-cycle-payroll.mdx (100%)
 rename docs/{workflows-overview => surfaces}/off-cycle-payroll/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/off-cycle-payroll/workflow.md (100%)
 rename docs/{workflows-overview => surfaces}/payroll.mdx (86%)
 rename docs/{workflows-overview => surfaces}/run-payroll/run-payroll.mdx (100%)
 rename docs/{workflows-overview => surfaces}/run-payroll/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/run-payroll/workflow.md (100%)
 rename docs/{workflows-overview/workflows-overview.mdx => surfaces/surfaces.mdx} (100%)
 rename docs/{workflows-overview => surfaces}/time-off.md (100%)
 rename docs/{workflows-overview => surfaces}/transition-payroll/sub-components.md (100%)
 rename docs/{workflows-overview => surfaces}/transition-payroll/transition-payroll.mdx (100%)
 rename docs/{workflows-overview => surfaces}/transition-payroll/workflow.md (100%)

diff --git a/docs-site/docusaurus.config.ts b/docs-site/docusaurus.config.ts
index a55bf7b75..50b78ac07 100644
--- a/docs-site/docusaurus.config.ts
+++ b/docs-site/docusaurus.config.ts
@@ -113,7 +113,7 @@ const config: Config = {
         {
           title: 'Build',
           items: [
-            { label: 'Workflows', to: '/docs/workflows-overview' },
+            { label: 'Workflows', to: '/docs/surfaces' },
             { label: 'Event Handling', to: '/docs/integration-guide/event-handling' },
             { label: 'Hooks', to: '/docs/hooks' },
           ],
diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index c093a22bd..bc864a453 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -18,30 +18,30 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'Surfaces',
-      link: { type: 'doc', id: 'workflows-overview/workflows-overview' },
+      link: { type: 'doc', id: 'surfaces/surfaces' },
       collapsible: false,
       items: [
         {
           type: 'category',
           label: 'Companies',
-          link: { type: 'doc', id: 'workflows-overview/companies' },
+          link: { type: 'doc', id: 'surfaces/companies' },
           items: [
             {
               type: 'category',
               label: 'Onboard a company',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/company-onboarding/company-onboarding',
+                id: 'surfaces/company-onboarding/company-onboarding',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/company-onboarding/workflow',
+                  id: 'surfaces/company-onboarding/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/company-onboarding/sub-components',
+                  id: 'surfaces/company-onboarding/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -51,17 +51,17 @@ const sidebars: SidebarsConfig = {
               label: 'Information requests',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/information-requests/information-requests',
+                id: 'surfaces/information-requests/information-requests',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/information-requests/workflow',
+                  id: 'surfaces/information-requests/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/information-requests/sub-components',
+                  id: 'surfaces/information-requests/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -71,24 +71,24 @@ const sidebars: SidebarsConfig = {
         {
           type: 'category',
           label: 'Employees',
-          link: { type: 'doc', id: 'workflows-overview/employees' },
+          link: { type: 'doc', id: 'surfaces/employees' },
           items: [
             {
               type: 'category',
               label: 'Onboard an employee',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/employee-onboarding/employee-onboarding',
+                id: 'surfaces/employee-onboarding/employee-onboarding',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/employee-onboarding/workflow',
+                  id: 'surfaces/employee-onboarding/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/employee-onboarding/sub-components',
+                  id: 'surfaces/employee-onboarding/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -98,17 +98,17 @@ const sidebars: SidebarsConfig = {
               label: 'Employee self-onboarding',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/employee-self-onboarding/employee-self-onboarding',
+                id: 'surfaces/employee-self-onboarding/employee-self-onboarding',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/employee-self-onboarding/workflow',
+                  id: 'surfaces/employee-self-onboarding/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/employee-self-onboarding/sub-components',
+                  id: 'surfaces/employee-self-onboarding/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -118,24 +118,24 @@ const sidebars: SidebarsConfig = {
         {
           type: 'category',
           label: 'Contractors',
-          link: { type: 'doc', id: 'workflows-overview/contractors' },
+          link: { type: 'doc', id: 'surfaces/contractors' },
           items: [
             {
               type: 'category',
               label: 'Contractor onboarding',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/contractor-onboarding/contractor-onboarding',
+                id: 'surfaces/contractor-onboarding/contractor-onboarding',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/contractor-onboarding/workflow',
+                  id: 'surfaces/contractor-onboarding/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/contractor-onboarding/sub-components',
+                  id: 'surfaces/contractor-onboarding/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -145,17 +145,17 @@ const sidebars: SidebarsConfig = {
               label: 'Contractor payments',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/contractor-payments/contractor-payments',
+                id: 'surfaces/contractor-payments/contractor-payments',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/contractor-payments/workflow',
+                  id: 'surfaces/contractor-payments/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/contractor-payments/sub-components',
+                  id: 'surfaces/contractor-payments/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -165,24 +165,24 @@ const sidebars: SidebarsConfig = {
         {
           type: 'category',
           label: 'Payroll',
-          link: { type: 'doc', id: 'workflows-overview/payroll' },
+          link: { type: 'doc', id: 'surfaces/payroll' },
           items: [
             {
               type: 'category',
               label: 'Payroll processing',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/run-payroll/run-payroll',
+                id: 'surfaces/run-payroll/run-payroll',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/run-payroll/workflow',
+                  id: 'surfaces/run-payroll/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/run-payroll/sub-components',
+                  id: 'surfaces/run-payroll/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -192,17 +192,17 @@ const sidebars: SidebarsConfig = {
               label: 'Off-cycle payroll',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/off-cycle-payroll/off-cycle-payroll',
+                id: 'surfaces/off-cycle-payroll/off-cycle-payroll',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/off-cycle-payroll/workflow',
+                  id: 'surfaces/off-cycle-payroll/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/off-cycle-payroll/sub-components',
+                  id: 'surfaces/off-cycle-payroll/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -212,17 +212,17 @@ const sidebars: SidebarsConfig = {
               label: 'Dismissal payroll',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/dismissal-payroll/dismissal-payroll',
+                id: 'surfaces/dismissal-payroll/dismissal-payroll',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/dismissal-payroll/workflow',
+                  id: 'surfaces/dismissal-payroll/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/dismissal-payroll/sub-components',
+                  id: 'surfaces/dismissal-payroll/sub-components',
                   label: 'Sub-components',
                 },
               ],
@@ -232,17 +232,17 @@ const sidebars: SidebarsConfig = {
               label: 'Transition payroll',
               link: {
                 type: 'doc',
-                id: 'workflows-overview/transition-payroll/transition-payroll',
+                id: 'surfaces/transition-payroll/transition-payroll',
               },
               items: [
                 {
                   type: 'doc',
-                  id: 'workflows-overview/transition-payroll/workflow',
+                  id: 'surfaces/transition-payroll/workflow',
                   label: 'Workflow',
                 },
                 {
                   type: 'doc',
-                  id: 'workflows-overview/transition-payroll/sub-components',
+                  id: 'surfaces/transition-payroll/sub-components',
                   label: 'Sub-components',
                 },
               ],
diff --git a/docs-site/src/components/SurfacesGrid/index.tsx b/docs-site/src/components/SurfacesGrid/index.tsx
index fb921415a..423fbe569 100644
--- a/docs-site/src/components/SurfacesGrid/index.tsx
+++ b/docs-site/src/components/SurfacesGrid/index.tsx
@@ -12,22 +12,22 @@ const surfaces: Surface[] = [
   {
     title: 'Companies',
     description: 'Stand up a new company and request the information needed to run payroll.',
-    to: '/docs/workflows-overview/companies',
+    to: '/docs/surfaces/companies',
   },
   {
     title: 'Employees',
     description: 'Onboard employees, manage their details, and handle terminations.',
-    to: '/docs/workflows-overview/employees',
+    to: '/docs/surfaces/employees',
   },
   {
     title: 'Contractors',
     description: 'Onboard contractors and pay them on or off cycle.',
-    to: '/docs/workflows-overview/contractors',
+    to: '/docs/surfaces/contractors',
   },
   {
     title: 'Payroll',
     description: 'Run regular, off-cycle, dismissal, and transition payrolls.',
-    to: '/docs/workflows-overview/payroll',
+    to: '/docs/surfaces/payroll',
   },
 ]
 
diff --git a/docs-site/src/pages/index.tsx b/docs-site/src/pages/index.tsx
index 120745a8e..e7728baee 100644
--- a/docs-site/src/pages/index.tsx
+++ b/docs-site/src/pages/index.tsx
@@ -182,7 +182,7 @@ const bigFeatures: BigFeature[] = [
     title: 'Pre-built Workflows',
     description:
       'Complete multi-step flows for employee onboarding, payroll, contractor management, and more — ready to drop into your app.',
-    to: '/docs/workflows-overview',
+    to: '/docs/surfaces',
     Icon: WorkflowIcon,
   },
   {
diff --git a/docs-site/src/theme/NotFound/Content/index.tsx b/docs-site/src/theme/NotFound/Content/index.tsx
index 949bc624b..f098f6095 100644
--- a/docs-site/src/theme/NotFound/Content/index.tsx
+++ b/docs-site/src/theme/NotFound/Content/index.tsx
@@ -37,7 +37,7 @@ export default function NotFoundContent(): ReactNode {
               <Link to="/docs/component-adapter">Component Adapter</Link>
             </li>
             <li>
-              <Link to="/docs/workflows-overview">Workflows</Link>
+              <Link to="/docs/surfaces">Workflows</Link>
             </li>
           </ul>
         </div>
diff --git a/docs/build-methods/workflows.md b/docs/build-methods/workflows.md
index a2b19caaa..e2f335961 100644
--- a/docs/build-methods/workflows.md
+++ b/docs/build-methods/workflows.md
@@ -36,4 +36,4 @@ function EmployeeOnboardingPage({ companyId }) {
 }
 ```
 
-Each surface in the SDK ships a workflow. See the [Surfaces section](../workflows-overview/workflows-overview.mdx) for the full list, with the props and events each one accepts.
+Each surface in the SDK ships a workflow. See the [Surfaces section](../surfaces/surfaces.mdx) for the full list, with the props and events each one accepts.
diff --git a/docs/integration-guide/composition.md b/docs/integration-guide/composition.md
index afbc58bdf..bf231400e 100644
--- a/docs/integration-guide/composition.md
+++ b/docs/integration-guide/composition.md
@@ -56,6 +56,6 @@ function MyApp({ employeeId, startDate }) {
 
 ![](https://files.readme.io/6fb4afca5b75cc9aac151e2ed873aa988b7ffc35dbcb3566b874d7cd8d323e64-image.png)
 
-Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../workflows-overview/employee-onboarding/sub-components.md)).
+Each step of the employee onboarding flow can be imported like this in isolation and used directly as needed. (For a comprehensive list of employee onboarding components available [see the Employee Onboarding documentation here](../surfaces/employee-onboarding/sub-components.md)).
 
 Because each step is available for direct use in isolation, it is also possible to rearrange steps, compose them with your own content, or [integrate them with your routing infrastructure as outlined here](./routing.md). For example, we could place this compensation form inside of an existing page inline with our own components, or we could use this as a step in a different flow entirely.
diff --git a/docs/workflows-overview/companies.mdx b/docs/surfaces/companies.mdx
similarity index 89%
rename from docs/workflows-overview/companies.mdx
rename to docs/surfaces/companies.mdx
index 930168835..889d2c672 100644
--- a/docs/workflows-overview/companies.mdx
+++ b/docs/surfaces/companies.mdx
@@ -15,13 +15,13 @@ The Companies surface covers everything required to onboard a new company to Gus
       title: 'Company onboarding',
       description:
         'Walks a company through everything needed before they can run payroll: industry, signatory assignment, locations, federal and state taxes, pay schedule, bank account, and document signing.',
-      to: '/docs/workflows-overview/company-onboarding/',
+      to: '/docs/surfaces/company-onboarding/',
     },
     {
       title: 'Information requests',
       description:
         'Standalone surface for outstanding information requests Gusto has issued for a company — for example a missing tax document or identity verification artifact — and lets the user respond to them.',
-      to: '/docs/workflows-overview/information-requests/',
+      to: '/docs/surfaces/information-requests/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/company-onboarding/company-onboarding.mdx b/docs/surfaces/company-onboarding/company-onboarding.mdx
similarity index 100%
rename from docs/workflows-overview/company-onboarding/company-onboarding.mdx
rename to docs/surfaces/company-onboarding/company-onboarding.mdx
diff --git a/docs/workflows-overview/company-onboarding/sub-components.md b/docs/surfaces/company-onboarding/sub-components.md
similarity index 100%
rename from docs/workflows-overview/company-onboarding/sub-components.md
rename to docs/surfaces/company-onboarding/sub-components.md
diff --git a/docs/workflows-overview/company-onboarding/workflow.md b/docs/surfaces/company-onboarding/workflow.md
similarity index 100%
rename from docs/workflows-overview/company-onboarding/workflow.md
rename to docs/surfaces/company-onboarding/workflow.md
diff --git a/docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx b/docs/surfaces/contractor-onboarding/contractor-onboarding.mdx
similarity index 100%
rename from docs/workflows-overview/contractor-onboarding/contractor-onboarding.mdx
rename to docs/surfaces/contractor-onboarding/contractor-onboarding.mdx
diff --git a/docs/workflows-overview/contractor-onboarding/sub-components.md b/docs/surfaces/contractor-onboarding/sub-components.md
similarity index 100%
rename from docs/workflows-overview/contractor-onboarding/sub-components.md
rename to docs/surfaces/contractor-onboarding/sub-components.md
diff --git a/docs/workflows-overview/contractor-onboarding/workflow.md b/docs/surfaces/contractor-onboarding/workflow.md
similarity index 100%
rename from docs/workflows-overview/contractor-onboarding/workflow.md
rename to docs/surfaces/contractor-onboarding/workflow.md
diff --git a/docs/workflows-overview/contractor-payments/contractor-payments.mdx b/docs/surfaces/contractor-payments/contractor-payments.mdx
similarity index 100%
rename from docs/workflows-overview/contractor-payments/contractor-payments.mdx
rename to docs/surfaces/contractor-payments/contractor-payments.mdx
diff --git a/docs/workflows-overview/contractor-payments/sub-components.md b/docs/surfaces/contractor-payments/sub-components.md
similarity index 100%
rename from docs/workflows-overview/contractor-payments/sub-components.md
rename to docs/surfaces/contractor-payments/sub-components.md
diff --git a/docs/workflows-overview/contractor-payments/workflow.md b/docs/surfaces/contractor-payments/workflow.md
similarity index 100%
rename from docs/workflows-overview/contractor-payments/workflow.md
rename to docs/surfaces/contractor-payments/workflow.md
diff --git a/docs/workflows-overview/contractors.mdx b/docs/surfaces/contractors.mdx
similarity index 88%
rename from docs/workflows-overview/contractors.mdx
rename to docs/surfaces/contractors.mdx
index a05ac0ebd..cb822f55e 100644
--- a/docs/workflows-overview/contractors.mdx
+++ b/docs/surfaces/contractors.mdx
@@ -15,13 +15,13 @@ The Contractors surface covers everything required to bring a contractor onto a
       title: 'Contractor onboarding',
       description:
         'Walks a contractor through everything needed to be set up for payment — profile, address, payment method, new hire reporting, and submission.',
-      to: '/docs/workflows-overview/contractor-onboarding/',
+      to: '/docs/surfaces/contractor-onboarding/',
     },
     {
       title: 'Contractor payments',
       description:
         'Create, manage, and view contractor payment groups — payment list, creation, history, summaries, and individual payment statements.',
-      to: '/docs/workflows-overview/contractor-payments/',
+      to: '/docs/surfaces/contractor-payments/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx b/docs/surfaces/dismissal-payroll/dismissal-payroll.mdx
similarity index 100%
rename from docs/workflows-overview/dismissal-payroll/dismissal-payroll.mdx
rename to docs/surfaces/dismissal-payroll/dismissal-payroll.mdx
diff --git a/docs/workflows-overview/dismissal-payroll/sub-components.md b/docs/surfaces/dismissal-payroll/sub-components.md
similarity index 100%
rename from docs/workflows-overview/dismissal-payroll/sub-components.md
rename to docs/surfaces/dismissal-payroll/sub-components.md
diff --git a/docs/workflows-overview/dismissal-payroll/workflow.md b/docs/surfaces/dismissal-payroll/workflow.md
similarity index 100%
rename from docs/workflows-overview/dismissal-payroll/workflow.md
rename to docs/surfaces/dismissal-payroll/workflow.md
diff --git a/docs/workflows-overview/employee-dashboard.md b/docs/surfaces/employee-dashboard.md
similarity index 100%
rename from docs/workflows-overview/employee-dashboard.md
rename to docs/surfaces/employee-dashboard.md
diff --git a/docs/workflows-overview/employee-management/employee-management.md b/docs/surfaces/employee-management/employee-management.md
similarity index 100%
rename from docs/workflows-overview/employee-management/employee-management.md
rename to docs/surfaces/employee-management/employee-management.md
diff --git a/docs/workflows-overview/employee-onboarding/employee-onboarding.mdx b/docs/surfaces/employee-onboarding/employee-onboarding.mdx
similarity index 100%
rename from docs/workflows-overview/employee-onboarding/employee-onboarding.mdx
rename to docs/surfaces/employee-onboarding/employee-onboarding.mdx
diff --git a/docs/workflows-overview/employee-onboarding/sub-components.md b/docs/surfaces/employee-onboarding/sub-components.md
similarity index 100%
rename from docs/workflows-overview/employee-onboarding/sub-components.md
rename to docs/surfaces/employee-onboarding/sub-components.md
diff --git a/docs/workflows-overview/employee-onboarding/workflow.md b/docs/surfaces/employee-onboarding/workflow.md
similarity index 100%
rename from docs/workflows-overview/employee-onboarding/workflow.md
rename to docs/surfaces/employee-onboarding/workflow.md
diff --git a/docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx b/docs/surfaces/employee-self-onboarding/employee-self-onboarding.mdx
similarity index 100%
rename from docs/workflows-overview/employee-self-onboarding/employee-self-onboarding.mdx
rename to docs/surfaces/employee-self-onboarding/employee-self-onboarding.mdx
diff --git a/docs/workflows-overview/employee-self-onboarding/sub-components.md b/docs/surfaces/employee-self-onboarding/sub-components.md
similarity index 100%
rename from docs/workflows-overview/employee-self-onboarding/sub-components.md
rename to docs/surfaces/employee-self-onboarding/sub-components.md
diff --git a/docs/workflows-overview/employee-self-onboarding/workflow.md b/docs/surfaces/employee-self-onboarding/workflow.md
similarity index 100%
rename from docs/workflows-overview/employee-self-onboarding/workflow.md
rename to docs/surfaces/employee-self-onboarding/workflow.md
diff --git a/docs/workflows-overview/employee-termination.md b/docs/surfaces/employee-termination.md
similarity index 100%
rename from docs/workflows-overview/employee-termination.md
rename to docs/surfaces/employee-termination.md
diff --git a/docs/workflows-overview/employees.mdx b/docs/surfaces/employees.mdx
similarity index 89%
rename from docs/workflows-overview/employees.mdx
rename to docs/surfaces/employees.mdx
index 49eb1ee0d..3c217a296 100644
--- a/docs/workflows-overview/employees.mdx
+++ b/docs/surfaces/employees.mdx
@@ -15,13 +15,13 @@ The Employees surface covers everything required to onboard new employees, wheth
       title: 'Employee onboarding',
       description:
         'Admin-driven workflow that collects every piece of information needed to add an employee to payroll: profile, compensation, federal and state taxes, payment method, deductions, and optional I-9 document configuration.',
-      to: '/docs/workflows-overview/employee-onboarding/',
+      to: '/docs/surfaces/employee-onboarding/',
     },
     {
       title: 'Employee self-onboarding',
       description:
         'Employee-driven workflow that hands the employee responsibility for submitting their own profile, tax, payment, and document-signing information after the admin invites them.',
-      to: '/docs/workflows-overview/employee-self-onboarding/',
+      to: '/docs/surfaces/employee-self-onboarding/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/information-requests/information-requests.mdx b/docs/surfaces/information-requests/information-requests.mdx
similarity index 100%
rename from docs/workflows-overview/information-requests/information-requests.mdx
rename to docs/surfaces/information-requests/information-requests.mdx
diff --git a/docs/workflows-overview/information-requests/sub-components.md b/docs/surfaces/information-requests/sub-components.md
similarity index 100%
rename from docs/workflows-overview/information-requests/sub-components.md
rename to docs/surfaces/information-requests/sub-components.md
diff --git a/docs/workflows-overview/information-requests/workflow.md b/docs/surfaces/information-requests/workflow.md
similarity index 100%
rename from docs/workflows-overview/information-requests/workflow.md
rename to docs/surfaces/information-requests/workflow.md
diff --git a/docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx b/docs/surfaces/off-cycle-payroll/off-cycle-payroll.mdx
similarity index 100%
rename from docs/workflows-overview/off-cycle-payroll/off-cycle-payroll.mdx
rename to docs/surfaces/off-cycle-payroll/off-cycle-payroll.mdx
diff --git a/docs/workflows-overview/off-cycle-payroll/sub-components.md b/docs/surfaces/off-cycle-payroll/sub-components.md
similarity index 100%
rename from docs/workflows-overview/off-cycle-payroll/sub-components.md
rename to docs/surfaces/off-cycle-payroll/sub-components.md
diff --git a/docs/workflows-overview/off-cycle-payroll/workflow.md b/docs/surfaces/off-cycle-payroll/workflow.md
similarity index 100%
rename from docs/workflows-overview/off-cycle-payroll/workflow.md
rename to docs/surfaces/off-cycle-payroll/workflow.md
diff --git a/docs/workflows-overview/payroll.mdx b/docs/surfaces/payroll.mdx
similarity index 86%
rename from docs/workflows-overview/payroll.mdx
rename to docs/surfaces/payroll.mdx
index e594accda..c7bb1d13d 100644
--- a/docs/workflows-overview/payroll.mdx
+++ b/docs/surfaces/payroll.mdx
@@ -15,25 +15,25 @@ The Payroll surface covers every way a company runs payroll: the regular pay-sch
       title: 'Payroll processing',
       description:
         'The main regular payroll flow — select a payroll, configure employee compensation, review, confirm wire transfers, and submit.',
-      to: '/docs/workflows-overview/run-payroll/',
+      to: '/docs/surfaces/run-payroll/',
     },
     {
       title: 'Off-cycle payroll',
       description:
         'Run a payroll outside the regular pay schedule — bonus or correction — then transition into the standard execution experience.',
-      to: '/docs/workflows-overview/off-cycle-payroll/',
+      to: '/docs/surfaces/off-cycle-payroll/',
     },
     {
       title: 'Dismissal payroll',
       description:
         'Guided final-paycheck flow for a terminated employee. Surfaces unprocessed termination pay periods and hands off to the standard payroll execution.',
-      to: '/docs/workflows-overview/dismissal-payroll/',
+      to: '/docs/surfaces/dismissal-payroll/',
     },
     {
       title: 'Transition payroll',
       description:
         'Run payrolls that cover gaps between old and new pay schedules. Includes an alert surfaced inside the payroll landing for unprocessed transition periods.',
-      to: '/docs/workflows-overview/transition-payroll/',
+      to: '/docs/surfaces/transition-payroll/',
     },
   ]}
 />
diff --git a/docs/workflows-overview/run-payroll/run-payroll.mdx b/docs/surfaces/run-payroll/run-payroll.mdx
similarity index 100%
rename from docs/workflows-overview/run-payroll/run-payroll.mdx
rename to docs/surfaces/run-payroll/run-payroll.mdx
diff --git a/docs/workflows-overview/run-payroll/sub-components.md b/docs/surfaces/run-payroll/sub-components.md
similarity index 100%
rename from docs/workflows-overview/run-payroll/sub-components.md
rename to docs/surfaces/run-payroll/sub-components.md
diff --git a/docs/workflows-overview/run-payroll/workflow.md b/docs/surfaces/run-payroll/workflow.md
similarity index 100%
rename from docs/workflows-overview/run-payroll/workflow.md
rename to docs/surfaces/run-payroll/workflow.md
diff --git a/docs/workflows-overview/workflows-overview.mdx b/docs/surfaces/surfaces.mdx
similarity index 100%
rename from docs/workflows-overview/workflows-overview.mdx
rename to docs/surfaces/surfaces.mdx
diff --git a/docs/workflows-overview/time-off.md b/docs/surfaces/time-off.md
similarity index 100%
rename from docs/workflows-overview/time-off.md
rename to docs/surfaces/time-off.md
diff --git a/docs/workflows-overview/transition-payroll/sub-components.md b/docs/surfaces/transition-payroll/sub-components.md
similarity index 100%
rename from docs/workflows-overview/transition-payroll/sub-components.md
rename to docs/surfaces/transition-payroll/sub-components.md
diff --git a/docs/workflows-overview/transition-payroll/transition-payroll.mdx b/docs/surfaces/transition-payroll/transition-payroll.mdx
similarity index 100%
rename from docs/workflows-overview/transition-payroll/transition-payroll.mdx
rename to docs/surfaces/transition-payroll/transition-payroll.mdx
diff --git a/docs/workflows-overview/transition-payroll/workflow.md b/docs/surfaces/transition-payroll/workflow.md
similarity index 100%
rename from docs/workflows-overview/transition-payroll/workflow.md
rename to docs/surfaces/transition-payroll/workflow.md

From 7115fb5470118c8d14e6f76191ae50352b27f875 Mon Sep 17 00:00:00 2001
From: Aaron Lee <aaron.lee@gusto.com>
Date: Fri, 12 Jun 2026 15:54:52 -0400
Subject: [PATCH 10/10] docs: add Customize section, group hooks sidebar, tidy
 hooks landing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New Customize landing page (docs/customize/customize.mdx) grouping
  Theming and Component Adapter behind a single "Customize" sidebar
  category, with a 2-up LinkCardGrid on the landing.
- Hooks sidebar: replace the flat 3-hook list with two visually
  separated label groups (Company / Employee) using type: 'html'
  items styled by a new .sidebar-group-label rule (spacing, no
  divider), and expand the listing to every documented hook.
- Hooks landing: collapse the redundant Reference column — the Hook
  column itself is now the link to the reference page.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs-site/sidebars.ts        | 96 ++++++++++++++++++++++--------------
 docs-site/src/css/custom.css | 20 ++++++++
 docs/customize/customize.mdx | 27 ++++++++++
 docs/hooks/hooks.md          | 38 +++++++-------
 4 files changed, 125 insertions(+), 56 deletions(-)
 create mode 100644 docs/customize/customize.mdx

diff --git a/docs-site/sidebars.ts b/docs-site/sidebars.ts
index bc864a453..583a3879c 100644
--- a/docs-site/sidebars.ts
+++ b/docs-site/sidebars.ts
@@ -15,6 +15,25 @@ const sidebars: SidebarsConfig = {
       link: { type: 'doc', id: 'build-methods/build-methods' },
       items: ['build-methods/workflows', 'build-methods/sub-components', 'build-methods/hooks'],
     },
+    {
+      type: 'category',
+      label: 'Integration Guide',
+      link: { type: 'doc', id: 'integration-guide/integration-guide' },
+      items: [
+        'integration-guide/versioning',
+        'integration-guide/event-handling',
+        'integration-guide/event-types',
+        'integration-guide/request-interceptors',
+        'integration-guide/customizing-sdk-ui',
+        'integration-guide/composition',
+        'integration-guide/providing-your-own-data',
+        'integration-guide/translation',
+        'integration-guide/routing',
+        'integration-guide/error-handling',
+        'integration-guide/observability',
+        'integration-guide/observability-examples',
+      ],
+    },
     {
       type: 'category',
       label: 'Surfaces',
@@ -253,51 +272,54 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Component Adapter',
-      link: { type: 'doc', id: 'component-adapter/component-adapter' },
-      items: [
-        'component-adapter/how-the-component-adapter-works',
-        'component-adapter/setting-up-your-component-adapter',
-        'component-adapter/component-adapter-types',
-        'component-adapter/component-inventory',
-        'component-adapter/component-adapter-faq',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Theming',
-      link: { type: 'doc', id: 'theming/theming' },
-      items: ['theming/theme-variables', 'theming/theming-guide'],
-    },
-    {
-      type: 'category',
-      label: 'Integration Guide',
-      link: { type: 'doc', id: 'integration-guide/integration-guide' },
+      label: 'Hooks',
+      link: { type: 'doc', id: 'hooks/hooks' },
       items: [
-        'integration-guide/versioning',
-        'integration-guide/event-handling',
-        'integration-guide/event-types',
-        'integration-guide/request-interceptors',
-        'integration-guide/customizing-sdk-ui',
-        'integration-guide/composition',
-        'integration-guide/providing-your-own-data',
-        'integration-guide/translation',
-        'integration-guide/routing',
-        'integration-guide/error-handling',
-        'integration-guide/observability',
-        'integration-guide/observability-examples',
+        { type: 'html', value: 'Company hooks', className: 'sidebar-group-label' },
+        'hooks/usePayScheduleForm',
+        'hooks/useSignCompanyForm',
+        { type: 'html', value: 'Employee hooks', className: 'sidebar-group-label' },
+        'hooks/useEmployeeList',
+        'hooks/useEmployeeDetailsForm',
+        'hooks/useJobForm',
+        'hooks/useCompensationForm',
+        'hooks/useWorkAddressForm',
+        'hooks/useFederalTaxesForm',
+        'hooks/useEmployeeStateTaxesForm',
+        'hooks/useSignEmployeeForm',
+        'hooks/useBankForm',
+        'hooks/usePaymentMethodForm',
+        'hooks/useSplitPaymentsForm',
+        'hooks/useDeductionForm',
+        'hooks/useChildSupportGarnishmentForm',
       ],
     },
     {
       type: 'category',
-      label: 'Hooks (Experimental)',
-      link: { type: 'doc', id: 'hooks/hooks' },
+      label: 'Customize',
+      link: { type: 'doc', id: 'customize/customize' },
       items: [
-        'hooks/useEmployeeDetailsForm',
-        'hooks/useCompensationForm',
-        'hooks/useWorkAddressForm',
+        {
+          type: 'category',
+          label: 'Theming',
+          link: { type: 'doc', id: 'theming/theming' },
+          items: ['theming/theme-variables', 'theming/theming-guide'],
+        },
+        {
+          type: 'category',
+          label: 'Component Adapter',
+          link: { type: 'doc', id: 'component-adapter/component-adapter' },
+          items: [
+            'component-adapter/how-the-component-adapter-works',
+            'component-adapter/setting-up-your-component-adapter',
+            'component-adapter/component-adapter-types',
+            'component-adapter/component-inventory',
+            'component-adapter/component-adapter-faq',
+          ],
+        },
       ],
     },
+
     {
       type: 'category',
       label: 'API Reference',
diff --git a/docs-site/src/css/custom.css b/docs-site/src/css/custom.css
index 68b010c6d..adc731faa 100644
--- a/docs-site/src/css/custom.css
+++ b/docs-site/src/css/custom.css
@@ -781,6 +781,26 @@ nav.theme-doc-breadcrumbs:not(:has(.breadcrumbs__item + .breadcrumbs__item)) {
   --ifm-alert-border-color: rgba(250, 56, 56, 0.3);
 }
 
+/* ── Sidebar group labels (non-interactive section dividers) ── */
+
+.sidebar-group-label {
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--ifm-color-emphasis-600);
+  padding: 0.25rem 0.75rem 0.75rem;
+  margin-top: 2rem;
+}
+
+.sidebar-group-label:first-child {
+  margin-top: 0;
+}
+
+[data-theme='dark'] .sidebar-group-label {
+  color: rgba(255, 255, 255, 0.5);
+}
+
 /* ── Sidebar scrollbars ── */
 
 .theme-doc-sidebar-container .menu,
diff --git a/docs/customize/customize.mdx b/docs/customize/customize.mdx
new file mode 100644
index 000000000..c867649c5
--- /dev/null
+++ b/docs/customize/customize.mdx
@@ -0,0 +1,27 @@
+---
+title: Customize
+description: Tailor the SDK's visual appearance to your product — start with theming, then reach for the component adapter when you need to swap in your own primitives.
+order: 5
+---
+
+import LinkCardGrid from '@site/src/components/LinkCardGrid'
+
+The SDK ships with sensible visual defaults, but every surface — colors, typography, shadows, and the primitive components themselves — is customizable. Start with **theming** for the broadest set of changes, and reach for the **component adapter** when you need to replace SDK primitives with components from your own design system.
+
+<LinkCardGrid
+  columns={2}
+  items={[
+    {
+      title: 'Theming',
+      description:
+        'Override design tokens — colors, typography, shadows, and other variables — to globally restyle the SDK to match your application.',
+      to: '/docs/theming/',
+    },
+    {
+      title: 'Component Adapter',
+      description:
+        "Replace the SDK's default UI primitives with components from your own design system while keeping all SDK business logic intact.",
+      to: '/docs/component-adapter/',
+    },
+  ]}
+/>
diff --git a/docs/hooks/hooks.md b/docs/hooks/hooks.md
index d10003168..1bd979b69 100644
--- a/docs/hooks/hooks.md
+++ b/docs/hooks/hooks.md
@@ -12,30 +12,30 @@ Hooks let you own the layout while the SDK manages data fetching, validation, su
 
 ## Available Form Hooks
 
-| Hook                             | Description                                                                                        | Reference                                                             |
-| -------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `useEmployeeDetailsForm`         | Create or update employee profile fields (name, email, SSN, date of birth, self-onboarding)        | [useEmployeeDetailsForm](./useEmployeeDetailsForm.md)                 |
-| `useJobForm`                     | Create or update an employee's job (title, hire date, S-Corp 2% shareholder, WA workers' comp)     | [useJobForm](./useJobForm.md)                                         |
-| `useCompensationForm`            | Create or update a compensation row on a job (FLSA status, pay rate, payment unit, effective date) | [useCompensationForm](./useCompensationForm.md)                       |
-| `useWorkAddressForm`             | Create or update an employee's work address (company location select, effective date)              | [useWorkAddressForm](./useWorkAddressForm.md)                         |
-| `useFederalTaxesForm`            | Update an employee's federal tax (W-4) withholding information                                     | [useFederalTaxesForm](./useFederalTaxesForm.md)                       |
-| `useEmployeeStateTaxesForm`      | Update an employee's state tax withholding answers (dynamic, per-state question groups)            | [useEmployeeStateTaxesForm](./useEmployeeStateTaxesForm.md)           |
-| `usePayScheduleForm`             | Create or update a company pay schedule (frequency, pay dates, pay period calendar preview)        | [usePayScheduleForm](./usePayScheduleForm.md)                         |
-| `useSignCompanyForm`             | Sign a company form (PDF viewer, typed signature, confirmation checkbox)                           | [useSignCompanyForm](./useSignCompanyForm.md)                         |
-| `useSignEmployeeForm`            | Sign an employee form (signature, confirmation, I-9 preparer/translator sections)                  | [useSignEmployeeForm](./useSignEmployeeForm.md)                       |
-| `useBankForm`                    | Create a bank account for an employee (nickname, routing/account number, account type)             | [useBankForm](./useBankForm.md)                                       |
-| `usePaymentMethodForm`           | Switch an employee's payment method between Direct Deposit and Check                               | [usePaymentMethodForm](./usePaymentMethodForm.md)                     |
-| `useSplitPaymentsForm`           | Split a paycheck across multiple bank accounts (Percentage or Fixed amount, with reordering)       | [useSplitPaymentsForm](./useSplitPaymentsForm.md)                     |
-| `useDeductionForm`               | Create or update a non-child-support deduction (court-ordered garnishment or post-tax custom)      | [useDeductionForm](./useDeductionForm.md)                             |
-| `useChildSupportGarnishmentForm` | Create or update a child-support garnishment (agency-keyed required attributes, county selection)  | [useChildSupportGarnishmentForm](./useChildSupportGarnishmentForm.md) |
+| Hook                                                                  | Description                                                                                        |
+| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [useEmployeeDetailsForm](./useEmployeeDetailsForm.md)                 | Create or update employee profile fields (name, email, SSN, date of birth, self-onboarding)        |
+| [useJobForm](./useJobForm.md)                                         | Create or update an employee's job (title, hire date, S-Corp 2% shareholder, WA workers' comp)     |
+| [useCompensationForm](./useCompensationForm.md)                       | Create or update a compensation row on a job (FLSA status, pay rate, payment unit, effective date) |
+| [useWorkAddressForm](./useWorkAddressForm.md)                         | Create or update an employee's work address (company location select, effective date)              |
+| [useFederalTaxesForm](./useFederalTaxesForm.md)                       | Update an employee's federal tax (W-4) withholding information                                     |
+| [useEmployeeStateTaxesForm](./useEmployeeStateTaxesForm.md)           | Update an employee's state tax withholding answers (dynamic, per-state question groups)            |
+| [usePayScheduleForm](./usePayScheduleForm.md)                         | Create or update a company pay schedule (frequency, pay dates, pay period calendar preview)        |
+| [useSignCompanyForm](./useSignCompanyForm.md)                         | Sign a company form (PDF viewer, typed signature, confirmation checkbox)                           |
+| [useSignEmployeeForm](./useSignEmployeeForm.md)                       | Sign an employee form (signature, confirmation, I-9 preparer/translator sections)                  |
+| [useBankForm](./useBankForm.md)                                       | Create a bank account for an employee (nickname, routing/account number, account type)             |
+| [usePaymentMethodForm](./usePaymentMethodForm.md)                     | Switch an employee's payment method between Direct Deposit and Check                               |
+| [useSplitPaymentsForm](./useSplitPaymentsForm.md)                     | Split a paycheck across multiple bank accounts (Percentage or Fixed amount, with reordering)       |
+| [useDeductionForm](./useDeductionForm.md)                             | Create or update a non-child-support deduction (court-ordered garnishment or post-tax custom)      |
+| [useChildSupportGarnishmentForm](./useChildSupportGarnishmentForm.md) | Create or update a child-support garnishment (agency-keyed required attributes, county selection)  |
 
 ## Available Data Hooks
 
 Data hooks fetch and decorate server data and expose the actions valid for it, leaving presentation to you. They follow the same `isLoading` discriminated union and `errorHandling` contract as the rest of the SDK hooks, returning domain `data`, `status`, and `actions`.
 
-| Hook              | Description                                                                                      | Reference                               |
-| ----------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- |
-| `useEmployeeList` | Paginated list of a company's employees, each decorated with its allowed actions and primary job | [useEmployeeList](./useEmployeeList.md) |
+| Hook                                    | Description                                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [useEmployeeList](./useEmployeeList.md) | Paginated list of a company's employees, each decorated with its allowed actions and primary job |
 
 ---