devskill 2.0.6 → 2.0.8

package/skills/secret-scanning/references/push-protection.md

@@ -0,0 +1,164 @@
+# Push Protection Reference
+
+Detailed reference for GitHub push protection — preventing secrets from reaching repositories, bypass workflows, and delegated bypass configuration.
+
+## How Push Protection Works
+
+Push protection scans for secrets during the push process and blocks pushes containing detected secrets. It operates as a preventative control, unlike standard secret scanning which detects secrets after commit.
+
+### What Gets Scanned
+
+| Surface | Scanned |
+|---|---|
+| Command line pushes | ✅ |
+| GitHub UI commits | ✅ |
+| File uploads to repo | ✅ |
+| REST API content creation requests | ✅ |
+
+### Types of Push Protection
+
+**Repository push protection:**
+- Requires GitHub Secret Protection enabled
+- Disabled by default; enabled by repo admin, org owner, or security manager
+- Generates alerts for bypasses in the Security tab
+- Can be enabled at repository, organization, or enterprise level
+
+**User push protection:**
+- Enabled by default for all GitHub.com accounts
+- Blocks pushes to public repositories containing supported secrets
+- Does NOT generate alerts when bypassed (unless repo also has push protection enabled)
+- Managed via personal account settings
+
+## Resolving Blocked Pushes — Command Line
+
+When push protection blocks a push, the error message includes:
+- The secret type detected
+- Commit SHAs containing the secret
+- File paths and line numbers
+- A URL to bypass (if permitted)
+
+### Remove Secret from Latest Commit
+
+```bash
+# Edit the file to remove the secret
+# Amend the commit
+git commit --amend --all
+
+# Push again
+git push
+```
+
+### Remove Secret from Earlier Commits
+
+```bash
+# 1. Review the push error for all commits containing the secret
+# 2. Find the earliest commit with the secret
+git log
+
+# 3. Interactive rebase before that commit
+git rebase -i <EARLIEST-COMMIT>~1
+
+# 4. Change 'pick' to 'edit' for the offending commit(s)
+# 5. Remove the secret from the file
+# 6. Stage and amend
+git add .
+git commit --amend
+
+# 7. Continue rebase
+git rebase --continue
+
+# 8. Push
+git push
+```
+
+### Bypass Push Protection
+
+1. Visit the URL from the error message (must be the same user who pushed)
+2. Select a reason:
+   - **It's used in tests** → creates a closed alert (resolved as "used in tests")
+   - **It's a false positive** → creates a closed alert (resolved as "false positive")
+   - **I'll fix it later** → creates an open alert
+3. Click **Allow me to push this secret**
+4. Re-push within **3 hours** (after that, repeat the bypass process)
+
+> A bypass reason is required when the repo has secret scanning enabled. For public repos with only user push protection (no repo push protection), no reason is needed and no alert is generated.
+
+## Resolving Blocked Pushes — GitHub UI
+
+When creating or editing a file in the GitHub UI:
+1. A banner appears warning about the detected secret
+2. Options to remove the secret or bypass are presented inline
+3. Same bypass reasons apply as command line
+
+## Resolving Blocked Pushes — REST API
+
+Push protection also applies to REST API content creation endpoints. When blocked:
+- The API returns an error response with details about the detected secret
+- Include the bypass reason in the request to proceed
+
+## Delegated Bypass
+
+Delegated bypass gives organizations fine-grained control over who can bypass push protection.
+
+### How It Works
+
+1. Organization owners/repo admins create a **bypass list** of users, roles, or teams
+2. Users on the bypass list can bypass push protection directly (with a reason)
+3. All other contributors must **submit a bypass request** for review
+4. Bypass requests appear in the Security tab → "Push protection bypass" page
+5. Requests expire after **7 days** if not reviewed
+
+### Who Can Always Bypass (Without Request)
+
+- Organization owners
+- Security managers
+- Users in teams/roles added to the bypass list
+- Users with custom role having "review and manage secret scanning bypass requests" permission
+
+### Enabling Delegated Bypass
+
+**Repository level:**
+1. Settings → Advanced Security → Push protection
+2. Enable "Restrict who can bypass push protection"
+3. Add users, teams, or roles to the bypass list
+
+**Organization level:**
+1. Organization Settings → Advanced Security → Global settings
+2. Configure delegated bypass in security configuration
+
+### Managing Bypass Requests
+
+Designated reviewers:
+1. Navigate to repository Security tab → "Push protection bypass"
+2. Review pending requests (includes the secret, commit, and contributor's comment)
+3. **Approve** — contributor can push the secret and any future commits with the same secret
+4. **Deny** — contributor must remove the secret before pushing
+
+### Bypass Request Flow (Contributor Perspective)
+
+1. Push is blocked; visit the URL from the error message
+2. Add a comment explaining why the secret is safe to push
+3. Click **Submit request**
+4. Wait for email notification of approval/denial
+5. If approved: push the commit
+6. If denied: remove the secret and push again
+
+## Push Protection Patterns
+
+Push protection supports a subset of secret scanning patterns. Not all detected secret types trigger push protection blocks.
+
+Key considerations:
+- Older/legacy token formats may not be supported by push protection
+- Some patterns have higher false positive rates and are excluded from push protection
+- Custom patterns can have push protection enabled after publishing
+
+For the full list of patterns supported by push protection, see [Supported secret scanning patterns](https://docs.github.com/en/code-security/secret-scanning/introduction/supported-secret-scanning-patterns).
+
+## Configuring Push Protection for Custom Patterns
+
+After publishing a custom pattern:
+1. Navigate to the custom pattern in Settings → Advanced Security
+2. Click **Enable** next to push protection
+3. The pattern will now block pushes containing matching secrets
+
+> Push protection for custom patterns only applies to repos that have push protection enabled. Enabling push protection for commonly found patterns can be disruptive to contributors.

package/skills/semantic-kernel/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/semantic-kernel/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: semantic-kernel
+description: 'Create, update, refactor, explain, or review Semantic Kernel solutions using shared guidance plus language-specific references for .NET and Python.'
+---
+
+# Semantic Kernel
+
+Use this skill when working with applications, plugins, function-calling flows, or AI integrations built on Semantic Kernel.
+
+Always ground implementation advice in the latest Semantic Kernel documentation and samples rather than memory alone.
+
+## Determine the target language first
+
+Choose the language workflow before making recommendations or code changes:
+
+1. Use the **.NET** workflow when the repository contains `.cs`, `.csproj`, `.sln`, or other .NET project files, or when the user explicitly asks for C# or .NET guidance. Follow [references/dotnet.md](references/dotnet.md).
+2. Use the **Python** workflow when the repository contains `.py`, `pyproject.toml`, `requirements.txt`, or the user explicitly asks for Python guidance. Follow [references/python.md](references/python.md).
+3. If the repository contains both ecosystems, match the language used by the files being edited or the user's stated target.
+4. If the language is ambiguous, inspect the current workspace first and then choose the closest language-specific reference.
+
+## Always consult live documentation
+
+- Read the Semantic Kernel overview first: <https://learn.microsoft.com/semantic-kernel/overview/>
+- Prefer official docs and samples for the current API surface.
+- Use the Microsoft Docs MCP tooling when available to fetch up-to-date framework guidance and examples.
+
+## Shared guidance
+
+When working with Semantic Kernel in any language:
+
+- Use async patterns for kernel operations.
+- Follow official plugin and function-calling patterns.
+- Implement explicit error handling and logging.
+- Prefer strong typing, clear abstractions, and maintainable composition patterns.
+- Use built-in connectors for Azure AI Foundry, Azure OpenAI, OpenAI, and other AI services, while preferring Azure AI Foundry services for new projects when that fits the task.
+- Use the kernel's memory and context-management capabilities when they simplify the solution.
+- Use `DefaultAzureCredential` when Azure authentication is appropriate.
+
+## Workflow
+
+1. Determine the target language and read the matching reference file.
+2. Fetch the latest official docs and samples before making implementation choices.
+3. Apply the shared Semantic Kernel guidance from this skill.
+4. Use the language-specific package, repository, sample paths, and coding practices from the chosen reference.
+5. When examples in the repo differ from current docs, explain the difference and follow the current supported pattern.
+
+## References
+
+- [.NET reference](references/dotnet.md)
+- [Python reference](references/python.md)
+
+## Completion criteria
+
+- Recommendations match the target language.
+- Package names, repository paths, and sample locations match the selected ecosystem.
+- Guidance reflects current Semantic Kernel documentation rather than stale assumptions.

package/skills/semantic-kernel/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/awesome-copilot/skills/semantic-kernel`
+- **Git SHA:** `23fb7006c132a0bba75b0e5af7a35cab11272812`
+- **Synced:** 2026-03-24

package/skills/semantic-kernel/references/dotnet.md

@@ -0,0 +1,15 @@
+# Semantic Kernel for .NET
+
+Use this reference when the target project is written in C# or another .NET language.
+
+## Authoritative sources
+
+- Repository: <https://github.com/microsoft/semantic-kernel/tree/main/dotnet>
+- Samples: <https://github.com/microsoft/semantic-kernel/tree/main/dotnet/samples>
+
+## .NET-specific guidance
+
+- Use `async`/`await` patterns consistently for kernel operations.
+- Follow .NET best practices with strong typing and explicit interfaces.
+- Keep service registration, configuration, and authentication aligned with standard .NET hosting patterns.
+- Check the latest .NET samples before introducing new APIs, plugins, or orchestration patterns.

package/skills/semantic-kernel/references/python.md

@@ -0,0 +1,15 @@
+# Semantic Kernel for Python
+
+Use this reference when the target project is written in Python.
+
+## Authoritative sources
+
+- Repository: <https://github.com/microsoft/semantic-kernel/tree/main/python>
+- Samples: <https://github.com/microsoft/semantic-kernel/tree/main/python/samples>
+
+## Python-specific guidance
+
+- Use modern async patterns throughout kernel operations.
+- Add type hints and keep APIs explicit even in dynamic code.
+- Follow standard Python packaging and environment practices for dependencies and tooling.
+- Check the latest Python samples before introducing new APIs, plugins, or orchestration patterns.

package/skills/shadcn/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/shadcn/SKILL.md

@@ -0,0 +1,242 @@
+---
+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 init --preset <code>`.
+
+## 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: **reinstall**, **merge**, or **skip**?
+   - **Reinstall**: `npx shadcn@latest init --preset <code> --force --reinstall`. Overwrites all components.
+   - **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. 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=base-nova
+
+# 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:** `base-nova`, `radix-nova`
+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
+**Preset codes:** Base62 strings starting with `a` (e.g. `a2r6bw`), 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/skills/shadcn/SYNC.md

@@ -0,0 +1,5 @@
+# Sync Info
+
+- **Source:** `vendor/shacdn-ui/skills/shadcn`
+- **Git SHA:** `ef78384bfdb410c52b767f701471d25cbabbf2e9`
+- **Synced:** 2026-03-24

package/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"