chore: add registry install flow

docs/registry.md

@@ -0,0 +1,118 @@
+# Registry Install and Upgrade
+
+Cadence UI now supports a minimal internal registry flow for source-owned consumers.
+The goal is not package publishing yet. The goal is to make one reviewed repo state
+directly consumable by another app.
+
+## What the registry contains
+
+- `registry/config.json`: the authored registry format
+- `registry/index.json`: generated install metadata
+- `scripts/build-registry.mjs`: rebuilds and validates the generated index
+- `scripts/registry-install.mjs`: copies selected source files into a consumer project
+
+`registry/index.json` is intentionally machine-readable. It records:
+
+- installable item names
+- entrypoints and copied files
+- transitive source files required by each item
+- external package dependencies
+- the package versions that produced the registry snapshot
+
+## Maintainer workflow
+
+Whenever `packages/ui` or `packages/tokens` changes in a way that affects installable
+source, refresh the registry metadata:
+
+```bash
+pnpm registry:build
+```
+
+To verify that the generated file is current:
+
+```bash
+pnpm registry:check
+```
+
+The pull request workflow now runs `pnpm registry:check`, and the release version PR
+workflow refreshes the registry automatically via `pnpm release:version`.
+
+## Consumer install flow
+
+### 1. Pin the Cadence UI source
+
+Consumers should install from a reviewed Cadence UI repo state, usually:
+
+- the merge commit of a version PR, or
+- a maintainer-created tag that points at that versioned commit
+
+The consumer does not need this repo as a runtime dependency. It only needs access to
+the checked-out source when running the installer.
+
+### 2. Run the installer from the Cadence UI repo
+
+From this repository checkout:
+
+```bash
+pnpm registry:install --project ../acme-app button dialog
+```
+
+The installer will:
+
+- include `tokens` automatically when a component requires it
+- copy files into `src/cadence-ui`
+- preserve shared internal imports under `src/cadence-ui/components`, `src/cadence-ui/lib`,
+  and `src/cadence-ui/tokens`
+- add any missing runtime dependencies to the consumer's `package.json`
+- write `src/cadence-ui/.install-manifest.json`
+
+Useful flags:
+
+- `--target-dir src/shared/cadence-ui`: customize the destination root
+- `--skip-package-json`: copy files without editing the consumer package manifest
+- `--dry-run`: preview copied files and package changes
+
+## Consumer upgrade flow
+
+Upgrades stay source-owned. There is no generated wrapper or hidden runtime.
+
+1. Update the Cadence UI checkout to the new reviewed commit or tag.
+2. Re-run the installer against the same consumer project.
+
+```bash
+pnpm registry:install --project ../acme-app
+```
+
+If no item names are provided, the installer reuses the list stored in
+`src/cadence-ui/.install-manifest.json`.
+
+After that:
+
+- review the consumer diff
+- run the consumer package manager install if `package.json` changed
+- verify imports still point at `src/cadence-ui/tokens/styles.css`
+
+## Expected consumer import points
+
+At minimum, the consumer app should import:
+
+- `src/cadence-ui/tokens/styles.css` from its global app stylesheet or entry module
+
+If the consumer wants the theme helpers, they can also import from:
+
+- `src/cadence-ui/tokens/index.ts`
+
+## Current scope
+
+This registry flow is intentionally minimal:
+
+- it copies source files
+- it writes dependency intent into the consumer app
+- it supports reinstalling the same item set for upgrades
+
+It does not yet:
+
+- publish to npm
+- host a remote registry API
+- auto-tag or auto-publish releases
+- resolve consumer-specific codemods during upgrade

docs/releasing.md

@@ -9,6 +9,7 @@ The current goal is modest:
 - keep release notes attached to the changes that caused them
 - avoid inventing ad hoc version bumps when the component system evolves
 - make release intent enforceable in CI before package work merges
+- keep the generated registry metadata aligned with versioned source
 
 ## Current assumptions
 
@@ -68,6 +69,7 @@ At minimum, run:
 
 ```bash
 pnpm lint
+pnpm registry:check
 pnpm typecheck
 pnpm test
 ```
@@ -104,10 +106,10 @@ keep the dependency graph coherent without requiring manual package edits.
 
 ### 4. Version the packages
 
-When it is time to cut a release manually, run the Changesets version step:
+When it is time to cut a release manually, run the repo version step:
 
 ```bash
-pnpm changeset version
+pnpm release:version
 ```
 
 That step is expected to:
@@ -115,6 +117,7 @@ That step is expected to:
 - update package versions
 - update internal dependency ranges where needed
 - consume the pending changeset files
+- rebuild `registry/index.json` so the copy-in install metadata stays version-aligned
 
 Review the resulting package diffs carefully before merging.
 
@@ -122,17 +125,19 @@ On `main`, the repository also runs a `Release Version PR` workflow that opens o
 version PR with the same command. That workflow is intentionally limited to version-file updates;
 it does not publish packages.
 
-### 5. Publish or tag
+### 5. Distribute the versioned source
 
-Publishing is not fully wired in this repo yet, so treat this step as pending infrastructure.
+Publishing is not fully wired in this repo yet, so the consumable artifact is the versioned
+repository state itself.
 
-The intended future flow is:
+After the version PR merges:
 
-```bash
-pnpm changeset publish
-```
+- keep the merge commit as a stable install point, or create a maintainer tag for it
+- treat the committed `registry/index.json` as the install contract for that repo state
+- point consumers at that commit or tag when they run `pnpm registry:install`
 
-But until registry, auth, and CI behavior are explicit, do not assume publish is automated.
+See [docs/registry.md](/Users/xd/project/cadence-ui/docs/registry.md) for the consumer
+install and upgrade flow.
 
 ## CI workflows
 
@@ -153,16 +158,24 @@ pnpm changeset:status --since origin/main
 
 This validates that pending changesets resolve cleanly against the base branch.
 
+The workflow also runs:
+
+```bash
+pnpm registry:check
+```
+
+This prevents registry metadata drift from merging unnoticed.
+
 ### Version PR workflow
 
 The `Release Version PR` workflow runs on pushes to `main` and on manual dispatch. It:
 
 - installs dependencies
-- runs `pnpm changeset version`
+- runs `pnpm release:version`
 - opens or updates a version PR using `changesets/action`
 
-This is a versioning skeleton, not a publish pipeline. It is safe to enable before registry
-credentials or publish commands exist.
+This is still a versioning skeleton, not a publish pipeline, but the version PR now refreshes
+the committed registry metadata that consumers install from.
 
 ## Future publish prerequisites
 
@@ -183,5 +196,6 @@ Before turning the version workflow into a publish workflow, the repo still need
 
 ## Main-thread follow-up still needed
 
-This baseline now covers changeset intent checks in PRs and version PR creation on `main`.
-What remains is the publish decision and any registry-specific automation.
+This baseline now covers changeset intent checks in PRs, registry metadata validation, and
+version PR creation on `main`. What remains is the publish decision, tagging policy, and any
+registry-specific automation beyond source-copy installs.