cyberui-2045 2.3.1 → 2.4.0

package/AGENT.md

@@ -24,29 +24,31 @@ import "cyberui-2045/styles.css";
 
 ## 3. Component Reference
 
-| Component | Description |
-| :--- | :--- |
-| `Button` | Neon-styled button. Variants: `primary`, `secondary`, `danger`, `ghost`. |
-| `Card` | Glassmorphism container with borders. |
-| `Input` | Cyberpunk text input with focus glows. |
-| `Modal` | CRT-style modal dialog. |
-| `Notification` | Toast notifications. Use `useCyberNotifications` hook. |
-| `CircularProgress` | Dual-ring circular progress indicator. |
-| `LinearProgress` | Smooth horizontal progress bar. |
-| `SegmentedProgress` | Segmented progress: `variant="radial"` (circular arc gauge, default) or `variant="block"` (discrete filled blocks ▮▮▮▯▯). |
-| `TabNavigation` | Animated tab bar. |
-| `Badge` | Status indicator. Variants: `primary`, `secondary`, `accent`, `success`, `error`, `warning`. |
-| `Toggle` | Cyberpunk switch. |
-| `Select` | Styled dropdown. |
-| `Skeleton` | Loading placeholder. |
-| `Image` | Image with cyberpunk frame/effects. |
-| `Carousel` | Image carousel. |
-| `Checkbox` | Neon-styled checkbox with SVG icons. |
-| `Divider` | Gradient/solid/dashed content separator. |
-| `GradientText` | Text with cyberpunk gradient effects. |
-| `SectionTitle` | Title with decorative gradient line. |
-| `Steps` | Multi-step progress indicator. |
-| `Timeline` | Vertical event history display. |
+<!-- cyberui-2045:manifest:start -->
+| Component | Description |
+| :--- | :--- |
+| `Button` | Neon-styled button. Variants: `primary`, `secondary`, `danger`, `ghost`. |
+| `Input` | Cyberpunk text input with focus glows. |
+| `Toggle` | Cyberpunk switch. |
+| `Select` | Styled dropdown. |
+| `Checkbox` | Neon-styled checkbox with SVG icons. |
+| `Card` | Glassmorphism container with borders. |
+| `Modal` | CRT-style modal dialog. |
+| `Divider` | Gradient/solid/dashed content separator. |
+| `Notification` | Toast notifications. Use `useCyberNotifications` hook. |
+| `Badge` | Status indicator. Variants: `primary`, `secondary`, `accent`, `success`, `error`, `warning`. |
+| `Skeleton` | Loading placeholder. |
+| `CircularProgress` | Dual-ring circular progress indicator. |
+| `SegmentedProgress` | Segmented progress: `variant="radial"` (circular arc gauge, default) or `variant="block"` (discrete filled blocks ▮▮▮▯▯). |
+| `LinearProgress` | Smooth horizontal progress bar. |
+| `TabNavigation` | Animated tab bar. |
+| `Carousel` | Image carousel. |
+| `Steps` | Multi-step progress indicator. |
+| `GradientText` | Text with cyberpunk gradient effects. |
+| `SectionTitle` | Title with decorative gradient line. |
+| `Timeline` | Vertical event history display. |
+| `Image` | Image with cyberpunk frame/effects. |
+<!-- cyberui-2045:manifest:end -->
 
 ## 4. Usage Patterns (Few-Shot)
 

package/README.md

@@ -40,47 +40,50 @@ function App() {
 
 ## Components
 
-| Component | Category | Docs |
-|-----------|----------|------|
-| Button | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-button--docs) |
-| Input | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-input--docs) |
-| Select | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-select--docs) |
-| Toggle | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-toggle--docs) |
-| Card | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-card--docs) |
-| Modal | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-modal--docs) |
-| Badge | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-badge--docs) |
-| Notification | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-notification--docs) |
-| Skeleton | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-skeleton--docs) |
-| CircularProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-circularprogress--docs) |
-| LinearProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-linearprogress--docs) |
-| SegmentedProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-segmentedprogress--docs) |
-| TabNavigation | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-tabnavigation--docs) |
-| Carousel | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs) |
-| Steps | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs) |
-| Image | Media | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-image--docs) |
-| Checkbox | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-checkbox--docs) |
-| Divider | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-divider--docs) |
-| GradientText | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs) |
-| SectionTitle | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs) |
-| Timeline | Display | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs) |
-
-Also includes hooks (`useCyberNotifications`, `useAnimatedProgress`, `useCyberScrollbar`) and `CyberNotificationProvider` context.
+<!-- cyberui-2045:manifest:start -->
+| Component | Category | Docs |
+|-----------|----------|------|
+| Button | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-button--docs) |
+| Input | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-input--docs) |
+| Toggle | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-toggle--docs) |
+| Select | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-select--docs) |
+| Checkbox | Forms | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-checkbox--docs) |
+| Card | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-card--docs) |
+| Modal | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-modal--docs) |
+| Divider | Layout | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-divider--docs) |
+| Notification | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-notification--docs) |
+| Badge | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-badge--docs) |
+| Skeleton | Feedback | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-skeleton--docs) |
+| CircularProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-circularprogress--docs) |
+| SegmentedProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-segmentedprogress--docs) |
+| LinearProgress | Progress | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-linearprogress--docs) |
+| TabNavigation | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-tabnavigation--docs) |
+| Carousel | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs) |
+| Steps | Navigation | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs) |
+| GradientText | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs) |
+| SectionTitle | Typography | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs) |
+| Timeline | Display | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs) |
+| Image | Media | [→](https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-image--docs) |
+
+Also includes hooks (`useCyberScrollbar`, `useCyberNotifications`, `useAnimatedProgress`) and `CyberNotificationProvider` context.
+<!-- cyberui-2045:manifest:end -->
 
 ## AI Coding Setup
 
-If you use an AI coding assistant (Claude Code, Cursor, GitHub Copilot), run this once after installing:
+If you use an AI coding assistant (Claude Code, Cursor, GitHub Copilot, or any tool that reads the open `AGENTS.md` standard), run this once after installing:
 
 ```bash
 npx cyberui-2045 init
 ```
 
-It writes a concise CyberUI usage guide — components, hooks, tokens, and patterns — directly into your AI config file (`CLAUDE.md`, `.cursorrules`, or `.github/copilot-instructions.md`). Idempotent: safe to re-run after upgrades.
+It writes a concise CyberUI usage guide — components, hooks, tokens, and patterns — directly into your AI config file (`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, or `AGENTS.md`). Idempotent: safe to re-run after upgrades.
 
 ```bash
 npx cyberui-2045 init --claude    # Claude Code only
 npx cyberui-2045 init --cursor    # Cursor only
 npx cyberui-2045 init --copilot   # GitHub Copilot only
-npx cyberui-2045 init --all       # all three
+npx cyberui-2045 init --agents    # AGENTS.md standard only
+npx cyberui-2045 init --all       # all four
 npx cyberui-2045 init --dry-run   # preview without writing
 ```
 

package/bin/init.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { getUsageContent } from './usage-content.js';
+import { replaceMarkedBlock } from './markers.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -23,6 +24,10 @@ const TARGETS = {
     label: 'GitHub Copilot → .github/copilot-instructions.md',
     file: '.github/copilot-instructions.md',
   },
+  agents: {
+    label: 'AGENTS.md standard → AGENTS.md',
+    file: 'AGENTS.md',
+  },
 };
 
 // ─── Arg parsing ──────────────────────────────────────────────────────────────
@@ -37,6 +42,7 @@ if (args.includes('--all')) {
   if (args.includes('--claude')) selectedKeys.push('claude');
   if (args.includes('--cursor')) selectedKeys.push('cursor');
   if (args.includes('--copilot')) selectedKeys.push('copilot');
+  if (args.includes('--agents')) selectedKeys.push('agents');
 }
 
 // ─── Main ─────────────────────────────────────────────────────────────────────
@@ -51,6 +57,7 @@ async function main() {
       console.log('    npx cyberui-2045 init --claude');
       console.log('    npx cyberui-2045 init --cursor');
       console.log('    npx cyberui-2045 init --copilot');
+      console.log('    npx cyberui-2045 init --agents');
       console.log('    npx cyberui-2045 init --all\n');
       process.exit(0);
     }
@@ -123,7 +130,7 @@ function writeTarget(key) {
   const filePath = join(cwd, target.file);
 
   // Read current package version
-  let version = '1.3.2';
+  let version = '2.4.0';
   try {
     const pkgPath = new URL('../package.json', import.meta.url).pathname;
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
@@ -132,7 +139,8 @@ function writeTarget(key) {
     // fallback to hardcoded version
   }
 
-  const block = `${MARKER_START}\n${getUsageContent(version)}\n${MARKER_END}`;
+  const content = getUsageContent(version);
+  const block = `${MARKER_START}\n${content}\n${MARKER_END}`;
 
   if (isDryRun) {
     console.log(`  ── ${target.file} ──\n${block}\n`);
@@ -152,9 +160,7 @@ function writeTarget(key) {
 
     if (existing.includes(MARKER_START) && existing.includes(MARKER_END)) {
       // Replace existing section
-      const before = existing.slice(0, existing.indexOf(MARKER_START));
-      const after = existing.slice(existing.indexOf(MARKER_END) + MARKER_END.length);
-      finalContent = `${before}${block}${after}`;
+      finalContent = replaceMarkedBlock(existing, MARKER_START, MARKER_END, content);
       console.log(`  ✓  Updated  ${target.file}`);
     } else {
       // Append new section

package/bin/markers.js

@@ -0,0 +1,18 @@
+// Shared marker-block replace helper.
+// Used by bin/init.js (consumer-file injection) and scripts/generate-manifest.js
+// (this repo's own doc regeneration) to replace only the text between a pair of
+// HTML comment markers, leaving the rest of the file untouched.
+
+export const MANIFEST_MARKER_START = '<!-- cyberui-2045:manifest:start -->';
+export const MANIFEST_MARKER_END = '<!-- cyberui-2045:manifest:end -->';
+
+export function replaceMarkedBlock(content, startMarker, endMarker, block) {
+  const startIdx = content.indexOf(startMarker);
+  const endIdx = content.indexOf(endMarker);
+  if (startIdx === -1 || endIdx === -1) {
+    throw new Error(`Markers not found: ${startMarker} / ${endMarker}`);
+  }
+  const before = content.slice(0, startIdx);
+  const after = content.slice(endIdx + endMarker.length);
+  return `${before}${startMarker}\n${block}\n${endMarker}${after}`;
+}

package/bin/usage-content.js

@@ -1,210 +1,136 @@
-// Consumer-facing AI usage guide for cyberui-2045.
-// Injected into CLAUDE.md / .cursorrules / copilot-instructions.md by `init`.
-
-export function getUsageContent(version = '2.2.0') {
-  return `## CyberUI (cyberui-2045 v${version})
-
-Cyberpunk-themed React UI library. Docs & live examples: https://patrickkuei.github.io/CyberUI/storybook/
-
-### Setup
-
-\`\`\`bash
-npm install cyberui-2045
-\`\`\`
-
-\`\`\`tsx
-// ⚠️ REQUIRED: import styles once in your app entry (e.g. main.tsx / index.tsx)
-// Without this ALL components lose colors, backgrounds, and animations.
-import 'cyberui-2045/styles.css';
-
-// Import components — always from the root, never from subpaths
-import { Button, Card, Modal } from 'cyberui-2045';
-\`\`\`
-
-⚠️ Do NOT import from \`cyberui-2045/components/Button\` or similar subpaths — root only.
-⚠️ If styles look broken or text is invisible, \`cyberui-2045/styles.css\` is missing from the app entry.
-
-### Component Reference
-
-| Component | Category | Storybook |
-|-----------|----------|-----------|
-| Button | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-button--docs |
-| Input | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-input--docs |
-| Select | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-select--docs |
-| Toggle | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-toggle--docs |
-| Checkbox | Forms | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-checkbox--docs |
-| Card | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-card--docs |
-| Modal | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-modal--docs |
-| Divider | Layout | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-divider--docs |
-| Badge | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-badge--docs |
-| Notification | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-notification--docs |
-| Skeleton | Feedback | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-skeleton--docs |
-| CircularProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-circularprogress--docs |
-| LinearProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-linearprogress--docs |
-| SegmentedProgress | Progress | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-segmentedprogress--docs |
-| TabNavigation | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-tabnavigation--docs |
-| Carousel | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-carousel--docs |
-| Steps | Navigation | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-steps--docs |
-| GradientText | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-gradienttext--docs |
-| SectionTitle | Typography | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-sectiontitle--docs |
-| Timeline | Display | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-timeline--docs |
-| Image | Media | https://patrickkuei.github.io/CyberUI/storybook/?path=/docs/components-image--docs |
-
-### Critical API notes (read before coding)
-
-\`\`\`tsx
-// Button — variants: 'primary' | 'secondary' | 'danger' | 'ghost'  (NO 'accent')
-<Button variant="primary">Jack In</Button>
-<Button variant="danger">Purge</Button>
-
-// Badge — uses children, NOT a label prop
-<Badge variant="success">Online</Badge>
-<Badge variant="error">Offline</Badge>
-// variants: 'primary' | 'secondary' | 'accent' | 'success' | 'error' | 'warning'
-
-// CircularProgress — use size prop (sm/md/lg/xl); prop is 'progress' not 'value'
-// center content goes as children; do NOT pass a large radius — default 20 is correct
-<CircularProgress progress={75} size="md">
-  <span className="text-xs font-mono text-accent">75%</span>
-</CircularProgress>
-
-// LinearProgress — prop is 'progress' (not 'value'); fills container width (w-full) by default
-// wrap in a constrained div to control width
-<LinearProgress progress={60} />
-<div className="w-64"><LinearProgress progress={60} /></div>
-
-// SegmentedProgress — two variants:
-//   variant="radial" (default): circular arc-segment gauge; children render in the center
-//   variant="block": linear discrete-block bar (▮▮▮▯▯); use segments prop (default 10)
-// Both support size prop (sm/md/lg/xl)
-<SegmentedProgress progress={80} size="md">
-  <span className="text-accent font-bold text-xs">80%</span>
-</SegmentedProgress>
-<SegmentedProgress variant="block" progress={60} segments={10} size="md" />
-
-// TabNavigation — tabs is a plain string array (NOT {id, label}[])
-<TabNavigation
-  tabs={['Overview', 'Stats', 'History']}
-  activeTab="Overview"
-  onTabChange={setTab}
-/>
-
-// SectionTitle — NO subtitle prop; use children for the heading text
-<SectionTitle>System Status</SectionTitle>
-
-// Select — use onValueChange for a simple string callback (like Toggle/Checkbox pattern)
-// or use standard HTML onChange for the raw event
-<Select
-  options={[{ value: 'a', label: 'Option A' }]}
-  onValueChange={(val) => setSelected(val)}
-/>
-
-// Toggle — onChange receives boolean directly
-<Toggle checked={on} onChange={setOn} />
-
-// Checkbox — use onCheckedChange for a simple boolean callback
-<Checkbox checked={val} onCheckedChange={setVal} />
-
-// Modal — default size is 'lg' (672px); use 'xl' for forms/tables, 'sm' only for simple alerts
-// variant="danger" for destructive confirmations
-<Modal title="Settings" size="lg" isOpen={open} onClose={close}>
-  content here
-</Modal>
-<Modal variant="danger" title="Delete?" size="md" onConfirm={handleDelete} onCancel={close}>
-  This cannot be undone.
-</Modal>
-
-// Card — supports onClick and all standard div HTML attributes
-<Card onClick={() => select(item)}>content</Card>
-
-// Image — preview={true} must be explicit to enable click-to-expand fullscreen (disabled by default)
-<Image src="/photo.jpg" alt="Description" size="md" preview={true} />
-
-// Carousel — images takes CarouselImageData[]: { src, alt, fallbackSrc?, caption? }
-<Carousel
-  images={[
-    { src: 'img1.jpg', alt: 'Cyber City', caption: 'Night District' },
-    { src: 'img2.jpg', alt: 'Neon Lights', fallbackSrc: 'fallback.jpg' }
-  ]}
-  currentIndex={idx}
-  onIndexChange={setIdx}
-/>
-
-// Steps — current is 0-BASED. First step = current={0}, second = current={1}.
-// Passing 1-based values is a common mistake that skips the first step.
-<Steps
-  current={0}
-  items={[{ title: 'Login' }, { title: 'Verify' }, { title: 'Complete' }]}
-/>
-\`\`\`
-
-### Hooks
-
-\`\`\`tsx
-import { useCyberNotifications, useAnimatedProgress, useCyberScrollbar } from 'cyberui-2045';
-
-// Toast notifications — showNotification(type, title, message, options?)
-// type: 'success' | 'warning' | 'error'
-const { showNotification } = useCyberNotifications();
-showNotification('success', 'Access Granted', 'Welcome back, runner.');
-showNotification('error', 'Breach Detected', 'Sector 7 compromised.', { duration: 5000 });
-
-// Oscillating value for loading/pulse animations (min → max → min loop)
-const value = useAnimatedProgress({ min: 5, max: 95, speed: 30 });
-
-// Apply cyberpunk scrollbar styles to a scrollable element
-const ref = useCyberScrollbar<HTMLDivElement>();
-\`\`\`
-
-### Notifications (requires provider)
-
-\`\`\`tsx
-import { CyberNotificationProvider, useCyberNotifications } from 'cyberui-2045';
-
-// Wrap your app once
-<CyberNotificationProvider>
-  <App />
-</CyberNotificationProvider>
-
-// Then anywhere inside:
-const { showNotification } = useCyberNotifications();
-showNotification('success', 'Upload Complete', 'Neural data synced.');
-\`\`\`
-
-### Theming — CSS token overrides
-
-Override in your global CSS (after importing cyberui-2045/styles.css):
-
-\`\`\`css
-:root {
-  --color-primary: #ff005d;        /* neon pink  */
-  --color-secondary: #00fff9;      /* cyan       */
-  --color-accent: #fffb00;         /* yellow     */
-  --color-success: #00ff9e;        /* green      */
-  --color-error: #ff4f4f;          /* red        */
-  --color-warning: #ffaa00;        /* orange     */
-  --color-base: #1a1a2e;           /* page background */
-  --color-surface: #2d2d44;        /* card / component surface */
-  --color-border-default: #3c3c5e; /* borders    */
-  --color-default: #e0e0e0;        /* primary text */
-  --color-muted: #8888aa;          /* secondary text */
-  --color-inverse: #1a1a2e;        /* inverted text */
-}
-\`\`\`
-
-### className overrides
-
-All components accept a \`className\` prop merged via \`tailwind-merge\` — your classes win on conflict.
-
-\`\`\`tsx
-<Button className="w-full mt-4">Full width</Button>
-\`\`\`
-
-### cn() utility (re-exported)
-
-\`\`\`tsx
-import { cn } from 'cyberui-2045';
-// clsx + tailwind-merge — compose className strings in your own components
-const cls = cn('base-class', isActive && 'active', className);
-\`\`\``;
-}
+// Consumer-facing AI usage guide for cyberui-2045.
+// Injected into CLAUDE.md / .cursorrules / copilot-instructions.md by `init`.
+
+export function getUsageContent(version = '2.4.0') {
+  return `## CyberUI (cyberui-2045 v${version})
+
+Cyberpunk-themed React UI library. Docs & live examples: https://patrickkuei.github.io/CyberUI/storybook/
+
+### Setup
+
+\`\`\`bash
+npm install cyberui-2045
+\`\`\`
+
+\`\`\`tsx
+// ⚠️ REQUIRED: import styles once in your app entry (e.g. main.tsx / index.tsx)
+// Without this ALL components lose colors, backgrounds, and animations.
+import 'cyberui-2045/styles.css';
+
+// Import components — always from the root, never from subpaths
+import { Button, Card, Modal } from 'cyberui-2045';
+\`\`\`
+
+⚠️ Do NOT import from \`cyberui-2045/components/Button\` or similar subpaths — root only.
+⚠️ If styles look broken or text is invisible, \`cyberui-2045/styles.css\` is missing from the app entry.
+
+### Component Reference
+
+Paths below are relative to \`node_modules/cyberui-2045/\`.
+
+<!-- cyberui-2045:manifest:start -->
+| Component | Category | Types |
+|-----------|----------|-------|
+| Button | Forms | \`dist/components/Button.d.ts\` |
+| Input | Forms | \`dist/components/Input.d.ts\` |
+| Toggle | Forms | \`dist/components/Toggle.d.ts\` |
+| Select | Forms | \`dist/components/Select.d.ts\` |
+| Checkbox | Forms | \`dist/components/Checkbox.d.ts\` |
+| Card | Layout | \`dist/components/Card.d.ts\` |
+| Modal | Layout | \`dist/components/Modal.d.ts\` |
+| Divider | Layout | \`dist/components/Divider.d.ts\` |
+| Notification | Feedback | \`dist/components/Notification.d.ts\` |
+| Badge | Feedback | \`dist/components/Badge.d.ts\` |
+| Skeleton | Feedback | \`dist/components/Skeleton.d.ts\` |
+| CircularProgress | Progress | \`dist/components/CircularProgress.d.ts\` |
+| SegmentedProgress | Progress | \`dist/components/SegmentedProgress.d.ts\` |
+| LinearProgress | Progress | \`dist/components/LinearProgress.d.ts\` |
+| TabNavigation | Navigation | \`dist/components/TabNavigation.d.ts\` |
+| Carousel | Navigation | \`dist/components/Carousel.d.ts\` |
+| Steps | Navigation | \`dist/components/Steps.d.ts\` |
+| GradientText | Typography | \`dist/components/GradientText.d.ts\` |
+| SectionTitle | Typography | \`dist/components/SectionTitle.d.ts\` |
+| Timeline | Display | \`dist/components/Timeline.d.ts\` |
+| Image | Media | \`dist/components/Image.d.ts\` |
+<!-- cyberui-2045:manifest:end -->
+
+### Critical API notes
+
+Every prop carries full JSDoc (types, \`@default\`, gotchas) — hover it in your editor or read
+\`node_modules/cyberui-2045/dist/index.d.ts\` before using an unfamiliar component. Don't guess.
+
+Only cross-cutting facts that don't belong to any single component's own types are listed here:
+
+- \`Button\` variants: \`primary | secondary | danger | ghost\`. \`Badge\` variants: \`primary | secondary | accent | success | error | warning\`. Different sets — \`Button\` has no \`accent\`, \`Badge\` has no \`danger\`. Easy to mix up since both are status/action-ish components.
+- Full machine-readable prop reference for all 21 components + hooks: \`node_modules/cyberui-2045/dist/component-manifest.json\`. Grep it for a component name before writing code against it if you're not confident of its exact props.
+
+### Hooks
+
+\`\`\`tsx
+import { useCyberNotifications, useAnimatedProgress, useCyberScrollbar } from 'cyberui-2045';
+
+// Toast notifications — showNotification(type, title, message, options?)
+// type: 'success' | 'warning' | 'error'
+const { showNotification } = useCyberNotifications();
+showNotification('success', 'Access Granted', 'Welcome back, runner.');
+showNotification('error', 'Breach Detected', 'Sector 7 compromised.', { duration: 5000 });
+
+// Oscillating value for loading/pulse animations (min → max → min loop)
+const value = useAnimatedProgress({ min: 5, max: 95, speed: 30 });
+
+// Apply cyberpunk scrollbar styles to a scrollable element
+const ref = useCyberScrollbar<HTMLDivElement>();
+\`\`\`
+
+### Notifications (requires provider)
+
+\`\`\`tsx
+import { CyberNotificationProvider, useCyberNotifications } from 'cyberui-2045';
+
+// Wrap your app once
+<CyberNotificationProvider>
+  <App />
+</CyberNotificationProvider>
+
+// Then anywhere inside:
+const { showNotification } = useCyberNotifications();
+showNotification('success', 'Upload Complete', 'Neural data synced.');
+\`\`\`
+
+### Theming — CSS token overrides
+
+Override in your global CSS (after importing cyberui-2045/styles.css):
+
+\`\`\`css
+:root {
+  --color-primary: #ff005d;        /* neon pink  */
+  --color-secondary: #00fff9;      /* cyan       */
+  --color-accent: #fffb00;         /* yellow     */
+  --color-success: #00ff9e;        /* green      */
+  --color-error: #ff4f4f;          /* red        */
+  --color-warning: #ffaa00;        /* orange     */
+  --color-base: #1a1a2e;           /* page background */
+  --color-surface: #2d2d44;        /* card / component surface */
+  --color-border-default: #3c3c5e; /* borders    */
+  --color-default: #e0e0e0;        /* primary text */
+  --color-muted: #8888aa;          /* secondary text */
+  --color-inverse: #1a1a2e;        /* inverted text */
+}
+\`\`\`
+
+### className overrides
+
+All components accept a \`className\` prop merged via \`tailwind-merge\` — your classes win on conflict.
+
+\`\`\`tsx
+<Button className="w-full mt-4">Full width</Button>
+\`\`\`
+
+### cn() utility (re-exported)
+
+\`\`\`tsx
+import { cn } from 'cyberui-2045';
+// clsx + tailwind-merge — compose className strings in your own components
+const cls = cn('base-class', isActive && 'active', className);
+\`\`\``;
+}