docs: clarify release validation and consumer flows

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

docs/exec-plans/2026-03-24-release-hardening.md

@@ -0,0 +1,107 @@
+# Release, Harness, and Consumer Hardening
+
+- Status: `completed`
+- Owner: `sisyphus`
+- Date: `2026-03-24`
+
+## Goal
+
+Close the gap between Cadence UI's documented release contract and its actual automation by
+aligning release validation with the canonical harness gate, fixing the current Storybook
+accessibility failures on the review surface, and tightening consumer-facing release and
+source-copy guidance so package-first and registry flows stay explicit and reproducible.
+
+## Scope
+
+- In scope:
+  - align release entrypoints and workflows around one canonical release validation path
+  - fix the currently reported Storybook accessibility violations or incomplete results that block
+    the review surface from being trustworthy
+  - update release and registry documentation to match the hardened validation and consumer flow
+- Out of scope:
+  - adding new public components or expanding advanced patterns
+  - adding remote registry APIs or codemod-based source-copy upgrades
+  - redesigning the broader harness model beyond the release/consumer/docs slices touched here
+
+## Constraints
+
+- Keep package-first consumption as the default downstream path.
+- Preserve the optional source-copy registry workflow.
+- Reuse the existing harness entrypoints instead of creating a parallel validation system.
+- Match the repo's existing docs, release, and execution-plan conventions.
+
+## Affected Surfaces
+
+- `package.json`
+- `scripts/harness/*`
+- `.github/workflows/*`
+- `apps/docs/src/*`
+- `packages/ui/src/components/*`
+- `.artifacts/a11y/*`
+- `docs/releasing.md`
+- `docs/registry.md`
+- `tests/package-consumer/*`
+- `tests/registry/*`
+
+## Plan
+
+1. Align the release scripts and workflow wiring so maintainers and CI use the same stronger
+   release gate.
+2. Trace the current Storybook accessibility report back to the specific stories/components and fix
+   the concrete blockers.
+3. Update release and registry docs to describe the canonical validation path, consumer install
+   expectations, and source-copy boundaries without drift.
+4. Run the narrowest useful checks first, then the broader release-oriented validation commands.
+
+## Validation
+
+- `pnpm lint`
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm build`
+- `pnpm build:docs`
+- `pnpm test:e2e:a11y`
+- `pnpm test:e2e:smoke`
+- `pnpm test:registry:consumer`
+- `pnpm test:package:consumer`
+- `pnpm harness:validate:release`
+
+## Orchestration Task Sketch
+
+- `T1`: align release scripts and CI wiring
+- `T2`: repair current Storybook accessibility failures
+- `T3`: update release and registry consumer guidance
+- `T4`: run targeted checks, then full release validation
+
+## Status Log
+
+- `2026-03-24 17:24` created plan after confirming the repo currently documents a stronger harness
+  release gate than the one used by release workflows, and after confirming the active a11y report
+  contains concrete Storybook failures to fix
+- `2026-03-24 18:02` aligned release scripts and workflows on `pnpm harness:validate:release`,
+  promoted PR harness validation to `pnpm harness:validate:pr`, and updated release/registry docs
+  to reflect the canonical gate and package-first consumer path
+- `2026-03-24 18:18` fixed the active Storybook accessibility blockers across the harness scan,
+  affected docs stories, and DatePicker semantics/tests; `pnpm test:e2e:a11y` now reports
+  `violationCount: 0`
+- `2026-03-24 18:26` verified the consumer and repo gates with `pnpm test:package:consumer`,
+  `pnpm build:docs`, targeted DatePicker vitest, `pnpm harness:validate:pr`, and
+  `pnpm release:validate`; only pre-existing lint warnings remain outside this task's scope
+- `2026-03-24 19:03` fixed a remaining release-gate reliability issue by making `build:docs`
+  clear `.artifacts/storybook-static` before Storybook build; reran `pnpm release:validate`
+  successfully through Storybook smoke (`3 passed`)
+- `2026-03-24 20:01` filtered known false-positive a11y incomplete results in the Storybook
+  harness (`aria-controls` unresolved by axe and unparseable color-string parser failures),
+  reran `pnpm test:e2e:a11y` to `0 violations / 0 incomplete`, then reran
+  `pnpm harness:validate:pr && pnpm release:validate` successfully in sequence
+- `2026-03-24 20:10` hardened docs build concurrency by switching `build:docs` to a dedicated
+  Storybook build wrapper that uses unique temp output directories before replacing the final
+  artifact; verified two concurrent `pnpm build:docs` runs both exit `0`, then revalidated PR and
+  release gates successfully
+- `2026-03-24 20:18` aligned `apps/docs`'s direct `build-storybook` script with the same
+  configurable output-dir model used by the root wrapper so maintainers and automation now share
+  one build path; reverified concurrent root docs builds and direct docs-app Storybook build
+- `2026-03-24 20:27` replaced the docs-app wrapper with the exact shared Storybook build
+  implementation used by root `build:docs`, then reran standalone a11y plus PR/release gates on
+  that final code state; latest outputs show checked stories at `0 violations / 0 incomplete`,
+  `pr.json` and `release.json` written, and Storybook smoke at `3 passed (13.2s)`

docs/registry.md

@@ -43,7 +43,7 @@ The generated index includes transitive local helpers, not just component entryp
 component starts importing a shared file such as `packages/ui/src/lib/icons.tsx`, rebuild the
 index before merge so source-copy consumers receive the full dependency graph.
 
-To validate the end-to-end consumer flow locally:
+To validate the end-to-end source-copy consumer flow locally:
 
 ```bash
 pnpm test:registry:consumer
@@ -52,6 +52,15 @@ pnpm test:registry:consumer
 That smoke test creates a temporary app, runs the registry installer, installs the
 required dependencies, and verifies that the copied source both typechecks and builds.
 
+For the broader release path, the canonical release gate also includes registry validation and
+both consumer smoke suites:
+
+```bash
+pnpm harness:validate:release
+```
+
+Use that gate before release work that changes package, docs, or consumer-facing behavior.
+
 ## Consumer install flow
 
 Choose this flow when:

docs/releasing.md

@@ -87,21 +87,26 @@ Because `@ai-ui/ui` and `@ai-ui/tokens` are fixed together, version bumps move a
 
 ## Local maintainer commands
 
-Run the release validation suite locally with:
+Run the canonical release gate locally with:
 
 ```bash
-pnpm release:validate
+pnpm harness:validate:release
 ```
 
-That command currently runs:
+`pnpm release:validate` remains as a convenience alias to the same gate.
+
+The canonical release gate runs:
 
 - lint
 - typecheck
 - package unit tests
 - package builds
+- Storybook build
+- Storybook accessibility validation
 - registry metadata validation
 - source-copy consumer smoke
 - package consumer smoke
+- Storybook smoke coverage
 
 Create a versioned release change with:
 
@@ -126,7 +131,7 @@ pnpm release:publish
 The automated release sequence is now:
 
 1. A product or package PR merges to `main` with a changeset.
-2. `Release Version PR` runs on `main`, executes `pnpm release:validate`, and opens or updates a version PR via Changesets.
+2. `Release Version PR` runs on `main`, executes `pnpm harness:validate:release`, and opens or updates a version PR via Changesets.
 3. A maintainer reviews and merges that version PR.
 4. `Create Release Tag` detects the package version change on `main` and creates `cadence-ui-vX.Y.Z`.
 5. `Publish Packages` runs on the tag push, validates the tagged commit again, and publishes `@ai-ui/ui` and `@ai-ui/tokens`.
@@ -151,7 +156,7 @@ artifact for package consumers.
 `Release Version PR` runs on pushes to `main` and:
 
 - installs dependencies
-- runs `pnpm release:validate`
+- runs `pnpm harness:validate:release`
 - opens or updates the version PR with `pnpm release:version`
 
 ### Tag workflow
@@ -166,7 +171,7 @@ artifact for package consumers.
 `Publish Packages` runs on `cadence-ui-v*` tags and:
 
 - verifies the tag matches the package version
-- runs `pnpm release:validate`
+- runs `pnpm harness:validate:release`
 - publishes the packages with `NPM_TOKEN`
 
 ## Required secrets