add project ai instructions

Document Attainly-specific TDD, worktree, Laravel, database, and future Vue conventions adapted from the youngstartup workflow.

ai/frontend-context.md

@@ -0,0 +1,90 @@
+# Frontend context
+
+Read `ai/shared.md` first. This file covers frontend-specific rules.
+
+## Current state
+
+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.
+
+- 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.
+
+## Vue conventions
+
+Apply these rules once a Vue 3 frontend exists:
+
+- Use the Composition API and `<script setup lang="ts">`.
+- Use PascalCase component filenames.
+- 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.
+
+## TypeScript
+
+- Enable and preserve strict mode.
+- Do not use `any`. Model unknown external values as `unknown` and 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.
+- 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.
+
+## 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.
+- Represent loading, empty, success, validation-error, and unexpected-error
+  states explicitly.
+- Do not cast unchecked JSON directly to an application interface.
+- Keep read and write payload types separate when their shapes differ.
+
+## Testing
+
+Use layered tests once the frontend test setup exists:
+
+- 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.
+- 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.
+
+## 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.