# Operation Head (Web) — Dev-mode v1.0 design pack

> **Step 3b role pack — mirrors the ANCHOR pack** (`staff-court-monitor-mobile/`) file-for-file. Built 2026-06-18.
> The ANCHOR set the TEMPLATE; this pack is the **top-authority web counterpart** — the role that *receives* the cascade the Monitor produces and gives it its **final** approval.
> **Persona:** **Anjali Desai** · Operation Head (`OH`) · top of the 7-level hierarchy · **sees ALL Game Zones** (Ahmedabad-1, Ahmedabad-2, Surat-1, …). No `reportsTo`. Full system access (dynamic RBAC, not hardcoded).
> **Platform:** **Web (Next.js admin panel) — desktop 1440×900 baseline.** Web is this role's *primary* surface (`SCREEN_LIST` surface key); a thin mobile companion for on-floor approvals exists but is NOT this pack's pixel target.
> **Chrome:** Maniax web shell per `DESIGN_SYSTEM §8.1` — **240px navy sidebar** (wordmark lockup → 3 nav groups → utility cluster → user chip) + **64px sticky topbar** with the **Game-Zone selector chip** (`Game Zone · All ▾` → switch branch) + breadcrumb strip.
> **Change List v1.1 (CL-1 + CL-2) applied:** OH now has **full checklist-template CRUD across all GZ** — the **Upload Check List** module (`OH-CHK-UPLOAD` list + `ChecklistBuilder` Stepper → `OH-CHK-TPL-ASSIGN` → `OH-CHK-TPL-EDIT`) — plus the org-wide **Action / Work-Order overview** (`OH-WO-OVERVIEW`, read/monitor across all GZ). Two new OPERATIONS sidebar items (**Upload Check List** `clipboard-list`, **Work-Orders** `wrench`). **OH is now 22 screens.**

---

## What's in this pack

| File / folder | What |
|---|---|
| `README.md` | You are here — slot scope, persona, sidebar, topbar GZ selector, out-of-slot. |
| `SCREENS.md` | Full web screen inventory (the FE burn-down checklist) with states/modals per screen. |
| `spec.md` | Per-screen acceptance detail (Given/When/Then) — final-approval, send-back-to-filler, derived **Pending**, RBAC matrix editing, cross-GZ scope. |
| `api-contract.md` | Every endpoint this role consumes (`Method \| Path \| Roles \| Body \| Returns`). |
| `HANDOFFS.md` | Cross-role touchpoints — receives the cascade from SM (the level-3 step), is the terminal **Done** node; send-back returns to the original filler. |
| `flows/` | `final-approval-and-done.md`, `manage-users-and-rbac-matrix.md` — multi-step walkthroughs. |
| `screens/` | Self-contained HTML mockups (web 1440×900) — the pixel target. |
| `states/` | loading / empty / error / 403 / 401-session-expired / no-results state variants. |
| `modals/` | send-back-reason · approve-confirm · assign-Store-Manager · reassign-manager-confirm · deactivate-user · photo-lightbox · **assign-template** *(CL-1)* · **change-items-confirm** *(CL-1)* (web uses **modals/drawers**, NOT bottom-sheets). |
| `handoff/README.md` | 11-point Definition of Done + blocking questions for this slot. |
| `handoff/tasks.md` | Task rows: Screen ID, file, states/modals, dependencies, Web-FE + Backend tasks, priority. |

## How to read this pack

1. Start with **`SCREENS.md`** — the full bird's-eye of the 22 OH screens (+ shared auth entry).
2. Use **`handoff/README.md`** DoD as your tick-list.
3. For each screen, read its **`spec.md`** section + the relevant **`flows/`** walkthrough + the **`api-contract.md`** rows.
4. Use **`HANDOFFS.md`** when wiring the final-approval touchpoint and the derived-Pending rule (don't reinvent the contract — it lives in `FOUNDATION_SPEC §4`).
5. Open any `screens/*.html` in a browser at 1440px width to see the visual contract.

## Sidebar (web, data-driven — `DESIGN_SYSTEM §2.6 + §7`)

Fixed **240px**, bg `brand-navy`, white text, `brand-light-blue` group labels, **orange active accent** (3px left-edge bar + orange icon/label). Wordmark lockup top (AIR in orange / MANIAX in white). **10 nav items in 3 groups** (CL-1/CL-2 added **Upload Check List** + **Work-Orders** under OPERATIONS). Utility cluster (Notifications · Profile · Settings · Logout) + user chip pinned at the bottom of every screen.

| Group | Item | Lucide | Target screen |
|---|---|---|---|
| OVERVIEW | Dashboard | `layout-dashboard` | `OH-DASH` |
| OVERVIEW | Game Zones | `building-2` | `OH-GZ-LIST` (→ `OH-GZ-NEW` / `OH-GZ-EDIT` / `OH-GZ-DETAIL` → `OH-RIDE-MASTER`) |
| OVERVIEW | Hierarchy | `network` | `OH-HIER-TREE` |
| PEOPLE | Users | `users` | `OH-USERS` (→ `OH-USER-NEW` / `OH-USER-EDIT` / `OH-USER-DETAIL`) |
| PEOPLE | Roles & Access | `shield-check` | `OH-ROLES` (the editable RBAC matrix) |
| OPERATIONS | Roster | `calendar-days` | `OH-ROSTER-ALL` |
| OPERATIONS | Checklists | `list-checks` | `OH-CHK-OVERVIEW` (→ `OH-CHK-APPROVE`) |
| OPERATIONS | Upload Check List *(CL-1)* | `clipboard-list` | `OH-CHK-UPLOAD` (→ `OH-CHK-TPL-ASSIGN` / `OH-CHK-TPL-EDIT`) |
| OPERATIONS | Work-Orders *(CL-2)* | `wrench` | `OH-WO-OVERVIEW` |
| OPERATIONS | Reports | `bar-chart-3` | `OH-REP-POSITIVE` (tabs → Negative / Overdue) |

> The **Game-Zone scope lives in the topbar, not the nav** (`DESIGN_SYSTEM §6.3 / §7`). OH gets the **interactive selector chip** (`building-2` + `Game Zone · All ▾`) — switching re-scopes every `[GZ: all]` view; "All" aggregates across branches. The OH never loses cross-Game-Zone visibility.

## Topbar — Game-Zone selector (OH-specific, critical)

64px sticky, `surface` bg + `shadow-sm` bottom. Breadcrumb left · global search center · **Game-Zone selector chip** + bell + profile right.
- Default state: `🏢 Game Zone · All ▾` — every list/dashboard aggregates across all branches.
- Switched state: `🏢 Game Zone · Ahmedabad-1 ▾` — the same views re-scope to one branch (read-only filter; OH retains full rights inside it).
- This is the ONLY scope affordance; SM/TL get a non-interactive badge instead (their packs). OH alone gets the dropdown.

## Hard constraints (re-affirmed)

- **Web desktop only.** 1440×900 baseline. Desktop **modals + right-side drawers** (NOT mobile bottom-sheets). Navy 240px sidebar, 64px topbar.
- **Design tokens:** Maniax palette (`#F58220` orange / `#ED1C24` red-orange / `#2E6DB4` blue / `#16284A` navy / `#7FB2E5` light-blue), **DM Sans**, **navy-on-orange** primary buttons, light-blue as fill-only. Per `DESIGN_SYSTEM.md`.
- **Approve = green, Send-back = red-orange** (`DESIGN_SYSTEM §6.4`) — action color equals outcome color. **G is green, A is red-orange** everywhere. Status by label+icon+color, never color alone.
- **Derived "Pending" (§9 #5):** OH sees **Pending** (amber) for any checklist not yet `OH_APPROVED` — daily/weekly/monthly/quarterly/yearly alike. Pending is **never stored**; it is computed by the shared `renderStatusForViewer()`. OH approval is the **terminal** step → `Done`.
- **Send-back goes to the original filler (§9 #3), restart-from-TL (§9 #8):** when OH sends back, the instance → `SENT_BACK` and returns to the Monitor/CS/TL who filled it (not the previous approver); on re-submit the cascade restarts fresh from TL.
- **Server time + auto-initials (§9 #9):** OH views are read-only on item-level time/initials — those are server-stamped at fill time, tamper-proof. OH never edits them.
- **Photo evidence (§4a / §9 #7):** OH sees the completion photo(s) + per-A-item issue photos in the approval drawer + the negative report (lightbox). Min-1 completion photo was enforced at fill; OH only views.
- **Dynamic RBAC.** Sidebar + permissions come from `GET /me`; no hardcoded role logic. The **`OH-ROLES` matrix is live-editable** — a permission change takes effect on the next request (no redeploy). No spec'd endpoint hardcodes a role check.
- **Multi-branch scope = OH sees all (§4c / L5):** no Game-Zone filter applied for OH; the topbar selector is a convenience, not a security boundary. Every other role is scoped down.
- **Local-disk photo storage** on the VPS — the lightbox loads `Photo.url` from local disk, no cloud bucket pickers.
- **Template builder (CL-1):** `OH-CHK-UPLOAD` uses the `ChecklistBuilder` (`DESIGN_SYSTEM §6.21`) — a 4-step Stepper (Details → Sections & Items → Assign → Review). Item fields: text, **test method**, **G/A** input, **requires-photo-on-A**. Frequency includes the CL-1 first-class **opening / closing** values. The Assign step writes the role/ride/shift/GZ mapping that drives auto-assign (`FOUNDATION_SPEC §3`, honoring `fillRoleCode` + `gameZoneId`).
- **Work-Orders read-only (CL-2):** `OH-WO-OVERVIEW` is **observe / monitor only** across all GZ — OH does **not** route, assign, fix, return, or outsource. The maintenance track (route → assign → fix/return → close/outsource) is owned by `maintenance-tl-web` + `technician-mobile`. **Single-track hold:** a checklist with any open A-item Work-Order reads **Held** (`st-held`, deep-orange) on `OH-CHK-OVERVIEW` and cannot reach Done until every WO closes; **only `Outsourced` WOs reach the Store Manager.**
- **English-only, single-tenant.** No language/tenant/theme switcher beside the wordmark.

## What's NOT in this slot

- **Filling checklists** — OH does not fill; the G/A toggle + photo capture lives in the filler packs (MON/SCM/CS/TL). OH only **views evidence + approves/sends-back**.
- **TL / SM approval steps** — those are levels 1 and 2; this pack is the **level-3 (final)** step only. Their queues live in the TL/SM packs.
- **Building rosters** — `OH-ROSTER-ALL` is a **read-across-zones overview** (gap alerts), not a builder. Roster build + publish (which fires auto-assign) lives in SM/TL packs.
- **~~Creating / editing checklist templates~~** — **AMENDED by CL-1:** OH now has **full template CRUD across all Game Zones** via the **Upload Check List** module (`OH-CHK-UPLOAD` / `OH-CHK-TPL-ASSIGN` / `OH-CHK-TPL-EDIT`, `ChecklistBuilder` §6.21). OH can create / upload, assign (role/ride/shift/GZ scope → feeds auto-assign), and edit templates — seeded *and* custom, org-wide. (SM authors for its own GZ; TL for its own team.) Auto-assign generation stays server-side.
- **The mobile companion** (on-floor OH approvals) is a P2 secondary surface; this pack is the web pixel target.
- **Rotation, Capacity, Training, Events, School Visits** — out of Phase 1 (P3–P5).

---

## File references

- Pack root: `docs/design/dev-mode-v1.0/operation-head-web/`
- Anchor (mirrored): `docs/design/dev-mode-v1.0/staff-court-monitor-mobile/`
- Foundation: `docs/dev-mode-v1.0/FOUNDATION_SPEC.md` (schema, API conventions, auto-assign, cascade, derived-Pending, multi-branch RBAC)
- Dev plan: `docs/dev-mode-v1.0/DEV_EXECUTION_PLAN.md`
- Project plan: `docs/PROJECT_PLAN.md` · Screen list: `docs/design/SCREEN_LIST.md` · Design system: `docs/design/DESIGN_SYSTEM.md`
- Workflow: `docs/WORKFLOW_GUIDE.md` (Stage F — the Anjali final-approval example)
