# AGENTS
## # SPQ-v2 Core Directive & Roadmap Execution

**System Role:** You are an elite, professional Web Designer and Full-Stack Developer strictly dedicated to the `spq-v2` codebase. You write clean, production-ready React/Vite and PocketBase code. 



**Your Execution Directives:**

1. **Strict Roadmap Adherence:** You must ONLY focus on the objectives outlined in the located at Websites\ShopProQuote.backup-20260626-2058\spq-v2\docs  `shopproquote-evaluation-recommendations.md`  document. Do not invent new features or refactor code outside of the explicit priorities listed in this roadmap.
2. **Task Selection:** Review the roadmap and consult your Think Tank to select the *single most impactful next item* to implement. Start strictly with "Priority 1 — Trust & Professionalism" (e.g., removing developer-facing PocketBase setup banners, generic error messages, and emojis) before moving to subsequent phases.
3. **Implementation:** Execute the code changes for the selected item. Ensure the UI feels like a professional automotive service application, not a generic SaaS template.
4. **Completion Memo (Required):** Once the implementation is successful, you MUST update the `shopproquote-evaluation-recommendations.md` file. Append a new section at the bottom titled `## Execution Memo: [Date] - [Feature Name]`. In this memo, state:
    * What was completed.
    * Which roadmap priority it resolved.
    * A brief note on how the Think Tank evaluated its benefit to the target audience.

**To begin your session:** Output a brief summary of the Think Tank's consensus on the *next immediate task* to tackle from the roadmap, and then proceed with the code implementation.

## Verify Changes
- `npm run build` is the closest thing to typecheck here. It runs `tsc -b && vite build`.
- `npm run test` runs the full Vitest suite.
- Run a focused test with `npx vitest run "src/store/__tests__/quote.test.ts"`.
- `npm run lint` uses `oxlint`. As of now it reports 2 existing warnings in `src/components/ui/Toast.tsx` and `src/pages/Settings.tsx`; do not treat those as new regressions unless you touched them.

## Permissions
-  Do not make drastic changes without confirming with me first - such as deleting a whole settings modal 
-  Do not make any changes to PocketBase without confirming with me and explaning exactly what changes would be made
-  Do not change or reset any type of passwords without my explicit permission - always ask
-  If I am asking you to do something that compromises my home server security please explain and ask for permission


## App Shape
- This is a single Vite + React app, not a monorepo. App entrypoints are `src/main.tsx` and `src/App.tsx`.
- Top-level pages are lazy-loaded in `src/App.tsx`. If you add a new page/route, wire it there.
- Shared app shell is `src/components/Layout.tsx`; settings has special modal/background-route behavior plus preload via `src/lib/routePreload.ts`.

## Runtime / Backend Quirks
- PocketBase is accessed only from the frontend. Central client/auth helpers live in `src/lib/pocketbase.ts`.
- Prefer `useIsLoggedIn()` / `useAuth()` for reactive auth state. Do not read `pb.authStore.isValid` directly in render paths you expect to update live.
- Dev proxy assumptions are in `vite.config.ts`:
  - `/pb` proxies to `http://127.0.0.1:8091`
  - `/deepseek` proxies to `https://localhost`
- `vite.config.ts` excludes `pocketbase` from `optimizeDeps`; do not remove that casually.
-Do not open this file without Explicitly asking for my permission before using this -- PocketBase login info is at /tmp/opencode/pb-admin.txt 

## Data Model Gotchas
- `services` catalog records are consumed by `QuoteGenerator` as flat-price items. Keep `price` populated even when UI adds richer pricing inputs.
- Catalog description fields are inconsistent across the app: `ServiceCatalog` reads `explanation || description`, while quote flows read `explanation`. Preserve compatibility when changing service description writes.
- User-owned PocketBase collections are expected to be scoped by `userId = @request.auth.id` per `pb_migrations/1739999000004_user_scoped_api_rules.js`. Keep new collection fields and queries compatible with that model.
- Quote ↔ RO links are plain text IDs, not PocketBase relation fields, by design. See `pb_migrations/1739999000006_quote_ro_link.js`.

## Shared State / Local Storage
- Quote draft state is persisted in Zustand under the `spq-quote` key in `src/store/quote.ts`. Be careful changing store shape because old local data will be rehydrated.
- Shop defaults belong in `src/lib/settings.ts`. Reuse `loadSettings()` / `saveSettings()` instead of duplicating fallback values in pages.
- Dark mode and some UI preferences also live in localStorage; search before introducing new keys.

## Repair Order Conventions
- RO totals should go through `src/lib/totals.ts`.
- Some RO progress/audit features intentionally avoid PocketBase schema changes:
  - service sub-status lives on the `ROService` JSON shape in `src/types.ts`
  - RO event history is stored in the `financial` JSON blob, not a separate collection

## Tests
- Vitest runs in `jsdom` with setup from `src/test/setup.ts`.
- Existing tests are lightweight unit tests under `src/store/__tests__` and `src/lib/__tests__`; there is no broader integration-test harness or CI config in this repo.