ns-ui: Instructions file for Codex

AGENTS.md — working inside this repo

Reference for an agent editing ns-ui itself. Two other documents may be the one you want:

• Consuming a component in some other project → https://design.helpmarq.com/llms.txt, or the README. There's also an MCP server (mcp/) and a CLI (cli/) — both optional, neither required to install a component; see https://design.helpmarq.com/connect for per-client config and current publish status.
• Setup, the add-a-component walkthrough, the token rule, and how to open a PR → CONTRIBUTING.md. That is the shared ground for humans and agents, and it is shorter.

What follows is the detail CONTRIBUTING.md deliberately leaves out: the autoplay, useWhen and gate descriptor schemas, how prop signatures are extracted for llms.txt, and the constraints in the preview driver that are easy to regress. Read the section you need, not the whole file.

Structure

Each component is a self-contained folder: registry/{core,loud}/<name>/ with:

• component.tsx — the actual component. "use client", zero or minimal deps, tokens not hex.
• demo.tsx — the preview render used by /components/<name> and the /preview/<name> screenshot-verifier fixture.
• meta.json — the single source of truth: name, title, description, collection, tags, instruction (a rich paragraph describing behavior — read by scripts/build-llms.ts), dependencies, the optional site-only autoplay descriptor (see below) that makes the landing-page card demonstrate itself, and the optional site-only useWhen override (see below) for llms.txt's "use when" line.
• screenshots/ — generated by npm run verify, not hand-authored.

core = Geist-dark restraint. loud = deliberately flashy showcase. Collection is decided at creation time and drives folder placement, not a runtime flag. Current counts drift by the day — read them from README.md (generated from registry.json on every build) rather than trusting a number here.