document standalone vue workflow

Update the AI guidance for the scaffolded npm application, its actual validation scripts, and its independent runtime boundary. Record the current lack of frontend test tooling without inventing commands.

ai/frontend-context.md

@@ -2,53 +2,94 @@
 
 Read `ai/shared.md` first. This file covers frontend-specific rules.
 
-## Current state
+## Project context
 
-The Vue frontend has not been scaffolded yet. The backend has Inertia Laravel
-installed and an Inertia route, but there is no `package.json`, Vue source
-tree, Vite configuration, or frontend test setup.
+**Stack:** Vue 3.5, TypeScript 6, Vite 8, Vue Router 5, Pinia 4, npm.
 
-- Do not create the frontend unless the user explicitly asks.
-- Do not invent a frontend directory, package manager, dependency version, or
-  command before the scaffold establishes it.
-- When the frontend is created, update this file with its actual paths,
-  package versions, scripts, and testing tools.
+**Location:** `frontend/website/`.
+
+The frontend is a standalone application. Keep its source, dependencies,
+development server, and production build independent from the backend unless
+the user explicitly requests integration.
+
+The scaffold uses:
+
+- `src/App.vue` as the root component.
+- `src/main.ts` to create the app and install the router and Pinia.
+- `src/router/index.ts` for routes.
+- `src/stores/` for Pinia stores.
+- `@` as an alias for `src/` in both Vite and TypeScript.
+
+There are no views, shared components, API layer, or test setup yet. Do not
+invent an architecture for them before requested behavior establishes one.
+
+## Package management and commands
+
+Use npm and keep `package-lock.json` committed. Run commands from
+`frontend/website/`.
+
+Install dependencies in a fresh checkout or worktree:
+
+```sh
+npm install
+```
+
+Start the development server on the port assigned by the shell hook:
+
+```sh
+npm run dev -- --port "$VITE_PORT"
+```
+
+`process-compose` does not start or proxy the frontend.
+
+The available validation commands are:
+
+```sh
+npm run format
+npm run lint
+npm run type-check
+npm run build
+```
+
+`npm run format` and `npm run lint` rewrite files. Review the resulting diff.
+`npm run build` runs type checking and the production build. Build output
+under `dist/` is generated and ignored.
 
 ## Vue conventions
 
-Apply these rules once a Vue 3 frontend exists:
-
 - Use the Composition API and `<script setup lang="ts">`.
-- Use PascalCase component filenames.
+- Use PascalCase component and view filenames.
+- Put reusable components under `src/components/`.
+- Put route-level views under `src/views/` and register them in
+  `src/router/index.ts`.
 - Keep page, component, composable, and store responsibilities distinct.
 - Prefer small components with explicit props and emitted events.
-- Keep component styles scoped unless the scaffold establishes a deliberate
-  global styling system.
-- Follow the routing and page conventions established by the chosen Inertia
-  or Vue Router scaffold. Do not mix the two approaches without an explicit
-  architectural reason.
-- Inspect similar files before introducing a new component, composable, store,
-  or data-access pattern.
+- Keep component styles scoped until the project adopts a deliberate global
+  styling system.
+- Use setup-style Pinia stores named `useXxxStore`.
+- Inspect similar files before introducing a new component, composable,
+  store, or data-access pattern.
 
 ## TypeScript
 
-- Enable and preserve strict mode.
-- Do not use `any`. Model unknown external values as `unknown` and narrow or
+- Preserve the strict TypeScript configuration and
+  `noUncheckedIndexedAccess`.
+- Do not use `any`. Model unknown external values as `unknown`, then narrow or
   validate them.
-- Derive types from runtime schemas when a schema library is adopted. Do not
-  maintain a hand-written type that can drift from its validation schema.
+- Derive types from runtime schemas if the project adopts a schema library.
+  Do not maintain a hand-written type that can drift from its schema.
 - Validate payloads at trust boundaries, especially backend responses and
   user-submitted forms.
-- Keep request and response types close to the API or store boundary that owns
-  them.
-- Add a path alias only when it is configured consistently in Vite,
-  TypeScript, tests, and Cypress.
+- Keep request and response types close to the API or store boundary that
+  owns them.
+- Keep the `@` alias aligned across Vite, TypeScript, and any future test
+  configuration.
 
 ## State and API access
 
-- Use the state-management approach chosen by the scaffold consistently.
-- Keep server data fetching and transformation at an API/store boundary, not
-  scattered through presentation components.
+- Use Pinia for shared client state. Keep component-local state in components.
+- Keep server requests and response transformation at an API or store
+  boundary, not scattered through presentation components.
 - Represent loading, empty, success, validation-error, and unexpected-error
   states explicitly.
 - Do not cast unchecked JSON directly to an application interface.
@@ -56,35 +97,24 @@ Apply these rules once a Vue 3 frontend exists:
 
 ## Testing
 
-Use layered tests once the frontend test setup exists:
+No frontend test runner or test script is configured yet.
 
-- Unit tests cover pure transformations, composables, store logic, computed
-  values, and formatting.
-- Component tests cover rendering, events, form behavior, and conditional UI.
-- Cypress tests cover routing, multi-page flows, and request wiring.
+- Do not invent test commands or claim frontend tests passed.
+- New frontend behavior must still follow the shared test-first workflow.
+  Establish the smallest appropriate test setup before implementing behavior
+  that needs it.
+- Unit tests should cover pure transformations, composables, and store logic.
+- Component tests should cover rendering, events, form behavior, and
+  conditional UI.
+- End-to-end tests should cover routing, multi-page flows, and request wiring.
 - Prefer the cheapest layer that proves the behavior.
-- Import test functions explicitly rather than relying on globals unless the
-  scaffold deliberately configures globals.
-- Build test data with small typed builders instead of repeated bare object
-  literals.
-
-## Frontend/backend test boundary
-
-- Mock backend requests in frontend tests.
-- A frontend test should verify how the UI consumes a response and which
-  request it sends, not retest Laravel's business rules.
-- Test backend persistence, validation, authentication, and mail behavior in
-  PHPUnit.
-- Keep mocked response bodies typed against the frontend's exported API or
-  store types.
-- When runtime schemas exist, parse mock-builder output through the same
-  schema so drift fails at the test boundary.
+- Mock backend requests in frontend tests. Do not retest backend persistence,
+  validation, authentication, or mail behavior through the frontend.
 
 ## Before completing frontend work
 
-- Run the formatter, linter, type checker, unit tests, and Cypress scripts
-  defined by the frontend's `package.json`.
-- Do not substitute a hand-picked subset for the repository's eventual full
-  frontend gate.
-- If the frontend cannot run because the scaffold or a required service is
-  absent, report the precise environmental or baseline failure.
+- Run the focused test while developing once test tooling exists.
+- Run the formatter, linter, type checker, production build, and every
+  configured test script affected by the change.
+- Do not claim a green gate when a command fails. Report a baseline or
+  environmental failure precisely.