kataster 0.2.0 → 0.3.0

package/AGENTS.md

@@ -1,12 +1,12 @@
 # Kataster – development entry point
 
-This repository is the **toolkit**, not an installation of it. `.claude/`, `.opencode/`, `templates/` and
-`extras/` are the payload that `npx kataster init` copies into a target repository.
+This repository is the **toolkit**, not an installation of it. `.claude/`, `.opencode/` and `templates/` are the
+payload that `npx kataster init` copies into a target repository.
 
 - **Installer:** `src/cli.mjs` (commands, prompts), `src/install.mjs` (copy, merge, manifest, upgrade),
   `src/detect.mjs` (stack detection), `src/repo.mjs` (monorepo tooling and workspaces), `src/util.mjs`.
 - **Payload:** `.claude/` (skills, agents, hooks, lib, settings), `.opencode/` (commands, agents, plugin),
-  `templates/` (docs skeleton, project profile defaults, conventions template), `extras/` (optional skills).
+  `templates/` (docs skeleton, project profile defaults, conventions template).
 - **Tests:** `npm test` (installs into temp directories and asserts the result).
 - **Docs for users:** `README.md` and `guide/`.
 

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.0 – 2026-10-31
+
+- **Removed the optional extras and the vendored `shadcn` skill.** `--with` is gone; the CLI fails with a clear
+  message instead of reading the value as a directory. The payload no longer ships third-party content: install a
+  UI skill such as shadcn/ui in the project that needs it. An installation made with `--with shadcn` keeps the files
+  under `.claude/skills/shadcn/`; `upgrade` leaves them alone and drops the stale `workflow.extras` field from
+  `.claude/project.json`.
+
+## 0.2.1 – 2026-10-31
+
+- Releases are published from CI with npm trusted publishing (OIDC): pushing a `v*` tag runs the type check and the
+  test suite, verifies that the tag matches `package.json`, and publishes with provenance attestations – no token
+  in the repository, no one-time password. `guide/release.md` documents the setup and the manual fallback.
+- The repository is maintained in the open: `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`, issue and pull
+  request templates, Dependabot for the tooling dependencies and a protected `main` (pull request required, green
+  CI, squash only).
+
 ## 0.2.0 – 2026-10-31
 
 - **Renamed from La Guardia to Kataster.** The CLI is `npx kataster`, the state directory is `.kataster/`, the

package/README.md

@@ -301,10 +301,6 @@ npx kataster doctor
 overwrite files you changed locally – it lists them instead. `--force` overwrites and writes a backup to
 `.kataster/backup/`.
 
-## Optional extras
-
-- `--with shadcn` installs the shadcn/ui skill for projects that use it.
-
 ## Design notes
 
 - **`.claude/` is the source of truth.** OpenCode and Claude Code share skills, agents and hooks; `.opencode/` is an
@@ -320,6 +316,13 @@ The name is a historical reference, not a domain: the workflow has none of its o
 was removed when the package was extracted – the examples are neutral, the stack is detected, and the language is
 yours.
 
+## Contributing
+
+The toolkit is maintained in the open: bug reports, a skill that fills a real gap and sharper prompts are welcome.
+[CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the payload rules and the release process;
+[SECURITY.md](SECURITY.md) is the way to report a vulnerability privately. Participation is covered by the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## License
 
 MIT

package/guide/install.md

@@ -15,7 +15,6 @@ npx kataster init [dir]
 | `--backlog <provider>` | Where stories live: `local` (default), `github`, `jira` |
 | `--jira-project <key>` | Jira project key (with `--backlog jira`) |
 | `--github-repo <repo>` | `owner/name` for a GitHub backlog (default: the current repository) |
-| `--with <list>` | Optional extras, comma-separated (`shadcn`) |
 | `--yes`, `-y` | Non-interactive: accept the detected defaults |
 | `--no-install` | Skip `npm install --prefix .claude` |
 | `--dry-run` | Show what would happen, write nothing |
@@ -57,7 +56,8 @@ npx kataster upgrade
   rewritten. `backlog.labelPrefix` in `project.json` is kept, so labels already in GitHub or Jira stay valid.
 - An existing `project.json` keeps its content. If it predates the backlog backend, add the `backlog` section by hand
   (see the README) – without it the provider stays `local`.
-- `--with` can add extras on upgrade.
+- An extra installed by an older version (`--with shadcn`, up to 0.2.1) stays on disk as a project file; upgrade no
+  longer touches it. Delete `.claude/skills/shadcn/` if you do not want it.
 
 ## Harness setup
 

package/guide/release.md

@@ -11,7 +11,7 @@
 npm install --prefix .claude --no-audit --no-fund
 npm run typecheck --prefix .claude
 npm test
-npm pack --dry-run        # 161 files, 255 kB – no examples/, no node_modules, no state/
+npm pack --dry-run        # 147 files, 215 kB – no examples/, no node_modules, no state/
 ```
 
 4. Install the tarball once and start a throwaway project with it – a tarball that installs is not the same as a
@@ -26,6 +26,42 @@ kataster doctor /tmp/smoke
 
 ## 2. Publish
 
+### Through CI (the normal case)
+
+The tag publishes. `v0.2.0` starts `.github/workflows/release.yml`, which checks that the tag matches
+`package.json`, runs the type check and the suite, then publishes over OIDC – no npm token in the repository, no
+one-time password, and provenance attestations are written automatically.
+
+```bash
+git push origin main
+git tag -a v0.2.0 -m "Kataster 0.2.0"
+git push origin v0.2.0
+gh run watch
+```
+
+If the tag and `package.json` disagree, the workflow fails before it publishes – bump the version first, then tag.
+
+### The first time only: trusted publisher
+
+npm has to know which workflow may publish. On npmjs.com → `kataster` → Settings → **Trusted publishing** →
+GitHub Actions:
+
+| Field | Value |
+|---|---|
+| Organization or user | `hemi1986` |
+| Repository | `kataster` |
+| Workflow filename | `release.yml` |
+| Environment name | – (leave empty) |
+| Allowed actions | **Allow npm publish** (the default `npm stage publish` alone is not enough) |
+
+The first publish has to succeed within **two days**, otherwise the configuration expires and has to be created
+again. Once it works, lock the old path down: Settings → **Publishing access** → "Require two-factor authentication
+and disallow tokens". Trusted publishers keep working; tokens and OTP stop working.
+
+### By hand (fallback)
+
+If CI is unavailable or a version has to go out without a tag:
+
 ```bash
 npm login                 # once per machine
 npm publish --access public
@@ -33,21 +69,16 @@ npm publish --access public
 
 `prepublishOnly` runs the test suite, so a red suite cannot be published.
 
-Verify:
+## 3. Verify
 
 ```bash
 npm view kataster version
 npx kataster@latest --version
 ```
 
-## 3. Tag
-
-The tag is the version with a `v`:
-
-```bash
-git tag -a v0.2.0 -m "Kataster 0.2.0"
-git push origin main v0.2.0
-```
+The package page shows a provenance badge (`built and signed on GitHub Actions`) and the workflow run is linked to
+the tag. A missing badge means the publish did not go through trusted publishing. The registry can take a minute or
+two before a new version appears; `npm view kataster version` is the source of truth, not the cache in `npx`.
 
 ## What ships
 
@@ -55,7 +86,7 @@ git push origin main v0.2.0
 
 - `bin/`, `src/` – the CLI and installer
 - `.claude/`, `.opencode/` – the payload the installer copies
-- `templates/`, `extras/` – docs skeleton and optional skills
+- `templates/` – docs skeleton
 - `guide/`, `README.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`
 
 Not shipped: `test/`, `examples/`, `.github/`. `examples/` contains project-specific facts and is reference material

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kataster",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Agent workflow for domain-driven discovery and delivery – drop it into a greenfield or brownfield repository and build the domain by grilling.",
   "keywords": [
     "agents",
@@ -40,7 +40,6 @@
     "bin",
     "src",
     "templates",
-    "extras",
     "guide",
     ".claude",
     ".opencode",

package/src/cli.mjs

@@ -25,7 +25,6 @@ Options:
   --backlog <provider>  Where stories live: local (default), github, jira
   --jira-project <key>  Jira project key (with --backlog jira)
   --github-repo <repo>  GitHub repository owner/name (with --backlog github; default: this repo)
-  --with <list>         Optional extras, comma-separated (available: shadcn)
   --force               Overwrite locally modified workflow files (backup is kept)
   --no-install          Do not run "npm install --prefix .claude"
   --yes, -y             Non-interactive: accept the detected defaults
@@ -34,7 +33,7 @@ Options:
 
 function parse(argv) {
   const options = { _: [] };
-  const takesValue = new Set(["name", "ui-language", "artifacts", "with", "backlog", "jira-project", "github-repo"]);
+  const takesValue = new Set(["name", "ui-language", "artifacts", "backlog", "jira-project", "github-repo"]);
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (!arg.startsWith("-")) {
@@ -49,6 +48,9 @@ function parse(argv) {
     else if (arg === "--no-install") options.noInstall = true;
     else if (arg === "--yes" || arg === "-y") options.yes = true;
     else if (arg === "--dry-run") options.dryRun = true;
+    else if (arg === "--with" || arg.startsWith("--with=")) {
+      throw new Error("--with was removed in 0.3.0 – install an extra such as shadcn/ui directly in your project.");
+    }
     else if (arg.startsWith("--") && arg.includes("=")) {
       const [key, ...rest] = arg.slice(2).split("=");
       options[camel(key)] = rest.join("=");
@@ -104,9 +106,9 @@ Useful commands afterwards:
 `);
 }
 
-function printSummary(installer, extras) {
+function printSummary(installer) {
   const { created, updated, conflicts } = installer.summary();
-  console.log(`\nDone: ${created} created, ${updated} updated${extras.length ? `, extras: ${extras.join(", ")}` : ""}.`);
+  console.log(`\nDone: ${created} created, ${updated} updated.`);
   if (conflicts.length) {
     console.log(`\n${conflicts.length} file(s) kept because they were modified locally:`);
     for (const c of conflicts) console.log(`  - ${c}`);
@@ -117,7 +119,6 @@ function printSummary(installer, extras) {
 async function init(options) {
   const root = resolve(options._[1] ?? ".");
   const detection = detectProject(root);
-  const extras = String(options.with ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 
   banner();
   if (existsSync(join(root, ".claude", "install.json"))) {
@@ -147,7 +148,7 @@ async function init(options) {
     : "";
 
   const profile = buildProfile(root, {
-    name, kind, uiLanguage, artifactLanguage, detection, extras,
+    name, kind, uiLanguage, artifactLanguage, detection,
     backlog, jiraProject, githubRepo,
   });
   profile.workflow.version = VERSION;
@@ -163,7 +164,6 @@ async function init(options) {
   installer.putClaudeMd(profile);
   installer.putProfile(profile);
   installer.putConventions(profile);
-  installer.installExtras(extras);
   installer.updateGitignore();
   installer.writeManifest();
 
@@ -177,7 +177,7 @@ async function init(options) {
     if (!result.ok) console.log("\nTooling dependencies could not be installed – run: npm install --prefix .claude");
   }
 
-  printSummary(installer, extras);
+  printSummary(installer);
   nextSteps(root, profile);
 }
 
@@ -190,7 +190,6 @@ async function upgrade(options) {
     return init({ ...options, _: ["init", root] });
   }
   const profile = readJson(join(root, ".claude", "project.json")) ?? {};
-  const extras = options.with ? String(options.with).split(",").map((s) => s.trim()).filter(Boolean) : profile.workflow?.extras ?? [];
 
   console.log(`Upgrading ${root} from ${installer.manifest.version ?? "?"} to ${VERSION}\n`);
   installer.migrateLegacy();
@@ -202,12 +201,12 @@ async function upgrade(options) {
   installer.putContext(profile);
   installer.putClaudeMd(profile);
   installer.putConventions(profile);
-  installer.installExtras(extras);
   installer.updateGitignore();
   installer.writeManifest();
 
   if (profile.name && !options.dryRun) {
-    profile.workflow = { ...(profile.workflow ?? {}), version: VERSION, extras };
+    profile.workflow = { ...(profile.workflow ?? {}), version: VERSION };
+    delete profile.workflow.extras;
     write(join(root, ".claude", "project.json"), `${JSON.stringify(profile, null, 2)}\n`);
   }
 
@@ -216,7 +215,7 @@ async function upgrade(options) {
     return;
   }
   if (!options.noInstall) installer.installToolingDependencies();
-  printSummary(installer, extras);
+  printSummary(installer);
   console.log("\nUpgrade complete. Project content (CONTEXT.md, docs/domain, docs/stories, ADRs) was not touched.");
 }
 

package/src/detect.mjs

@@ -157,7 +157,7 @@ export function detectProject(root) {
   };
 }
 
-export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, detection, extras = [], backlog = "local", jiraProject = "", githubRepo = "" }) {
+export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, detection, backlog = "local", jiraProject = "", githubRepo = "" }) {
   const stackSummary = [
     ...detection.languages,
     ...detection.frameworks,
@@ -230,7 +230,6 @@ export function buildProfile(root, { name, kind, uiLanguage, artifactLanguage, d
     },
     workflow: {
       version: "0.1.0",
-      extras,
       installedAt: new Date().toISOString(),
     },
   };

package/src/install.mjs

@@ -341,19 +341,6 @@ export class Installer {
     });
   }
 
-  installExtras(names = []) {
-    for (const name of names) {
-      const source = join(PKG, "extras", "skills", name);
-      if (!existsSync(source)) {
-        this.record("skip", source, `unknown extra '${name}'`);
-        continue;
-      }
-      for (const file of walk(source)) {
-        this.put(join(this.root, ".claude", "skills", name, relative(source, file)), read(file));
-      }
-    }
-  }
-
   installToolingDependencies() {
     if (this.dryRun) return { ok: true, skipped: true };
     if (!existsSync(join(this.root, ".claude", "package.json"))) return { ok: true, skipped: true };

package/extras/skills/shadcn/SKILL.md

@@ -1,277 +0,0 @@
----
-name: shadcn
-description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. 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 follows the project base.** Use `toast` from the `toast` component for
-  Base UI projects. Use `toast()` from `sonner` for Radix and React Aria
-  projects.
-- **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.
-
-### Chat & Messaging → [chat.md](./rules/chat.md)
-
-- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container.
-- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook.
-- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label.
-
-### CLI
-
-- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@latest preset resolve`.
-- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply <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                   | `toast` (Base UI), `sonner` (Radix/Aria), `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`                                                                   |
-| Chat / conversation UI     | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`                                      |
-
-## 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`).
-- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information.
-
-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`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
-9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**?
-   - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values.
-   - **Inspect incoming preset**: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
-   - **Overwrite**: `npx shadcn@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
-   - **Partial**: `npx shadcn@latest apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
-   - **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 a2r6bw
-npx shadcn@latest apply a2r6bw --only theme
-npx shadcn@latest apply a2r6bw --only font
-npx shadcn@latest apply a2r6bw --only theme,font
-
-# Inspect preset codes and project preset state.
-npx shadcn@latest preset decode a2r6bw
-npx shadcn@latest preset url a2r6bw
-npx shadcn@latest preset open a2r6bw
-npx shadcn@latest preset resolve
-npx shadcn@latest preset resolve --json
-
-# Add components.
-npx shadcn@latest add button card dialog
-npx shadcn@latest add @magicui/shimmer-button
-npx shadcn@latest add owner/repo/item
-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
-npx shadcn@latest add owner/repo/item --dry-run
-
-# Search registries.
-npx shadcn@latest search @shadcn -q "sidebar"
-npx shadcn@latest search @tailark -q "stats"
-npx shadcn@latest search owner/repo -q "login"
-npx shadcn@latest search                          # all configured registries
-npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
-
-# 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
-npx shadcn@latest view owner/repo/item
-```
-
-**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/chat.md](./rules/chat.md) — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest
-- [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
-- [registry.md](./registry.md) — Authoring source registries, `include`, item definitions, dependencies, GitHub registry rules
-- [customization.md](./customization.md) — Theming, CSS variables, extending components

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

@@ -1,5 +0,0 @@
-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"