@toa.io/extensions.configuration 1.0.0-alpha.273 → 1.0.0-alpha.274

package/ui/.agents/skills/antcn/references/tools.md

@@ -0,0 +1,68 @@
+# Tools
+
+Small Svelte/TypeScript utilities — formatters, reactive helpers, browser glue, view transitions. Installs to `$lib/tools/` with barrel `index.ts`.
+
+```sh
+npx shadcn-svelte add https://cn.ants.dev/r/tools.json
+```
+
+```ts
+import { ago, date, navigate, ios } from '$lib/tools'
+```
+
+Most modules need only an import. Below: app-wide setup the CLI cannot merge.
+
+## Transitions (`transition.ts`)
+
+View Transition API helpers for SvelteKit navigation and in-page morphs.
+
+| Export | Role |
+| --- | --- |
+| `navigate` | Pass to SvelteKit `onNavigate` — wraps route changes in `document.startViewTransition` |
+| `transit` | Manual `startViewTransition` wrapper (async callback optional) |
+| `takeoff` | Before navigation, pin a departing element by `id` + transition name |
+| `transition` | Svelte action for non-navigation morphs |
+| `styles` | Store of inline `view-transition-*` style while a non-nav transition runs |
+
+### Route transitions — wire once in root layout
+
+CSS alone (`view-transition-name`, antcn `globals` layers) does **not** start transitions. Hook SvelteKit navigation:
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { onNavigate } from '$app/navigation'
+  import { navigate } from '$lib/tools'
+
+  let { children } = $props()
+
+  onNavigate(navigate)
+</script>
+
+{@render children()}
+```
+
+Required for route morphs (e.g. `shell` nav). Without this, transition CSS is inert. Unsupported browsers no-op (`transit` runs the callback immediately).
+
+### Shared CSS
+
+Antcn components using `transition-morph` / `standalone:` / `constructive` need `globals` (pulled in by `shell`) — see **globals** (`globals.md`).
+
+### Named morphs across navigation
+
+```ts
+import { takeoff } from '$lib/tools'
+
+takeoff('my-avatar', 'avatar', 'transition-morph')
+await goto('/profile')
+```
+
+### In-page (no navigation)
+
+```svelte
+<div use:transition={{ name: 'panel', classes: 'transition-morph' }}>...</div>
+```
+
+```ts
+await transit(async () => { /* DOM updates */ })
+```

package/ui/.agents/skills/antcn/references/transmission.md

@@ -0,0 +1,96 @@
+# transmission
+
+Web-push / FCM notification permission, subscription, and per-domain preferences for the signed-in account. Boots a single push channel (FCM iOS handler if present, else Web Push), reconciles permission with the backend after sign-in, exposes a `permissions` store keyed by `ScopeKey`, and lets you toggle them via `configure(...)`.
+
+`subscribe`/`unsubscribe` drive the platform channel and the backend record together; `request()` prompts the OS and follows through with a subscribe on grant. `ping()` round-trips a test notification. State lives under `transmission:subscribed` and `transmission:permissions` (bound to `@/iam`'s `account`); the `default.transmission.sync` realtime event refreshes permissions when other devices change them.
+
+Ships two UI pieces (`Permission`, `Scopes`) plus its own `ui/intl/` mount. Run `await rc()` from app bootstrap (after `@/iam` and `@/realtime`) to wire auto-subscribe on sign-in and `@/realtime` sync.
+
+## `$config`
+
+- `VAPID_PUBLIC_KEY: string` — base64url VAPID public key for Web Push subscriptions. Empty disables the Web Push channel (`getVapidKey` returns an `Error` and `subscribe()` short-circuits). Not used by the FCM/TWA channels.
+
+## Notes
+
+- **Intersect `transmission`'s `Events` into your `@/realtime`.** After install, edit your own `src/@/realtime/svc/events.ts` and add `TransmissionEvents` to the `Events` intersection — typed payloads everywhere, no cast in `store.ts`:
+
+  ```ts
+  // src/@/realtime/svc/events.ts
+  import type { Events as TransmissionEvents } from '@/transmission/svc/net'
+  // ...other Solutions' Events imports
+
+  export type Events = TransmissionEvents & /* & OtherEvents */
+  ```
+
+  Until you do, `store.ts` keeps a `(data as Transmission)` cast against `@/realtime`'s default `Record<string, unknown>`.
+
+- **`Window.webkit` global.** The FCM channel declares `Window.webkit` and `WebkitMessageHandlers` globally from its `types.d.ts`. If you ship more native bridges (e.g. Apple Pay), extend `WebkitMessageHandlers` the same way — interface merging means you don't need to redeclare `Window.webkit`.
+
+- **TWA channel ships but isn't wired by default.** `svc/channel/active.ts` only boots `web` and `fcm`. Add `twa` to the boot order if you target Android TWAs.
+
+## Usage
+
+Bootstrap once, after `@/iam` and `@/realtime`:
+
+```ts
+// src/routes/+layout.svelte (or wherever you boot Solutions)
+import { rc } from '@/transmission'
+
+await rc()
+```
+
+Programmatic API (no UI):
+
+```ts
+import { configure, ping, request, unsubscribe, key, permissions } from '@/transmission'
+
+await request()                                            // OS prompt + subscribe (idempotent)
+await configure({ [key({ domain: 'expenses' })]: false })  // mute one domain
+await ping()                                               // round-trip a test push (signed-in + subscribed)
+await unsubscribe()                                        // drop subscription on this device
+$permissions                                               // reactive scope→bool map
+```
+
+Send a real push from your backend by `POST`ing to the user's `transmission/<identity>` row — see `svc/net` for the wire shape.
+
+## `Permission`
+
+Onboarding nag card asking the user to enable push. Drop it on a high-traffic surface (dashboard, home, post-sign-in screen). Self-hides via `@/hints` once the user is no longer `unfamiliar('transmission_permission')`: **Enable** calls `request()` (OS prompt + subscribe on grant) and consumes the hint permanently; **Dismiss** marks it `later(KEY, 7d)` so the card disappears for a week. Gate it on `$promptable` yourself — the component does not check whether the browser can still prompt, so the caller decides when there's nothing left to ask for (denied, already subscribed, unsupported).
+
+```svelte
+<script lang="ts">
+  import { promptable } from '@/transmission'
+  import { Permission } from '@/transmission/ui'
+</script>
+
+{#if $promptable}
+  <Permission class="mb-4" />
+{/if}
+```
+
+### Props
+
+| Prop    | Type         | Default | Notes                          |
+| ------- | ------------ | ------- | ------------------------------ |
+| `class` | `ClassValue` | —       | Forwarded to the root `Card`.  |
+
+## `Scopes`
+
+Settings row for managing notifications on the current device. The master switch flips the whole subscription (`unsubscribe()` / `request()` under the hood); when on, per-domain switches expand below and toggle a single channel via `configure({ [key(scope)]: bool })` — muting it without dropping the subscription. Reads `$permissions`, so it reflects remote changes pushed via the `default.transmission.sync` realtime event (other devices, backend writes). The domain set is declared in `ui/Scopes.ts` (`scopes`) — edit it to add/remove rows; each row pulls its label/description from `ui/intl` keyed by `scope.domain`.
+
+```svelte
+<script lang="ts">
+  import { Scopes } from '@/transmission/ui'
+  import * as Item from '$ui/item'
+</script>
+
+<Item.Group>
+  <Scopes />
+</Item.Group>
+```
+
+### Props
+
+| Prop    | Type         | Default | Notes                                                |
+| ------- | ------------ | ------- | ---------------------------------------------------- |
+| `class` | `ClassValue` | —       | Forwarded to the top-level `Item.Root` (master row). |

package/ui/.agents/skills/shadcn-svelte/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: shadcn-svelte
+description: Manages shadcn-svelte components and projects — adding, updating, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn-svelte, the CLI, design-system presets, or any project with a components.json file. Also triggers for "shadcn-svelte init", "add component", or registry URLs.
+user-invocable: false
+allowed-tools: Bash(npx shadcn-svelte@latest *), Bash(pnpm dlx shadcn-svelte@latest *), Bash(bunx --bun shadcn-svelte@latest *)
+---
+
+# shadcn-svelte
+
+A framework for building UI, components, and design systems for Svelte. Components are added as source to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn-svelte@latest`, `pnpm dlx shadcn-svelte@latest`, or `bunx --bun shadcn-svelte@latest` — based on the project's package manager. Examples below use `npx shadcn-svelte@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+Read `components.json` at the project root and, when you need the live file layout, list the directory given by the `aliases.ui` path (resolved with the same rules as the CLI).
+
+## Imports (Svelte)
+
+Each component lives in its own folder with an `index.ts` barrel. Match the [installation docs](https://shadcn-svelte.com/docs/installation):
+
+- **Multi-part components** (dialog, select, card, field, tabs, …): `import * as Dialog from "$lib/components/ui/dialog"` then `Dialog.Content`, `Dialog.Title`, `Card.Root`, `Card.Header`, etc. — whatever the barrel exports (short names and/or `Root as …` aliases).
+- **Single-component barrels** (only one meaningful component in the folder): **named imports** — `import { Button } from "$lib/components/ui/button"` and `<Button>`, not `import * as Button` + `Button.Root`. Same pattern for `{ Input }`, `{ Badge }`, `{ Spinner }`, `{ Checkbox }`, `{ Separator }`, `{ Skeleton }`, etc.
+
+```ts
+import * as Dialog from "$lib/components/ui/dialog";
+import { Button } from "$lib/components/ui/button";
+import { Separator } from "$lib/components/ui/separator";
+```
+
+Use the real aliases from `components.json` (often `$lib/components/ui/...`), not hardcoded paths.
+
+## Principles
+
+1. **Use existing components first.** Run `npx shadcn-svelte@latest add` with no arguments to browse available components, or check [Components](https://shadcn-svelte.com/docs/components) before writing custom UI.
+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)
+
+- **`class` 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 `Field.FieldGroup` + `Field.Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroup.Input`/`InputGroup.Textarea`.** Never raw `Input`/`Textarea` inside `InputGroup.Root`.
+- **Buttons inside inputs use `InputGroup.Root` + `InputGroup.Addon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`Field.FieldSet` + `Field.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.** `Select.Item` → `Select.Group`. `DropdownMenu.Item` → `DropdownMenu.Group`. `Command.Item` → `Command.Group`.
+- **Custom triggers.** Wrap controls in `Dialog.Trigger` / `AlertDialog.Trigger`, or control open state with `bind:open` on the root — see component docs.
+- **Dialog, Sheet, and Drawer always need a Title.** `Dialog.Title`, `Sheet.Title`, `Drawer.Title` required for accessibility. Use `class="sr-only"` if visually hidden.
+- **Use full Card composition.** `Card.Header`/`Card.Title`/`Card.Description`/`Card.Content`/`Card.Footer`. Don't dump everything in `Card.Content`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` inside `Button` + `disabled`; use `data-icon="inline-start"` / `inline-end` on `Spinner` for correct spacing (`import { Button }`, `import { Spinner }`).
+- **`Tabs.Trigger` must be inside `Tabs.List`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `Avatar.Fallback`.** 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 `svelte-sonner`.** Use `toast()` from `svelte-sonner` with the Sonner component from your UI folder.
+- **Use `Separator`** instead of `<hr>` or a `div` with border-only classes.
+- **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 components.** Import from the configured `iconLibrary` (e.g. `@lucide/svelte`), not string keys.
+
+### CLI
+
+- **Presets** — copy the encoded string from the design-system builder on [shadcn-svelte.com](https://shadcn-svelte.com) and pass it to `npx shadcn-svelte@latest init --preset <code>`.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn-svelte code. For edge cases, see the linked rule files above.
+
+```svelte
+<script lang="ts">
+  import * as Field from "$lib/components/ui/field";
+  import { Input } from "$lib/components/ui/input";
+  import { Button } from "$lib/components/ui/button";
+  import SearchIcon from "@lucide/svelte/icons/search";
+  import { Badge } from "$lib/components/ui/badge";
+  import * as Avatar from "$lib/components/ui/avatar";
+</script>
+
+<!-- Form layout: Field.FieldGroup + Field.Field, not div + Label. -->
+<Field.FieldGroup>
+  <Field.Field>
+    <Field.FieldLabel for="email">Email</Field.FieldLabel>
+    <Input id="email" />
+  </Field.Field>
+</Field.FieldGroup>
+
+<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
+<Field.Field data-invalid>
+  <Field.FieldLabel for="email">Email</Field.FieldLabel>
+  <Input id="email" aria-invalid />
+  <Field.FieldDescription>Invalid email.</Field.FieldDescription>
+</Field.Field>
+
+<!-- Icons in buttons: data-icon, no sizing classes. -->
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<!-- Spacing: gap-*, not space-y-*. -->
+<div class="flex flex-col gap-4"></div>
+
+<!-- Equal dimensions: size-*, not w-* h-*. -->
+<Avatar.Root class="size-10">
+  <Avatar.Image src="/u.png" alt="User" />
+  <Avatar.Fallback>U</Avatar.Fallback>
+</Avatar.Root>
+
+<!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
+<Badge variant="secondary">+20.1%</Badge>
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant (`import { Button }`)                                             |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup.Root` + `ToggleGroup.Item`                                                             |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `svelte-sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                 |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (LayerChart)                                                                                |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+
+## Key Fields
+
+Use `components.json` and the filesystem — not a separate `info` command:
+
+- **`aliases`** → use the actual alias prefix from config (e.g. `$lib/`), never hardcode unrelated projects.
+- **`tailwind.css`** → the global CSS file where theme variables live. Edit this file for theme tweaks; don't add a second globals file unless the user already uses one.
+- **`style`** → visual treatment (e.g. `nova`, `vega`, …) and registry style path.
+- **`iconLibrary`** → determines icon packages (`@lucide/svelte`, `@tabler/icons-svelte`, etc.). Never assume `@lucide/svelte`.
+- **`registry`** → where the CLI fetches components; default official registry at `shadcn-svelte.com`.
+- **`resolvedPaths`** (conceptual) → the CLI resolves `aliases` to absolute paths; list `aliases.ui` on disk to see installed components.
+
+See [cli.md](./cli.md) for commands and flags.
+
+## Component Docs, Examples, and Usage
+
+Open `https://shadcn-svelte.com/docs/components/<name>.md` for docs and examples. **When creating, fixing, debugging, or using a component, read the official page first** so you follow the documented APIs.
+
+## Workflow
+
+1. **Get project context** — read `components.json` and list the UI components directory when needed.
+2. **Check installed components first** — before running `add`, list files under the resolved `ui` path. Don't import components that haven't been added, and don't re-add ones already present unless updating.
+3. **Discover components** — `npx shadcn-svelte@latest add` with no arguments (interactive list), or the docs site.
+4. **Install or update** — `npx shadcn-svelte@latest add <name>` or a registry **URL**. To refresh existing files from the registry, use `npx shadcn-svelte@latest update` (see [cli.md](./cli.md)).
+5. **Fix imports in third-party / URL-added items** — After adding from a custom registry URL, check for hardcoded paths that don't match the project's `aliases`. Rewrite imports to use the project's `ui` / `lib` aliases from `components.json`.
+6. **Review added components** — After adding, **read the added files** and verify composition (groups, titles, validation attrs). Align icon imports with `iconLibrary`.
+7. **Remote registry items** — Adding by URL is explicit; if the user wants a component from an unknown source, confirm the registry URL or item before running `add`.
+
+## Updating Components
+
+Use the **`update`** command to pull the latest registry versions of components already in the project. Review changes with `git diff` after `update`.
+
+1. Commit or stash local work.
+2. Run `npx shadcn-svelte@latest update [component]` or `--all`.
+3. Resolve merge conflicts if you had customized files.
+4. **Never use `--overwrite` on `add` without the user's explicit approval** when it would destroy intentional edits.
+
+## Quick Reference
+
+```bash
+# Initialize shadcn-svelte in your project.
+npx shadcn-svelte@latest init
+
+# Initialize with a preset string from the docs site builder.
+npx shadcn-svelte@latest init --preset <code>
+
+# Add components (interactive when run with no names).
+npx shadcn-svelte@latest add
+npx shadcn-svelte@latest add button card dialog
+npx shadcn-svelte@latest add --all
+
+# Update components already installed.
+npx shadcn-svelte@latest update button
+npx shadcn-svelte@latest update --all --yes
+
+# Build a custom registry (registry authors).
+npx shadcn-svelte@latest registry build
+```
+
+**Registry:** default `https://shadcn-svelte.com/registry` — override in `components.json` if needed.  
+**Docs:** [shadcn-svelte.com](https://shadcn-svelte.com)
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — Field.FieldGroup, Field.Field, InputGroup, ToggleGroup, Field.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 icon components
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, class, spacing, size, truncate, dark mode, cn(), z-index
+- [cli.md](./cli.md) — Commands, flags, registry
+- [customization.md](./customization.md) — Theming, CSS variables, extending components

package/ui/.agents/skills/shadcn-svelte/agents/openai.yml

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

package/ui/.agents/skills/shadcn-svelte/cli.md

@@ -0,0 +1,166 @@
+# shadcn-svelte CLI Reference
+
+Configuration is read from `components.json`. See [components.json](https://shadcn-svelte.com/docs/components-json) on the docs site for the full schema.
+
+> **IMPORTANT:** Always run commands using the project's package runner: `npx shadcn-svelte@latest`, `pnpm dlx shadcn-svelte@latest`, or `bunx --bun shadcn-svelte@latest`. Check `packageManager` from the project (or lockfile) to choose the right one. Examples below use `npx shadcn-svelte@latest` but substitute the correct runner for the project.
+
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist. The CLI auto-detects the package manager; there is no `--package-manager` flag.
+
+## Contents
+
+- Commands: `init`, `add`, `apply`, `update`, `registry build`
+- Proxy / outgoing requests
+- Presets (via `init` and `apply`)
+
+---
+
+## Commands
+
+### `init` — Initialize an existing project
+
+```bash
+npx shadcn-svelte@latest init [options]
+```
+
+Installs dependencies, adds the `cn` util, creates `components.json`, and sets up CSS variables. Run `init` from the root of your project.
+
+| Flag                        | Short | Description                                                               | Default   |
+| --------------------------- | ----- | ------------------------------------------------------------------------- | --------- |
+| `--preset <preset>`         | —     | Encoded design-system preset string from the docs site                    | —         |
+| `-c, --cwd <path>`          | `-c`  | Working directory                                                         | current   |
+| `-o, --overwrite`           | —     | Overwrite existing files                                                  | `false`   |
+| `--no-deps`                 | —     | Do not add or install dependencies                                        | —         |
+| `--skip-preflight`          | —     | Ignore preflight checks and continue                                      | `false`   |
+| `--base-color <name>`       | —     | Base color: `neutral`, `stone`, `zinc`, `mauve`, `olive`, `mist`, `taupe` | —         |
+| `--css <path>`              | —     | Path to the global CSS file                                               | —         |
+| `--components-alias <path>` | —     | Import alias for components                                               | —         |
+| `--lib-alias <path>`        | —     | Import alias for lib                                                      | —         |
+| `--utils-alias <path>`      | —     | Import alias for utils                                                    | —         |
+| `--hooks-alias <path>`      | —     | Import alias for hooks                                                    | —         |
+| `--ui-alias <path>`         | —     | Import alias for UI components                                            | —         |
+| `--proxy <proxy>`           | —     | Fetch registry items through this proxy                                   | env-based |
+| `--design-system-url`       | —     | Optional design-system URL (see docs / preset builder)                    | —         |
+| `-h, --help`                | `-h`  | Help                                                                      | —         |
+
+---
+
+### `add` — Add components
+
+```bash
+npx shadcn-svelte@latest add [options] [components...]
+```
+
+Adds components from the configured registry. Arguments are component names from the registry index, or a **URL** to a registry JSON item. With **no** component names, the CLI prompts you to pick components interactively.
+
+| Flag               | Short | Description                                     | Default   |
+| ------------------ | ----- | ----------------------------------------------- | --------- |
+| `-c, --cwd <path>` | `-c`  | Working directory                               | current   |
+| `--no-deps`        | —     | Skip adding and installing package dependencies | —         |
+| `--skip-preflight` | —     | Ignore preflight checks and continue            | `false`   |
+| `-a, --all`        | —     | Install all UI components                       | `false`   |
+| `-y, --yes`        | —     | Skip confirmation prompt                        | `false`   |
+| `-o, --overwrite`  | —     | Overwrite existing files                        | `false`   |
+| `--proxy <proxy>`  | —     | Fetch components through this proxy             | env-based |
+| `-h, --help`       | `-h`  | Help                                            | —         |
+
+---
+
+### `apply` — Apply a preset to an existing project
+
+```bash
+npx shadcn-svelte@latest apply [options]
+```
+
+Applies a design-system preset to a project that has already been initialized. Updates `components.json` with the preset settings, reinstalls existing components (except `utils`) with the new styles, and installs any required dependencies.
+
+Use `--only theme` or `--only font` to apply only part of a preset without reinstalling UI components.
+
+Get a preset code from the builder at [shadcn-svelte.com/create](https://shadcn-svelte.com/create).
+
+| Flag                | Short | Description                                    | Default   |
+| ------------------- | ----- | ---------------------------------------------- | --------- |
+| `--preset <preset>` | —     | Encoded design-system preset string (required) | —         |
+| `--only [parts]`    | —     | Apply only `theme` or `font` from the preset   | —         |
+| `-c, --cwd <path>`  | `-c`  | Working directory                              | current   |
+| `-y, --yes`         | `-y`  | Overwrite existing files without confirmation  | `false`   |
+| `-s, --silent`      | `-s`  | Mute output                                    | `false`   |
+| `--skip-preflight`  | —     | Ignore preflight checks and continue           | `false`   |
+| `--proxy <proxy>`   | —     | Fetch registry items through this proxy        | env-based |
+| `-h, --help`        | `-h`  | Help                                           | —         |
+
+Requires an existing `components.json`. Run `init` first if the project is not yet configured.
+
+---
+
+### `update` — Update installed components
+
+```bash
+npx shadcn-svelte@latest update [options] [components...]
+```
+
+Re-fetches and applies registry content for components **already present** in the project. Run `shadcn-svelte update --help` for options.
+
+| Flag               | Short | Description                                     | Default   |
+| ------------------ | ----- | ----------------------------------------------- | --------- |
+| `-c, --cwd <path>` | `-c`  | Working directory                               | current   |
+| `--skip-preflight` | —     | Ignore preflight checks and continue            | `false`   |
+| `--no-deps`        | —     | Skip adding and installing package dependencies | —         |
+| `-a, --all`        | —     | Update every installed component                | `false`   |
+| `-y, --yes`        | —     | Skip confirmation prompt                        | `false`   |
+| `--proxy <proxy>`  | —     | Fetch through this proxy                        | env-based |
+| `-h, --help`       | `-h`  | Help                                            | —         |
+
+Commit your work before updating; overwrites are destructive.
+
+---
+
+### `registry build` — Build a custom registry
+
+```bash
+npx shadcn-svelte@latest registry build [options] [registry]
+```
+
+Reads a `registry.json` and writes registry JSON files for distribution. Default input: `./registry.json`, default output: `./static/r`.
+
+| Flag                  | Short | Description                     | Default      |
+| --------------------- | ----- | ------------------------------- | ------------ |
+| `-c, --cwd <path>`    | `-c`  | Working directory               | current      |
+| `-o, --output <path>` | `-o`  | Output directory for JSON files | `./static/r` |
+| `-h, --help`          | `-h`  | Help                            | —            |
+
+---
+
+## Outgoing Requests
+
+### Proxy
+
+The CLI can fetch the registry through a proxy. If `HTTP_PROXY` or `http_proxy` is set, requests respect it. You can also pass `--proxy` on `init`, `add`, `apply`, or `update`.
+
+```bash
+HTTP_PROXY="<proxy-url>" npx shadcn-svelte@latest init
+```
+
+---
+
+## Presets
+
+Design-system options (style, theme, icons, fonts, etc.) can be captured as an encoded **preset** string from the builder on [shadcn-svelte.com/create](https://shadcn-svelte.com/create).
+
+- **New project:** pass the preset to **`init`** with `--preset <string>`.
+- **Existing project:** use **`apply --preset <string>`** to update configuration, restyle installed components, and install any new dependencies.
+
+---
+
+## `components.json` — useful fields for agents
+
+| Field / path         | Meaning                                                          |
+| -------------------- | ---------------------------------------------------------------- |
+| `tailwind.css`       | Global CSS file path (Tailwind entry / theme variables)          |
+| `tailwind.baseColor` | Base palette (cannot change after init)                          |
+| `aliases.*`          | Import aliases; must match `svelte.config.js` / `tsconfig` paths |
+| `registry`           | Base registry URL (default `https://shadcn-svelte.com/registry`) |
+| `style`              | Registered style name (e.g. `nova`, `vega`, …)                   |
+| `iconLibrary`        | Icon set key (`lucide`, `tabler`, …) — drives generated imports  |
+| `typescript`         | Whether TS and optional custom config path                       |
+
+Resolved paths (including `tailwindCss`, `ui`, `components`) are computed by the CLI from `components.json` and the filesystem. Read `components.json` and list the UI directory when you need a snapshot of what is installed.