Merge pull request 'fix: strip Aura .p-drawer-content padding in mobile drawer (switcher stays bottom-anchored)' (#29) from fix/mobile-drawer-content-padding into main

Merge PR #29: strip Aura .p-drawer-content padding in mobile drawer

Corrects the mobile drawer spacing: WorkspaceSwitcher stays bottom-anchored
(reverts the PR #28 grow change) and the Aura .p-drawer-content wrapper padding
(~20px sides+bottom) is removed with !p-0 so the block sits edge-to-edge like
the desktop sidebar. Reviewer PASS; 582 frontend tests green; visually
confirmed at 375px.

.claude-sync.conf

@@ -11,3 +11,32 @@ dev-docs/BACKLOG.md
 dev-docs/SECURITY_AUDIT.md
 dev-docs/design-document.md
 dev-docs/UX_SPEC_FESTIVAL_HIERARCHY.md
+dev-docs/ARCH-BINDINGS.md
+dev-docs/ARCH-API-VALIDATION.md
+dev-docs/RFC-WS-7-OBSERVABILITY.md
+dev-docs/GLITCHTIP.md
+dev-docs/ARCH-OBSERVABILITY.md
+dev-docs/ARCH-TESTING.md
+dev-docs/runbooks/observability-triage.md
+dev-docs/runbooks/observability-erasure.md
+dev-docs/RFC-WS-6.md
+dev-docs/RFC-TIMETABLE-Artist-Timetable-Module.md
+dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md
+dev-docs/RFC-WS-PRIMEVUE-PLAN-2-5.md
+dev-docs/MIGRATION-AUDIT-PRIMEVUE.md
+dev-docs/PRIMEVUE_COMPONENTS.md
+dev-docs/RFC-WS-GUI-REDESIGN-CREWLI-STARTER.md
+dev-docs/superpowers/specs/2026-05-15-crewli-starter-gui-redesign-design.md
+# sync script has no glob support — list each new dev-docs/superpowers/plans/*.md here by hand
+dev-docs/superpowers/plans/2026-05-16-gui-redesign-foundation.md
+dev-docs/superpowers/plans/2026-05-17-gui-redesign-tier1-primitives.md
+dev-docs/CLAUDE_CODE_TOOLING.md
+dev-docs/ADR-LEFTHOOK-LFS-INTEGRATION.md
+dev-docs/FRONTEND-TOOLING.md
+dev-docs/LARASTAN.md
+dev-docs/RECTOR.md
+dev-docs/TELESCOPE.md
+dev-docs/WS-3-SESSION-1C-AUDIT.md
+dev-docs/FORM_BUILDER_SCOPE_POLICY.md
+dev-docs/COPY_CATALOGUE.md
+dev-docs/TEST_SCENARIO.md

.claude/.gitignore

@@ -0,0 +1,2 @@
+worktrees/
+.DS_Store

.claude/agents/backend-implementer.md

@@ -0,0 +1,55 @@
+---
+name: backend-implementer
+description: >
+  Implements one bounded Laravel backend subtask from an approved
+  crewli-architect plan: migration, model, factory, policy, form
+  request, API resource, resource controller, route, or Service class.
+  Invoke per-subtask during /build-module Phase 2. Does NOT write
+  frontend code or tests (test-writer handles tests). Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You implement Crewli backend code (PHP 8.2+, Laravel 12). You receive
+ONE bounded subtask from the architect's approved plan. Implement only
+that subtask.
+
+## Non-negotiables (the architect already planned around these; you
+## must not break them)
+
+- HasUlids on business models. NEVER UUID v4. Integer PK only on pure
+  pivots.
+- OrganisationScope global scope on every event-related model. Every
+  query on event data scopes organisation_id.
+- Authorization in Policies. NEVER `$user->role === '...'` in a
+  controller. Check via `$user->can(...)` / policy methods.
+- Business logic lives in a Service class, NOT the controller. The
+  controller orchestrates: authorize -> validate (Form Request) ->
+  delegate to Service -> return API Resource.
+- String constants that represent a fixed set -> PHP Enum (backed),
+  never a string literal.
+- Every state change that matters for audit -> activity-log entry.
+- Queued jobs MUST be idempotent (safe to retry).
+- MySQL 8 syntax only. Index introspection via information_schema,
+  never sqlite_master. FK on every relation column.
+- Byte-stable JSON columns canonicalized via JsonCanonicalizer at
+  write (see CLAUDE.md). Opaque-config JSON is exempt.
+- Delete > adapt: if you replace code, remove the old path. Never
+  leave dead code or duplicate logic.
+
+## Order within your subtask
+Follow the relevant slice of: migration -> model (relationships,
+scopes, HasUlids) -> factory -> policy -> form request -> API resource
+-> controller -> routes in `api.php`. Stop at the boundary the
+architect gave you; do not wander into adjacent subtasks.
+
+## After implementation
+- Run `php artisan test --filter=<RelevantTest>` if tests exist yet.
+- `make schema-dump` + stage `mysql-schema.sql` IF you added a migration.
+- Commit: conventional message, one logical unit, Co-Authored-By:
+  Claude. Do NOT push.
+
+If anything in the subtask forces a deviation from the architect's
+plan (e.g. a missing dependency, a schema mismatch), STOP and report
+it rather than improvising — the plan was human-approved.

.claude/agents/crewli-architect.md

@@ -0,0 +1,104 @@
+---
+name: crewli-architect
+description: >
+  Use PROACTIVELY at the start of any new module, feature, or backlog
+  item that requires implementation. Reads the Gitea issue or task
+  description, performs the SYNC_MANIFEST drift-check, decomposes the
+  work into an ordered task plan respecting the 17-step order-of-work,
+  and produces a DECISION BRIEF for human approval. Does NOT write
+  implementation code — it plans, decomposes, and dispatches.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+You are the architect and orchestrator for Crewli, a multi-tenant
+Laravel 12 + Vue 3 SaaS platform. You do NOT write implementation
+code. Your job is to turn a task into an approved, dispatchable plan.
+
+## Your sequence (never skip a step)
+
+1. DRIFT-CHECK. Read `dev-docs/SYNC_MANIFEST.md` (or the synced copy)
+   for its `git-sha`. Run `git rev-parse --short HEAD` on `main`.
+   - If they differ: STOP. Report both SHAs and the dev-docs that may
+     have changed (`git log <manifest-sha>..HEAD --name-only --
+     dev-docs/`). Output "DRIFT DETECTED — sync required" and halt.
+     Do not plan on stale docs.
+   - If they match: proceed.
+
+2. VERIFY FILESYSTEM STATE. Audit-first, never plan from memory.
+   Before prescribing scaffolding, confirm the actual state of the
+   files you will touch (`ls`, `cat`, `grep`). If docs and code
+   disagree, the code is truth — flag the divergence in the brief.
+
+3. DECOMPOSE. Break the work into atomic subtasks. Each subtask must
+   touch a bounded set of files, have clear inputs/outputs, and be
+   independently verifiable. Map every backend subtask onto the
+   17-step order-of-work in CLAUDE.md (migration -> model -> factory ->
+   policy -> form request -> resource -> controller -> routes -> tests
+   -> types -> composable -> store -> page -> route). Identify the
+   dependency graph: what MUST be sequential, what MAY be parallel.
+
+4. RISK SWEEP against the 7 most-missed gaps (see below). For each
+   subtask, pre-flag where a gap is likely.
+
+5. PRODUCE THE DECISION BRIEF in the exact format below and STOP.
+   Do not dispatch. Wait for human approval.
+
+## The 7 gaps you must pre-flag
+
+1. Business logic that belongs in a Service class, not a controller.
+2. String literals where a PHP Enum is required.
+3. Missing activity-log entry on a state change.
+4. Queued jobs that aren't idempotent.
+5. Duplicate code not removed (Crewli rule: delete > adapt).
+6. Frontend views missing loading / error / empty states.
+7. Stale SPA assumptions (references to `apps/admin` or `apps/portal`
+   — both removed in WS-3; everything lives in `apps/app/`).
+
+## Hard architectural invariants (flag any plan that violates these)
+
+- ULID via HasUlids on business tables; integer auto-increment only on
+  pure pivots. NEVER UUID v4.
+- Every event-data query scopes on organisation_id via OrganisationScope.
+- Authorization via Policies, never raw role-string checks.
+- API responses via API Resources; validation via Form Requests.
+- MySQL 8 only — SQLite is forbidden in every environment.
+- New/migrated frontend surfaces: PrimeVue + Tailwind v4. No new
+  Vuetify. No PrimeVue back-ported into un-migrated surfaces.
+- Soft-delete policy is per-table (SCHEMA.md) — audit records
+  (CheckIn, BriefingSend, MessageReply, ShiftWaitlist) get NONE.
+
+## DECISION BRIEF format (output exactly this structure)
+
+```
+# DECISION BRIEF — <task name>
+
+## Scope
+<2-3 sentences: what this builds, which user-facing behaviour changes>
+
+## Tables & enums touched (per SCHEMA.md)
+- <table> §<section> — <new | modified | read-only>
+- <enum> — values: <...>
+
+## Subtask plan (dependency-ordered)
+| # | Subtask | Agent | Depends on | Parallel-safe? | Files (bounded) |
+|---|---------|-------|------------|----------------|-----------------|
+| 1 | migration: ... | backend-implementer | — | no | ... |
+| 2 | model + policy | backend-implementer | 1 | no | ... |
+| ... |
+
+## Risk flags (7-gap sweep)
+- [gap #N] <subtask>: <specific concern> -> <mitigation>
+- (or "No gap risks identified for subtasks X, Y")
+
+## Open questions for Bert
+- <only genuine judgment calls; empty if none>
+
+## Worktree / branch plan
+- branch: feat/<name> off main
+- parallel worktrees: <list, or "sequential — single worktree">
+
+READY FOR DISPATCH — approve / adjust / reject
+```
+
+After the brief: STOP. Output nothing further until approval arrives.

.claude/agents/crewli-reviewer.md

@@ -0,0 +1,90 @@
+---
+name: crewli-reviewer
+description: Reviews code against Crewli's zero-compromise principles. Use after any backend or frontend implementation is complete, before committing. Returns a structured MUST FIX / SHOULD FIX / CONSIDER report.
+tools: Read, Grep, Glob, Bash
+model: claude-opus-4-7
+---
+
+You are a staff engineer reviewing code for Crewli — a multi-tenant Laravel 12 + Vue 3 SaaS platform with zero tolerance for technical debt.
+
+Read /CLAUDE.md and the relevant /dev-docs/SCHEMA.md sections before reviewing. Do not patch code — produce a structured report only.
+
+## Review checklist (in order)
+
+### Multi-tenancy (highest priority — leaks cross-org data)
+- Every business model has `OrganisationScope` registered in `booted()` (NOT just imported).
+- Every business table FK chain reaches `organisations.id` within ≤2 hops.
+- Every model has a Policy class registered in `AuthServiceProvider`.
+- Public/unscoped query paths explicitly bypass the scope (`->withoutGlobalScope(OrganisationScope::class)`).
+- Pest tests include a cross-org leak assertion: a record from org B must not appear when authenticated as org A.
+
+### Schema & types
+- Primary keys: ULID on business tables, integer auto-increment on pure pivots — NEVER UUID v4.
+- Status/type/category fields use a PHP Enum cast — NEVER string literals.
+- Soft delete decision matches /dev-docs/SCHEMA.md — immutable audit records (check_ins, form_submissions) MUST NOT have softDeletes.
+- JSON columns only for opaque config — never queryable data.
+- Migration follows Laravel 12 anonymous-class style and uses `ulid('id')->primary()`.
+
+### Service & controller layer
+- Business logic lives in `app/Services/<Domain>Service.php` — NEVER in the controller.
+- Controllers are thin: validate (FormRequest), delegate (Service), respond (Resource).
+- Form Request validation rules cover every field, including enum cases.
+- API Resource shapes the response — no raw `$model->toArray()`.
+
+### Activity log
+- Every state-changing model uses the `LogsActivity` trait from spatie/laravel-activitylog.
+- `getActivitylogOptions()` configured (logName, logFillable or logOnly, logOnlyDirty).
+- Suppress logging in seeders/factories via `ActivityLog::suppressed()` where appropriate.
+
+### Queued jobs
+- Jobs implement `ShouldQueue` and are idempotent.
+- Side effects gated by a check (status flag, transient lock) so a re-run is safe.
+- `tries`, `backoff`, `failed()` defined where retry semantics matter.
+
+### Cleanup
+- Old code that the new feature replaces is DELETED, not adapted. No dead code paths, no duplicate implementations.
+
+### Frontend (apps/app or apps/portal)
+- Component first checked against /dev-docs/VUEXY_COMPONENTS.md — Vuexy/Vuetify component used over hand-rolled HTML.
+- Pinia store for shared state, TanStack Vue Query for server state — never raw axios in components.
+- Forms use VeeValidate + Zod; error/empty/loading states explicitly rendered.
+- TypeScript: no `any`. Strict types from API Resource shape.
+
+## The six most-missed gaps (always check explicitly)
+
+1. Business logic in controller instead of Service class.
+2. String literals instead of PHP Enums.
+3. Missing activity log on state-changing models.
+4. Queued jobs not idempotent.
+5. Replaced code not deleted (delete > adapt).
+6. Frontend missing error/empty/loading states.
+
+## Output format
+
+Produce a single Markdown report with three sections:
+
+### MUST FIX (blocking — violates a zero-compromise principle)
+- Bullet list. For each: `path/to/file.php:LINE` — issue — required change.
+
+### SHOULD FIX (non-blocking but clear improvement)
+- Bullet list, same format.
+
+### CONSIDER (judgment call — flagged for Bert)
+- Bullet list, same format.
+
+If the diff is clean: output `No issues found against the zero-compromise principles.` and stop.
+
+Always cite `file:line`. No vague feedback. No prose padding.
+
+## Verdict line (required final output)
+
+After the three sections (MUST FIX / SHOULD FIX / CONSIDER), emit
+exactly one of the following as the LAST line of your output:
+
+- `REVIEW VERDICT: PASS` — no MUST FIX findings remain.
+- `REVIEW VERDICT: BLOCK` — one or more MUST FIX findings remain.
+
+This line is consumed by the /build-module gate automation. It must be
+the literal last line, with no trailing prose, so it can be parsed
+reliably. If the diff is clean, you still emit `REVIEW VERDICT: PASS`
+after your "No issues found" line.

.claude/agents/frontend-implementer.md

@@ -0,0 +1,58 @@
+---
+name: frontend-implementer
+description: >
+  Implements one bounded Vue 3 + TypeScript frontend subtask in
+  apps/app/: types, API composables, Pinia stores, page components,
+  routes. PrimeVue + Tailwind v4 on new/migrated surfaces. Invoke for
+  frontend slices of an approved architect plan, after the backend
+  contract exists. Does NOT write backend code. Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You implement Crewli frontend code in `apps/app/` (the single SPA —
+`apps/admin/` and `apps/portal/` no longer exist; everything is
+route-trees inside `apps/app/`).
+
+## Before any frontend work
+Read `dev-docs/PRIMEVUE_COMPONENTS.md` — authoritative for component
+selection, theming, forms, DataTable conventions.
+
+## Framework rule (migration-aware)
+- New surface or migrated surface -> PrimeVue + Tailwind v4. Component
+  selection order: Tailwind utility -> PrimeVue component ->
+  primevue.org closest match. Customization order: Tailwind -> `pt`
+  API -> Aura preset -> `<style scoped>` (last resort, commented).
+- Un-migrated (legacy) surface -> match surrounding Vuetify/Vuexy; do
+  NOT introduce PrimeVue there (no back-porting).
+- Never put responsive Tailwind visibility classes (e.g. `lg:hidden`)
+  directly on a PrimeVue component — wrap in a plain element;
+  PrimeVue's CSS wins the cascade.
+
+## Non-negotiables
+- `<script setup lang="ts">` always. Props via `defineProps<{...}>()`,
+  emits via `defineEmits<{...}>()`.
+- NO `any`. Ever. Use proper types, generics, or `unknown` + guards.
+- Types first: `src/types/[module].ts` before composables/components.
+  Mirror backend PHP Enums as `as const` objects.
+- ALL API calls via TanStack Query in `composables/api/use[Module].ts`.
+  Never import axios in a component — only `src/lib/axios.ts`.
+- Pinia for cross-component state — no prop drilling.
+- Respect the import-boundary matrix (eslint-plugin-boundaries). If a
+  zone forbids your import, hoist a type to `types/` or a helper to
+  `utils/` — do not disable the rule (per-line disable only with a
+  `TODO TECH-*` backlog reference).
+- EVERY data-driven view handles three states: loading (skeleton),
+  error (Message + retry), empty (helpful message + action).
+- Forms on migrated surfaces: `@primevue/forms` + Zod resolver via
+  `<FormField>`; field names mirror backend Form Request keys
+  (snake_case); 422 errors merge via `useFormError(formRef)`.
+
+## After implementation
+`pnpm test` for affected tests green; eslint clean (the post-edit hook
+auto-fixes, but verify no remaining errors). Commit with a `feat:` /
+`fix:` conventional message, Co-Authored-By: Claude. Do NOT push.
+
+If anything forces a deviation from the architect's approved plan,
+STOP and report it rather than improvising.

.claude/agents/test-writer.md

@@ -0,0 +1,44 @@
+---
+name: test-writer
+description: >
+  Writes PHPUnit feature tests (backend) and Vitest tests (frontend)
+  for subtasks implemented by backend-implementer or
+  frontend-implementer. Invoke after an implementation subtask is
+  committed. Writes tests only — never modifies implementation code to
+  make a test pass (reports the discrepancy instead). Does NOT push.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+isolation: worktree
+---
+
+You write tests for Crewli. You never alter implementation code to
+make a test green — if implementation looks wrong, STOP and report it;
+the architect or implementer owns that fix.
+
+## Backend (PHPUnit feature tests)
+Per controller / endpoint, MINIMUM three cases:
+- happy path (200/201, correct API Resource shape)
+- unauthenticated -> 401
+- wrong organisation -> 403 (multi-tenancy isolation — this is the
+  test that proves OrganisationScope works; never skip it)
+
+Use factories for ALL test data. Assert on the documented API contract
+(SCHEMA.md / API.md), not on whatever the implementation currently
+emits. For canonicalized-JSON data, assert via
+`assertSame(JsonCanonicalizer::encode($a), JsonCanonicalizer::encode($b))`.
+MySQL test DB only (`--env=testing`), never SQLite.
+
+## Frontend (Vitest)
+Pick the tier per ARCH-TESTING.md's decision tree (Unit / Component /
+Integration / Visual / E2E) — don't default everything to Unit. Cover
+the three mandatory view states where applicable: loading, error,
+empty.
+
+## After writing
+Run the relevant suite (`php artisan test --filter=...` or
+`pnpm test`). All green before you commit. Commit with a `test:`
+conventional message, Co-Authored-By: Claude. Do NOT push.
+
+If a test you wrote correctly (against the documented contract) fails
+because the implementation diverges from the contract: that is a
+finding, not a test bug. Report it; do not weaken the test.

.claude/commands/build-module.md

@@ -0,0 +1,72 @@
+---
+description: >
+  Orchestrate a full module build from an approved decision brief:
+  dispatch backend/frontend/test subagents per the plan, run the
+  reviewer gate, and assemble the PR merge-gate. Stops at the two
+  human gates (decomposition approval, merge).
+argument-hint: <task-name-or-gitea-issue-#>
+allowed-tools: Read, Grep, Glob, Bash, Agent, Edit, Write
+---
+
+Orchestrate the build for: $ARGUMENTS
+
+You are the orchestrator running in the MAIN session (subagents cannot
+spawn subagents, so the sequencing logic lives here, not in an agent).
+You dispatch the specialist subagents via the Agent tool.
+
+## Phase 0 — Branch
+Confirm a clean working tree first (`git status`). Create `feat/<task>`
+off `main`. Branch creation is ALWAYS Phase 0 (Crewli prompt
+discipline — never operate on `main` directly).
+
+## Phase 1 — Architect (HUMAN GATE 1)
+Dispatch the crewli-architect subagent on $ARGUMENTS. It will
+drift-check, audit filesystem state, decompose, and emit a DECISION
+BRIEF ending in `READY FOR DISPATCH`.
+-> STOP. Present the brief verbatim. Wait for the human to reply
+   `approve` / `adjust` / `reject`. Do NOT proceed without explicit
+   approval. If `adjust`, relay the changes back to the architect and
+   re-present. If `reject`, halt.
+
+## Phase 2 — Dispatch (after approval only)
+Walk the approved subtask table in dependency order:
+- Sequential subtasks: dispatch the assigned implementer subagent,
+  wait, verify the commit landed (`git log -1`), then proceed.
+- Parallel-safe subtasks: dispatch as background subagents. The
+  implementer agents carry `isolation: worktree`, so parallel-safe
+  subtasks are file-isolated automatically — no manual worktree
+  juggling. Merge each worktree branch back as it completes.
+After each backend/frontend subtask commits, dispatch test-writer for
+its tests BEFORE moving to the next dependent subtask.
+
+If any implementer or test-writer STOPS and reports a deviation from
+the approved plan, surface it to the human — do not improvise a fix
+around an approved decomposition.
+
+## Phase 3 — Review gate
+Dispatch crewli-reviewer on the changes since the branch point.
+Read its final `REVIEW VERDICT:` line.
+- `BLOCK` -> route the MUST FIX findings back to the relevant
+  implementer subagent, re-run, re-review. Loop until PASS. The human
+  is NOT bothered during this loop.
+- `PASS` -> proceed to Phase 4.
+
+## Phase 4 — Assemble merge gate (HUMAN GATE 2)
+Fill `.claude/templates/pr-merge-gate.md` with REAL signals: test
+counts, the reviewer verdict, Larastan result, the multi-tenancy 403
+test status, the Gitea compare URL, the commit table, and the merge
+commit message. Verify EVERY gate signal is green. If ANY signal is
+red, return to Phase 2/3 — never present a red gate to the human.
+-> Present the completed merge gate. Wait for the human to reply
+   `merge`. (You do NOT execute the merge or any push — the human
+   performs the `--no-ff` merge into local main at their discretion.)
+
+## Phase 5 — Post-merge reminders (after the human confirms merge)
+- If dev-docs changed: remind to run `/sync-docs` and re-upload
+  `.claude-sync/` (including SYNC_MANIFEST.md) to Project Knowledge.
+  Without the upload, the next drift-check is blind.
+- Delete the feature branch locally and remotely ONLY after confirming
+  the merge actually landed on `main` (`git log main --oneline | grep`
+  the merge). This is the pre-merge verification gate — the D1
+  near-miss rule. Never delete a branch whose merge you haven't
+  verified.

.claude/commands/review-multitenancy.md

@@ -0,0 +1,26 @@
+---
+description: Check a model + migration + policy + tests for multi-tenancy correctness
+argument-hint: [model-name]
+allowed-tools: Read, Grep, Glob
+---
+
+Target: $ARGUMENTS
+
+Locate and read all four artefacts:
+1. The Eloquent model — `app/Models/$ARGUMENTS.php` (or matching path under `app/Models/`).
+2. The most recent migration that creates or modifies the table.
+3. The policy class — `app/Policies/${ARGUMENTS}Policy.php`.
+4. Pest tests for the model — search `tests/` for the class name.
+
+Verify each item against /dev-docs/SCHEMA.md and /CLAUDE.md, marking PASS / FAIL / N/A with one-line reasoning:
+
+- [ ] Primary key is ULID (`ulid('id')->primary()` in migration; `HasUlids` trait on model)
+- [ ] `OrganisationScope` registered in model `booted()` (NOT merely imported)
+- [ ] FK chain reaches `organisations.id` within ≤2 hops
+- [ ] Policy class exists and is registered in `AuthServiceProvider::$policies`
+- [ ] All status/type/category columns use a PHP Enum cast
+- [ ] Soft delete decision matches the type's row in /dev-docs/SCHEMA.md
+- [ ] Pest tests include a cross-org leak assertion
+- [ ] Activity log trait present (if state-changing)
+
+End with a verdict line: `READY` or `NEEDS WORK`.

.claude/commands/sprint-status.md

@@ -0,0 +1,15 @@
+---
+description: Summarise current sprint position from BACKLOG.md, recent commits, and working tree
+allowed-tools: Bash(git:*), Read
+---
+
+Read the first 50 lines of `dev-docs/BACKLOG.md`.
+Run `git branch --show-current`, `git log --oneline -20`, and `git status -sb`.
+
+Produce a 5–10 line summary covering:
+- Current branch and the work package it belongs to
+- Last completed work package (most recent --no-ff merge in the log)
+- Staged or unstaged work (uncommitted changes)
+- Next item per BACKLOG.md
+
+No prose padding. Just the facts.

.claude/commands/sync-docs.md

@@ -0,0 +1,11 @@
+---
+description: Run the dev-docs sync pipeline and remind to upload .claude-sync/
+allowed-tools: Bash(npm:*), Read
+---
+
+Run `npm run sync:docs`.
+After it completes, read `.claude-sync/SYNC_MANIFEST.md` and print the `Git SHA` and `Generated` lines.
+
+End with this exact warning block:
+
+> ⚠️ Manual step required: upload `.claude-sync/` (including `SYNC_MANIFEST.md`) to Project Knowledge in Claude Chat. The drift-check protocol depends on this. Without upload the sync is stale and Claude Chat will work from outdated dev-docs.

.claude/hooks/block-dangerous-bash.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+cmd="$(echo "$input" | jq -r '.tool_input.command // empty')"
+
+[ -z "$cmd" ] && exit 0
+
+block() {
+  echo "Bash command blocked: $1. $2." >&2
+  exit 2
+}
+
+# git reset --hard
+if echo "$cmd" | grep -Eq 'git[[:space:]]+reset[[:space:]]+--hard'; then
+  block "git reset --hard destroys local work" "Use 'git stash' to set work aside, or branch off the current state before resetting"
+fi
+
+# git push --force / -f
+if echo "$cmd" | grep -Eq 'git[[:space:]]+push[[:space:]]+(--force([[:space:]]|=|$)|-f([[:space:]]|$))'; then
+  block "force push rewrites history" "Crewli uses --no-ff merges; never force-push. If the remote diverged, pull/rebase locally and resolve"
+fi
+
+# rm -rf on absolute paths outside /tmp and /home/<user>/
+if echo "$cmd" | grep -Eq '\brm[[:space:]]+-rf?[[:space:]]+/' && ! echo "$cmd" | grep -Eq '\brm[[:space:]]+-rf?[[:space:]]+/(tmp|var/folders|home/[^/[:space:]]+/[^[:space:]]|Users/[^/[:space:]]+/[^[:space:]])'; then
+  block "rm -rf on an absolute path outside /tmp" "Verify the path is project-relative; if you really need it, run it manually outside Claude Code"
+fi
+
+# php artisan migrate:fresh — only with --env=testing
+if echo "$cmd" | grep -Eq 'php[[:space:]]+artisan[[:space:]]+migrate:fresh\b'; then
+  if ! echo "$cmd" | grep -Eq -- '--env=testing\b'; then
+    block "migrate:fresh wipes the database" "Add --env=testing to scope this to the test database, or run a non-destructive 'migrate' / 'migrate:rollback'"
+  fi
+fi
+
+# php artisan db:wipe — only with --env=testing
+if echo "$cmd" | grep -Eq 'php[[:space:]]+artisan[[:space:]]+db:wipe\b'; then
+  if ! echo "$cmd" | grep -Eq -- '--env=testing\b'; then
+    block "db:wipe destroys the database" "Add --env=testing to scope this to the test database"
+  fi
+fi
+
+# composer/pnpm/npm update
+if echo "$cmd" | grep -Eq '\b(composer|pnpm|npm)[[:space:]]+update\b'; then
+  block "blanket dependency update bumps everything without review" "Use targeted 'composer require <pkg>' or 'pnpm add <pkg>' to bump one package at a time"
+fi
+
+exit 0

.claude/hooks/inject-sprint-context.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$CLAUDE_PROJECT_DIR" 2>/dev/null || exit 0
+
+branch="$(git branch --show-current 2>/dev/null || echo unknown)"
+recent="$(git log --oneline -10 2>/dev/null || echo '(git log unavailable)')"
+
+backlog_excerpt="(BACKLOG.md not found)"
+if [ -f dev-docs/BACKLOG.md ]; then
+  # First 40 lines, capped at ~3500 chars to stay well under 600 tokens for the whole output.
+  backlog_excerpt="$(head -n 40 dev-docs/BACKLOG.md | head -c 3500)"
+fi
+
+cat <<EOF
+## Sprint context (re-injected after compaction)
+
+**Branch:** $branch
+
+**Last 10 commits:**
+$recent
+
+**Top of BACKLOG.md:**
+$backlog_excerpt
+
+Reminder: re-read /CLAUDE.md if any zero-compromise principle is unclear. /dev-docs/SCHEMA.md is authoritative for table structure.
+EOF
+
+exit 0

.claude/hooks/post-edit-eslint.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+path="$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty')"
+
+[ -z "$path" ] && exit 0
+
+# Strip leading absolute prefix if present, so we match repo-relative paths.
+rel="$path"
+if [[ "$path" = /* ]]; then
+  rel="${path#$CLAUDE_PROJECT_DIR/}"
+fi
+
+# Match apps/app/** for .vue/.ts/.tsx/.js files.
+if ! echo "$rel" | grep -Eq '^apps/app/.+\.(vue|ts|tsx|js)$'; then
+  exit 0
+fi
+
+# Path inside apps/app/.
+inside="${rel#apps/app/}"
+
+cd "$CLAUDE_PROJECT_DIR/apps/app" 2>/dev/null || exit 0
+pnpm eslint --fix "$inside" >/dev/null 2>&1 || true
+exit 0

.claude/hooks/post-edit-pint.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+path="$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty')"
+
+# No path or non-PHP — nothing to do.
+[ -z "$path" ] && exit 0
+[[ "$path" != *.php ]] && exit 0
+
+# Laravel app lives in api/. Pint binary is at api/vendor/bin/pint.
+cd "$CLAUDE_PROJECT_DIR/api" 2>/dev/null || exit 0
+[ -x vendor/bin/pint ] || exit 0
+
+# --dirty only formats files with git changes — fast even when called per-edit.
+vendor/bin/pint --dirty >/dev/null 2>&1 || true
+exit 0

.claude/hooks/protect-files.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+input="$(cat)"
+path="$(echo "$input" | jq -r '.tool_input.file_path // .tool_input.path // empty')"
+
+[ -z "$path" ] && exit 0
+
+block() {
+  echo "Edit to '$path' blocked: $1. $2." >&2
+  exit 2
+}
+
+# .env files (but not .env.example)
+if echo "$path" | grep -Eq '(^|/)\.env(\..*)?$' && ! echo "$path" | grep -Eq '(^|/)\.env\.example$'; then
+  block "secrets" "Propose changes to .env.example instead"
+fi
+
+# composer.lock
+if echo "$path" | grep -Eq '(^|/)composer\.lock$'; then
+  block "locked dependency tree" "Run composer require deliberately, then commit the regenerated lock file"
+fi
+
+# JS lock files
+if echo "$path" | grep -Eq '(^|/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$'; then
+  block "locked JS dependency tree" "Run pnpm add / npm install deliberately, then commit the regenerated lock file"
+fi
+
+# Laravel default migrations
+if echo "$path" | grep -Eq '(^|/)database/migrations/0001_01_01_.*\.php$'; then
+  block "Laravel default migration" "Never modify Laravel scaffold migrations — write a new migration that alters the table"
+fi
+
+# apps/admin/ — deleted SPA per WS-3
+if echo "$path" | grep -Eq '(^|/)apps/admin/'; then
+  block "apps/admin/ was deleted in WS-3 and must not return" "Use apps/app/ (Organizer SPA, includes Platform Admin under /platform/*)"
+fi
+
+# .claude/ tooling self-modification (allow ephemeral agent worktrees under .claude/worktrees/)
+if echo "$path" | grep -Eq '(^|/)\.claude/' && ! echo "$path" | grep -Eq '(^|/)\.claude/worktrees/'; then
+  block "tooling self-modification — Bert reviews .claude/ changes by hand" "Open the file in an editor outside Claude Code, or ask Bert to authorize the change explicitly"
+fi
+
+# dev-docs/SCHEMA.md
+if echo "$path" | grep -Eq '(^|/)dev-docs/SCHEMA\.md$'; then
+  block "SCHEMA.md is updated only at sprint milestones" "Bert decides when SCHEMA snapshots roll forward — do not edit ad hoc"
+fi
+
+exit 0

.claude/settings.json

@@ -0,0 +1,74 @@
+{
+   "permissions": {
+     "allow": [
+      "Edit",
+      "Write",
+      "Bash(php artisan test:*)",
+      "Bash(php artisan migrate:*)",
+      "Bash(./vendor/bin/pint:*)",
+      "Bash(composer analyse)",
+      "Bash(composer rector)",
+      "Bash(pnpm test:*)",
+      "Bash(pnpm eslint:*)",
+      "Bash(make schema-dump)",
+      "Bash(make test:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git status)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git checkout:*)",
+      "Bash(git branch:*)",
+      "Bash(git worktree:*)",
+      "Bash(git rev-parse:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-bash.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-pint.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-eslint.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-sprint-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/templates/pr-merge-gate.md

@@ -0,0 +1,35 @@
+# PR MERGE GATE — <task name>
+
+## Gate signals (ALL must be ✅ before merge is offered)
+- [ ] crewli-reviewer: `REVIEW VERDICT: PASS` (no MUST FIX)
+- [ ] Backend tests green — `php artisan test` (<N> passing)
+- [ ] Frontend tests green — `pnpm test` (<N> passing)
+- [ ] pint clean / eslint clean (post-edit hooks + final pass)
+- [ ] Larastan: no new errors beyond baseline (`composer analyse`)
+- [ ] Multi-tenancy isolation test present & green (403 wrong-org)
+- [ ] No `apps/admin` / `apps/portal` references introduced
+- [ ] Docs updated where user-facing behaviour changed (or N/A)
+- [ ] SCHEMA.md / API.md / BACKLOG.md updated if needed (or N/A)
+
+## SHOULD FIX / CONSIDER (non-blocking — Bert's call)
+<reviewer's non-blocking findings, or "none">
+
+## PR delivery (Crewli standard)
+- Gitea compare URL: <url>
+- PR title: <conventional-commit-style title>
+- Commit table:
+
+  | SHA | Type | Summary |
+  |-----|------|---------|
+  |     |      |         |
+
+- Merge commit message: <--no-ff merge message>
+
+## Decision
+All gate signals green -> reply `merge`. You (Bert) perform the
+`--no-ff` merge into local main and push at your discretion. The
+agents do not merge or push.
+
+Any red signal -> this PR should NOT have reached you; the orchestrator
+returns it to the implementer. (Bert never merges a red PR — the gate
+enforces it.)

.cursor/ARCHITECTURE.md

@@ -1,436 +0,0 @@
-# Crewli - Architecture
-
-> Multi-tenant SaaS platform for event- and festival management.
-> Source of truth: `/resources/design/design-document.md`
-
-## System Overview
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                              INTERNET                                   │
-└─────────────────────────────────────────────────────────────────────────┘
-                                    │
-                    ┌───────────────┼───────────────┐
-                    │                               │
-                    ▼                               ▼
-            ┌───────────────┐               ┌───────────────┐
-            │  Organizer +  │               │  Portal SPA   │
-            │  Admin SPA    │               │  (External)   │
-            │  :5174        │               │  :5175        │
-            └───────┬───────┘               └───────┬───────┘
-                    │                               │
-                    └───────────────┼───────────────┘
-                                    │ CORS + Sanctum tokens
-                                    ▼
-                        ┌───────────────────────┐
-                        │   Laravel 12 REST API │
-                        │   (JSON only, no      │
-                        │    Blade views)        │
-                        │   :8000               │
-                        └───────────┬───────────┘
-                                    │
-                    ┌───────────────┼───────────────┐
-                    │               │               │
-                    ▼               ▼               ▼
-            ┌───────────┐   ┌───────────┐   ┌───────────┐
-            │   MySQL 8 │   │   Redis   │   │  Mailpit  │
-            │   :3306   │   │   :6379   │   │   :8025   │
-            └───────────┘   └───────────┘   └───────────┘
-```
-
-**Golden Rule:** Laravel is exclusively a JSON REST API. No Blade views, no Mix, no Inertia. Every response is `application/json`. Vue handles ALL UI via two SPAs.
-
----
-
-## Applications
-
-### Organizer App (`apps/app/`)
-
-**Purpose**: Main application for event management per organisation. Also serves as the platform admin interface for `super_admin` users via `/platform/*` routes.
-
-**Users**: Organisation Admins, Event Managers, Staff Coordinators, Artist Managers, Volunteer Coordinators, Super Admins (platform management via `/platform/*`).
-
-**Features**:
-- Event lifecycle management (Draft through Closed)
-- Festival Sections, Time Slots, Shift planning
-- Person & Crowd management (Crew, Volunteers, Artists, Guests, Press, Partners, Suppliers)
-- Accreditation engine (categories, items, access zones)
-- Artist booking & advancing
-- Timetable & stage management
-- Briefing builder & communication hub
-- Mission Control (show day operations)
-- Form builder with conditional logic
-- Supplier & production management
-- Reporting & insights
-- Platform admin: organisation management, billing, platform users (`/platform/*` routes, `super_admin` only)
-
-**Vuexy Version**: `typescript-version/full-version` (customized navigation)
-
----
-
-### Portal (`apps/portal/`)
-
-**Purpose**: External-facing portal with two access modes.
-
-**Users**: Volunteers, Crew (login-based), Artists, Suppliers, Press (token-based).
-
-**Access Modes**:
-
-| User | Access Mode | Rationale |
-|------|-------------|-----------|
-| Volunteer / Crew | Login (`auth:sanctum`) | Long-term relationship, festival passport, shift history |
-| Artist / Tour Manager | Token (`portal.token` middleware) | Per-event, advance portal via signed URL |
-| Supplier / Partner | Token (`portal.token` middleware) | Per-event, production request via token |
-| Press / Media | Token (`portal.token` middleware) | Per-event accreditation, no recurring relationship |
-
-**Router guard logic**: If `route.query.token` -> token mode. If `authStore.isAuthenticated` -> login mode. Otherwise -> redirect to `/login`.
-
-**Vuexy Version**: `typescript-version/starter-kit` (stripped: no sidebar, no customizer, no dark mode toggle; uses Vuetify components + Vuexy SCSS)
-
----
-
-## Multi-Tenant Data Model
-
-Shared database schema with organisation scoping on all tables. No row-level security at DB level; scoping enforced via Laravel Policies and Eloquent Global Scopes.
-
-**Scoping Rule**: EVERY query on event data MUST have an `organisation_id` scope via `OrganisationScope` Global Scope.
-
-**Tenancy Hierarchy**:
-
-```
-Platform (Super Admin)
-  └─ Organisation (client A)
-       └─ Event (event 1)
-            └─ Festival Section (Bar, Hospitality, Technical, ...)
-                 ├─ Time Slots (DAY1-EARLY-CREW, DAY1-EARLY-VOLUNTEER, ...)
-                 └─ Shifts (Bar x DAY1-EARLY-VOLUNTEER, 5 slots)
-```
-
----
-
-## Three-Level Role & Permission Model
-
-Managed via Spatie `laravel-permission` with team-based permissions.
-
-| Level | Scope | Roles | Implementation |
-|-------|-------|-------|----------------|
-| App Level | Whole platform | `super_admin`, `support_agent` | Spatie role |
-| Organisation Level | Within one org | `org_admin`, `org_member`, `org_readonly` | Spatie team = organisation |
-| Event Level | Within one event | `event_manager`, `artist_manager`, `staff_coordinator`, `volunteer_coordinator`, `accreditation_officer` | `event_user_roles` pivot table |
-
-**Middleware**: `OrganisationRoleMiddleware` and `EventRoleMiddleware` check per route.
-
----
-
-## Event Lifecycle
-
-| Phase | Description |
-|-------|-------------|
-| `draft` | Created but not published. Only admin sees it. |
-| `published` | Active in planning. Internal modules available. External portals closed. |
-| `registration_open` | Volunteer registration and artist advance portals open. |
-| `buildup` | Setup days. Crew shifts begin. Accreditation distribution starts. |
-| `showday` | Active event days. Mission Control active. Real-time check-in. |
-| `teardown` | Breakdown days. Inventory return. Shift closure. |
-| `closed` | Event completed. Read-only. Reports available. |
-
----
-
-## API Structure
-
-### Base URL
-- Development: `http://localhost:8000/api/v1`
-
-### Route Groups
-
-```
-# Public (no auth)
-POST   /auth/login
-POST   /portal/token-auth              Token-based portal access
-POST   /portal/form-submit             Public form submission
-
-# Protected (auth:sanctum)
-POST   /auth/logout
-GET    /auth/me                        Returns user + organisations + event roles
-
-# Organisations
-GET/POST   /organisations
-GET/PUT    /organisations/{id}
-POST       /organisations/{id}/invite
-GET        /organisations/{id}/members
-
-# Events (nested under organisations)
-GET/POST   /organisations/{org}/events
-GET/PUT/DELETE /events/{id}
-PUT        /events/{id}/status
-
-# Festival Sections
-GET/POST   /events/{event}/sections
-GET/PUT/DELETE /sections/{id}
-GET        /sections/{id}/dashboard
-
-# Time Slots
-GET/POST   /events/{event}/time-slots
-PUT/DELETE /time-slots/{id}
-
-# Shifts
-GET/POST   /sections/{section}/shifts
-PUT/DELETE /shifts/{id}
-POST       /shifts/{id}/assign
-POST       /shifts/{id}/claim           Volunteer self-service
-
-# Persons
-GET/POST   /events/{event}/persons
-GET/PUT    /persons/{id}
-POST       /persons/{id}/approve
-POST       /persons/{id}/checkin
-
-# Crowd Types & Lists
-GET/POST   /organisations/{org}/crowd-types
-GET/POST   /events/{event}/crowd-lists
-
-# Artists & Advancing
-GET/POST   /events/{event}/artists
-GET/PUT    /artists/{id}
-GET/POST   /artists/{id}/sections       Advance sections
-POST       /sections/{id}/submit        Advance submission
-
-# Accreditation
-GET/POST   /events/{event}/accreditation-items
-POST       /persons/{id}/accreditations
-GET/POST   /events/{event}/access-zones
-
-# Briefings & Communication
-GET/POST   /events/{event}/briefings
-POST       /briefings/{id}/send
-GET/POST   /events/{event}/campaigns
-POST       /campaigns/{id}/send
-
-# Mission Control
-GET        /events/{event}/mission-control
-POST       /persons/{id}/checkin-item
-
-# Scanners & Inventory
-GET/POST   /events/{event}/scanners
-POST       /scan
-GET/POST   /events/{event}/inventory
-
-# Reports
-GET        /events/{event}/reports/{type}
-
-# Portal (token-based, portal.token middleware)
-GET        /portal/artist
-POST       /portal/advancing
-GET        /portal/supplier
-POST       /portal/production-request
-```
-
-### API Response Format
-
-```json
-{
-  "data": { ... },
-  "meta": {
-    "pagination": {
-      "current_page": 1,
-      "per_page": 15,
-      "total": 100,
-      "last_page": 7
-    }
-  }
-}
-```
-
----
-
-## Core Database Schema
-
-**Primary Keys**: ULID on all business tables via `HasUlids` trait. Pure pivot tables use auto-increment integer PK.
-
-**Soft Deletes ON**: organisations, events, festival_sections, shifts, shift_assignments, persons, artists, companies, production_requests.
-
-**Soft Deletes OFF** (audit records): check_ins, briefing_sends, message_replies, shift_waitlist, volunteer_festival_history.
-
-**JSON Columns**: ONLY for opaque config (blocks, fields, settings, items). NEVER for dates, status values, foreign keys, booleans, or anything filtered/sorted/aggregated.
-
-### 1. Foundation
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `users` | id (ULID), name, email, password, timezone, locale, avatar, deleted_at | Platform-wide, unique per email. |
-| `organisations` | id (ULID), name, slug, billing_status, settings (JSON: display prefs only), deleted_at | hasMany events, crowd_types. |
-| `organisation_user` | id (int AI), user_id, organisation_id, role | Pivot. Integer PK. |
-| `user_invitations` | id (ULID), email, invited_by_user_id, organisation_id, event_id (nullable), role, token (ULID unique), status, expires_at | INDEX: (token), (email, status). |
-| `events` | id (ULID), organisation_id, name, slug, start_date, end_date, timezone, status (enum), deleted_at | INDEX: (organisation_id, status). |
-| `event_user_roles` | id (int AI), user_id, event_id, role | Pivot. Integer PK. |
-
-### 2. Locations
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `locations` | id (ULID), event_id, name, address, lat, lng, description, access_instructions | INDEX: (event_id). |
-
-### 3. Festival Sections, Time Slots & Shifts
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `festival_sections` | id (ULID), event_id, name, sort_order, deleted_at | INDEX: (event_id, sort_order). |
-| `time_slots` | id (ULID), event_id, name, person_type (CREW/VOLUNTEER/PRESS/...), date, start_time, end_time | INDEX: (event_id, person_type, date). |
-| `shifts` | id (ULID), festival_section_id, time_slot_id, location_id, slots_total, slots_open_for_claiming, status, deleted_at | INDEX: (festival_section_id, time_slot_id). |
-| `shift_assignments` | id (ULID), shift_id, person_id, time_slot_id (denormalized), status (pending_approval/approved/rejected/cancelled/completed), auto_approved, deleted_at | UNIQUE(person_id, time_slot_id). |
-| `volunteer_availabilities` | id (ULID), person_id, time_slot_id, submitted_at | UNIQUE(person_id, time_slot_id). |
-| `shift_waitlist` | id (ULID), shift_id, person_id, position, added_at | UNIQUE(shift_id, person_id). |
-| `shift_swap_requests` | id (ULID), from_assignment_id, to_person_id, status, auto_approved | |
-| `shift_absences` | id (ULID), shift_assignment_id, person_id, reason, status | |
-
-### 4. Volunteer Profile & History
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `volunteer_profiles` | id (ULID), user_id (unique), bio, tshirt_size, first_aid, driving_licence, reliability_score (0.00-5.00) | Platform-wide, 1:1 with users. |
-| `volunteer_festival_history` | id (ULID), user_id, event_id, hours_planned, hours_completed, no_show_count, coordinator_rating, would_reinvite | UNIQUE(user_id, event_id). Never visible to volunteer. |
-| `post_festival_evaluations` | id (ULID), event_id, person_id, overall_rating, would_return, feedback_text | |
-| `festival_retrospectives` | id (ULID), event_id (unique), KPI columns, top_feedback (JSON) | |
-
-### 5. Crowd Types, Persons & Crowd Lists
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `crowd_types` | id (ULID), organisation_id, name, system_type (CREW/GUEST/ARTIST/VOLUNTEER/PRESS/PARTNER/SUPPLIER), color, icon | Org-level config. |
-| `persons` | id (ULID), user_id (nullable), event_id, crowd_type_id, company_id (nullable), name, email, phone, status, is_blacklisted, custom_fields (JSON), deleted_at | user_id nullable for externals. UNIQUE(event_id, user_id) WHERE user_id IS NOT NULL. |
-| `companies` | id (ULID), organisation_id, name, type, contact_*, deleted_at | Shared across events within org. |
-| `crowd_lists` | id (ULID), event_id, crowd_type_id, name, type (internal/external), auto_approve, max_persons | |
-| `crowd_list_persons` | id (int AI), crowd_list_id, person_id | Pivot. |
-
-### 6. Accreditation Engine
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `accreditation_categories` | id (ULID), organisation_id, name, sort_order, icon | Org-level. |
-| `accreditation_items` | id (ULID), accreditation_category_id, name, is_date_dependent, barcode_type, cost_price | Org-level items. |
-| `event_accreditation_items` | id (ULID), event_id, accreditation_item_id, max_quantity_per_person, is_active | Activates item per event. UNIQUE(event_id, accreditation_item_id). |
-| `accreditation_assignments` | id (ULID), person_id, accreditation_item_id, event_id, date, quantity, is_handed_out | |
-| `access_zones` | id (ULID), event_id, name, zone_code (unique per event) | |
-| `access_zone_days` | id (int AI), access_zone_id, day_date | UNIQUE(access_zone_id, day_date). |
-| `person_access_zones` | id (int AI), person_id, access_zone_id, valid_from, valid_to | |
-
-### 7. Artists & Advancing
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `artists` | id (ULID), event_id, name, booking_status (concept/requested/option/confirmed/contracted/cancelled), portal_token (ULID unique), deleted_at | |
-| `performances` | id (ULID), artist_id, stage_id, date, start_time, end_time, check_in_status | INDEX: (stage_id, date, start_time). |
-| `stages` | id (ULID), event_id, name, color, capacity | |
-| `stage_days` | id (int AI), stage_id, day_date | UNIQUE(stage_id, day_date). |
-| `advance_sections` | id (ULID), artist_id, name, type, is_open, sort_order | |
-| `advance_submissions` | id (ULID), advance_section_id, data (JSON), status | |
-| `artist_contacts` | id (ULID), artist_id, name, email, role | |
-| `artist_riders` | id (ULID), artist_id, category (technical/hospitality), items (JSON) | |
-
-### 8. Communication & Briefings
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `briefing_templates` | id (ULID), event_id, name, type, blocks (JSON) | |
-| `briefings` | id (ULID), event_id, briefing_template_id, name, target_crowd_types (JSON), status | |
-| `briefing_sends` | id (ULID), briefing_id, person_id, status (queued/sent/opened/downloaded) | NO soft delete. |
-| `communication_campaigns` | id (ULID), event_id, type (email/sms/whatsapp), status | |
-| `messages` | id (ULID), event_id, sender_user_id, recipient_person_id, urgency (normal/urgent/emergency) | |
-| `broadcast_messages` | id (ULID), event_id, sender_user_id, body, urgency | |
-
-### 9. Forms, Check-In & Operational
-
-| Table | Key Columns | Notes |
-|-------|-------------|-------|
-| `public_forms` | id (ULID), event_id, crowd_type_id, fields (JSON), conditional_logic (JSON), iframe_token | |
-| `form_submissions` | id (ULID), public_form_id, person_id, data (JSON) | |
-| `check_ins` | id (ULID), event_id, person_id, scanned_by_user_id, scanned_at | NO soft delete. Immutable audit record. |
-| `scanners` | id (ULID), event_id, name, type, pairing_code | |
-| `inventory_items` | id (ULID), event_id, name, item_code, assigned_to_person_id | |
-| `production_requests` | id (ULID), event_id, company_id, title, status, token (ULID unique) | |
-| `material_requests` | id (ULID), production_request_id, category, name, quantity, status | |
-
----
-
-## Model Relationships
-
-**User**
-- belongsToMany Organisations (via `organisation_user`)
-- belongsToMany Events (via `event_user_roles`)
-
-**Organisation**
-- hasMany Events
-- hasMany CrowdTypes
-- hasMany AccreditationCategories
-- hasMany Companies
-- belongsToMany Users (via `organisation_user`)
-
-**Event**
-- belongsTo Organisation
-- hasMany FestivalSections
-- hasMany TimeSlots
-- hasMany Persons
-- hasMany Artists
-- hasMany Briefings
-- hasMany Locations
-- hasMany AccessZones
-- hasMany PublicForms
-
-**FestivalSection**
-- belongsTo Event
-- hasMany Shifts
-
-**TimeSlot**
-- belongsTo Event
-- hasMany Shifts
-- hasMany ShiftAssignments (denormalized)
-
-**Shift**
-- belongsTo FestivalSection
-- belongsTo TimeSlot
-- belongsTo Location (nullable)
-- hasMany ShiftAssignments
-
-**Person**
-- belongsTo Event
-- belongsTo CrowdType
-- belongsTo User (nullable)
-- belongsTo Company (nullable)
-- hasMany ShiftAssignments
-- hasMany AccreditationAssignments
-- hasMany CheckIns
-
-**Artist**
-- belongsTo Event
-- hasMany Performances
-- hasMany AdvanceSections
-- hasMany ArtistContacts
-
----
-
-## Security & CORS
-
-Two frontend origins in `config/cors.php` (via env):
-
-| App | Dev URL | Env Variable |
-|-----|---------|--------------|
-| App | `http://localhost:5174` | `FRONTEND_APP_URL` |
-| Portal | `http://localhost:5175` | `FRONTEND_PORTAL_URL` |
-
-Production (registered domain **crewli.app**): API `https://api.crewli.app` (`APP_URL`); SPAs `https://crewli.app`, `https://portal.crewli.app` via the same env keys. Frontends use `VITE_API_URL=https://api.crewli.app/api/v1`. `SANCTUM_STATEFUL_DOMAINS` = comma-separated SPA hostnames only (e.g. `crewli.app,portal.crewli.app`). **`crewli.nl`** is reserved for a future marketing site only — not used for this application stack.
-
----
-
-## Real-time Events (WebSocket)
-
-Via Laravel Echo + Pusher/Soketi:
-- `PersonCheckedIn`
-- `ShiftFillRateChanged`
-- `ArtistCheckInStatusChanged`
-- `AdvanceSectionSubmitted`
-- `AccreditationItemHandedOut`
-- `BriefingSendQueued`
-
----
-
-*Source: Crewli Design Document v1.3, March 2026*

.cursor/instructions.md

@@ -1,222 +0,0 @@
-# Crewli - Cursor AI Instructions
-
-> Multi-tenant SaaS platform for event- and festival management.
-> Design Document: `/resources/design/design-document.md`
-> Dev Guide: `/resources/design/dev-guide.md`
-> Start Guide: `/resources/design/start-guide.md`
-
-## Project Overview
-
-**Name**: Crewli
-**Type**: Multi-tenant SaaS platform (API-first architecture)
-**Status**: Development
-
-### Description
-
-Crewli is a multi-tenant SaaS platform for professional event and festival management. It supports the full operational cycle: artist booking and advancing, staff planning and volunteer management, accreditation, briefings, and real-time show-day operations (Mission Control). Built for a professional volunteer organisation, with SaaS expansion potential.
-
-## Quick Reference
-
-| Component | Technology | Location | Port |
-|-----------|------------|----------|------|
-| API | Laravel 12 + Sanctum + Spatie Permission | `api/` | 8000 |
-| Organizer + Admin App (Main) | Vue 3 + Vuexy (full) | `apps/app/` | 5174 |
-| Portal (External) | Vue 3 + Vuexy (stripped) | `apps/portal/` | 5175 |
-| Database | MySQL 8 | Docker | 3306 |
-| Cache / Queues | Redis | Docker | 6379 |
-| Mail | Mailpit | Docker | 8025 |
-
-## Documentation Structure
-
-```
-.cursor/
-├── instructions.md          # This file - overview and quick start
-├── ARCHITECTURE.md          # System architecture, schema, API routes
-└── rules/
-    ├── 001_workspace.mdc    # Project structure, conventions, multi-tenancy
-    ├── 100_laravel.mdc      # Laravel API patterns and templates
-    ├── 101_vue.mdc          # Vue + Vuexy patterns and templates
-    └── 200_testing.mdc      # Testing strategies and templates
-```
-
----
-
-## Core Modules
-
-### Phase 1 - Foundation
-- [ ] Multi-tenant architecture + Auth (Sanctum + Spatie)
-- [ ] Users, Roles & Permissions (three-level model)
-- [ ] Organisations CRUD + User Invitations
-- [ ] Events CRUD with lifecycle status
-- [ ] Crowd Types (org-level configuration)
-- [ ] Festival Sections + Time Slots + Shifts
-- [ ] Persons & Crowd Lists
-- [ ] Accreditation Engine (categories, items, access zones)
-
-### Phase 2 - Core Operations
-- [ ] Briefings & Communication (template builder, queue-based sending)
-- [ ] Staff & Crew Management (crowd pool, accreditation matrix)
-- [ ] Volunteer Management + Portal (registration, shift claiming, approval flow)
-- [ ] Form Builder (drag-drop, conditional logic, iframe embed)
-- [ ] Artist Advancing + Portal (token-based access)
-- [ ] Timetable & Stage management
-- [ ] Show Day Mode
-- [ ] Shift Swap & Waitlist
-- [ ] Volunteer Profile + Festival Passport
-- [ ] Communication Hub (email/SMS/WhatsApp via Zender, urgency levels)
-
-### Phase 3 - Advancing & Show Day
-- [ ] Guests & Hospitality
-- [ ] Suppliers & Production (production requests, supplier portal)
-- [ ] Mission Control (real-time check-in, artist handling, scanner management)
-- [ ] Communication Campaigns (email + SMS batch)
-- [ ] Allocation Sheet PDF (Browsershot)
-- [ ] Scan infrastructure (hardware pairing)
-- [ ] Reporting & Insights
-- [ ] No-show automation
-- [ ] Post-festival evaluation + retrospective
-
-### Phase 4 - Differentiators
-- [ ] Real-time WebSocket notifications (Echo + Pusher/Soketi)
-- [ ] Cross-event crew pool with reliability score
-- [ ] Global search (cmd+K)
-- [ ] Crew PWA
-- [ ] Public REST API + webhook system
-- [ ] CO2/sustainability reporting
-
----
-
-## Module Development Order (per module)
-
-Always follow this sequence:
-
-1. Migration(s) - ULID PKs, composite indexes, constrained FKs
-2. Eloquent Model - HasUlids, relations, scopes, OrganisationScope
-3. Factory - realistic Dutch test data
-4. Policy - authorization via Spatie roles
-5. Form Request(s) - Store + Update validation
-6. API Resource - computed fields, `whenLoaded()`, permission-dependent fields
-7. Resource Controller - index/show/store/update/destroy
-8. Routes in `api.php`
-9. PHPUnit Feature Test - happy path (200/201) + unauthenticated (401) + wrong organisation (403) + validation (422)
-10. Vue Composable (`useModuleName.ts`) - TanStack Query
-11. Pinia Store (if cross-component state needed)
-12. Vue Page Component
-13. Vue Router entry
-
----
-
-## Getting Started Prompts
-
-### 1. Phase 1 Foundation (Backend)
-
-```
-Read CLAUDE.md. Then generate Phase 1 Foundation:
-
-1. Migrations: Update users (add timezone, locale, deleted_at). Create organisations (ULID, name, slug, billing_status, settings JSON, deleted_at), organisation_user pivot, user_invitations, events (ULID, organisation_id, name, slug, start_date, end_date, timezone, status enum, deleted_at), event_user_roles pivot.
-2. Models: User (update), Organisation, UserInvitation, Event. All with HasUlids, SoftDeletes where applicable, OrganisationScope on Event.
-3. Spatie Permission: RoleSeeder with roles: super_admin, org_admin, org_member, event_manager, staff_coordinator, volunteer_coordinator.
-4. Auth: LoginController, LogoutController, MeController (returns user + organisations + active event roles).
-5. Organisations: Controller, Policy, Request, Resource.
-6. Events: Controller nested under organisations, Policy, Request, Resource.
-7. Feature tests per step. Run php artisan test after each step.
-```
-
-### 2. Phase 1 Foundation (Frontend)
-
-```
-Build auth flow in apps/app/:
-1. stores/useAuthStore.ts - token storage, isAuthenticated, me() loading
-2. pages/login.vue - use Vuexy login layout
-3. Router guard - redirect to login if not authenticated
-4. Replace Vuexy demo navigation with Crewli structure
-5. CASL permissions: connect to Spatie roles from auth/me response
-```
-
-### 3. Module Generation (example: Shifts)
-
-```
-Build the Shifts module following CLAUDE.md module order:
-- Migration with ULID PK, festival_section_id, time_slot_id, location_id, slots_total, slots_open_for_claiming, status. Composite indexes.
-- Model with HasUlids, SoftDeletes, relations, computed accessors (slots_filled, fill_rate).
-- shift_assignments with denormalized time_slot_id, status machine (pending_approval > approved/rejected/cancelled/completed), UNIQUE(person_id, time_slot_id).
-- Configurable auto-approve per shift.
-- Queued notification jobs using ZenderService for WhatsApp.
-- Feature tests covering 200/401/403/422.
-```
-
----
-
-## Common Tasks
-
-### Add a New API Endpoint
-
-1. Create/update Controller in `app/Http/Controllers/Api/V1/`
-2. Create Form Request in `app/Http/Requests/Api/V1/`
-3. Create/update API Resource in `app/Http/Resources/Api/V1/`
-4. Add route in `routes/api.php`
-5. Create Service class if complex business logic needed
-6. Write PHPUnit Feature Test (200/401/403/422)
-
-### Add a New Vue Page
-
-1. Create page component in `src/pages/`
-2. Route added automatically by file-based routing (or add to router)
-3. Add navigation item in `src/navigation/`
-4. Create composable for API calls in `src/composables/`
-5. Use Vuexy/Vuetify components for UI
-
-### Add a New Database Table
-
-1. Create migration with ULID PK, composite indexes
-2. Create model with HasUlids, relations, OrganisationScope (if applicable)
-3. Create factory with realistic Dutch test data
-4. Create Policy, Form Request, Resource, Controller
-5. Register routes in `api.php`
-6. Write PHPUnit Feature Test
-
----
-
-## Code Generation Preferences
-
-When generating code, always:
-
-- Use PHP 8.2+ features (typed properties, enums, match, readonly)
-- Use `declare(strict_types=1);`
-- Use ULID primary keys via HasUlids trait
-- Use Spatie laravel-permission for roles (never hardcode role strings)
-- Scope all queries on `organisation_id` via Global Scope
-- Use `<script setup lang="ts">` for Vue components
-- Use TanStack Query for all API calls
-- Use VeeValidate + Zod for form validation
-- Use Vuetify/Vuexy components for UI (never custom CSS if Vuetify class exists)
-
----
-
-## Environment Setup
-
-### Docker Services
-```bash
-make services       # Start MySQL, Redis, Mailpit
-make services-stop  # Stop services
-```
-
-### Development Servers
-```bash
-make api            # Laravel on :8000
-make app            # Organizer + Admin SPA on :5174
-make portal         # Portal SPA on :5175
-```
-
-### Database
-```bash
-make migrate        # Run migrations
-make fresh          # Fresh migrate + seed
-```
-
-### Testing
-```bash
-cd api && php artisan test                          # All tests
-cd api && php artisan test --filter=ShiftTest       # Specific test
-cd api && php artisan test --coverage               # With coverage
-```

.cursor/rules/101_vue.mdc

@@ -1,6 +1,6 @@
 ---
-description: Vue 3, TypeScript, and Vuexy patterns for Crewli platform
-globs: ["apps/**/*.{vue,ts,tsx}"]
+description: Vue 3, TypeScript, and Vuexy patterns for Crewli
+globs: ["apps/app/**/*.{vue,ts,tsx}"]
 alwaysApply: true
 ---
 
@@ -8,675 +8,78 @@ alwaysApply: true
 
 ## Core Principles
 
-1. **Composition API only** - Always `<script setup lang="ts">`
-2. **TypeScript strict mode** - No `any` types
-3. **TanStack Query for API** - Never raw axios in components
-4. **Pinia for client state** - Server data stays in TanStack Query
-5. **Vuexy/Vuetify components** - Never custom CSS if a Vuetify class exists
-6. **VeeValidate + Zod** - For all form validation
-7. **Mobile-first** - Minimum 375px width
+1. **Composition API only** — always `<script setup lang="ts">`, never Options API
+2. **No `any` types** — use proper typing or `unknown` + narrowing
+3. **TanStack Query for API** — never raw axios in components
+4. **Pinia for cross-component client state** — server data lives in TanStack Query, never duplicated in stores
+5. **Vuetify components first** — custom CSS only when no Vuetify class fits the use case
+6. **VeeValidate + Zod** for all form validation
+7. **Mobile-first** — minimum 375px width, responsive at every breakpoint
 
-## App-Specific Rules
+## File structure
 
-### `apps/app/` (Organizer + Platform Admin - Main App)
-- Sidebar nav customized for Crewli structure
-- Remove Vuexy demo/customizer components
-- Full Vuetify component usage
-- 90% of development work happens here
-- Super admin functionality under `/platform/*` routes for `super_admin` users
-
-### `apps/portal/` (External Portal)
-- Stripped Vuexy: no sidebar, no customizer, no dark mode toggle
-- Custom layout: top-bar with event logo + name
-- Uses Vuetify components + Vuexy SCSS variables
-- Two access modes: login (volunteers) and token (artists/suppliers)
-- Mobile-first design
-
-## Vuexy Folder Rules
-
-### Never Modify
 ```
-src/@core/          # Vuexy core
-src/@layouts/       # Vuexy layouts
+apps/app/src/
+├── lib/axios.ts              # Single axios instance (do not duplicate)
+├── composables/api/use*.ts   # TanStack Query composables (one per resource)
+├── stores/use*Store.ts       # Pinia stores — client state only
+├── types/*.ts                # TypeScript interfaces (mirror backend Resources)
+├── pages/                    # File-based routing via unplugin-vue-router
+├── layouts/                  # Layout components
+├── components/               # Reusable components
+└── @core/                    # Vuexy core — DO NOT MODIFY
 ```
 
-### Customize
-```
-src/
-├── components/         # Custom components
-├── composables/        # useModule.ts composables (TanStack Query)
-├── layouts/            # App layout customizations
-├── lib/                # axios.ts (SINGLE axios instance per app)
-├── navigation/         # Sidebar menu items
-├── pages/              # Page components
-├── plugins/            # vue-query, casl, vuetify
-├── stores/             # Pinia stores (client state only)
-└── types/              # TypeScript interfaces
-```
+## Reference patterns (read these for templates)
 
-## File Templates
+For working examples in the actual codebase:
 
-### Axios Instance (ONE per app)
+- **Composable pattern:** `apps/app/src/composables/api/useEvents.ts`
+- **Pinia store pattern:** `apps/app/src/stores/useAuthStore.ts`
+- **Page pattern:** `apps/app/src/pages/events/index.vue`
+- **Form pattern:** `apps/app/src/components/events/CreateEventDialog.vue`
+- **Layout pattern:** `apps/app/src/layouts/OrganizerLayout.vue`
 
-```typescript
-// src/lib/axios.ts
-import axios from 'axios'
-import type { AxiosInstance, InternalAxiosRequestConfig } from 'axios'
-import { useAuthStore } from '@/stores/useAuthStore'
+For Vuexy component selection, consult `dev-docs/VUEXY_COMPONENTS.md` — the registry of @core wrappers and patterns. Always check that registry before writing a custom component.
 
-const api: AxiosInstance = axios.create({
-  baseURL: `${import.meta.env.VITE_API_URL}/api/v1`,
-  withCredentials: true,
-  headers: {
-    'Content-Type': 'application/json',
-    Accept: 'application/json',
-  },
-  timeout: 30000,
-})
+For auth and routing, see `dev-docs/AUTH_ARCHITECTURE.md` (httpOnly cookies, dual-axios for portal-token routes, route guard logic).
 
-api.interceptors.request.use((config: InternalAxiosRequestConfig) => {
-  const authStore = useAuthStore()
-  if (authStore.token) {
-    config.headers.Authorization = `Bearer ${authStore.token}`
-  }
-  return config
-})
+## Strict rules
 
-api.interceptors.response.use(
-  response => response,
-  error => {
-    if (error.response?.status === 401) {
-      const authStore = useAuthStore()
-      authStore.logout()
-    }
-    return Promise.reject(error)
-  },
-)
+### TypeScript
+- Use `import type { ... }` for type-only imports
+- Mirror backend PHP Enums as const objects with `as const` in `apps/app/src/types/`
+- Generic API response shape: `{ data: T, meta?: PaginationMeta }`
 
-export { api }
-```
+### Architecture
+- Components never import axios directly — always via composables
+- Composables call axios via the singleton in `apps/app/src/lib/axios.ts`
+- Mutations invalidate query keys after success
+- No prop drilling — use Pinia stores when state crosses two component boundaries
 
-### TypeScript Types
+### UI
+- Three states for every list view: **loading** (VSkeletonLoader), **error** (VAlert with retry button), **empty** (helpful message explaining what action to take)
+- Custom CSS forbidden when a Vuetify utility class exists
+- Tables on mobile (<768px) collapse to VList or card view — never horizontal scroll without a visual indicator
 
-```typescript
-// src/types/events.ts
+### Forms
+- Zod schema mirrors backend FormRequest validation
+- Errors shown inline via VeeValidate's `errors` object
+- Submit button disabled while `isPending`
 
-export type EventStatus = 'draft' | 'published' | 'registration_open' | 'buildup' | 'showday' | 'teardown' | 'closed'
-export type PersonStatus = 'invited' | 'applied' | 'pending' | 'approved' | 'rejected' | 'no_show'
-export type BookingStatus = 'concept' | 'requested' | 'option' | 'confirmed' | 'contracted' | 'cancelled'
-export type ShiftAssignmentStatus = 'pending_approval' | 'approved' | 'rejected' | 'cancelled' | 'completed'
-export type CrowdSystemType = 'CREW' | 'GUEST' | 'ARTIST' | 'VOLUNTEER' | 'PRESS' | 'PARTNER' | 'SUPPLIER'
+### Routing
+- File-based routing via unplugin-vue-router
+- Guards in `apps/app/src/plugins/1.router/guards.ts`
+- Portal routes are at `/portal/*` (within apps/app), NOT a separate SPA
+- Platform admin routes are at `/platform/*`, gated by `super_admin` role
 
-export interface Organisation {
-  id: string
-  name: string
-  slug: string
-  billing_status: string
-  created_at: string
-  updated_at: string
-}
+## Avoid
 
-export interface Event {
-  id: string
-  organisation_id: string
-  name: string
-  slug: string
-  start_date: string
-  end_date: string
-  timezone: string
-  status: EventStatus
-  status_label: string
-  status_color: string
-  festival_sections?: FestivalSection[]
-  persons_count?: number
-  created_at: string
-  updated_at: string
-}
-
-export interface FestivalSection {
-  id: string
-  event_id: string
-  name: string
-  sort_order: number
-}
-
-export interface TimeSlot {
-  id: string
-  event_id: string
-  name: string
-  person_type: CrowdSystemType
-  date: string
-  start_time: string
-  end_time: string
-}
-
-export interface Shift {
-  id: string
-  festival_section_id: string
-  time_slot_id: string
-  location_id: string | null
-  slots_total: number
-  slots_open_for_claiming: number
-  slots_filled: number
-  fill_rate: number
-  status: string
-  festival_section?: FestivalSection
-  time_slot?: TimeSlot
-  assignments?: ShiftAssignment[]
-}
-
-export interface ShiftAssignment {
-  id: string
-  shift_id: string
-  person_id: string
-  time_slot_id: string
-  status: ShiftAssignmentStatus
-  auto_approved: boolean
-  person?: Person
-}
-
-export interface Person {
-  id: string
-  event_id: string
-  crowd_type_id: string
-  user_id: string | null
-  name: string
-  email: string
-  phone: string | null
-  status: PersonStatus
-  is_blacklisted: boolean
-  crowd_type?: CrowdType
-}
-
-export interface CrowdType {
-  id: string
-  organisation_id: string
-  name: string
-  system_type: CrowdSystemType
-  color: string
-  icon: string
-}
-
-export interface Artist {
-  id: string
-  event_id: string
-  name: string
-  booking_status: BookingStatus
-  star_rating: number
-}
-
-// API response types
-export interface PaginatedResponse<T> {
-  data: T[]
-  meta: {
-    current_page: number
-    per_page: number
-    total: number
-    last_page: number
-  }
-}
-
-// Form types
-export interface CreateEventData {
-  organisation_id: string
-  name: string
-  slug: string
-  start_date: string
-  end_date: string
-  timezone?: string
-  status?: EventStatus
-}
-
-export interface UpdateEventData extends Partial<CreateEventData> {}
-```
-
-### TanStack Query Setup
-
-```typescript
-// src/plugins/vue-query.ts
-import type { VueQueryPluginOptions } from '@tanstack/vue-query'
-import { QueryClient } from '@tanstack/vue-query'
-
-export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      retry: 1,
-    },
-  },
-})
-
-export const vueQueryPluginOptions: VueQueryPluginOptions = {
-  queryClient,
-}
-```
-
-### Composable (useEvents)
-
-```typescript
-// src/composables/useEvents.ts
-import { computed } from 'vue'
-import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
-import { api } from '@/lib/axios'
-import type { Event, CreateEventData, UpdateEventData, PaginatedResponse } from '@/types/events'
-
-export function useEventList(organisationId: string) {
-  return useQuery({
-    queryKey: ['organisations', organisationId, 'events'],
-    queryFn: async () => {
-      const { data } = await api.get<PaginatedResponse<Event>>(
-        `/organisations/${organisationId}/events`
-      )
-      return data
-    },
-    enabled: !!organisationId,
-  })
-}
-
-export function useEventDetail(eventId: string) {
-  return useQuery({
-    queryKey: ['events', eventId],
-    queryFn: async () => {
-      const { data } = await api.get<{ data: Event }>(`/events/${eventId}`)
-      return data.data
-    },
-    enabled: !!eventId,
-  })
-}
-
-export function useCreateEvent() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: async (payload: { organisationId: string; data: CreateEventData }) => {
-      const { data } = await api.post<{ data: Event }>(
-        `/organisations/${payload.organisationId}/events`,
-        payload.data,
-      )
-      return data.data
-    },
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({
-        queryKey: ['organisations', variables.organisationId, 'events'],
-      })
-    },
-  })
-}
-
-export function useUpdateEvent() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: async (payload: { eventId: string; data: UpdateEventData }) => {
-      const { data } = await api.put<{ data: Event }>(
-        `/events/${payload.eventId}`,
-        payload.data,
-      )
-      return data.data
-    },
-    onSuccess: (data) => {
-      queryClient.invalidateQueries({ queryKey: ['events', data.id] })
-      queryClient.invalidateQueries({
-        queryKey: ['organisations', data.organisation_id, 'events'],
-      })
-    },
-  })
-}
-
-export function useDeleteEvent() {
-  const queryClient = useQueryClient()
-
-  return useMutation({
-    mutationFn: async (eventId: string) => {
-      await api.delete(`/events/${eventId}`)
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ['events'] })
-    },
-  })
-}
-```
-
-### Pinia Store (Auth)
-
-```typescript
-// src/stores/useAuthStore.ts
-import { defineStore } from 'pinia'
-import { ref, computed } from 'vue'
-import { api } from '@/lib/axios'
-import type { Organisation } from '@/types/events'
-
-interface AuthUser {
-  id: string
-  name: string
-  email: string
-  timezone: string
-  locale: string
-  organisations: Organisation[]
-  event_roles: Array<{ event_id: string; role: string }>
-}
-
-export const useAuthStore = defineStore('auth', () => {
-  const user = ref<AuthUser | null>(null)
-  const token = ref<string | null>(localStorage.getItem('auth_token'))
-  const currentOrganisationId = ref<string | null>(localStorage.getItem('current_organisation_id'))
-
-  const isAuthenticated = computed(() => !!token.value && !!user.value)
-  const currentOrganisation = computed(() =>
-    user.value?.organisations.find(o => o.id === currentOrganisationId.value) ?? null
-  )
-
-  async function login(email: string, password: string): Promise<boolean> {
-    try {
-      const { data } = await api.post('/auth/login', { email, password })
-      user.value = data.data.user
-      token.value = data.data.token
-      localStorage.setItem('auth_token', data.data.token)
-
-      if (data.data.user.organisations.length > 0) {
-        setCurrentOrganisation(data.data.user.organisations[0].id)
-      }
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  async function fetchMe(): Promise<boolean> {
-    if (!token.value) return false
-    try {
-      const { data } = await api.get('/auth/me')
-      user.value = data.data
-      return true
-    } catch {
-      logout()
-      return false
-    }
-  }
-
-  function setCurrentOrganisation(orgId: string) {
-    currentOrganisationId.value = orgId
-    localStorage.setItem('current_organisation_id', orgId)
-  }
-
-  function logout() {
-    user.value = null
-    token.value = null
-    currentOrganisationId.value = null
-    localStorage.removeItem('auth_token')
-    localStorage.removeItem('current_organisation_id')
-  }
-
-  return {
-    user, token, currentOrganisationId,
-    isAuthenticated, currentOrganisation,
-    login, fetchMe, setCurrentOrganisation, logout,
-  }
-})
-```
-
-### Page Component (Event List)
-
-```vue
-<!-- src/pages/events/index.vue -->
-<script setup lang="ts">
-import { computed } from 'vue'
-import { useAuthStore } from '@/stores/useAuthStore'
-import { useEventList } from '@/composables/useEvents'
-
-const authStore = useAuthStore()
-const organisationId = computed(() => authStore.currentOrganisationId ?? '')
-const { data, isLoading, isError, error } = useEventList(organisationId.value)
-
-const events = computed(() => data.value?.data ?? [])
-
-function getStatusColor(status: string): string {
-  const colors: Record<string, string> = {
-    draft: 'secondary',
-    published: 'info',
-    registration_open: 'primary',
-    buildup: 'warning',
-    showday: 'success',
-    teardown: 'warning',
-    closed: 'secondary',
-  }
-  return colors[status] ?? 'secondary'
-}
-</script>
-
-<template>
-  <div>
-    <!-- Page Header -->
-    <div class="d-flex justify-space-between align-center mb-6">
-      <div>
-        <h4 class="text-h4 mb-1">Events</h4>
-        <p class="text-body-1 text-medium-emphasis">
-          Manage events for your organisation
-        </p>
-      </div>
-      <VBtn
-        color="primary"
-        prepend-icon="tabler-plus"
-        :to="{ name: 'events-create' }"
-      >
-        Create Event
-      </VBtn>
-    </div>
-
-    <!-- Loading State -->
-    <VCard v-if="isLoading">
-      <VCardText class="text-center py-8">
-        <VProgressCircular indeterminate color="primary" />
-      </VCardText>
-    </VCard>
-
-    <!-- Error State -->
-    <VAlert v-else-if="isError" type="error" class="mb-4">
-      {{ error?.message ?? 'Failed to load events' }}
-    </VAlert>
-
-    <!-- Events Table -->
-    <VCard v-else>
-      <VDataTable
-        :items="events"
-        :headers="[
-          { title: 'Name', key: 'name' },
-          { title: 'Dates', key: 'start_date' },
-          { title: 'Status', key: 'status' },
-          { title: 'Actions', key: 'actions', sortable: false },
-        ]"
-      >
-        <template #item.name="{ item }">
-          <RouterLink :to="{ name: 'events-show', params: { id: item.id } }">
-            {{ item.name }}
-          </RouterLink>
-        </template>
-
-        <template #item.start_date="{ item }">
-          {{ item.start_date }} - {{ item.end_date }}
-        </template>
-
-        <template #item.status="{ item }">
-          <VChip :color="getStatusColor(item.status)" size="small">
-            {{ item.status_label }}
-          </VChip>
-        </template>
-
-        <template #item.actions="{ item }">
-          <VBtn
-            icon
-            variant="text"
-            size="small"
-            :to="{ name: 'events-edit', params: { id: item.id } }"
-          >
-            <VIcon icon="tabler-edit" />
-          </VBtn>
-        </template>
-      </VDataTable>
-    </VCard>
-  </div>
-</template>
-```
-
-### Navigation Menu (Organizer App)
-
-```typescript
-// src/navigation/vertical/index.ts
-import type { VerticalNavItems } from '@/@layouts/types'
-
-export default [
-  {
-    title: 'Dashboard',
-    to: { name: 'dashboard' },
-    icon: { icon: 'tabler-smart-home' },
-  },
-  { heading: 'Event Management' },
-  {
-    title: 'Events',
-    to: { name: 'events' },
-    icon: { icon: 'tabler-calendar-event' },
-  },
-  {
-    title: 'Festival Sections',
-    to: { name: 'festival-sections' },
-    icon: { icon: 'tabler-layout-grid' },
-  },
-  {
-    title: 'Time Slots & Shifts',
-    to: { name: 'shifts' },
-    icon: { icon: 'tabler-clock' },
-  },
-  { heading: 'People' },
-  {
-    title: 'Persons',
-    to: { name: 'persons' },
-    icon: { icon: 'tabler-users' },
-  },
-  {
-    title: 'Artists',
-    to: { name: 'artists' },
-    icon: { icon: 'tabler-music' },
-  },
-  {
-    title: 'Volunteers',
-    to: { name: 'volunteers' },
-    icon: { icon: 'tabler-heart-handshake' },
-  },
-  { heading: 'Operations' },
-  {
-    title: 'Accreditation',
-    to: { name: 'accreditation' },
-    icon: { icon: 'tabler-id-badge-2' },
-  },
-  {
-    title: 'Briefings',
-    to: { name: 'briefings' },
-    icon: { icon: 'tabler-mail' },
-  },
-  {
-    title: 'Mission Control',
-    to: { name: 'mission-control' },
-    icon: { icon: 'tabler-broadcast' },
-  },
-  { heading: 'Insights' },
-  {
-    title: 'Reports',
-    to: { name: 'reports' },
-    icon: { icon: 'tabler-chart-bar' },
-  },
-] as VerticalNavItems
-```
-
-## Forms with VeeValidate + Zod
-
-```vue
-<script setup lang="ts">
-import { useForm } from 'vee-validate'
-import { toTypedSchema } from '@vee-validate/zod'
-import { z } from 'zod'
-import { useCreateEvent } from '@/composables/useEvents'
-
-const schema = toTypedSchema(
-  z.object({
-    name: z.string().min(1, 'Name is required'),
-    slug: z.string().min(1, 'Slug is required'),
-    start_date: z.string().min(1, 'Start date is required'),
-    end_date: z.string().min(1, 'End date is required'),
-    timezone: z.string().default('Europe/Amsterdam'),
-  })
-)
-
-const { handleSubmit, errors, defineField } = useForm({ validationSchema: schema })
-const [name, nameAttrs] = defineField('name')
-const [startDate, startDateAttrs] = defineField('start_date')
-
-const { mutate: createEvent, isPending } = useCreateEvent()
-
-const onSubmit = handleSubmit(values => {
-  createEvent({
-    organisationId: authStore.currentOrganisationId!,
-    data: values as CreateEventData,
-  })
-})
-</script>
-
-<template>
-  <form @submit="onSubmit">
-    <VTextField
-      v-model="name"
-      v-bind="nameAttrs"
-      label="Event Name"
-      :error-messages="errors.name"
-    />
-    <VTextField
-      v-model="startDate"
-      v-bind="startDateAttrs"
-      label="Start Date"
-      type="date"
-      :error-messages="errors.start_date"
-    />
-    <VBtn type="submit" color="primary" :loading="isPending">
-      Create Event
-    </VBtn>
-  </form>
-</template>
-```
-
-## Best Practices
-
-### Always Use
-- `<script setup lang="ts">` for components
-- Props: `defineProps<{...}>()`
-- Emits: `defineEmits<{...}>()`
-- TanStack Query for all API calls via composables
-- Computed properties for derived state
-- Vuexy/Vuetify components (VBtn, VCard, VDataTable, VDialog, etc.)
-- `import type { ... }` for type-only imports
-- Status KPI tiles as clickable VCards on list pages
-- VSkeleton loader during loading
-- VAlert with retry on errors
-- Mobile: table collapses to VList below 768px
-
-### Avoid
-- Options API
+- Options API (`export default { ... }`)
 - `any` types
-- Raw axios calls in components (use composables)
-- Inline styles (use Vuetify utility classes)
+- Raw axios calls in components
+- Inline styles
 - Direct DOM manipulation
 - Mutating props
-- Prop drilling (use Pinia stores)
-- Custom CSS when Vuetify class exists
-
-## Portal Router Guards
-
-```typescript
-// apps/portal/src/router/guards.ts
-export function determineAccessMode(route: RouteLocationNormalized): 'token' | 'login' | 'unauthenticated' {
-  if (route.query.token) return 'token'
-  if (authStore.isAuthenticated) return 'login'
-  return 'unauthenticated'
-}
-
-// Token-based: POST /api/v1/portal/token-auth { token: '...' } -> returns person context
-// Login-based: Same /api/v1/auth/login as app/
-```
+- Custom CSS when a Vuetify class exists
+- Hardcoded URLs or string-literal status values

.cursor/rules/102_multi_tenancy.mdc

@@ -1,6 +1,6 @@
 ---
 description: Multi-tenancy and portal architecture rules for Crewli
-globs: ["api/**/*.php", "apps/portal/**/*.{vue,ts}"]
+globs: ["api/**/*.php"]
 alwaysApply: true
 ---
 
@@ -92,16 +92,20 @@ Route::middleware(['auth:sanctum', 'event.role:event_manager'])->group(...);
 
 ## Portal Architecture
 
-### Two Access Modes in One App (`apps/portal/`)
+### Two Access Modes Under `/portal/*` Routes (within `apps/app/`)
+
+Post-WS-3, the portal lives in the main SPA at `/portal/*` routes.
+Two access modes coexist:
 
 | Mode | Middleware | Users | Token Source |
-|------|-----------|-------|-------------|
-| Login | `auth:sanctum` | Volunteers, Crew | Bearer token from login |
+|------|------------|-------|--------------|
+| Login | `auth:sanctum` | Volunteers, Crew | Bearer token from login (httpOnly cookie) |
 | Token | `portal.token` | Artists, Suppliers, Press | URL token param: `?token=ULID` |
 
 ### Token-Based Authentication Flow
 ```
-1. Artist/supplier receives email with link: https://portal.crewli.app/advance?token=01HQ3K...
+1. Artist/supplier receives email with link: https://crewli.app/portal/advance?token=01HQ3K...
+   (Legacy portal.crewli.app links 301-redirect, preserving the token query param)
 2. Portal detects token in URL query parameter
 3. POST /api/v1/portal/token-auth { token: '01HQ3K...' }
 4. Backend validates token against artists.portal_token or production_requests.token
@@ -111,9 +115,9 @@ Route::middleware(['auth:sanctum', 'event.role:event_manager'])->group(...);
 
 ### Login-Based Authentication Flow
 ```
-1. Volunteer navigates to https://portal.crewli.app/login
+1. Volunteer navigates to https://crewli.app/login
 2. Enters email + password
-3. POST /api/v1/auth/login (same endpoint as apps/app/)
+3. POST /api/v1/auth/login
 4. Returns user + organisations + event roles
 5. Portal shows volunteer-specific views (My Shifts, Claim Shifts, Messages, Profile)
 ```
@@ -190,12 +194,11 @@ class PortalTokenMiddleware
 // config/cors.php
 'allowed_origins' => [
     env('FRONTEND_APP_URL', 'http://localhost:5174'),
-    env('FRONTEND_PORTAL_URL', 'http://localhost:5175'),
 ],
 'supports_credentials' => true,
 ```
 
-Production example (subdomains on **crewli.app**): `FRONTEND_APP_URL=https://crewli.app`, `FRONTEND_PORTAL_URL=https://portal.crewli.app`, and `SANCTUM_STATEFUL_DOMAINS=crewli.app,portal.crewli.app`.
+Production example (registered domain **crewli.app**): `FRONTEND_APP_URL=https://crewli.app` and `SANCTUM_STATEFUL_DOMAINS=crewli.app`. The legacy `FRONTEND_PORTAL_URL` env key is retained for outbound-email controllers (per AUTH_ARCHITECTURE.md §11), but resolves to the same host post-WS-3.
 
 ## Shift Claiming & Approval Flow
 

.cursorrules

@@ -1,7 +1,11 @@
 # Crewli Cursor Rules
 
+> Migration phase: this file is updated in F2 of RFC-WS-FRONTEND-PRIMEVUE
+> and continues to evolve as F4 progresses. Authoritative UI-framework
+> reference is `dev-docs/PRIMEVUE_COMPONENTS.md`.
+
 ## Stack
-PHP 8.2 + Laravel 12 | TypeScript + Vue 3 + Vuexy/Vuetify | Pinia + TanStack Query
+PHP 8.2 + Laravel 12 | TypeScript + Vue 3 + PrimeVue + Tailwind v4 (target) / Vuetify (legacy, un-migrated surfaces) | Pinia + TanStack Query
 
 ## Laravel
 - Resource controllers, form requests, API resources — always
@@ -9,15 +13,22 @@ PHP 8.2 + Laravel 12 | TypeScript + Vue 3 + Vuexy/Vuetify | Pinia + TanStack Que
 - Global scope `OrganisationScope` on event-related models
 - Policies for authorization — never inline role checks
 
-## Vuexy reference path (mandatory)
-- When looking at Vuexy examples, demos, or patterns, ALWAYS reference:
+## UI framework strategy (migration-aware)
+- Always read `dev-docs/PRIMEVUE_COMPONENTS.md` first — it's the authoritative reference for component selection, theming, forms, and DataTable conventions
+- On migrated / new surfaces: PrimeVue + Tailwind v4; forms via `@primevue/forms` + Zod resolver through `<FormField>` (RFC-WS-FRONTEND-PRIMEVUE Appendix A)
+- On un-migrated surfaces (during F4): match surrounding Vuetify code; pre-F2 Vuexy reference recoverable via `git show 1c449ff6204cae6371da08c34ea8934d6b2ffcb8:dev-docs/VUEXY_COMPONENTS.md`
+- Never mix PrimeVue and Vuetify inside one form or one surface ("no back-porting")
+
+## Vuexy reference path (legacy surfaces only)
+- When extending an un-migrated surface, the Vuexy template reference is at:
   `resources/vuexy-admin-v10.11.1/vue-version/typescript-version/full-version/`
 - Never reference `javascript-version/` or `starter-kit/` variants
 
 ## Vue 3
 - `<script setup lang="ts">` always
 - TanStack Query for API state, Pinia for UI state
-- Vuetify components first; custom CSS only as a last resort
+- On migrated surfaces: Tailwind utilities for layout, PrimeVue components, `pt` API for component-internal styling
+- On legacy surfaces: Vuetify components first; custom CSS only as a last resort
 
 ## Naming
 - snake_case DB | camelCase JS | PascalCase Vue | `use*` composables | `use*Store` Pinia

.gitattributes

@@ -0,0 +1,2 @@
+apps/app/tests/playwright-ct/**/__screenshots__/**/*.png filter=lfs diff=lfs merge=lfs -text
+apps/app/tests/playwright-e2e/**/__screenshots__/**/*.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -39,6 +39,18 @@ storage/framework/views/*
 .phpunit.result.cache
 coverage/
 
+# Playwright runtime artifacts (test-results, blob-report, html-report,
+# .cache build dir, playwright traces). __screenshots__/ is committed
+# (via Git LFS, see .gitattributes).
+apps/app/test-results/
+apps/app/playwright-report/
+apps/app/blob-report/
+apps/app/playwright/.cache/
+
+# Playwright e2e seed-data fixture file — written by E2EBaselineSeeder
+# during globalSetup, never source-of-truth.
+api/storage/app/e2e-fixtures.json
+
 # Misc
 *.pem
 .cache/
@@ -57,3 +69,22 @@ docs/.vitepress/cache
 
 # Claude Project Knowledge sync output (regenerated by scripts/sync-claude-docs.sh)
 .claude-sync/
+
+# Claude Code runtime state
+.claude/*.lock
+
+# GlitchTip
+docker/glitchtip/.env
+backups/
+
+# WS-7 RFC §3.5: Vite sourcemaps are uploaded to GlitchTip and stripped
+# from dist/ before deploy. Defensive exclusion in case dist/ is ever
+# committed by mistake (it's already covered by `dist/` above).
+apps/app/dist/**/*.map
+
+*storybook.log
+storybook-static
+
+# Python bytecode
+__pycache__/
+*.pyc

CLAUDE.md

@@ -1,5 +1,7 @@
 # Crewli — Claude Code Instructions
 
+> See `dev-docs/CLAUDE_CODE_TOOLING.md` for the deterministic guard-rail layer (hooks, subagent, slash commands).
+
 ## Project context
 
 Crewli is a multi-tenant SaaS platform for event and festival management.
@@ -9,7 +11,7 @@ Design document: `/dev-docs/design-document.md`
 ## Tech stack
 
 - Backend: PHP 8.2+, Laravel 12, Sanctum, Spatie Permission, MySQL 8, Redis
-- Frontend: TypeScript, Vue 3 (Composition API), Vuexy/Vuetify, Pinia, TanStack Query
+- Frontend: TypeScript, Vue 3 (Composition API), PrimeVue + Tailwind v4 (target state, migration in progress per [RFC-WS-FRONTEND-PRIMEVUE](./dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md)) — Vuetify/Vuexy still present on un-migrated surfaces during F4; see [`PRIMEVUE_COMPONENTS.md`](./dev-docs/PRIMEVUE_COMPONENTS.md). Pinia, TanStack Query.
 - Testing: PHPUnit (backend), Vitest (frontend)
 
 ## Quality gates
@@ -22,12 +24,11 @@ Design document: `/dev-docs/design-document.md`
 - `composer rector` — Rector dry-run for modernisation suggestions.
   See `/dev-docs/RECTOR.md`. Apply only in scoped sprints, never
   automatically.
-- ts-reset patches TypeScript's loosest default types in both SPAs.
+- ts-reset patches TypeScript's loosest default types in the SPA.
   See `/dev-docs/FRONTEND-TOOLING.md`. New TypeScript code adheres
   to ts-reset's stricter types automatically.
-- Vitest — `apps/portal` has 113+ tests; `apps/app` currently has
-  no Vitest setup (tracked as TECH-APP-VITEST, must close before
-  S3b lands).
+- Vitest — `apps/app` has Vitest with 213 tests as of WS-3 PR-B2a.
+  Test count grows with each PR; check `pnpm test` for current value.
 
 ## Development tooling
 
@@ -38,24 +39,23 @@ Design document: `/dev-docs/design-document.md`
 ## Repository layout
 
 - `api/` — Laravel backend
-- `apps/app/` — Organizer SPA (main product app + Platform Admin for super admins)
-- `apps/portal/` — External portal (volunteers, artists, suppliers, etc.)
+- `apps/app/` — Single SPA covering organizers, volunteers, crew, super admins (context-routed in-app) plus the public form-fill / artist-advance flows
 
-## Apps and portal architecture
+## App architecture
 
-- `apps/app/` — Organizer: event management per organisation. Includes **Platform Admin** section (`/platform/*`) for super_admin users (organisation management, user management, impersonation, activity log).
-- `apps/portal/` — External users: one app, two access modes:
-  - Login-based (`auth:sanctum`): volunteers, crew — persons with `user_id`
-  - Token-based (`portal.token` middleware): artists, suppliers, press — persons without `user_id`
+`apps/app/` — single workspace, two access modes:
+
+- Login-based (`auth:sanctum`): organizers, volunteers, crew, super_admin. Includes **Platform Admin** section (`/platform/*`) for super_admin users (organisation management, user management, impersonation, activity log). Context-aware routing inside the SPA distinguishes organizer vs. volunteer experience based on `useAuthStore.availableContexts` (see `dev-docs/AUTH_ARCHITECTURE.md`).
+- Token-based (`portal.token` middleware): artists, suppliers, press — persons without `user_id`. Stateless per-request token via `Authorization: Bearer` header or `?token=` query parameter.
 
 ### CORS
 
-Configure two frontend origins in both Laravel (`config/cors.php` via env) and the Vite dev server proxy:
+Single frontend origin in both Laravel (`config/cors.php` via env) and the Vite dev server proxy:
 
-- app: `localhost:5174`
-- portal: `localhost:5175`
+- dev: `localhost:5174`
+- prod: `https://crewli.app`
 
-**Production (`crewli.app`):** API `https://api.crewli.app`, SPAs `https://crewli.app`, `https://portal.crewli.app` — see `api/.env.example` for `FRONTEND_*` and `SANCTUM_STATEFUL_DOMAINS`. **`crewli.nl`** is only for a future marketing site; this application stack uses **`crewli.app`** (not `.nl` for API, SPAs, or transactional mail).
+See `api/.env.example` for `FRONTEND_*` and `SANCTUM_STATEFUL_DOMAINS`. **`crewli.nl`** is only for a future marketing site; this application stack uses **`crewli.app`** (not `.nl` for API, SPA, or transactional mail).
 
 ## Backend rules (strict)
 
@@ -160,56 +160,53 @@ PR as the migration.
 - Use factories for all test data
 - After each module: `php artisan test --filter=ModuleName`
 
+Frontend test architecture (5 tiers: Unit / Component / Integration /
+Visual / E2E) is documented in `dev-docs/ARCH-TESTING.md`. Choose the
+right tier per the decision tree there before adding new tests.
+
 ## Frontend rules (strict)
 
-### Vuexy reference source (mandatory)
+### UI framework strategy (migration-aware)
 
-When referencing Vuexy demo pages, components, or patterns, ALWAYS use the TypeScript Vue version at:
+The SPA is migrating Vuetify/Vuexy → PrimeVue + Tailwind v4 per
+[RFC-WS-FRONTEND-PRIMEVUE](./dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md).
+During F4 (sub-packages F4a–F4d), both frameworks ship in the same build
+on different surfaces. The component-selection rules depend on which side
+of the migration the surface is on.
 
-```
-resources/vuexy-admin-v10.11.1/vue-version/typescript-version/full-version/
-```
+**Always read [`PRIMEVUE_COMPONENTS.md`](./dev-docs/PRIMEVUE_COMPONENTS.md)
+before any frontend task** — it is the authoritative reference for
+component selection, theming, forms, and DataTable conventions across
+both phases.
 
-This is the **ONLY** valid reference path. Never use:
-- `javascript-version/` — wrong language
-- `starter-kit/` — incomplete, missing components
-- Any other variant or version
+#### On migrated surfaces (target state)
 
-Before implementing any Vuexy-based page or component, read the reference implementation from this path first:
-```bash
-# Example: find auth page references
-find resources/vuexy-admin-v10.11.1/vue-version/typescript-version/full-version/src/pages -name "*.vue" | grep -i "login\|auth"
-```
+PrimeVue is the framework. Follow [`PRIMEVUE_COMPONENTS.md`](./dev-docs/PRIMEVUE_COMPONENTS.md):
 
-### Vuexy-first strategy
+1. **Can a Tailwind utility do this?** (layout, spacing, typography) → use it.
+2. **Does PrimeVue provide a component?** → use it (see §3 component mapping).
+3. **Forms** → `@primevue/forms` + Zod resolver via `<FormField>` (§5; full API in [RFC Appendix A](./dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md#appendix-a--formfield-api-specification)).
+4. **DataTables** → `<DataTable>` with `:lazy="true"` for server-side (§6).
+5. **None of the above?** → cross-reference https://primevue.org/ for the closest match. Add a note in `PRIMEVUE_COMPONENTS.md` §3 if it's a recurring need.
 
-Before writing ANY frontend component, consult `/dev-docs/VUEXY_COMPONENTS.md` and follow this decision tree:
+Customization order: Tailwind utilities (layout) → `pt` API (component-internal) → Aura preset extension (brand-wide) → `<style scoped>` (last resort, with comment).
 
-1. **Can a standard Vuetify component do this?** → Use it with default props.
-   Do not wrap it in a custom component.
-2. **Does Vuexy provide an @core component for this?** → Use it. Check
-   `/dev-docs/VUEXY_COMPONENTS.md` section 1 for the full registry.
-3. **Does an existing Crewli page already solve a similar UI pattern?** →
-   Copy that pattern exactly. Check `/dev-docs/VUEXY_COMPONENTS.md` section 3
-   for established patterns and their reference implementations.
-4. **None of the above?** → Only then write custom code. Add `<style scoped>`
-   with a comment explaining why Vuexy/Vuetify couldn't handle it.
+#### On un-migrated surfaces (legacy, transient)
 
-Concrete component rules:
-- Tables: `v-data-table-server` with server-side pagination — never client-side for API data
-- Cards: `v-card` directly, or `AppCardActions` when collapse/refresh/remove is needed
-- Forms in dialogs: `v-dialog` + `v-card` + `v-form` — follow the established dialog pattern
-- Detail panels: `v-navigation-drawer` with `temporary` and `location="end"` — follow ShiftDetailPanel pattern
-- Date/time pickers: `AppDateTimePicker` from @core — never raw input[type=date]
-- Status indicators: `v-chip` with color prop — never custom styled spans
-- Loading states: `v-skeleton-loader` — never custom spinners
-- Error states: `v-alert` with retry button — never custom error divs
-- Empty states: `v-card` with icon + message + action button
-- Notifications: `v-snackbar` — never custom toast components
-- Page layout: `v-row` + `v-col` with Vuetify breakpoint props — never CSS grid or custom flexbox
+Vuetify + Vuexy `@core/` components remain in use until the surface's F4
+sub-package lands. When extending these surfaces during the transition:
 
-**Before ANY frontend task:** read `/dev-docs/VUEXY_COMPONENTS.md` to verify
-you are using available components rather than building custom ones.
+- Match the surrounding code (`<VBtn>`, `<VTextField>`, `<v-data-table-server>`, etc.)
+- Reference the pre-F2 Vuexy registry via git: `git show 1c449ff6204cae6371da08c34ea8934d6b2ffcb8:dev-docs/VUEXY_COMPONENTS.md`
+- Vuexy template reference (when needed): `resources/vuexy-admin-v10.11.1/vue-version/typescript-version/full-version/` — TypeScript Vue version is the only valid path
+
+Do **not** introduce PrimeVue components inside an un-migrated surface
+("no back-porting" — see `PRIMEVUE_COMPONENTS.md` §9).
+
+#### On new surfaces (created during or after F4)
+
+Start in PrimeVue. The migration phase is not a license to add new
+Vuetify code.
 
 ### Vue components
 
@@ -236,10 +233,36 @@ you are using available components rather than building custom ones.
 
 ### Forms
 
-- VeeValidate for form state + Zod for schema validation — always together
-- Zod schemas must mirror the backend Form Request rules (field names, required/optional, types)
+The canonical form pattern depends on the migration phase of the surface:
+
+**Target state (migrated surfaces, new surfaces):** `@primevue/forms` +
+Zod resolver via the `<FormField>` wrapper. Full API specification in
+[RFC-WS-FRONTEND-PRIMEVUE Appendix A](./dev-docs/RFC-WS-FRONTEND-PRIMEVUE.md#appendix-a--formfield-api-specification);
+Crewli conventions in [`PRIMEVUE_COMPONENTS.md` §5](./dev-docs/PRIMEVUE_COMPONENTS.md).
+One Zod schema per form, field names mirror backend Form Request keys
+(snake_case), 422 errors merge via `useFormError(formRef)`.
+
+**Legacy state (un-migrated surfaces, transient until each F4 sub-package):**
+
+- `ref({ field: ... })` for form state
+- `VForm` ref + per-field rules drawn from `@core/utils/validators`
+  (`requiredValidator`, `emailValidator`, etc.)
+- A separate `errors: Ref<Record<string, string>>` for server-validation
+  feedback (mapped from 422 responses)
+- **Zod** for runtime validation of API payloads/responses (in
+  `apps/app/src/schemas/*.ts`) — schemas already mirror backend Form
+  Requests and carry forward unchanged into the target state
 - No inline validation logic in components
 
+A single form is either fully Zod-resolver-validated (target) or fully
+`:rules`-validated (legacy) — never a hybrid. VeeValidate is **NOT** in
+the stack on either side of the migration.
+
+Reference forms (legacy pattern, will migrate during F4):
+`apps/app/src/components/sections/CreateShiftDialog.vue`,
+`apps/app/src/components/timetable/AddPerformanceDialog.vue`,
+`apps/app/src/pages/register/[public_token].vue`.
+
 ### Naming
 
 - DB columns: `snake_case`
@@ -250,12 +273,12 @@ you are using available components rather than building custom ones.
 
 ### UI
 
-- Always use Vuexy/Vuetify for layout, forms, tables, dialogs
-- Do not write custom CSS when a Vuetify utility class exists
+- Component framework selection: see "UI framework strategy" above and [`PRIMEVUE_COMPONENTS.md`](./dev-docs/PRIMEVUE_COMPONENTS.md). PrimeVue + Tailwind v4 on migrated/new surfaces; Vuetify on un-migrated surfaces during F4
+- Do not write custom CSS when a framework utility (Tailwind on migrated surfaces, Vuetify utilities on legacy surfaces) exists
 - Responsive: mobile-first, usable from 375px width
-- **Three states per page:** every data-driven view must handle loading (skeleton/spinner), error (`v-alert` with retry button), and empty (helpful message with action button)
-- Use Vuetify responsive props (`cols`, `sm`, `md`, `lg`) — no fixed pixel widths
-- Custom CSS via `<style scoped>` only as last resort when no Vuetify utility exists
+- **Three states per page:** every data-driven view must handle loading (skeleton), error (`Message` / `v-alert` with retry button), and empty (helpful message with action button) — both frameworks support this pattern
+- Responsive layout: Tailwind grid (`grid grid-cols-12 gap-4` + `col-span-N md:col-span-M`) on migrated surfaces; Vuetify `v-row` + `v-col` with breakpoint props on legacy surfaces — no fixed pixel widths
+- Custom CSS via `<style scoped>` only as last resort when no framework utility / `pt` API / Aura token can do the job
 
 ## Forbidden patterns
 
@@ -303,6 +326,38 @@ allowed only with a `TODO TECH-*` reference to a backlog item.
 13. Vue page component in `src/pages/[module]/`
 14. Add route in Vue Router
 
+> **Framework note for steps 13–14 during F4 migration:** new pages
+> follow the PrimeVue + Tailwind conventions in [`PRIMEVUE_COMPONENTS.md`](./dev-docs/PRIMEVUE_COMPONENTS.md).
+> If the new module is grafted onto a not-yet-migrated surface (rare),
+> match the surrounding Vuetify style and let the surface's F4
+> sub-package migrate it later.
+
+## Diagnostic discipline: audit before assume
+
+When debugging or fixing any bug, the first action is to verify the
+canonical model against the artifact in question — not to write a fix
+based on the symptom or hypothesis.
+
+This applies to:
+
+- Schema drift (verify the resource shape against the Zod schema, line
+  by line)
+- Filter logic (verify the data model in SCHEMA.md before assuming a
+  controller is wrong)
+- UX divergence (verify the prototype line-by-line, not via spot check)
+- Test failures (verify the assertion matches the documented contract,
+  not the current implementation)
+
+Phase A of every fix prompt is STOP-and-report. No code is written
+before the audit is reviewed.
+
+This principle was formalised after three consecutive incidents where
+initial hypotheses were wrong and the audit gate caught them: B1
+(controller assumed buggy, seeder was wrong), B5 (enum-shape assumed
+drifted, decimals were wrong), and timetable UX (test-passing layer
+diverged from prototype, mechanical-vs-UX split surfaced via browser
+test).
+
 ## User Documentation (VitePress)
 
 End-user documentation lives in /docs/ as a VitePress site.
@@ -348,7 +403,8 @@ Rules:
 3. One commit per logical unit of work (one feature, one bugfix, one refactor)
 4. Never bundle unrelated changes in a single commit
 5. Never commit with failing tests
-6. Do NOT push automatically — only commit locally. The developer will push manually.
+6. Push, open PRs, and merge are AUTHORISED for Claude (granted by Bert
+   2026-06-03), gated on a green merge gate — see "Push & Merge Authority".
 
 Commit message format:
 ```
@@ -369,3 +425,26 @@ Examples:
 - `feat: person tags system with org-level skills and sync endpoint`
 - `fix: auth race condition on page refresh`
 - `docs: update SCHEMA.md with person_identity_matches table`
+
+### Push & Merge Authority
+
+Claude may push feature branches, open Gitea PRs, and merge them **without
+a separate human approval click**, provided ALL of the following hold:
+
+1. **Green merge gate** — crewli-reviewer `REVIEW VERDICT: PASS` (no MUST
+   FIX), all applicable tests passing, lint + typecheck clean, and for
+   backend changes Larastan clean + the multi-tenancy 403 test present.
+   The gate — not a human click — is the safety mechanism. If any signal
+   is red, Claude does NOT merge; it returns the work to the implementer.
+2. **Never push directly to `main`.** Integrate only via a `--no-ff` merge
+   of a reviewed feature branch (a merged Gitea PR with `merge_style: merge`,
+   or a local `--no-ff` merge then push).
+3. **Never force-push** to `main` or any shared branch.
+4. **Post-merge:** verify the merge landed on `main`, then delete the
+   feature branch locally and remotely (per the rule above).
+5. Still **present the merge gate** for visibility before self-merging, but
+   Claude may proceed to merge once the gate is green rather than blocking
+   on an explicit `merge` reply.
+
+This supersedes the earlier "developer pushes manually" rule and the
+build-module skill's HUMAN GATE 2 (CLAUDE.md takes precedence over skills).

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help services services-stop api app portal docs migrate fresh db-shell test test-db-create schema-dump
+.PHONY: help services services-stop services-glitchtip-status api app docs migrate fresh db-shell test test-db-create schema-dump storybook
 
 # Colors
 GREEN  := \033[0;32m
@@ -6,6 +6,10 @@ YELLOW := \033[0;33m
 CYAN   := \033[0;36m
 NC     := \033[0m
 
+# Compose files merged for local dev. Both files share one project so
+# Mailpit (bm_mailpit) is reachable from the GlitchTip containers.
+COMPOSE_FILES := -f docker-compose.yml -f docker-compose.glitchtip.yml
+
 help:
 	@echo ""
 	@echo "$(GREEN)╔══════════════════════════════════════════════════════════════╗$(NC)"
@@ -13,14 +17,15 @@ help:
 	@echo "$(GREEN)╚══════════════════════════════════════════════════════════════╝$(NC)"
 	@echo ""
 	@echo "  $(YELLOW)Services (Docker):$(NC)"
-	@echo "    make services         Start MySQL, Redis, Mailpit"
-	@echo "    make services-stop    Stop all Docker services"
+	@echo "    make services                    Start MySQL, Redis, Mailpit, GlitchTip"
+	@echo "    make services-stop               Stop all Docker services"
+	@echo "    make services-glitchtip-status   Tail GlitchTip web container logs"
 	@echo ""
 	@echo "  $(YELLOW)Development Servers:$(NC)"
 	@echo "    make api              Laravel API        → http://localhost:8000"
 	@echo "    make app              Organizer SPA      → http://localhost:5174"
-	@echo "    make portal           Portal SPA         → http://localhost:5175"
 	@echo "    make docs             VitePress docs     → http://localhost:5176"
+	@echo "    make storybook        Storybook (apps/app) → http://localhost:6006"
 	@echo ""
 	@echo "  $(YELLOW)Database:$(NC)"
 	@echo "    make migrate          Run migrations"
@@ -35,21 +40,27 @@ help:
 
 services:
 	@echo "$(GREEN)Starting Docker services...$(NC)"
-	@docker compose up -d
+	@docker compose $(COMPOSE_FILES) up -d
 	@echo ""
 	@echo "$(GREEN)Services:$(NC)"
-	@echo "  $(CYAN)MySQL:$(NC)    localhost:3306 (crewli / secret)"
-	@echo "  $(CYAN)Redis:$(NC)    localhost:6379"
-	@echo "  $(CYAN)Mailpit:$(NC)  http://localhost:8025"
+	@echo "  $(CYAN)MySQL:$(NC)        localhost:3306 (crewli / secret)"
+	@echo "  $(CYAN)Redis:$(NC)        localhost:6379"
+	@echo "  $(CYAN)Mailpit:$(NC)      http://localhost:8025"
+	@echo "  $(CYAN)GlitchTip:$(NC)    http://localhost:8200"
 	@echo ""
 	@echo "$(YELLOW)Waiting for MySQL...$(NC)"
 	@until docker exec bm_mysql mysqladmin ping -h localhost -u root -proot --silent 2>/dev/null; do sleep 1; done
 	@echo "$(GREEN)✓ Ready!$(NC)"
+	@echo "$(YELLOW)Note:$(NC) GlitchTip web takes ~60s on first boot (migrations)."
+	@echo "      Tail logs with: $(CYAN)make services-glitchtip-status$(NC)"
 
 services-stop:
-	@docker compose down
+	@docker compose $(COMPOSE_FILES) down
 	@echo "$(GREEN)✓ Services stopped$(NC)"
 
+services-glitchtip-status:
+	@docker compose $(COMPOSE_FILES) logs -f glitchtip-web
+
 api:
 	@echo "$(GREEN)Starting Laravel API → http://localhost:8000$(NC)"
 	@cd api && php artisan serve
@@ -58,10 +69,6 @@ app:
 	@echo "$(GREEN)Starting Organizer SPA → http://localhost:5174$(NC)"
 	@cd apps/app && pnpm dev
 
-portal:
-	@echo "$(GREEN)Starting Portal SPA → http://localhost:5175$(NC)"
-	@cd apps/portal && pnpm dev
-
 docs:
 	@echo "$(GREEN)Starting VitePress docs → http://localhost:5176$(NC)"
 	@cd docs && npm run docs:dev
@@ -96,3 +103,7 @@ schema-dump: test-db-create
 	@echo "$(GREEN)Regenerating api/database/schema/mysql-schema.sql...$(NC)"
 	@cd api && DB_DATABASE=crewli_test php artisan schema:dump --database=mysql
 	@echo "$(YELLOW)Note: Commit the updated schema dump alongside any new migrations.$(NC)"
+
+storybook:
+	@echo "$(GREEN)Starting Storybook → http://localhost:6006$(NC)"
+	@cd apps/app && pnpm storybook

README.md

@@ -21,10 +21,9 @@ Implementation is phased; the authoritative feature and schema list lives in the
 
 | App | Path | Port | Role |
 |-----|------|------|------|
-| **Organizer** | `apps/app/` | 5174 | Main product for **org and event staff**: events, sections, shifts, people, artists, accreditation, briefings, reports. Includes **Platform Admin** section for super admins (`/platform/*`). |
-| **Portal** | `apps/portal/` | 5175 | **External** users: stripped layout; login- or token-based access. |
+| **SPA** | `apps/app/` | 5174 | Single-SPA product covering **organizers, volunteers, crew, super admins** (context-routed in-app), plus token-based access for artists, suppliers, press. Includes **Platform Admin** section for super admins (`/platform/*`). |
 
-All apps talk to the API over **CORS** with **Laravel Sanctum** tokens.
+The SPA talks to the API over **CORS** with **Laravel Sanctum** tokens.
 
 ---
 
@@ -125,13 +124,12 @@ make db-shell
 
 | Resource | Contents |
 |----------|----------|
-| [resources/design/](resources/design/) | **Canonical product specs** in Markdown. Referenced by `.cursor` and `CLAUDE.md` as source of truth for features and data model: `design-document.md`, `dev-guide.md`, `start-guide.md`. |
-| [.cursor/ARCHITECTURE.md](.cursor/ARCHITECTURE.md) | System diagram, apps, multi-tenancy, roles, event lifecycle, API route map, core schema overview (summarises `resources/design` when present) |
-| [.cursor/instructions.md](.cursor/instructions.md) | Quick reference, phased roadmap, module build order |
-| [.cursor/rules/](.cursor/rules/) | Workspace, Laravel, Vue, testing conventions |
-| [docs/SETUP.md](docs/SETUP.md) | Environment and local setup |
-| [docs/API.md](docs/API.md) | API notes (if maintained) |
-| [docs/SCHEMA.md](docs/SCHEMA.md) | Schema notes (if maintained) |
+| [CLAUDE.md](CLAUDE.md) | Project conventions, vibe-coding principles, Vuexy-first decision tree (auto-loaded by Claude Code). |
+| [.cursor/rules/](.cursor/rules/) | Workspace, Laravel, Vue, testing conventions. |
+| [dev-docs/SETUP.md](dev-docs/SETUP.md) | Environment and local setup. |
+| [dev-docs/SCHEMA.md](dev-docs/SCHEMA.md) | Database schema (kept in sync with migrations). |
+| [dev-docs/API.md](dev-docs/API.md) | API contract. |
+| [dev-docs/design-document.md](dev-docs/design-document.md) | Product specification. |
 
 ---
 

api/.env.example

@@ -78,3 +78,14 @@ SANCTUM_STATEFUL_DOMAINS=localhost:5174,localhost:5175
 # env-gate + this flag) keeps Telescope out even if one layer is
 # breached. See /dev-docs/TELESCOPE.md.
 TELESCOPE_ENABLED=false
+
+# Sentry / GlitchTip (RFC-WS-7 §3.3, §3.4).
+# DSN routes events to the self-hosted GlitchTip project crewli-api.
+# Empty = SDK no-op — leave blank in local development. Source the real
+# value from the 1Password vault entry "Crewli / GlitchTip / DSNs"
+# (key SENTRY_DSN_BACKEND) for staging / production.
+SENTRY_DSN_BACKEND=
+# Release identifier in the form crewli-api@<short-sha>. The deploy
+# pipeline injects this per build; leave blank locally. Empty release
+# means events are still captured but won't carry release context.
+SENTRY_RELEASE=

api/app/Console/Commands/Artist/DemoteExpiredOptions.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands\Artist;
+
+use App\Enums\Artist\ArtistEngagementStatus;
+use App\Models\ArtistEngagement;
+use App\Models\Scopes\OrganisationScope;
+use App\Services\Artist\ArtistEngagementService;
+use Illuminate\Console\Command;
+
+/**
+ * RFC v0.2 — daily option-expiry demotion.
+ *
+ * Finds every engagement with booking_status = Option whose
+ * option_expires_at has passed, transitions it to Draft via the state
+ * machine (which records the transition activity entry), and writes
+ * an additional `option_expired` activity event so the audit log can
+ * distinguish system-driven expiries from manual demotions.
+ *
+ * Idempotency: the state machine returns immediately when the
+ * engagement is no longer in Option (e.g. another run already
+ * demoted it), so a second run within the same minute is a no-op
+ * for any given engagement.
+ *
+ * Notification: notification framework lands post-Accreditation. For
+ * Session 2 the command writes activity log only; emailing the
+ * project leader is tracked under BACKLOG entry
+ * ART-DEMOTE-NOTIFICATION.
+ */
+final class DemoteExpiredOptions extends Command
+{
+    protected $signature = 'artist:demote-expired-options';
+
+    protected $description = 'Demote ArtistEngagement rows whose option_expires_at has passed back to Draft.';
+
+    public function handle(ArtistEngagementService $service): int
+    {
+        $expired = ArtistEngagement::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('booking_status', ArtistEngagementStatus::Option->value)
+            ->whereNotNull('option_expires_at')
+            ->where('option_expires_at', '<=', now())
+            ->whereNull('deleted_at')
+            ->get();
+
+        $demotedIds = [];
+        foreach ($expired as $engagement) {
+            // Re-check status under fresh state — another worker / a
+            // user UI action may have already transitioned this row.
+            if ($engagement->booking_status !== ArtistEngagementStatus::Option) {
+                continue;
+            }
+
+            $service->transitionStatus($engagement, ArtistEngagementStatus::Draft);
+
+            activity('artist_engagement')
+                ->performedOn($engagement)
+                ->event('option_expired')
+                ->withProperties([
+                    'organisation_id' => $engagement->organisation_id,
+                    'event_id' => $engagement->event_id,
+                    'option_expires_at' => optional($engagement->option_expires_at)->toIso8601String(),
+                ])
+                ->log('option_expired');
+
+            $demotedIds[] = (string) $engagement->id;
+        }
+
+        $count = count($demotedIds);
+        $this->info("Demoted {$count} option(s) on ".now()->toDateString().'.');
+        if ($count > 0) {
+            $this->line('IDs: '.implode(', ', $demotedIds));
+        }
+
+        return self::SUCCESS;
+    }
+}

api/app/Console/Commands/SeedArtistAdvanceDefaultCommand.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Console\Commands;
+
+use App\FormBuilder\Defaults\ArtistAdvanceDefault;
+use App\Models\Organisation;
+use Illuminate\Console\Command;
+
+/**
+ * Seed the default artist_advance FormSchema for one organisation
+ * (by id) or for every organisation.
+ *
+ * The OrganisationObserver wires this for new tenants automatically;
+ * this command exists to backfill organisations that pre-date the
+ * RFC-TIMETABLE v0.2 D15 default. Idempotent — orgs that already own
+ * an artist_advance schema are skipped.
+ */
+final class SeedArtistAdvanceDefaultCommand extends Command
+{
+    protected $signature = 'artist:seed-advance-default {organisation? : Organisation ID; omit to seed every organisation}';
+
+    protected $description = 'Seed the default artist_advance FormSchema for one or every organisation.';
+
+    public function handle(): int
+    {
+        $organisationId = $this->argument('organisation');
+
+        $query = Organisation::query();
+        if (is_string($organisationId) && $organisationId !== '') {
+            $query->whereKey($organisationId);
+        }
+
+        $organisations = $query->get();
+        if ($organisations->isEmpty()) {
+            $this->error('No organisations matched the supplied filter.');
+
+            return self::FAILURE;
+        }
+
+        foreach ($organisations as $organisation) {
+            ArtistAdvanceDefault::seedFor($organisation);
+            $this->line(sprintf('  ✓ %s (%s)', $organisation->name, $organisation->id));
+        }
+
+        $this->info(sprintf('Seeded artist_advance defaults for %d organisation(s).', $organisations->count()));
+
+        return self::SUCCESS;
+    }
+}

api/app/Enums/Artist/AdvanceSectionSubmissionStatus.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Submission lifecycle status for an AdvanceSection.
+ *
+ * Per RFC-TIMETABLE v0.2 §5.3 (`advance_sections.submission_status`
+ * column).
+ */
+enum AdvanceSectionSubmissionStatus: string
+{
+    case Open = 'open';
+    case Pending = 'pending';
+    case Submitted = 'submitted';
+    case Approved = 'approved';
+    case Declined = 'declined';
+}

api/app/Enums/Artist/AdvanceSectionType.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Type-categorisation for an AdvanceSection.
+ *
+ * Per RFC-TIMETABLE v0.2 §5.3 (`advance_sections.type` column).
+ * Section labels live in the `name` column; this enum classifies
+ * the section for downstream behaviour (rendering, defaults).
+ */
+enum AdvanceSectionType: string
+{
+    case GuestList = 'guest_list';
+    case Contacts = 'contacts';
+    case Production = 'production';
+    case Custom = 'custom';
+}

api/app/Enums/Artist/AdvanceSubmissionStatus.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Review status for an individual AdvanceSubmission row.
+ *
+ * Per RFC-TIMETABLE v0.2 §5.3 (`advance_submissions.status`).
+ */
+enum AdvanceSubmissionStatus: string
+{
+    case Pending = 'pending';
+    case Accepted = 'accepted';
+    case Declined = 'declined';
+}

api/app/Enums/Artist/ArtistEngagementStatus.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Booking status for an ArtistEngagement (per-event booking).
+ *
+ * Per RFC-TIMETABLE v0.2 D9 — 9 states. `Cancelled`, `Rejected`,
+ * `Declined` are three distinct end-states for reporting.
+ */
+enum ArtistEngagementStatus: string
+{
+    case Draft = 'draft';
+    case Requested = 'requested';
+    case Option = 'option';
+    case Offered = 'offered';
+    case Confirmed = 'confirmed';
+    case Contracted = 'contracted';
+    case Cancelled = 'cancelled';
+    case Rejected = 'rejected';
+    case Declined = 'declined';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Draft => 'Concept',
+            self::Requested => 'Aangevraagd',
+            self::Option => 'Optie',
+            self::Offered => 'Aanbod uit',
+            self::Confirmed => 'Bevestigd',
+            self::Contracted => 'Gecontracteerd',
+            self::Cancelled => 'Geannuleerd',
+            self::Rejected => 'Afgewezen',
+            self::Declined => 'Bedankt',
+        };
+    }
+}

api/app/Enums/Artist/BumaHandledBy.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Who handles BUMA reporting/payment for a given engagement.
+ *
+ * Per RFC-TIMETABLE v0.2 D26.
+ */
+enum BumaHandledBy: string
+{
+    case Organisation = 'organisation';
+    case BookingAgency = 'booking_agency';
+    case NotApplicable = 'not_applicable';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Organisation => 'Organisatie',
+            self::BookingAgency => 'Boekingsagent',
+            self::NotApplicable => 'Niet van toepassing',
+        };
+    }
+}

api/app/Enums/Artist/FeeType.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Deal-fee structure for an ArtistEngagement.
+ *
+ * Per RFC-TIMETABLE v0.2 §5.3 (`fee_type` column).
+ */
+enum FeeType: string
+{
+    case Flat = 'flat';
+    case DoorSplit = 'door_split';
+    case GuaranteePlusSplit = 'guarantee_plus_split';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::Flat => 'Vaste fee',
+            self::DoorSplit => 'Door split',
+            self::GuaranteePlusSplit => 'Garantie + split',
+        };
+    }
+}

api/app/Enums/Artist/PaymentStatus.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Artist;
+
+/**
+ * Payment progress for an ArtistEngagement.
+ *
+ * Per RFC-TIMETABLE v0.2 §5.3 (`payment_status` column).
+ */
+enum PaymentStatus: string
+{
+    case None = 'none';
+    case DepositPaid = 'deposit_paid';
+    case PaidInFull = 'paid_in_full';
+
+    public function label(): string
+    {
+        return match ($this) {
+            self::None => 'Geen betaling',
+            self::DepositPaid => 'Aanbetaling voldaan',
+            self::PaidInFull => 'Volledig voldaan',
+        };
+    }
+}

api/app/Enums/FormBuilder/FormFieldBindingMergeStrategy.php

@@ -37,4 +37,31 @@ enum FormFieldBindingMergeStrategy: string
     {
         return $this !== self::Append;
     }
+
+    /**
+     * Whether this strategy is structurally valid against the given target
+     * type.
+     *
+     * Per RFC-WS-6 §V1 + ARCH-BINDINGS §4.2 (strategy x target-type validity matrix).
+     *
+     *                  | SCALAR | COLLECTION | RELATION |
+     *  Overwrite       | valid  | valid*     | valid    |
+     *  Append          | INVALID| valid      | INVALID  |
+     *  Replace         | valid  | valid      | valid    |
+     *  FirstWriteWins  | valid  | valid      | valid    |
+     *
+     *  * unusual but valid (overwrites entire collection)
+     *
+     * The PublishGuard AppendStrategyRequiresCollectionTarget uses this
+     * method to validate at publish time. Append on scalars is rejected
+     * because it requires a fingerprint mechanism for retry-idempotency
+     * that would embed implementation detail in domain data.
+     */
+    public function validForTargetType(BindingTargetType $type): bool
+    {
+        return match ($this) {
+            self::Append => $type === BindingTargetType::COLLECTION,
+            default => true,
+        };
+    }
 }

api/app/Enums/Observability/ActorType.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Enums\Observability;
+
+use App\Models\User;
+use Illuminate\Contracts\Auth\Authenticatable;
+use Illuminate\Http\Request;
+
+/**
+ * Actor classification used as the `actor_type` Sentry tag (RFC-WS-7 §3.6).
+ *
+ * Resolution precedence (most specific first):
+ *  1. Portal-token request → PORTAL_TOKEN
+ *  2. Authenticated super_admin → SUPER_ADMIN
+ *  3. Authenticated org_admin → ORGANIZER_ADMIN
+ *  4. Other authenticated user → ORG_MEMBER
+ *  5. None of the above → UNAUTHENTICATED
+ *
+ * Crewli has no dedicated `volunteer` Spatie role today; volunteer-ness is
+ * behaviour (a user has shift assignments) rather than identity. A
+ * dedicated VOLUNTEER actor_type case will land alongside that role split
+ * if/when it is introduced (BACKLOG OBS-1).
+ */
+enum ActorType: string
+{
+    case ORGANIZER_ADMIN = 'organizer_admin';
+    case SUPER_ADMIN = 'super_admin';
+    case PORTAL_TOKEN = 'portal_token';
+    case ORG_MEMBER = 'org_member';
+    case UNAUTHENTICATED = 'unauthenticated';
+
+    public static function resolve(?Authenticatable $user, ?Request $request): self
+    {
+        if ($request !== null && $request->attributes->get('portal_context') !== null) {
+            return self::PORTAL_TOKEN;
+        }
+
+        if (! $user instanceof User) {
+            return self::UNAUTHENTICATED;
+        }
+
+        if ($user->hasRole('super_admin')) {
+            return self::SUPER_ADMIN;
+        }
+
+        if ($user->hasRole('org_admin')) {
+            return self::ORGANIZER_ADMIN;
+        }
+
+        return self::ORG_MEMBER;
+    }
+}

api/app/Events/FormBuilder/FormSubmissionIdentityMatchResolved.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events\FormBuilder;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Broadcasting\PrivateChannel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Broadcast when TriggerPersonIdentityMatchOnFormSubmit (D2) writes the
+ * final identity_match_status. Frontend portal IdentityMatchBanner
+ * subscribes to this channel and refetches the submission resource on
+ * receipt, so the banner copy transitions from "we're checking matches…"
+ * to the final state without a manual reload.
+ *
+ * Per RFC-WS-6 §Q1 v1.3 addition 2.
+ *
+ * Wiring (the dispatch call from TriggerPersonIdentityMatchOnFormSubmit::handle)
+ * lands in D2. This class exists in D1 so D2's wiring is a one-liner.
+ */
+final class FormSubmissionIdentityMatchResolved implements ShouldBroadcast
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    public function __construct(
+        public readonly string $submissionId,
+        public readonly string $status,        // 'matched' | 'no_match' | 'multiple_candidates'
+        public readonly int $matchCount,
+    ) {}
+
+    /**
+     * Private channel keyed on submission ULID.
+     *
+     * Frontend subscribes via `Echo.private('submission.${submissionId}')`.
+     * Authorization (only the submitter / organisation admins can subscribe)
+     * is the responsibility of the channel-authorization callback in
+     * routes/channels.php — that wiring lands in D2 alongside the dispatch.
+     *
+     * @return array<int, PrivateChannel>
+     */
+    public function broadcastOn(): array
+    {
+        return [
+            new PrivateChannel("submission.{$this->submissionId}"),
+        ];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'identity-match.resolved';
+    }
+}

api/app/Exceptions/Artist/ArtistDeletedException.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use DomainException;
+
+/**
+ * Raised by ArtistResolver::fromPortalToken when the engagement's
+ * portal_token matches but the master Artist has been soft-deleted.
+ * Per RFC v0.2 D27 the engagement itself remains usable; the portal
+ * flow surfaces a clear 410 Gone rather than crashing on a null
+ * subject downstream.
+ */
+final class ArtistDeletedException extends DomainException
+{
+    public function __construct(public readonly string $engagementId)
+    {
+        parent::__construct(sprintf(
+            'Master Artist for engagement %s has been deleted; portal flow is not available.',
+            $engagementId,
+        ));
+    }
+}

api/app/Exceptions/Artist/CrossTenantEngagementException.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use App\Models\ArtistEngagement;
+use DomainException;
+
+/**
+ * Raised when an ArtistEngagement is being created with an artist and
+ * event that belong to different organisations. The engagement's
+ * `organisation_id` is denormalised from the artist (RFC v0.2 D10);
+ * the event must match. Cross-tenant linkage is a hard error — fail
+ * loud rather than silently denormalise the wrong tenant.
+ */
+final class CrossTenantEngagementException extends DomainException
+{
+    public static function forEngagement(ArtistEngagement $engagement): self
+    {
+        return new self(sprintf(
+            'ArtistEngagement cross-tenant: artist=%s (org=%s) vs event=%s (org=%s).',
+            $engagement->artist_id ?? 'null',
+            $engagement->artist?->organisation_id ?? 'null',
+            $engagement->event_id ?? 'null',
+            $engagement->event?->organisation_id ?? 'null',
+        ));
+    }
+}

api/app/Exceptions/Artist/DuplicateArtistException.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use App\Models\Artist;
+use DomainException;
+
+/**
+ * Raised by ArtistService::create when an exact-name match (case-insensitive)
+ * already exists in the same organisation. The handler can surface the
+ * existing artist's id to the UI so a "use existing or rename" choice is
+ * presented to the booker.
+ */
+final class DuplicateArtistException extends DomainException
+{
+    public function __construct(
+        public readonly Artist $existing,
+        string $message = 'An artist with this name already exists in this organisation.',
+    ) {
+        parent::__construct($message);
+    }
+}

api/app/Exceptions/Artist/GenreInUseException.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use App\Models\Genre;
+use DomainException;
+
+/**
+ * Raised by GenreService::delete when artists still reference this genre
+ * via `default_genre_id`. The frontend must offer to re-bind those
+ * artists to a different genre (or null) before retrying.
+ */
+final class GenreInUseException extends DomainException
+{
+    public function __construct(
+        public readonly Genre $genre,
+        public readonly int $referencingArtistsCount,
+    ) {
+        parent::__construct(sprintf(
+            'Genre "%s" cannot be deleted: %d artist(s) reference it as their default genre.',
+            $genre->name,
+            $referencingArtistsCount,
+        ));
+    }
+}

api/app/Exceptions/Artist/InvalidPortalTokenException.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use DomainException;
+
+/**
+ * Raised by ArtistResolver::fromPortalToken when the supplied portal
+ * token does not match any active artist_engagements row. Maps to a
+ * 404 at the HTTP boundary — distinguishes from ArtistDeletedException
+ * (engagement exists but master Artist is soft-deleted, → 410 Gone).
+ */
+final class InvalidPortalTokenException extends DomainException
+{
+    public static function create(): self
+    {
+        return new self('Portal token does not resolve to an active engagement.');
+    }
+}

api/app/Exceptions/Artist/InvalidStatusTransitionException.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use App\Enums\Artist\ArtistEngagementStatus;
+use DomainException;
+
+/**
+ * Raised when a booking_status transition is rejected by the
+ * ArtistEngagement state machine (RFC v0.2 §10.1).
+ */
+final class InvalidStatusTransitionException extends DomainException
+{
+    public function __construct(
+        public readonly ArtistEngagementStatus $from,
+        public readonly ArtistEngagementStatus $to,
+        public readonly string $reason,
+    ) {
+        parent::__construct(sprintf(
+            'Invalid booking_status transition %s → %s: %s',
+            $from->value,
+            $to->value,
+            $reason,
+        ));
+    }
+}

api/app/Exceptions/Artist/StageDaysOrphanedPerformancesException.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use DomainException;
+
+/**
+ * Raised by StageDayService::replaceDays when the proposed event_ids
+ * would remove a day that still has non-cancelled performances scheduled
+ * on it. The frontend re-prompts the user with a confirmation dialog
+ * and re-submits with `?force_orphan=true` to acknowledge the orphans.
+ *
+ * Controller maps to HTTP 409 with body
+ * `{conflict: 'orphaned_performances', performances_on_removed_events: [...]}`.
+ */
+final class StageDaysOrphanedPerformancesException extends DomainException
+{
+    /**
+     * @param  array<int, string>  $performanceIds
+     * @param  array<int, string>  $removedEventIds
+     */
+    public function __construct(
+        public readonly array $performanceIds,
+        public readonly array $removedEventIds,
+    ) {
+        parent::__construct(sprintf(
+            'Stage-day removal would orphan %d performance(s) on %d event(s).',
+            count($performanceIds),
+            count($removedEventIds),
+        ));
+    }
+}

api/app/Exceptions/Artist/VersionMismatchException.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\Artist;
+
+use DomainException;
+
+/**
+ * Raised by LaneCascadeService::move when the client-supplied version
+ * does not match the row's current version (RFC v0.2 D14 — optimistic
+ * locking on Performance). Controller maps to HTTP 409 with body
+ * `{conflict: 'version_mismatch', current_version: N, server_data: …}`.
+ */
+final class VersionMismatchException extends DomainException
+{
+    public function __construct(
+        public readonly int $currentVersion,
+        public readonly int $clientVersion,
+    ) {
+        parent::__construct(sprintf(
+            'Performance version mismatch: server=%d, client=%d.',
+            $currentVersion,
+            $clientVersion,
+        ));
+    }
+}

api/app/Exceptions/FormBuilder/FormBindingApplicatorException.php

@@ -5,19 +5,48 @@ declare(strict_types=1);
 namespace App\Exceptions\FormBuilder;
 
 use RuntimeException;
+use Throwable;
 
 /**
- * RFC-WS-6 §3 (Q3) — catastrophic applicator failure that bubbles to
- * the caller. Per-binding failures are captured in BindingPassResult,
- * not thrown.
+ * Base for all FormBindingApplicator-pipeline exceptions.
+ *
+ * Subclasses provide a `reasonCode()` that maps to:
+ * - failure_response_code on form_submissions (response-shape driver)
+ * - HTTP status code (422 / 503 / 500)
+ * - user-facing copy class (rendered by frontend)
+ *
+ * Per RFC-WS-6 §Q3 v1.3 addition 2.
+ *
+ * Concrete subclasses:
+ * - FormBindingSchemaConfigException — schema misconfiguration (422, schema_config_error)
+ * - FormBindingInfraException — infra issue, retryable (503, temporary_error)
+ *   - FormBindingApplicatorTimeoutException — deadline-wrapper exceeded (extends Infra)
+ * - FormBindingDataIntegrityException — data shape violation (422, data_integrity_error)
+ *
+ * The classifier (FormBindingExceptionClassifier) maps unknown Throwables
+ * to 'unknown_error' — that is the fallback for anything not in this
+ * hierarchy.
+ *
+ * `submissionId` is preserved as a public readonly property so D2's
+ * outer-transaction handler can structurally read it when writing the
+ * `form_submission_action_failures.context` JSON, instead of regex-parsing
+ * the message string.
  */
-final class FormBindingApplicatorException extends RuntimeException
+abstract class FormBindingApplicatorException extends RuntimeException
 {
     public function __construct(
-        public readonly string $reasonCode,
         public readonly string $submissionId,
-        ?string $message = null,
+        string $message,
+        ?Throwable $previous = null,
     ) {
-        parent::__construct($message ?? "FormBindingApplicator failed: {$reasonCode} (submission {$submissionId})");
+        parent::__construct($message, 0, $previous);
     }
+
+    /**
+     * Response-shape classification token. One of:
+     * - 'schema_config_error'
+     * - 'temporary_error'
+     * - 'data_integrity_error'
+     */
+    abstract public function reasonCode(): string;
 }

api/app/Exceptions/FormBuilder/FormBindingApplicatorTimeoutException.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+/**
+ * Thrown by the deadline-wrapper around FormBindingApplicator when the
+ * inner transaction takes longer than config('form_builder.apply_deadline_seconds')
+ * (default 5).
+ *
+ * Extends FormBindingInfraException because from the user's perspective a
+ * timeout is identical to any other temporary infra issue: retry should
+ * help. The response-shape classification 'temporary_error' is inherited.
+ *
+ * Per RFC-WS-6 §Q1 v1.3 addition 4.
+ *
+ * The deadline-wrapper itself lands in D2 (modification to
+ * ApplyBindingsOnFormSubmit's apply call site). This class exists in D1
+ * so D2's wiring is straightforward.
+ */
+final class FormBindingApplicatorTimeoutException extends FormBindingInfraException
+{
+    // No reasonCode override — inherits 'temporary_error' from FormBindingInfraException.
+    // No constructor override — inherits (submissionId, message, previous) from the base.
+}

api/app/Exceptions/FormBuilder/FormBindingDataIntegrityException.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+/**
+ * Data shape violation during binding apply.
+ *
+ * Examples: type mismatch between form_value and target attribute;
+ * foreign-key violation when the target references a soft-deleted entity;
+ * attempt to write to a column that has a unique constraint already
+ * violated by another row outside this submission.
+ *
+ * User-perceptible the same as schema_config (organiser fix needed); admin
+ * sees the difference via the exception class on the action-failures row.
+ *
+ * Maps to HTTP 422, failure_response_code='data_integrity_error'.
+ *
+ * Per RFC-WS-6 §Q3 v1.3 addition 2.
+ */
+final class FormBindingDataIntegrityException extends FormBindingApplicatorException
+{
+    public function reasonCode(): string
+    {
+        return 'data_integrity_error';
+    }
+}

api/app/Exceptions/FormBuilder/FormBindingInfraException.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+/**
+ * Infrastructure issue during binding apply.
+ *
+ * Examples: database connection lost, lock-for-update wait exceeded,
+ * race condition surfaced as a constraint violation that retry would
+ * resolve, applicator invoked outside a DB transaction (developer-error
+ * surfacing as infra-triage workflow).
+ *
+ * Maps to HTTP 503, failure_response_code='temporary_error'.
+ * User-facing copy: "Temporary issue, please try again." with retry-after.
+ *
+ * NOT final — FormBindingApplicatorTimeoutException extends this class.
+ *
+ * Per RFC-WS-6 §Q3 v1.3 addition 2.
+ */
+class FormBindingInfraException extends FormBindingApplicatorException
+{
+    public function reasonCode(): string
+    {
+        return 'temporary_error';
+    }
+}

api/app/Exceptions/FormBuilder/FormBindingSchemaConfigException.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+/**
+ * Schema misconfiguration that publish-guards missed.
+ *
+ * Examples: column renamed without schema invalidation; binding target
+ * attribute that no longer exists on the entity; merge_strategy that's
+ * structurally invalid for the target type but passed publish for some
+ * reason; unregistered purpose value; null schema relation.
+ *
+ * Maps to HTTP 422, failure_response_code='schema_config_error'.
+ * User-facing copy: "This form has a configuration issue. Please contact
+ * the organiser. Reference: F-{ulid}"
+ *
+ * Per RFC-WS-6 §Q3 v1.3 addition 2.
+ */
+final class FormBindingSchemaConfigException extends FormBindingApplicatorException
+{
+    public function reasonCode(): string
+    {
+        return 'schema_config_error';
+    }
+}

api/app/Exceptions/FormBuilder/IdentityMatchInvariantViolation.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Exceptions\FormBuilder;
+
+use DomainException;
+
+/**
+ * Thrown by TriggerPersonIdentityMatchOnFormSubmit when the post-ApplyBindings
+ * invariant breaks.
+ *
+ * Per RFC-WS-6 §Q2 + ARCH-BINDINGS §7.3:
+ *   Post ApplyBindingsOnFormSubmit::handle for event_registration purpose:
+ *   subject_type='person' AND subject_id IS NOT NULL,
+ *   OR apply_status=ApplyStatus::FAILED.
+ *   No third state exists. Violation is a structural defect.
+ *
+ * This is NOT a FormBindingApplicatorException — the listener that throws
+ * this does not run inside the FormBindingApplicator pipeline. It indicates
+ * the pipeline succeeded according to apply_status but produced incoherent
+ * subject state, which means a publish-guard gap or a race with manual
+ * data manipulation.
+ *
+ * Routed via Laravel queue worker → GlitchTip + form_submission_action_failures
+ * row (the catch + outer-transaction handler in TriggerPersonIdentityMatchOnFormSubmit
+ * mirrors ApplyBindingsOnFormSubmit's pattern). Wiring lands in D2.
+ */
+final class IdentityMatchInvariantViolation extends DomainException
+{
+    // Plain DomainException subclass. No reasonCode — when this fires,
+    // 'unknown_error' (the classifier's default fallback) is the right
+    // response-shape because users cannot meaningfully act on it; admins
+    // triage via GlitchTip. D2's invariant-throw path writes its own
+    // context JSON to form_submission_action_failures.
+}

api/app/FormBuilder/Bindings/FormBindingApplicator.php

@@ -7,6 +7,9 @@ namespace App\FormBuilder\Bindings;
 use App\Enums\FormBuilder\BindingTargetType;
 use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
 use App\Exceptions\FormBuilder\FormBindingApplicatorException;
+use App\Exceptions\FormBuilder\FormBindingApplicatorTimeoutException;
+use App\Exceptions\FormBuilder\FormBindingInfraException;
+use App\Exceptions\FormBuilder\FormBindingSchemaConfigException;
 use App\FormBuilder\Purposes\PurposeRegistry;
 use App\Models\FormBuilder\FormSubmission;
 use Illuminate\Database\Eloquent\Model;
@@ -26,6 +29,10 @@ use Throwable;
  *   - Q9: subject resolution via per-purpose PurposeSubjectResolver.
  *   - Q10: optional sectionId for future section-level apply.
  *   - Q12: hierarchical activity log via BindingActivityLogger.
+ *   - v1.3 Q1 add 4: optional deadline (withDeadline()) — soft post-call
+ *     microtime check throwing FormBindingApplicatorTimeoutException.
+ *     Cannot interrupt mid-query; intended to catch the long-tail of
+ *     slow applies before they hang the public flow.
  */
 // Not final + not readonly: listener tests need to override `apply()` for
 // throw-path coverage (Mockery can't mock final classes; PHP doesn't allow
@@ -33,6 +40,15 @@ use Throwable;
 // individually to preserve immutability.
 class FormBindingApplicator
 {
+    /**
+     * Per RFC-WS-6 §Q1 v1.3 addition 4 — soft deadline (seconds). NULL
+     * means "no deadline check" (default). Set via withDeadline() so the
+     * value travels with a clone and the original instance stays
+     * deadline-free for other callers (e.g. the retry-service path,
+     * which currently does not bound apply() — see ARCH-BINDINGS §5.3).
+     */
+    private ?int $deadlineSeconds = null;
+
     public function __construct(
         private readonly PurposeRegistry $purposeRegistry,
         private readonly BindingConflictResolver $conflictResolver,
@@ -40,33 +56,54 @@ class FormBindingApplicator
         private readonly BindingActivityLogger $activityLogger,
     ) {}
 
+    /**
+     * Returns a clone configured to throw FormBindingApplicatorTimeoutException
+     * if apply() exceeds the given deadline.
+     *
+     * Per RFC-WS-6 §Q1 v1.3 addition 4 + ARCH-BINDINGS §5.3.
+     *
+     * Implementation note: this is a soft post-call deadline check via
+     * microtime. It cannot interrupt mid-query — for that, configure MySQL
+     * connection timeouts at the database driver level. The soft deadline
+     * is sufficient to prevent runaway apply() calls from hanging the
+     * public flow indefinitely; a typical apply() takes <100ms, so a 5s
+     * deadline catches the long tail.
+     */
+    public function withDeadline(int $seconds): self
+    {
+        $clone = clone $this;
+        $clone->deadlineSeconds = $seconds;
+
+        return $clone;
+    }
+
     /**
      * @throws FormBindingApplicatorException
      */
     public function apply(FormSubmission $submission, ?string $sectionId = null): BindingPassResult
     {
+        $start = microtime(true);
+
         if (DB::transactionLevel() < 1) {
-            throw new FormBindingApplicatorException(
-                'no_transaction',
-                (string) $submission->id,
-                'FormBindingApplicator must be invoked inside DB::transaction',
+            throw new FormBindingInfraException(
+                submissionId: (string) $submission->id,
+                message: 'FormBindingApplicator must be invoked inside DB::transaction',
             );
         }
 
         /** @var \App\Models\FormBuilder\FormSchema|null $schema */
         $schema = $submission->schema;
         if ($schema === null) {
-            throw new FormBindingApplicatorException(
-                'no_schema',
-                (string) $submission->id,
+            throw new FormBindingSchemaConfigException(
+                submissionId: (string) $submission->id,
+                message: "schema null for submission {$submission->id}",
             );
         }
         $purposeValue = $schema->purpose->value;
         if (! $this->purposeRegistry->has($purposeValue)) {
-            throw new FormBindingApplicatorException(
-                'unknown_purpose',
-                (string) $submission->id,
-                "purpose '{$purposeValue}' not registered",
+            throw new FormBindingSchemaConfigException(
+                submissionId: (string) $submission->id,
+                message: "purpose '{$purposeValue}' not registered",
             );
         }
 
@@ -81,38 +118,61 @@ class FormBindingApplicator
                 provisionedSubjectId: null,
                 applications: [],
             );
-            $this->activityLogger->logPass($submission, $result);
+        } else {
+            $resolved = $this->conflictResolver->resolve($submission, $sectionId);
 
-            return $result;
-        }
-
-        $resolved = $this->conflictResolver->resolve($submission, $sectionId);
-
-        // Persist subject identity for the result + apply each binding.
-        $applications = [];
-        foreach ($resolved as $binding) {
-            // Skip identity-key bindings — the resolver already used them
-            // for subject lookup in EventRegistration's PersonProvisioner
-            // path. Writing them again is a no-op at best, a clobber at
-            // worst.
-            if ($binding->isIdentityKey) {
-                continue;
+            // Persist subject identity for the result + apply each binding.
+            $applications = [];
+            foreach ($resolved as $binding) {
+                // Skip identity-key bindings — the resolver already used them
+                // for subject lookup in EventRegistration's PersonProvisioner
+                // path. Writing them again is a no-op at best, a clobber at
+                // worst.
+                if ($binding->isIdentityKey) {
+                    continue;
+                }
+                $applications[] = $this->applyOne($subject, $binding);
             }
-            $applications[] = $this->applyOne($subject, $binding);
-        }
 
-        $result = new BindingPassResult(
-            formSubmissionId: (string) $submission->id,
-            provisionedSubjectType: $this->morphAlias($subject),
-            provisionedSubjectId: (string) $subject->getKey(),
-            applications: $applications,
-        );
+            $result = new BindingPassResult(
+                formSubmissionId: (string) $submission->id,
+                provisionedSubjectType: $this->morphAlias($subject),
+                provisionedSubjectId: (string) $subject->getKey(),
+                applications: $applications,
+            );
+        }
 
         $this->activityLogger->logPass($submission, $result);
 
+        $this->checkDeadline((string) $submission->id, $start);
+
         return $result;
     }
 
+    /**
+     * Throws FormBindingApplicatorTimeoutException if a deadline is
+     * configured and the elapsed wall-clock time exceeds it.
+     */
+    private function checkDeadline(string $submissionId, float $startMicrotime): void
+    {
+        if ($this->deadlineSeconds === null) {
+            return;
+        }
+
+        $elapsed = microtime(true) - $startMicrotime;
+        if ($elapsed > $this->deadlineSeconds) {
+            throw new FormBindingApplicatorTimeoutException(
+                submissionId: $submissionId,
+                message: sprintf(
+                    'FormBindingApplicator exceeded deadline of %ds (elapsed: %.2fs) for submission %s',
+                    $this->deadlineSeconds,
+                    $elapsed,
+                    $submissionId,
+                ),
+            );
+        }
+    }
+
     private function applyOne(Model $subject, ResolvedBinding $binding): BindingApplicationResult
     {
         try {
@@ -168,6 +228,7 @@ class FormBindingApplicator
         // Per-strategy matrix. RFC §3 Q7.
         if ($newValue === null) {
             $behaviour = $strategy->nullWinnerBehaviour();
+
             return match ($behaviour) {
                 'write' => null,
                 'noop' => self::NO_OP,

api/app/FormBuilder/Bindings/FormBindingExceptionClassifier.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Bindings;
+
+use App\Exceptions\FormBuilder\FormBindingApplicatorException;
+use Throwable;
+
+/**
+ * Maps a Throwable to a failure_response_code string.
+ *
+ * Used by both ApplyBindingsOnFormSubmit::handle's catch block (D2) and
+ * FormFailureRetryService::recordFailure (D2 update). Centralised so the
+ * listener and the retry-service produce identical classifications and a
+ * single behaviour change requires a single edit.
+ *
+ * Resolution order:
+ * 1. If the Throwable is a FormBindingApplicatorException, return its reasonCode().
+ *    Subclass dispatch handles SchemaConfig / Infra / DataIntegrity / Timeout
+ *    (Timeout extends Infra so it inherits 'temporary_error').
+ * 2. Otherwise, return 'unknown_error' — anything outside the hierarchy
+ *    (database connection lost not surfaced as Infra, generic RuntimeException
+ *    from a non-applicator code path, IdentityMatchInvariantViolation if it
+ *    somehow leaks here) is unknown from the response-shape perspective.
+ *
+ * Per RFC-WS-6 §Q3 v1.3 addition 2.
+ */
+final class FormBindingExceptionClassifier
+{
+    public static function classify(Throwable $exception): string
+    {
+        if ($exception instanceof FormBindingApplicatorException) {
+            return $exception->reasonCode();
+        }
+
+        return 'unknown_error';
+    }
+}

api/app/FormBuilder/Defaults/ArtistAdvanceDefault.php

@@ -0,0 +1,181 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Defaults;
+
+use App\Enums\Artist\AdvanceSectionType;
+use App\Enums\FormBuilder\FormFieldType;
+use App\Enums\FormBuilder\FormPurpose;
+use App\Enums\FormBuilder\FormSchemaSnapshotMode;
+use App\Enums\FormBuilder\FormSubmissionMode;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\FormBuilder\FormSchemaSection;
+use App\Models\Organisation;
+use App\Models\Scopes\OrganisationScope;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Default `artist_advance` FormSchema bootstrap per RFC-TIMETABLE
+ * v0.2 D15. One schema per organisation, with five sections mapped
+ * to AdvanceSectionType:
+ *
+ *   - General Info     → Custom
+ *   - Contacts         → Contacts
+ *   - Production       → Production
+ *   - Technical Rider  → Production
+ *   - Hospitality      → Custom
+ *
+ * Each section carries 3-4 illustrative fields. Organisations
+ * customise via the FormBuilder UI later. The schema is published
+ * and uses section_level_submit per ARCH-FORM-BUILDER §3.2.5.
+ *
+ * Idempotent: if an organisation already owns an artist_advance
+ * schema (any one), the seeder no-ops and returns the existing row.
+ *
+ * Bridge to per-engagement AdvanceSection rows: FormSchemaSection
+ * slug matches AdvanceSectionType::value (where applicable). Sections
+ * carrying type=Custom use a stable slug per row name.
+ */
+final class ArtistAdvanceDefault
+{
+    public static function seedFor(Organisation $organisation): FormSchema
+    {
+        $existing = FormSchema::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('organisation_id', $organisation->id)
+            ->where('purpose', FormPurpose::ARTIST_ADVANCE->value)
+            ->first();
+
+        if ($existing instanceof FormSchema) {
+            return $existing;
+        }
+
+        return DB::transaction(static function () use ($organisation): FormSchema {
+            $schema = FormSchema::create([
+                'organisation_id' => $organisation->id,
+                'owner_type' => 'organisation',
+                'owner_id' => $organisation->id,
+                'name' => 'Artiest advance',
+                'slug' => 'artiest-advance',
+                'purpose' => FormPurpose::ARTIST_ADVANCE->value,
+                'description' => 'Standaard advance-formulier voor artiesten. Pas de secties en velden aan via de FormBuilder.',
+                'is_published' => true,
+                'submission_mode' => FormSubmissionMode::DRAFT_SINGLE->value,
+                'locale' => 'nl',
+                'snapshot_mode' => FormSchemaSnapshotMode::ON_SUBMIT->value,
+                'freeze_on_submit' => false,
+                'section_level_submit' => true,
+                'auto_save_enabled' => true,
+                'version' => 1,
+            ]);
+
+            foreach (self::sectionDefinitions() as $sortOrder => $def) {
+                $section = FormSchemaSection::create([
+                    'form_schema_id' => $schema->id,
+                    'slug' => $def['slug'],
+                    'name' => $def['name'],
+                    'sort_order' => $sortOrder + 1,
+                    'submit_independent' => true,
+                    'required_for_schema_submit' => true,
+                ]);
+
+                foreach ($def['fields'] as $fieldOrder => $field) {
+                    FormField::create([
+                        'form_schema_id' => $schema->id,
+                        'form_schema_section_id' => $section->id,
+                        'field_type' => $field['type']->value,
+                        'slug' => $field['slug'],
+                        'label' => $field['label'],
+                        'help_text' => $field['help_text'] ?? null,
+                        'is_required' => $field['is_required'] ?? false,
+                        'is_filterable' => false,
+                        'is_portal_visible' => true,
+                        'is_admin_only' => false,
+                        'is_pii' => $field['is_pii'] ?? false,
+                        'display_width' => $field['display_width'] ?? 'full',
+                        'value_storage_hint' => ($field['type']->recommendedValueStorageHint())->value,
+                        'sort_order' => $fieldOrder + 1,
+                    ]);
+                }
+            }
+
+            return $schema->refresh();
+        });
+    }
+
+    /**
+     * @return array<int, array{
+     *   slug: string,
+     *   name: string,
+     *   advance_type: AdvanceSectionType,
+     *   fields: array<int, array{
+     *     type: FormFieldType,
+     *     slug: string,
+     *     label: string,
+     *     help_text?: string,
+     *     is_required?: bool,
+     *     is_pii?: bool,
+     *     display_width?: string,
+     *   }>
+     * }>
+     */
+    private static function sectionDefinitions(): array
+    {
+        return [
+            [
+                'slug' => 'general-info',
+                'name' => 'Algemeen',
+                'advance_type' => AdvanceSectionType::Custom,
+                'fields' => [
+                    ['type' => FormFieldType::DATETIME, 'slug' => 'arrival-datetime', 'label' => 'Aankomsttijd', 'is_required' => true, 'display_width' => 'half'],
+                    ['type' => FormFieldType::DATETIME, 'slug' => 'departure-datetime', 'label' => 'Vertrektijd', 'is_required' => true, 'display_width' => 'half'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'general-notes', 'label' => 'Opmerkingen'],
+                ],
+            ],
+            [
+                'slug' => 'contacts',
+                'name' => 'Contactpersonen',
+                'advance_type' => AdvanceSectionType::Contacts,
+                'fields' => [
+                    ['type' => FormFieldType::TEXT, 'slug' => 'tour-manager-name', 'label' => 'Tour manager', 'is_required' => true, 'is_pii' => true, 'display_width' => 'full'],
+                    ['type' => FormFieldType::EMAIL, 'slug' => 'tour-manager-email', 'label' => 'E-mail tour manager', 'is_required' => true, 'is_pii' => true, 'display_width' => 'half'],
+                    ['type' => FormFieldType::PHONE, 'slug' => 'tour-manager-phone', 'label' => 'Telefoon tour manager', 'is_pii' => true, 'display_width' => 'half'],
+                    ['type' => FormFieldType::TABLE_ROWS, 'slug' => 'additional-contacts', 'label' => 'Aanvullende contactpersonen', 'is_pii' => true],
+                ],
+            ],
+            [
+                'slug' => 'production',
+                'name' => 'Productie',
+                'advance_type' => AdvanceSectionType::Production,
+                'fields' => [
+                    ['type' => FormFieldType::FILE_UPLOAD, 'slug' => 'stage-plot', 'label' => 'Stage plot'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'monitor-needs', 'label' => 'Monitorwensen'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'special-equipment', 'label' => 'Specifieke apparatuur'],
+                ],
+            ],
+            [
+                'slug' => 'technical-rider',
+                'name' => 'Technische rider',
+                'advance_type' => AdvanceSectionType::Production,
+                'fields' => [
+                    ['type' => FormFieldType::FILE_UPLOAD, 'slug' => 'input-list', 'label' => 'Input list'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'microphone-preferences', 'label' => 'Microfoonvoorkeuren'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'backline-requirements', 'label' => 'Backline'],
+                ],
+            ],
+            [
+                'slug' => 'hospitality',
+                'name' => 'Hospitality',
+                'advance_type' => AdvanceSectionType::Custom,
+                'fields' => [
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'dressing-room-requirements', 'label' => 'Kleedkamer'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'food-preferences', 'label' => 'Cateringvoorkeuren'],
+                    ['type' => FormFieldType::TEXTAREA, 'slug' => 'drinks', 'label' => 'Drankvoorkeuren'],
+                    ['type' => FormFieldType::TEXT, 'slug' => 'allergies', 'label' => 'Allergieën', 'is_pii' => true],
+                ],
+            ],
+        ];
+    }
+}

api/app/FormBuilder/Resolvers/ArtistResolver.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Resolvers;
+
+use App\Exceptions\Artist\ArtistDeletedException;
+use App\Exceptions\Artist\InvalidPortalTokenException;
+use App\Models\Artist;
+use App\Models\ArtistEngagement;
+use App\Models\Scopes\OrganisationScope;
+
+/**
+ * Engagement-scoped subject resolution for the artist_advance portal
+ * flow. Per ARCH-FORM-BUILDER §17.3 footnote and RFC-TIMETABLE v0.2
+ * D15: the master Artist is the FormSubmission subject (subject_type
+ * = 'artist'), but the engagement provides the event_id (denormalised
+ * onto form_submissions per WS-4) and any advance_section context.
+ *
+ * The portal token itself is stored on artist_engagements.portal_token
+ * as a SHA-256 hex digest (Session 1 commit eb6d396). Callers pass
+ * the plaintext token; we hash and look up.
+ *
+ * This resolver is the single shared helper for portal-token →
+ * engagement resolution. PortalTokenMiddleware delegates to it; the
+ * EngagementPortalController calls it directly to produce the value
+ * object the FormSubmissionService needs.
+ */
+final class ArtistResolver
+{
+    public function fromPortalToken(string $portalToken): ArtistResolverResult
+    {
+        $digest = hash('sha256', $portalToken);
+
+        $engagement = ArtistEngagement::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('portal_token', $digest)
+            ->first();
+
+        if ($engagement === null) {
+            throw InvalidPortalTokenException::create();
+        }
+
+        $artist = Artist::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->whereKey($engagement->artist_id)
+            ->first();
+
+        if (! $artist instanceof Artist) {
+            throw new ArtistDeletedException((string) $engagement->id);
+        }
+
+        return new ArtistResolverResult(
+            subject: $artist,
+            eventId: (string) $engagement->event_id,
+            engagement: $engagement,
+        );
+    }
+}

api/app/FormBuilder/Resolvers/ArtistResolverResult.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\FormBuilder\Resolvers;
+
+use App\Models\Artist;
+use App\Models\ArtistEngagement;
+
+/**
+ * Value object returned by ArtistResolver::fromPortalToken.
+ *
+ * Per ARCH-FORM-BUILDER §17.3 footnote: artist_advance submissions use
+ * the master Artist as `subject` (preserves form_submissions.subject_type
+ * = 'artist'); `eventId` populates form_submissions.event_id per WS-4
+ * denormalisation; the engagement itself is returned so callers
+ * (controllers, listeners) can resolve advance_section context without
+ * a second query.
+ */
+final readonly class ArtistResolverResult
+{
+    public function __construct(
+        public Artist $subject,
+        public string $eventId,
+        public ArtistEngagement $engagement,
+    ) {}
+}

api/app/Http/Controllers/Api/V1/Artist/ArtistController.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Exceptions\Artist\DuplicateArtistException;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\CreateArtistRequest;
+use App\Http\Requests\Api\V1\Artist\UpdateArtistRequest;
+use App\Http\Resources\Api\V1\Artist\ArtistResource;
+use App\Models\Artist;
+use App\Models\Organisation;
+use App\Services\Artist\ArtistService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class ArtistController extends Controller
+{
+    public function __construct(
+        private readonly ArtistService $service,
+    ) {}
+
+    public function index(Request $request, Organisation $organisation): AnonymousResourceCollection
+    {
+        Gate::authorize('viewAny', [Artist::class, $organisation]);
+
+        $query = Artist::query()
+            ->where('organisation_id', $organisation->id)
+            ->with(['defaultGenre', 'agentCompany']);
+
+        if ($request->boolean('with_trashed')) {
+            $query->withTrashed();
+        }
+        if ($request->boolean('trashed_only')) {
+            $query->onlyTrashed();
+        }
+
+        if ($request->filled('search')) {
+            $term = '%'.$request->string('search').'%';
+            $query->where(function ($q) use ($term): void {
+                $q->where('name', 'like', $term)->orWhere('slug', 'like', $term);
+            });
+        }
+        if ($request->filled('genre_id')) {
+            $query->where('default_genre_id', $request->string('genre_id'));
+        }
+        if ($request->filled('agent_company_id')) {
+            $query->where('agent_company_id', $request->string('agent_company_id'));
+        }
+
+        return ArtistResource::collection($query->orderBy('name')->paginate(50));
+    }
+
+    public function show(Organisation $organisation, Artist $artist): JsonResponse
+    {
+        Gate::authorize('view', $artist);
+        $artist->loadMissing(['defaultGenre', 'agentCompany', 'contacts']);
+
+        return $this->success(ArtistResource::make($artist));
+    }
+
+    public function store(CreateArtistRequest $request, Organisation $organisation): JsonResponse
+    {
+        Gate::authorize('create', [Artist::class, $organisation]);
+
+        try {
+            $artist = $this->service->create($organisation, $request->validated());
+        } catch (DuplicateArtistException $e) {
+            return $this->error('Duplicate artist name.', 409, [
+                'duplicate_artist_id' => $e->existing->id,
+            ]);
+        }
+
+        return $this->created(ArtistResource::make($artist->load(['defaultGenre', 'agentCompany'])));
+    }
+
+    public function update(UpdateArtistRequest $request, Organisation $organisation, Artist $artist): JsonResponse
+    {
+        Gate::authorize('update', $artist);
+
+        $artist = $this->service->update($artist, $request->validated());
+
+        return $this->success(ArtistResource::make($artist->load(['defaultGenre', 'agentCompany'])));
+    }
+
+    public function destroy(Organisation $organisation, Artist $artist): JsonResponse
+    {
+        if (! Gate::check('delete', $artist)) {
+            return $this->forbidden('Cannot delete artist with active engagements.');
+        }
+
+        $this->service->softDelete($artist);
+
+        return response()->json(null, 204);
+    }
+
+    public function restore(Organisation $organisation, string $artist): JsonResponse
+    {
+        $model = Artist::withTrashed()->findOrFail($artist);
+        Gate::authorize('restore', $model);
+
+        $this->service->restore($model);
+
+        return $this->success(ArtistResource::make($model->fresh()));
+    }
+}

api/app/Http/Controllers/Api/V1/Artist/ArtistEngagementController.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Exceptions\Artist\InvalidStatusTransitionException;
+use App\Http\Controllers\Api\V1\Traits\VerifiesOrganisationEvent;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\CreateArtistEngagementRequest;
+use App\Http\Requests\Api\V1\Artist\UpdateArtistEngagementRequest;
+use App\Http\Resources\Api\V1\Artist\ArtistEngagementResource;
+use App\Models\Artist;
+use App\Models\ArtistEngagement;
+use App\Models\Event;
+use App\Models\Organisation;
+use App\Services\Artist\ArtistEngagementService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class ArtistEngagementController extends Controller
+{
+    use VerifiesOrganisationEvent;
+
+    public function __construct(
+        private readonly ArtistEngagementService $service,
+    ) {}
+
+    public function index(Request $request, Organisation $organisation, Event $event): AnonymousResourceCollection
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('viewAny', [ArtistEngagement::class, $event]);
+
+        $query = ArtistEngagement::query()
+            ->where('event_id', $event->id)
+            ->with(['artist.defaultGenre', 'projectLeader']);
+
+        if ($request->filled('status')) {
+            $query->where('booking_status', $request->string('status'));
+        }
+        if ($request->filled('search')) {
+            $term = '%'.$request->string('search').'%';
+            $query->whereHas('artist', fn ($q) => $q->where('name', 'like', $term));
+        }
+
+        return ArtistEngagementResource::collection(
+            $query->orderBy('created_at', 'desc')->paginate(50),
+        );
+    }
+
+    public function show(Organisation $organisation, Event $event, ArtistEngagement $engagement): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('view', [$engagement, $event]);
+
+        $engagement->loadMissing([
+            'artist.defaultGenre', 'artist.agentCompany', 'artist.contacts',
+            'projectLeader', 'performances.stage',
+        ]);
+
+        return $this->success(ArtistEngagementResource::make($engagement));
+    }
+
+    public function store(CreateArtistEngagementRequest $request, Organisation $organisation, Event $event): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('create', [ArtistEngagement::class, $event]);
+
+        $data = $request->validated();
+        $artist = Artist::query()->findOrFail($data['artist_id']);
+
+        try {
+            $engagement = $this->service->create($event, $artist, $data);
+        } catch (InvalidStatusTransitionException $e) {
+            return $this->error($e->getMessage(), 422);
+        }
+
+        return $this->created(
+            ArtistEngagementResource::make($engagement->load(['artist.defaultGenre', 'projectLeader'])),
+        );
+    }
+
+    public function update(
+        UpdateArtistEngagementRequest $request,
+        Organisation $organisation,
+        Event $event,
+        ArtistEngagement $engagement,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('update', [$engagement, $event]);
+
+        try {
+            $engagement = $this->service->update($engagement, $request->validated());
+        } catch (InvalidStatusTransitionException $e) {
+            return $this->error($e->getMessage(), 422);
+        }
+
+        return $this->success(
+            ArtistEngagementResource::make($engagement->load(['artist.defaultGenre', 'projectLeader'])),
+        );
+    }
+
+    public function destroy(
+        Organisation $organisation,
+        Event $event,
+        ArtistEngagement $engagement,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('delete', [$engagement, $event]);
+
+        $this->service->softDelete($engagement);
+
+        return response()->json(null, 204);
+    }
+}

api/app/Http/Controllers/Api/V1/Artist/GenreController.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Exceptions\Artist\GenreInUseException;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\CreateGenreRequest;
+use App\Http\Requests\Api\V1\Artist\UpdateGenreRequest;
+use App\Http\Resources\Api\V1\Artist\GenreResource;
+use App\Models\Genre;
+use App\Models\Organisation;
+use App\Services\Artist\GenreService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class GenreController extends Controller
+{
+    public function __construct(
+        private readonly GenreService $service,
+    ) {}
+
+    public function index(Organisation $organisation): AnonymousResourceCollection
+    {
+        Gate::authorize('viewAny', [Genre::class, $organisation]);
+
+        $genres = Genre::query()
+            ->where('organisation_id', $organisation->id)
+            ->orderBy('sort_order')
+            ->orderBy('name')
+            ->get();
+
+        return GenreResource::collection($genres);
+    }
+
+    public function store(CreateGenreRequest $request, Organisation $organisation): JsonResponse
+    {
+        Gate::authorize('create', [Genre::class, $organisation]);
+
+        $genre = $this->service->create($organisation, $request->validated());
+
+        return $this->created(GenreResource::make($genre));
+    }
+
+    public function update(UpdateGenreRequest $request, Organisation $organisation, Genre $genre): JsonResponse
+    {
+        Gate::authorize('update', $genre);
+
+        $genre = $this->service->update($genre, $request->validated());
+
+        return $this->success(GenreResource::make($genre));
+    }
+
+    public function destroy(Organisation $organisation, Genre $genre): JsonResponse
+    {
+        Gate::authorize('delete', $genre);
+
+        try {
+            $this->service->delete($genre);
+        } catch (GenreInUseException $e) {
+            return $this->error($e->getMessage(), 409, [
+                'referencing_artists_count' => $e->referencingArtistsCount,
+            ]);
+        }
+
+        return response()->json(null, 204);
+    }
+}

api/app/Http/Controllers/Api/V1/Artist/PerformanceController.php

@@ -0,0 +1,102 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Http\Controllers\Api\V1\Traits\VerifiesOrganisationEvent;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\CreatePerformanceRequest;
+use App\Http\Requests\Api\V1\Artist\UpdatePerformanceRequest;
+use App\Http\Resources\Api\V1\Artist\PerformanceResource;
+use App\Models\ArtistEngagement;
+use App\Models\Event;
+use App\Models\Organisation;
+use App\Models\Performance;
+use App\Services\Artist\PerformanceService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class PerformanceController extends Controller
+{
+    use VerifiesOrganisationEvent;
+
+    public function __construct(
+        private readonly PerformanceService $service,
+    ) {}
+
+    public function index(Request $request, Organisation $organisation, Event $event): AnonymousResourceCollection
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('viewAny', [Performance::class, $event]);
+
+        $query = Performance::query()
+            ->whereHas('engagement', fn ($q) => $q->where('event_id', $event->id))
+            ->with(['engagement.artist.defaultGenre', 'stage']);
+
+        if ($request->filled('day')) {
+            $query->where('event_id', $request->string('day'));
+        }
+        if ($request->query('stage_id') === 'null') {
+            $query->whereNull('stage_id');
+        } elseif ($request->filled('stage_id')) {
+            $query->where('stage_id', $request->string('stage_id'));
+        }
+
+        return PerformanceResource::collection($query->orderBy('start_at')->get());
+    }
+
+    public function show(Organisation $organisation, Event $event, Performance $performance): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('view', [$performance, $event]);
+
+        $performance->loadMissing(['engagement.artist.defaultGenre', 'stage']);
+
+        return $this->success(PerformanceResource::make($performance));
+    }
+
+    public function store(CreatePerformanceRequest $request, Organisation $organisation, Event $event): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('create', [Performance::class, $event]);
+
+        $data = $request->validated();
+        $engagement = ArtistEngagement::query()->findOrFail($data['engagement_id']);
+
+        $performance = $this->service->create($engagement, $data);
+
+        return $this->created(
+            PerformanceResource::make($performance->load(['engagement.artist.defaultGenre', 'stage'])),
+        );
+    }
+
+    public function update(
+        UpdatePerformanceRequest $request,
+        Organisation $organisation,
+        Event $event,
+        Performance $performance,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('update', [$performance, $event]);
+
+        $performance = $this->service->update($performance, $request->validated());
+
+        return $this->success(PerformanceResource::make($performance));
+    }
+
+    public function destroy(
+        Organisation $organisation,
+        Event $event,
+        Performance $performance,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('delete', [$performance, $event]);
+
+        $this->service->delete($performance);
+
+        return response()->json(null, 204);
+    }
+}

api/app/Http/Controllers/Api/V1/Artist/StageController.php

@@ -0,0 +1,131 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Exceptions\Artist\StageDaysOrphanedPerformancesException;
+use App\Http\Controllers\Api\V1\Traits\VerifiesOrganisationEvent;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\CreateStageRequest;
+use App\Http\Requests\Api\V1\Artist\ReorderStagesRequest;
+use App\Http\Requests\Api\V1\Artist\ReplaceStageDaysRequest;
+use App\Http\Requests\Api\V1\Artist\UpdateStageRequest;
+use App\Http\Resources\Api\V1\Artist\StageResource;
+use App\Models\Event;
+use App\Models\Organisation;
+use App\Models\Stage;
+use App\Services\Artist\StageDayService;
+use App\Services\Artist\StageService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class StageController extends Controller
+{
+    use VerifiesOrganisationEvent;
+
+    public function __construct(
+        private readonly StageService $stageService,
+        private readonly StageDayService $stageDayService,
+    ) {}
+
+    public function index(Organisation $organisation, Event $event): AnonymousResourceCollection
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('viewAny', [Stage::class, $event]);
+
+        $stages = Stage::query()
+            ->where('event_id', $event->id)
+            ->with('stageDays')
+            ->ordered()
+            ->get();
+
+        return StageResource::collection($stages);
+    }
+
+    public function show(Organisation $organisation, Event $event, Stage $stage): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('view', [$stage, $event]);
+
+        $stage->loadMissing('stageDays');
+
+        return $this->success(StageResource::make($stage));
+    }
+
+    public function store(CreateStageRequest $request, Organisation $organisation, Event $event): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('create', [Stage::class, $event]);
+
+        $stage = $this->stageService->create($event, $request->validated());
+
+        return $this->created(StageResource::make($stage));
+    }
+
+    public function update(UpdateStageRequest $request, Organisation $organisation, Event $event, Stage $stage): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('update', [$stage, $event]);
+
+        $stage = $this->stageService->update($stage, $request->validated());
+
+        return $this->success(StageResource::make($stage));
+    }
+
+    public function destroy(Organisation $organisation, Event $event, Stage $stage): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('delete', [$stage, $event]);
+
+        $parkedCount = $this->stageService->delete($stage);
+
+        return response()->json(['parked_performances' => $parkedCount], 200);
+    }
+
+    public function reorder(ReorderStagesRequest $request, Organisation $organisation, Event $event): JsonResponse
+    {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('reorder', [Stage::class, $event]);
+
+        $this->stageService->reorder($event, $request->validated('stage_ids'));
+
+        $stages = Stage::query()->where('event_id', $event->id)->ordered()->get();
+
+        return $this->success(StageResource::collection($stages));
+    }
+
+    public function replaceDays(
+        ReplaceStageDaysRequest $request,
+        Organisation $organisation,
+        Event $event,
+        Stage $stage,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+        Gate::authorize('update', [$stage, $event]);
+
+        $forceOrphan = $request->boolean('force_orphan')
+            || $request->query('force_orphan') === 'true';
+
+        try {
+            $diff = $this->stageDayService->replaceDays(
+                $stage,
+                $request->validated('event_ids'),
+                $forceOrphan,
+            );
+        } catch (StageDaysOrphanedPerformancesException $e) {
+            return $this->error('Removing day(s) would orphan scheduled performances.', 409, [
+                'conflict' => 'orphaned_performances',
+                'performances_on_removed_events' => $e->performanceIds,
+                'removed_event_ids' => $e->removedEventIds,
+            ]);
+        }
+
+        return $this->success([
+            'stage' => StageResource::make($stage->fresh()->load('stageDays')),
+            'added_event_ids' => $diff['added'],
+            'removed_event_ids' => $diff['removed'],
+        ]);
+    }
+}

api/app/Http/Controllers/Api/V1/Artist/TimetableMoveController.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Artist;
+
+use App\Exceptions\Artist\VersionMismatchException;
+use App\Http\Controllers\Api\V1\Traits\VerifiesOrganisationEvent;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Artist\MoveTimetablePerformanceRequest;
+use App\Http\Resources\Api\V1\Artist\PerformanceResource;
+use App\Models\Event;
+use App\Models\Organisation;
+use App\Models\Performance;
+use App\Models\Stage;
+use App\Services\Artist\LaneCascadeService;
+use Carbon\CarbonImmutable;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Gate;
+
+final class TimetableMoveController extends Controller
+{
+    use VerifiesOrganisationEvent;
+
+    public function __construct(
+        private readonly LaneCascadeService $service,
+    ) {}
+
+    public function __invoke(
+        MoveTimetablePerformanceRequest $request,
+        Organisation $organisation,
+        Event $event,
+    ): JsonResponse {
+        $this->verifyEventBelongsToOrganisation($organisation, $event);
+
+        $data = $request->validated();
+        $performance = Performance::query()->findOrFail($data['performance_id']);
+
+        Gate::authorize('move', [$performance, $event]);
+
+        $targetStage = isset($data['target_stage_id'])
+            ? Stage::query()->find($data['target_stage_id'])
+            : null;
+
+        $start = isset($data['target_start_at'])
+            ? CarbonImmutable::parse((string) $data['target_start_at'])
+            : null;
+        $end = isset($data['target_end_at'])
+            ? CarbonImmutable::parse((string) $data['target_end_at'])
+            : null;
+
+        try {
+            $result = $this->service->move(
+                performance: $performance,
+                targetStage: $targetStage,
+                start: $start,
+                end: $end,
+                targetLane: isset($data['target_lane']) ? (int) $data['target_lane'] : null,
+                clientVersion: (int) $data['version'],
+            );
+        } catch (VersionMismatchException $e) {
+            $performance->refresh();
+
+            return $this->error('Version mismatch — performance was modified by another request.', 409, [
+                'conflict' => 'version_mismatch',
+                'current_version' => $e->currentVersion,
+                'client_version' => $e->clientVersion,
+                'server_data' => PerformanceResource::make(
+                    $performance->load(['engagement.artist.defaultGenre', 'stage']),
+                )->toArray(request()),
+            ]);
+        }
+
+        return $this->success([
+            'moved' => PerformanceResource::make(
+                $result->moved->load(['engagement.artist.defaultGenre', 'stage']),
+            ),
+            'cascaded' => PerformanceResource::collection(
+                collect($result->cascaded)->each->load(['engagement.artist.defaultGenre', 'stage']),
+            ),
+        ]);
+    }
+}

api/app/Http/Controllers/Api/V1/Auth/MfaVerifyController.php

@@ -4,12 +4,12 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1\Auth;
 
+use App\Enums\MfaMethod;
 use App\Http\Controllers\Api\V1\Traits\SetAuthCookie;
 use App\Http\Controllers\Controller;
 use App\Http\Requests\Api\V1\Auth\MfaEmailSendRequest;
 use App\Http\Requests\Api\V1\Auth\MfaVerifyRequest;
 use App\Http\Resources\Api\V1\MeResource;
-use App\Enums\MfaMethod;
 use App\Models\User;
 use App\Services\MfaService;
 use Illuminate\Http\JsonResponse;
@@ -58,19 +58,18 @@ final class MfaVerifyController extends Controller
         ]);
 
         $token = $user->createToken('auth-token')->plainTextToken;
-        $cookieName = $this->resolveCookieName($request);
 
         return $this->success([
             'user' => new MeResource($user),
         ], 'MFA verification successful')
-            ->withCookie($this->makeAuthCookie($cookieName, $token));
+            ->withCookie($this->makeAuthCookie($token));
     }
 
     public function sendEmailCode(MfaEmailSendRequest $request): JsonResponse
     {
         $sessionToken = $request->validated('mfa_session_token');
 
-        $cacheKey = 'mfa_session:' . $sessionToken;
+        $cacheKey = 'mfa_session:'.$sessionToken;
         $session = Cache::get($cacheKey);
 
         if (! $session) {

api/app/Http/Controllers/Api/V1/AuthRefreshController.php

@@ -24,7 +24,6 @@ final class AuthRefreshController extends Controller
 
         // Create a new token
         $newToken = $user->createToken('auth-token')->plainTextToken;
-        $cookieName = $this->resolveCookieName($request);
 
         $user->load(['organisations', 'roles', 'permissions']);
 
@@ -34,6 +33,6 @@ final class AuthRefreshController extends Controller
         ]);
 
         return $this->success(new MeResource($user), 'Token refreshed')
-            ->withCookie($this->makeAuthCookie($cookieName, $newToken));
+            ->withCookie($this->makeAuthCookie($newToken));
     }
 }

api/app/Http/Controllers/Api/V1/InvitationController.php

@@ -18,6 +18,7 @@ use Illuminate\Support\Facades\Gate;
 final class InvitationController extends Controller
 {
     use SetAuthCookie;
+
     public function __construct(
         private readonly InvitationService $invitationService,
     ) {}
@@ -65,7 +66,6 @@ final class InvitationController extends Controller
         );
 
         $sanctumToken = $user->createToken('auth-token')->plainTextToken;
-        $cookieName = $this->resolveCookieName($request);
 
         return $this->success([
             'user' => [
@@ -76,7 +76,7 @@ final class InvitationController extends Controller
                 'email' => $user->email,
             ],
         ], 'Uitnodiging geaccepteerd')
-            ->withCookie($this->makeAuthCookie($cookieName, $sanctumToken));
+            ->withCookie($this->makeAuthCookie($sanctumToken));
     }
 
     public function revoke(Organisation $organisation, UserInvitation $invitation): JsonResponse

api/app/Http/Controllers/Api/V1/LoginController.php

@@ -65,13 +65,11 @@ final class LoginController extends Controller
 
             // Return MFA challenge — NO auth token, NO auth cookie.
             // Expire the auth cookie to invalidate any stale browser session.
-            $cookieName = $this->resolveCookieName($request);
-
             return response()->json([
                 'success' => true,
                 'mfa_required' => true,
                 ...$mfaSession,
-            ])->withCookie($this->forgetAuthCookie($cookieName));
+            ])->withCookie($this->forgetAuthCookie());
         }
 
         // MFA required by policy but not yet set up — issue token with flag
@@ -80,11 +78,10 @@ final class LoginController extends Controller
             $data = $response->getData(true);
             $data['mfa_setup_required'] = true;
 
-            $cookieName = $this->resolveCookieName($request);
             $token = $user->createToken('auth-token')->plainTextToken;
 
             return response()->json($data)
-                ->withCookie($this->makeAuthCookie($cookieName, $token));
+                ->withCookie($this->makeAuthCookie($token));
         }
 
         // No MFA — issue token as normal
@@ -101,11 +98,10 @@ final class LoginController extends Controller
         ]);
 
         $token = $user->createToken('auth-token')->plainTextToken;
-        $cookieName = $this->resolveCookieName($request);
 
         return $this->success([
             'user' => new MeResource($user),
         ], 'Login successful')
-            ->withCookie($this->makeAuthCookie($cookieName, $token));
+            ->withCookie($this->makeAuthCookie($token));
     }
 }

api/app/Http/Controllers/Api/V1/LogoutController.php

@@ -17,9 +17,7 @@ final class LogoutController extends Controller
     {
         $request->user()->currentAccessToken()->delete();
 
-        $cookieName = $this->resolveCookieName($request);
-
         return $this->success(null, 'Logged out successfully')
-            ->withCookie($this->forgetAuthCookie($cookieName));
+            ->withCookie($this->forgetAuthCookie());
     }
 }

api/app/Http/Controllers/Api/V1/Portal/EngagementPortalController.php

@@ -0,0 +1,271 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1\Portal;
+
+use App\Enums\Artist\AdvanceSectionSubmissionStatus;
+use App\Enums\FormBuilder\FormPurpose;
+use App\Exceptions\Artist\ArtistDeletedException;
+use App\Exceptions\Artist\InvalidPortalTokenException;
+use App\FormBuilder\Resolvers\ArtistResolver;
+use App\FormBuilder\Resolvers\ArtistResolverResult;
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\Portal\SubmitEngagementSectionRequest;
+use App\Http\Resources\Api\V1\Portal\EngagementPortalResource;
+use App\Models\AdvanceSection;
+use App\Models\ArtistEngagement;
+use App\Models\FormBuilder\FormField;
+use App\Models\FormBuilder\FormSchema;
+use App\Models\FormBuilder\FormSchemaSection;
+use App\Models\FormBuilder\FormSubmission;
+use App\Models\FormBuilder\FormSubmissionSectionStatus;
+use App\Models\FormBuilder\FormValue;
+use App\Models\Scopes\OrganisationScope;
+use App\Services\FormBuilder\FormSubmissionService;
+use App\Services\FormBuilder\FormValueService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Public artist-advance portal endpoints. Mounted under /p/artist/{token}/...
+ *
+ *   GET  /p/artist/{token}                            — engagement summary + sections
+ *   GET  /p/artist/{token}/sections/{section}         — schema + draft values for one section
+ *   POST /p/artist/{token}/sections/{section}         — submit one section
+ *
+ * The route token is the plaintext portal token; resolution happens
+ * via ArtistResolver::fromPortalToken (SHA-256 digest match against
+ * artist_engagements.portal_token, Session 1 commit eb6d396). Master
+ * Artist is the FormSubmission subject; engagement.event_id populates
+ * form_submissions.event_id per WS-4 denormalisation.
+ *
+ * The standard FormBindingApplicator pipeline (RFC-WS-6 v1.3.1) runs
+ * via the FormSubmissionSectionSubmitted listener — this controller
+ * does not duplicate any binding-apply logic.
+ *
+ * AdvanceSection (engagement-scoped) ↔ FormSchemaSection bridge:
+ * matched by name (case-sensitive) on the organisation's artist_advance
+ * schema. The default seeder names them in lockstep.
+ */
+final class EngagementPortalController extends Controller
+{
+    public function __construct(
+        private readonly ArtistResolver $artistResolver,
+        private readonly FormSubmissionService $submissionService,
+        private readonly FormValueService $valueService,
+    ) {}
+
+    public function show(string $token): JsonResponse
+    {
+        try {
+            $resolved = $this->artistResolver->fromPortalToken($token);
+        } catch (InvalidPortalTokenException) {
+            return $this->error('Engagement not found.', 404);
+        } catch (ArtistDeletedException) {
+            return $this->error('Engagement no longer available.', 410);
+        }
+
+        $engagement = $resolved->engagement->load([
+            'artist' => fn ($q) => $q->withoutGlobalScope(OrganisationScope::class),
+            'event' => fn ($q) => $q->withoutGlobalScope(OrganisationScope::class),
+            'advanceSections' => fn ($q) => $q->withoutGlobalScope(OrganisationScope::class)->orderBy('sort_order'),
+        ]);
+
+        return $this->success(new EngagementPortalResource($engagement));
+    }
+
+    public function showSection(string $token, string $section): JsonResponse
+    {
+        try {
+            $resolved = $this->artistResolver->fromPortalToken($token);
+        } catch (InvalidPortalTokenException) {
+            return $this->error('Engagement not found.', 404);
+        } catch (ArtistDeletedException) {
+            return $this->error('Engagement no longer available.', 410);
+        }
+
+        $advanceSection = $this->findAdvanceSection($resolved->engagement, $section);
+        if ($advanceSection === null) {
+            return $this->error('Section not found on this engagement.', 404);
+        }
+
+        $schema = $this->resolveAdvanceSchema($resolved);
+        if ($schema === null) {
+            return $this->error('Artist advance schema not configured for this organisation.', 404);
+        }
+
+        $schemaSection = $this->findSchemaSectionFor($schema, $advanceSection);
+        if ($schemaSection === null) {
+            return $this->error('Section is not mapped to a form schema section.', 404);
+        }
+
+        $fields = FormField::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('form_schema_section_id', $schemaSection->id)
+            ->orderBy('sort_order')
+            ->get();
+
+        $submission = $this->findExistingDraft($schema, $resolved->engagement);
+        $existingValues = $submission instanceof FormSubmission
+            ? FormValue::query()
+                ->withoutGlobalScope(OrganisationScope::class)
+                ->where('form_submission_id', $submission->id)
+                ->whereIn('form_field_id', $fields->pluck('id')->all())
+                ->get()
+                ->keyBy(fn (FormValue $v) => (string) $v->form_field_id)
+            : collect();
+
+        return $this->success([
+            'section' => [
+                'id' => (string) $advanceSection->id,
+                'name' => (string) $advanceSection->name,
+                'type' => $advanceSection->getRawOriginal('type'),
+                'submission_status' => $advanceSection->getRawOriginal('submission_status'),
+                'is_open' => (bool) $advanceSection->is_open,
+            ],
+            'fields' => $fields->map(static fn (FormField $field): array => [
+                'id' => (string) $field->id,
+                'slug' => (string) $field->slug,
+                'label' => (string) $field->label,
+                'help_text' => $field->help_text,
+                'field_type' => (string) $field->field_type,
+                'is_required' => (bool) $field->is_required,
+                'display_width' => $field->getRawOriginal('display_width'),
+                'sort_order' => (int) $field->sort_order,
+            ])->all(),
+            'values' => $fields->mapWithKeys(static function (FormField $field) use ($existingValues): array {
+                $value = $existingValues->get((string) $field->id);
+
+                return [(string) $field->slug => $value?->value];
+            })->all(),
+        ]);
+    }
+
+    public function submitSection(SubmitEngagementSectionRequest $request, string $token, string $section): JsonResponse
+    {
+        try {
+            $resolved = $this->artistResolver->fromPortalToken($token);
+        } catch (InvalidPortalTokenException) {
+            return $this->error('Engagement not found.', 404);
+        } catch (ArtistDeletedException) {
+            return $this->error('Engagement no longer available.', 410);
+        }
+
+        $advanceSection = $this->findAdvanceSection($resolved->engagement, $section);
+        if ($advanceSection === null) {
+            return $this->error('Section not found on this engagement.', 404);
+        }
+
+        $schema = $this->resolveAdvanceSchema($resolved);
+        if ($schema === null) {
+            return $this->error('Artist advance schema not configured for this organisation.', 404);
+        }
+
+        $schemaSection = $this->findSchemaSectionFor($schema, $advanceSection);
+        if ($schemaSection === null) {
+            return $this->error('Section is not mapped to a form schema section.', 404);
+        }
+
+        /** @var array<string, mixed> $values */
+        $values = (array) $request->validated('values', []);
+
+        $result = DB::transaction(function () use ($resolved, $schema, $schemaSection, $advanceSection, $values): array {
+            $submission = $this->findOrCreateDraft($schema, $resolved);
+
+            $this->valueService->upsertMany($submission, $values, null);
+
+            $sectionStatus = FormSubmissionSectionStatus::query()
+                ->withoutGlobalScope(OrganisationScope::class)
+                ->where('form_submission_id', $submission->id)
+                ->where('form_schema_section_id', $schemaSection->id)
+                ->first();
+
+            if ($sectionStatus === null) {
+                $sectionStatus = new FormSubmissionSectionStatus;
+                $sectionStatus->form_submission_id = $submission->id;
+                $sectionStatus->form_schema_section_id = $schemaSection->id;
+            }
+            $sectionStatus->status = 'submitted';
+            $sectionStatus->submitted_at = now();
+            $sectionStatus->save();
+
+            $advanceSection->submission_status = AdvanceSectionSubmissionStatus::Submitted->value;
+            $advanceSection->last_submitted_at = now()->toDateTimeString();
+            $advanceSection->save();
+
+            return [$submission->refresh(), $sectionStatus->refresh(), $advanceSection->refresh()];
+        });
+
+        [$submission, $sectionStatus] = $result;
+
+        \App\Events\FormBuilder\FormSubmissionSectionSubmitted::dispatch($submission, $sectionStatus);
+
+        return $this->success([
+            'submission_id' => (string) $submission->id,
+            'section_status' => (string) $sectionStatus->status,
+            'advance_section_status' => AdvanceSectionSubmissionStatus::Submitted->value,
+        ]);
+    }
+
+    private function findAdvanceSection(ArtistEngagement $engagement, string $sectionId): ?AdvanceSection
+    {
+        return AdvanceSection::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('engagement_id', $engagement->id)
+            ->whereKey($sectionId)
+            ->first();
+    }
+
+    private function resolveAdvanceSchema(ArtistResolverResult $resolved): ?FormSchema
+    {
+        return FormSchema::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('organisation_id', $resolved->engagement->organisation_id)
+            ->where('purpose', FormPurpose::ARTIST_ADVANCE->value)
+            ->first();
+    }
+
+    private function findSchemaSectionFor(FormSchema $schema, AdvanceSection $advanceSection): ?FormSchemaSection
+    {
+        return FormSchemaSection::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('form_schema_id', $schema->id)
+            ->where('name', $advanceSection->name)
+            ->first();
+    }
+
+    private function findExistingDraft(FormSchema $schema, ArtistEngagement $engagement): ?FormSubmission
+    {
+        return FormSubmission::query()
+            ->withoutGlobalScope(OrganisationScope::class)
+            ->where('form_schema_id', $schema->id)
+            ->where('subject_type', 'artist')
+            ->where('subject_id', $engagement->artist_id)
+            ->where('event_id', $engagement->event_id)
+            ->orderBy('created_at')
+            ->first();
+    }
+
+    private function findOrCreateDraft(FormSchema $schema, ArtistResolverResult $resolved): FormSubmission
+    {
+        $existing = $this->findExistingDraft($schema, $resolved->engagement);
+        if ($existing instanceof FormSubmission) {
+            return $existing;
+        }
+
+        // Pass event_id via the context bag — the schema is org-owned (not
+        // event-owned) and this route has no {event} parameter for the
+        // FormSubmissionObserver fallback. ARCH-FORM-BUILDER §17.3 footnote.
+        // idempotency_key column is varchar(30); 'aa:' + 26-char ULID fits.
+        return $this->submissionService->createDraft(
+            schema: $schema,
+            subject: $resolved->subject,
+            submitter: null,
+            context: [
+                'idempotency_key' => 'aa:'.$resolved->engagement->id,
+                'event_id' => $resolved->eventId,
+            ],
+        );
+    }
+}

api/app/Http/Controllers/Api/V1/PortalTokenController.php

@@ -18,18 +18,28 @@ final class PortalTokenController extends Controller
     {
         $hashedToken = hash('sha256', $request->validated('token'));
 
-        // Try artists table
-        $artist = DB::table('artists')->where('portal_token', $hashedToken)->first();
+        // Artist portal token lives on artist_engagements (per RFC-TIMETABLE
+        // v0.2 §5.3); join to artists for the master name.
+        $row = DB::table('artist_engagements')
+            ->join('artists', 'artists.id', '=', 'artist_engagements.artist_id')
+            ->where('artist_engagements.portal_token', $hashedToken)
+            ->select(
+                'artist_engagements.id as id',
+                'artist_engagements.event_id as event_id',
+                'artist_engagements.booking_status as booking_status',
+                'artists.name as name',
+            )
+            ->first();
 
-        if ($artist) {
-            $event = Event::withoutGlobalScope(OrganisationScope::class)->find($artist->event_id);
+        if ($row) {
+            $event = Event::withoutGlobalScope(OrganisationScope::class)->find($row->event_id);
 
             return response()->json([
                 'context' => 'artist',
                 'data' => [
-                    'id' => $artist->id,
-                    'name' => $artist->name,
-                    'booking_status' => $artist->booking_status,
+                    'id' => $row->id,
+                    'name' => $row->name,
+                    'booking_status' => $row->booking_status,
                 ],
                 'event' => $event ? new PortalEventResource($event) : null,
             ]);

api/app/Http/Controllers/Api/V1/Traits/SetAuthCookie.php

@@ -4,42 +4,18 @@ declare(strict_types=1);
 
 namespace App\Http\Controllers\Api\V1\Traits;
 
-use Illuminate\Http\Request;
 use Symfony\Component\HttpFoundation\Cookie;
 
 trait SetAuthCookie
 {
-    private const COOKIE_MAP = [
-        'app' => 'crewli_app_token',
-        'portal' => 'crewli_portal_token',
-    ];
+    private const COOKIE_NAME = 'crewli_app_token';
 
     private const COOKIE_TTL_MINUTES = 60 * 24 * 7; // 7 days
 
-    protected function resolveCookieName(Request $request): string
-    {
-        $origin = $request->headers->get('Origin')
-            ?? $request->headers->get('Referer')
-            ?? '';
-
-        $appUrl = config('app.frontend_app_url', 'http://localhost:5174');
-        $portalUrl = config('app.frontend_portal_url', 'http://localhost:5175');
-
-        if ($this->originMatches($origin, $appUrl)) {
-            return self::COOKIE_MAP['app'];
-        }
-
-        if ($this->originMatches($origin, $portalUrl)) {
-            return self::COOKIE_MAP['portal'];
-        }
-
-        return self::COOKIE_MAP['app'];
-    }
-
-    protected function makeAuthCookie(string $cookieName, string $token): Cookie
+    protected function makeAuthCookie(string $token): Cookie
     {
         return new Cookie(
-            name: $cookieName,
+            name: self::COOKIE_NAME,
             value: $token,
             expire: now()->addMinutes(self::COOKIE_TTL_MINUTES),
             path: '/',
@@ -50,10 +26,10 @@ trait SetAuthCookie
         );
     }
 
-    protected function forgetAuthCookie(string $cookieName): Cookie
+    protected function forgetAuthCookie(): Cookie
     {
         return new Cookie(
-            name: $cookieName,
+            name: self::COOKIE_NAME,
             value: '',
             expire: now()->subMinute(),
             path: '/',
@@ -63,19 +39,4 @@ trait SetAuthCookie
             sameSite: 'Strict',
         );
     }
-
-    private function originMatches(string $origin, string $configuredUrl): bool
-    {
-        if ($origin === '' || $configuredUrl === '') {
-            return false;
-        }
-
-        // Parse to compare host+port, ignoring trailing slashes and paths
-        $originHost = parse_url($origin, PHP_URL_HOST);
-        $originPort = parse_url($origin, PHP_URL_PORT);
-        $configHost = parse_url($configuredUrl, PHP_URL_HOST);
-        $configPort = parse_url($configuredUrl, PHP_URL_PORT);
-
-        return $originHost === $configHost && $originPort === $configPort;
-    }
 }

api/app/Http/Middleware/BindRequestLogContext.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use App\Models\Event;
+use App\Models\Organisation;
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Str;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * Structured-logging context binder (RFC-WS-7 §3.13). Tags every Laravel
+ * log line written during this request with request_id, organisation_id,
+ * user_id, and route name. Round-trips X-Request-Id with the response so
+ * the SPA can correlate to backend log lines via one click.
+ */
+final class BindRequestLogContext
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        $requestId = $this->resolveRequestId($request);
+        $request->attributes->set('observability.request_id', $requestId);
+
+        Log::withContext(array_filter([
+            'request_id' => $requestId,
+            'organisation_id' => $this->resolveOrganisationId($request),
+            'user_id' => $request->user()?->getAuthIdentifier(),
+            'route' => $request->route()?->getName(),
+        ], static fn ($v) => $v !== null && $v !== ''));
+
+        $response = $next($request);
+
+        $response->headers->set('X-Request-Id', $requestId);
+
+        return $response;
+    }
+
+    private function resolveRequestId(Request $request): string
+    {
+        $supplied = $request->header('X-Request-Id');
+
+        if (is_string($supplied) && Str::isUlid($supplied)) {
+            return $supplied;
+        }
+
+        return (string) Str::ulid();
+    }
+
+    private function resolveOrganisationId(Request $request): ?string
+    {
+        $portalEvent = $request->attributes->get('portal_event');
+        if ($portalEvent instanceof Event) {
+            return $portalEvent->organisation_id;
+        }
+
+        $route = $request->route();
+        if ($route === null) {
+            return null;
+        }
+
+        $org = $route->parameter('organisation');
+        if ($org instanceof Organisation) {
+            return $org->id;
+        }
+        if (is_string($org) && $org !== '') {
+            return $org;
+        }
+
+        $event = $route->parameter('event');
+        if ($event instanceof Event) {
+            return $event->organisation_id;
+        }
+
+        return null;
+    }
+}

api/app/Http/Middleware/BindSentryRouteContext.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Sentry\State\Scope;
+use Symfony\Component\HttpFoundation\Response;
+
+use function Sentry\configureScope;
+
+/**
+ * Binds route-scope context to Sentry events on every API request.
+ *
+ * Auth-scope tags (user_id, actor_type, organisation_id, impersonation.*,
+ * actor_scope) live in {@see \App\Listeners\Observability\AuthScopeContextListener}
+ * so they bind on Authenticated event rather than route entry. That keeps
+ * the auth-scope binding uniform across Sanctum, portal-tokens, and any
+ * future authenticator without per-route middleware-attachment.
+ *
+ * RFC-WS-7 §3.6.
+ */
+final class BindSentryRouteContext
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        configureScope(static function (Scope $scope) use ($request): void {
+            $scope->setTag('app', 'api');
+            $scope->setTag('http.method', $request->method());
+
+            $routeName = $request->route()?->getName();
+            if (is_string($routeName) && $routeName !== '') {
+                $scope->setTag('route_name', $routeName);
+            }
+        });
+
+        return $next($request);
+    }
+}

api/app/Http/Middleware/CookieBearerToken.php

@@ -10,74 +10,21 @@ use Symfony\Component\HttpFoundation\Response;
 
 final class CookieBearerToken
 {
-    private const COOKIE_NAMES = [
-        'crewli_app_token',
-        'crewli_portal_token',
-    ];
+    private const COOKIE_NAME = 'crewli_app_token';
 
     public function handle(Request $request, Closure $next): Response
     {
-        // Skip if an Authorization header is already present
+        // Skip if an Authorization header is already present (e.g. portal-token
+        // Bearer flow for artists/suppliers, or server-to-server callers).
         if ($request->hasHeader('Authorization')) {
             return $next($request);
         }
 
-        // Resolve the cookie name for the requesting app via Origin header.
-        // This prevents cross-app cookie leakage on localhost where the
-        // browser sends all cookies regardless of port.
-        $cookieName = $this->resolveCookieName($request);
-
-        if ($cookieName) {
-            $token = $request->cookie($cookieName);
-            if ($token) {
-                $request->headers->set('Authorization', 'Bearer ' . $token);
-            }
+        $token = $request->cookie(self::COOKIE_NAME);
+        if ($token) {
+            $request->headers->set('Authorization', 'Bearer '.$token);
         }
 
         return $next($request);
     }
-
-    private function resolveCookieName(Request $request): ?string
-    {
-        $origin = $request->headers->get('Origin')
-            ?? $request->headers->get('Referer')
-            ?? '';
-
-        if ($origin === '') {
-            // No Origin — fall back to first available cookie (e.g. server-to-server)
-            foreach (self::COOKIE_NAMES as $name) {
-                if ($request->cookie($name)) {
-                    return $name;
-                }
-            }
-
-            return null;
-        }
-
-        $originHost = parse_url($origin, PHP_URL_HOST);
-        $originPort = parse_url($origin, PHP_URL_PORT);
-
-        $map = [
-            'app' => [config('app.frontend_app_url', 'http://localhost:5174'), 'crewli_app_token'],
-            'portal' => [config('app.frontend_portal_url', 'http://localhost:5175'), 'crewli_portal_token'],
-        ];
-
-        foreach ($map as [$configuredUrl, $cookieName]) {
-            $configHost = parse_url($configuredUrl, PHP_URL_HOST);
-            $configPort = parse_url($configuredUrl, PHP_URL_PORT);
-
-            if ($originHost === $configHost && $originPort === $configPort) {
-                return $cookieName;
-            }
-        }
-
-        // Origin didn't match any configured frontend — fall back to first available
-        foreach (self::COOKIE_NAMES as $name) {
-            if ($request->cookie($name)) {
-                return $name;
-            }
-        }
-
-        return null;
-    }
 }

api/app/Http/Middleware/HandleImpersonation.php

@@ -4,13 +4,17 @@ declare(strict_types=1);
 
 namespace App\Http\Middleware;
 
-use App\Services\ImpersonationService;
+use App\Enums\Observability\ActorType;
 use App\Models\User;
+use App\Services\ImpersonationService;
 use Closure;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Log;
+use Sentry\State\Scope;
 use Symfony\Component\HttpFoundation\Response;
 
+use function Sentry\configureScope;
+
 class HandleImpersonation
 {
     /**
@@ -88,6 +92,24 @@ class HandleImpersonation
             'impersonation_session_id' => $session->id,
         ]);
 
+        // Re-bind Sentry auth-scope tags after the user swap. The
+        // Authenticated event already fired with the admin; AuthScopeContextListener
+        // tagged the admin's user_id/actor_type. We now overwrite both with
+        // the target's data and add the impersonation.* invariants
+        // (RFC-WS-7 §3.6) so captured events attribute correctly.
+        $targetActorType = ActorType::resolve($targetUser, $request);
+        configureScope(static function (Scope $scope) use ($admin, $targetUser, $session, $targetActorType): void {
+            $scope->setUser([
+                'id' => $targetUser->id,
+                'username' => $targetUser->id,
+            ]);
+            $scope->setTag('user_id', $targetUser->id);
+            $scope->setTag('actor_type', $targetActorType->value);
+            $scope->setTag('impersonation.active', 'true');
+            $scope->setTag('impersonation.impersonator_user_id', $admin->id);
+            $scope->setTag('impersonation.session_id', $session->id);
+        });
+
         // Increment actions count
         $this->impersonationService->incrementActionsCount($session);
 

api/app/Http/Middleware/IdempotencyKey60sRedis.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
+use Symfony\Component\HttpFoundation\Response;
+
+/**
+ * RFC v0.2 R1 — 60-second Idempotency-Key replay window backed by
+ * Redis cache.
+ *
+ * Why 60s and not the 12-hour MySQL window from ARCH §10:
+ * a stale 12-hour replay of the cascade-bump endpoint can corrupt
+ * timetable state in hard-to-detect ways (the persisted lanes have
+ * since been edited; replaying a cached response over a fresh edit
+ * would silently undo it). 60 seconds covers honest network retry
+ * without giving stale requests a window in which to resurrect.
+ *
+ * Storage: Laravel Cache facade with the default store (Redis in
+ * non-test environments). The key namespace `idempotency:60s:` is
+ * deliberately distinct from any other idempotency surface in the
+ * codebase — keys never collide with the FormSubmission DB-column
+ * idempotency.
+ *
+ * Applied today only on `POST /api/v1/events/{event}/timetable/move`.
+ * Other R-numbered idempotent endpoints (RFC §6 lists POST
+ * /performances and POST /engagements as candidates) get the regular
+ * 12-hour pattern when ARCH §10 lands; this middleware is purposely
+ * narrow.
+ */
+final class IdempotencyKey60sRedis
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        $key = $request->header('Idempotency-Key');
+
+        if (! is_string($key) || trim($key) === '') {
+            return response()->json(
+                ['error' => 'idempotency_key_required'],
+                400,
+            );
+        }
+
+        $cacheKey = 'idempotency:60s:'.$key;
+        $cached = Cache::get($cacheKey);
+
+        if (is_array($cached)) {
+            $response = response($cached['body'], $cached['status']);
+            foreach ($cached['headers'] ?? [] as $name => $value) {
+                $response->headers->set($name, $value);
+            }
+            $response->headers->set('Idempotency-Replayed', 'true');
+
+            return $response;
+        }
+
+        /** @var Response $response */
+        $response = $next($request);
+
+        if ($response->isSuccessful()) {
+            Cache::put($cacheKey, [
+                'status' => $response->getStatusCode(),
+                'body' => $response->getContent(),
+                'headers' => [
+                    'Content-Type' => $response->headers->get('Content-Type'),
+                ],
+            ], 60);
+        }
+
+        return $response;
+    }
+}

api/app/Http/Middleware/PortalTokenMiddleware.php

@@ -23,18 +23,19 @@ final class PortalTokenMiddleware
 
         $hashedToken = hash('sha256', $plainToken);
 
-        // Try artists table
-        $artist = DB::table('artists')->where('portal_token', $hashedToken)->first();
+        // Artist portal token lives on artist_engagements (per RFC-TIMETABLE
+        // v0.2 §5.3); resolve to the engagement's event.
+        $engagement = DB::table('artist_engagements')->where('portal_token', $hashedToken)->first();
 
-        if ($artist) {
-            $event = Event::withoutGlobalScope(OrganisationScope::class)->find($artist->event_id);
+        if ($engagement) {
+            $event = Event::withoutGlobalScope(OrganisationScope::class)->find($engagement->event_id);
 
             if (! $event || in_array($event->status, ['draft', 'closed'], true)) {
                 return response()->json(['message' => 'Portal token required.'], 401);
             }
 
             $request->attributes->set('portal_context', 'artist');
-            $request->attributes->set('portal_person', $artist);
+            $request->attributes->set('portal_person', $engagement);
             $request->attributes->set('portal_event', $event);
 
             return $next($request);

api/app/Http/Requests/Api/V1/Artist/CreateArtistEngagementRequest.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Enums\Artist\ArtistEngagementStatus;
+use App\Enums\Artist\BumaHandledBy;
+use App\Enums\Artist\FeeType;
+use App\Enums\Artist\PaymentStatus;
+use App\Models\Event;
+use App\Rules\Artist\ContractRequiresFee;
+use App\Rules\Artist\OptionExpiresInFuture;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * RFC v0.2 §10.3.
+ */
+final class CreateArtistEngagementRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $event = $this->route('event');
+        $organisationId = $event instanceof Event ? $event->organisation_id : null;
+        $bookingStatus = $this->input('booking_status');
+
+        return [
+            'artist_id' => [
+                'required', 'string', 'max:30',
+                Rule::exists('artists', 'id')->where('organisation_id', $organisationId),
+            ],
+            'booking_status' => ['required', Rule::enum(ArtistEngagementStatus::class)],
+            'project_leader_id' => ['nullable', 'string', 'max:30', 'exists:users,id'],
+            'fee_amount' => ['nullable', 'numeric', 'min:0', 'max:9999999.99', new ContractRequiresFee($bookingStatus)],
+            'fee_currency' => ['nullable', 'string', 'size:3', Rule::in(['EUR', 'USD', 'GBP'])],
+            'fee_type' => ['nullable', Rule::enum(FeeType::class)],
+            'buma_applicable' => ['nullable', 'boolean'],
+            'buma_percentage' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'buma_handled_by' => ['nullable', Rule::enum(BumaHandledBy::class)],
+            'vat_applicable' => ['nullable', 'boolean'],
+            'vat_percentage' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'deal_breakdown' => ['nullable', 'array'],
+            'deposit_percentage' => ['nullable', 'numeric', 'min:0', 'max:100'],
+            'deposit_due_date' => ['nullable', 'date'],
+            'balance_due_date' => ['nullable', 'date'],
+            'payment_status' => ['nullable', Rule::enum(PaymentStatus::class)],
+            'crew_count' => ['nullable', 'integer', 'min:0', 'max:200'],
+            'guests_count' => ['nullable', 'integer', 'min:0', 'max:1000'],
+            'requested_at' => ['nullable', 'date'],
+            'option_expires_at' => ['nullable', 'date', new OptionExpiresInFuture($bookingStatus)],
+            'advance_open_from' => ['nullable', 'date'],
+            'advance_open_to' => ['nullable', 'date', 'after_or_equal:advance_open_from'],
+            'notes' => ['nullable', 'string', 'max:2000'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/CreateArtistRequest.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Organisation;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * RFC v0.2 §5.3 (artists table) + §10.3 derived shape.
+ *
+ * Authorization is handled in the controller via Gate::authorize per
+ * the codebase convention; this request returns true.
+ */
+final class CreateArtistRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $organisationId = $this->route('organisation') instanceof Organisation
+            ? $this->route('organisation')->id
+            : (string) $this->route('organisation');
+
+        return [
+            'name' => ['required', 'string', 'max:120'],
+            'default_genre_id' => [
+                'nullable', 'string', 'max:30',
+                Rule::exists('genres', 'id')->where('organisation_id', $organisationId),
+            ],
+            'default_draw' => ['nullable', 'integer', 'min:0'],
+            'star_rating' => ['nullable', 'integer', 'between:1,5'],
+            'home_base_country' => ['nullable', 'string', 'size:2', 'alpha'],
+            'agent_company_id' => [
+                'nullable', 'string', 'max:30',
+                Rule::exists('companies', 'id')->where('organisation_id', $organisationId),
+            ],
+            'notes' => ['nullable', 'string', 'max:2000'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/CreateGenreRequest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Organisation;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class CreateGenreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $organisationId = $this->route('organisation') instanceof Organisation
+            ? $this->route('organisation')->id
+            : (string) $this->route('organisation');
+
+        return [
+            'name' => [
+                'required', 'string', 'max:40',
+                Rule::unique('genres', 'name')->where('organisation_id', $organisationId),
+            ],
+            'color' => ['nullable', 'string', 'size:7', 'regex:/^#[0-9A-Fa-f]{6}$/'],
+            'sort_order' => ['nullable', 'integer', 'min:0'],
+            'is_active' => ['nullable', 'boolean'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/CreatePerformanceRequest.php

@@ -0,0 +1,87 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\ArtistEngagement;
+use App\Models\Event;
+use App\Rules\Artist\StageActiveOnEvent;
+use App\Rules\Artist\WithinEventBounds;
+use Illuminate\Contracts\Validation\Validator;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * RFC v0.2 §10.2.
+ */
+final class CreatePerformanceRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $event = $this->route('event');
+        $organisationId = $event instanceof Event ? $event->organisation_id : null;
+        $eventIdInput = (string) $this->input('event_id', '');
+
+        return [
+            'engagement_id' => [
+                'required', 'string', 'max:30',
+                Rule::exists('artist_engagements', 'id')->where('organisation_id', $organisationId),
+            ],
+            'event_id' => [
+                'required', 'string', 'max:30',
+                Rule::exists('events', 'id')->where('organisation_id', $organisationId),
+            ],
+            'stage_id' => [
+                'nullable', 'string', 'max:30',
+                Rule::exists('stages', 'id'),
+                new StageActiveOnEvent($eventIdInput),
+            ],
+            'start_at' => ['required', 'date_format:Y-m-d H:i:s', new WithinEventBounds($eventIdInput)],
+            'end_at' => ['required', 'date_format:Y-m-d H:i:s', 'after:start_at', new WithinEventBounds($eventIdInput)],
+            'lane' => ['nullable', 'integer', 'min:0', 'max:9'],
+            'notes' => ['nullable', 'string', 'max:1000'],
+        ];
+    }
+
+    public function withValidator(Validator $validator): void
+    {
+        $validator->after(function (Validator $validator): void {
+            $engagementId = $this->input('engagement_id');
+            $eventId = $this->input('event_id');
+            if (! is_string($engagementId) || ! is_string($eventId)) {
+                return;
+            }
+
+            $engagement = ArtistEngagement::query()->find($engagementId);
+            if ($engagement === null) {
+                return;
+            }
+
+            $event = Event::withoutGlobalScopes()->find($eventId);
+            if ($event === null) {
+                return;
+            }
+
+            // event_id must equal engagement.event_id (flat case) OR be a
+            // sub-event of engagement.event_id (festival case).
+            if (
+                $eventId !== $engagement->event_id
+                && $event->parent_event_id !== $engagement->event_id
+            ) {
+                $validator->errors()->add(
+                    'event_id',
+                    'event_id moet gelijk zijn aan de engagement.event_id of een sub-event daarvan.',
+                );
+            }
+        });
+    }
+}

api/app/Http/Requests/Api/V1/Artist/CreateStageRequest.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Event;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class CreateStageRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $eventId = $this->route('event') instanceof Event
+            ? $this->route('event')->id
+            : (string) $this->route('event');
+
+        return [
+            'name' => [
+                'required', 'string', 'max:120',
+                Rule::unique('stages', 'name')->where('event_id', $eventId),
+            ],
+            'color' => ['required', 'string', 'size:7', 'regex:/^#[0-9A-Fa-f]{6}$/'],
+            'capacity' => ['nullable', 'integer', 'min:0'],
+            'sort_order' => ['nullable', 'integer', 'min:0'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/MoveTimetablePerformanceRequest.php

@@ -0,0 +1,108 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Stage;
+use App\Models\StageDay;
+use App\Rules\Artist\StageActiveOnEvent;
+use App\Rules\Artist\WithinEventBounds;
+use Carbon\CarbonImmutable;
+use Illuminate\Contracts\Validation\Validator;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * RFC v0.2 §10.4 — D18 transactional move endpoint.
+ */
+final class MoveTimetablePerformanceRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $event = $this->route('event');
+        $resolvedEventId = $this->resolveTargetEventId();
+
+        return [
+            // performances has no organisation_id column (FK-chain via
+            // engagement_id); cross-tenant is caught by the policy in
+            // TimetableMoveController via Gate::authorize('move', ...).
+            'performance_id' => [
+                'required', 'string', 'max:30',
+                Rule::exists('performances', 'id'),
+            ],
+            'target_stage_id' => [
+                'nullable', 'string', 'max:30',
+                Rule::exists('stages', 'id'),
+                new StageActiveOnEvent($resolvedEventId),
+            ],
+            'target_start_at' => [
+                'nullable', 'date_format:Y-m-d H:i:s',
+                'required_unless:target_stage_id,null',
+                new WithinEventBounds($resolvedEventId),
+            ],
+            'target_end_at' => [
+                'nullable', 'date_format:Y-m-d H:i:s',
+                'required_unless:target_stage_id,null',
+                'after:target_start_at',
+                new WithinEventBounds($resolvedEventId),
+            ],
+            'target_lane' => ['nullable', 'integer', 'min:0', 'max:9'],
+            'version' => ['required', 'integer', 'min:0'],
+        ];
+    }
+
+    public function withValidator(Validator $validator): void
+    {
+        $validator->after(function (Validator $validator): void {
+            // When target_stage_id is non-null, target_lane must be set
+            // (the move algorithm requires a definite lane).
+            if ($this->input('target_stage_id') !== null && $this->input('target_lane') === null) {
+                $validator->errors()->add('target_lane', 'target_lane is verplicht bij een niet-leeg target_stage_id.');
+            }
+        });
+    }
+
+    /**
+     * Resolve the event_id the candidate move lands on so the
+     * StageActiveOnEvent and WithinEventBounds rules can validate
+     * against a concrete event window.
+     *
+     * For flat events: stage.event_id is the answer.
+     * For festivals: walk stage_days for target_stage_id and find the
+     * sub-event whose [start, end] contains target_start_at.
+     */
+    private function resolveTargetEventId(): ?string
+    {
+        $stageId = $this->input('target_stage_id');
+        $startAt = $this->input('target_start_at');
+        if (! is_string($stageId) || ! is_string($startAt)) {
+            return null;
+        }
+
+        $start = CarbonImmutable::parse($startAt);
+        $stage = Stage::query()->find($stageId);
+        if ($stage === null) {
+            return null;
+        }
+
+        $match = StageDay::query()
+            ->where('stage_id', $stage->id)
+            ->join('events', 'events.id', '=', 'stage_days.event_id')
+            ->where('events.start_date', '<=', $start->toDateString())
+            ->where('events.end_date', '>=', $start->toDateString())
+            ->orderBy('events.start_date', 'desc')
+            ->limit(1)
+            ->value('stage_days.event_id');
+
+        return is_string($match) ? $match : $stage->event_id;
+    }
+}

api/app/Http/Requests/Api/V1/Artist/ReorderStagesRequest.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Event;
+use App\Models\Stage;
+use Illuminate\Contracts\Validation\Validator;
+use Illuminate\Foundation\Http\FormRequest;
+
+final class ReorderStagesRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'stage_ids' => ['required', 'array', 'min:1'],
+            'stage_ids.*' => ['string', 'max:30'],
+        ];
+    }
+
+    public function withValidator(Validator $validator): void
+    {
+        $validator->after(function (Validator $validator): void {
+            $event = $this->route('event');
+            if (! $event instanceof Event) {
+                return;
+            }
+
+            $submitted = (array) $this->input('stage_ids', []);
+            $existing = Stage::query()
+                ->where('event_id', $event->id)
+                ->pluck('id')
+                ->all();
+
+            $missing = array_diff($existing, $submitted);
+            $extra = array_diff($submitted, $existing);
+
+            if ($missing !== [] || $extra !== []) {
+                $validator->errors()->add(
+                    'stage_ids',
+                    'stage_ids moet een permutatie zijn van alle stages op dit evenement.',
+                );
+            }
+        });
+    }
+}

api/app/Http/Requests/Api/V1/Artist/ReplaceStageDaysRequest.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Event;
+use App\Models\Stage;
+use Illuminate\Contracts\Validation\Validator;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+/**
+ * RFC v0.2 §10.5 — atomic stage_days matrix replace.
+ */
+final class ReplaceStageDaysRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $event = $this->route('event');
+        $organisationId = $event instanceof Event ? $event->organisation_id : null;
+
+        return [
+            'event_ids' => ['required', 'array', 'min:1'],
+            'event_ids.*' => [
+                'string', 'max:30',
+                Rule::exists('events', 'id')->where('organisation_id', $organisationId),
+            ],
+        ];
+    }
+
+    public function withValidator(Validator $validator): void
+    {
+        $validator->after(function (Validator $validator): void {
+            $stage = $this->route('stage');
+            if (! $stage instanceof Stage) {
+                return;
+            }
+
+            $eventIds = (array) $this->input('event_ids', []);
+            $events = Event::withoutGlobalScopes()
+                ->whereIn('id', $eventIds)
+                ->get(['id', 'parent_event_id']);
+
+            foreach ($events as $event) {
+                $isFlatMatch = $event->id === $stage->event_id;
+                $isSubEventMatch = $event->parent_event_id === $stage->event_id;
+
+                if (! $isFlatMatch && ! $isSubEventMatch) {
+                    $validator->errors()->add(
+                        'event_ids',
+                        sprintf(
+                            'event_id %s is geen sub-event van of gelijk aan stage.event_id (%s).',
+                            $event->id,
+                            $stage->event_id,
+                        ),
+                    );
+                }
+            }
+        });
+    }
+}

api/app/Http/Requests/Api/V1/Artist/UpdateArtistEngagementRequest.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Enums\Artist\ArtistEngagementStatus;
+use App\Enums\Artist\BumaHandledBy;
+use App\Enums\Artist\FeeType;
+use App\Enums\Artist\PaymentStatus;
+use App\Models\ArtistEngagement;
+use App\Rules\Artist\ContractRequiresFee;
+use App\Rules\Artist\OptionExpiresInFuture;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class UpdateArtistEngagementRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $engagement = $this->route('engagement');
+        $effectiveStatus = $this->input(
+            'booking_status',
+            $engagement instanceof ArtistEngagement
+                ? ($engagement->booking_status?->value ?? null)
+                : null,
+        );
+
+        return [
+            'booking_status' => ['sometimes', Rule::enum(ArtistEngagementStatus::class)],
+            'project_leader_id' => ['sometimes', 'nullable', 'string', 'max:30', 'exists:users,id'],
+            'fee_amount' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:9999999.99', new ContractRequiresFee($effectiveStatus)],
+            'fee_currency' => ['sometimes', 'nullable', 'string', 'size:3', Rule::in(['EUR', 'USD', 'GBP'])],
+            'fee_type' => ['sometimes', 'nullable', Rule::enum(FeeType::class)],
+            'buma_applicable' => ['sometimes', 'boolean'],
+            'buma_percentage' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:100'],
+            'buma_handled_by' => ['sometimes', 'nullable', Rule::enum(BumaHandledBy::class)],
+            'vat_applicable' => ['sometimes', 'boolean'],
+            'vat_percentage' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:100'],
+            'deal_breakdown' => ['sometimes', 'nullable', 'array'],
+            'deposit_percentage' => ['sometimes', 'nullable', 'numeric', 'min:0', 'max:100'],
+            'deposit_due_date' => ['sometimes', 'nullable', 'date'],
+            'balance_due_date' => ['sometimes', 'nullable', 'date'],
+            'payment_status' => ['sometimes', 'nullable', Rule::enum(PaymentStatus::class)],
+            'crew_count' => ['sometimes', 'nullable', 'integer', 'min:0', 'max:200'],
+            'guests_count' => ['sometimes', 'nullable', 'integer', 'min:0', 'max:1000'],
+            'requested_at' => ['sometimes', 'nullable', 'date'],
+            'option_expires_at' => ['sometimes', 'nullable', 'date', new OptionExpiresInFuture($effectiveStatus)],
+            'advance_open_from' => ['sometimes', 'nullable', 'date'],
+            'advance_open_to' => ['sometimes', 'nullable', 'date', 'after_or_equal:advance_open_from'],
+            'notes' => ['sometimes', 'nullable', 'string', 'max:2000'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/UpdateArtistRequest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Artist;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class UpdateArtistRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $artist = $this->route('artist');
+        $organisationId = $artist instanceof Artist
+            ? $artist->organisation_id
+            : ($this->route('organisation')?->id ?? null);
+
+        return [
+            'name' => ['sometimes', 'required', 'string', 'max:120'],
+            'default_genre_id' => [
+                'sometimes', 'nullable', 'string', 'max:30',
+                Rule::exists('genres', 'id')->where('organisation_id', $organisationId),
+            ],
+            'default_draw' => ['sometimes', 'nullable', 'integer', 'min:0'],
+            'star_rating' => ['sometimes', 'nullable', 'integer', 'between:1,5'],
+            'home_base_country' => ['sometimes', 'nullable', 'string', 'size:2', 'alpha'],
+            'agent_company_id' => [
+                'sometimes', 'nullable', 'string', 'max:30',
+                Rule::exists('companies', 'id')->where('organisation_id', $organisationId),
+            ],
+            'notes' => ['sometimes', 'nullable', 'string', 'max:2000'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/UpdateGenreRequest.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Genre;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class UpdateGenreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $genre = $this->route('genre');
+        $organisationId = $genre instanceof Genre
+            ? $genre->organisation_id
+            : ($this->route('organisation')?->id ?? null);
+        $genreId = $genre instanceof Genre ? $genre->id : null;
+
+        return [
+            'name' => [
+                'sometimes', 'required', 'string', 'max:40',
+                Rule::unique('genres', 'name')
+                    ->where('organisation_id', $organisationId)
+                    ->ignore($genreId),
+            ],
+            'color' => ['sometimes', 'nullable', 'string', 'size:7', 'regex:/^#[0-9A-Fa-f]{6}$/'],
+            'sort_order' => ['sometimes', 'nullable', 'integer', 'min:0'],
+            'is_active' => ['sometimes', 'boolean'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/UpdatePerformanceRequest.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * RFC v0.2 §10.2 — non-placement edits only. Placement (start_at,
+ * end_at, stage_id, lane) is NOT updateable here; placement changes
+ * route through POST /timetable/move so the cascade-bump and
+ * optimistic-lock contract is honoured.
+ */
+final class UpdatePerformanceRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'notes' => ['sometimes', 'nullable', 'string', 'max:1000'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Artist/UpdateStageRequest.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Artist;
+
+use App\Models\Stage;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+final class UpdateStageRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        $stage = $this->route('stage');
+        $eventId = $stage instanceof Stage
+            ? $stage->event_id
+            : ($this->route('event')?->id ?? null);
+        $stageId = $stage instanceof Stage ? $stage->id : null;
+
+        return [
+            'name' => [
+                'sometimes', 'required', 'string', 'max:120',
+                Rule::unique('stages', 'name')->where('event_id', $eventId)->ignore($stageId),
+            ],
+            'color' => ['sometimes', 'required', 'string', 'size:7', 'regex:/^#[0-9A-Fa-f]{6}$/'],
+            'capacity' => ['sometimes', 'nullable', 'integer', 'min:0'],
+            'sort_order' => ['sometimes', 'nullable', 'integer', 'min:0'],
+        ];
+    }
+}

api/app/Http/Requests/Api/V1/Portal/SubmitEngagementSectionRequest.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1\Portal;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * Validates the body of POST /p/artist/{token}/sections/{section}.
+ *
+ * Body shape: { values: { "<field-slug>": <value>, ... } }
+ *
+ * Per-field type validation runs inside FormValueService against the
+ * form_field_validation_rules rows; this request only enforces the
+ * envelope shape so we can reject malformed requests early.
+ */
+final class SubmitEngagementSectionRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        // Auth lives in the controller (via ArtistResolver token check).
+        return true;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [
+            'values' => ['required', 'array'],
+            'values.*' => ['nullable'],
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/Artist/ArtistContactResource.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Models\ArtistContact;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin ArtistContact
+ */
+final class ArtistContactResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'artist_id' => $this->artist_id,
+            'name' => $this->name,
+            'email' => $this->email,
+            'phone' => $this->phone,
+            'role' => $this->role,
+            'is_primary' => (bool) $this->is_primary,
+            'receives_briefing' => (bool) $this->receives_briefing,
+            'receives_infosheet' => (bool) $this->receives_infosheet,
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/Artist/ArtistEngagementResource.php

@@ -0,0 +1,124 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Enums\Artist\BumaHandledBy;
+use App\Models\ArtistEngagement;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin ArtistEngagement
+ *
+ * Buma + VAT formulas (RFC v0.2 D26 — must match Session 5 client-side
+ * preview):
+ *
+ *   buma_amount    = fee × buma_percentage / 100
+ *                    IFF buma_applicable && buma_handled_by === Organisation
+ *                    ELSE 0
+ *
+ *   vat_grondslag  = fee + (buma_amount IF Organisation handles buma ELSE 0)
+ *
+ *   vat_amount     = vat_grondslag × vat_percentage / 100  IF vat_applicable
+ *                    ELSE 0
+ *
+ *   total_cost     = fee + buma_amount + vat_amount
+ *                  + Σ deal_breakdown[*].amount
+ */
+final class ArtistEngagementResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        $fee = (float) ($this->fee_amount ?? 0);
+        $bumaPercentage = (float) ($this->buma_percentage ?? 0);
+        $vatPercentage = (float) ($this->vat_percentage ?? 0);
+
+        $bumaAmount = ($this->buma_applicable && $this->buma_handled_by === BumaHandledBy::Organisation)
+            ? round($fee * $bumaPercentage / 100, 2)
+            : 0.0;
+
+        $vatGrondslag = $fee + (
+            $this->buma_handled_by === BumaHandledBy::Organisation
+                ? $bumaAmount
+                : 0.0
+        );
+
+        $vatAmount = $this->vat_applicable
+            ? round($vatGrondslag * $vatPercentage / 100, 2)
+            : 0.0;
+
+        $breakdownTotal = 0.0;
+        foreach ((array) $this->deal_breakdown as $line) {
+            if (is_array($line) && isset($line['amount'])) {
+                $breakdownTotal += (float) $line['amount'];
+            }
+        }
+
+        $totalCost = round($fee + $bumaAmount + $vatAmount + $breakdownTotal, 2);
+
+        return [
+            'id' => $this->id,
+            'organisation_id' => $this->organisation_id,
+            'artist_id' => $this->artist_id,
+            'event_id' => $this->event_id,
+            'artist' => ArtistResource::make($this->whenLoaded('artist')),
+            'project_leader_id' => $this->project_leader_id,
+            'project_leader' => $this->whenLoaded('projectLeader', fn () => [
+                'id' => $this->projectLeader?->id,
+                'name' => trim(($this->projectLeader?->first_name ?? '').' '.($this->projectLeader?->last_name ?? '')),
+                'email' => $this->projectLeader?->email,
+            ]),
+            'booking_status' => [
+                'value' => $this->booking_status?->value,
+                'label' => $this->booking_status?->label(),
+            ],
+            'fee_amount' => $this->fee_amount,
+            'fee_currency' => $this->fee_currency,
+            'fee_type' => [
+                'value' => $this->fee_type?->value,
+                'label' => $this->fee_type?->label(),
+            ],
+            'buma_applicable' => (bool) $this->buma_applicable,
+            'buma_percentage' => $this->buma_percentage,
+            'buma_handled_by' => [
+                'value' => $this->buma_handled_by?->value,
+                'label' => $this->buma_handled_by?->label(),
+            ],
+            'vat_applicable' => (bool) $this->vat_applicable,
+            'vat_percentage' => $this->vat_percentage,
+            'deal_breakdown' => $this->deal_breakdown,
+            'deposit_percentage' => $this->deposit_percentage,
+            'deposit_due_date' => optional($this->deposit_due_date)->toIso8601String(),
+            'balance_due_date' => optional($this->balance_due_date)->toIso8601String(),
+            'payment_status' => [
+                'value' => $this->payment_status?->value,
+                'label' => $this->payment_status?->label(),
+            ],
+            'crew_count' => $this->crew_count,
+            'guests_count' => $this->guests_count,
+            'requested_at' => optional($this->requested_at)->toIso8601String(),
+            'option_expires_at' => optional($this->option_expires_at)->toIso8601String(),
+            'advance_open_from' => optional($this->advance_open_from)->toIso8601String(),
+            'advance_open_to' => optional($this->advance_open_to)->toIso8601String(),
+            'advancing_completed_count' => $this->advancing_completed_count,
+            'advancing_total_count' => $this->advancing_total_count,
+            'notes' => $this->notes,
+            'computed' => [
+                'buma_amount' => $bumaAmount,
+                'vat_grondslag' => $vatGrondslag,
+                'vat_amount' => $vatAmount,
+                'breakdown_total' => $breakdownTotal,
+                'total_cost' => $totalCost,
+            ],
+            'performances' => PerformanceResource::collection($this->whenLoaded('performances')),
+            'created_at' => optional($this->created_at)->toIso8601String(),
+            'updated_at' => optional($this->updated_at)->toIso8601String(),
+            'deleted_at' => optional($this->deleted_at)->toIso8601String(),
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/Artist/ArtistResource.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Enums\Artist\ArtistEngagementStatus;
+use App\Models\Artist;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin Artist
+ */
+final class ArtistResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        $lifetime = $this->engagements()
+            ->whereNotIn('booking_status', [
+                ArtistEngagementStatus::Cancelled->value,
+                ArtistEngagementStatus::Rejected->value,
+                ArtistEngagementStatus::Declined->value,
+            ])
+            ->count();
+
+        $upcoming = $this->engagements()
+            ->whereNotIn('booking_status', [
+                ArtistEngagementStatus::Cancelled->value,
+                ArtistEngagementStatus::Rejected->value,
+                ArtistEngagementStatus::Declined->value,
+            ])
+            ->whereHas('event', fn ($q) => $q->where('end_date', '>=', now()->toDateString()))
+            ->count();
+
+        return [
+            'id' => $this->id,
+            'organisation_id' => $this->organisation_id,
+            'name' => $this->name,
+            'slug' => $this->slug,
+            'default_genre_id' => $this->default_genre_id,
+            'default_genre' => GenreResource::make($this->whenLoaded('defaultGenre')),
+            'default_draw' => $this->default_draw,
+            'star_rating' => $this->star_rating,
+            'home_base_country' => $this->home_base_country,
+            'agent_company_id' => $this->agent_company_id,
+            'agent_company' => $this->whenLoaded(
+                'agentCompany',
+                fn () => [
+                    'id' => $this->agentCompany?->id,
+                    'name' => $this->agentCompany?->name,
+                    'handles_buma' => (bool) ($this->agentCompany?->handles_buma ?? false),
+                ],
+            ),
+            'notes' => $this->notes,
+            'contacts' => ArtistContactResource::collection($this->whenLoaded('contacts')),
+            'engagements_summary' => [
+                'lifetime_count' => $lifetime,
+                'upcoming_count' => $upcoming,
+            ],
+            'created_at' => optional($this->created_at)->toIso8601String(),
+            'updated_at' => optional($this->updated_at)->toIso8601String(),
+            'deleted_at' => optional($this->deleted_at)->toIso8601String(),
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/Artist/GenreResource.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Models\Genre;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin Genre
+ */
+final class GenreResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'organisation_id' => $this->organisation_id,
+            'name' => $this->name,
+            'color' => $this->color,
+            'sort_order' => $this->sort_order,
+            'is_active' => (bool) $this->is_active,
+            'created_at' => optional($this->created_at)->toIso8601String(),
+            'updated_at' => optional($this->updated_at)->toIso8601String(),
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/Artist/PerformanceResource.php

@@ -0,0 +1,109 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Models\Performance;
+use App\Services\Artist\LaneResolver;
+use Carbon\CarbonImmutable;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin Performance
+ */
+final class PerformanceResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'engagement_id' => $this->engagement_id,
+            'event_id' => $this->event_id,
+            'stage_id' => $this->stage_id,
+            'lane' => (int) $this->lane,
+            'lane_resolved' => $this->resolveLane(),
+            'start_at' => optional($this->start_at)->toIso8601String(),
+            'end_at' => optional($this->end_at)->toIso8601String(),
+            'version' => (int) $this->version,
+            'notes' => $this->notes,
+            'warnings' => $this->computeWarnings(),
+            'engagement' => ArtistEngagementResource::make($this->whenLoaded('engagement')),
+            'stage' => StageResource::make($this->whenLoaded('stage')),
+            'created_at' => optional($this->created_at)->toIso8601String(),
+            'updated_at' => optional($this->updated_at)->toIso8601String(),
+            'deleted_at' => optional($this->deleted_at)->toIso8601String(),
+        ];
+    }
+
+    /**
+     * Computed via LaneResolver over the (stage, sub-event) cohort.
+     * For parked performances (stage_id = null) the persisted lane is
+     * surfaced as-is — the wachtrij is a flat list, not a lane grid.
+     */
+    private function resolveLane(): int
+    {
+        if ($this->stage_id === null) {
+            return (int) $this->lane;
+        }
+
+        $cohort = Performance::query()
+            ->where('stage_id', $this->stage_id)
+            ->where('event_id', $this->event_id)
+            ->get();
+
+        $resolved = app(LaneResolver::class)->resolve($cohort);
+
+        return $resolved[(string) $this->id] ?? (int) $this->lane;
+    }
+
+    /**
+     * RFC v0.2 D5 / D6 / D25 — overlap, B2B, capacity warnings.
+     * Naive implementation for Session 2; refined as the timetable
+     * frontend lands in Session 4.
+     *
+     * @return array<int, string>
+     */
+    private function computeWarnings(): array
+    {
+        $warnings = [];
+
+        if ($this->stage_id === null) {
+            return $warnings;
+        }
+
+        $start = CarbonImmutable::instance($this->start_at);
+        $end = CarbonImmutable::instance($this->end_at);
+
+        $peers = Performance::query()
+            ->where('stage_id', $this->stage_id)
+            ->where('event_id', $this->event_id)
+            ->where('id', '!=', $this->id)
+            ->get();
+
+        foreach ($peers as $other) {
+            $oStart = CarbonImmutable::instance($other->start_at);
+            $oEnd = CarbonImmutable::instance($other->end_at);
+
+            if ($start < $oEnd && $oStart < $end && (int) $other->lane === (int) $this->lane) {
+                $warnings[] = 'overlap';
+                break;
+            }
+        }
+
+        foreach ($peers as $other) {
+            $oEnd = CarbonImmutable::instance($other->end_at);
+            $oStart = CarbonImmutable::instance($other->start_at);
+            if ($oEnd->equalTo($start) || $oStart->equalTo($end)) {
+                $warnings[] = 'b2b';
+                break;
+            }
+        }
+
+        return array_values(array_unique($warnings));
+    }
+}

api/app/Http/Resources/Api/V1/Artist/StageResource.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1\Artist;
+
+use App\Models\Stage;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin Stage
+ */
+final class StageResource extends JsonResource
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'event_id' => $this->event_id,
+            'name' => $this->name,
+            'color' => $this->color,
+            'capacity' => $this->capacity,
+            'sort_order' => $this->sort_order,
+            'stage_days' => $this->whenLoaded(
+                'stageDays',
+                fn () => $this->stageDays->pluck('event_id')->all(),
+            ),
+            'created_at' => optional($this->created_at)->toIso8601String(),
+            'updated_at' => optional($this->updated_at)->toIso8601String(),
+        ];
+    }
+}