From ff95e2d2eeac410c8f5e60362d3ba458f68ebfb6 Mon Sep 17 00:00:00 2001
From: Yisroel Baum <yisroel.d.baum@gmail.com>
Date: Thu, 30 Jul 2026 23:15:16 +0300
Subject: [PATCH] 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  |   9 ++-
 ai/frontend-context.md | 144 +++++++++++++++++++++++++----------------
 ai/shared.md           |  34 +++++++---
 3 files changed, 118 insertions(+), 69 deletions(-)

diff --git a/ai/backend-context.md b/ai/backend-context.md
index 740118b..3d5dea4 100644
--- a/ai/backend-context.md
+++ b/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.
-  Do not add placeholder frontend assets as part of unrelated backend work.
+- The Vue application is a separate project under `frontend/website/`.
+- 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
 
diff --git a/ai/frontend-context.md b/ai/frontend-context.md
index 7d9dba7..b8a3097 100644
--- a/ai/frontend-context.md
+++ b/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.
diff --git a/ai/shared.md b/ai/shared.md
index 82bf820..860da67 100644
--- a/ai/shared.md
+++ b/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
-  user explicitly asks for that work.
+- The standalone Vue frontend exists under `frontend/website/`.
+- 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
-  another checkout. Dependency paths and generated autoloaders must remain
+- Never symlink `backend/vendor` or `frontend/website/node_modules` from
+  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
-  its `package.json` for formatting, linting, type checking, unit tests, and
-  end-to-end tests.
-- Update `ai/frontend-context.md` when the actual scaffold, package manager,
-  and commands are known.
+- Run these commands from `frontend/website/`:
+
+  ```sh
+  npm run format
+  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