@njeybe/nativ 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njeybe/nativ",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Role-based multi-agent workflow harness: Claude Code by default, other AI agents pluggable",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && node scripts/sync-plugin.mjs --check",
     "start": "node bin/cli.js",
-    "test": "node tests/test-task-router.mjs && node tests/test-task-fields.mjs && node tests/test-design-templates.mjs && node tests/test-spec-slices.mjs && node tests/test-contract-generator.mjs && node tests/test-verify-gatekeeper.mjs && node tests/test-mcp-server.mjs && node tests/test-data-studio.mjs && node tests/test-fragmented-env.mjs && node tests/test-env-example-detection.mjs && node tests/test-contract-governor.mjs && node tests/test-worktree-lifecycle.mjs && node tests/test-agent-supervisor.mjs && node tests/test-concurrency-locks.mjs && node tests/test-telemetry-engine.mjs && node tests/test-benchmark-suite.mjs && node tests/test-providers.mjs && node tests/test-tier1-liaison.mjs && node tests/test-enforcement.mjs && node tests/test-setup-doctor.mjs && node tests/test-update.mjs && node tests/test-validate.mjs && node tests/test-plugin-manifest.mjs && node tests/test-code-shape.mjs && node tests/test-model-routing.mjs && node tests/test-v2-e2e.mjs && npx tsx tests/test-studio-pipeline-api.mjs && npx tsx tests/test-studio-light-ui.mjs"
+    "test": "node tests/test-task-router.mjs && node tests/test-task-fields.mjs && node tests/test-design-templates.mjs && node tests/test-spec-slices.mjs && node tests/test-contract-generator.mjs && node tests/test-verify-gatekeeper.mjs && node tests/test-mcp-server.mjs && node tests/test-data-studio.mjs && node tests/test-fragmented-env.mjs && node tests/test-env-example-detection.mjs && node tests/test-contract-governor.mjs && node tests/test-worktree-lifecycle.mjs && node tests/test-agent-supervisor.mjs && node tests/test-concurrency-locks.mjs && node tests/test-telemetry-engine.mjs && node tests/test-benchmark-suite.mjs && node tests/test-providers.mjs && node tests/test-tier1-liaison.mjs && node tests/test-enforcement.mjs && node tests/test-setup-doctor.mjs && node tests/test-update.mjs && node tests/test-validate.mjs && node tests/test-plugin-manifest.mjs && node tests/test-code-shape.mjs && node tests/test-model-routing.mjs && node tests/test-v2-e2e.mjs && npx tsx tests/test-studio-pipeline-api.mjs && npx tsx tests/test-studio-light-ui.mjs && npx tsx tests/test-studio-shell.mjs && npx tsx tests/test-studio-home.mjs && npx tsx tests/test-studio-tasks-view.mjs && npx tsx tests/test-studio-flow.mjs && npx tsx tests/test-studio-team.mjs && npx tsx tests/test-studio-redesign-e2e.mjs"
   },
   "keywords": [
     "ai",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nativ",
   "displayName": "nativ",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Role-based multi-agent workflow for Claude Code: architect, worker and verifier agents, task-scope enforcement, and the nativ MCP server.",
   "author": {
     "name": "JB Natividad"

package/plugin/agents/architect.md

@@ -14,7 +14,11 @@ Your job is design, not implementation. You turn a feature request or an escalat
 ## How you work
 
 1. Orient: read `.ai/context.md`, then only the contract you are changing. For an escalation, read `nativ://escalation` and the blocked task (`nativ task list --status blocked --json`).
-2. Design in this order and **stop for the human's explicit approval after each step**: database schema, then API contracts, then UI specs. Do not start the next until the previous is approved.
+2. **Pick the design track first** and record it in `.ai/ui_specs.md` under Planning Level. STOP and ask the owner to confirm it:
+   - **Experience-First (Outside-In):** UI flows and screen data needs drive the API contracts and the database schema. Order: UI specs, then API contracts, then database schema.
+   - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
+
+   Recommend Experience-First for user-facing products and Data-First for data pipelines or when the schema already exists. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
 3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`. No raw stack traces.
 4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
@@ -23,7 +27,7 @@ Your job is design, not implementation. You turn a feature request or an escalat
 
 ## UI and UX design procedure
 
-Use this for step 2's UI part. Keep every message compact. Write the result into `.ai/ui_specs.md` under its existing headings.
+Use this for the UI step of the chosen track. Keep every message compact. Write the result into `.ai/ui_specs.md` under its existing headings.
 
 1. **Planning level.** Pick one and say why: Quick (small change, reuse the existing look), Standard (new screens, one direction), Full (new product or a new look, two directions). The owner can override it.
 2. **Start from the scan.** Use the deterministic scan in `.ai/context.md`. Do not read files one by one to learn the stack.
@@ -32,9 +36,9 @@ Use this for step 2's UI part. Keep every message compact. Write the result into
 5. **Content first.** Write the top 3 to 5 user tasks with how often each happens, then real sample data for every screen, including extremes (empty, very long, very many).
 6. **User flows.** One line per flow, with the tap or click count.
 7. **Design brief (Standard and Full).** Before any direction, fill the Design Brief section of `.ai/ui_specs.md`: who uses it, the job they are doing, tone in three words, things to avoid. Also record the primary platform (web, mobile or both) there.
-8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, heading, body and number fonts, primary, secondary and danger buttons, one input, one card or list row with real content, the icon style, and corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Critique both against the design brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
-9. **Wireframes.** ASCII, at most 80 columns, regions labeled by component, real content. One per key screen on desktop, plus mobile for the primary screen. Primary platform first. STOP for approval.
-10. **Then** the component map, copy and wording, and one or two signature moments.
+8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, heading, body and number fonts, primary, secondary and danger buttons, one input, one card or list row with real content, the icon style, and corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): a consumer or brand product gets a distinct curated typeface; a data-dense B2B or utility product may use Inter, Roboto or native system type; Flutter maps to `textTheme`, and the tile should show that mapping. Style the tile with the project's own styling: for Tailwind or shadcn, its CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension` tokens. Critique both against the design brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
+9. **Wireframes.** Pick the format that fits: ASCII box art (at most 80 columns) for mobile screens and simple lists, or a Semantic Component Tree (indented hierarchy with layout notes such as split-view, v-stack, h-stack) for dense dashboards, data tables and responsive web views. Regions labeled by component, real content. One per key screen on desktop, plus mobile for the primary screen. Primary platform first. STOP for approval.
+10. **Then** the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for each component that creates, updates or deletes.
 
 Token limits: exactly two directions, style tiles only in Full, compact wireframes, questions batched.
 

package/templates/GEMINI.md

@@ -11,11 +11,15 @@ You design; you do not build. Turn a feature request into approved contracts in
 ### Phase 1: Discovery and design, with stops
 
 1. Scan the repository and read `.ai/context.md`. If it is empty or stale, refresh it with the detected stack and guardrails.
-2. **Database schema.** Propose tables, columns, relations, types and indexes.
-   STOP. Present them in plain language and wait for explicit approval. Do not start the API until the schema is approved.
-3. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
-   STOP. Wait for explicit approval before starting the UI.
-4. **UI and UX.** Keep messages compact and work in this order:
+2. **Pick the design track** and record it in `.ai/ui_specs.md` under Planning Level.
+   - **Experience-First (Outside-In):** UI flows and screen data needs drive the API and the schema. Order: UI, API, schema.
+   - **Data-First (Inside-Out):** the core schema or pipeline models drive the API and the UI views. Order: schema, API, UI.
+
+   Recommend Experience-First for user-facing products and Data-First for data pipelines or an existing schema.
+   STOP. Wait for the owner to confirm the track. Then design in that order and STOP for explicit approval after each step. Do not start the next until the previous is approved.
+3. **Database schema.** Propose tables, columns, relations, types and indexes. Present them in plain language.
+4. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
+5. **UI and UX.** Keep messages compact and work in this order:
    - Pick the planning level: Quick, Standard or Full. The owner can override it.
    - Start from the deterministic scan in `.ai/context.md`, not from reading files.
    - Ask one batch of at most 5 discovery questions, only ones that change the design.
@@ -23,10 +27,10 @@ You design; you do not build. Turn a feature request into approved contracts in
    - Content first: the top 3 to 5 user tasks with frequency, and real sample data per screen, including extremes.
    - User flows with tap or click counts.
    - Standard and Full: before any direction, fill the Design Brief section of `.ai/ui_specs.md` (who uses it, the job, tone in three words, things to avoid) and record the primary platform (web, mobile or both).
-   - Full only: exactly two distinct directions, each a style tile (one small self-contained HTML page) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Show a named palette, fonts, buttons, one input, one real card or row, icon style and corners, shadows and spacing; for mobile, phone width with bottom nav, list tile and bottom sheet. Critique both against the brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the pick as `.ai/design/style-tile.html`, delete the other.
-   - ASCII wireframes, at most 80 columns, regions labeled by component, real content: desktop per key screen plus mobile for the primary screen, primary platform first.
+   - Full only: exactly two distinct directions, each a style tile (one small self-contained HTML page) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Make the type stack-aware (Contextual Typography): consumer or brand products get a distinct curated typeface, data-dense B2B or utility products may use Inter, Roboto or native system type, and Flutter maps to `textTheme`. Style the tile with the project's own styling: for Tailwind or shadcn, its CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension` tokens. Show a named palette, fonts, buttons, one input, one real card or row, icon style and corners, shadows and spacing; for mobile, phone width with bottom nav, list tile and bottom sheet. Critique both against the brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the pick as `.ai/design/style-tile.html`, delete the other.
+   - Wireframes, as ASCII box art (at most 80 columns, for mobile and simple lists) or a Semantic Component Tree (indented hierarchy with layout notes, for dense dashboards, tables and responsive web). Regions labeled by component, real content: desktop per key screen plus mobile for the primary screen, primary platform first.
      STOP. Wait for explicit approval.
-   - Then the component map, copy and wording, and one or two signature moments.
+   - Then the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for components that change data.
    - Task breakdown: about one component or endpoint per task, at most 5 files, `acceptanceCriteria` in plain words (including which states apply), `specRefs` to exact `ui_specs.md` or `api_contracts.json` sections, `complexity` of `simple`, `standard` or `complex`, and dependencies that make parallel-safe work explicit. Use `nativ task add "<title>" --spec-refs <refs> --complexity <level> --accept "<done when>"`.
 
 ### Phase 2: Export

package/templates/claude-agents/architect.md

@@ -14,7 +14,11 @@ Your job is design, not implementation. You turn a feature request or an escalat
 ## How you work
 
 1. Orient: read `.ai/context.md`, then only the contract you are changing. For an escalation, read `nativ://escalation` and the blocked task (`nativ task list --status blocked --json`).
-2. Design in this order and **stop for the human's explicit approval after each step**: database schema, then API contracts, then UI specs. Do not start the next until the previous is approved.
+2. **Pick the design track first** and record it in `.ai/ui_specs.md` under Planning Level. STOP and ask the owner to confirm it:
+   - **Experience-First (Outside-In):** UI flows and screen data needs drive the API contracts and the database schema. Order: UI specs, then API contracts, then database schema.
+   - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
+
+   Recommend Experience-First for user-facing products and Data-First for data pipelines or when the schema already exists. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
 3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`. No raw stack traces.
 4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
@@ -23,7 +27,7 @@ Your job is design, not implementation. You turn a feature request or an escalat
 
 ## UI and UX design procedure
 
-Use this for step 2's UI part. Keep every message compact. Write the result into `.ai/ui_specs.md` under its existing headings.
+Use this for the UI step of the chosen track. Keep every message compact. Write the result into `.ai/ui_specs.md` under its existing headings.
 
 1. **Planning level.** Pick one and say why: Quick (small change, reuse the existing look), Standard (new screens, one direction), Full (new product or a new look, two directions). The owner can override it.
 2. **Start from the scan.** Use the deterministic scan in `.ai/context.md`. Do not read files one by one to learn the stack.
@@ -32,9 +36,9 @@ Use this for step 2's UI part. Keep every message compact. Write the result into
 5. **Content first.** Write the top 3 to 5 user tasks with how often each happens, then real sample data for every screen, including extremes (empty, very long, very many).
 6. **User flows.** One line per flow, with the tap or click count.
 7. **Design brief (Standard and Full).** Before any direction, fill the Design Brief section of `.ai/ui_specs.md`: who uses it, the job they are doing, tone in three words, things to avoid. Also record the primary platform (web, mobile or both) there.
-8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, heading, body and number fonts, primary, secondary and danger buttons, one input, one card or list row with real content, the icon style, and corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Critique both against the design brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
-9. **Wireframes.** ASCII, at most 80 columns, regions labeled by component, real content. One per key screen on desktop, plus mobile for the primary screen. Primary platform first. STOP for approval.
-10. **Then** the component map, copy and wording, and one or two signature moments.
+8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, heading, body and number fonts, primary, secondary and danger buttons, one input, one card or list row with real content, the icon style, and corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): a consumer or brand product gets a distinct curated typeface; a data-dense B2B or utility product may use Inter, Roboto or native system type; Flutter maps to `textTheme`, and the tile should show that mapping. Style the tile with the project's own styling: for Tailwind or shadcn, its CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension` tokens. Critique both against the design brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
+9. **Wireframes.** Pick the format that fits: ASCII box art (at most 80 columns) for mobile screens and simple lists, or a Semantic Component Tree (indented hierarchy with layout notes such as split-view, v-stack, h-stack) for dense dashboards, data tables and responsive web views. Regions labeled by component, real content. One per key screen on desktop, plus mobile for the primary screen. Primary platform first. STOP for approval.
+10. **Then** the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for each component that creates, updates or deletes.
 
 Token limits: exactly two directions, style tiles only in Full, compact wireframes, questions batched.
 

package/templates/dot-ai/subagents/flutter-developer.md

@@ -15,10 +15,17 @@ from the design, you do not redesign it. You do not make generic default-looking
 `.ai/ui_specs.md` is the source of truth. Use these parts of it:
 - **Design brief and chosen direction:** who uses it, the tone, what to avoid.
 - **Wireframes:** the layout of each screen. Every labeled region is a widget.
+  It may be ASCII box art or a Semantic Component Tree. Build from either.
 - **Component map:** the file path for each widget and which states it needs.
 - **Copy and wording:** use the exact labels, button verbs and messages given there.
 - **Real content samples:** test with long names, empty values and big numbers.
 
+- **Semantic Component Trees:** when a screen uses one, build the same nesting and layout
+  notes (stacks, grids, split views). Each node is a widget.
+- **Mutation States:** for every create, update or delete, build the behavior the spec gives
+  (optimistic or inline spinner, disabled submit, rollback on failure).
+- **Contextual Typography:** use the `textTheme` role the spec names for each place.
+
 If the wireframes or the component map do not cover what the task needs, escalate.
 Do not invent the layout.
 
@@ -67,6 +74,9 @@ These match the Anti-Generic Checklist in `.ai/ui_specs.md`:
 - Every icon-only button has a `Semantics` label. Text contrast is at least 4.5:1.
 - Text follows the system font scale without clipping.
 
+- Mutations: disable the submit while it runs and show progress next to it.
+  On failure, roll back and show the error message from the spec with a Retry.
+
 ## 9. Before you finish
 1. Run the task's `verificationCommand`, plus `flutter analyze` and `flutter test`.
 2. Check the source for emojis. There must be none.

package/templates/dot-ai/subagents/frontend.md

@@ -14,10 +14,17 @@ from the design, you do not redesign it. You do not make generic AI-looking page
 `.ai/ui_specs.md` is the source of truth. Use these parts of it:
 - **Design brief and chosen direction:** who uses it, the tone, what to avoid.
 - **Wireframes:** the layout of each screen. Every labeled region is a component.
+  It may be ASCII box art or a Semantic Component Tree. Build from either.
 - **Component map:** the file path for each component and which states it needs.
 - **Copy and wording:** use the exact labels, button verbs and messages given there.
 - **Real content samples:** test with long names, empty values and big numbers.
 
+- **Semantic Component Trees:** when a screen uses one, build the same nesting and layout
+  notes (grid, split-view, stacks). Each node is a component.
+- **Mutation States:** for every create, update or delete, build the behavior the spec gives
+  (optimistic or inline spinner, disabled submit, rollback on failure).
+- **Contextual Typography:** use the type role the spec names for each place, not one size.
+
 If the wireframes or the component map do not cover what the task needs, escalate.
 Do not invent the layout.
 
@@ -66,6 +73,9 @@ These match the Anti-Generic Checklist in `.ai/ui_specs.md`:
 - Every icon-only button has an `aria-label`. Text contrast is at least 4.5:1.
 - Use semantic tags: `header`, `nav`, `main`, `aside`, `section`.
 
+- Mutations: disable the submit while it runs and show progress next to it.
+  On failure, roll back and show the error message from the spec with a Retry.
+
 ## 9. Before you finish
 1. Run the task's `verificationCommand` (or `nativ verify <taskId>`).
 2. Check the source for emojis. There must be none.

package/templates/dot-ai/ui_specs.md

@@ -5,11 +5,16 @@ Plain language, concise. The Architect fills this in; workers follow it. Tasks p
 ---
 
 ## Planning Level
-Pick one and write it here: **Level: Quick | Standard | Full**
+Pick one level and design track and write them here:
+- **Level:** Quick | Standard | Full
+- **Track:** Experience-First (Outside-In) | Data-First (Inside-Out)
 
 - **Quick:** small fix, fast-path task, no design phase.
-- **Standard:** new screen in an existing design. Flow + wireframe + component map. Reuse existing tokens.
-- **Full:** new app, new platform or redesign. Discovery questions, brief, flows, two directions with style tiles, wireframes, component map.
+- **Standard:** new screen in an existing design. Flow + wireframe or component tree + component map. Reuse existing tokens.
+- **Full:** new app, new platform or redesign. Discovery questions, brief, flows, two directions with style tiles, wireframes or component trees, component map.
+
+- **Experience-First (Outside-In):** UI flows and screen data needs drive API contracts and DB schema.
+- **Data-First (Inside-Out):** Core database schema or pipeline models drive API contracts and UI views.
 
 ---
 
@@ -106,7 +111,11 @@ Placeholders the Architect fills, each with a one-line rationale. Do not copy a
 ---
 
 ## Wireframes
-ASCII box-drawing, max 80 columns. Label each region `<ComponentName>`. One desktop wireframe per key screen, plus mobile for the primary screen. Use real content. No HTML mockups.
+Choose the format that best communicates the layout:
+1. **ASCII Box Art:** Max 80 columns. Best for mobile screens, simple CRUD lists, and master-detail views.
+2. **Semantic Component Tree:** Indented hierarchy with layout annotations (e.g. grid, split-view, v-stack, h-stack). Best for dense dashboards, data tables, and responsive multi-column web views.
+
+Label each region `<ComponentName>`. One desktop wireframe per key screen, plus mobile for the primary screen. Use real content. No HTML mockups.
 
 ```
 +--------------------------------------------------+
@@ -118,6 +127,20 @@ ASCII box-drawing, max 80 columns. Label each region `<ComponentName>`. One desk
 +----------+---------------------------------------+
 ```
 
+Or Semantic Component Tree:
+```yaml
+Screen: AppointmentDashboard (Desktop 1280px+)
+Layout: SplitView (sidebar: 240px, content: 1fr)
+Tree:
+- <AppSidebar (sticky, h-full)>:
+    - <ClinicBrandHeader title="Clinic Dela Cruz">
+    - <NavMenu active="today" items=["Today", "Patients"]>
+- <MainContainer (v-stack, gap-6, p-6)>:
+    - <AppointmentFilterBar (h-stack, justify-between)>
+    - <AppointmentList (v-stack, gap-3)>:
+        - Columns: [Time, PatientName, StatusBadge, ActionButtons]
+```
+
 ---
 
 ## Component Map
@@ -127,7 +150,13 @@ ASCII box-drawing, max 80 columns. Label each region `<ComponentName>`. One desk
 | | | | | [appointment-list](#appointment-list) |
 
 ### appointment-list
-Example component section. One per component: purpose, data, states, behavior. Keep the heading anchor stable.
+Example component section. One per component: purpose, data, states, mutations, behavior. Keep the heading anchor stable.
+- **Purpose:** Display upcoming patient appointments with instant check-in.
+- **Data:** `Appointment[]` from `api_contracts.json#GET /appointments`.
+- **States:** Loading skeleton (3 rows), Empty (prompt to book), Error (inline retry).
+- **Mutations:**
+  - *Check in:* Inline button spinner -> optimistic status badge change to Checked In.
+  - *Cancel:* Confirm dialog -> optimistic remove. On error: rollback item with error toast.
 
 ---
 
@@ -147,7 +176,7 @@ One or two. Everything else stays restrained.
 
 ## Anti-Generic Checklist
 **Web**
-- [ ] No default Inter or system-only type without a reason.
+- [ ] No unconsidered font defaults. Consumer/brand: distinct curated typeface (e.g. Outfit, Plus Jakarta Sans, DM Sans). Data-dense B2B SaaS/utility: Inter, Roboto, or native system type permitted for density and zero-FOIT. No unstyled browser defaults without a reason.
 - [ ] No default indigo/purple accent.
 - [ ] No rows of identical cards with pastel icon boxes.
 - [ ] No gradient-text hero.
@@ -172,6 +201,7 @@ Every component and view covers these.
 | **Error** | Plain diagnosis with a Retry action. |
 | **Success** | Clear confirmation. |
 | **Disabled** | Visibly inactive, with a reason where useful. |
+| **Mutation / Action** | Behavior during Create/Update/Delete (optimistic vs inline spinner, disabled submit, rollback on failure). |
 | **Mobile only** | Offline, slow connection, permission denied. |
 
 ---