@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/app-dev/python-backend/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: python-backend
+description: "Python backend architecture for FastAPI, Tortoise ORM, Pydantic Settings, loguru, and uv. Also: uv.lock installs in CI/Docker via a proxy or mirror (`uv sync --frozen` bypasses it), slow uv installs on runners, relocking."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Python Backend Conventions
+**Stack:** Python 3.12 | FastAPI | Tortoise-ORM | Aerich | Pydantic v2 | loguru | uv | pytest
+
+## Critical Rule
+
+Use **uv** for all environment, dependency, and tool commands. No raw `pip`, `poetry`, `pipenv`, or manual `venv`.
+
+CI/image installs: `uv sync --frozen` bypasses proxies and mirrors; use the hash-checked
+script; relock on PyPI only: [references/uv-installs.md](references/uv-installs.md).
+
+---
+
+## Tooling & Commands
+
+### Dependencies
+
+```bash
+# Runtime deps
+uv add fastapi tortoise-orm aerich pydantic pydantic-settings loguru
+
+# Dev deps
+uv add --dev pytest ruff mypy
+```
+
+### Running Commands
+
+```bash
+uv run uvicorn app.main:app --reload  # Start app
+uv run pytest                          # Run tests
+uv run ruff check .                    # Lint
+uv run mypy app                        # Type check
+uv run aerich migrate                  # Run migrations
+uv run aerich upgrade                  # Apply migrations
+```
+
+---
+
+## Architecture
+
+```
+app/
+├── api/          # API Layer - routes, endpoints
+├── services/     # Service Layer - business logic
+├── dal/          # Data Access Layer - Tortoise queries
+├── models/       # Tortoise ORM models
+├── schemas/      # Pydantic schemas
+└── core/         # Infrastructure
+    ├── config.py     # Pydantic Settings
+    ├── logging.py    # loguru configuration
+    ├── tortoise.py   # DB init/close
+    ├── errors.py     # Domain exceptions
+    └── security.py   # Auth utilities
+```
+
+### Export Rule
+
+All modules in `core`, `dal`, `services`, `schemas`, `api` must define `__all__`.
+All packages (`__init__.py`) re-export the public API using `__all__`.
+
+---
+
+## Config Management
+
+Location: `app/core/config.py`
+
+```python
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import AnyUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["Settings", "get_settings"]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    ENV: Literal["local", "dev", "staging", "prod"] = "local"
+    DATABASE_URL: AnyUrl
+    LOG_LEVEL: str = "INFO"
+    APP_NAME: str = "Backend"
+    API_V1_PREFIX: str = "/api/v1"
+    JWT_SECRET_KEY: str
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Global, cached settings accessor."""
+    return Settings()
+```
+
+**Rule:** Never create new `Settings()` manually; always use `get_settings()`.
+
+---
+
+## Logging
+
+Location: `app/core/logging.py`
+
+```python
+from __future__ import annotations
+
+import sys
+from loguru import logger
+
+from app.core.config import get_settings
+
+__all__ = ["logger", "configure_logging"]
+
+
+def configure_logging() -> None:
+    """Configure global loguru logger. Call once at app startup."""
+    settings = get_settings()
+
+    logger.remove()
+    logger.add(
+        sys.stderr,
+        level=settings.LOG_LEVEL,
+        enqueue=True,
+        backtrace=False,
+        diagnose=False,
+        serialize=settings.ENV in ("staging", "prod"),
+    )
+```
+
+**Rule:** Import `logger` from `app.core.logging` (not `loguru` directly).
+
+---
+
+## Tortoise-ORM & Aerich
+
+Location: `app/core/tortoise.py`
+
+```python
+from __future__ import annotations
+
+from tortoise import Tortoise
+
+from app.core.config import get_settings
+
+__all__ = ["TORTOISE_ORM", "init_db", "close_db"]
+
+settings = get_settings()
+
+TORTOISE_ORM = {
+    "connections": {
+        "default": str(settings.DATABASE_URL),
+    },
+    "apps": {
+        "models": {
+            "models": ["app.models.user", "app.models.order", "aerich.models"],
+            "default_connection": "default",
+        },
+    },
+}
+
+
+async def init_db() -> None:
+    await Tortoise.init(config=TORTOISE_ORM)
+
+
+async def close_db() -> None:
+    await Tortoise.close_connections()
+```
+
+---
+
+## Data Access Layer (DAL)
+
+Location: `app/dal/**`
+
+- Functional style, Tortoise only
+- No FastAPI, no Pydantic, no auth, no logging
+
+```python
+# app/dal/order_dal.py
+from __future__ import annotations
+
+from tortoise.transactions import in_transaction
+from app.models.order import Order, OrderItem
+
+__all__ = ["get_user_orders_with_items", "create_order_with_items"]
+
+
+async def get_user_orders_with_items(
+    user_id: int,
+    limit: int = 20,
+    offset: int = 0,
+) -> list[Order]:
+    return await (
+        Order
+        .filter(user_id=user_id)
+        .prefetch_related("items")
+        .order_by("-created_at")
+        .offset(offset)
+        .limit(limit)
+    )
+
+
+async def create_order_with_items(
+    user_id: int,
+    items: list[dict],
+) -> Order:
+    async with in_transaction() as conn:
+        order = await Order.using_db(conn).create(user_id=user_id)
+        for item in items:
+            await OrderItem.using_db(conn).create(order=order, **item)
+        return order
+```
+
+### Complexity Rule
+
+- **Simple / one-off** queries: Direct Tortoise in services
+- **Complex / reused / transactional**: DAL functions
+
+---
+
+## Service Layer
+
+Location: `app/services/**`
+
+- Center of business logic
+- Uses DAL for complex queries
+- Raises domain exceptions from `app/core/errors.py`
+- Uses `logger` for business-level events
+
+```python
+# app/services/order_service.py
+from __future__ import annotations
+
+from app.schemas.order import OrderRead
+from app.dal import get_user_orders_with_items
+from app.core.logging import logger
+
+__all__ = ["list_my_orders", "get_order_detail", "create_order"]
+
+
+async def list_my_orders(
+    user_id: int,
+    limit: int = 20,
+    offset: int = 0,
+) -> list[OrderRead]:
+    orders = await get_user_orders_with_items(user_id, limit, offset)
+    logger.info("Listed orders", user_id=user_id, count=len(orders))
+    return [OrderRead.model_validate(o) for o in orders]
+```
+
+---
+
+## API Layer
+
+Location: `app/api/**`
+
+- Uses `APIRouter`, `Depends`, `HTTPException`
+- Converts domain exceptions to HTTP status codes
+
+```python
+# app/api/v1/orders.py
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException
+from app.schemas.order import OrderRead
+from app.services import list_my_orders, get_order_detail
+from app.core.errors import OrderNotFoundError, PermissionDeniedError
+from app.api.deps import get_current_user
+
+__all__ = ["router"]
+
+router = APIRouter(prefix="/orders", tags=["orders"])
+
+
+@router.get("/", response_model=list[OrderRead])
+async def list_orders(current_user=Depends(get_current_user)) -> list[OrderRead]:
+    return await list_my_orders(user_id=current_user.id)
+
+
+@router.get("/{order_id}", response_model=OrderRead)
+async def get_order(
+    order_id: int,
+    current_user=Depends(get_current_user),
+) -> OrderRead:
+    try:
+        return await get_order_detail(current_user.id, order_id)
+    except OrderNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except PermissionDeniedError as e:
+        raise HTTPException(status_code=403, detail=str(e))
+```
+
+---
+
+## Do / Don't
+
+### Do
+
+- Use **Pydantic Settings** with `get_settings()` for config
+- Use **loguru** via `app.core.logging.logger`
+- Keep API -> Service -> DAL separation
+- Use DAL for complex/reused DB logic
+- Use `__all__` and package `__init__.py` for explicit exports
+- Use pytest for all tests
+
+### Don't
+
+- Don't use raw `pip`, `venv`, or `pytest` outside `uv run`
+- Don't import `loguru.logger` directly
+- Don't instantiate `Settings()` directly
+- Don't call Tortoise from API routes
+- Don't let DAL log or handle business logic
+- Don't raise `HTTPException` outside the API layer

package/skills/app-dev/python-backend/assets/uv-install.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Install a locked selection of a uv project or workspace, downloading
+# third-party packages through the configured package index instead of the
+# file URLs recorded in uv.lock.
+#
+# Usage, from the directory that holds uv.lock:
+#   uv-install.sh [uv export selection args...]
+#   uv-install.sh --package api --extra dev
+#   uv-install.sh --package engine --no-dev --no-emit-package nvidia-nccl-cu12
+# Then run commands with `uv run --no-sync`.
+#
+# Why not `uv sync --frozen`: it downloads every locked file from the URL in
+# uv.lock (files.pythonhosted.org) and ignores UV_DEFAULT_INDEX, so a proxy or
+# mirror never serves the package files. Instead:
+#   1. export the selection's third-party pins with their sha256 hashes,
+#   2. `uv pip sync --require-hashes` them through the configured index, which
+#      rejects any file whose hash differs from uv.lock,
+#   3. install the selected workspace members editable with --no-deps.
+# The environment matches what `uv sync --frozen <args>` would install. With
+# no index configured, step 2 uses PyPI, so the same script works anywhere.
+set -euo pipefail
+
+[[ -f uv.lock ]] || {
+  echo "uv-install.sh: run from the directory that holds uv.lock" >&2
+  exit 2
+}
+
+tmp="$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/uv-install.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT
+
+export_args=(--frozen --format requirements.txt --no-header --no-annotate "$@")
+uv export "${export_args[@]}" --no-emit-workspace -o "$tmp/third-party.txt" >/dev/null
+uv export "${export_args[@]}" --no-hashes -o "$tmp/all.txt" >/dev/null
+
+editables=()
+while IFS= read -r path; do
+  editables+=(-e "$path")
+done < <(sed -n 's/^-e //p' "$tmp/all.txt")
+
+venv="${UV_PROJECT_ENVIRONMENT:-.venv}"
+[[ "$venv" == /* ]] || venv="$PWD/$venv"
+uv venv --quiet --allow-existing "$venv"
+export VIRTUAL_ENV="$venv"
+
+uv pip sync --require-hashes "$tmp/third-party.txt"
+if ((${#editables[@]})); then
+  uv pip install --no-deps "${editables[@]}"
+fi

package/skills/app-dev/python-backend/references/uv-installs.md

@@ -0,0 +1,83 @@
+# Installing a uv lockfile in CI and images
+
+> Read when: a CI job or Dockerfile installs a uv project, installs are slow on the
+> self-hosted runners, a package proxy or mirror "isn't being used", or someone is about
+> to relock `uv.lock`.
+
+## `uv sync --frozen` bypasses the proxy
+
+`uv sync --frozen` (and `--locked`) downloads every locked file from the URL recorded in
+`uv.lock`, normally `files.pythonhosted.org`. It ignores `UV_DEFAULT_INDEX`, so a LAN
+proxy or regional mirror sees only index lookups and build-backend fetches, never the
+package files. On the self-hosted runners this cost about 2m20s each for spaCy and SciPy
+(~0.2 MB/s) on files the proxy already had; one measured sync sent 31 wheel downloads
+to PyPI and 14 to the proxy.
+
+Dropping `--frozen` is not the fix: plain `uv sync` against a different index can
+re-resolve and rewrite `uv.lock`, so what gets installed is no longer what was locked.
+
+## The pattern: export, then hash-checked install through the index
+
+[`assets/uv-install.sh`](../assets/uv-install.sh) does it in three steps. Copy it into
+the repo (for example `scripts/ci/uv-install.sh`), run it from the directory that holds
+`uv.lock`, and pass the same selection flags you would give `uv sync`:
+
+```bash
+bash scripts/ci/uv-install.sh --package api --extra dev
+uv run --no-sync pytest            # --no-sync, or uv run re-syncs from uv.lock URLs
+```
+
+1. `uv export --frozen --no-emit-workspace` writes the selection's third-party pins with
+   their sha256 hashes and no URLs.
+2. `uv pip sync --require-hashes` installs them through whatever index is configured.
+   A file whose hash differs from `uv.lock` is rejected, so integrity matches `--frozen`.
+3. `uv pip install --no-deps -e …` installs the selected workspace members, taken from
+   the `-e` lines of a `--no-hashes` export.
+
+The result is the environment `uv sync --frozen <same args>` would build. With no index
+configured, step 2 uses PyPI, so the same script works on GitHub-hosted runners and
+laptops. Measured with an empty cache: 11.8s with `uv sync --frozen`, 1.6s through the
+proxy (all 47 files from the proxy).
+
+This is the one place `uv pip` and `uv venv` are the right tools; everywhere else use
+`uv sync`, `uv add` and `uv run`.
+
+In a Dockerfile the same idea needs only steps 1 and 2 (the `docker` skill's template).
+
+## Caches and Python on the self-hosted runners
+
+- **Put uv's cache and managed Pythons on the persistent work disk.** The runner home is
+  ephemeral, so the default `UV_CACHE_DIR` starts cold every job. `_work` is reused per
+  slot and is on the same filesystem as the venv, so uv hardlinks instead of copying:
+
+  ```yaml
+  - name: Persist uv cache per runner slot
+    run: |
+      base="$(dirname "$RUNNER_WORKSPACE")/.uv"
+      echo "UV_CACHE_DIR=$base/cache" >> "$GITHUB_ENV"
+      echo "UV_PYTHON_INSTALL_DIR=$base/python" >> "$GITHUB_ENV"
+  ```
+
+- **`actions/setup-python` breaks subprocesses that get a minimal environment.** Its
+  toolcache Python finds `libpython3.12.so` through `LD_LIBRARY_PATH`; a test that spawns
+  `python3` with a stripped env fails with `error while loading shared libraries`.
+  uv-managed CPython (`UV_PYTHON_PREFERENCE=only-managed`) is self-contained, but it
+  downloads ~33 MB from GitHub per job unless `UV_PYTHON_INSTALL_DIR` persists it (above).
+
+## Keep CI installs lean
+
+- Skip heavy packages a test never loads. xgboost on Linux pulls `nvidia-nccl-cu12`
+  (276 MB, ~6.5 min); it is loaded only for multi-GPU training, so
+  `--no-emit-package nvidia-nccl-cu12` is safe in CI.
+- Pass `--no-dev` when the dev group is notebook or editor tooling the job does not run.
+
+## Relocking
+
+Lock against official PyPI, never the proxy:
+
+```bash
+UV_DEFAULT_INDEX=https://pypi.org/simple uv lock
+```
+
+Relocking through the proxy has hung, and the committed lock's URLs must stay official
+PyPI: `pip-audit` and other provenance checks read them.

package/skills/app-dev/python-backend/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/app-dev/shadcn/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/app-dev/shadcn/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: shadcn
+description: "Add or debug shadcn/ui in a React/Next.js project: components.json, shadcn init/add, presets, registries, Tailwind styling, base/radix/aria composition, component fixes, and list-index pages — where the default is the DiceUI data table with filter/sort/pagination in the URL via nuqs, not a bare shadcn Table."
+allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# shadcn/ui
+
+Components are added as **source code** via the CLI — you edit them like your own files.
+
+**This page is an index.** Each rule below is the short form; the linked file carries the reasoning and the Incorrect/Correct pairs. Read the row for your task before acting — the rules are stated flat here and the *why* is what stops you misapplying them.
+
+> Run every CLI command with the project's runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Pick from the lockfile or `package.json`'s `packageManager` — `shadcn info` does not report it.
+
+## Current Project Context
+
+```json
+!`npx shadcn@latest info --json`
+```
+
+Blocks: `project`, `config`, `preset`, `components`, `links`. Names are exact — `config.rsc` not `isRSC`, `project.tailwindCss` not `tailwindCssFile`, `project.importAlias` not `aliasPrefix`, and there is no `packageManager`. Full table: [cli.md](./cli.md#info--project-information).
+
+Four fields change what you write: **`config.base`** (`radix` | `base` | `aria` — different APIs), **`config.rsc`** (`"use client"` needed?), **`config.iconLibrary`** (never assume `lucide-react`), **`config.aliases`**/`resolvedPaths` (never hardcode `@/`).
+
+## Routing
+
+| Task | Read |
+|---|---|
+| Pick a component; the core code patterns | [rules/component-selection.md](./rules/component-selection.md) |
+| Forms — layout, validation, errors, inputs | [rules/forms.md](./rules/forms.md) |
+| Compose — groups, overlays, Card, Tabs, Avatar | [rules/composition.md](./rules/composition.md) |
+| Style — colors, spacing, variants, `cn()`, dark mode | [rules/styling.md](./rules/styling.md) |
+| Icons — `data-icon`, sizing, icons as props | [rules/icons.md](./rules/icons.md) |
+| A list/index page or any data table | [rules/data-table.md](./rules/data-table.md) |
+| `asChild` vs `render`; `base`/`radix`/`aria` splits | [rules/base-vs-radix.md](./rules/base-vs-radix.md) |
+| Any CLI command, flag, preset, registry | [cli.md](./cli.md) |
+| Theming, CSS variables, extending a component | [customization.md](./customization.md) |
+| MCP server | [mcp.md](./mcp.md) |
+
+## Principles
+
+1. **Use an existing component first** (`npx shadcn@latest search`), and **compose rather than reinvent** — a settings page is Tabs + Card + form controls.
+2. **Built-in variants before custom styles; semantic colors only** — never `bg-blue-500`.
+3. **Read the docs before writing a component** — `npx shadcn@latest docs <component>`, then fetch the URLs. APIs differ per base and shift between releases, so guessing yields code that looks right and isn't.
+
+## Critical Rules
+
+**Styling** → [styling.md](./rules/styling.md)
+
+- `className` for layout only — never component colors or typography, and no manual `dark:` overrides.
+- `gap-*` not `space-x-*`/`space-y-*`; `size-*` when width and height match; `truncate` not the longhand.
+- `cn()` for conditional classes, never template literals. No manual `z-index` on overlays.
+- `Badge` variants are exactly `default`, `secondary`, `destructive`, `outline`, `ghost` — no `success`.
+
+**Forms** → [forms.md](./rules/forms.md)
+
+- `FieldGroup` + `Field` for layout, never a raw `div`.
+- Errors go in `FieldError`, never `FieldDescription`. Validation is `data-invalid` on `Field` **and** `aria-invalid` on the control; disabled likewise.
+- `InputGroup` takes `InputGroupInput`/`InputGroupTextarea`; buttons inside it use `InputGroupButton` in an `InputGroupAddon`, and a trailing one needs `align="inline-end"`.
+- Option sets (2–7) use `ToggleGroup`; `FieldSet` + `FieldLegend` group related checkboxes/radios.
+
+**Composition** → [composition.md](./rules/composition.md)
+
+- Items live inside their Group — `SelectItem`→`SelectGroup`, `DropdownMenuItem`→`DropdownMenuGroup`, `CommandItem`→`CommandGroup`.
+- `asChild` (radix) or `render` (base) for custom triggers; check `config.base` → [base-vs-radix.md](./rules/base-vs-radix.md).
+- Dialog/Sheet/Drawer need a Title (`sr-only` if hidden); `TabsTrigger` belongs in `TabsList`; `Avatar` needs `AvatarFallback`.
+- Full Card composition, not everything in `CardContent`. `Button` has no `isPending`/`isLoading` — compose `Spinner` + `data-icon` + `disabled`.
+- Prefer the component over markup: `Alert`, `Empty`, `sonner`'s `toast()`, `Separator`, `Skeleton`, `Badge`.
+
+**Icons** → [icons.md](./rules/icons.md)
+
+- `data-icon="inline-start"`/`"inline-end"` on icons inside `Button`; pass icons as components (`icon={CheckIcon}`), not string keys.
+- No sizing classes on icons inside components — a `size-*` class *opts out* of the component's sizing rather than matching it.
+
+**CLI** → [cli.md](./cli.md)
+
+- Never decode or fetch a preset code by hand — `preset decode <code>` shows what it encodes. Swap icon libraries with `migrate icons --from <a> --to <b>`.
+- Never `--overwrite` without explicit approval → [smart merge](./cli.md#smart-merge-from-upstream). Never guess an unnamed registry, and read every file one adds → [third-party registries](./cli.md#working-with-third-party-registries).
+
+## Data Tables & List Pages
+
+**On a portal list/index page the data table is DiceUI's — the default, not a suggestion.** A bare `Table` there is the choice that needs justifying. Elsewhere: DiceUI once a table needs server-side filter/sort/paginate, plain `Table` when it's display.
+
+**List-page state belongs in the URL, via `nuqs`** — not `useState`, and never mirrored into both. `useDataTable` calls `useQueryState` internally, so `nuqs` is a hard dependency and the app must be wrapped once in `NuqsAdapter` or the hook throws.
+
+```bash
+npx shadcn@latest add "https://tablecn.com/r/data-table.json"   # .json required; extensionless 404s
+```
+
+Why URL state is the point, the install traps (undeclared `zod` / `@dnd-kit/*`), the server-side parsing pattern, and the column contract: [rules/data-table.md](./rules/data-table.md). Surrounding state & data-flow conventions: the project's `nextjs-fullstack` skill.
+
+## Starting a New Project
+
+Canonical config: **Base UI + nova + lucide** — `components.json` ends up with `style: "base-nova"`. Install the whole library up front so feature work never stalls on a missing component.
+
+```bash
+# Single app — same result as `init --defaults`, which resolves to next + base-nova.
+npx shadcn@latest init --template next --base base --preset nova
+# Turborepo workspace.
+npx shadcn@latest init --template next --base base --preset nova --monorepo
+npx shadcn@latest add --all
+```
+
+Two consequences to carry into everything you write afterwards:
+
+- **The base is `base`, so component APIs are Base UI's** — `render` not `asChild`, `multiple` not `type="single"`, a scalar `Slider`, and `Select` needs an `items` prop → [base-vs-radix.md](./rules/base-vs-radix.md). Registry items and most examples online are written for radix; expect to convert.
+- **In a monorepo the UI alias is `@workspace/ui/components`, not `@/components/ui`** — so third-party registry items land with imports that resolve to nothing. Rewrite them against `config.aliases`.
+
+`--all` is a setup step, not an update path — what that means when upstream moves: [cli.md](./cli.md#installing-everything-up-front).
+
+## Workflow
+
+1. Read the injected context; re-run `npx shadcn@latest info` to refresh.
+2. Check `components` (or list `resolvedPaths.ui`) before importing. On a project set up as above everything is already there, so this is usually a one-line confirmation — but don't assume it: older projects and ones initialised elsewhere may have been added to piecemeal, and importing a component that was never added fails at build, not at review.
+3. Find components — `npx shadcn@latest search`.
+4. Read the docs — `npx shadcn@latest docs <component>`, then fetch. `view` browses uninstalled items; `add --diff` previews changes to installed ones.
+5. Install or update — `npx shadcn@latest add`; [smart merge](./cli.md#smart-merge-from-upstream) anything with local edits.
+6. Ask which registry when the user didn't name one, then review every added file → [third-party registries](./cli.md#working-with-third-party-registries).
+7. Switching presets — ask first: **overwrite** / **merge** / **skip**, or `apply --only theme` to re-theme alone → [cli.md](./cli.md#switching-presets).