spq-v2/AGENTS__1.md

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.