Merge pull request #606 from Perdolique/update-packages

Add catalog navigation and update dev tools

Author: Perdolique

.agents/skills/equipment-backend/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: equipment-backend
+description: Equipment and catalog backend conventions for the Perd project. Use this skill whenever the task touches `server/api`, `server/utils/validation`, `server/database/schema.ts`, Drizzle write paths, equipment reference data, contributions logging, or equipment API tests, even if the user does not explicitly mention the backend skill.
+---
+
+# Equipment Backend Conventions
+
+Use this skill for equipment and catalog backend work. Keep the implementation narrow, predictable, and shaped by current product needs instead of speculative abstractions.
+
+## Scope
+
+Apply these rules when working on:
+
+- `server/api/equipment/**`
+- `server/utils/validation/**`
+- `server/database/schema.ts`
+- Drizzle queries and write paths that touch equipment catalog data
+- Equipment-related Vitest API handler tests
+
+Do not use this skill for generic Vue or styling work. Use the dedicated frontend skill for `.vue` files.
+
+## Data model expectations
+
+- Keep the EAV model intact: `category_properties` defines available properties, `item_property_values` stores actual item values.
+- Keep groups and categories independent. Do not add a foreign key between them unless the product plan explicitly changes.
+- Treat items as flat catalog rows. Size and similar distinctions belong in properties, not a variant system.
+- Keep UUID v7 for user-facing entities and serial IDs for reference data.
+- Keep reference-data slugs canonical and lowercase.
+- Keep `equipment_items` foreign keys to brand/category non-cascading with `restrict`.
+- Keep all schema sections in `server/database/schema.ts`.
+
+## Route and validation conventions
+
+- Public read routes for reference data use `slug` in route params.
+- Admin mutation routes for reference data use stable `id` params because `slug` is editable content.
+- Category-property admin routes stay nested under category ID routes so handlers can verify parent ownership from the route chain.
+- Validate every request input through the shared Valibot helpers:
+  - `readValidatedBody` for request bodies
+  - `getValidatedRouterParams` for route params
+  - `getValidatedQuery` for query strings
+- Keep schemas and validator helpers in `server/utils/validation/schemas.ts`. Handlers should consume parsed values, not manually re-validate raw input.
+
+## Write-path and query-shape rules
+
+- Any admin catalog write that both mutates reference data and logs `contributions` must be atomic. Use a transaction-capable write path rather than separate `dbHttp` calls.
+- `contributions.targetId` stores the changed entity primary key as a string so it can hold either serial IDs or UUIDs.
+- Public detail endpoints stay narrow. Return the entity needed for that route and fetch related collections with separate endpoints only when there is a concrete consumer.
+- For shared `returning(...)` fragments, prefer small server-only base-record helpers over global endpoint models.
+- When only one row is needed once, destructure directly from the awaited query result: `const [row] = await ...`.
+- If deleting an enum option would orphan existing enum item values, return `409`.
+- Protected `/api/*` routes keep mixed unauthenticated behavior: browser navigations redirect to login, programmatic requests still receive `401`.
+
+## Testing expectations
+
+- Cover API handlers in Vitest with mocks for `event`, `dbHttp`, auth helpers, and validated-input helpers as needed.
+- Do not rely on seeded database state or fixed catalog row counts in required tests.
+- Keep browser-level coverage in Playwright as smoke coverage, not the primary API contract layer.
+- Put shared test helpers in the repo root, such as `test-utils/`, instead of runtime source trees.
+- Prefer `vi.mock(import(...))` so mocks stay aligned with the project lint rules.
+- Avoid file-level lint disables in tests unless there is a documented tool mismatch and no cleaner local fix.
+
+## Skill maintenance
+
+If this skill starts to sprawl, move detailed reference material into `references/` files instead of bloating this `SKILL.md`.

.agents/skills/planning-docs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: planning-docs
+description: Planning and documentation conventions for the Perd project. Use this skill whenever the task touches files in `plan/`, roadmap structure, completed-work notes, architecture documentation, or asks to split work into implementation iterations, even if the user does not explicitly mention planning.
+---
+
+# Planning And Documentation Conventions
+
+Use this skill for roadmap maintenance and planning docs. The goal is to keep the plan tree small, current, and implementation-oriented instead of turning it into a vague backlog dump.
+
+## Scope
+
+Apply these rules when working on:
+
+- `plan/**`
+- roadmap summaries and task decomposition
+- completed-work summaries
+- architecture notes that change how future work should be implemented
+
+Do not use this skill for backend endpoint code unless the task also changes roadmap or documentation artifacts.
+
+## Roadmap model
+
+- Treat `plan/` as the global product roadmap, not a sprint board or personal todo list.
+- Keep `plan/PLAN.md` short and use it as an index to detailed plan files.
+- Large efforts should be split into sequential iteration files when that helps implementation stay concrete.
+- Move completed work summaries to `plan/completed.md` instead of leaving stale execution detail inside roadmap specs.
+
+## Iteration design
+
+- Prefer the smallest completed iteration that removes one blocker or delivers one coherent slice.
+- Do not add speculative implementation detail, abstractions, or future phases that the current iteration does not need.
+- For new API iterations, every join must be justified by a returned field or an applied filter in that iteration.
+- Do not add extra detail endpoints or broader detail payloads unless the current iteration already has a concrete consumer.
+- Treat response examples in plan files as the upper bound for that iteration's payload. Do not silently extend them.
+
+## Update rules
+
+- When roadmap files are renamed or moved, update links in `plan/PLAN.md` and any overview files immediately.
+- If a task changes architecture, route conventions, data-model expectations, or test strategy, update the relevant planning or documentation files in the same change.
+- Keep completed notes short and factual. Save detailed implementation guidance for the active roadmap files that still matter.
+
+## Writing style
+
+- Write plans so another engineer can implement them without guessing the intended slice.
+- Prefer concrete behavior and current constraints over generic platform-speak.
+- Remove stale guidance instead of appending contradictory notes on top of it.

.agents/skills/vue-components/SKILL.md

@@ -9,6 +9,8 @@ description: Vue component conventions and patterns for the Perd project. Use wh
 
 Use the standard order: `<template>`, `<script>`, `<style>`.
 
+If a UI has a small, fixed number of known elements and all labels, props, and targets are already known, write those elements directly in the template. Do not introduce arrays, `v-for`, config objects, or extra computed state just to make static markup look generic. Use config-driven rendering only when the structure is genuinely dynamic or repeated enough to justify abstraction.
+
 Type exports that other components need go in a separate non-setup script block above the setup block:
 
 ```vue
@@ -121,6 +123,17 @@ useEventListener(dialogRef, 'close', () => {
 document.addEventListener('pointerdown', handler)
 ```
 
+## Accessibility
+
+All UI must be accessible and meet at least **WCAG 2.1 AA**. Treat this as a project requirement, not a nice-to-have.
+
+- Prefer semantic HTML over `div` / `span` plus manual `role` attributes when a native element already provides the correct behavior.
+- All interactive elements must be keyboard accessible and have a visible focus state.
+- Icon-only buttons, form inputs, and custom controls must have an accessible name via `aria-label`, `aria-labelledby`, or an associated `label`.
+- Decorative elements should be hidden from assistive technology with `aria-hidden="true"`. Informative images must have a meaningful `alt`.
+- Do not rely on color alone to communicate meaning, state, or validation errors.
+- If a custom control is necessary, it must match the native equivalent's keyboard, focus, and ARIA behavior.
+
 ## Styling
 
 ### CSS Modules Only
@@ -176,6 +189,14 @@ The project targets modern browsers only. Use these freely:
 - **`@layer`** for CSS organization (reset, colors, spacings, sizes, transitions, typography)
 - **CSS custom properties** for all design tokens (`--spacing-*`, `--color-*`, `--font-size-*`, etc.)
 
+Prefer native CSS features that are already part of the supported browser baseline over legacy compatibility workarounds.
+
+### Responsive Rules
+
+Use `@container` for component-level responsive layout changes that should react to the space actually available inside the component.
+
+Keep `@media` for viewport- and environment-level behavior such as app shell breakpoints, fullscreen page treatments, overlays, and user preference queries like `prefers-color-scheme`.
+
 ### Media Queries
 
 Use the modern range syntax:

AGENTS.md

@@ -6,86 +6,40 @@
 - Drizzle ORM
 - Neon PostgreSQL
 
-## Equipment architecture
+## Core project invariants
 
-### Data model
+- Equipment properties use an EAV model: `category_properties` defines available fields, `item_property_values` stores per-item values.
+- Groups and categories are separate reference entities with no FK between them. Do not invent one unless the product plan explicitly changes.
+- Items are flat. Size and similar distinctions are category properties, not a variant subsystem.
+- User-facing catalog entities use UUID v7 where the product already depends on stable public IDs. Reference data uses serial IDs.
+- Reference-data slugs are canonical lowercase URL tokens using only `a-z`, `0-9`, and single hyphens.
+- Reference-data `name` values stay English display strings. Slugs are the durable keys for URLs and future i18n lookups.
+- `equipment_items` brand/category foreign keys must stay non-cascading (`restrict`), so deleting reference data cannot silently remove catalog or inventory records.
+- Public reference-data read routes use `slug`; admin mutations use stable `id` params.
+- All tables live in `server/database/schema.ts`, organized by Auth, Equipment catalog, and User data sections.
 
-- **EAV (Entity-Attribute-Value)** for item properties: `category_properties` defines what properties a category has, `item_property_values` stores actual values per item. This enables dynamic filters and item comparison without schema migrations.
-- **Two-level categorization**: Groups (functional area: Sleep, Shelter, Cooking) and Categories (specific type: Sleeping Bags, Sleeping Pads) are independent entities with no FK relationship. Connection can be added later when navigation patterns become clear.
-- **Items are flat** — each size/variant is a separate item. Size is a category property, not a separate variant system.
+## Local skills
 
-### Database conventions
+Before any task, check whether a local skill matches the domain and follow it.
 
-- **UUID v7** as PK for all user-facing entities (items, user_equipment, contributions).
-- **Serial** PK for reference data (groups, categories, properties, brands).
-- **Slugs** on reference data only (groups, categories, brands) — used for URLs and as future i18n translation keys. Items use UUID in URLs.
-- **Reference data slugs are canonical lowercase URL tokens** using only `a-z`, `0-9`, and single hyphens between segments.
-- **`name`** columns on reference data are English display values. When i18n is added, `slug` maps to a translation key, `name` becomes the fallback.
-- **Brand/category FKs from `equipment_items` must not cascade on delete**: use `restrict` so deleting reference data cannot silently remove catalog items, item property values, or user inventories.
+- `vue-components` for `.vue` component structure, styling, props/emits, and SSR-safe frontend patterns.
+- `equipment-backend` for equipment/catalog backend work in `server/api`, validation schemas, Drizzle write paths, schema changes, and equipment API tests.
+- `planning-docs` for roadmap files in `plan/`, completed work notes, architecture docs, and iteration planning tasks.
 
-### API conventions
+## Workflow rules
 
-- **Public read routes for reference data use `slug`** in detail URLs (`/api/equipment/brands/[slug]`, `/api/equipment/categories/[slug]`).
-- **Admin mutation routes for reference data use `id`** in route params (`PATCH`/`DELETE`), because `slug` is editable content and must not be the stable mutation key.
-- **Admin category property mutations stay nested under category `id` routes** (`/api/equipment/categories/[categoryId]/properties/...`) so parent ownership is explicit and property/enum-option handlers can verify the full route chain.
-- **All API request inputs use Valibot schemas through h3 validated helpers**: `readValidatedBody` for request bodies, `getValidatedRouterParams` for route params, and `getValidatedQuery` for query strings. Schemas and validator functions live in `server/utils/validation/schemas.ts`; handlers should consume parsed values instead of manually validating raw input.
-- **Catalog admin writes that both mutate reference data and log `contributions` must be atomic**: run them through a transaction-capable write path, not separate `dbHttp` calls.
-- **Single-result query arrays should be destructured directly from the awaited query** when only the first row is needed once (`const [row] = await ...`); keep an intermediate array only when the full result set, row count, or repeated reuse matters.
-- **Public read detail endpoints stay narrow**: return the entity needed for that route, and fetch related collections with separate read endpoints when a page needs them. Do not expand detail payloads just to save a future frontend request.
-- **Shared catalog `returning(...)` shapes use reusable base records, not global endpoint models**: extract common `id`/`name`/`slug` selections into server-only helpers when reused, but keep each endpoint free to return a different response shape later if needed.
-- **Deleting an enum option that is already used by existing item property values must return `409`**: enum item values are currently stored by slug text, so option deletes need an application-level guard against orphaned enum values.
-- **Protected `/api/*` routes keep mixed auth behavior by caller type**: unauthenticated browser document navigations redirect to `/login?redirectTo=...`, while programmatic API requests (`fetch`/XHR) still receive `401`.
+- Files imported by standalone Node or `tsx` scripts, including `tools/*.ts`, migrations, seeds, and their transitive dependencies, must not rely on Nuxt-only aliases like `~/` or `@@/`. If they use `#shared/*` or `#server/*`, keep those aliases backed by `package.json#imports`.
+- After any architecture, route-convention, data-model, or test-strategy change, update the relevant docs in the same change. This can include `AGENTS.md`, `plan/PLAN.md`, `plan/completed.md`, or the detailed roadmap file that changed.
 
-### Testing conventions
+## Verification matrix
 
-- **API handlers are tested in Vitest with mocks** for `event`, `dbHttp`, and auth/body helpers. Required API coverage must not depend on shared database state.
-- **Playwright is reserved for browser/UI smoke** and must not be the primary layer for API contract coverage.
-- **Deterministic tests over seeded assumptions**: avoid checks that depend on fixed counts or specific catalog rows in a real database.
-- **Shared test helpers live at the repo root** (for example `test-utils/`), not inside `server/` or `app/`, so runtime source trees stay free of test-only utilities. Import them through root aliases like `~~/` or `@@/`, not deep relative paths.
-- **Avoid file-level lint disables in tests** when a clean test helper, typed wrapper, or test-specific lint override can solve the problem. Use inline/file disables only as a last resort for a documented tool mismatch.
-- **Prefer `vi.mock(import(...))` in Vitest** so test mocks stay aligned with the project skill and `vitest/prefer-import-in-mock`. If a test needs leniency, prefer narrow `oxlint` test overrides like `max-lines` or `import/no-relative-parent-imports`, not disabling mock-style rules.
+After any code modification, run the checks that match the files you touched.
 
-### Content management
+- If Markdown files changed: `pnpm run lint:markdown`
+- If TypeScript or Vue code changed: `pnpm run test:typecheck`
+- If TypeScript or Vue code changed: `pnpm run test:unit:agent`
+- If TypeScript or Vue code changed: `pnpm run lint:oxlint`
+- If TypeScript or Vue code changed: `pnpm run build`
+- If TypeScript or Vue code changed: `pnpm run test:e2e:ci`
 
-- **Contributions table** logs every write operation (create/update/delete) with userId, action, targetId, and optional metadata. `targetId` stores the changed entity's primary key as a string, so it can hold either a serial ID or a UUID. Used for future gamification.
-- **Item status**: `approved` by default for admin-created items. Future user submissions will default to `pending`.
-- MVP: only admins can manage the equipment catalog. Users browse and add items to their inventory.
-
-### Schema file
-
-All tables live in a single `server/database/schema.ts` file, organized by sections: Auth, Equipment catalog, User data.
-
-## Workflow
-
-Before performing any task, action, or code modification, event small one, check if there are existing skills that cover the domain of your task and follow their instructions.
-
-- Files imported by standalone Node/`tsx` scripts (for example migration, seed, and other `tools/*.ts` entry points, plus their transitive dependencies) must not rely on Nuxt-only aliases like `~/` or `@@/`. If such files use `#shared/*` or `#server/*`, keep those aliases backed by `package.json#imports`, because plain script execution does not get Nuxt alias resolution automatically.
-
-After any code modification, always run:
-
-- If Markdown files are modified:
-  - `pnpm run lint:markdown` for markdown linting
-- If TypeScript or Vue code is modified:
-  - `pnpm run test:typecheck` - to ensure type safety
-  - `pnpm run test:unit:agent` for unit tests
-  - `pnpm run lint:oxlint` for linting
-  - `pnpm run build` to ensure the project builds successfully
-  - `pnpm run test:e2e:ci` for E2E tests (auto-starts dev server)
-
-All tasks above can be run in parallel.
-
-If any architectural decisions were made during the task (new patterns, conventions, data model changes), update relevant sections of this file. Remove or revise entries that are no longer accurate.
-If a task changes architecture, route conventions, or test strategy, update `AGENTS.md` and relevant roadmap/completed docs in the same change automatically.
-
-## Planning conventions
-
-The `plan/` directory is the **global product roadmap**, not a per-sprint task list. It describes the full scope of planned product features and their implementation order.
-
-- Prefer the **smallest possible completed iteration** that removes one blocker or delivers one coherent slice. Smaller iterations reduce implementation mistakes and make progress easier to verify.
-- For new API iterations, every join must be justified by a field returned in the current response or by a filter applied in the current endpoint. Do not preload relations "just in case".
-- Do not add extra detail payload or extra detail endpoints unless the current iteration already has a concrete consumer for them.
-- Response examples in plan files are the **upper bound** for payload in that iteration. Do not silently extend them without updating the plan and the consumer need.
-- `plan/PLAN.md` is the roadmap index — keep it short, link to detailed plan files.
-- Large iterations must be split into sequential task files (e.g. `plan/admin-management/01-foundations.md`).
-- Completed work goes to `plan/completed.md` as short summaries, not detailed specs.
-- When plan files are renamed or moved, update links in `plan/PLAN.md` and overview files immediately.
+All applicable commands may be run in parallel.