create-xani-agentic-app 1.0.0

package/template/.agents/skills/security-scanner/references/A10-mishandling-exceptional-conditions.md

@@ -0,0 +1,154 @@
+# A10:2025 — Mishandling of Exceptional Conditions
+
+## Overview
+
+Mishandling of Exceptional Conditions is #10 in OWASP Top 10:2025 — a newly introduced category. It covers 24 CWEs with 769,581 total occurrences and 3,416 CVEs. This category addresses deficiencies in error management: programs that fail to prevent, detect, or respond to unusual and unpredictable situations. These failures threaten confidentiality (info disclosure), availability (denial of service), and integrity (data corruption).
+
+## Key CWEs
+
+- **CWE-209**: Generation of Error Message Containing Sensitive Information
+- **CWE-234**: Failure to Handle Missing Parameter
+- **CWE-274**: Improper Handling of Insufficient Privileges
+- **CWE-280**: Improper Handling of Insufficient Permissions
+- **CWE-476**: NULL Pointer Dereference
+- **CWE-636**: Not Failing Securely (Fail-Open)
+- **CWE-252**: Unchecked Return Value
+- **CWE-754**: Improper Check for Unusual or Exceptional Conditions
+- **CWE-755**: Improper Handling of Exceptional Conditions
+
+## What to Look For
+
+### General Patterns
+- Empty catch blocks that swallow errors silently
+- Generic error handling that hides root causes
+- Missing error handling on async operations (unhandled promise rejections)
+- Error responses that expose stack traces, SQL queries, or internal paths to users
+- Fail-open patterns: errors cause the system to grant access instead of denying it
+- Unchecked return values from security-critical functions
+- Missing error handling on file I/O, network calls, database operations
+- Partial transaction failures without rollback
+- Resource leaks when exceptions occur (file handles, DB connections, memory)
+- Missing global/unhandled exception handlers
+- Inconsistent error handling across the application
+
+### Grep Patterns
+
+```
+# Empty catch blocks
+catch\s*\([^)]*\)\s*\{\s*\}|catch\s*\(\s*\)\s*:|except\s*:.*pass
+catch.*\{\s*\/\/|catch.*\{\s*\n\s*\}
+
+# Stack trace / internal info exposure
+err\.stack|error\.stack|e\.getStackTrace|traceback
+err\.message|error\.message|e\.getMessage
+res\.json.*err|response.*stack|render.*error
+
+# Fail-open patterns
+catch.*return true|catch.*allow|catch.*grant|catch.*next\(\)
+catch.*continue|on_error.*pass|rescue.*true
+
+# Unhandled async
+\.then\((?!.*\.catch)|async.*(?!try)
+unhandledRejection|uncaughtException
+
+# Unchecked returns
+=\s*(await\s+)?.*\(.*\)\s*;?\s*$(?!.*if|.*\?|.*throw|.*return)
+
+# Resource cleanup
+finally|dispose|close|cleanup|release
+try.*open|try.*connect|try.*acquire
+```
+
+### JavaScript / TypeScript / Node.js
+- `catch (e) {}` — empty catch block, error silently swallowed
+- `catch (e) { return res.json({ error: e.message, stack: e.stack }) }` — info disclosure
+- Missing `.catch()` on Promises or missing try/catch around `await`
+- Express error middleware missing or exposing internals
+- `process.on('uncaughtException')` handler missing
+- Database/file operations without try/catch in async handlers
+
+### Python (Django/Flask)
+- `except: pass` or `except Exception: pass` — swallowing all errors
+- `traceback.format_exc()` returned in HTTP response
+- Missing `finally` blocks for resource cleanup
+- Django `DEBUG = True` in production exposing full tracebacks
+
+### Java (Spring)
+- Empty catch blocks: `catch (Exception e) {}`
+- `e.printStackTrace()` in production code
+- Missing `@ControllerAdvice` global exception handler
+- `@ExceptionHandler` returning `e.getMessage()` to client
+
+## Prevention Measures
+
+1. Catch and handle errors at their point of origin with meaningful responses
+2. Provide user-friendly error messages — never expose internal details
+3. Log all errors with sufficient context for debugging
+4. Use global exception handlers as a safety net for unhandled errors
+5. Roll back transactions completely on failure — no partial state
+6. Apply rate limiting and resource quotas to prevent resource exhaustion
+7. Implement proper resource cleanup in `finally` blocks
+8. Default to deny (fail-closed) — never grant access on error
+9. Conduct stress testing and penetration testing to find edge cases
+10. Aggregate repeated identical errors as statistics to prevent log flooding
+
+## Example Attack Scenarios
+
+**Scenario 1 — Denial of Service:** File upload exception leaves resources unreleased. Repeated uploads exhaust system resources, causing downtime until restart.
+
+**Scenario 2 — Information Disclosure:** Database error message exposes table names, column names, and query structure. Attacker uses this to craft targeted SQL injection attacks.
+
+**Scenario 3 — Financial Transaction Compromise:** Network interruption during multi-step transfer. Missing rollback allows attacker to drain accounts or create duplicate transfers.
+
+## Fix Examples
+
+**Before (empty catch + info disclosure):**
+```typescript
+try {
+  const results = db.all(query);
+  return Response.json(results);
+} catch (e) {
+  return Response.json({ error: e.message, sql: query, stack: e.stack });
+}
+```
+
+**After (proper error handling):**
+```typescript
+try {
+  const results = db.all(query);
+  return Response.json(results);
+} catch (e) {
+  logger.error('Database query failed', { error: e.message, query, stack: e.stack });
+  return Response.json({ error: 'An internal error occurred' }, { status: 500 });
+}
+```
+
+**Before (fail-open):**
+```typescript
+try {
+  const isAuthorized = await checkPermission(user, resource);
+  if (!isAuthorized) return deny();
+} catch (e) {
+  // Auth service is down, let them through
+}
+return allow();
+```
+
+**After (fail-closed):**
+```typescript
+try {
+  const isAuthorized = await checkPermission(user, resource);
+  if (!isAuthorized) return deny();
+  return allow();
+} catch (e) {
+  logger.error('Authorization check failed', { user: user.id, resource, error: e.message });
+  return deny(); // Default to deny on error
+}
+```
+
+## References
+
+- [OWASP A10:2025](https://owasp.org/Top10/2025/A10_2025-Mishandling_of_Exceptional_Conditions/)
+- OWASP Error Handling Cheat Sheet
+- OWASP Logging Cheat Sheet
+- OWASP ASVS V16.5 Error Handling

package/template/.agents/skills/security-scanner/references/report-template.md

@@ -0,0 +1,148 @@
+# Security Audit Report
+
+**Project:** [PROJECT_NAME]
+**Date:** [YYYY-MM-DD]
+**Auditor:** Claude Code Security Scanner
+**Framework:** OWASP Top 10:2025
+**Scope:** [LIST_OF_DIRECTORIES_AND_FILES_ANALYZED]
+**Technology Stack:** [LANGUAGES_FRAMEWORKS_DETECTED]
+
+---
+
+## Executive Summary
+
+[2-3 paragraph overview: what was analyzed, key risk areas found, overall risk posture, most urgent items to address]
+
+**Overall Risk Score:** [SCORE] ([Low/Moderate/High/Critical] Risk)
+
+| Severity | Count |
+|----------|-------|
+| Critical | [X]   |
+| High     | [X]   |
+| Medium   | [X]   |
+| Low      | [X]   |
+| Info     | [X]   |
+| **Total**| **[X]** |
+
+---
+
+## Findings
+
+### A01:2025 — Broken Access Control
+
+[If findings exist, list each one using the format below. If no findings, write: "No issues identified. Checked: [list what was checked]."]
+
+#### [SEVERITY] [Finding Title]
+- **File:** `[path/to/file.ext]`
+- **Line(s):** [XX-YY]
+- **CWE:** [CWE-XXX: Name]
+- **Description:** [What the vulnerability is and why it matters]
+- **Evidence:**
+  ```[language]
+  // vulnerable code snippet from the actual codebase
+  ```
+- **Recommendation:**
+  ```[language]
+  // fixed code snippet showing the remediation
+  ```
+
+---
+
+### A02:2025 — Security Misconfiguration
+
+[Same format as above]
+
+---
+
+### A03:2025 — Software Supply Chain Failures
+
+[Same format as above]
+
+---
+
+### A04:2025 — Cryptographic Failures
+
+[Same format as above]
+
+---
+
+### A05:2025 — Injection
+
+[Same format as above]
+
+---
+
+### A06:2025 — Insecure Design
+
+[Same format as above]
+
+---
+
+### A07:2025 — Authentication Failures
+
+[Same format as above]
+
+---
+
+### A08:2025 — Software or Data Integrity Failures
+
+[Same format as above]
+
+---
+
+### A09:2025 — Security Logging and Alerting Failures
+
+[Same format as above]
+
+---
+
+### A10:2025 — Mishandling of Exceptional Conditions
+
+[Same format as above]
+
+---
+
+## Risk Score Breakdown
+
+Scoring: Critical = 10 pts, High = 7 pts, Medium = 4 pts, Low = 2 pts, Info = 0 pts.
+
+| Category | Critical | High | Medium | Low | Info | Points |
+|----------|----------|------|--------|-----|------|--------|
+| A01 — Broken Access Control        | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A02 — Security Misconfiguration    | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A03 — Supply Chain Failures        | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A04 — Cryptographic Failures       | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A05 — Injection                    | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A06 — Insecure Design              | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A07 — Authentication Failures      | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A08 — Data Integrity Failures      | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A09 — Logging & Alerting Failures  | [X] | [X] | [X] | [X] | [X] | [XX] |
+| A10 — Exceptional Conditions       | [X] | [X] | [X] | [X] | [X] | [XX] |
+| **Total**                           |     |     |     |     |     | **[XX]** |
+
+**Risk Rating:** 0-10 = Low | 11-30 = Moderate | 31-60 = High | 61+ = Critical
+
+---
+
+## Remediation Priority
+
+[Ordered list of the most critical items to fix first, with brief rationale]
+
+1. **[Most critical finding]** — [why this is urgent and what to do]
+2. **[Second most critical]** — [why and what]
+3. **[Third most critical]** — [why and what]
+[Continue as needed...]
+
+---
+
+## Methodology
+
+This audit was performed using static analysis against the OWASP Top 10:2025 framework. Each category was evaluated using pattern-matching (grep), code review (file reading), dependency analysis, and configuration inspection. The analysis covered source code, configuration files, dependency manifests, and environment settings.
+
+**Limitations:** This is a static analysis — it does not include dynamic/runtime testing, penetration testing, or network-level analysis. Some vulnerabilities may only be discoverable through dynamic testing.
+
+## References
+
+- [OWASP Top 10:2025](https://owasp.org/Top10/2025/)
+- [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/)
+- [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/)

package/template/.agents/skills/shadcn/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: shadcn
+description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
+user-invocable: false
+allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
+---
+
+# shadcn/ui
+
+A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+```json
+!`npx shadcn@latest info --json`
+```
+
+The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
+
+## Principles
+
+1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`className` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast via `sonner`.** Use `toast()` from `sonner`.
+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.
+
+### CLI
+
+- **Never decode or fetch preset codes manually.** Pass them directly to `npx shadcn@latest apply --preset <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
+
+```tsx
+// Form layout: FieldGroup + Field, not div + Label.
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+// Validation: data-invalid on Field, aria-invalid on the control.
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes.
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+// Spacing: gap-*, not space-y-*.
+<div className="flex flex-col gap-4">  // correct
+<div className="space-y-4">           // wrong
+
+// Equal dimensions: size-*, not w-* h-*.
+<Avatar className="size-10">   // correct
+<Avatar className="w-10 h-10"> // wrong
+
+// Status colors: Badge variants or semantic tokens, not raw colors.
+<Badge variant="secondary">+20.1%</Badge>    // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                        |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (wraps Recharts)                                                                            |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+
+## Key Fields
+
+The injected project context contains these key fields:
+
+- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
+- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.
+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
+- **`style`** → component visual treatment (e.g. `nova`, `vega`).
+- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
+- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
+- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
+- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
+
+See [cli.md — `info` command](./cli.md) for the full field reference.
+
+## Component Docs, Examples, and Usage
+
+Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+
+```bash
+npx shadcn@latest docs button dialog select
+```
+
+**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+
+## Workflow
+
+1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
+3. **Find components** — `npx shadcn@latest search`.
+4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
+9. **Switching presets** — Ask the user first: **overwrite**, **merge**, or **skip**?
+   - **Overwrite**: `npx shadcn@latest apply --preset <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
+
+## Updating Components
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
+
+1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
+3. Decide per file based on the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
+   - User says "just update everything" → use `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Create a new project.
+npx shadcn@latest init --name my-app --preset base-nova
+npx shadcn@latest init --name my-app --preset a2r6bw --template vite
+
+# Create a monorepo project.
+npx shadcn@latest init --name my-app --preset base-nova --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
+
+# Initialize existing project.
+npx shadcn@latest init --preset base-nova
+npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+
+# Apply a preset to an existing project.
+npx shadcn@latest apply --preset a2r6bw
+npx shadcn@latest apply a2r6bw
+
+# Add components.
+npx shadcn@latest add button card dialog
+npx shadcn@latest add @magicui/shimmer-button
+npx shadcn@latest add --all
+
+# Preview changes before adding/updating.
+npx shadcn@latest add button --dry-run
+npx shadcn@latest add button --diff button.tsx
+npx shadcn@latest add @acme/form --view button.tsx
+
+# Search registries.
+npx shadcn@latest search @shadcn -q "sidebar"
+npx shadcn@latest search @tailark -q "stats"
+
+# Get component docs and example URLs.
+npx shadcn@latest docs button dialog select
+
+# View registry item details (for items not yet installed).
+npx shadcn@latest view @shadcn/button
+```
+
+**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com).
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
+- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
+- [cli.md](./cli.md) — Commands, flags, presets, templates
+- [customization.md](./customization.md) — Theming, CSS variables, extending components

package/template/.agents/skills/shadcn/agents/openai.yml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "shadcn/ui"
+  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
+  icon_small: "./assets/shadcn-small.png"
+  icon_large: "./assets/shadcn.png"