zugzbot 1.0.20 → 1.0.22

package/.opencode/docs/shadcn/customization.md

@@ -1,209 +0,0 @@
-# Customization & Theming
-
-Components reference semantic CSS variable tokens. Change the variables to change every component.
-
-## Contents
-
-- How it works (CSS variables → Tailwind utilities → components)
-- Color variables and OKLCH format
-- Dark mode setup
-- Changing the theme (presets, CSS variables)
-- Adding custom colors (Tailwind v3 and v4)
-- Border radius
-- Customizing components (variants, className, wrappers)
-- Checking for updates
-
----
-
-## How It Works
-
-1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
-2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
-3. Components use these utilities — changing a variable changes all components that reference it.
-
----
-
-## Color Variables
-
-Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
-
-| Variable                                     | Purpose                          |
-| -------------------------------------------- | -------------------------------- |
-| `--background` / `--foreground`              | Page background and default text |
-| `--card` / `--card-foreground`               | Card surfaces                    |
-| `--primary` / `--primary-foreground`         | Primary buttons and actions      |
-| `--secondary` / `--secondary-foreground`     | Secondary actions                |
-| `--muted` / `--muted-foreground`             | Muted/disabled states            |
-| `--accent` / `--accent-foreground`           | Hover and accent states          |
-| `--destructive` / `--destructive-foreground` | Error and destructive actions    |
-| `--border`                                   | Default border color             |
-| `--input`                                    | Form input borders               |
-| `--ring`                                     | Focus ring color                 |
-| `--chart-1` through `--chart-5`              | Chart/data visualization         |
-| `--sidebar-*`                                | Sidebar-specific colors          |
-| `--surface` / `--surface-foreground`         | Secondary surface                |
-
-Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
-
----
-
-## Dark Mode
-
-Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
-
-```tsx
-import { ThemeProvider } from "next-themes"
-
-<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-  {children}
-</ThemeProvider>
-```
-
----
-
-## Changing the Theme
-
-```bash
-# Apply a preset code from ui.shadcn.com.
-npx shadcn@latest apply --preset a2r6bw
-
-# Positional shorthand also works.
-npx shadcn@latest apply a2r6bw
-
-# Switch to a named preset and overwrite existing components.
-npx shadcn@latest apply --preset nova
-
-# Preserve existing components instead.
-npx shadcn@latest init --preset nova --force --no-reinstall
-
-# Use a custom theme URL.
-npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."
-```
-
-Or edit CSS variables directly in `globals.css`.
-
----
-
-## Adding Custom Colors
-
-Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
-
-```css
-/* 1. Define in the global CSS file. */
-:root {
-  --warning: oklch(0.84 0.16 84);
-  --warning-foreground: oklch(0.28 0.07 46);
-}
-.dark {
-  --warning: oklch(0.41 0.11 46);
-  --warning-foreground: oklch(0.99 0.02 95);
-}
-```
-
-```css
-/* 2a. Register with Tailwind v4 (@theme inline). */
-@theme inline {
-  --color-warning: var(--warning);
-  --color-warning-foreground: var(--warning-foreground);
-}
-```
-
-When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
-
-```js
-// 2b. Register with Tailwind v3 (tailwind.config.js).
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        warning: "oklch(var(--warning) / <alpha-value>)",
-        "warning-foreground":
-          "oklch(var(--warning-foreground) / <alpha-value>)",
-      },
-    },
-  },
-}
-```
-
-```tsx
-// 3. Use in components.
-<div className="bg-warning text-warning-foreground">Warning</div>
-```
-
----
-
-## Border Radius
-
-`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
-
----
-
-## Customizing Components
-
-See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
-
-Prefer these approaches in order:
-
-### 1. Built-in variants
-
-```tsx
-<Button variant="outline" size="sm">
-  Click
-</Button>
-```
-
-### 2. Tailwind classes via `className`
-
-```tsx
-<Card className="mx-auto max-w-md">...</Card>
-```
-
-### 3. Add a new variant
-
-Edit the component source to add a variant via `cva`:
-
-```tsx
-// components/ui/button.tsx
-warning: "bg-warning text-warning-foreground hover:bg-warning/90",
-```
-
-### 4. Wrapper components
-
-Compose shadcn/ui primitives into higher-level components:
-
-```tsx
-export function ConfirmDialog({ title, description, onConfirm, children }) {
-  return (
-    <AlertDialog>
-      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
-      <AlertDialogContent>
-        <AlertDialogHeader>
-          <AlertDialogTitle>{title}</AlertDialogTitle>
-          <AlertDialogDescription>{description}</AlertDialogDescription>
-        </AlertDialogHeader>
-        <AlertDialogFooter>
-          <AlertDialogCancel>Cancel</AlertDialogCancel>
-          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
-        </AlertDialogFooter>
-      </AlertDialogContent>
-    </AlertDialog>
-  )
-}
-```
-
----
-
-## Checking for Updates
-
-```bash
-npx shadcn@latest add button --diff
-```
-
-To preview exactly what would change before updating, use `--dry-run` and `--diff`:
-
-```bash
-npx shadcn@latest add button --dry-run        # see all affected files
-npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
-```
-
-See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.

package/.opencode/docs/shadcn/evals/evals.json

@@ -1,47 +0,0 @@
-{
-  "skill_name": "shadcn",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
-      "expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
-      "files": [],
-      "expectations": [
-        "Uses FieldGroup and Field components for form layout instead of raw div with space-y",
-        "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
-        "Uses data-invalid on Field and aria-invalid on the input control for validation states",
-        "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
-        "Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
-        "No manual dark: color overrides"
-      ]
-    },
-    {
-      "id": 2,
-      "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
-      "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
-      "files": [],
-      "expectations": [
-        "Includes DialogTitle for accessibility (visible or with sr-only class)",
-        "Avatar component includes AvatarFallback",
-        "Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
-        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
-        "Uses tabler icons (@tabler/icons-react) instead of lucide-react",
-        "Uses asChild for custom triggers (radix preset)"
-      ]
-    },
-    {
-      "id": 3,
-      "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
-      "expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
-      "files": [],
-      "expectations": [
-        "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
-        "Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
-        "Uses Badge component for percentage change instead of custom styled spans",
-        "Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
-        "Uses gap-* instead of space-y-* or space-x-* for spacing",
-        "Uses size-* when width and height are equal instead of separate w-* h-*"
-      ]
-    }
-  ]
-}

package/.opencode/docs/shadcn/mcp.md

@@ -1,105 +0,0 @@
-# shadcn MCP Server
-
-The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
-
----
-
-## Setup
-
-```bash
-shadcn mcp        # start the MCP server (stdio)
-shadcn mcp init   # write config for your editor
-```
-
-Editor config files:
-
-| Editor      | Config file                     |
-| ----------- | ------------------------------- |
-| Claude Code | `.mcp.json`                     |
-| Cursor      | `.cursor/mcp.json`              |
-| VS Code     | `.vscode/mcp.json`              |
-| OpenCode    | `opencode.json`                 |
-| Codex       | `~/.codex/config.toml` (manual) |
-
----
-
-## Tools
-
-> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
-
-### `shadcn:get_project_registries`
-
-Returns registry names from `components.json`. Errors if no `components.json` exists.
-
-**Input:** none
-
-### `shadcn:list_items_in_registries`
-
-Lists all items from one or more registries. Registries can be configured
-namespaces such as `@acme`, public GitHub sources such as `owner/repo`, or
-registry catalog URLs. Omit `registries` to list from every registry configured
-in `components.json`.
-
-**Input:** `registries` (string[], optional — omit for all configured), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
-
-### `shadcn:search_items_in_registries`
-
-Fuzzy search across registries. Registries can be configured namespaces, public
-GitHub sources, or registry catalog URLs. Omit `registries` to search every
-registry configured in `components.json` — e.g. "find me a hero" across all
-configured registries.
-
-**Input:** `registries` (string[], optional — omit for all configured), `query` (string), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
-
-### `shadcn:view_items_in_registries`
-
-View item details including full file contents.
-
-**Input:** `items` (string[]) — e.g.
-`["@shadcn/button", "@shadcn/card", "owner/repo/item"]`
-
-### `shadcn:get_item_examples_from_registries`
-
-Find usage examples and demos with source code. Omit `registries` to search
-every registry configured in `components.json`.
-
-**Input:** `registries` (string[], optional — omit for all configured), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
-
-### `shadcn:get_add_command_for_items`
-
-Returns the CLI install command.
-
-**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
-
-### `shadcn:get_audit_checklist`
-
-Returns a checklist for verifying components (imports, deps, lint, TypeScript).
-
-**Input:** none
-
----
-
-## Configuring Registries
-
-Namespaced and authenticated registries are set in `components.json`. The
-`@shadcn` registry is always built-in. Public GitHub registries can also be used
-directly as `owner/repo` registry sources when the repository has a root
-`registry.json`; they do not need `components.json` configuration.
-
-```json
-{
-  "registries": {
-    "@acme": "https://acme.com/r/{name}.json",
-    "@private": {
-      "url": "https://private.com/r/{name}.json",
-      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
-    }
-  }
-}
-```
-
-- Names must start with `@`.
-- URLs must contain `{name}`.
-- `${VAR}` references are resolved from environment variables.
-
-Community registry index: `https://ui.shadcn.com/r/registries.json`

package/.opencode/docs/shadcn/registry.md

@@ -1,277 +0,0 @@
-# Registry Authoring and Addresses
-
-Use this reference when the user wants to create, fix, publish, or reason about
-a shadcn registry.
-
-## Mental Model
-
-A registry has two forms:
-
-- **Source registry**: an authored `registry.json` in a project or repository.
-  It may use `include` and file paths that point at source files.
-- **Built registry**: generated JSON files served to CLI consumers, usually
-  from `public/r`. Use `npx shadcn@latest build` to create this form.
-
-The CLI installer consumes registry item payloads. A source registry is a way to
-author those payloads from real files.
-
-Registry items are not limited to React components. They can distribute
-components, hooks, utilities, design tokens, pages, config files, docs, rules,
-workflows, templates, MCP files, and other project files.
-
-## Root `registry.json`
-
-The root registry file should define registry metadata and either `items` or
-`include`.
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "acme",
-  "homepage": "https://acme.com",
-  "items": [
-    {
-      "name": "absolute-url",
-      "type": "registry:lib",
-      "title": "Absolute URL",
-      "description": "A utility to turn any path into an absolute URL.",
-      "files": [
-        {
-          "path": "lib/absolute-url.ts",
-          "type": "registry:lib"
-        }
-      ]
-    }
-  ]
-}
-```
-
-Root registry rules:
-
-- Root `registry.json` must include `name` and `homepage`.
-- `items` is an array of registry item definitions.
-- `include` may be used to split the source registry into multiple files.
-- Included registry files may omit `name` and `homepage`.
-
-## Include
-
-Use `include` to keep large registries modular.
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema/registry.json",
-  "name": "acme",
-  "homepage": "https://acme.com",
-  "include": ["registry/ui/registry.json", "registry/blocks/registry.json"]
-}
-```
-
-Include rules:
-
-- Include paths are relative to the `registry.json` that declares them.
-- Include paths must explicitly point to a `registry.json` file.
-- Do not use remote URLs, absolute paths, or parent traversal (`..`).
-- Item file paths are relative to the registry file that declares the item.
-- Duplicate item names fail across the resolved registry.
-
-Example included file:
-
-```json
-{
-  "items": [
-    {
-      "name": "button",
-      "type": "registry:ui",
-      "files": [
-        {
-          "path": "button.tsx",
-          "type": "registry:ui"
-        }
-      ]
-    }
-  ]
-}
-```
-
-If this file is at `registry/ui/registry.json`, then `button.tsx` is read from
-`registry/ui/button.tsx`, and the built item path is emitted relative to the
-root registry.
-
-## Item Definitions
-
-Common item fields:
-
-```json
-{
-  "name": "login-form",
-  "type": "registry:block",
-  "title": "Login Form",
-  "description": "A login form with email and password fields.",
-  "dependencies": ["zod"],
-  "registryDependencies": ["button", "input", "label"],
-  "files": [
-    {
-      "path": "blocks/login-form.tsx",
-      "type": "registry:block"
-    }
-  ],
-  "cssVars": {
-    "light": {
-      "brand": "oklch(0.62 0.18 250)"
-    },
-    "dark": {
-      "brand": "oklch(0.72 0.16 250)"
-    }
-  }
-}
-```
-
-Important fields:
-
-- `name`: the installable item name. It is not necessarily a file path.
-- `type`: one of the registry item types, such as `registry:ui`,
-  `registry:block`, `registry:lib`, `registry:hook`, `registry:file`,
-  `registry:page`, `registry:theme`, `registry:style`, `registry:font`, or
-  `registry:item`.
-- `files`: source files copied or generated by the item.
-- `dependencies`: npm runtime dependencies.
-- `devDependencies`: npm development dependencies.
-- `registryDependencies`: other registry items required by this item.
-- `cssVars`, `css`, `tailwind`, `envVars`, and `docs`: optional install-time
-  additions.
-
-File rules:
-
-- File paths are relative to the declaring `registry.json`.
-- `registry:file` and `registry:page` files require a `target`.
-- Do not use remote file URLs in source registry file paths.
-- Keep source files copy-pasteable: no hidden app-only imports.
-
-## Registry Dependencies
-
-`registryDependencies` entries are item addresses, not file paths.
-
-```json
-{
-  "name": "login-form",
-  "type": "registry:block",
-  "registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"],
-  "files": [
-    {
-      "path": "blocks/login-form.tsx",
-      "type": "registry:block"
-    }
-  ]
-}
-```
-
-Dependency rules:
-
-- Bare names such as `"button"` mean official shadcn items.
-- Bare names never mean same-registry or same-repository items.
-- Namespaced dependencies use `@namespace/item-name`.
-- GitHub dependencies use `owner/repo/item-name`.
-- Pin GitHub dependencies with `owner/repo/item-name#ref` when needed.
-- Refs are not inherited. If `owner/repo/foo#v2` depends on `bar` from the same
-  repo at `v2`, write `owner/repo/bar#v2`.
-- Do not use relative dependencies such as `"./bar"`.
-
-## Address Schemes
-
-When reasoning about a registry item string, classify it first.
-
-| Address                             | Scheme    | Meaning                                                      |
-| ----------------------------------- | --------- | ------------------------------------------------------------ |
-| `button`                            | shadcn    | Official shadcn item named `button`.                         |
-| `@acme/button`                      | namespace | Item `button` from configured registry `@acme`.              |
-| `@acme/ui/button`                   | namespace | Item `ui/button` from configured registry `@acme`.           |
-| `https://example.com/r/button.json` | url       | Built registry item JSON at that URL.                        |
-| `./button.json`                     | file      | Built registry item JSON on disk.                            |
-| `acme/ui/button`                    | github    | Item `button` from GitHub repo `acme/ui`.                    |
-| `acme/ui/forms/login#main`          | github    | Item `forms/login` from GitHub repo `acme/ui` at ref `main`. |
-
-For namespace and GitHub addresses, slashful item names are allowed and are item
-names, not file paths. Addresses ending in `.json` keep file-address
-precedence, so `acme/ui/data/schema.json` is treated as a file path, not a
-GitHub item address.
-
-## GitHub Registries
-
-A public GitHub repository can act as a source registry when it has a root
-`registry.json`.
-
-```txt
-owner/repo/item-name[#ref]
-```
-
-Rules:
-
-- The first two path segments are GitHub owner and repo.
-- All remaining path segments are the registry item name.
-- The source entrypoint is always root `registry.json`.
-- GitHub registries are source registries consumed directly by the CLI. They do
-  not require `shadcn build` or generated item JSON files.
-- `include` follows the same source-registry rules as local registries.
-- Currently, GitHub addresses support public `github.com` repositories only.
-- Private repos and GitHub Enterprise require explicit product decisions.
-
-When implementing GitHub registry fetching, resolve refs to a commit SHA before
-reading source files. Do not read moving refs directly from
-`raw.githubusercontent.com`, because branch-like refs can be cached for several
-minutes.
-
-Preferred flow:
-
-```txt
-owner/repo[#ref]
-  -> resolve ref with git ls-remote
-  -> commit SHA
-  -> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json
-  -> read includes and item files from the same SHA
-```
-
-This keeps a command on one consistent repository snapshot.
-
-Full 40-character commit SHAs are already stable and can be used directly.
-Branches, tags, and short refs require Git so the CLI can resolve them to a
-commit SHA first.
-
-## Build and Verify
-
-Use the CLI to build source registries:
-
-```bash
-npx shadcn@latest build
-npx shadcn@latest build registry.json --output public/r
-```
-
-Use CLI commands to inspect the result:
-
-```bash
-npx shadcn@latest list @acme
-npx shadcn@latest search @acme -q "login"
-npx shadcn@latest view @acme/login-form
-npx shadcn@latest add @acme/login-form --dry-run
-npx shadcn@latest registry validate ./registry.json
-```
-
-Use GitHub addresses directly for public GitHub registries:
-
-```bash
-npx shadcn@latest list owner/repo
-npx shadcn@latest search owner/repo -q "login"
-npx shadcn@latest view owner/repo/item
-npx shadcn@latest add owner/repo/item --dry-run
-npx shadcn@latest registry validate owner/repo
-```
-
-When working on registry implementation in the shadcn/ui codebase:
-
-- Keep address parsing pure and testable.
-- Do not add side effects to validators.
-- Preserve existing behavior for official shadcn, namespace, URL, and file
-  schemes.
-- Add tests for address parsing, source loading, dependency resolution, list,
-  search, view, and add paths.
-- Prefer small source-reader abstractions over a plugin system until there are
-  multiple real providers.