chore: add registry install flow

README.md

@@ -9,6 +9,7 @@ default styling with its own tokens, motion recipes, and component contract.
 - `packages/tokens`: theme tokens, motion tokens, and theme helpers
 - `packages/ui`: component source, variants, contracts, and tests
 - `apps/docs`: Storybook docs and usage reference
+- `registry`: generated registry metadata plus the source-copy install contract
 - `tests/e2e`: Playwright smoke coverage for high-value Storybook flows
 
 ## System principles
@@ -50,6 +51,12 @@ Build Storybook:
 pnpm build:docs
 ```
 
+Build the registry metadata:
+
+```bash
+pnpm registry:build
+```
+
 Run tests:
 
 ```bash
@@ -64,6 +71,12 @@ pnpm lint
 pnpm typecheck
 ```
 
+Install source-owned components into another project:
+
+```bash
+pnpm registry:install --project ../acme-app button dialog
+```
+
 ## Workspace structure
 
 ```txt
@@ -74,6 +87,7 @@ packages/
   ui/          Component source, variants, tests, and contracts
 tests/
   e2e/         Playwright smoke specs
+registry/      Generated item metadata for copy-in installs
 ```
 
 ## How the component system is organized
@@ -88,6 +102,17 @@ 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
+
+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.
+
+- Registry metadata lives in `registry/index.json` and is generated by `pnpm registry:build`.
+- The installer copies components into `src/cadence-ui`, adds missing package dependencies,
+  and writes `src/cadence-ui/.install-manifest.json` so upgrades can reuse the same item set.
+- Install and upgrade instructions live in [docs/registry.md](/Users/xd/project/cadence-ui/docs/registry.md).
+
 ## Docs and QA
 
 Storybook is the main usage reference and review surface. Component stories are expected