@pikku/skills 0.12.52 → 0.12.55

package/skills/pikku-software-archaeology/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pikku-software-archaeology
-description: 'Use when reverse-engineering an existing repository into a Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner who holds the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language — JS, TS, Ruby, Python, PHP, Go) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator audience. DO NOT TRIGGER for: documenting code structure, generating API docs from an already-clean codebase, or an engineer-facing code review.'
+description: 'Use when reverse-engineering an existing repository into a `.knowledge/` Product Blueprint — recovering what product an undocumented or organically-grown codebase implements so it can be rebuilt cleanly (e.g. as a Pikku app) — and when turning that blueprint into a plain-language second opinion for the non-technical owner of the app. TRIGGER when: user says "extract a blueprint", "reverse engineer this app", "what does this codebase actually do as a product", "prepare this repo for a rewrite/migration", points at a legacy repo (any language) and asks for its domains, workflows, business rules or a rebuild plan, or asks "explain how my app works" / "what would you do differently" / "is this built well?" for a founder, PM or operator. Not the `knowledge/` notes of pikku-knowledge. DO NOT TRIGGER for: documenting code structure, API docs for a clean codebase, an engineer-facing code review, or rebuilding from an existing blueprint.'
 installGroups: [core]
 ---
 
@@ -25,7 +25,7 @@ Everything goes in `<repo>/.knowledge/` (or a caller-specified directory):
 
 ```
 .knowledge/
-├── product.json        # purpose, actors, capabilities, terminology
+├── product.json        # purpose, virtualUsers, capabilities, terminology
 ├── domains.json        # business domains (NEVER folder names)
 ├── entities.json       # domain entities: attributes, relationships, states, transitions
 ├── commands.json       # state-changing actions (SendInvoice, not POST /invoices/:id/send)
@@ -45,9 +45,9 @@ Everything goes in `<repo>/.knowledge/` (or a caller-specified directory):
 │   # frontend and/or non-HTTP consumer channels. A backend-only repo omits them
 │   # and the validator does not complain.
 ├── interfaces.json         # every way the product is consumed: web-ui, cli, mcp, openapi-rest, sdk, realtime, webhooks
-├── frontend.json           # web-UI app shape: framework, router, styling, data layer, auth (e.g. TanStack Start + better-auth + Mantine)
+├── frontend.json           # web-UI app shape: framework, router, styling, data layer, auth (e.g. TanStack Start + better-auth + Tailwind)
 ├── frontend-routes.json    # the page/route tree — what a user navigates to, its data + components
-└── frontend-components.json# component inventory; `rebuild` splits trivial-Mantine from custom-logic-to-port
+└── frontend-components.json# component inventory; `rebuild` splits trivial-library from custom-logic-to-port
 ```
 
 The exact field shapes live in `references/blueprint.schema.json` (in this skill's directory — read it before writing any output file). After writing, ALWAYS run:
@@ -77,21 +77,21 @@ Build an inventory before interpreting anything:
 
 Where intent hides, per ecosystem (read these first):
 
-| Ecosystem                 | Highest-yield locations                                                                                                                                                                                                                                                                                                      |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Rails                     | `config/routes.rb`, model validations + callbacks + `aasm`/state machines, `app/policies` (Pundit) / `ability.rb` (CanCan), Sidekiq/ActiveJob workers, `db/schema.rb`, specs (esp. request + model specs)                                                                                                                    |
-| Express/Node              | route registration files, middleware chains (auth!), inline `if` guards in handlers, SQL/ORM models, `jobs/`+crontab refs, webhook handlers                                                                                                                                                                                  |
-| Django                    | `urls.py`, model `Meta`/constraints/`clean()`, DRF serializers + permissions classes, celery tasks, admin.py (reveals internal workflows)                                                                                                                                                                                    |
-| Laravel                   | `routes/`, FormRequests (validation), Policies/Gates, Jobs + scheduler in `Kernel.php`, migrations                                                                                                                                                                                                                           |
-| Go                        | mux/router setup, middleware, struct tags, `cmd/` binaries (each is a component)                                                                                                                                                                                                                                             |
-| Frontend (React/Vue/etc.) | router config / file-based routes (pages a user reaches), the component tree, the design-system import (`@mantine/*`, `@mui/*`, Tailwind config) to judge consistency, the data layer (react-query/tRPC/fetch wrappers) to tie UI back to backend queries, charts/tables/editors (the `custom-logic` port risk), auth wiring |
+| Ecosystem                 | Highest-yield locations                                                                                                                                                                                                                                                                                                                  |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Rails                     | `config/routes.rb`, model validations + callbacks + `aasm`/state machines, `app/policies` (Pundit) / `ability.rb` (CanCan), Sidekiq/ActiveJob workers, `db/schema.rb`, specs (esp. request + model specs)                                                                                                                                |
+| Express/Node              | route registration files, middleware chains (auth!), inline `if` guards in handlers, SQL/ORM models, `jobs/`+crontab refs, webhook handlers                                                                                                                                                                                              |
+| Django                    | `urls.py`, model `Meta`/constraints/`clean()`, DRF serializers + permissions classes, celery tasks, admin.py (reveals internal workflows)                                                                                                                                                                                                |
+| Laravel                   | `routes/`, FormRequests (validation), Policies/Gates, Jobs + scheduler in `Kernel.php`, migrations                                                                                                                                                                                                                                       |
+| Go                        | mux/router setup, middleware, struct tags, `cmd/` binaries (each is a component)                                                                                                                                                                                                                                                         |
+| Frontend (React/Vue/etc.) | router config / file-based routes (pages a user reaches), the component tree, the design-system import (`@mui/*`, Tailwind config, shadcn `components.json`) to judge consistency, the data layer (react-query/tRPC/fetch wrappers) to tie UI back to backend queries, charts/tables/editors (the `custom-logic` port risk), auth wiring |
 
 ### Phase 2 — Test excavation (do not skip)
 
 Tests are the closest thing to an executable product spec. For every test file:
 
 - `describe`/`context`/`it` names → **scenarios** (attach to the matching workflow in `workflows.json` under `scenarios[]`, with `fromTest` set).
-- User-flow/journey harnesses (`pikkuUserFlow` stories, cucumber `.feature` files, Playwright journeys) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim.
+- User-flow/journey harnesses (`pikkuUserFlow` stories, `.feature` files, Playwright journeys) are the highest-grade scenario source — they already ARE given/when/outcome sequences; extract them verbatim.
 - Assertions → confirmations of policies and invariants (upgrade their `confidence` to `high`, add the test as evidence).
 - Fixtures/factories → entity attribute shapes and realistic example data.
 - Edge-case tests → business rules that exist **nowhere else in the code** (e.g. "replayed webhook events are idempotent" may only be stated in a test).
@@ -105,9 +105,9 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 
 **Domains** — infer from data ownership, workflows, and vocabulary; NEVER from folder names. `controllers/` is not a domain; "Billing" is. A domain owns entities and the commands that mutate them.
 
-**Entities** — domain concepts, not tables. Include: attributes (from schema + serializers + fixtures), relationships, **lifecycle states and transitions** (grep status/state columns, then find every write to them — each write site is a transition with a trigger), ownership (which actor's rows), constraints.
+**Entities** — domain concepts, not tables. Include: attributes (from schema + serializers + fixtures), relationships, **lifecycle states and transitions** (grep status/state columns, then find every write to them — each write site is a transition with a trigger), ownership (which virtual user's rows), constraints.
 
-**Commands** — every way state changes: routes, jobs, webhooks, CLI, admin consoles, DB triggers. Name them imperative `VerbNoun` in domain language: `POST /api/users/:id/status` → `ActivateUser`. For each: actor, preconditions (every `if (...) return 4xx` guard is a precondition or policy), effects, events produced. Convention: authentication/token issuance is a command (`LogInUser`, effect: "issues a session/JWT") even though it writes no rows — it changes the caller's security state.
+**Commands** — every way state changes: routes, jobs, webhooks, CLI, admin consoles, DB triggers. Name them imperative `VerbNoun` in domain language: `POST /api/users/:id/status` → `ActivateUser`. For each: virtual user, preconditions (every `if (...) return 4xx` guard is a precondition or policy), effects, events produced. Convention: authentication/token issuance is a command (`LogInUser`, effect: "issues a session/JWT") even though it writes no rows — it changes the caller's security state.
 
 **Queries** — reads and views, `GetX`/`ListX`/`SearchX`. Record the tenancy scoping each applies (a missing `WHERE user_id=` that exists elsewhere is a gaps.json security entry).
 
@@ -131,18 +131,18 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 
 **Interfaces** (`interfaces.json`, optional) — every way the product is CONSUMED, one entry per channel, not per route. A product is usually driven through several: a **web UI** (humans), a **CLI** (developers/operators), an **MCP server** (AI agents — in a Pikku app each MCP tool IS a `pikkuFunc`), an **OpenAPI/REST** surface (developers/external systems, often _generated_ from the routes), a **generated SDK**, **realtime** (websocket/SSE), and **webhooks** (in/out). For each: `kind`, `audience`, `purpose`, roughly how many ops it exposes, whether it's `generated` vs hand-written, which domains it serves, and `status` (complete/partial/stub — an MCP server with two tools is `stub`). This layer answers "who can drive this, and how" — it is the map the second-opinion skill needs to explain that the app is usable by people, developers, and agents.
 
-**Frontend** (`frontend.json` + `frontend-routes.json` + `frontend-components.json`, optional) — the web UI, which needs its own treatment because frontends vary wildly (framework, router, styling, state, data, auth) and the rebuild target is opinionated: **everything in one component system (Mantine), one data layer, one auth**.
+**Frontend** (`frontend.json` + `frontend-routes.json` + `frontend-components.json`, optional) — the web UI, which needs its own treatment because frontends vary wildly (framework, router, styling, state, data, auth) and the rebuild target is opinionated: **everything in one component system (shadcn), one data layer, one auth**.
 
 - `frontend.json` records the stack as FACTS: framework (e.g. TanStack Start), rendering (SSR/streaming/SPA), router, styling/design system, `designSystemConsistency`, state management, data layer (e.g. pikku-react vs REST helpers), auth (e.g. better-auth), i18n. Name the real technologies — the second-opinion skill weighs their tradeoffs, so record them precisely (do NOT editorialize here; this file is facts).
 - `frontend-routes.json` is the page tree: each route's `purpose` in product terms, `auth`, the `dataFrom` (query/command names it reads — reuse the backend concept names so the UI ties back to the domain), the `usesComponents`, and the `userFlows` it belongs to.
 - `frontend.json.designFindings` captures **broken/inconsistent design patterns** as concrete, cited observations (not taste). Actively hunt for: _interaction inconsistency_ (the same job done as a modal in one place and a drawer in another; inconsistent confirm dialogs); _theming not tokenized_ (hardcoded hex colors, magic spacing/font sizes, inline styles instead of theme tokens/variables — grep for `#[0-9a-f]{3,6}`, `style={{`, raw `px` values); _cross-page inconsistency_ (the same element — button, page header, card — styled differently across routes); _component duplication_ (three near-identical cards/tables for one purpose); _design-system bypass_ (raw HTML/CSS where a library component exists). Each finding gets an example, its impact (feels unpolished / a color change means hunting every file), and a fix (standardize on one pattern / move to tokens / extract one shared component). These are almost always cheap cleanups, and they are exactly what a non-technical owner perceives as "the app looks off" without being able to say why.
-- `frontend-components.json` is where the frontend's real migration cost lives, in the **`rebuild`** field: `mantine-standard` (maps 1:1 to a Mantine component — trivial), `mantine-composition` (built from Mantine primitives — straightforward), `custom-style` (diverges only visually — normalize to Mantine), or **`custom-logic`** (bespoke behavior — a custom chart, a virtualized/complex table, a canvas, drag-and-drop, a rich editor — that must be **ported**, not re-skinned). A `custom-logic` component MUST fill `customLogic` explaining the behavior, and should list the `dependencies` (charting/table/editor libs) that make it a real port. This split — "trivially re-Mantine-able" vs "carries logic that must survive the port" — is the single most useful thing the frontend extraction produces.
+- `frontend-components.json` is where the frontend's real migration cost lives, in the **`rebuild`** field: `library-standard` (maps 1:1 to a shadcn component — trivial), `library-composition` (built from shadcn primitives — straightforward), `custom-style` (diverges only visually — normalize to shadcn), or **`custom-logic`** (bespoke behavior — a custom chart, a virtualized/complex table, a canvas, drag-and-drop, a rich editor — that must be **ported**, not re-skinned). A `custom-logic` component MUST fill `customLogic` explaining the behavior, and should list the `dependencies` (charting/table/editor libs) that make it a real port. This split — "trivially re-shadcn-able" vs "carries logic that must survive the port" — is the single most useful thing the frontend extraction produces.
 - **Server-rendered / non-React frontends still get all three files — do NOT skip them.** The `rebuild` enum is named for the target stack, but the distinction it draws is target-agnostic: _trivial stock element_ vs _composed from primitives_ vs _visual divergence only_ vs **bespoke behavior that must be ported**. A Rails app (Slim/ERB + ViewComponents + Hotwire/Stimulus), a Django app (templates + HTMX), or a Laravel app (Blade + Livewire) all have that same split, and it is just as load-bearing there. Use the enum values verbatim (the validator enforces them), classify by what the thing actually _does_, and record the vocabulary mismatch in `frontend.json.notes`. Concretely: treat a template partial + its behavior controller (Stimulus/Alpine/Livewire) as ONE component and classify the pair; a server-rendered app's `custom-logic` is the same list as a SPA's (maps, charts, video players, payment elements, drag-to-reorder, rich text, QR, live-updating regions), plus anything whose behavior rides on a streaming/partial-update contract (Turbo Streams, HTMX swaps) — get that mapping wrong on rebuild and pages show stale data. Omitting these files because "it isn't a React app" hides the frontend's entire migration cost, which is the one thing this file exists to expose.
 - The `designFindings` grep hints above are React-flavored; the server-rendered equivalents are inline `style=` attributes in templates, hardcoded hex in the stylesheet tree, per-locale forked templates instead of i18n, and design-system bypass = raw markup where a component/partial already exists. Same findings, different needles.
 
 ### Phase 4 — Cross-check, validate, synthesize
 
-1. Cross-checks before writing: every command has an actor and at least one precondition or policy (or you explain why it is genuinely unguarded); every state transition appears in some command/workflow — if a state is only reachable by manual/DB intervention, record the transition with trigger `"none (manual/DB-only)"` AND add a gaps.json entry; every event has a producer; every api surface maps to a defined concept; every integration is used by some command/workflow.
+1. Cross-checks before writing: every command has a virtual user and at least one precondition or policy (or you explain why it is genuinely unguarded); every state transition appears in some command/workflow — if a state is only reachable by manual/DB intervention, record the transition with trigger `"none (manual/DB-only)"` AND add a gaps.json entry; every event has a producer; every api surface maps to a defined concept; every integration is used by some command/workflow.
 2. Write all 14 JSON files, sorting **unordered identity collections** by `name` (or `path`) — on first extraction too, not just re-runs. Arrays whose order carries meaning (`workflows[].steps`, and any other observed sequence) stay in their observed order: sorting them would rewrite the behavior you extracted. Run the validator: done means `0 error(s)` and exit 0, and every WARN explicitly reviewed and either fixed or justified in your summary.
 3. Write `blueprint.md`: product summary → domain map → per-domain narrative (entities/commands/events with the interesting rules) → workflows → integrations/architecture → invariants → gaps and open decisions → rebuild recommendation. Write it for the engineer who will rebuild the product and has never seen the legacy code.
 
@@ -177,17 +177,11 @@ Run each lens over the surveyed material. Rules that counter the classic failure
 | "A component list is enough"                    | Without the `rebuild` split, you've hidden the frontend's real cost. Flag every `custom-logic` component (chart/table/canvas/editor) and say what the logic is — that's the port work. |
 | "I'll skip the validator, the JSON looks right" | Run it. Missing domains refs, dangling event names, and undescribed custom-logic components are exactly what it catches.                                                               |
 
-## Quick Reference
+## Reference files
 
-```bash
-# 1. survey + excavate + extract (you, with Read/Grep/subagents)
-# 2. write <repo>/.knowledge/*.json + blueprint.md per references/blueprint.schema.json
-# 3. validate:
-node <skill-dir>/scripts/validate.mjs <repo>/.knowledge
-```
-
-- Schema/contract: `references/blueprint.schema.json`
+- Schema and contract for every output file: `references/blueprint.schema.json` (large JSON; open it with a search for the file you are writing rather than reading it whole)
 - How Pikku consumes the blueprint: `references/pikku-mapping.md`
+- Validator: `node <skill-dir>/scripts/validate.mjs <repo>/.knowledge`
 
 ## The second phase — a report the owner can act on
 

package/skills/pikku-software-archaeology/references/blueprint.schema.json

@@ -36,7 +36,7 @@
       "required": [
         "name",
         "purpose",
-        "actors",
+        "virtualUsers",
         "capabilities",
         "terminology",
         "evidence",
@@ -49,7 +49,7 @@
           "description": "1-3 sentences: what problem, for whom"
         },
         "targetUsers": { "type": "array", "items": { "type": "string" } },
-        "actors": {
+        "virtualUsers": {
           "type": "array",
           "minItems": 1,
           "items": {
@@ -212,7 +212,7 @@
               },
               "ownership": {
                 "type": "string",
-                "description": "which actor/tenant owns rows of this entity"
+                "description": "which virtual user/tenant owns rows of this entity"
               },
               "constraints": { "type": "array", "items": { "type": "string" } },
               "evidence": { "$ref": "#/$defs/evidence" },
@@ -233,7 +233,7 @@
             "required": [
               "name",
               "domain",
-              "actor",
+              "virtualUser",
               "input",
               "preconditions",
               "effects",
@@ -247,7 +247,7 @@
                 "description": "imperative VerbNoun: ApproveInvoice"
               },
               "domain": { "$ref": "#/$defs/conceptName" },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "trigger": {
                 "type": "string",
                 "description": "how it is invoked today (route, job, webhook, cron)"
@@ -305,7 +305,7 @@
             "required": [
               "name",
               "domain",
-              "actor",
+              "virtualUser",
               "description",
               "returns",
               "evidence",
@@ -317,7 +317,7 @@
                 "description": "GetX / ListX / SearchX"
               },
               "domain": { "$ref": "#/$defs/conceptName" },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "description": { "type": "string" },
               "input": {
                 "type": "array",
@@ -448,7 +448,7 @@
             "required": [
               "name",
               "kind",
-              "actor",
+              "virtualUser",
               "trigger",
               "steps",
               "result",
@@ -458,7 +458,7 @@
             "properties": {
               "name": { "type": "string" },
               "kind": { "type": "string", "enum": ["user", "admin", "system"] },
-              "actor": { "type": "string" },
+              "virtualUser": { "type": "string" },
               "trigger": { "type": "string" },
               "steps": {
                 "type": "array",
@@ -879,7 +879,7 @@
     "frontend.json": {
       "x-optional": true,
       "type": "object",
-      "description": "Web-UI app-level shape. Names the framework/router/styling/data/auth so the rebuild can weigh their tradeoffs (e.g. TanStack Start + better-auth + Mantine).",
+      "description": "Web-UI app-level shape. Names the framework/router/styling/data/auth so the rebuild can weigh their tradeoffs (e.g. TanStack Start + better-auth + Tailwind).",
       "required": [
         "framework",
         "styling",
@@ -903,12 +903,12 @@
         },
         "styling": {
           "type": "string",
-          "description": "the design system, e.g. Mantine, Tailwind, MUI, CSS modules"
+          "description": "the design system, e.g. shadcn, Tailwind, MUI, CSS modules"
         },
         "designSystemConsistency": {
           "type": "string",
           "enum": ["single-system", "mostly-consistent", "mixed", "ad-hoc"],
-          "description": "how uniformly ONE component/theme system is used — the rebuild target is 'everything Mantine', so divergence is porting work"
+          "description": "how uniformly ONE component/theme system is used — the rebuild target is 'everything shadcn', so divergence is porting work"
         },
         "designFindings": {
           "type": "array",
@@ -1036,7 +1036,7 @@
     "frontend-components.json": {
       "x-optional": true,
       "type": "object",
-      "description": "Component inventory. The load-bearing field is `rebuild`: it separates components that are trivially rebuildable in the target design system (Mantine) from those carrying bespoke logic that must be carefully PORTED (custom charts, complex tables, canvas, drag/drop). That split is the frontend's real migration cost.",
+      "description": "Component inventory. The load-bearing field is `rebuild`: it separates components that are trivially rebuildable in the target design system (shadcn) from those carrying bespoke logic that must be carefully PORTED (custom charts, complex tables, canvas, drag/drop). That split is the frontend's real migration cost.",
       "required": ["components"],
       "properties": {
         "components": {
@@ -1071,12 +1071,12 @@
               "rebuild": {
                 "type": "string",
                 "enum": [
-                  "mantine-standard",
-                  "mantine-composition",
+                  "library-standard",
+                  "library-composition",
                   "custom-style",
                   "custom-logic"
                 ],
-                "description": "mantine-standard = maps 1:1 to a Mantine component (trivial); mantine-composition = built from Mantine primitives (straightforward); custom-style = diverges visually from the design system (normalize to Mantine); custom-logic = bespoke behavior (chart/table/canvas/drag/editor) that must be PORTED, not re-skinned"
+                "description": "library-standard = maps 1:1 to a shadcn component (trivial); library-composition = built from shadcn primitives (straightforward); custom-style = diverges visually from the design system (normalize to shadcn); custom-logic = bespoke behavior (chart/table/canvas/drag/editor) that must be PORTED, not re-skinned"
               },
               "customLogic": {
                 "type": "string",

package/skills/pikku-software-archaeology/references/pikku-mapping.md

@@ -27,11 +27,11 @@ The `.knowledge/` blueprint is designed so each concept maps onto exactly one Pi
 | `interfaces.json` kind=mcp                                                  | `wireMCP` — each MCP tool IS a `pikkuFunc` (reuse the command/query funcs; don't author tool duplicates)                                                                                                                                                                                                                        |
 | `interfaces.json` kind=openapi-rest / sdk                                   | generated, not hand-written: the OpenAPI spec + typed client SDK fall out of the `wireHTTP` routes + codegen                                                                                                                                                                                                                    |
 | `interfaces.json` kind=websocket-realtime                                   | `pikku-wiring` EventHub topics / channels                                                                                                                                                                                                                                                                                     |
-| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `@pikku/mantine` theme, `pikku-react` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
+| `frontend.json`                                                             | `apps/app` (TanStack Start) shell: router, `packages/theme` theme, `pikku-react` data layer, `better-auth` client — the target stack the legacy UI is rebuilt onto                                                                                                                                                        |
 | `frontend-routes.json`                                                      | TanStack Router routes under `apps/app/src/routes/**` (thin data containers calling `usePikkuQuery`); `dataFrom` names become the generated hooks; subpath routes for rich detail views                                                                                                                                         |
-| `frontend-components.json` rebuild=`mantine-standard`/`mantine-composition` | components in `packages/components` composed from `@pikku/mantine` — the trivial/straightforward bulk                                                                                                                                                                                                                           |
+| `frontend-components.json` rebuild=`library-standard`/`library-composition` | components in `packages/components` composed from shadcn components — the trivial/straightforward bulk                                                                                                                                                                                                                           |
 | `frontend-components.json` rebuild=`custom-logic`                           | the PORT list — each becomes a `packages/components` component that reimplements the bespoke behavior (chart/table/editor); its `dependencies` inform whether the lib is kept or replaced. These are the frontend's real work items                                                                                             |
-| `frontend-components.json` rebuild=`custom-style`                           | normalize to Mantine/theme tokens; usually deleted-and-recomposed, not ported                                                                                                                                                                                                                                                   |
+| `frontend-components.json` rebuild=`custom-style`                           | normalize to shadcn/theme tokens; usually deleted-and-recomposed, not ported                                                                                                                                                                                                                                                   |
 
 ## Order of generation
 

package/skills/pikku-software-archaeology/references/second-opinion.md

@@ -1,5 +1,17 @@
 # Product Second Opinion
 
+## Contents
+
+- Overview
+- The cardinal rule: translate, don't dump
+- Report structure (layered — skim or dive)
+- Rewire vs rebuild (say which)
+- The frontend and the other ways your app is used
+- Technology choices — the honest tradeoffs (don't be cheap on the cons)
+- Delivery
+- Red flags — you're writing the wrong report
+- Relationship to the extraction phase
+
 ## Overview
 
 Turn an extracted product blueprint into a **report a non-technical owner can act on**. Two jobs, in one voice: (1) explain, in plain language, how the app they're stuck with actually works; (2) give an honest, opinionated second opinion — what's solid, what's holding them back, and how you'd build it better, argued in business outcomes, not architecture.
@@ -110,7 +122,7 @@ Worth naming when it applies: adopting one coherent system in place of hand-roll
 
 ### The stack a rebuild would land on
 
-Include this section **only if you are actually recommending a rebuild** onto it — and then give every part of it the same both-sides treatment you gave the app's own bets, per the "hold your own recommendation to the same bar" rule above. These are not choices the app made; they are choices you are proposing, which is exactly why their costs are the reader's to weigh. The Pikku target stack is Pikku + Better Auth + TanStack Start + Mantine; the framings below are reference material for the parts you actually recommend, not a script to recite.
+Include this section **only if you are actually recommending a rebuild** onto it — and then give every part of it the same both-sides treatment you gave the app's own bets, per the "hold your own recommendation to the same bar" rule above. These are not choices the app made; they are choices you are proposing, which is exactly why their costs are the reader's to weigh. The Pikku target stack is Pikku + Better Auth + TanStack Start + shadcn; the framings below are reference material for the parts you actually recommend, not a script to recite.
 
 **Better Auth (self-hosted sign-in) — instead of a paid service like Auth0/Clerk.**
 

package/skills/pikku-tailwind/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: pikku-tailwind
+description: >-
+  Use when building a Tailwind + shadcn/ui interface on top of a Pikku backend — rendering dates that
+  came back from a generated client, keeping layout flow-relative so the app survives an RTL locale,
+  branching on colour scheme without hardcoding a shade, and choosing components. TRIGGER when:
+  putting a value from usePikkuQuery or an RPC response on screen, writing margins/padding/alignment
+  classes, choosing a date input or any shadcn component, handling light/dark, or fixing a
+  `@shadcn/lint` error. DO NOT TRIGGER when: the data does not come from a Pikku client (this is only
+  about what the generated clients hand you), or for user-facing copy (use pikku-i18n).
+installGroups: [client]
+---
+
+# Tailwind and shadcn/ui on a Pikku client
+
+The UI is Tailwind v4 utility classes over shadcn/ui components that live in the app's own
+`src/components/ui/`. They are source you edit, not a dependency you configure. Every colour, radius
+and font comes from CSS variables in the app's `theme.css`; change the look by editing the theme presets in `packages/theme/themes` (the theme command ships with the UI addon).
+
+## Components
+
+- Use the shadcn component for the job (`Button`, `Input`, `Select`, `Sheet`, `Table`, `Tabs`,
+  `Calendar`) before writing markup. Compose it with utility classes for layout.
+- Need a size or look the component lacks? Add a `variant` or `size` to the component file with
+  `cva`, then use it. Do not restyle one instance with a pile of classes.
+- A raw `<div onClick>` or `<span role="button">` gets none of Radix's keyboard and ARIA handling.
+  Use `Button`, `Toggle` or the matching primitive.
+- Merge classes with `cn()` from `@/lib/utils`, never string concatenation.
+- Forms take a visible `<Label htmlFor>` on every input; a placeholder is not a label.
+
+## Lint
+
+`@shadcn/lint` runs in ESLint/Oxlint and fails the build. It reads the app's components, variants and
+theme, and every error names what to use instead. Fix the cause the message points at:
+
+- an arbitrary value (`w-[313px]`, `bg-[#2F5D62]`) → a spacing step or a theme token
+- a raw palette class (`bg-blue-500`, `text-gray-400`) → a semantic token (`bg-primary`,
+  `text-muted-foreground`)
+- a missing variant → add it to the component, then use it
+
+Never silence a rule with a disable comment to get past it.
+
+## Dates — always format before rendering
+
+The generated clients run `transformDates`, which revives **fully-zoned ISO-8601 instants** —
+`2026-03-14T08:12:00Z`, `2026-03-14T08:12:00.000+01:00` — into `Date` objects and touches nothing
+else. A bare `2026-03-14`, a zoneless `2026-03-14T08:12:00` and an impossible `2026-02-31T00:00:00Z`
+all stay the strings the server sent. So a field's runtime type follows the VALUE, not the schema:
+one column can arrive as a `Date` from one row and a string from the next.
+
+Two consequences, and both compile:
+
+- **A string method on one white-screens the page.** `row.createdAt.split('T')[0]` type-checks
+  against nothing useful and blows up at runtime. There is no string to slice.
+- **A raw `Date` dropped into JSX crashes the route.** `<span>{row.createdAt}</span>`, a table cell,
+  a `<Badge>` — React throws `Objects are not valid as a React child (found: [object Date])` and the
+  page falls into its error boundary. Nothing catches it before the screen is white, which makes it
+  the most common broken page in a build.
+
+**Format with dayjs.** It takes either a `Date` or a string. Never `toLocaleDateString`, `date-fns`
+or `luxon`.
+
+```tsx
+import dayjs from 'dayjs'
+
+<span>{dayjs(row.dueOn).format('D MMM YYYY')}</span>
+<span>{dayjs(row.createdAt).format('D MMM YYYY, HH:mm')}</span>
+```
+
+A relative "2 days ago" via dayjs `relativeTime` is fine. Coercing instead of formatting
+(`` `${d}` ``, `String(d)`, `d + ''`) does not crash but prints
+`Mon Jun 15 2026 02:00:00 GMT+0200` — a different bug, equally wrong.
+
+Date **inputs** are the shadcn `Calendar` inside a `Popover` (the date-picker recipe), never a raw
+`<input type="date">`. A calendar is not a schedule: there is no week/time-grid component, so a
+diary, rota, timetable or booking week is a grid you build. `Calendar` with a custom day cell IS
+right for "a few things on each day of a month", like a content calendar or a holiday planner.
+
+All of this applies to stub and fixture dates exactly as it does to real data.
+
+## RTL-safe styles
+
+Write layout classes flow-relative so the UI works in both LTR and RTL languages. Pikku's i18n ships
+Arabic, Hebrew, Farsi and Urdu support, and a physical margin is what breaks under it.
+
+| Avoid                    | Use instead                 |
+| ------------------------ | --------------------------- |
+| `ml-*`, `mr-*`           | `ms-*`, `me-*`              |
+| `pl-*`, `pr-*`           | `ps-*`, `pe-*`              |
+| `left-*`, `right-*`      | `start-*`, `end-*`          |
+| `text-left`, `text-right`| `text-start`, `text-end`    |
+| `border-l`, `border-r`   | `border-s`, `border-e`      |
+| `rounded-l`, `rounded-r` | `rounded-s`, `rounded-e`    |
+| `flex-row-reverse`       | the `dir` attribute         |
+
+Directional icons (chevrons, arrows) flip with `rtl:rotate-180`.
+
+## Dark mode
+
+Colours come from semantic tokens that already change per scheme: `bg-background`,
+`text-foreground`, `bg-card`, `border-border`, `text-muted-foreground`. They need no `dark:` prefix.
+Use a `dark:` variant only to pick between two theme tokens, never to introduce a literal colour or a
+palette shade for one scheme.
+
+```tsx
+// Correct
+<div className="bg-background text-foreground">
+
+// Wrong — scheme branch with hardcoded palette shades
+<div className="bg-gray-50 dark:bg-zinc-900">
+```

package/skills/pikku-theme/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: pikku-theme
+description: >-
+  Use when giving a Pikku Tailwind + shadcn/ui app its look: picking and applying a theme with `pikku
+  ui theme list|apply`, composing brand colours, fonts, page and ink over a preset's structure, matching
+  an existing look by hand, declaring component variants in the component's `cva` definition,
+  replacing template names (`pikku validate` flags them), and keeping emails/theme.json on-brand.
+  Also the light/dark and WCAG contrast rules a theme must clear. TRIGGER when: the user asks to
+  theme, restyle, rebrand or recolour an app; the project has packages/theme (themes/*.json,
+  active.json); a screen needs a colour, font, radius or shadow; or the app still shows a template
+  name. DO NOT TRIGGER when: rendering data or RTL layout (use pikku-tailwind),
+  writing email templates (use pikku-emails), or accessibility beyond colour (use pikku-a11y).
+installGroups: [client]
+---
+
+# Theming a Pikku Tailwind app
+
+The look of the app lives in one package, `packages/theme`, and the CLI owns it. Do not hand-edit
+the theme JSON or the generated `theme.css` to change the look; run `pikku ui theme apply`. Every
+colour in app code then comes from the theme, never a literal.
+
+## The theme package
+
+```
+packages/theme/
+  themes/
+    default.json      # one file per theme: { name, description, brand, structure }
+    <id>.json         # written by `pikku ui theme apply`
+  active.json         # { "id": "<id>" } — which theme the app renders
+  base.json           # optional: spacing / radius / fontSizes scales shared by every theme
+  theme.css           # GENERATED on every apply/switch — never edit
+```
+
+The app imports `theme.css` once, after Tailwind. It holds the shadcn tokens as CSS variables in
+OKLCH, a `:root` block for light and a `.dark` block for dark, and the font variables. Tailwind's
+`@theme inline` maps those variables to utilities, so `bg-primary`, `text-muted-foreground` and
+`rounded-lg` follow the active theme with no JavaScript.
+
+A theme is ONE set of tokens in two halves:
+
+- **brand** — `colors` (`primary`, `secondary`, `accent`, as hex) and `fonts` (`heading`, `body`,
+  optional `mono`, each a Google Fonts family). This is what makes two apps look different.
+- **structure** — the depth: `radius` (the base for `rounded-*`), `shadows` (`xs`..`xl`), `density`
+  (the spacing scale), `page` (light page colour), `ink` (light text colour), `defaultColorScheme`,
+  and an optional `darkSurface` ramp. This is what makes styles read as genuinely different rather
+  than recoloured.
+
+`pikku ui theme apply` generates the whole token set from those inputs: each brand colour becomes
+`--primary`, `--secondary`, `--accent` with a matching `-foreground` picked for contrast, the neutral
+ramp (`--background`, `--card`, `--muted`, `--border`, `--input`, `--ring`) is tinted toward the
+primary's hue unless `darkSurface` is given, and `--muted-foreground` is darkened in light mode so it
+clears AA. The frontend writes plain `<Card>` and `<Button>` and inherits all of it.
+
+## Presets, structures and brands
+
+A **preset** pairs a brand and a structure under one id and tags the kinds of app it suits.
+`pikku ui theme list` prints the themes on disk, the active id, the listed presets (with `suits` tags)
+and their structures. The full set, including the presets `list` hides but `apply` still accepts,
+is in `references/presets.md`.
+
+Choosing:
+
+1. **Default to light.** A near-black UI flattens the palette, the depth and the type scale at
+   once and is the most common "this looks cheap" tell. Pick a dark-first preset (`terminal`,
+   `blueprint`, `neon`, `matrix`) only when the domain asks for it: developer and terminal tools,
+   code and DevOps, media, music, observability.
+2. **Tool or experience?** An app opened because a job requires it (CRM, booking, admin, finance)
+   takes a workplace preset. An app someone opens because they want to (a story, a journal, a
+   meditation or kids' app, a recipe box) takes a character preset (`storybook`, `stillness`),
+   which carries a warm page colour and a reading body face. A story on `monopro` or `linear`
+   comes out looking like a changelog, and later styling does not recover it.
+3. **Lean bold.** The structure cascades to every component, so this one choice decides the look.
+4. **Compose the app's own look on top.** Presets are starting points, not a menu. Take the preset
+   whose STRUCTURE carries the right depth, then set colours, fonts, page and ink from what the app
+   actually is.
+
+## `pikku ui theme apply`
+
+```bash
+pikku ui theme list
+pikku ui theme apply --preset breeze
+pikku ui theme apply --preset storybook \
+  --primary '#2F5D62' --secondary '#A7774B' --accent '#D9A441' \
+  --font-heading 'Young Serif' --font-body 'Literata' \
+  --page '#FBF5EA' --ink '#2A2118'
+pikku ui theme apply --preset quorum --structure monopro
+```
+
+| Flag | Sets |
+| --- | --- |
+| `--preset <id>` | starting brand + structure; the theme is written as `themes/<id>.json` (no preset → `custom`, based on the first preset) |
+| `--structure <id>` | swap in another preset's structure (depth) under this brand |
+| `--primary`, `--secondary`, `--accent` | brand colours, hex |
+| `--font-heading`, `--font-body` | Google Fonts families |
+| `--page` | light-mode page colour (`structure.page`) — paper, linen, bone instead of white |
+| `--ink` | light-mode text colour (`structure.ink`) |
+
+Flags are flat scalars, one value each; there is no nested `--colors` object. One call writes the
+theme, makes it active, regenerates `themes/index.ts` (so the running app reloads) and re-brands
+`emails/theme.json`. There is no separate activate step. Re-running with the same preset overwrites
+that theme file.
+
+Fine-grained structure tweaks the flags do not cover (a shadow scale, the radius base) are edits to
+the active `themes/<id>.json` `structure`, followed by `pikku ui theme apply` to regenerate
+`theme.css`; keep them in the theme, not in components.
+
+## Colour rule
+
+Every colour in app code comes from the theme: a semantic utility (`bg-primary`, `text-foreground`,
+`bg-muted`, `border-border`, `text-destructive`) or a token your theme exports. No hex, `rgb()`,
+`hsl()`, named CSS colour, arbitrary value (`bg-[#2F5D62]`), raw palette class (`bg-blue-500`),
+ad-hoc alpha or one-scheme shade in components or CSS. Gradients, tinted borders and shadows follow
+the same rule: define them as tokens in the theme and reference them. `@shadcn/lint` enforces this
+and names the token to use instead. Before finishing UI work, run it and scan the changed files for
+colour literals.
+
+## Light, dark and contrast
+
+- Always set `structure.defaultColorScheme`. It decides which block the page boots in; a theme
+  without it boots dark.
+- A dark-first structure ships an explicit `darkSurface` ramp (lightest text to deepest background).
+  Without one, the dark ramp is tinted toward the primary's hue; a near-grey primary stays neutral.
+- Semantic tokens already switch per scheme, so most classes need no `dark:` prefix. Use `dark:` only
+  to choose between theme tokens. Never hardcode a shade for one scheme; see pikku-tailwind.
+- **Text clears 4.5:1 (WCAG AA) on every surface it can land on**, in both schemes. Verify, do not
+  estimate. If you need a colour dimmer than the dimmest text token, change the layout.
+- **Control boundaries clear 3:1** (WCAG 1.4.11): input borders, toggles, focus rings. A
+  translucent fill cannot reach 3:1 on a dark surface; the border carries it.
+- **Two tiers.** Text-tier colours (words, links, status labels) must clear 4.5:1. Graphic-tier
+  colours (dots, bars, chart series, icons) need 3:1 and may be more chromatic, but never carry
+  words. On white no amber that still reads as amber clears 4.5:1, so light-mode warnings are
+  carried by a tinted fill with normal text, and the amber is only the mark.
+- **Accent means state.** The accent marks selection, current item, active state, and means the
+  same thing in both schemes. On an element regardless of its state, it is decoration.
+- Every `-foreground` token is generated from its surface, so a filled button gets a readable
+  label. The page/ink you pass with `--page`/`--ink` must clear 4.5:1 against each other, and the
+  primary must still read on the page.
+- One status vocabulary: red, amber/yellow, green, plus a neutral. Do not add a second spelling of
+  a colour that already exists.
+
+## Custom variants and component metadata
+
+Read a component's `cva` definition in `src/components/ui/` for the variants and sizes it accepts before guessing a `variant` or `size` value.
+
+A custom variant is added where the component defines its variants, in the component file:
+
+```js
+const buttonVariants = cva('...', {
+  variants: {
+    variant: {
+      default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+      brand: 'bg-accent text-accent-foreground hover:bg-accent/90',
+    },
+  },
+})
+```
+
+`@shadcn/lint` then accepts `variant="brand"` and its error messages suggest it. Use theme tokens only inside a variant. Add it
+once and use it; do not restyle one button inline.
+
+## Names and emails
+
+The starter templates ship with placeholder names. Replace them before anything else ships.
+`pikku validate` reports each place still using a template's name (the `placeholder-brand` checks):
+`app__name` in the app's `messages/en.json` (the wordmark in the shell and auth screens), the
+`title` / `og:title` / `og:site_name` meta in `src/app-meta.ts` or `__root.tsx`, and `appName` in
+`emails/theme.json`. Update other app-identity strings (tagline, description) at the same time.
+
+**Emails.** `pikku ui theme apply` rewrites `emails/theme.json`
+from the applied theme: neutrals from the scheme (or the `darkSurface` ramp for a dark theme),
+`accent`, `button` from the primary, `buttonText` black or white by luminance, `fonts.body` from
+the brand. It merges, so `appName` and any project keys survive. It cannot know the app's name: set
+`appName` yourself right after the first apply, because confirm-address and reset-password emails
+send from the first signup. Then read `emails/locales/en.json` and fix any line that names the
+template. `pikku emails catalog` lists ready-made emails (invitation, magic-link, password-reset,
+receipt, welcome) and `pikku emails add <name>` copies one in; they use the same theme keys. See
+pikku-emails.
+
+## Matching an existing design
+
+When the user names a live site or a design-tokens file, read its colours, fonts and depth yourself
+and pass them to `pikku ui theme apply`. The recipe is in `references/from-a-reference.md`.
+
+## Hosted only
+
+Interactive theme pickers, design extraction, stock images, site crawling, favicon generation, AI-generated logos and
+agent-driven build flows are not part of the CLI; a hosting platform may offer them.