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/backend-context.md

@@ -4,7 +4,7 @@ Read `ai/shared.md` first. This file covers backend-specific rules.
 
 ## Project context
 
-**Stack:** PHP 8.4, Laravel 13, Inertia Laravel, PHPUnit, Larastan, Composer.
+**Stack:** PHP 8.4, Laravel 13, PHPUnit, Larastan, Composer.
 
 **Location:** `backend/`.
 
@@ -26,8 +26,11 @@ pattern.
   duplicating query fragments.
 - Avoid speculative interfaces and abstractions with only one trivial
   implementation.
-- Routes currently use Inertia, but the Vue client has not been scaffolded.
+- The Vue application is a separate project under `frontend/website/`.
-  Do not add placeholder frontend assets as part of unrelated backend work.
+- Keep frontend source, dependencies, builds, and delivery out of the backend
+  unless the user explicitly asks to integrate them.
+- The backend root route is intentionally unclaimed. The built-in health
+  endpoint is `/up`.
 
 ## Tests
 

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
+**Stack:** Vue 3.5, TypeScript 6, Vite 8, Vue Router 5, Pinia 4, npm.
-installed and an Inertia route, but there is no `package.json`, Vue source
-tree, Vite configuration, or frontend test setup.
 
-- Do not create the frontend unless the user explicitly asks.
+**Location:** `frontend/website/`.
-- Do not invent a frontend directory, package manager, dependency version, or
+
-  command before the scaffold establishes it.
+The frontend is a standalone application. Keep its source, dependencies,
-- When the frontend is created, update this file with its actual paths,
+development server, and production build independent from the backend unless
-  package versions, scripts, and testing tools.
+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
+- Keep component styles scoped until the project adopts a deliberate global
-  global styling system.
+  styling system.
-- Follow the routing and page conventions established by the chosen Inertia
+- Use setup-style Pinia stores named `useXxxStore`.
-  or Vue Router scaffold. Do not mix the two approaches without an explicit
+- Inspect similar files before introducing a new component, composable,
-  architectural reason.
+  store, or data-access pattern.
-- Inspect similar files before introducing a new component, composable, store,
-  or data-access pattern.
 
 ## TypeScript
 
-- Enable and preserve strict mode.
+- Preserve the strict TypeScript configuration and
-- Do not use `any`. Model unknown external values as `unknown` and narrow or
+  `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
+- Derive types from runtime schemas if the project adopts a schema library.
-  maintain a hand-written type that can drift from its validation schema.
+  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
+- Keep request and response types close to the API or store boundary that
-  them.
+  owns them.
-- Add a path alias only when it is configured consistently in Vite,
+- Keep the `@` alias aligned across Vite, TypeScript, and any future test
-  TypeScript, tests, and Cypress.
+  configuration.
 
 ## State and API access
 
-- Use the state-management approach chosen by the scaffold consistently.
+- Use Pinia for shared client state. Keep component-local state in components.
-- Keep server data fetching and transformation at an API/store boundary, not
+- Keep server requests and response transformation at an API or store
-  scattered through presentation components.
+  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
+- Do not invent test commands or claim frontend tests passed.
-  values, and formatting.
+- New frontend behavior must still follow the shared test-first workflow.
-- Component tests cover rendering, events, form behavior, and conditional UI.
+  Establish the smallest appropriate test setup before implementing behavior
-- Cypress tests cover routing, multi-page flows, and request wiring.
+  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
+- Mock backend requests in frontend tests. Do not retest backend persistence,
-  scaffold deliberately configures globals.
+  validation, authentication, or mail behavior through the frontend.
-- 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.
 
 ## Before completing frontend work
 
-- Run the formatter, linter, type checker, unit tests, and Cypress scripts
+- Run the focused test while developing once test tooling exists.
-  defined by the frontend's `package.json`.
+- Run the formatter, linter, type checker, production build, and every
-- Do not substitute a hand-picked subset for the repository's eventual full
+  configured test script affected by the change.
-  frontend gate.
+- Do not claim a green gate when a command fails. Report a baseline or
-- If the frontend cannot run because the scaffold or a required service is
+  environmental failure precisely.
-  absent, report the precise environmental or baseline failure.

ai/shared.md

@@ -13,8 +13,10 @@ these rules.
   unfinished assignments across the remaining dates.
 - Planned features in `README.md` are future ideas, not authorized scope.
 - The Laravel backend exists under `backend/`.
-- The Vue frontend has not been scaffolded yet. Do not create it unless the
+- The standalone Vue frontend exists under `frontend/website/`.
-  user explicitly asks for that work.
+- Keep the frontend independent from the backend. Do not add backend-driven
+  rendering, asset delivery, or build integration unless the user explicitly
+  asks for it.
 - PostgreSQL is the development and runtime database.
 - PHPUnit uses in-memory SQLite for isolated tests.
 
@@ -62,6 +64,9 @@ those changes with the most relevant parser, formatter, dry run, or check.
 
 - Run backend commands from `backend/`, or explicitly change into it in the
   command.
+- Run frontend commands from `frontend/website/`.
+- `process-compose` does not start the frontend. Start it separately with
+  `npm run dev -- --port "$VITE_PORT"` when needed.
 - When a normally valid check fails because a required service is down,
   surface the environmental failure. Do not skip the check or silently switch
   to a different database or service.
@@ -134,9 +139,12 @@ those changes with the most relevant parser, formatter, dry run, or check.
   direnv exec <worktree> true
   ```
 
-- Never symlink `backend/vendor` or a future frontend's `node_modules` from
+- Never symlink `backend/vendor` or `frontend/website/node_modules` from
-  another checkout. Dependency paths and generated autoloaders must remain
+  another checkout. Dependency paths and generated files must remain
   worktree-local.
+- The shell hook installs backend dependencies but does not install frontend
+  dependencies. Run `npm install` from `frontend/website/` when provisioning a
+  fresh worktree.
 
 Do not push anything. Make commits as the TDD workflow requires.
 
@@ -162,11 +170,19 @@ gate affected by the change.
 
 ### Frontend
 
-- The frontend does not exist yet. Once scaffolded, use the scripts defined in
+- Run these commands from `frontend/website/`:
-  its `package.json` for formatting, linting, type checking, unit tests, and
+
-  end-to-end tests.
+  ```sh
-- Update `ai/frontend-context.md` when the actual scaffold, package manager,
+  npm run format
-  and commands are known.
+  npm run lint
+  npm run type-check
+  npm run build
+  ```
+
+- The formatter and linters rewrite files. Review their changes before
+  committing.
+- No frontend test runner is configured yet. Do not claim unit, component, or
+  end-to-end test coverage until the relevant scripts exist and pass.
 
 ### Environment and integration