# Registry Install and Upgrade

Cadence UI supports a source-copy registry flow for teams that want local ownership of
component source inside their own application.

This is the optional customization path. The default downstream consumption model is now
package install via `@ai-ui/ui`, with `@ai-ui/tokens` available for lower-level token imports.

## 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`.

The generated index includes transitive local helpers, not just component entrypoints. If a
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:

```bash
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.

## Consumer install flow

Choose this flow when:

- your team wants to edit copied component code locally
- you expect app-specific divergence that would be awkward to upstream immediately
- you prefer source ownership over centralized package upgrades

If you just want to use Cadence UI in another app with the lowest maintenance overhead,
use the package flow in [docs/releasing.md](/Users/xd/project/cadence-ui/docs/releasing.md)
instead.

### 1. Pin the Cadence UI source

Consumers should install from a reviewed Cadence UI repo state, usually:

- the `cadence-ui-vX.Y.Z` tag created for the release, or
- the matching merge commit if the source-copy install must be tested before the tag is created

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

For package consumers instead of source-copy installs, the equivalent convenience import
is:

- `@ai-ui/ui/styles.css`

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:

- host a remote registry API
- resolve consumer-specific codemods during upgrade