indira-workspace-ui 0.1.0

package/.claude/skills/indira-api/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: indira-api
+description: Scaffold and extend Node/Express backend services in the Indira API architecture — routes/controller/service/repository/model layering, validated per-environment config, PM2 process definitions, and Pino structured HTTP logging with an audit trail on every mutation. Ensures every backend app shares the same folder structure and constraints. Use for any new Express service, or any new module (patient, auth, appointment, audit, billing, ...) added to an existing one.
+---
+
+# indira-api
+
+You build Node/Express backend services in the **Indira API architecture**.
+The full spec lives at `docs/api-architecture.md` in the target repository —
+read it completely before doing anything else; every path, filename and rule
+you need is in it, and this skill does not repeat them.
+
+Your job has four parts, in order. Do not skip Part 0 or Part 1.
+
+## Part 0 — Establish the spec (new repo only)
+
+Check whether the target repo already has `docs/api-architecture.md`.
+
+- **It exists** — read it. It is the source of truth for *this* repo, even
+  where a later edition of this skill's own copy has moved on. Follow what's
+  written there; if it's silent on something this skill covers, follow this
+  skill and consider proposing an addition to the repo's doc.
+- **It does not exist** — this is a new service. Copy
+  `reference/api-architecture.md` from this skill into `docs/api-architecture.md`
+  in the target repo verbatim, then fill in the one placeholder it leaves
+  open: §2.4 names the DB driver/ORM as "a per-app choice, recorded here" —
+  ask which one this app uses (see Part 1) and write it into that section
+  before treating the doc as final.
+
+Never invent a second architecture doc under a different name or path —
+`docs/api-architecture.md` is the one location, matching how the UI side of
+these apps keeps its spec at `docs/design-system.md`.
+
+## Part 1 — Ask before you scaffold
+
+Do not scaffold from a one-line request. For a **new service**, confirm:
+
+- **Purpose & callers** — what does this service do, and who calls it (a
+  specific frontend, another internal service, a cron, a webhook)?
+- **Database** — Postgres, MySQL, MongoDB, something else? Driver or ORM
+  preference, or should it match another Indira service for consistency?
+- **First modules** — beyond the mandatory `auth` and `audit` (§12 of the
+  spec builds these first), which domain modules does the initial version
+  need? Get the entity name and its core fields for each.
+- **Auth model** — session, JWT, SSO against an existing identity provider?
+  Anything from an existing Indira service to reuse rather than reinvent?
+- **Environments** — which of local/uat/production does this need on day
+  one, and are there secrets beyond DB + mail that the env schema must
+  declare?
+
+For a **new module in an existing service**, confirm just:
+
+- **Entity & fields** — name and core fields of the thing this module owns.
+- **Operations** — CRUD, or specific actions (e.g. "approve", "cancel")?
+  Which need auth scopes beyond a logged-in user?
+- **Cross-module reads** — which existing modules' *services* (never
+  repositories) does this one need to call?
+- **Sensitive fields** — anything that must be redacted from logs or kept
+  out of the default list response, per §5 and law 4 of the spec.
+
+Write the answers up as a short brief and confirm it before Part 2:
+
+```
+Service: <name>                 New service | New module in <service>
+DB: <engine/ORM>                Auth: <model>
+Modules (first cut): <a>, <b>, auth, audit
+For <this module>: entity <name>, fields <...>, operations <...>
+Depends on (via service): <module>, <module>
+Sensitive fields: <...>
+```
+
+## Part 2 — Plan the files
+
+List, module by module, exactly the files §1–§2 of the spec require —
+`routes.js dto.js controller.js service.js repository.js model.js`, plus
+`errors.js` only if the module needs a domain-specific error and
+`test.js` for its unit tests. No extra files, no extra top-level folders.
+
+Checks before you build — answer each with yes:
+
+- Does every route have a matching DTO validating body/params/query (§7,
+  law 6)?
+- Does the controller do nothing but translate HTTP ↔ domain — no DB import,
+  no business `if` (§2.2)?
+- Does the repository expose plain async functions only, with zero business
+  rules (§2.4)?
+- Does every mutation route sit behind the shared write path that writes to
+  `audit` (law 5)?
+- Does every write route (bar the ones explicitly public) sit behind
+  `auth(...)` (§10)?
+- Are cross-module calls going through the other module's *service*, never
+  its repository or model (law 7)?
+- Will a missing/invalid env var stop boot rather than fail mid-request
+  (§3, law 2)?
+
+If any answer is no, fix the plan before writing code.
+
+## Part 3 — Build
+
+1. If Part 0 created a new doc, scaffold the tree in §1 exactly: `app.js`,
+   `server.js`, `config/`, `shared/{middleware,errors,mail,logger,utils}`,
+   `routes.js`, `ecosystem.config.js`, `.env.example`.
+2. Wire `config/index.js` (§3) with a Zod schema covering every env var this
+   app needs so far. Confirm it exits non-zero on a missing required key —
+   check this once by actually removing a required var and running it,
+   don't assume the schema does what it looks like it does.
+3. Wire the shared Pino logger + `pino-http` (§5) into `app.js` **before**
+   any route, then `helmet`, CORS from config, a body size limit, and the
+   `/api/auth/*` rate limiter (§10).
+4. Wire `errorHandler.js` (§6) as the last middleware, after `routes.js` is
+   mounted.
+5. Build `auth` and `audit` first if they don't exist yet — every other
+   module depends on both.
+6. For each domain module, write files in this order so nothing imports
+   something that doesn't exist yet: `dto.js` → `model.js` →
+   `repository.js` → `service.js` → `controller.js` → `routes.js`, then
+   mount the router in `routes.js`.
+7. Add `ecosystem.config.js` and `.env.example` (or extend them) so every
+   key the config schema declares has a placeholder.
+8. Write one integration test per new route under `tests/`, and unit tests
+   for the service's business rules beside the module.
+9. Verify (§12 of the spec): the server boots, `GET /api/health` returns
+   200, one request produces one structured Pino log line carrying a
+   request id, and a deliberately-triggered error returns the `{ error:
+   { code, message, requestId } }` shape with that same id.
+
+## What "done" looks like
+
+Give back, in this order: the confirmed brief, the file plan, what was
+scaffolded vs. added to an existing module, the verification results from
+step 9, and — if this touched `docs/api-architecture.md` — a note of what
+changed there and why, since that file governs every other app too.
+
+## Things you never do
+
+- Read `process.env` anywhere outside `config/index.js`.
+- Let a controller import a repository or a DB driver, or a repository
+  contain a business decision.
+- Call `console.log`/`console.error` for application logging.
+- Return an error value from a service for a controller to branch on —
+  services throw.
+- Add a write route without wiring it to the audit trail, or without
+  `auth(...)` unless it's deliberately public.
+- Commit a real `.env.local`/`.env.uat`/`.env.production` file, or put a
+  secret in `ecosystem.config.js`.
+- Invent a second architecture doc, a new top-level `src/` folder, or a
+  driver/ORM choice that contradicts what `docs/api-architecture.md`
+  already recorded for this repo.

package/.claude/skills/indira-api/reference/api-architecture.md

@@ -0,0 +1,337 @@
+# Indira API architecture specification
+
+A build-from-scratch specification for the Node/Express backend services used
+across Indira apps. Written so an agent (or a person) can scaffold a new
+service, or extend an existing one, and land on the exact same shape every
+time. Where a path or a filename appears, it is the path — not a suggestion.
+
+The reference stack is Express + a validated env config + Pino logging. The
+database driver/ORM is a per-app choice (see §2.4); everything else here is
+fixed.
+
+---
+
+## 0. The three sentences
+
+1. **A request flows in one direction only**: route → controller → service →
+   repository → database, and back out the same way in reverse. No layer
+   calls sideways or skips the one below it.
+2. **Config is validated once, at boot, in one place.** If an environment
+   variable is missing or malformed, the process refuses to start — it never
+   fails later, mid-request, in a way that's hard to trace.
+3. **Every request is logged as one structured line, and every domain
+   mutation is written to the audit trail.** Nothing is inferred from
+   `console.log` output after the fact.
+
+---
+
+## 1. Folder structure
+
+```
+server/
+├── src/
+│   ├── app.js                  # express app: middleware, mount routes
+│   ├── server.js               # listen, graceful shutdown
+│   ├── config/
+│   │   ├── index.js            # validated env (zod), single import point
+│   │   └── db.js                # connection/pool setup, exported once
+│   ├── modules/
+│   │   ├── <module>/
+│   │   │   ├── <module>.routes.js
+│   │   │   ├── <module>.controller.js
+│   │   │   ├── <module>.service.js
+│   │   │   ├── <module>.repository.js   # DB access only
+│   │   │   ├── <module>.model.js        # schema / entity
+│   │   │   ├── <module>.dto.js          # request/response shapes + validation
+│   │   │   ├── <module>.errors.js       # domain errors (optional)
+│   │   │   └── <module>.test.js         # unit tests, colocated
+│   │   ├── auth/
+│   │   ├── audit/
+│   │   └── ...                          # one directory per domain module
+│   ├── shared/
+│   │   ├── middleware/         # auth, validate(dto), errorHandler, requestId
+│   │   ├── errors/             # AppError, NotFoundError, ForbiddenError, ...
+│   │   ├── mail/               # transport.js, graph.js
+│   │   ├── logger/             # pino instance + pino-http middleware
+│   │   └── utils/
+│   └── routes.js               # mounts every module's router under /api
+├── tests/                      # integration tests only; unit tests live in modules
+├── scripts/                    # seed, migrate, one-off ops
+├── ecosystem.config.js         # committed; PM2 definition for every environment
+├── .env.example                # committed; placeholders only
+├── .env.local                  # gitignored; developer's machine
+├── .env.uat                    # gitignored; lives only on the UAT box
+├── .env.production             # gitignored; lives only on the prod box
+└── package.json
+```
+
+Nothing is created above `server/src/modules/*` beyond what's listed here. A
+new top-level folder under `src/` is a spec change, not a per-app decision —
+raise it, don't add it quietly.
+
+---
+
+## 2. Layering — one direction, one job per file
+
+### 2.1 Routes (`<module>.routes.js`)
+Declares the Express `Router()`, wires `validate(dto)` and `auth(...)`
+middleware, and points each path at a controller method. No logic. No
+`req`/`res` handling beyond what the router itself needs.
+
+```js
+router.post("/", auth("patient:write"), validate(createPatientDto), controller.create);
+```
+
+### 2.2 Controller (`<module>.controller.js`)
+Translates HTTP ↔ domain: reads `req.params/query/body` (already validated by
+the DTO middleware), calls exactly one service method, and shapes the
+response envelope (§8.2). A controller never imports the repository or the
+database driver, and never contains business rules — if it has an `if` that
+decides an outcome rather than a status code, that branch belongs in the
+service.
+
+### 2.3 Service (`<module>.service.js`)
+All business logic. Orchestrates one or more repositories, calls other
+modules' services directly (never their repositories), throws domain errors
+(§6) instead of returning error objects, and knows nothing about `req`/`res`
+or HTTP status codes.
+
+### 2.4 Repository (`<module>.repository.js`)
+The only file in the module allowed to import the DB driver/ORM. Exposes
+plain async functions (`findById`, `create`, `listByStatus`, ...) that return
+plain objects or `null` — never a query builder, never a raw driver row.
+Contains no business rules: a repository method that decides *whether* to do
+something, not just *how*, has leaked a service concern.
+
+The specific driver/ORM (pg, Prisma, Mongoose, ...) is chosen per app and
+recorded in that app's `docs/api-architecture.md` addendum — the layering
+contract above is what's fixed, not the driver.
+
+### 2.5 Model (`<module>.model.js`)
+The schema/entity definition in whatever the chosen ORM/driver expects, or a
+plain shape comment if the app is schema-less. Read only by the repository.
+
+### 2.6 DTO (`<module>.dto.js`)
+Zod schemas for every request shape the module accepts, and for the response
+shape(s) it returns. The `validate(dto)` middleware (§7) runs these against
+`req.body/params/query` before the controller ever sees the request.
+
+### 2.7 Errors (`<module>.errors.js`, optional)
+Module-specific subclasses of the shared `AppError` (§6) — e.g.
+`PatientAlreadyDischargedError` — for failures that need a distinct code or
+message beyond the generic `NotFoundError`/`ConflictError`.
+
+---
+
+## 3. Config & environments
+
+`src/config/index.js` is the **only** place `process.env` is read directly
+anywhere in the codebase. It:
+
+1. Picks the env file by `NODE_ENV` (`local` → `.env.local`, `uat` →
+   `.env.uat`, `production` → `.env.production`), loaded with `dotenv`.
+2. Validates the merged result against a Zod schema — every variable the app
+   uses is declared, typed, and either required or given a default.
+3. Exports one frozen config object. Everywhere else imports from here:
+   `import { config } from "../config/index.js"`.
+
+If validation fails, the process logs the specific missing/invalid keys and
+exits non-zero — it does not start in a half-configured state.
+
+`.env.example` is committed with every key the schema declares, set to a
+placeholder value. `.env.local`, `.env.uat`, `.env.production` are gitignored
+and never leave the machine/box they belong to.
+
+---
+
+## 4. Process management (PM2)
+
+`ecosystem.config.js` is committed and defines one app entry per environment
+that box runs, e.g.:
+
+```js
+module.exports = {
+  apps: [
+    {
+      name: "api-uat",
+      script: "src/server.js",
+      env: { NODE_ENV: "uat" },
+      instances: 1,
+      exec_mode: "fork",
+      watch: false,
+      autorestart: true,
+    },
+  ],
+};
+```
+
+PM2 supplies `NODE_ENV`; `src/config/index.js` does the rest. PM2 captures
+stdout/stderr for process supervision, but log **content** is Pino's job
+(§5) — PM2 log files are a fallback, not where anyone reads structured logs
+from.
+
+---
+
+## 5. Logging — Pino, always on
+
+`shared/logger/index.js` exports one Pino instance for the whole app:
+
+- **Pretty-printed** (`pino-pretty`) only when `NODE_ENV === "local"`.
+  Every other environment emits newline-delimited JSON to stdout.
+- **Redacts** `req.headers.authorization`, `req.headers.cookie`, and any
+  field named `password`/`token`/`otp` at any depth.
+- Log level from config (`debug` local, `info` uat/production), never
+  hardcoded.
+
+`shared/middleware/httpLogger.js` wires `pino-http` into `app.js` **before**
+the routes are mounted:
+
+```js
+app.use(pinoHttp({ logger, genReqId: (req) => req.headers["x-request-id"] ?? randomUUID() }));
+```
+
+This gives one structured line per request — method, path, status, response
+time, and the request id — and that same request id is attached to every
+`req.log.*` call made deeper in the stack (service, repository) and to the
+error response body (§6.2), so a single request's logs and its error can be
+correlated by id. **No module ever calls `console.log`.**
+
+---
+
+## 6. Errors
+
+### 6.1 Hierarchy
+`shared/errors/AppError.js` is the base class: `{ statusCode, code, message,
+details? }`. Concrete subclasses in the same folder: `NotFoundError` (404),
+`ValidationError` (400), `UnauthorizedError` (401), `ForbiddenError` (403),
+`ConflictError` (409). Modules add their own subclasses (§2.7) only for
+failures the generic set doesn't name.
+
+### 6.2 Central handler
+`shared/middleware/errorHandler.js` is the last middleware in `app.js`. Any
+`AppError` maps straight to its status/code/message; any other thrown error
+is logged at `error` level with the request id and returned as a generic 500
+— its internal message is never sent to the client. Response shape:
+
+```json
+{ "error": { "code": "NOT_FOUND", "message": "Patient not found", "requestId": "..." } }
+```
+
+Every service throws; nothing downstream of a controller returns an error
+value for the controller to inspect.
+
+---
+
+## 7. Validation
+
+`shared/middleware/validate.js` takes a DTO's Zod schema and validates
+`req.body`, `req.params`, and `req.query` before the controller runs,
+throwing a `ValidationError` (with the Zod issue list as `details`) on
+failure. A route with a body, params, or query shape always has a matching
+DTO — a controller reading unvalidated `req.body` directly is a bug, not a
+shortcut.
+
+---
+
+## 8. API surface
+
+### 8.1 Mounting
+`src/routes.js` imports every module's router and mounts it under `/api`:
+
+```js
+router.use("/patients", patientRoutes);
+router.use("/auth", authRoutes);
+```
+
+A version prefix (`/api/v1`) is added only when the app has already shipped
+a v1 and needs to change it — new apps start unversioned.
+
+### 8.2 Response envelope
+Success: `{ "data": <result> }` (a single object, or an array for a list
+endpoint). Paginated lists: `{ "data": [...], "page": { "cursor", "limit",
+"hasMore" } }`. Errors: §6.2's shape. A route never returns a bare array or
+a bare object at the top level — the envelope is constant so a client never
+has to branch on shape.
+
+### 8.3 Health check
+`GET /api/health` (no auth) returns `{ "data": { "status": "ok" } }` and is
+wired before any DB-dependent middleware, so it answers even if a downstream
+dependency is degraded — that's what makes it useful to PM2/monitoring.
+
+---
+
+## 9. Testing
+
+- **Unit tests** live next to the code they test (`<module>.test.js`),
+  exercise the service and repository logic directly, and mock across
+  layers (a service test mocks its repository; it doesn't hit a database).
+- **Integration tests** live in the top-level `tests/`, boot the real
+  `app.js` with `supertest`, and hit it over HTTP against a real (test)
+  database — they verify the layers wired together correctly, not business
+  logic already covered by a unit test.
+- Both run against `.env.local`'s test counterpart or an in-memory/test
+  database — never against `.env.uat` or `.env.production`.
+
+---
+
+## 10. Security baseline
+
+`app.js` always includes, in this order: `helmet()`, CORS configured from
+`config.corsOrigins` (never `*` outside local), a body size limit, and a rate
+limiter on `/api/auth/*`. Every write route sits behind `auth(...)` unless
+it's explicitly public (health check, login). No raw string-concatenated
+SQL anywhere — parameterized queries or the chosen ORM's query builder only.
+Secrets (DB passwords, JWT signing keys, mail credentials) exist only in the
+gitignored `.env.*` files and in the box's process environment — never in
+`ecosystem.config.js`, never in a committed file.
+
+---
+
+## 11. Laws
+
+1. **One direction.** Route → controller → service → repository → DB, and
+   back. A controller that queries the DB, or a repository that contains an
+   `if` deciding business outcome, is a layering violation — fix the layer,
+   don't work around it.
+2. **Fail fast on config.** A missing or invalid env var stops boot. It never
+   surfaces later as an obscure runtime error.
+3. **No naked errors.** Every thrown error is an `AppError` subclass or gets
+   wrapped into one by the central handler before it reaches a client.
+4. **No naked console.** All logging goes through the shared Pino instance;
+   `req.log` inside a request, `logger` outside one.
+5. **Every mutation is audited.** A `POST`/`PATCH`/`PUT`/`DELETE` that
+   changes domain state writes an audit entry (actor, action, entity,
+   before/after or a diff, timestamp) via the `audit` module — this is not
+   optional per-module, it's wired once in the shared write path.
+6. **DTOs are mandatory.** A route accepting a body, params, or query has a
+   DTO validating it before the controller runs.
+7. **One module, one concern.** Cross-module reads go through the other
+   module's service, never its repository or model directly.
+8. **Consistency beats local optimisation.** If a new module wants a shape
+   the spec doesn't have, the answer is usually the existing pattern used
+   plainly. Extend this document (and every app's copy of it) before
+   inventing a one-off.
+
+---
+
+## 12. Building it for a new app
+
+1. Scaffold the tree in §1 exactly. Nothing above `modules/*` beyond what's
+   listed.
+2. Wire `config/index.js` (§3) and confirm the process exits non-zero when a
+   required var is missing — check this once, don't assume it.
+3. Wire the shared Pino logger + `pino-http` (§5) into `app.js` before any
+   route is mounted, then `helmet`, CORS, and the body parser (§10).
+4. Wire `errorHandler.js` (§6) as the last middleware, after `routes.js`.
+5. Add the `auth` and `audit` modules first — every other module depends on
+   both (identity for `auth(...)`, the write path for the audit law).
+6. For each domain module: routes → dto → controller → service →
+   repository → model, in that order, so each file only ever imports things
+   that already exist.
+7. Add `ecosystem.config.js` (§4) and `.env.example` with every key the
+   config schema declares.
+8. Write one integration test per new route in `tests/`, and unit tests for
+   the service's business rules in the module.
+9. Confirm: the server boots, `/api/health` returns 200, one request
+   produces one structured Pino log line carrying a request id, and a
+   deliberately-triggered error returns the §6.2 shape with that same id.

package/.claude/skills/indira-ui/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: indira-ui
+description: Design and build screens in the Indira Workspace UI language. Interviews the developer or business team first (who uses it, what they come to do, what must be found in two seconds), turns the answers into a component hierarchy that shows no more data than the task needs, then builds it from the design-system spec. Use for any new page, dashboard, form, list, or internal tool that should look and behave like the BRD Governance Tool.
+---
+
+# indira-ui
+
+You are a senior product designer who builds. You work in the **Indira
+Workspace UI** language, specified in `docs/design-system.md` in this
+repository. Read that file completely before doing anything else; every
+number and rule you need is in it, and this skill does not repeat them.
+
+Your job has three parts, in order, and you do not skip the first one.
+
+## Part 1 — Grill before you draw
+
+Do not design from a one-line request. Interview until you can answer every
+question below in the requester's own words. Ask in batches of three or four,
+not one at a time, and stop as soon as the answers are clear — this is a
+discovery, not a form. Use the question tool when one is available; otherwise
+ask in prose and wait.
+
+**Who**
+- Who opens this screen, by role? How often — several times a day, once a
+  week, once a quarter?
+- What do they already live in all day (Outlook, Excel, a specific ERP)? Their
+  habits from that tool are the habits to borrow.
+
+**Why they come**
+- What is the *one thing* they most often come here to do? That becomes the
+  primary action — the single filled button, top-right.
+- What is the second and third thing? Those are secondary controls or row
+  actions, never a second filled button.
+- What question are they trying to answer when they land? ("Is anything
+  waiting on me?" "Where is X?") The answer to that question is the first
+  thing the screen shows.
+
+**What they need to see**
+- For each record shown, what are the three facts they scan for? Everything
+  else is a click or a hover away.
+- What do they currently squint at, scroll for, or export to Excel to find?
+- What has been shown on the old screen that nobody uses? (Ask this directly.
+  The answer is what you leave out.)
+
+**What must not go wrong**
+- Which action is irreversible or expensive? It gets a named, status-coloured
+  button and a confirmation with the consequence spelled out.
+- Which data is sensitive to show broadly? It goes behind a hover or a detail
+  view, not a list column.
+
+**Where it lives**
+- Which sidebar section does it belong under? (Its sidebar item is its name —
+  the screen gets no page-title heading.)
+- Is it a list, a detail, a form, or a dashboard? Mixed screens are almost
+  always two screens.
+
+When the requester says "show everything" or "add a description under each
+field", push back once with the reason (laws 3 and 4 in the spec), then build
+what they decide. When they ask for a second primary action, ask which one a
+newcomer should find first; the other becomes tonal.
+
+Write the answers up as a short brief — five lines, not a document — and
+confirm it before Part 2:
+
+```
+Screen: <name>            Under: <sidebar section>   Kind: list | detail | form | dashboard
+Users: <roles, frequency> Habitat: <Outlook / Excel / …>
+Landing question: "<…>"   Primary action: <verb noun>   Secondary: <…>, <…>
+Per-record facts: <a>, <b>, <c>   Hidden until hover/click: <…>
+Irreversible: <action> → confirm with "<consequence>"
+```
+
+## Part 2 — Component hierarchy
+
+Turn the brief into a hierarchy using **only** components from §4 of the spec.
+Write it as an indented tree with the component name, what it shows, and which
+law justifies it. Example shape:
+
+```
+Shell (§3)
+└─ Content panel
+   ├─ Toolbar row                         — law 2: no title; the sidebar names the screen
+   │  ├─ Filter chips (.fchip) by status  — counts from the full set
+   │  └─ [Primary action] filled button   — law 1: the one thing, top-right
+   ├─ Record grid (.brd-card ×N)          — state-first list; orb = status
+   │  └─ per card: title · dept · who · date · approver stack · progress
+   │        (id, priority, status text → title= / sr-only)   — law 3
+   └─ Empty state                         — one tonal button
+```
+
+Checks before you build — answer each with yes:
+
+- Is there exactly one filled button, top-right of the content panel?
+- Is there no page-title heading? (A record title on a detail screen is
+  content, and allowed.)
+- Does every list row show ≤ 5 facts, and is everything else reachable by
+  hover (contact card, tooltip) or click?
+- Is every explanatory sentence gone — replaced by a `title=` tooltip, a
+  contact card, or nothing?
+- Is every status expressed as a shape *and* a colour from the six?
+- Do views use segmented tabs and filters use chips, never the other way round?
+- Does every person render through the Person component (hoverable card)?
+- Can a 4-item form or dialog fit a 900px-tall viewport without scrolling its
+  chrome?
+- Will nothing overflow at 1180px — column plan for >5 columns, truncate +
+  tooltip on single-line cells, clamp-2 on titles?
+- Is the spacing on the 4/8 grid using the recurring numbers in §1.6?
+
+If any answer is no, fix the hierarchy before writing code.
+
+## Part 3 — Build
+
+Build from the spec, not from memory of other design systems.
+
+1. Reuse the existing tokens, shell and components in the repository if they
+   exist (`client/src/app/index.css`, `client/src/shared/ui`, `client/src/entities/user/ui/Person.jsx`).
+   In a fresh project, create them in the order §7 of the spec gives.
+2. Never introduce a colour, radius, shadow, font size or icon outside the
+   scales. If the framework lets you type one, the framework is misconfigured
+   (§1.5: delete the defaults).
+3. Use state layers for hover/press, never a second colour.
+4. Skeletons in the shape of the content while loading; a spinner only inside
+   a working control.
+5. Every clickable person is `<Person>`; every avatar is `<Avatar>` (photo
+   when present, tinted initials otherwise).
+6. Tables over five columns get a `<colgroup>` plan and `table-layout: fixed`.
+7. Finish with an overflow audit at 1440 and 1180 (scan for text wider than
+   its box, clipped without ellipsis, or past the viewport) and a screenshot
+   of each new screen. Report zero offenders, or fix until it is zero.
+
+## What "done" looks like
+
+Give back, in this order: the confirmed brief, the hierarchy tree, the
+screens built, the audit result, and a two-line note of any place the request
+was pushed back on and what was decided. If a requested element was left out
+for a law, name the law — the requester should be able to overrule it
+knowingly, not discover it missing.
+
+## Things you never do
+
+- Add a page-name heading, a hero, a gradient, an emoji icon, or a second
+  filled button.
+- Write a sentence of help text under a control.
+- Show an id, a status word and a status colour for the same record in the
+  same place.
+- Invent a colour for a new status. Six statuses; a seventh is a product
+  decision, not a design one.
+- Use a spinner for page content, or animate anything on a loop.
+- Design a screen for a user you have not asked about.