@gallopsystems/agent-skills 1.2.0 → 1.5.0

package/README.md

@@ -15,6 +15,10 @@ Then install the skills you want:
 /plugin install nuxt-nitro-api@gallop-systems-agent-skills
 /plugin install nitro-testing@gallop-systems-agent-skills
 /plugin install linear@gallop-systems-agent-skills
+/plugin install doctl@gallop-systems-agent-skills
+/plugin install git-github@gallop-systems-agent-skills
+/plugin install copier-template@gallop-systems-agent-skills
+/plugin install volt-primevue@gallop-systems-agent-skills
 ```
 
 ## Updating
@@ -111,6 +115,60 @@ Covers:
 - Async/automation testing utilities
 - CI/CD setup with GitHub Actions and PostgreSQL
 
+### linear
+
+Create, triage, and manage Linear issues following team conventions, with a GraphQL CLI for operations the Linear MCP server doesn't expose.
+
+Covers:
+- Issue creation and triage conventions
+- Tech-stack labels
+- A `linear.mjs` CLI for GraphQL operations
+
+### doctl
+
+Manage DigitalOcean resources with the doctl CLI.
+
+Covers:
+- Auth contexts (per-command `--context` over stateful switching)
+- Resolving the current git repo to its DO context + app
+- App Platform: deployments, bounded polling, logs and their retention quirks
+- App specs: env var/secret round-trips, validation, creating apps
+- `--format` / `-o json` gotchas
+- Managed databases, Spaces keys, droplets, DNS
+
+### git-github
+
+Git and GitHub (gh CLI) workflows for agents.
+
+Covers:
+- Ground rules and the branch → commit → PR loop
+- Reading PR and CI state (`gh pr view --json`, `gh pr checks`)
+- Debugging failed GitHub Actions runs (the full playbook)
+- Repair ladders: rejected pushes, rebase-after-squash-merge, shallow clones, worktrees
+- `gh api` recipes: PR comments, no-checkout file reads, repo settings, PAT gotchas
+- Releases: tags, npm Trusted Publishing, release-please
+- External review loop with the codex CLI
+
+### copier-template
+
+Maintain a Copier project template and propagate updates to generated repos.
+
+Covers:
+- Template anatomy: copier.yml, conditional files, tasks, jinja escaping in CI workflows
+- Testing template changes (`--vcs-ref HEAD`, generate-and-validate)
+- Releasing versions (tag + GitHub Release) and the update-checker workflow pattern
+- Applying `copier update` in descendants: conflict triage, `.rej` files, validation
+
+## Contributing a Lesson Back
+
+Every skill ends with a **Contributing Back** section: when Claude works through
+something the skill didn't cover, it offers to contribute the lesson upstream. The
+`/contribute-skill` command (shipped in this package and symlinked into
+`.claude/commands/` on install) automates the flow: distill the generic lesson,
+privacy-sweep it, clone or fork this repo, and open a PR against the right skill
+file. PRs from forks are welcome — content must be generic (placeholders only, no
+project-specific names, IDs, or domains).
+
 ## Adding New Skills
 
 1. Create a new plugin directory: `plugins/my-skill/`

package/commands/contribute-skill.md

@@ -0,0 +1,65 @@
+---
+description: Contribute a lesson learned this session back to the gallop-systems/agent-skills repo as a PR
+argument-hint: [which skill and/or what lesson]
+---
+
+# Contribute a Lesson Back to the Skills Repo
+
+You are turning something learned in this session into a PR against
+https://github.com/gallop-systems/agent-skills, the public repo behind the
+installed skills.
+
+## 1. Identify the lesson
+
+From this session (or from `$ARGUMENTS` if given), pin down:
+
+- **The lesson**: usually an error→fix sequence, a behavior that contradicted the
+  skill, or a workflow knot the skill didn't cover. It must be something you
+  *verified in this session* — not a guess.
+- **The target**: which skill (`doctl`, `git-github`, `copier-template`,
+  `kysely-postgres`, `nuxt-nitro-api`, `nitro-testing`, `linear`), and within it,
+  whether it belongs in `SKILL.md` or one of its reference `.md` files. Read the
+  target file first and match its structure and tone.
+
+If the lesson is ambiguous or you can't verify it, stop and clarify with the user.
+
+## 2. Genericize — the repo is public
+
+Rewrite the lesson with placeholders only: `<app-id>`, `<owner>/<repo>`, `<branch>`,
+`<domain>`. **No project names, client names, UUIDs, IPs, domains, tokens, or file
+paths from the user's codebase.** Keep it tight: the generic rule, a minimal example
+command, and the failure it prevents — in that order.
+
+## 3. Clone, edit, verify
+
+Work in a temp directory, never in the user's project:
+
+```bash
+dir=$(mktemp -d)
+if [ "$(gh api repos/gallop-systems/agent-skills --jq .permissions.push)" = "true" ]; then
+  gh repo clone gallop-systems/agent-skills "$dir"
+else
+  gh repo fork gallop-systems/agent-skills --clone "$dir"   # outside contributors
+fi
+cd "$dir" && git checkout -b feat/<skill>-<short-slug>
+```
+
+Edit the target file under `plugins/<skill>/skills/<skill>/`. Then privacy-sweep
+your diff before committing — grep the changed files for anything resembling the
+user's project (project name, org, hostnames, IDs). If anything hits, fix it.
+
+## 4. Commit and open the PR
+
+The repo enforces Conventional Commit PR titles (release-please derives versions
+from them). Use `feat(<skill>): <summary>` for new coverage, `fix(<skill>): <summary>`
+for corrections to existing content.
+
+```bash
+git add -A && git commit -m "feat(<skill>): document <lesson summary>"
+git push -u origin <branch>
+gh pr create --repo gallop-systems/agent-skills \
+  --title "feat(<skill>): <summary>" \
+  --body "<what the lesson is, how it was hit and verified (genericized), why it belongs in this skill>"
+```
+
+Show the user the PR URL, then clean up: `cd - && rm -rf "$dir"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Gallop Systems Claude Code skills, symlinked into .claude/skills on install.",
   "license": "UNLICENSED",
   "repository": {
@@ -9,6 +9,7 @@
   },
   "files": [
     "plugins",
+    "commands",
     "scripts/link-skills.mjs",
     "README.md"
   ],

package/plugins/copier-template/skills/copier-template/SKILL.md

@@ -66,3 +66,9 @@ If newer, it pushes a **static branch name** (e.g. `chore/template-update`) with
 
 - **Template anatomy & testing changes**: [template-authoring.md](template-authoring.md)
 - **Applying an update in a descendant** (the conflict-resolution procedure): [applying-updates.md](applying-updates.md)
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the copier-template skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/doctl/skills/doctl/SKILL.md

@@ -117,3 +117,9 @@ doctl apps logs <app-id> --type run --follow            # live tail (interactive
 
 - **App specs — env vars, secrets, creating apps**: see [spec-management.md](spec-management.md)
 - **Databases, Spaces, droplets, DNS**: see [other-services.md](other-services.md)
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the doctl skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/git-github/skills/git-github/SKILL.md

@@ -83,3 +83,9 @@ Do not bypass failing hooks with `--no-verify` unless the user says to.
 - **gh api recipes** — PR comments, reading files without checkout, repo settings, PAT gotchas: [gh-api-recipes.md](gh-api-recipes.md)
 - **Releases & publishing** — tags, gh release, npm Trusted Publishing, release-please: [releases.md](releases.md)
 - **External review loop** — using the codex CLI as an adversarial pre-merge reviewer: [external-review.md](external-review.md)
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the git-github skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/kysely-postgres/skills/kysely-postgres/SKILL.md

@@ -1099,3 +1099,9 @@ const result = await db
 - The asserted type must structurally match the actual type (full type safety preserved)
 - Apply to several intermediate `with` clauses in large queries
 - TypeScript cannot automatically simplify these types - explicit assertion is required
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the kysely-postgres skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/linear/skills/linear/SKILL.md

@@ -1038,3 +1038,9 @@ node linear.mjs rebalance
 4. **Don't overcommit cycles.** Leave ~20% buffer for bugs, client requests, and interruptions.
 5. **Projects identify the client.** No need for client prefixes in issue titles or client labels — the project name (e.g., `[GBX] Portal`) already provides that context.
 6. **Triage first.** New client requests go to Backlog, not straight into the sprint — unless truly urgent.
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the linear skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/nitro-testing/skills/nitro-testing/SKILL.md

@@ -495,3 +495,9 @@ it("updates after user interaction", async () => {
 5. **Await everything** - `mountSuspended`, `trigger()`, `nextTick()` are all async.
 
 6. **Separate test configs** - Use `VITEST_ENV` to run frontend and backend tests with different environments.
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the nitro-testing skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md

@@ -25,6 +25,7 @@ For detailed patterns, see these topic-focused reference files:
 - [auth-patterns.md](./auth-patterns.md) - nuxt-auth-utils, OAuth, WebAuthn, middleware
 - [page-structure.md](./page-structure.md) - Keep pages thin, components do the work
 - [composables-utils.md](./composables-utils.md) - When to use composables vs utils
+- [formatters.md](./formatters.md) - Centralize currency/date/number formatters in useFormatters, never inline
 - [ssr-client.md](./ssr-client.md) - SSR + localStorage, hydration, VueUse
 - [deep-linking.md](./deep-linking.md) - URL params sync with filters and useFetch
 - [nitro-tasks.md](./nitro-tasks.md) - Background jobs, scheduled tasks, job queues
@@ -258,3 +259,9 @@ const activeProjects = computed(() =>
 ```
 
 This ensures your frontend types stay in sync with your API - if the endpoint return type changes, TypeScript will catch mismatches.
+
+## Contributing Back
+
+This skill grows by capturing what it missed. If you just worked through something in this domain that this skill did not cover — an error you had to figure out, a behavior that contradicts what is documented above, a workflow knot — ask the user: **"Want me to contribute this back to the nuxt-nitro-api skill?"**
+
+If yes, run `/contribute-skill`. If that command is not available, do the equivalent inline: distill the generic lesson (placeholders only — no project names, IDs, domains, or secrets), then branch or fork [gallop-systems/agent-skills](https://github.com/gallop-systems/agent-skills) and open a PR editing this skill.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/composables-utils.md

@@ -79,6 +79,11 @@ export const usePermissions = () => {
 - Data transformations, formatting, parsing
 - NO `use` prefix
 
+> **Formatters belong in one shared place.** The examples below show util *placement*,
+> not where to call formatters from. Never define a currency/date/number formatter inline
+> at the call site — centralize them in `useFormatters` or a shared util, and prefer
+> VueUse / date-fns over hand-rolling. See [formatters.md](./formatters.md).
+
 ```typescript
 // utils/formatting.ts
 export const formatDate = (date: string) => {

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/formatters.md

@@ -0,0 +1,139 @@
+# Formatters (Currency, Dates, Numbers)
+
+## Rule: Never define a formatter inline
+
+Whenever you need to format a value — currency, dates, times, numbers, percentages,
+file sizes, relative time, etc. — **do not define the formatter inline at the call site.**
+
+Before writing any new formatting logic:
+
+1. **Check if a shared formatter already exists.** Look for a `useFormatters`
+   composable (`/composables/useFormatters.ts`) or a formatting util
+   (`/utils/formatters.ts`, `/shared/utils/format.ts`). If a formatter for the value
+   you need is already there, **use it.**
+2. **If none exists, create one** in the appropriate shared location, then use it.
+   Do not scatter a one-off `Intl.NumberFormat(...)` or `new Date(...).toLocaleString(...)`
+   at the call site.
+
+This keeps formatting consistent across the app (one source of truth for locale,
+currency, date style) and makes a future change — switching locale, adding a currency,
+tweaking date format — a single edit instead of a hunt-and-replace.
+
+```typescript
+// WRONG - inline formatter at the call site
+<template>
+  <span>{{ new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(total) }}</span>
+  <span>{{ new Date(order.createdAt).toLocaleDateString("en-US", { dateStyle: "medium" }) }}</span>
+</template>
+
+// RIGHT - use the shared formatter
+<script setup lang="ts">
+const { formatCurrency, formatDate } = useFormatters();
+</script>
+<template>
+  <span>{{ formatCurrency(total) }}</span>
+  <span>{{ formatDate(order.createdAt) }}</span>
+</template>
+```
+
+## Reach for existing libraries before hand-rolling
+
+Two libraries are almost always already available — prefer them over writing formatting
+or date logic by hand:
+
+- **VueUse** ships a broad set of formatting/reactive helpers out of the box (auto-imported
+  in Nuxt). Before building your own, check for one of these:
+  - `useDateFormat(date, "YYYY-MM-DD HH:mm")` — reactive date formatting
+  - `useTimeAgo(date)` — reactive "3 minutes ago" relative time
+  - `useNow()` / `useTimestamp()` — reactive current time to drive the above
+  - `formatTimeAgo()` — the non-reactive function form
+  Wrap these in `useFormatters` when you want a single app-wide configuration point,
+  rather than calling them ad hoc at each site.
+
+- **date-fns is the preferred way to work with dates.** Do **not** parse, compare, add,
+  or diff dates by hand (no manual `string.split("-")`, no `new Date(a) - new Date(b)`
+  arithmetic, no hand-rolled "is same day"). Use `date-fns`:
+
+  ```typescript
+  import { format, parseISO, formatDistanceToNow, differenceInDays, isSameDay } from "date-fns";
+
+  format(parseISO(order.createdAt), "MMM d, yyyy");   // "Jun 12, 2026"
+  formatDistanceToNow(parseISO(order.createdAt));      // "about 2 hours"
+  differenceInDays(parseISO(end), parseISO(start));    // 5
+  ```
+
+  ```typescript
+  // WRONG - parsing/diffing dates by hand
+  const [y, m, d] = order.createdAt.split("T")[0].split("-");
+  const daysLeft = Math.floor((new Date(end) - new Date(start)) / 86400000);
+  ```
+
+  Still route date-fns calls through `useFormatters` (or a shared util) rather than
+  importing and calling them inline everywhere — same single-source-of-truth reason.
+
+## Where to put the formatters
+
+Pick the location by what the formatter needs (see [composables-utils.md](./composables-utils.md)):
+
+- **Needs Nuxt/Vue context** (e.g. reads locale/currency from `useRuntimeConfig()`,
+  `useI18n()`, or user preferences) → **composable** `useFormatters` in
+  `/composables/useFormatters.ts`.
+- **Pure, client-only** → **util** in `/utils/formatters.ts`.
+- **Used on both client and server** (e.g. an invoice rendered in SSR *and* in a
+  server API response) → **shared util** in `/shared/utils/format.ts`.
+
+When in doubt and the formatters are pure, prefer `useFormatters` as a composable so
+there is one obvious, discoverable place to look — and so it can later pull locale
+from context without moving every call site.
+
+### Composable form (`useFormatters`)
+
+```typescript
+// composables/useFormatters.ts
+export const useFormatters = () => {
+  const config = useRuntimeConfig();
+  const locale = config.public.locale ?? "en-US";
+  const currency = config.public.currency ?? "USD";
+
+  const currencyFmt = new Intl.NumberFormat(locale, { style: "currency", currency });
+  const dateFmt = new Intl.DateTimeFormat(locale, { dateStyle: "medium" });
+  const dateTimeFmt = new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short" });
+  const numberFmt = new Intl.NumberFormat(locale);
+  const percentFmt = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 });
+
+  return {
+    formatCurrency: (amount: number) => currencyFmt.format(amount),
+    formatDate: (date: string | Date) => dateFmt.format(new Date(date)),
+    formatDateTime: (date: string | Date) => dateTimeFmt.format(new Date(date)),
+    formatNumber: (n: number) => numberFmt.format(n),
+    formatPercent: (n: number) => percentFmt.format(n),
+  };
+};
+```
+
+> **Reuse the `Intl.*` instances.** Construct each formatter once (as above), not on
+> every call. `Intl.NumberFormat`/`Intl.DateTimeFormat` construction is comparatively
+> expensive, so building a new one inside a render or a loop is wasteful.
+
+### Pure util / shared form
+
+If no Nuxt context is needed, the same functions live as plain exports:
+
+```typescript
+// shared/utils/format.ts  (or utils/formatters.ts for client-only)
+const currencyFmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
+const dateFmt = new Intl.DateTimeFormat("en-US", { dateStyle: "medium" });
+
+export const formatCurrency = (amount: number) => currencyFmt.format(amount);
+export const formatDate = (date: string | Date) => dateFmt.format(new Date(date));
+```
+
+## Checklist before adding a formatter
+
+- [ ] Searched for an existing `useFormatters` / `formatters` / `format` util?
+- [ ] Reusing it if a matching formatter exists?
+- [ ] Checked for a VueUse helper (`useDateFormat`, `useTimeAgo`, …) before hand-rolling?
+- [ ] Using `date-fns` for any date parsing/formatting/math — not hand-parsing strings?
+- [ ] If creating, placed it in the right shared location (composable vs util vs shared)?
+- [ ] Constructed the `Intl.*` instance once, not per call?
+- [ ] Replaced the inline formatting at the call site with the shared function?

package/plugins/volt-primevue/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "volt-primevue",
+  "description": "Volt (unstyled PrimeVue + Tailwind) UI: adding components, pt: pass-through styling, the surface-* vs semantic-token color model, and prefers-color-scheme dark mode",
+  "version": "1.0.0",
+  "author": {
+    "name": "yeedle"
+  }
+}

package/plugins/volt-primevue/skills/volt-primevue/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: volt-primevue
+description: Build UIs with Volt (unstyled PrimeVue + Tailwind). Covers adding components, pt: pass-through customization, choosing components, and the two-layer color model for prefers-color-scheme dark mode.
+---
+
+# Volt + PrimeVue UI
+
+Volt components are **PrimeVue unstyled components styled with Tailwind**. They
+ship as source you vendor into `src/volt/` and register with a `Volt` prefix, so
+you own the markup but track upstream styling conventions.
+
+## When to Use This Skill
+
+- Building UI in a Nuxt + Tailwind v4 + PrimeVue/Volt project
+- Adding or customizing a Volt component
+- Anything color/theme/dark-mode related in this stack
+- Deciding between a Volt component and a hand-rolled one
+
+## What Volt is
+
+- PrimeVue **unstyled** components + Tailwind classes, vendored under `src/volt/`.
+- Registered with a `Volt` prefix via `nuxt.config.ts` (`<VoltButton>`, `<VoltCard>`, …).
+- `app/assets/css/main.css` has `@source "../../../src/volt";` so Tailwind scans
+  the vendored sources for class names. If a Volt class isn't generating, that
+  `@source` line is the first thing to check.
+
+## Adding components
+
+Use the CLI — **never hand-create a Volt component**:
+
+```bash
+npx volt-vue add MultiSelect      # adds src/volt/MultiSelect.vue
+```
+
+Hand-writing one means you've guessed the PrimeVue part structure and the
+`surface-*`/`dark:` conventions; the generator gets both right and stays
+consistent with upstream.
+
+## Customization — `pt:` pass-through
+
+Volt uses PrimeVue's pass-through API. Target a component's internal section with
+`pt:<section>:class`:
+
+```vue
+<VoltButton pt:root:class="bg-zinc-900 hover:bg-zinc-800" />
+<VoltCard pt:root:class="rounded-2xl" pt:body:class="p-6" />
+```
+
+**Use `pt:`, not a plain `class`.** Volt merges classes with
+[tailwind-merge](https://volt.primevue.org/overview/#twmerge), and the two paths
+differ in precedence:
+
+- `pt:{section}:class` is **merged with the component's defaults** and reliably
+  overrides them — `pt:root:class="bg-primary"` wins.
+- A plain `class="bg-primary"` has **lower precedence and may not apply** — its
+  conflicting utilities can lose to the component's own classes.
+
+So `<VoltInputText pt:root:class="bg-primary" />` works; `<VoltInputText
+class="bg-primary" />` may silently not.
+
+What `pt:` **can't** do is change DOM — it only restyles sections the component
+already renders. To add an element the component doesn't have (e.g. an animated
+overlay), you have two honest options, because Volt components are **vendored and
+yours to edit** (see [Choosing a component](#choosing-a-component-volt-vs-custom)):
+edit the component's source in `src/volt/`, or build a standalone component.
+
+## Choosing a component: Volt vs custom
+
+Volt gives you selection semantics + accessibility for free. The question is only
+whether you need DOM/behavior the component doesn't render — and remember Volt
+components are **vendored and editable**, so "the component doesn't do X" has
+three answers, not two: restyle via `pt:`, **edit the source in `src/volt/`**, or
+build standalone.
+
+Worked example — **segmented toggle** (`SelectButton` vs a custom `SlidingTabs`):
+
+- `VoltSelectButton` ships v-model, single/multi-select, label+icon options, and
+  proper radiogroup a11y, with a *highlighted-active* look.
+- A custom `SlidingTabs` adds an **animated indicator** (a single shared element
+  that measures the active button and slides), responsive label collapse, and
+  token-matched styling.
+- The slide **can't** come from `pt:` — `SelectButton` toggles a background class
+  per button and has no shared, position-measured overlay, and `pt:` changes
+  classes, not DOM. But that doesn't force a rewrite: since the source lives in
+  `src/volt/SelectButton.vue`, adding the indicator **there** is a legitimate
+  option (you keep its a11y + selection model).
+
+So the real decision:
+
+- **No animation needed → `SelectButton` as-is** (`pt:` to match your design).
+  Free a11y + multi-select; don't reinvent it.
+- **Animated indicator / responsive collapse needed →** either **edit the
+  vendored `SelectButton`** (keep its a11y, accept that you now own that file and
+  lose easy `volt-vue add` regeneration) **or build a standalone `SlidingTabs`**
+  (clean and decoupled, but you owe the a11y yourself — `role="group"` +
+  `aria-pressed` at minimum). Standalone wins when it's a *filter* toggle rather
+  than a form field; editing the source wins when you want the full input
+  semantics.
+
+## Theming & dark mode
+
+This is the part people get wrong. Read **[theming.md](./theming.md)** — the
+two-layer color model (`surface-*` for Volt, semantic tokens for your markup),
+why they can't be unified, and the `prefers-color-scheme` mechanics.
+
+The one-paragraph version: dark mode follows the OS via
+`@media (prefers-color-scheme: dark)`. **Your app markup** uses semantic `@theme`
+tokens (`bg-surface`, `text-fg`, `border-line`) written **once** — the
+`--color-*` var flips in the dark media block, so there's no `dark:` half to
+forget. **Volt internals** stay on the `surface-*` scale with explicit `dark:`
+pairs — they need the full 0–950 ramp, and leaving them as `volt-vue add`
+generated them keeps regeneration easy. You *could* restyle a vendored component
+to tokens (it's your code), but the small token set can't express the whole ramp,
+so don't — tokens for your opinionated markup, `surface-*` for the component
+library.
+
+## Gotchas
+
+See **[gotchas.md](./gotchas.md)** — the ones that cost real debugging time:
+
+- `@reference "main.css"` (not `"tailwindcss"`) for `@apply` of custom tokens in
+  SFC `<style>` blocks.
+- JS-driven colors (ApexCharts, canvas) can't read CSS tokens — pick them from a
+  reactive `prefers-color-scheme` palette.
+- A bare `boolean` prop casts to `false` when absent — default it with
+  `withDefaults`, never rely on `undefined`.

package/plugins/volt-primevue/skills/volt-primevue/gotchas.md

@@ -0,0 +1,66 @@
+# Gotchas
+
+The ones that cost real debugging time in this stack.
+
+## `@apply` of custom tokens in `<style>` needs `@reference "main.css"`
+
+Tailwind v4 SFC `<style>` blocks need a `@reference` to resolve `@apply`. The
+trap: `@reference "tailwindcss"` only loads the **default** theme — built-in
+colors (`zinc`, etc.) work, but your custom `@theme` tokens (`text-fg`,
+`bg-surface`) fail with *"Cannot apply unknown utility class."*
+
+```vue
+<style scoped>
+/* ❌ @reference "tailwindcss";  → @apply text-fg fails */
+@reference "../assets/css/main.css";   /* ✅ exposes your tokens */
+.prose :where(h2) { @apply text-fg; }
+</style>
+```
+
+`@reference` is relative to the SFC. Note `yarn build` validates `@apply` in
+`<style>`; a bare `@tailwindcss/cli` compile does **not**, so the CLI can pass
+while the real build fails — include `build` in your check.
+
+## JS-driven colors can't read CSS tokens — use a reactive palette
+
+Anything that sets colors as JS values (ApexCharts, canvas, SVG attributes
+written from script) can't use `bg-surface`/`var(--color-fg)` — the value is
+baked at render. Pick concrete colors from a reactive `prefers-color-scheme`
+match and recompute on change:
+
+```ts
+const isDark = ref(false);
+let mq: MediaQueryList | null = null;
+const sync = () => (isDark.value = mq?.matches ?? false);
+onMounted(() => {
+  mq = window.matchMedia("(prefers-color-scheme: dark)");
+  sync();
+  mq.addEventListener("change", sync);
+});
+onBeforeUnmount(() => mq?.removeEventListener("change", sync));
+
+const palette = computed(() =>
+  isDark.value ? { fg: "#f4f4f5", line: "#f4f4f5", grid: "#27272a" }
+               : { fg: "#18181b", line: "#18181b", grid: "#f4f4f5" });
+```
+
+Mirror the dark values from `main.css`. A chart `colors: ["#18181b"]` (near-black)
+is invisible on dark — invert the line to a light value via the palette.
+
+## A bare `boolean` prop casts to `false` when absent — `withDefaults` it
+
+Vue's Boolean-prop casting: a prop typed `boolean` with **no default** coerces to
+`false` when the parent doesn't pass it — *not* `undefined`. So a "default-on"
+flag written as `responsive?: boolean` + `props.responsive !== false` is always
+`false` unless explicitly passed, and the feature silently never fires.
+
+```ts
+// ❌ absent → false → feature off, no error
+const props = defineProps<{ responsive?: boolean }>();
+// ✅ absent → true
+const props = withDefaults(defineProps<{ responsive?: boolean }>(), { responsive: true });
+```
+
+Not Volt-specific, but it bit the `SlidingTabs` responsive collapse, so it lives
+here. Any "defaults to on" boolean prop must use `withDefaults` (or invert it to
+an opt-out flag that naturally defaults false).

package/plugins/volt-primevue/skills/volt-primevue/theming.md

@@ -0,0 +1,123 @@
+# Theming & dark mode
+
+Dark mode follows the OS: `@media (prefers-color-scheme: dark)`. No toggle, no
+`dark` class on `<html>`. Tailwind v4's `dark:` variant also keys on
+`prefers-color-scheme` by default, so everything reacts to the same signal.
+
+There are **two color systems** in play, and the whole skill is knowing which to
+use where.
+
+## The two layers
+
+| | App markup (you own) | Volt internals (vendored) |
+|---|---|---|
+| **System** | semantic `@theme` tokens | `surface-*` scale + `dark:` pairs |
+| **Example** | `bg-surface text-fg` | `bg-surface-0 dark:bg-surface-900` |
+| **How it flips** | the `--color-*` var changes value in the dark media block | each shade is fixed; the component picks the dark end with `dark:` |
+| **You write** | once | both halves |
+
+### Why not use semantic tokens everywhere (incl. Volt)?
+
+You *can* — Volt components are vendored and editable, so nothing stops you from
+restyling one to `bg-surface text-fg`. The reasons not to are practical, in
+descending order of weight:
+
+1. **Vocabulary mismatch (the real one).** Semantic tokens are a small,
+   opinionated set (`surface`, `surface-muted`, `line`, `fg`, `fg-muted`, …) for
+   "card / text / border" decisions. A component library reaches all over the
+   0–950 ramp — subtle fills, two border weights, icon idle vs hover, elevation
+   layering. To express all of Volt in tokens you'd expand them until they *are*
+   the ramp, at which point you've just renamed `surface-*`.
+2. **Regeneration convenience.** `volt-vue add` scaffolds a component in the
+   upstream `surface-*` + `dark:` convention. Restyle it and you own that file —
+   re-adding or pulling a newer version later means redoing your edits. Leaving
+   Volt as-generated keeps that escape hatch cheap. (This is a convenience cost,
+   not "you diverge from upstream forever" — there's no continuous sync; you add
+   once and own it either way.)
+3. **The convention they ship in.** As generated, `--p-surface-0…950` are fixed
+   (never flipped), so a Volt component flips by *picking the dark end* with
+   `dark:bg-surface-900` — not by a value that changes. Semantic tokens flip the
+   variable's value instead, so one class covers both schemes. You could rewrite
+   a component to the token style, but then you're back to reasons 1 and 2.
+
+## The token set
+
+Defined in `app/assets/css/main.css`: light values in a top-level `@theme`
+block, dark values overriding the same `--color-*` vars inside the
+`prefers-color-scheme: dark` media block.
+
+```css
+@theme {
+  --color-canvas: #fafafa;        /* app background */
+  --color-surface: #ffffff;       /* cards, panels, dialogs */
+  --color-surface-muted: #fafafa; /* subtle fills, row hover */
+  --color-line: #e4e4e7;          /* borders */
+  --color-line-soft: #f4f4f5;     /* soft dividers */
+  --color-fg: #18181b;            /* primary text */
+  --color-fg-muted: #71717a;      /* secondary text */
+  --color-fg-subtle: #a1a1aa;     /* tertiary text */
+  --color-accent: #18181b;        /* inverted/primary fills (buttons) */
+  --color-on-accent: #ffffff;     /* text/icon on an accent fill */
+  --color-fill: #e4e4e7;          /* neutral solid fills: avatars, tracks, dots */
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-canvas: #09090b;
+    --color-surface: #18181b;
+    --color-surface-muted: #27272a;
+    --color-line: #27272a;
+    --color-line-soft: #27272a;
+    --color-fg: #f4f4f5;
+    --color-fg-muted: #b4b4bc;    /* lifted off a strict mirror-invert for legibility */
+    --color-fg-subtle: #8c8c95;   /* ~5.5:1 on near-black */
+    --color-accent: #f4f4f5;      /* inverts so filled buttons read on dark */
+    --color-on-accent: #18181b;
+    --color-fill: #3f3f46;
+  }
+}
+```
+
+The dark `fg-muted` / `fg-subtle` are **lifted** off a strict mirror-invert —
+the perfectly-inverted values are too dark to read on near-black.
+
+### Where each layer lives (and why it's not fighting Volt)
+
+[Volt's Nuxt setup](https://volt.primevue.org/nuxt/#css-variables) prescribes the
+`--p-*` palette + semantic tokens in **`:root`**, with dark mode via
+`@media (prefers-color-scheme: dark)`. Keep that exactly as-is — don't move
+`--p-*` into `@theme`; the `tailwindcss-primeui` plugin already turns them into
+`surface-*` / `primary-*` utilities.
+
+Your semantic tokens go in **`@theme`** instead, because that's the Tailwind v4
+mechanism that generates the utilities (`--color-canvas` → `bg-canvas`). Defining
+them only in `:root` would set the variable but produce **no class**. So:
+
+- `--p-*` → `:root` (Volt's way; plugin generates `surface-*`)
+- `--color-*` → `@theme` (Tailwind's way; generates `bg-surface`, `text-fg`, …)
+
+Different namespaces, no collision: `bg-surface-0` (primeui, numbered) and
+`bg-surface` (your token, bare) coexist. Dark values for **both** sit in the same
+`prefers-color-scheme` block — your `--color-*` overrides next to Volt's `--p-*`
+overrides.
+
+## The naming trap (this one bites)
+
+In Tailwind v4 the utility name is the **full** variable suffix:
+
+- `--color-fg-subtle` → `text-fg-subtle`  ✅
+- `text-subtle` ❌ — generates **nothing**, element falls back to near-black
+
+A wrong/shortened token name fails silently (no class generated), so a
+suspicious "secondary text is black in dark mode" is almost always a misnamed
+token, not a wrong value. **Compile the CSS and grep the generated utilities** —
+don't eyeball the browser.
+
+## Adding a new token
+
+1. Add `--color-foo: <light>;` to the `@theme` block.
+2. Add `--color-foo: <dark>;` inside the dark media block.
+3. Use `bg-foo` / `text-foo` / `border-foo` — done, both schemes covered.
+
+No `dark:` variant, ever, for app markup. If you're typing `dark:` in a page or
+app component, you're reaching for the wrong layer.