Docs And Storybook Release Deploy Runbook

This runbook coordinates docs and Storybook deployment without merging their artifacts.

Pre-Deploy

Run from the workspace root:

pnpm verify:docs-site
pnpm verify:ui-storybook-build
pnpm verify:docs-dx
pnpm security:supply-chain

For package releases, pnpm release:gate remains the full release gate. Docs deploys can use pnpm verify:docs-site when only the Docusaurus site changes.

Deploy Order

1. Deploy docs to the maya-docs Pages project.
2. Deploy Storybook to the maya-storybook Pages project.
3. Run smoke checks for both domains.
4. Update Linear if either deploy fails or requires rollback.

Docs and Storybook may deploy independently. A Storybook failure does not automatically roll back docs unless the release owner chooses a combined release decision.

Failure Handling

Failure	First action
Docusaurus build fails	Run pnpm verify:docs-site locally and inspect generated docs
Docs broken link fails	Fix canonical .docs source or sidebars, then rebuild
Storybook build fails	Run pnpm verify:ui-storybook-build and inspect the Storybook package
Domain serves old content	Check Cloudflare Pages latest deployment and rollback/promote state
Headers missing	Confirm apps/docs/build/_headers and .tmp/storybook/assistant-ui/_headers exist; source files are apps/docs/static/_headers and projects/claude-ui/storybook-static-headers

Release Notes

Docs deploy notes should name:

• docs commit SHA
• Pages project
• production deployment URL
• smoke-check result
• rollback target if applicable

Storybook deploy notes should name:

• Storybook commit SHA
• Pages project
• production deployment URL
• Storybook index.json smoke result
• rollback target if applicable