For agents

1 · Discover

• /llms.txt — the full catalogue: every installable item with a one-line description.
• /llms-full.txt — the same plus exports, dependencies and showcase links per item, so you can choose what to install without fetching item JSON.
• /r/versions.json — per-item content hashes (the drift signal) and the registry digest.
• /changelog — what changed and when, tagged by item (machine-readable).

2 · Wire up

Point your repo's components.json at the registry, then install the theme first, always — it carries the entire design-token system every other item assumes, and nothing pulls it in automatically. Follow the theme item's install notes exactly (it removes the conflicting shadcn init scaffolding from globals.css and wires light-mode/dark-mode classes via next-themes).

// components.json — add the @nx-ui registry (either host):
{
  "registries": {
    // Option A — hosted (no auth):
    "@nx-ui": "https://ui.nexusregen.com/r/{name}.json"

    // Option B — raw GitHub (private repo, needs NX_UI_GITHUB_TOKEN):
    // "@nx-ui": {
    //   "url": "https://raw.githubusercontent.com/nexus-regen/nx-ui/main/public/r/{name}.json",
    //   "headers": { "Authorization": "token ${NX_UI_GITHUB_TOKEN}" }
    // }
  }
}

3 · Follow the skills

The complete procedures live as versioned agent skills in this repo — vendor them into the consuming repo (recorded in skills-lock.json, per nx-standards) rather than improvising:

• skills/nx-ui-components — consuming: setup, discovery, install paths, usage rules (class vocabulary, icons, dark mode), updating and troubleshooting.
• skills/nx-ui-maintain — the scheduled update loop for consuming repos: doctor check → changelog → diff → apply → re-lock.
• skills/nx-ui-contribute — working in the nx-ui repo itself (minimal-diff doctrine, registry regeneration, changelog entries).

Golden rules: keep vendored files pristine — customisations live in wrapper components, which is what makes updates safe to apply automatically; use shadcn semantic classes (bg-primary, text-muted-foreground…); icons come from @untitledui/icons, never lucide; every surface must look right in both light-mode and dark-mode.

4 · Stay current

Install @nx-ui/nx-ui-doctor once, run lock straight after installing, and the update loop is four commands. Updates are pull-based and explicit — a registry change never breaks you silently, and sitting on an older version deliberately is fine (the lock records the choice).

bun lib/nx-ui-doctor.ts check          # which items are stale? (reads nx-ui.lock)
# → read the changelog entries for the stale items, then per item:
bunx shadcn@latest add @nx-ui/<item> --diff       # preview the change
bunx shadcn@latest add @nx-ui/<item> --overwrite  # apply (pristine files only)
bun lib/nx-ui-doctor.ts lock <item>               # record the new hash