indira-workspace-ui 0.1.0 → 0.2.0

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

@@ -1,6 +1,6 @@
 ---
 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.
+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. Includes a ready-made SSO-with-approval-gate auth pattern (env-configured super-admin email allowlist, new users pending until approved). Ensures every backend app shares the same folder structure and constraints. Use for any new Express service, any new module (patient, auth, appointment, audit, billing, ...) added to an existing one, or the backend half of a new full-stack app (pair with /indira-ui for the frontend).
 ---
 
 # indira-api
@@ -10,6 +10,12 @@ 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.
 
+**Building a brand-new full-stack app?** Scaffold the backend first —
+`auth` and `audit` before any domain module (§13 of the spec) — then hand
+off to `/indira-ui` for the frontend. That skill designs the screens; it
+doesn't invent the data they show, so the API should exist (even just
+scaffolded and booting) before it starts.
+
 Your job has four parts, in order. Do not skip Part 0 or Part 1.
 
 ## Part 0 — Establish the spec (new repo only)
@@ -39,11 +45,15 @@ Do not scaffold from a one-line request. For a **new service**, confirm:
   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
+- **First modules** — beyond the mandatory `auth` and `audit` (§13 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?
+  If it's SSO with an approval gate (a new user is `pending` until a super
+  admin approves them; an env-configured email allowlist grants super-admin
+  on first login) that exact pattern is §12 of the reference spec — read it
+  before scaffolding `auth`, don't design it from scratch. 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?
@@ -119,7 +129,7 @@ If any answer is no, fix the plan before writing code.
    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
+9. Verify (§13 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.

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

@@ -311,10 +311,80 @@ gitignored `.env.*` files and in the box's process environment — never in
    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.
+9. **The super-admin allowlist lives in env, not the database.**
+   `SUPER_ADMIN_EMAILS` (§12.1) is read at boot and re-checked on every SSO
+   login — never exposed as an editable field, never granted through an API
+   call.
 
 ---
 
-## 12. Building it for a new app
+## 12. SSO authentication with an approval gate
+
+A pattern for services that authenticate against a corporate identity
+provider (reference IdP: Microsoft Entra ID / Azure AD, via OIDC) instead of
+issuing their own passwords, and that gate a brand-new user behind a human
+approval before they can do anything.
+
+### 12.1 Config
+
+`config/index.js`'s schema declares, alongside the existing keys:
+
+```
+SSO_TENANT_ID        required
+SSO_CLIENT_ID        required
+SSO_CLIENT_SECRET    required
+SSO_REDIRECT_URI     required
+SUPER_ADMIN_EMAILS   required, comma-separated, lower-cased and trimmed on read
+```
+
+`SUPER_ADMIN_EMAILS` is the one allowlist that grants the `super_admin`
+role. It is never stored in the database and never editable from the API —
+the only way to change who is a super admin is to change this env var and
+redeploy. That is deliberate: the people who can approve new accounts must
+themselves be provisioned outside the thing they administer.
+
+### 12.2 Flow
+
+1. `GET /api/auth/sso/login` redirects to the IdP's OIDC authorize endpoint
+   (state + PKCE verifier stored server-side, keyed by a short-lived cookie).
+2. `GET /api/auth/sso/callback` exchanges the code, validates the id_token
+   (issuer, audience, signature, nonce), and extracts the verified email.
+3. Look the email up in `users`:
+   - **Not found, and email ∈ `SUPER_ADMIN_EMAILS`** — create the user with
+     `role: "super_admin"`, `status: "active"`, issue the session/JWT +
+     refresh token immediately.
+   - **Not found, and email ∉ `SUPER_ADMIN_EMAILS`** — create the user with
+     `status: "pending"`, `role: "member"`. Do **not** issue a session.
+     Respond `202 { data: { status: "pending" } }` — the client shows a
+     "waiting for approval" screen, not an error.
+   - **Found, `status: "active"`** — issue session/JWT + refresh token as
+     normal. If email ∈ `SUPER_ADMIN_EMAILS` and the stored role isn't
+     `super_admin` yet, elevate it on this login too — the allowlist is
+     always the source of truth for who is a super admin, even for rows
+     created before an email was added to it.
+   - **Found, `status: "pending"`** — respond `202` again, same as a brand
+     new pending user. No session.
+   - **Found, `status: "rejected"`** — `403`. A rejected user is not
+     silently re-queued by logging in again.
+4. A `super_admin` calls `GET /api/users?status=pending` to see the queue,
+   and `POST /api/users/:id/approve` or `POST /api/users/:id/reject` to
+   resolve one. Approve flips `status` to `active` (the user's *next* SSO
+   login then issues a session); reject flips it to `rejected`. Both routes
+   sit behind `auth("user:approve")`, restricted to `super_admin`, and both
+   write to the audit trail (actor, the user approved/rejected, before/after
+   status) — this is a mutation like any other, law 5 applies.
+
+### 12.3 What this buys, and what it deliberately doesn't
+
+This is a gate, not a role system — every approved user is a plain member
+until something else grants them more. Fine-grained permissions beyond
+"super admin vs. everyone else" are a separate module's concern (or a later
+addendum to this one), not something to bolt onto `auth` because it's
+already open.
+
+---
+
+## 13. Building it for a new app
 
 1. Scaffold the tree in §1 exactly. Nothing above `modules/*` beyond what's
    listed.

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

@@ -1,16 +1,46 @@
 ---
 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.
+description: Design and build screens from this repo's design-system spec(s) — Indira Workspace UI (light, the default) and, where the repo has it, Vault UI (dark, for custody/treasury/compliance-grade data) — asking which composition to use when more than one is available. 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 chosen spec. Use for any new page, dashboard, form, list, or internal tool; migrating an existing screen's UI to this design language; or the frontend half of a new full-stack app (pair with /indira-api for the backend).
 ---
 
 # 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.
+You are a senior product designer who builds. A repo can define more than
+one design composition — which one you build in is decided in Part 0, below.
+Whichever one is chosen, read its spec file completely before doing anything
+else; every number and rule you need is in that one file, and this skill
+does not repeat them.
+
+Your job has four parts, in order, and you do not skip Part 0 or Part 1.
+
+## Part 0 — Pick the design composition
+
+Check the target repo for `docs/design-system*.md`.
+
+- **Exactly one file** — that is the composition. Read it completely and go
+  to Part 1; don't make the developer confirm a choice they don't have.
+- **More than one file** — read enough of each (title + opening paragraph)
+  to describe it in a sentence, then ask the developer which this screen
+  should use before doing anything else. As of this writing, a repo may
+  offer:
+  - **Indira Workspace UI** (`docs/design-system.md`) — light, one rose
+    accent, soft rounded shapes. The default: governance/workflow tools,
+    anything that should look like the BRD Governance Tool.
+  - **Vault UI** (`docs/design-system-vault.md`) — dark by default, one
+    desaturated accent, dense tabular layout. Custody/treasury/compliance-
+    grade screens where the data itself carries the seriousness and a
+    light, friendly surface would undersell that.
+
+  List whatever compositions the repo actually has, not just these two —
+  more may exist by the time you read this. Wait for an explicit answer.
+  If the developer has no preference, recommend Indira Workspace UI and say
+  why (it's this product's established look); switch only on request.
+- **No file** — fresh project. Fall back to building Indira Workspace UI
+  from this skill's own copy of the spec (§7), same as if this part didn't
+  exist.
+
+Never mix components from two compositions on one screen — each spec's own
+closing section says so, and it's as true across systems as within one.
 
 ## Part 1 — Grill before you draw
 
@@ -20,6 +50,29 @@ 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.
 
+**Migrating an existing screen, not building a new one?** Same three parts,
+but the brief opens differently — add these before "Who":
+
+- **What's there today** — describe or screenshot the current screen. What
+  do people actually use vs. ignore? (Ask directly — the ignored parts are
+  what you leave out, exactly as with a fresh build.)
+- **What must not change** — which behaviours, data, or integrations are
+  load-bearing and must survive untouched? A migration rebuilds the visual
+  and structural layer; it is not licence to rewrite what the screen does.
+- **What's the current stack** — plain CSS, Bootstrap, MUI, styled-
+  components? None of its styling survives the swap; what you're checking
+  for is which existing data-fetching/behaviour logic can stay as-is
+  underneath the new markup.
+
+Migrate one screen at a time. "Migrate the whole app" is always several
+screens — say so, and ask which one first. An old screen and a newly
+migrated one looking different in the same nav is normal mid-migration, not
+a bug to fix immediately.
+
+**Building a brand-new full-stack app?** If there's no backend yet, run
+`/indira-api` first (it scaffolds `auth` and `audit` before any domain
+module) — this skill designs screens, it doesn't invent the data they show.
+
 **Who**
 - Who opens this screen, by role? How often — several times a day, once a
   week, once a quarter?
@@ -130,20 +183,25 @@ Build from the spec, not from memory of other design systems.
 
 ## 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.
+Give back, in this order: which design composition was used (and, if more
+than one was on offer, that the developer chose it), 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
 
+- Assume the design composition when the repo defines more than one — Part
+  0 is not optional just because you're confident which one fits.
 - 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.
+- Invent a colour for a new status beyond what the chosen composition's own
+  spec defines — a new one is a product decision, not a per-screen one.
 - Use a spinner for page content, or animate anything on a loop.
 - Design a screen for a user you have not asked about.
+- Reach for a second composition's component inside a screen built in the
+  first one.

package/README.md

@@ -4,6 +4,15 @@ The component library specified in [docs/design-system.md](docs/design-system.md
 React 19 + Tailwind CSS 4 + Lucide. Published to npm as `indira-workspace-ui`, and it doubles
 as an installer for the `indira-ui` and `indira-api` Claude Code skills.
 
+This repo also holds a second, deliberately separate composition — **Vault UI**
+([docs/design-system-vault.md](docs/design-system-vault.md), components in
+[src/vault/](src/vault/)) — dark, one accent, dense tabular layout, for
+custody/treasury/compliance-grade screens where a light, friendly surface
+would undersell the data. See it live at the "Vault UI" nav item in the demo
+workspace. The `/indira-ui` skill now asks which composition to use before
+building a screen whenever a repo has more than one. Vault UI is not part of
+the published npm package yet — it's source-only in this repo for now.
+
 ## Install in a consuming project
 
 ```
@@ -55,6 +64,7 @@ npm run build:lib # builds the publishable package into dist-lib/
 | `src/components/` | One file per component; `index.js` is the barrel and the library's entry point. |
 | `src/screens/` | The demo workspace: Dashboard, BRD list, BRD detail, a library gallery per component group, and the dev-skills docs screen. |
 | `src/data/` | Demo directory and BRD records (demo app only — not part of the published package). |
+| `src/vault/` | Vault UI — the second design composition. Its own tokens/components, scoped under `.vault`, never mixed with `src/components/`. |
 | `.claude/skills/indira-ui`, `.claude/skills/indira-api` | The two Claude Code skills this package installs into consumer projects. |
 | `bin/cli.js` | The `indira-workspace-ui add-skills` CLI. |
 | `vite.lib.config.js` | Library build config — components only, externalizes `react`/`react-dom`/`lucide-react`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indira-workspace-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Indira Workspace UI — the component library specified in docs/design-system.md, plus a CLI to install the indira-ui and indira-api Claude Code skills",