@nextop-os/ui-system 0.0.16 → 0.0.18

package/AGENTS.md

@@ -0,0 +1,106 @@
+# AGENTS.md
+
+## Scope
+
+This file applies to `packages/ui/system/*`.
+
+`packages/ui/system` is the source package for `@nextop-os/ui-system`, the
+shared Nextop UI component library. It owns shared CSS tokens, theme styles,
+icon exports, presentation primitives, reusable host-agnostic business display
+components, component metadata, storyboard inventory, and the bundled
+`nextop-ui-system` agent skill.
+
+Before changing components, icons, metadata, styles, storyboard examples, or
+the bundled skill, read `ui-system.md`.
+
+UI-system design compliance is a release gate for this package, not a follow-up
+task. If a promoted component does not yet follow the shared token model,
+surface language, primitive vocabulary, and storyboard evidence standard, do
+not report it as complete.
+
+## Public API
+
+Stable public imports are:
+
+- `@nextop-os/ui-system`
+- `@nextop-os/ui-system/components`
+- `@nextop-os/ui-system/metadata`
+- `@nextop-os/ui-system/icons`
+- `@nextop-os/ui-system/styles.css`
+- `@nextop-os/ui-system/utils`
+
+Rules:
+
+- prefer adding exports to an existing public barrel before introducing a new
+  public subpath
+- do not expose `src/*` layout as public API
+- do not encourage per-file deep imports such as
+  `@nextop-os/ui-system/components/button`
+- if package exports change intentionally, update both the package exports and
+  the UI-boundary check script
+
+## Component Library Rules
+
+- keep `base` components low-level, generic, and
+  frontend-foundation-focused
+- allow `business` components only when they are reusable business display
+  components that remain host-agnostic and side-effect-free
+- business components may expose domain display props such as workspace, file,
+  task, agent, status, permission, and callbacks, but must not own daemon,
+  Electron, router, store, query, filesystem, persistence, or workflow calls
+- before promoting a business component, scan source usage, build a
+  code-evidence state matrix, and define the public props boundary from that
+  evidence; after that, promote it directly into `packages/ui/system` and add
+  storyboard coverage for the accepted states
+- business components should compose `base` primitives instead of recreating
+  buttons, fields, dialogs, cards, icons, or overlays
+- promoted components and their storyboard examples must use UI-system semantic
+  tokens and approved shared CSS variables; do not leave raw `hex`,
+  `rgb(...)`, `rgba(...)`, ad hoc gradients, or app-local palette values in the
+  final UI-system implementation unless they already come from approved shared
+  tokens
+- storyboard coverage must show the component's real promoted surface and
+  states; do not rely on surrounding docs chrome or wrapper panels to mask
+  component-level visual drift
+- UI storyboard foundation content is JSON-driven. When changing documented
+  token, color, typography, spacing, radius, motion, or overview display data,
+  edit `apps/ui-storyboard/src/foundation/*.json` directly instead of
+  hardcoding those values in `apps/ui-storyboard/src/App.tsx`
+- migrated consumers must end on the same UI-system visual implementation for
+  the promoted surface; temporary bridges are allowed only for wiring, not as a
+  separate long-lived token or styling system
+- treat this package as the shared shadcn and Radix host package
+- when a primitive exists in the shadcn registry, acquire it through shadcn CLI
+  targeted at this package instead of handwriting the component body
+- keep `components.json` and package aliases usable enough that CLI download
+  remains the default path for shared primitives
+- after CLI acquisition, limit edits to narrow package-specific adaptation such
+  as icon routing, import aliases, stable exports, and boundary-check fixes
+- keep CSS variables as the source of truth for token values
+- prefer semantic token naming over raw palette leakage in public APIs
+- keep helper exports minimal and tied to primitive support, not general
+  convenience reuse
+- build primitives for a calm workbench shell, not for marketing-card theatrics
+- every public component, icon, utility, or style entry must have metadata with
+  a stable readable `id` and `layer`
+- use the single `nextop-ui-system` skill for component reuse, extraction,
+  base/business classification, metadata, and storyboard work
+
+## Validation
+
+- Run `pnpm typecheck`
+- Run `pnpm check:ui-boundaries`
+- If component metadata changed, run `node tools/scripts/check-ui-metadata.mjs`
+- If storyboard inventory changed, run
+  `pnpm --filter @nextop-os/ui-storyboard typecheck`
+- If a change affects desktop integration, also run
+  `pnpm --filter @nextop-os/desktop build`
+- In the handoff, explicitly state whether tokens, primitives, storyboard
+  surface, and migrated consumer all comply with the UI-system standard; if any
+  of those are still divergent, the work is not complete
+
+## Related Docs
+
+- `ui-system.md`
+- `docs/conventions/desktop-visual-language.md`
+- `docs/conventions/local-git-hooks.md`

package/README.md

@@ -38,9 +38,9 @@ export default defineConfig({
 ```
 
 When the dev server is reachable, the plugin mirrors the allowed UI-system
-source files into `.nextop-ui-system-dev/` and aliases the stable package
-entrypoints to that cache. When the dev server is unavailable, resolution falls
-back to the installed package in `node_modules`.
+source and skill-support files into `.nextop-ui-system-dev/` and aliases the
+stable package entrypoints to that cache. When the dev server is unavailable,
+resolution falls back to the installed package in `node_modules`.
 
 Add the generated cache to the external app's `.gitignore`:
 
@@ -65,15 +65,18 @@ import { uiSystemMetadata } from "@nextop-os/ui-system/metadata";
 ```
 
 When promoting business UI into this package, use the bundled
-`agent/nextop-ui-system/SKILL.md` skill when it is available. The durable rules
-are:
+`agent/nextop-ui-system/SKILL.md` skill when it is available. In the source
+checkout, also read `AGENTS.md`, `ui-system.md`, and
+`docs/conventions/desktop-visual-language.md`. The durable rules are:
 
 1. prefer existing metadata entries before creating a component
 2. classify the component as `base` or `business`
 3. keep business components host-agnostic and side-effect-free
-4. compose business components from base primitives
-5. add metadata, stable exports, and storyboard examples for public UI
-6. run metadata and boundary validation before shipping
+4. before promoting a business component, scan source usage and define the
+   public props boundary from code evidence
+5. compose business components from base primitives
+6. add metadata, stable exports, and storyboard examples for public UI
+7. run metadata and boundary validation before shipping
 
 External repositories can install the bundled skill into their local Codex
 skill directory with one command:
@@ -88,5 +91,7 @@ This copies the package skill into:
 .codex/skills/nextop-ui-system/SKILL.md
 ```
 
-The installer does not overwrite a locally modified skill unless `--force` is
-provided.
+When `.nextop-ui-system-dev/` is present, the installer prefers the synced
+source checkout so the installed skill and bundled UI-system rules stay aligned
+with the current local UI-system source. The installer does not overwrite a
+locally modified skill unless `--force` is provided.

package/agent/install-skill.mjs

@@ -14,8 +14,9 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const sourceDirectory = join(packageRoot, "agent", "nextop-ui-system");
 const skillName = "nextop-ui-system";
+const devCacheDirectoryName = ".nextop-ui-system-dev";
+const companionFiles = ["AGENTS.md", "ui-system.md"];
 
 const options = parseArgs(process.argv.slice(2));
 
@@ -26,8 +27,15 @@ if (options.help) {
 
 const targetRoot = resolve(options.cwd, ".codex", "skills");
 const targetDirectory = join(targetRoot, skillName);
+const sourceRoot = await resolveSourceRoot(options.cwd);
+const sourceDirectory = join(sourceRoot, "agent", skillName);
 
 await assertReadableDirectory(sourceDirectory);
+await Promise.all(
+  companionFiles.map((fileName) =>
+    assertReadableFile(join(sourceRoot, fileName))
+  )
+);
 await mkdir(targetRoot, { recursive: true });
 
 if (await pathExists(targetDirectory)) {
@@ -38,7 +46,7 @@ if (await pathExists(targetDirectory)) {
   }
 
   if (!options.force) {
-    if (await directoriesMatch(sourceDirectory, targetDirectory)) {
+    if (await directoriesMatch(sourceRoot, sourceDirectory, targetDirectory)) {
       console.log(
         `nextop-ui-system skill already configured at ${targetDirectory}`
       );
@@ -59,6 +67,15 @@ await cp(sourceDirectory, targetDirectory, {
   force: true,
   recursive: true
 });
+await Promise.all(
+  companionFiles.map((fileName) =>
+    cp(join(sourceRoot, fileName), join(targetDirectory, fileName), {
+      errorOnExist: false,
+      force: true,
+      recursive: false
+    })
+  )
+);
 
 console.log(`Installed nextop-ui-system skill to ${targetDirectory}`);
 console.log(
@@ -121,6 +138,15 @@ async function assertReadableDirectory(path) {
   }
 }
 
+async function assertReadableFile(path) {
+  await access(path, constants.R_OK);
+  const pathStats = await stat(path);
+
+  if (!pathStats.isFile()) {
+    throw new Error(`Expected file: ${path}`);
+  }
+}
+
 async function pathExists(path) {
   try {
     await access(path, constants.F_OK);
@@ -130,8 +156,24 @@ async function pathExists(path) {
   }
 }
 
-async function directoriesMatch(leftDirectory, rightDirectory) {
-  const leftEntries = await listFiles(leftDirectory, leftDirectory);
+async function resolveSourceRoot(cwd) {
+  const devCacheRoot = resolve(cwd, devCacheDirectoryName);
+  const devCacheSkillDirectory = join(devCacheRoot, "agent", skillName);
+
+  if (
+    (await pathExists(devCacheSkillDirectory)) &&
+    (await pathExists(join(devCacheRoot, "AGENTS.md"))) &&
+    (await pathExists(join(devCacheRoot, "ui-system.md")))
+  ) {
+    return devCacheRoot;
+  }
+
+  return packageRoot;
+}
+
+async function directoriesMatch(sourceRoot, sourceDirectory, rightDirectory) {
+  const sourceEntries = await listBundleFiles(sourceRoot, sourceDirectory);
+  const leftEntries = sourceEntries.map((entry) => entry.targetRelativePath);
   const rightEntries = await listFiles(rightDirectory, rightDirectory);
 
   if (leftEntries.length !== rightEntries.length) {
@@ -143,7 +185,7 @@ async function directoriesMatch(leftDirectory, rightDirectory) {
       return false;
     }
 
-    const leftFile = join(leftDirectory, leftEntries[index]);
+    const leftFile = sourceEntries[index].sourceAbsolutePath;
     const rightFile = join(rightDirectory, rightEntries[index]);
 
     const [leftContent, rightContent] = await Promise.all([
@@ -159,6 +201,24 @@ async function directoriesMatch(leftDirectory, rightDirectory) {
   return true;
 }
 
+async function listBundleFiles(sourceRoot, sourceDirectory) {
+  const skillFiles = await listFiles(sourceDirectory, sourceDirectory);
+  const companionEntries = companionFiles.map((fileName) => ({
+    sourceAbsolutePath: join(sourceRoot, fileName),
+    targetRelativePath: fileName
+  }));
+
+  return skillFiles
+    .map((relativePath) => ({
+      sourceAbsolutePath: join(sourceDirectory, relativePath),
+      targetRelativePath: relativePath
+    }))
+    .concat(companionEntries)
+    .sort((left, right) =>
+      left.targetRelativePath.localeCompare(right.targetRelativePath)
+    );
+}
+
 async function listFiles(rootDirectory, directory) {
   const entries = await readdir(directory, { withFileTypes: true });
   const files = await Promise.all(

package/agent/nextop-ui-system/SKILL.md

@@ -1,20 +1,45 @@
 ---
 name: nextop-ui-system
-description: Use when working with @nextop-os/ui-system components, replacing local UI with shared components, querying component ids or metadata, promoting business UI into shared base or business components, or maintaining UI-system storyboard inventory.
+description: Use when working with @nextop-os/ui-system components, replacing local UI with shared components, querying component ids or metadata, promoting UI into shared base or business components, or maintaining UI-system storyboard inventory.
 ---
 
 # Nextop UI System
 
-Use this skill as the single entrypoint for `@nextop-os/ui-system` use,
-promotion, metadata, and storyboard work.
+Use this skill as the single entrypoint for `@nextop-os/ui-system` component
+reuse, extraction, promotion, metadata, and storyboard work.
+
+## Non-Negotiable Standard
+
+Any UI promoted into `@nextop-os/ui-system` must fully follow the UI-system
+design standard before it can be reported as complete.
+
+Treat these as hard requirements, not cleanup suggestions:
+
+- use UI-system semantic tokens and existing shared CSS variables; do not leave
+  raw `hex`, `rgb(...)`, `rgba(...)`, ad hoc gradients, or app-local palette
+  values in promoted components or their storyboard examples unless the source
+  of truth already exposes them as approved tokens
+- compose existing UI-system `base` primitives such as `Card`, `Button`,
+  `Tooltip`, `Dialog`, and related vocabulary before creating custom panel,
+  button, field, or overlay treatments
+- make storyboard examples render the real component surface and states; do not
+  rely on surrounding docs chrome to hide component-level visual drift or to
+  fake the final panel/surface language
+- when a consumer is migrated, its final rendered result must also follow the
+  same UI-system visual standard; a temporary bridge may help wiring, but it is
+  not acceptable as the final visual implementation if it keeps a second token
+  system or divergent component styling
+
+If these conditions are not met, report the promotion as incomplete or blocked,
+not complete.
 
 ## Source Of Truth
 
 Read these before editing:
 
 1. nearest `AGENTS.md` for the target code
-2. `packages/ui/AGENTS.md`
-3. `docs/conventions/ui-system.md`
+2. local `AGENTS.md` bundled with this skill
+3. local `ui-system.md` bundled with this skill
 4. component metadata from the first available source:
    - `GET http://127.0.0.1:4100/components`
    - `packages/ui/system/src/metadata/components.json`
@@ -33,76 +58,120 @@ Never deep import `@nextop-os/ui-system/src/*` or per-file component paths.
 
 ## Route The Task
 
-### Use Existing Component
-
-Use when replacing local UI or answering what components exist.
-
-1. Check metadata first by `id`, `name`, `export`, `layer`, and `useCases`.
-2. Prefer existing components before creating or extracting new ones.
-3. Read the source and props type for the selected export.
-4. Keep host state, data loading, routing, daemon calls, i18n keys, and business
-   transforms in the caller.
-5. Replace only the visual surface with stable UI-system imports.
-
-### Extract Base Component
-
-Use when the target is a low-level visual primitive.
-
-Proceed only if the public API has no domain noun and props describe
-presentation, interaction, accessibility, variants, refs, slots, class names, or
-children.
-
-1. If the primitive exists in shadcn, acquire it through shadcn CLI targeted at
-   `packages/ui/system`.
-2. Adapt only package aliases, icons, tokens, exports, and boundary issues.
-3. Add stable exports, metadata with `layer: "base"`, and storyboard coverage.
-4. Replace duplicated local UI with the shared component.
+Read only the reference file that matches the task.
 
-### Extract Business Component
+- Using or querying existing components:
+  `references/use-existing-component.md`
+- Extracting a low-level base primitive:
+  `references/extract-base-component.md`
+- Promoting reusable business UI into a shared component:
+  `references/promote-business-component.md`
+- Maintaining ids, metadata, exports, or storyboard inventory:
+  `references/maintain-inventory.md`
 
-Use when business-side UI should become a reusable display component.
+## Global Boundaries
 
-Proceed only if the component can render from props with no host side effects.
-Business components may expose domain display props such as workspace, file,
-task, agent, run, status, permission, labels, and callbacks.
-
-Before editing, state:
-
-- component `id` and `layer`
-- source usage being replaced
-- intended reuse surfaces
-- public props and callbacks
-- host-owned state and side effects that remain outside the component
-- export path, metadata entry, storyboard states, and validation commands
-
-Keep these outside the component:
+Keep these outside `@nextop-os/ui-system` components:
 
 - daemon, Electron, filesystem, router, or host adapter calls
 - data fetching, cache mutation, persistence, polling, and global store
   ownership
-- workflow orchestration such as onboarding, workspace registration, or
-  navigation
-
-Implement the business component by composing `base` primitives. Add metadata
-with `layer: "business"` and storyboard examples for normal, empty, disabled,
-loading, and error-like states when those states exist in the public contract.
-
-### Maintain Inventory
-
-Use when changing component ids, metadata, exports, or storyboard.
-
-1. Keep each public entry's `id` stable, readable, globally unique, and
-   kebab-case.
-2. Keep `layer` as `base` or `business`.
-3. Ensure `source` points under `packages/ui/system/src`.
-4. Ensure `from` is a stable public entrypoint.
-5. Keep storyboard grouped by `Foundation`, `Base Components`, and
-   `Business Components`; visible component stories should support copying the
-   component id.
-
-## Validation
-
-Run the smallest relevant checks, then report exact commands and results:
+- workflow orchestration such as onboarding, workspace registration, install or
+  uninstall flows, confirmation dialogs, queueing, or navigation
+- i18n key lookup and business-specific copy derivation unless supplied by
+  props, children, or labels
+
+For any promoted public component, add stable exports, metadata, and storyboard
+coverage that match the chosen reference workflow.
+
+For promoted base components, storyboard coverage is not satisfied by metadata
+alone. The promotion flow must also add or update a real renderable example in
+`apps/ui-storyboard` so the component is visible in navigation and can be
+visually reviewed in shared docs immediately after promotion.
+
+For business component promotion, derive the promoted component directly from
+the state matrix, proposed props boundary, and candidate source UI, then add
+storyboard coverage for the accepted states in the same promotion pass. Treat
+that evidence and boundary decision as the implementation blueprint for
+`packages/ui/system`, and use review only to verify the finished implementation.
+
+## Design Foundation Verification
+
+Every promoted component must comply with
+`ui-system.md`, especially the shared tokens,
+theme variables, spacing, radius, typography, surface language, interactive
+states, and existing `base` primitive vocabulary.
+
+Explicitly check and report all of these before completion:
+
+- color and surface styling come from UI-system semantic tokens rather than raw
+  palette values
+- panels, rows, controls, and overlays compose existing base primitives where
+  applicable instead of recreating them locally
+- storyboard shows the component's real promoted surface rather than only a
+  documentation wrapper
+- migrated consumers no longer depend on a separate visual token system for the
+  promoted surface
+
+Run the Nextop promotion review gate before reporting completion. The gate is
+adapted from frontend design review practice but constrained to Nextop's dense
+workbench product language:
+
+- Frictionless: the migrated consumer preserves the original task path, keeps a
+  clear action hierarchy, and does not bury primary or recovery actions.
+- Quality craft: visual parity evidence is captured for selected states, shared
+  tokens and primitives are used, light/dark and interactive states work, and no
+  unapproved raw palette, spacing, radius, typography, or motion drift remains.
+- Trustworthy: empty, loading, disabled, error-like, permission-limited, and
+  AI-generated-content states keep clear labels, actionable recovery, and
+  host-owned policy or provenance outside the shared component.
+
+After promoting a base or business component, start an independent subagent to
+review design-foundation compliance before reporting completion. Provide the
+subagent with the promoted files, source usage, selected states, storyboard and
+metadata entries, and the UI-system guidelines. If subagents are unavailable,
+state that design-foundation verification is blocked and do not claim full
+compliance.
+
+Report the gate result with:
+
+- context: source usage, promoted component id/layer, user task, selected states
+- status: pass, needs work, or blocked
+- pillar assessment: Frictionless, Quality craft, Trustworthy
+- issues grouped as blocking, major, and minor
+- validation commands and exact results
+- remaining risks, uncovered states, or approved visual deltas
+
+## API Composition Review
+
+When converting source states into public props, review the API shape before
+writing the promoted component:
+
+- avoid boolean prop proliferation for rendering modes; mode axes such as
+  `isFoo`, `showBar`, or `withBaz` must come from code evidence and usually
+  become a finite variant, discriminated union, explicit component variant,
+  slot, or composed child
+- keep standard UI booleans such as `disabled`, `loading`, `selected`, `open`,
+  `required`, and `invalid` only when they represent real component state and
+  cannot create impossible combinations
+- prefer `children` or named slots for caller-owned visual regions; use render
+  props only when the shared component must pass data back to the caller
+- use compound components and context only for genuinely complex reusable
+  structures where consumers need to compose subparts without prop drilling
+- if shared state is needed, define a narrow context value as `state`,
+  `actions`, and `meta`; providers may inject state but must not own daemon,
+  Electron, router, store, query, persistence, or workflow side effects
+- for new React components in this React 19 codebase, prefer the React 19 API
+  shape such as `ref` as a prop; do not churn shadcn or Radix-acquired code only
+  to normalize style when behavior and public API are already sound
+
+Report the API composition decision with the state matrix: which differences
+became props, variants, slots, children, explicit variants, provider state, or
+stayed host-owned.
+
+## Validation Commands
+
+Run the smallest relevant checks from the selected reference. Common checks are:
 
 ```bash
 node tools/scripts/check-ui-metadata.mjs
@@ -111,4 +180,11 @@ pnpm --filter @nextop-os/ui-storyboard typecheck
 ```
 
 If runtime component code changed, also run the relevant package typecheck or
-build for the consumer that was migrated.
+consumer build.
+
+When a base component is promoted, verify both of these conditions before
+reporting completion:
+
+- the component metadata opts into storyboard visibility when appropriate
+- `apps/ui-storyboard` contains a concrete rendered example for the promoted
+  component states, not just inventory wiring

package/agent/nextop-ui-system/references/extract-base-component.md

@@ -0,0 +1,87 @@
+# Extract Base Component
+
+Use this reference when the target is a low-level visual primitive.
+
+## Base Criteria
+
+Proceed only if the public API has no domain noun and props describe generic UI
+concerns:
+
+- presentation and variants
+- interaction and accessibility
+- refs, slots, class names, and children
+- controlled or uncontrolled primitive state
+
+If the component represents a workspace, file, task, agent, run, project,
+account, or other business concept, use `promote-business-component.md`
+instead.
+
+## Workflow
+
+1. Check metadata and existing exports first.
+2. Read the bundled `ui-system.md` before implementation and
+   treat it as a hard gate for the extraction. The component must follow the
+   shared token, theme variable, spacing, radius, typography, surface,
+   interactive-state, accessibility, and reduced-motion rules from
+   `@nextop-os/ui-system`; do not preserve or introduce caller-local styling
+   when it conflicts with those guidelines.
+3. If the primitive exists in the shadcn registry, acquire it through shadcn CLI
+   targeted at `packages/ui/system`.
+4. Decide the primitive API before editing:
+   - use finite variants or discriminated unions for mutually exclusive visual
+     modes
+   - keep standard UI booleans such as `disabled`, `loading`, `selected`,
+     `open`, `required`, and `invalid` only when they represent real states
+   - prefer `children`, slots, refs, and class names for composition instead
+     of broad render props
+   - use compound components or context only when consumers need to assemble
+     reusable subparts that share primitive state
+   - follow the React 19 baseline for new hand-authored components, but do not
+     rewrite shadcn or Radix internals only for API-style churn
+5. Adapt only package aliases, icon routing, tokens, stable exports, metadata,
+   storyboard examples, and boundary-check issues.
+6. Keep helper exports minimal and directly tied to primitive support.
+7. Add metadata with `layer: "base"`.
+8. Add storyboard coverage for the public states and variants exposed by the
+   primitive.
+   - This is mandatory for base-component promotion.
+   - Do not treat `storyboard: true` in metadata as sufficient by itself.
+   - Add or update a real renderable example in `apps/ui-storyboard` so the
+     component appears in navigation and can be visually reviewed immediately.
+9. Replace duplicated local UI only after the shared primitive exists.
+10. Run the promotion review gate from
+    `ui-system.md`: verify Frictionless task
+    preservation, Quality Craft visual/token/state parity, and Trustworthy
+    status/error/accessibility behavior for the migrated consumer.
+11. Start an independent design-foundation review subagent after promotion. The
+    review must check the promoted files against
+    `ui-system.md`, existing tokens, primitives,
+    API shape, storyboard coverage, and metadata. Resolve any reported design
+    drift before completion.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+pnpm --filter @nextop-os/ui-system typecheck
+```
+
+If a consumer was migrated, also run that consumer's typecheck or build.
+
+Before reporting completion, confirm storyboard delivery at two levels:
+
+- inventory: the component is discoverable from storyboard navigation
+- rendering: the component has a concrete example that renders its public
+  states or variants inside `apps/ui-storyboard`
+
+Do not report full design-foundation compliance unless the subagent review ran
+and found no unresolved drift. If subagents are unavailable, report the
+verification as blocked.
+
+Report the promotion review result with the component id, selected states,
+Frictionless / Quality Craft / Trustworthy pillar status, blocking/major/minor
+issues, validation commands, and remaining risks or approved visual deltas.

package/agent/nextop-ui-system/references/maintain-inventory.md

@@ -0,0 +1,45 @@
+# Maintain Inventory
+
+Use this reference when changing component ids, metadata, exports, or storyboard
+inventory without promoting a new component.
+
+## Metadata Rules
+
+Every public UI-system entry must have metadata with:
+
+- stable readable `id`
+- globally unique kebab-case id
+- `layer` as `base` or `business`
+- `source` under `packages/ui/system/src`
+- stable public `from` entrypoint
+
+Do not expose `src/*` layout as public API and do not encourage per-file deep
+imports.
+
+## Storyboard Rules
+
+Keep storyboard grouped by:
+
+- `Foundation`
+- `Base Components`
+- `Business Components`
+
+Visible component stories should support copying the component id.
+
+When a base component is newly promoted into `@nextop-os/ui-system`, updating
+inventory alone is not enough. The same change must also add or refresh a real
+renderable example in `apps/ui-storyboard` so the promoted component is
+immediately reviewable from the shared storyboard.
+
+When changing metadata or storyboard inventory, keep ids stable unless the
+rename is intentional and callers or docs are updated together.
+
+## Validation
+
+Run the relevant checks:
+
+```bash
+node tools/scripts/check-ui-metadata.mjs
+pnpm check:ui-boundaries
+pnpm --filter @nextop-os/ui-storyboard typecheck
+```