@owlmeans/agent-skills 0.1.8

package/README.md

@@ -0,0 +1,92 @@
+# @owlmeans/agent-skills
+
+CLI installer that lifts embedded Claude Code skills and GitHub Copilot instructions
+out of installed `@owlmeans/*` packages and places them into your project's native
+agent-guidance locations.
+
+## Usage
+
+After installing `@owlmeans/*` packages, run once:
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The installer scans `node_modules/@owlmeans/*/agent-meta/`, shows you what guidance
+is available, and (with your confirmation) copies it into:
+
+- **Claude Code**: `.claude/skills/<name>/SKILL.md`
+- **GitHub Copilot**: `.github/instructions/<name>.instructions.md`
+
+Re-run after updating `@owlmeans/*` packages to pick up revised guidance.
+
+## Flags
+
+```
+--dir <path>        target project directory (default: current working directory)
+--yes, -y           skip interactive confirmation (non-destructive; conflicts still skip)
+--only <pkg,...>    install guidance from these packages only (comma-separated @owlmeans/* names)
+--claude-only       install only Claude Code skills (.claude/skills/)
+--copilot-only      install only Copilot instructions (.github/instructions/)
+--extras            include extras bundled in the installer itself (default: on)
+--no-extras         skip extras bundled in the installer
+--force             overwrite locally-edited files (no AUTO-GENERATED banner)
+--dry-run           print plan without writing any files
+--help, -h          show this help
+```
+
+## Conflict policy
+
+Files managed by the installer carry an `AUTO-GENERATED` banner. On re-run:
+
+- **Managed files** (banner present) — always updated to the latest embedded version.
+- **Locally-edited files** (no banner) — **skipped** and reported as conflicts by default.
+  Pass `--force` to overwrite, or confirm individually in interactive mode.
+
+## Extras (shadcn)
+
+The installer ships `shadcn-web` and `shadcn-versions` as bundled extras — design
+system guidance that spans multiple packages and has no single lead package. These
+are installed by default alongside package-specific guidance from `node_modules`.
+
+## Linked monorepo
+
+If any `@owlmeans/*` packages are **symlinked** (e.g. via a `libraries/` workspace
+link in an OwlMeans monorepo), the installer refuses and exits with code 4. In that
+setup agents already load guidance from the linked monorepo's root `.claude/skills/`
+and `.github/instructions/` — running the installer would install stale copies.
+
+Pass `--force` only if you understand this and want to proceed anyway.
+
+## Schema
+
+Each `@owlmeans/*` package ships its embedded guidance under:
+
+```
+agent-meta/
+  manifest.json          # package, version, entries list
+  skills/<name>/
+    SKILL.md             # Claude Code skill
+  instructions/
+    <name>.instructions.md   # GitHub Copilot instruction
+```
+
+Embedded files are **generated and read-only**. To contribute guidance edits, open
+a PR against [owlmeans/common](https://github.com/owlmeans/common).
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/shadcn-versions.instructions.md

@@ -0,0 +1,46 @@
+---
+description: How to update Tailwind CSS, shadcn UI primitives, and related UI lib versions across shadcn-based OwlMeans packages. Distinct from the @owlmeans/* version sync (see versions.instructions.md).
+applyTo: "**/components.json"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# shadcn + Tailwind version management
+
+This covers **external UI dependency versions** across shadcn-based OwlMeans packages. It is separate from the `@owlmeans/*` version sync (see `versions.instructions.md`).
+
+## What to update
+
+- `tailwindcss`, `@tailwindcss/vite`, `@tailwindcss/postcss`
+- `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`
+- `@radix-ui/*` (added per component as primitives are copied in)
+- Shadcn primitive `.tsx` files in `src/@/components/ui/` (copied source, not npm)
+
+## Bumping npm versions
+
+```bash
+# Example: bump tailwindcss in a shadcn package (run per package)
+sed -i 's/"tailwindcss": "[^"]*"/"tailwindcss": "^4.1.0"/g' <shadcn-package>/package.json
+bun install
+bun run build
+```
+
+## Re-syncing copied primitives
+
+1. Find the new source for the component in shadcn GitHub.
+2. Diff against the local copy to preserve any project-local changes.
+3. Update the version comment: `// shadcn <name> — sourced from shadcn@<version> <date>`.
+4. Run `bun run build` and category-D UI tests.
+
+## Tailwind major upgrades
+
+Follow the official Tailwind upgrade guide. Check `@theme` token compatibility and `@source` syntax. Update `@tailwindcss/vite` to a matching major version.
+
+## Verification
+
+```bash
+bun run build
+# Run category-D UI tests for shadcn packages
+bun test --filter <shadcn-pkg-name> ./tests
+```
+
+See `.claude/skills/shadcn-versions/SKILL.md` for full procedure.

package/agent-meta/instructions/shadcn-web.instructions.md

@@ -0,0 +1,94 @@
+---
+description: How to build and maintain shadcn UI + Tailwind v4 web packages in OwlMeans Common. Load when editing components.json, tailwind.config.*, globals.css, or files under components/ui/.
+applyTo: "**/components.json, **/tailwind.config.{ts,js,mjs}, **/globals.css, **/components/ui/**, **/@/lib/utils.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# shadcn UI + Tailwind v4 — OwlMeans web packages
+
+Shadcn-based web packages are the next-generation Web layer replacing `web-panel` (MUI). They wrap the same headless `@owlmeans/client-panel` logic and mirror `web-panel`'s package shape — swapping MUI for shadcn UI + Tailwind v4.
+
+## The `@` contract — three invariants
+
+1. **No shadcn registries.** Primitives are **hand-copied** into `src/@/components/ui/`. Never use `registries` in `components.json`.
+2. **Same `@` import prefix as the final app.** Components import `@/components/ui/button`, `@/lib/utils`, etc. The build emits `@/…` verbatim (Bundler resolution). The app's bundler resolves `@` to its own shadcn copy. The package never ships its primitives as a public import.
+3. **Local copy is dev/test-only.** `src/@/` exists so the package can build and test in isolation. Never expose `./@/*` in `package.json` exports.
+
+## tsconfig — `@` alias setup
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["./src/@/*"] }
+  }
+}
+```
+
+`moduleResolution: Bundler` (from `dep-config/tsconfig.base.json`) emits `@/…` verbatim — TypeScript resolves types via `paths` but does not rewrite the specifier.
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": { "config": "", "css": "src/@/globals.css", "baseColor": "neutral", "cssVariables": true },
+  "iconLibrary": "lucide",
+  "aliases": { "components": "@/components", "ui": "@/components/ui", "utils": "@/lib/utils", "lib": "@/lib", "hooks": "@/hooks" }
+}
+```
+
+`tailwind.config: ""` is required for Tailwind v4.
+
+## Tailwind v4 — globals.css
+
+```css
+@import "tailwindcss";
+@source "../..";
+@theme {
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --color-destructive: oklch(0.577 0.245 27.325);
+  --color-border: oklch(0.922 0 0);
+  --radius: 0.625rem;
+  /* ... full token set in @owlmeans/shadcn-web reference.md ... */
+}
+```
+
+In production, the **app owns its own `globals.css`**. The package's CSS is only for dev/test.
+
+## Adding a primitive (no registry)
+
+1. Copy `.tsx` source from shadcn GitHub into `src/@/components/ui/<name>.tsx`.
+2. Repoint imports to `@/lib/utils` and `@/components/ui/…`.
+3. Add any `@radix-ui/*` packages as **peerDependencies**.
+4. Add comment: `// shadcn <name> — sourced from shadcn@<version> <date>`.
+
+## Wrapping `@owlmeans/client-panel`
+
+Replace MUI rendering in `web-panel` components with shadcn + Tailwind classes. The `FormProvider`, `useFormContext`, `Controller`, AJV resolver, and `useFormI18n` are unchanged — only JSX changes.
+
+```tsx
+// MUI: <TextField {...field} label={label} error={...} />
+// shadcn:
+<div className="flex flex-col gap-1.5">
+  <Label htmlFor={field.name}>{label}</Label>
+  <Input id={field.name} {...field} aria-invalid={fieldState.error != null} />
+  {fieldState.error && <p className="text-sm text-destructive">{fieldState.error.message}</p>}
+</div>
+```
+
+## package.json peerDependencies
+
+`class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, `react`, `react-dom`, `react-hook-form`, `tailwindcss`. Add `@radix-ui/*` per component copied.
+
+## package.json exports — never expose `@/*`
+
+```json
+{ "exports": { ".": { "import": "./build/index.js", "types": "./build/index.d.ts" } } }
+```
+
+See `.claude/skills/shadcn-web/SKILL.md` for the full pattern.

package/agent-meta/manifest.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/agent-skills",
+  "version": "0.1.8",
+  "generatedAt": "2026-06-11T16:30:27.174Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "shadcn-web",
+      "category": "multi-package",
+      "file": "skills/shadcn-web/SKILL.md",
+      "canonicalPath": ".claude/skills/shadcn-web/SKILL.md"
+    },
+    {
+      "kind": "skill",
+      "name": "shadcn-versions",
+      "category": "multi-package",
+      "file": "skills/shadcn-versions/SKILL.md",
+      "canonicalPath": ".claude/skills/shadcn-versions/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "shadcn-versions",
+      "category": "multi-package",
+      "file": "instructions/shadcn-versions.instructions.md",
+      "canonicalPath": ".github/instructions/shadcn-versions.instructions.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "shadcn-web",
+      "category": "multi-package",
+      "file": "instructions/shadcn-web.instructions.md",
+      "canonicalPath": ".github/instructions/shadcn-web.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/shadcn-versions/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: shadcn-versions
+description: How to update versions of shadcn UI primitives, Tailwind CSS v4, and related UI libs across all shadcn-based OwlMeans web packages. Distinct from the @owlmeans/* package version sync (see [[versions]] skill). Use when bumping tailwind, shadcn components, or utility libs.
+allowed-tools: Bash(grep *), Bash(sed *), Bash(bun install)
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# shadcn + Tailwind version management — OwlMeans Common
+
+This skill handles **external UI dependency versions** for the shadcn-based web packages. It is **distinct** from the `[[versions]]` skill, which manages the synchronized `@owlmeans/*` package version (`0.1.x` etc.).
+
+## What this covers
+
+| Package | Location | Notes |
+|---|---|---|
+| `tailwindcss` | peerDependency + devDependency | core engine |
+| `@tailwindcss/vite` | devDependency | Vite plugin for dev/test harness |
+| `@tailwindcss/postcss` | devDependency | PostCSS fallback (if used) |
+| `class-variance-authority` | peerDependency | `cva()` for component variants |
+| `clsx` | peerDependency | conditional class names |
+| `tailwind-merge` | peerDependency | merge Tailwind classes without conflicts |
+| `lucide-react` | peerDependency | icon library |
+| `@radix-ui/*` | peerDependency | per-component Radix UI primitives |
+| shadcn primitives (copied) | source in `src/@/components/ui/` | hand-copied `.tsx` files — not npm |
+
+Shadcn primitive `.tsx` files inside each package are **not** npm dependencies — they are copied source files. Updating them is a separate step (see below).
+
+## Checking current versions
+
+To see what versions installed `@owlmeans/*` shadcn packages declare:
+
+```bash
+# Which tailwind version do installed OwlMeans shadcn packages use?
+grep -r '"tailwindcss"' node_modules/@owlmeans/*/package.json
+
+# Which tailwind-merge / clsx version?
+grep -r '"tailwind-merge"\|"clsx"\|"class-variance-authority"' node_modules/@owlmeans/*/package.json
+
+# Which @radix-ui/* versions?
+grep -r '"@radix-ui/' node_modules/@owlmeans/*/package.json
+```
+
+## Bumping external UI lib versions
+
+Shadcn packages use caret ranges in peerDependencies (e.g. `"tailwindcss": "*"` or `"tailwindcss": "^4.x"`). To pin to a specific version across all shadcn packages in the `@owlmeans/common` source repo, run these in the monorepo root (OwlMeans framework contributors):
+
+```bash
+# Example: pin tailwindcss to ^4.1.0 across all shadcn packages
+OLD_TW='\*'   # or whatever the current range is
+NEW_TW='^4.1.0'
+
+# Update each shadcn package's package.json (run per package)
+sed -i "s/\"tailwindcss\": \"$OLD_TW\"/\"tailwindcss\": \"$NEW_TW\"/g" <shadcn-package>/package.json
+
+# Same pattern for other UI libs
+sed -i 's/"tailwind-merge": "\*"/"tailwind-merge": "^2.5.0"/g' <shadcn-package>/package.json
+sed -i 's/"clsx": "\*"/"clsx": "^2.1.0"/g' <shadcn-package>/package.json
+
+bun install
+```
+
+Always run `bun run build` and the category-D UI tests after bumping to catch breaking changes.
+
+## Bumping the Vite plugin / PostCSS plugin
+
+These are devDependencies only (used in the test harness, not production). Update them separately:
+
+```bash
+sed -i 's/"@tailwindcss\/vite": "\*"/"@tailwindcss\/vite": "^4.1.0"/g' <shadcn-package>/package.json
+bun install
+```
+
+## Tailwind major version upgrades (v4 → v5, etc.)
+
+1. Read the [Tailwind upgrade guide](https://tailwindcss.com/docs/upgrade-guide) for breaking changes.
+2. Check `@theme` token compatibility — token names may change between major versions.
+3. Check `@source` directive syntax changes.
+4. Update `@tailwindcss/vite` and `@tailwindcss/postcss` to matching major versions.
+5. Rebuild (`bun run build`) and run all category-D UI tests.
+6. Update this skill and `[[shadcn-web]]` with the new conventions.
+
+## Re-syncing copied shadcn primitives
+
+When shadcn upstream releases a new version, manually update the hand-copied primitives:
+
+1. **Find the changed component source** — check the shadcn GitHub diff or changelog.
+2. **Get the new source** — copy from `https://ui.shadcn.com/r/<name>.json` (the raw file URL) or from the [shadcn GitHub](https://github.com/shadcn-ui/ui) (`registry/new-york/ui/<name>.tsx`).
+3. **Diff against the local copy** to identify any project-local modifications (custom classes, extra props, i18n tweaks) that must be preserved.
+4. **Apply changes**, preserving local modifications.
+5. **Update the version comment** at the top of the file: `// shadcn <name> — sourced from shadcn@<version> <date>`.
+6. **Check `components.json` schema** — if the shadcn schema version changed, update `"$schema"` URLs.
+7. Run `bun run build` and UI tests.
+
+## Keeping `@radix-ui/*` versions consistent
+
+Radix UI packages are added as peerDependencies when primitives are copied in. Keep them consistent across packages:
+
+```bash
+# Check radix versions in installed OwlMeans shadcn packages
+grep -r '"@radix-ui/' node_modules/@owlmeans/*/package.json | grep -v node_modules
+
+# Bump a specific radix package (run per shadcn package in the source repo)
+sed -i 's/"@radix-ui\/react-slot": "[^"]*"/"@radix-ui\/react-slot": "^1.1.0"/g' <shadcn-package>/package.json
+bun install
+```
+
+## Verification
+
+After any version change:
+
+```bash
+# Build all packages
+bun run build
+
+# Run category-D UI tests for shadcn packages
+bun test --filter <shadcn-pkg-name> ./tests
+```
+
+If category-D tests don't exist yet, at minimum load the harness URL manually to confirm components render without JS errors.
+
+## Cross-references
+
+- `[[versions]]` — synchronized `@owlmeans/*` package version (separate concern)
+- `[[shadcn-web]]` — how to build/maintain shadcn-based OwlMeans packages
+- `[[testing-ui]]` — category-D Playwright tests that verify UI after version bumps
+- `[[bun]]` — bun install, workspace filter, build commands

package/agent-meta/skills/shadcn-web/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: shadcn-web
+description: How to build and maintain shadcn UI + Tailwind v4 web packages in the OwlMeans framework. Auto-invoked when editing components.json, tailwind.config.*, globals.css, or files under components/ui/. Use when creating a new shadcn-based web package or adding shadcn components.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# shadcn UI + Tailwind v4 web packages — OwlMeans pattern
+
+Shadcn-based web packages are the **next-generation Web layer**, replacing MUI `web-panel` over time. They sit at the same architecture layer (Web), wrap the same headless `@owlmeans/client-panel` logic, and follow the same `web-panel` package shape — swapping MUI + Emotion for shadcn UI + Tailwind CSS v4.
+
+See `reference.md` in this skill folder for full code examples (components.json, tsconfig, globals.css @theme tokens, peerDeps, cn(), MUI→shadcn mapping table).
+
+## The `@` contract — core rule
+
+Three invariants govern every shadcn-based OwlMeans package:
+
+1. **No shadcn registries.** Primitives (Button, Input, Card, …) are **hand-copied** into `src/@/components/ui/` and committed. The `registries` field in `components.json` is always empty/absent.
+
+2. **Same `@` import prefix as the final app.** Components inside the package import shadcn primitives as `@/components/ui/button`, `@/lib/utils`, etc. The build leaves `@/…` specifiers **verbatim** (TypeScript Bundler resolution never rewrites them). The downstream app's bundler resolves `@` to **its own** shadcn copy + theme. The package never ships its primitives as a public import.
+
+3. **Local copy is dev/test-only.** Each package keeps its own copy under `src/@/` so it can build and test in isolation. The `package.json` `exports` map must **not** expose `./@/*` — consumers never accidentally import the package's copy.
+
+## Package skeleton (mirrors `web-panel`)
+
+```
+<your-package>/
+├── src/
+│   ├── @/                              # dev/test-only primitives — NOT a public export
+│   │   ├── components/ui/              # hand-copied shadcn primitives
+│   │   │   ├── button.tsx
+│   │   │   └── input.tsx
+│   │   ├── lib/
+│   │   │   └── utils.ts               # cn() utility
+│   │   └── globals.css                # Tailwind v4 entry (app provides its own in prod)
+│   ├── components/                    # OwlMeans framework components (wrap client-panel)
+│   │   ├── form/
+│   │   │   ├── component.tsx
+│   │   │   ├── text/component.tsx
+│   │   │   ├── button/component.tsx
+│   │   │   ├── types.ts
+│   │   │   └── index.ts
+│   │   ├── layout/component.tsx
+│   │   ├── panel-app/component.tsx
+│   │   └── index.ts                   # barrel; re-exports @owlmeans/client-panel
+│   ├── context.ts                     # makeContext wrapping web-client's makeContext
+│   ├── main.tsx                       # render() — no theme arg (theme is pure CSS)
+│   ├── types.ts
+│   ├── modules.ts
+│   └── index.ts
+├── tests/
+│   ├── harness/
+│   │   ├── index.html                 # copy from @owlmeans/test-ui harness/index.html
+│   │   └── mount.tsx                  # per-package: imports globals.css, registers components
+│   ├── context.ts                     # boots Vite with @tailwindcss/vite + @ alias
+│   └── *.spec.ts
+├── components.json
+├── package.json
+└── tsconfig.json
+```
+
+## tsconfig setup
+
+```json
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.react.json"
+  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@/*": ["./src/@/*"] },
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}
+```
+
+`moduleResolution: Bundler` (from `tsconfig.base.json`) causes `tsc` to emit `@/…` verbatim. `paths` is used only for **type-checking** during build — it finds types for `@/components/ui/button` in `src/@/components/ui/button.tsx` without rewriting the emitted specifier.
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/@/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "utils": "@/lib/utils",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
+```
+
+`tailwind.config: ""` is required for Tailwind v4 (no separate config file). Do not add a `registries` field.
+
+## Tailwind v4 wiring
+
+`src/@/globals.css` — the Tailwind entry used in dev/test only:
+
+```css
+@import "tailwindcss";
+
+@source "../..";
+
+@theme {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --color-destructive: oklch(0.577 0.245 27.325);
+  --color-border: oklch(0.922 0 0);
+  --color-input: oklch(0.922 0 0);
+  --color-ring: oklch(0.708 0 0);
+  --radius: 0.625rem;
+}
+```
+
+`@source "../.."` scans the package root. In the Vite dev/test harness, `@tailwindcss/vite` processes this CSS. The **production app owns its own `globals.css`** with its own `@theme` tokens — the package's CSS is only for tests.
+
+## Adding a primitive without a registry
+
+1. Find the component source on the [shadcn GitHub](https://github.com/shadcn-ui/ui) (e.g. `registry/new-york/ui/<name>.tsx`) or via `npx shadcn@latest add <name> --cwd <your-package-dir>` in a throwaway branch.
+2. Copy the `.tsx` source into `src/@/components/ui/<name>.tsx`.
+3. Repoint all imports to `@/lib/utils` and `@/components/ui/…` for sub-primitives.
+4. Add any `@radix-ui/*` packages the file imports as **peerDependencies** in `package.json`.
+5. Add a comment at the top: `// shadcn <name> — sourced from shadcn@<version> <date>`.
+6. Run `bun install` and `bun run build` to verify.
+
+## Wrapping `@owlmeans/client-panel`
+
+Shadcn form/field components are the rendering layer over the framework-agnostic headless logic from `@owlmeans/client-panel`. Mirror the MUI pattern from `@owlmeans/web-panel` (form text component):
+
+```tsx
+// MUI version (web-panel) — for reference
+import { TextField } from '@mui/material'
+// ...
+<TextField {...field} label={label} error={fieldState.error != null} />
+
+// shadcn version
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+// ...
+<div className="flex flex-col gap-1.5">
+  <Label htmlFor={field.name}>{label}</Label>
+  <Input id={field.name} {...field} aria-invalid={fieldState.error != null} />
+  {fieldState.error && (
+    <p className="text-sm text-destructive">{fieldState.error.message}</p>
+  )}
+</div>
+```
+
+`FormProvider`, `useFormContext`, `Controller`, the AJV validation resolver, and `useFormI18n` from `@owlmeans/client-i18n` are unchanged — only the rendered JSX changes.
+
+`panel-app/component.tsx` no longer needs MUI `ThemeProvider` or `CssBaseline`. It simply renders children. Theme is provided via the app's `globals.css` Tailwind entry.
+
+## package.json exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "types": "./build/index.d.ts"
+    },
+    "./auth": {
+      "import": "./build/auth/index.js",
+      "types": "./build/auth/index.d.ts"
+    }
+  }
+}
+```
+
+Do **not** add `./@/*` or `./src/@/*` to exports.
+
+## Dev/test harness (Vite + @tailwindcss/vite)
+
+See `[[testing-ui]]` for the full Playwright harness pattern. For shadcn packages the `tests/context.ts` Vite config adds the Tailwind plugin and the `@` alias:
+
+```ts
+import tailwindcss from '@tailwindcss/vite'
+import { resolve } from 'node:path'
+
+const server = await createServer({
+  configFile: false,
+  root: resolve(here, './harness'),
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: { '@': resolve(here, '../src/@') },
+  },
+  server: { port: 0 },
+})
+```
+
+`tests/harness/mount.tsx` imports the package globals.css so components render with Tailwind styles:
+
+```tsx
+import '../../src/@/globals.css'
+// ... dynamic component mounting ...
+```
+
+## Cross-references
+
+- `[[client-panel]]` — headless form/layout logic being wrapped
+- `[[web-panel]]` — MUI counterpart; the structural and API reference
+- `[[testing-ui]]` — Playwright harness for component acceptance tests
+- `[[shadcn-versions]]` — bumping tailwind/shadcn external deps across packages
+- `[[tsconfig]]` — OwlMeans TypeScript config conventions
+- `[[bun]]` — build, install, workspace filter scripts

package/build/apply.d.ts

@@ -0,0 +1,13 @@
+import type { InstallItem } from './plan.js';
+export interface ApplyResult {
+    installed: number;
+    updated: number;
+    skipped: number;
+    conflicts: number;
+}
+/**
+ * Execute an install plan. Items with action 'conflict' or 'skip-uptodate'
+ * are not written. Only 'install' and 'update' items are written.
+ */
+export declare const applyInstall: (items: InstallItem[]) => ApplyResult;
+//# sourceMappingURL=apply.d.ts.map

package/build/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,WAAW,EAAE,KAAG,WAsBnD,CAAA"}

package/build/apply.js

@@ -0,0 +1,28 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Execute an install plan. Items with action 'conflict' or 'skip-uptodate'
+ * are not written. Only 'install' and 'update' items are written.
+ */
+export const applyInstall = (items) => {
+    const result = { installed: 0, updated: 0, skipped: 0, conflicts: 0 };
+    for (const item of items) {
+        if (item.action === 'skip-uptodate') {
+            result.skipped++;
+            continue;
+        }
+        if (item.action === 'conflict') {
+            result.conflicts++;
+            continue;
+        }
+        const content = readFileSync(item.entry.sourcePath, 'utf8');
+        mkdirSync(dirname(item.targetPath), { recursive: true });
+        writeFileSync(item.targetPath, content, 'utf8');
+        if (item.action === 'install')
+            result.installed++;
+        else
+            result.updated++;
+    }
+    return result;
+};
+//# sourceMappingURL=apply.js.map

package/build/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAUnC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAoB,EAAe,EAAE;IAChE,MAAM,MAAM,GAAgB,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;IAElF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM,KAAK,eAAe,EAAE,CAAC;YACpC,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,CAAC,SAAS,EAAE,CAAA;YAClB,SAAQ;QACV,CAAC;QAED,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;QAC3D,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACxD,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;QAE/C,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,SAAS,EAAE,CAAA;;YAC5C,MAAM,CAAC,OAAO,EAAE,CAAA;IACvB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}