---
description: Consumer apps — bump @exxatdesignux/ui without wiping product work; never blind-run exxat-ui upgrade or copy generated-starter wholesale. Load on install, update, upgrade, bump, or sync-extras.
alwaysApply: false
---

# Exxat DS — consumer package upgrade (preserve app work)

**Applies when:** installing, bumping, upgrading, or syncing `@exxatdesignux/ui` in a **consumer / customer app** (npm/`pnpm` dependency — not the DS monorepo `workspace:*`).

**Procedure skill:** `.cursor/skills/exxat-package-upgrade/SKILL.md` (Claude / Antigravity mirrors after sync).

**Checklist pattern:** `docs/exxat-ds/consumer-upgrade-checklist.md` (after `sync-extras`).

## Three commands (pick deliberately)

| Command | Touches app source? | Use when |
|---------|---------------------|----------|
| `pnpm add @exxatdesignux/ui@…` / `npm install @exxatdesignux/ui@…` | **No** — only `node_modules` + lockfile | You need new primitives / bugfixes only |
| `npx exxat-ui sync-extras` | **Docs/rules only** — `.cursor/`, `.claude/`, `.agents/`, `docs/exxat-ds/` | Refresh agent context; never product pages |
| `npx exxat-ui upgrade` | **Yes** — overwrites **package-owned shell** files from `generated-starter/` | User **explicitly** asked to align shell chrome; never as a default after install |

`upgrade` also writes backups under `.exxat-ui/backups/<timestamp>/`. Prefer **git commit** before any upgrade.

## MUST

1. **Confirm the command before running it.** If the user said "update the package" / "bump the DS", default to **install only** — do **not** run `exxat-ui upgrade` unless they also asked to sync/port shell.
2. **Dry-run first** when shell sync is intended:
   ```bash
   npx exxat-ui upgrade --check
   ```
3. **Preserve builder-owned / tenant work:** custom products, domain hubs, mock/API modules, column defs, tenant nav labels/URLs, custom pages, `.env*`.
4. **Port shell only** when release notes or a chrome bug require it — merge against `node_modules/@exxatdesignux/ui/generated-starter/` using the skill **port-map**; keep app content.
5. **Report** what was installed vs what was ported vs what was left alone (skill Phase 6 handoff).

## MUST NOT

1. **MUST NOT** run `exxat-ui upgrade` as a silent follow-up to `pnpm add` / `npm install`.
2. **MUST NOT** copy the entire `generated-starter/` tree into the customer app.
3. **MUST NOT** overwrite or delete tenant routes, hubs, mocks, API clients, or product copy "to match the starter".
4. **MUST NOT** put durable product IA only in auto-ported paths without a merge plan — `upgrade` will replace package-owned files (e.g. product chrome, shared shell, listed sync-manifest paths) with the dogfood starter.
5. **MUST NOT** invent a second fork of `@exxatdesignux/ui` components in the consumer to avoid upgrades — compose the package; keep product code in app-owned files.

## Recovering wiped files

1. `git checkout -- <path>` or `git restore <path>` from the pre-upgrade commit.
2. Or copy from `.exxat-ui/backups/<timestamp>/`.
3. Re-apply tenant changes in **app-owned** files so the next `upgrade` does not erase them again.

## See also

- Skill: `exxat-package-upgrade` (+ `port-map.md`)
- Maintainer publish gate: `exxat-package-publish-validation.mdc` (monorepo only)
- CLI: `exxat-ui doctor` · `exxat-ui changelog` · `exxat-ui upgrade --check`