crewli/dev-docs/MASTER_PROMPT_CURSOR.md

# Crewli — Cursor Master Prompt
# Plak dit BOVEN elke task. Vervang [TASK] onderaan.

## MANDATORY PREAMBLE

Read `@CLAUDE.md` and `@dev-docs/SCHEMA.md` before starting. Use `@workspace`
for full codebase context. These documents are your source of truth.

If modifying existing code, read the current implementation first. Understand
the patterns already in use before writing anything new.

## PROJECT CONTEXT

Crewli — multi-tenant SaaS for event/festival management.

- **Frontend:** Vue 3 + TypeScript + Vuexy 9.5 (Vuetify 3.10) + Pinia +
  TanStack Vue Query + VeeValidate + Zod
- **Two SPAs:**
  - `apps/app/` — Organizer + Platform Admin main app (port 5174)
  - `apps/portal/` — Dual-mode portal (port 5175)
- **API base:** `VITE_API_URL` from `.env.local` (default `http://localhost:8000`)
- **Axios instance:** `src/lib/axios.ts` — this is the ONLY axios instance.
  Never create another. Never import axios directly in components.
- **Backend Enums:** PHP Enums in `api/app/Enums/` define all valid status/type
  values. TypeScript equivalents must mirror these exactly in `src/types/`.

### Frontend file structure (per app)

```
src/
├── lib/axios.ts              # Singleton axios instance (DO NOT DUPLICATE)
├── types/                     # TypeScript interfaces per module
│   └── [module].ts
├── composables/api/           # TanStack Query composables per module
│   └── use[Module].ts
├── stores/                    # Pinia stores (cross-component state only)
│   └── use[Module]Store.ts
├── pages/                     # Page components
│   └── [module]/
│       ├── index.vue          # List view
│       └── [id].vue           # Detail view (or side panel)
└── router/                    # Vue Router config
```

---

## ZERO-COMPROMISE RULES — VIOLATIONS ARE BLOCKERS

### TypeScript & typing

1. **NO `any` TYPES. EVER.** Every variable, prop, emit, return type, ref,
   reactive, computed, and API response is fully typed. If you don't know the
   type, check the backend API Resource in `api/app/Http/Resources/` — that
   defines the contract. Create matching interfaces in `src/types/[module].ts`.

2. **TYPES FIRST.** Before writing any composable or component for a new
   module, create the TypeScript interfaces in `src/types/[module].ts`. These
   mirror the backend API Resource shape. Include:
   - Entity interface (e.g., `Shift`, `Person`, `Event`)
   - Create/Update DTOs (matching backend Form Request fields)
   - Enum-like union types or const objects matching backend PHP Enums
   - Paginated response wrapper if applicable

3. **ENUMS AS CONST OBJECTS.** Mirror backend PHP Enums as TypeScript const
   objects with `as const`, not as loose string unions scattered across files:
   ```typescript
   // src/types/shift.ts
   export const ShiftAssignmentStatus = {
     PENDING_APPROVAL: 'pending_approval',
     APPROVED: 'approved',
     REJECTED: 'rejected',
     CANCELLED: 'cancelled',
     COMPLETED: 'completed',
   } as const
   export type ShiftAssignmentStatus = typeof ShiftAssignmentStatus[keyof typeof ShiftAssignmentStatus]
   ```

### Architecture & patterns

4. **NO DIRECT AXIOS IN COMPONENTS.** All API calls go through composables in
   `composables/api/use[Module].ts` using TanStack Query (`useQuery` /
   `useMutation`). Components never import axios or `src/lib/axios.ts`.
   The composable is the only layer that knows about HTTP.

5. **NO OPTIONS API.** Always `<script setup lang="ts">`. Props via
   `defineProps<{...}>()`, emits via `defineEmits<{...}>()`, expose via
   `defineExpose()`. No `export default { ... }`.

6. **NO PROP DRILLING.** If state needs to cross more than one component
   boundary, use a Pinia store (`src/stores/use[Module]Store.ts`). Access
   reactive state via `storeToRefs()`. Mutations only through store actions.

7. **DELETE OVER ADAPT.** If you find duplicate composables, overlapping
   stores, or conflicting patterns: delete the worse version. Do not build
   alongside existing code that does the same thing. One implementation per
   concern.

8. **CONSISTENCY OVER CLEVERNESS.** Look at how existing modules handle the
   same pattern (table views, form dialogs, detail panels, error handling).
   Use the exact same approach. Never introduce a "better" alternative without
   refactoring ALL existing modules to match.

9. **SINGLE SOURCE OF TRUTH.** Don't duplicate:
   - Validation logic → Zod schema mirrors backend Form Request. One schema
     per form, referenced by VeeValidate.
   - Enum values → const objects in `src/types/`, matching backend Enums.
     Never use raw string literals like `'approved'` in templates or logic.
   - API URLs → constructed in composable from module prefix, never
     hardcoded in components.

### UI & UX

10. **NO CUSTOM CSS WHERE VUETIFY HAS A SOLUTION.** Before writing any CSS:
    check if a Vuetify utility class, component prop, or slot achieves the
    result. Custom CSS is a last resort, must be `<style scoped>`, and must
    have a comment explaining why Vuetify couldn't handle it.

11. **EVERY PAGE HAS THREE STATES:**
    - **Loading:** Vuetify skeleton loader or progress indicator
    - **Error:** User-facing message with retry action (`v-alert` with retry
      button). Show what went wrong in user terms, not technical jargon.
    - **Empty:** Helpful message explaining why the list is empty and what
      action to take (not a blank white screen).
    Never show only the happy path.

12. **MOBILE-FIRST.** Every component must be usable at 375px width. Use
    Vuetify's responsive props (`cols`, `sm`, `md`, `lg` on `v-col`). Never
    use fixed pixel widths for layout. Tables on mobile → card views or
    horizontal scroll with visual indicator.

13. **FORMS USE VEEVALIDATE + ZOD.** Define the Zod schema matching the
    backend Form Request rules. No inline validation logic in templates. Use
    `useForm()` and `useField()` from VeeValidate with the Zod resolver.

### Code quality

14. **NO TODO / FIXME / HACK.** Complete the implementation or report the
    blocker. No stubs, no "implement later", no placeholder components.

15. **NO ORPHANED IMPORTS OR UNUSED VARIABLES.** Run `npx tsc --noEmit`
    after every change. Zero errors, zero warnings. Dead code is deleted
    immediately, not commented out.

16. **NO GENERIC NAMES.** Component and composable names must be specific:
    - ❌ `DataTable.vue`, `useApi.ts`, `helpers.ts`, `utils.ts`
    - ✅ `ShiftAssignmentTable.vue`, `useShifts.ts`,
      `formatShiftTimeRange.ts`

### Routing & auth

17. **ROUTER GUARDS.** Protected routes check auth state via navigation
    guard. Portal routes validate token. No unguarded routes to
    authenticated content. Redirect to login on 401.

### Process

18. **COMPONENT CREATION ORDER.** For every new page/feature:
    1. TypeScript types in `src/types/[module].ts`
    2. API composable in `src/composables/api/use[Module].ts`
    3. Pinia store in `src/stores/use[Module]Store.ts` (if cross-component)
    4. Vue page component in `src/pages/[module]/`
    5. Router entry in `src/router/`

19. **VERIFY BEFORE DONE:**
    - `npx tsc --noEmit` — zero errors
    - No `any` types anywhere (search: `grep -rn ": any\|as any" src/`)
    - No TODO/FIXME/HACK
    - All three states (loading, error, empty) implemented
    - Mobile responsive at 375px
    - Consistent with existing module patterns

---

## TASK

[INSERT SPECIFIC TASK HERE]