feat: add package-first release flow

README.md

@@ -16,8 +16,8 @@ default styling with its own tokens, motion recipes, and component contract.
 
 - The foundation, token layer, authoring contract, Storybook docs, and unit coverage are in place.
 - The public UI surface now includes the core form and overlay set plus advanced patterns such as `DataTable`, `Command`, `Combobox`, `Sheet`, and `EmptyState`.
-- The internal source-copy registry flow is live and validated with `pnpm registry:check` and `pnpm test:registry:consumer`.
-- The main remaining release work is publish policy and tagging automation, not initial component bootstrapping.
+- The default distribution path is package-first: `@ai-ui/ui` and `@ai-ui/tokens` are versioned and validated for package consumption.
+- The internal source-copy registry flow remains available as an optional mode for teams that want local ownership of copied component source.
 
 ## System principles
 
@@ -68,6 +68,7 @@ Run tests:
 
 ```bash
 pnpm test
+pnpm test:package:consumer
 pnpm test:registry:consumer
 pnpm test:e2e:smoke
 ```
@@ -81,7 +82,13 @@ pnpm typecheck
 
 ## Package consumption
 
-For package-style consumers, prefer a single CSS entrypoint from `@ai-ui/ui`:
+Package consumption is the default path for downstream apps:
+
+```bash
+pnpm add @ai-ui/ui
+```
+
+Prefer a single CSS entrypoint from `@ai-ui/ui`:
 
 ```tsx
 import { Button } from "@ai-ui/ui";
@@ -95,14 +102,19 @@ import { Button } from "@ai-ui/ui";
 
 This keeps the app on one UI package import path while still pulling in token and skin
 styles together. Consumers that want lower-level control can still import
-`@ai-ui/tokens/styles.css` and `@ai-ui/ui/skins.css` separately.
+`@ai-ui/tokens/styles.css` and `@ai-ui/ui/skins.css` separately. If you need token helpers
+such as `setTheme`, add `@ai-ui/tokens` directly as well.
 
-Install source-owned components into another project:
+If you need source ownership instead of package upgrades, use the optional registry
+installer to copy component source into another project:
 
 ```bash
 pnpm registry:install --project ../acme-app button dialog
 ```
 
+Package release details live in [docs/releasing.md](/Users/xd/project/cadence-ui/docs/releasing.md).
+Source-copy install and upgrade details live in [docs/registry.md](/Users/xd/project/cadence-ui/docs/registry.md).
+
 ## Workspace structure
 
 ```txt
@@ -128,11 +140,11 @@ The system is layered:
 The current public component layer lives in `packages/ui/src/components`, with shared
 helpers in `packages/ui/src/lib`.
 
-## Registry install flow
+## Optional Source-Copy Flow
 
-Cadence UI now ships a minimal internal registry flow for source-owned adoption.
-Consumers pin this repo to a reviewed commit or tag, then run the local installer to
-copy selected items into their own codebase.
+Cadence UI still ships a registry installer for teams that want to copy component source
+into their own app and keep editing it there. This is the advanced customization path,
+not the default distribution path.
 
 - Registry metadata lives in `registry/index.json` and is generated by `pnpm registry:build`.
 - The generated index tracks transitive local helpers in addition to component entrypoints, so helper-import changes need a registry rebuild before merge.
@@ -149,6 +161,7 @@ to document more than the default playground when behavior is non-trivial. The r
 uses:
 
 - Vitest + Testing Library for unit and interaction coverage
+- package consumer smoke coverage for published-package consumption
 - Storybook interaction coverage for representative examples
 - Playwright smoke coverage for core Storybook flows
 - Storybook a11y checks as part of the docs review surface