@alfadocs/ui-kit 0.69.0 → 0.71.0

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "0.69.0",
+  "packageVersion": "0.71.0",
   "components": [
     {
       "kind": "component",
@@ -204,6 +204,114 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "address-fields",
+      "capabilities": [
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "object",
+          "description": "The current structured address: { street, city, postcode, province, country, formatted }.",
+          "descriptionKey": "ui.agent.addressFields.state.value"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: StructuredAddress }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "object",
+                "properties": {
+                  "street": {
+                    "type": "string"
+                  },
+                  "city": {
+                    "type": "string"
+                  },
+                  "postcode": {
+                    "type": "string"
+                  },
+                  "province": {
+                    "type": "string",
+                    "description": "UPPERCASED province code."
+                  },
+                  "country": {
+                    "type": "string",
+                    "description": "ISO alpha-2, lowercased."
+                  },
+                  "formatted": {
+                    "type": "string"
+                  }
+                }
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "description": "Replace the entire address.",
+          "descriptionKey": "ui.agent.addressFields.actions.setValue"
+        },
+        {
+          "name": "set_field",
+          "safety": "write",
+          "argsType": "{ field: 'street' | 'city' | 'postcode' | 'province' | 'country'; value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "field": {
+                "type": "string",
+                "enum": [
+                  "street",
+                  "city",
+                  "postcode",
+                  "province",
+                  "country"
+                ]
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "field",
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "field": "country",
+                "value": "it"
+              },
+              "note": "Set the country to Italy."
+            }
+          ],
+          "description": "Set a single address field. Setting `country` also clears the now-stale province.",
+          "descriptionKey": "ui.agent.addressFields.actions.setField"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "address-fields"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "agenda-card",
@@ -408,162 +516,372 @@
     },
     {
       "kind": "component",
-      "id": "ai-tools-rail",
+      "id": "alert",
       "capabilities": [
-        "open",
-        "close",
-        "select_single"
+        "dismiss"
+      ],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "alert",
+          "description": "Marks the element as a kit Alert. The root also emits `data-state=\"open\" | \"closing\"` while the dismiss animation runs. Alerts inherit native `id` from props, which is what agents address them by."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "anamnesis-card",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "anamnesis-card",
+          "description": "Marks the element as a kit AnamnesisCard. The root also emits data-has-flags when at least one answer is a clinical red-flag — a structural boolean only, never the underlying answer."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop — the stable questionnaire identifier."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "anatomy-scheme",
+      "capabilities": [
+        "pick",
+        "set_value",
+        "edit_inline",
+        "view_change"
       ],
       "state": [
         {
-          "name": "activeToolId",
-          "type": "string | null",
-          "description": "Id of the tool whose panel is currently open, or null when the rail is collapsed to its strip. No panel content is ever exposed.",
-          "descriptionKey": "ui.aiToolsRail.agent.state.activeToolId"
+          "name": "chart",
+          "type": "object",
+          "description": "Current anatomy chart — findings keyed by region id. Notes are PHI and omitted from this snapshot; read them per-region via get_region.",
+          "descriptionKey": "ui.agent.anatomyScheme.state.chart"
+        },
+        {
+          "name": "activeView",
+          "type": "string",
+          "description": "Id of the currently displayed anatomy view.",
+          "descriptionKey": "ui.agent.anatomyScheme.state.activeView"
         }
       ],
       "actions": [
         {
-          "name": "open",
+          "name": "focus_region",
           "safety": "read",
-          "argsType": "{ id: string }",
+          "argsType": "{ regionId: string }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "id": {
-                "type": "string"
+              "regionId": {
+                "type": "string",
+                "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
               }
             },
             "required": [
-              "id"
+              "regionId"
             ]
           },
           "idempotent": true,
-          "examples": [
-            {
-              "args": {
-                "id": "inbox"
+          "description": "Move focus to a specific region in the active view.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.focusRegion"
+        },
+        {
+          "name": "get_region",
+          "safety": "phi",
+          "argsType": "{ regionId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "regionId": {
+                "type": "string",
+                "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
+              }
+            },
+            "required": [
+              "regionId"
+            ]
+          },
+          "returns": "AnatomyFinding[]",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "enum": [
+                    "observation",
+                    "lesion",
+                    "pain",
+                    "treatment",
+                    "note"
+                  ]
+                },
+                "note": {
+                  "type": "string"
+                }
               },
-              "note": "Open the inbox tool panel."
+              "required": [
+                "type"
+              ]
             }
-          ],
-          "description": "Open the given tool's panel.",
-          "descriptionKey": "ui.aiToolsRail.agent.actions.open"
+          },
+          "idempotent": true,
+          "description": "Read the findings (incl. notes) recorded on one region.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.getRegion"
         },
         {
-          "name": "close",
+          "name": "regions_with",
           "safety": "read",
+          "argsType": "{ type: FindingType }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "enum": [
+                  "observation",
+                  "lesion",
+                  "pain",
+                  "treatment",
+                  "note"
+                ]
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "returns": "string[]",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
+            }
+          },
           "idempotent": true,
-          "description": "Collapse the rail to its strip (no active tool).",
-          "descriptionKey": "ui.aiToolsRail.agent.actions.close"
+          "description": "List the region ids carrying a given finding type.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.regionsWith"
         },
         {
-          "name": "select_tool",
-          "safety": "read",
-          "argsType": "{ id: string | null }",
+          "name": "set_finding",
+          "safety": "write",
+          "argsType": "{ regionId: string; type: FindingType; note?: string }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "id": {
-                "type": [
-                  "string",
-                  "null"
+              "regionId": {
+                "type": "string",
+                "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
+              },
+              "type": {
+                "enum": [
+                  "observation",
+                  "lesion",
+                  "pain",
+                  "treatment",
+                  "note"
                 ]
+              },
+              "note": {
+                "type": "string"
               }
             },
             "required": [
-              "id"
+              "regionId",
+              "type"
             ]
           },
           "idempotent": true,
-          "description": "Set the active tool by id (opens its panel), or pass null to collapse.",
-          "descriptionKey": "ui.aiToolsRail.agent.actions.selectTool"
+          "description": "Record a finding (observation / lesion / pain / treatment / note) on a region.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.setFinding"
+        },
+        {
+          "name": "remove_finding",
+          "safety": "write",
+          "argsType": "{ regionId: string; type: FindingType }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "regionId": {
+                "type": "string",
+                "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
+              },
+              "type": {
+                "enum": [
+                  "observation",
+                  "lesion",
+                  "pain",
+                  "treatment",
+                  "note"
+                ]
+              }
+            },
+            "required": [
+              "regionId",
+              "type"
+            ]
+          },
+          "idempotent": true,
+          "description": "Remove a single finding type from a region.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.removeFinding"
+        },
+        {
+          "name": "clear_region",
+          "safety": "destructive",
+          "argsType": "{ regionId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "regionId": {
+                "type": "string",
+                "description": "Region id within the active view, e.g. 'ovary-l', 'prostate', 'quadriceps-r', 'kidney-r'."
+              }
+            },
+            "required": [
+              "regionId"
+            ]
+          },
+          "idempotent": true,
+          "description": "Clear every finding from a region.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.clearRegion"
+        },
+        {
+          "name": "set_view",
+          "safety": "write",
+          "argsType": "{ viewId: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "viewId": {
+                "type": "string",
+                "description": "View id, e.g. 'body-front', 'face-front', 'female-reproductive', 'male-reproductive', 'urinary', 'muscular-front', 'skeletal-front'."
+              }
+            },
+            "required": [
+              "viewId"
+            ]
+          },
+          "idempotent": true,
+          "description": "Switch the active anatomy view.",
+          "descriptionKey": "ui.agent.anatomyScheme.actions.setView"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "ai-tools-rail",
-          "description": "Marks the AiToolsRail wrapper."
+          "value": "anatomy-scheme"
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop. Required to address a specific rail from the agent."
+          "description": "Sourced from the id prop."
         },
         "item": {
-          "attr": "data-tool-id",
-          "description": "Stable tool id emitted on each strip IconButton. The active icon also carries data-active set to its id."
+          "attr": "data-region",
+          "description": "Each rendered region `<g>` carries its region id as `data-region` and its anatomical side (`left` / `right` / `midline`) as `data-side`, so bilateral regions can be disambiguated by side. The root `data-system` / `data-view` attributes expose the active anatomy system and view."
         }
       }
     },
     {
       "kind": "component",
-      "id": "alert",
-      "capabilities": [
-        "dismiss"
-      ],
+      "id": "app-frame",
+      "capabilities": [],
       "state": [],
       "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "alert",
-          "description": "Marks the element as a kit Alert. The root also emits `data-state=\"open\" | \"closing\"` while the dismiss animation runs. Alerts inherit native `id` from props, which is what agents address them by."
+          "value": "app-frame",
+          "description": "Marks the AppFrame layout wrapper. Inner landmarks (Header, Sidebar, main) carry their own component hooks."
         }
       }
     },
     {
       "kind": "component",
-      "id": "anamnesis-card",
-      "capabilities": [],
+      "id": "appointment-card",
+      "capabilities": [
+        "pick"
+      ],
       "state": [],
       "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "anamnesis-card",
-          "description": "Marks the element as a kit AnamnesisCard. The root also emits data-has-flags when at least one answer is a clinical red-flag — a structural boolean only, never the underlying answer."
+          "value": "appointment-card",
+          "description": "Marks the element as a kit AppointmentCard. The root also emits data-component-id sourced from item.id, data-state with the appointment lifecycle, and data-type with the delivery channel."
         },
         "instanceId": {
           "attr": "data-component-id",
-          "sourceProp": "id",
-          "description": "Sourced from the id prop — the stable questionnaire identifier."
-        }
-      }
-    },
-    {
-      "kind": "component",
-      "id": "app-frame",
-      "capabilities": [],
-      "state": [],
-      "actions": [],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "value": "app-frame",
-          "description": "Marks the AppFrame layout wrapper. Inner landmarks (Header, Sidebar, main) carry their own component hooks."
+          "sourceProp": "item.id",
+          "description": "Sourced from item.id — the stable appointment identifier."
         }
       }
     },
     {
       "kind": "component",
-      "id": "appointment-card",
+      "id": "appointment-timeline",
       "capabilities": [
+        "scroll",
         "pick"
       ],
-      "state": [],
-      "actions": [],
+      "state": [
+        {
+          "name": "items",
+          "type": "Array<{ id: string; state: string }>",
+          "description": "Currently-rendered appointments. Ids + lifecycle state only — never patient identity.",
+          "descriptionKey": "ui.agent.appointmentTimeline.state.items"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_item",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Activate the appointment with the given id.",
+          "descriptionKey": "ui.agent.appointmentTimeline.actions.selectItem"
+        },
+        {
+          "name": "jump_to_today",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Re-anchor the timeline scroll on today's appointments.",
+          "descriptionKey": "ui.agent.appointmentTimeline.actions.jumpToToday"
+        }
+      ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "appointment-card",
-          "description": "Marks the element as a kit AppointmentCard. The root also emits data-component-id sourced from item.id, data-state with the appointment lifecycle, and data-type with the delivery channel."
+          "value": "appointment-timeline",
+          "description": "Marks the AppointmentTimeline wrapper."
         },
         "instanceId": {
           "attr": "data-component-id",
-          "sourceProp": "item.id",
-          "description": "Sourced from item.id — the stable appointment identifier."
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific timeline from the agent."
+        },
+        "item": {
+          "attr": "data-appointment-id",
+          "description": "Stable appointment id emitted on each rendered AppointmentCard inside the timeline."
         }
       }
     },
@@ -1565,6 +1883,38 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "care-plan-header",
+      "capabilities": [],
+      "state": [
+        {
+          "name": "state",
+          "type": "'estimate' | 'accepted' | 'discarded' | 'closed'",
+          "description": "The plan lifecycle state. Enum value only — never the localised label or any PHI.",
+          "descriptionKey": "ui.agent.carePlanHeader.state.state"
+        },
+        {
+          "name": "alertCount",
+          "type": "number",
+          "description": "How many attention alerts (e.g. missing signature) are showing. Count only — never the alert labels.",
+          "descriptionKey": "ui.agent.carePlanHeader.state.alertCount"
+        }
+      ],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "care-plan-header",
+          "description": "Marks the CarePlanHeader root region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Addresses a specific plan header."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "carousel",
@@ -1848,7 +2198,7 @@
         "root": {
           "attr": "data-component",
           "value": "chat-message",
-          "description": "Marks the ChatMessage article element. Agents address an individual message by its native `id` and read role / status from the DOM."
+          "description": "Marks the ChatMessage article element. Agents address an individual message by its native `id` and read role / status from the `data-role` and `data-status` attributes emitted on this element (`data-status` is omitted when the message has no status)."
         }
       }
     },
@@ -1945,26 +2295,94 @@
           "descriptionKey": "ui.agent.checkboxGroup.actions.setSelection"
         },
         {
-          "name": "clear_selection",
+          "name": "clear_selection",
+          "safety": "destructive",
+          "description": "Uncheck every option in the group.",
+          "descriptionKey": "ui.agent.checkboxGroup.actions.clearSelection"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "checkbox-group",
+          "description": "Marks the CheckboxGroup fieldset."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-option-id",
+          "description": "Stable opaque value emitted on each rendered Checkbox child within the group."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "city-input",
+      "capabilities": [
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Current city / town value.",
+          "descriptionKey": "ui.agent.cityInput.state.value"
+        },
+        {
+          "name": "isEmpty",
+          "type": "boolean",
+          "description": "Whether the field has no value.",
+          "descriptionKey": "ui.agent.cityInput.state.isEmpty"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "Milano"
+              },
+              "note": "Set the city to Milano."
+            }
+          ],
+          "description": "Replace the city value.",
+          "descriptionKey": "ui.agent.cityInput.actions.setValue"
+        },
+        {
+          "name": "clear",
           "safety": "destructive",
-          "description": "Uncheck every option in the group.",
-          "descriptionKey": "ui.agent.checkboxGroup.actions.clearSelection"
+          "idempotent": true,
+          "description": "Empty the field. Loses any typed value.",
+          "descriptionKey": "ui.agent.cityInput.actions.clear"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "checkbox-group",
-          "description": "Marks the CheckboxGroup fieldset."
+          "value": "city-input"
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
           "description": "Sourced from the id prop."
-        },
-        "item": {
-          "attr": "data-option-id",
-          "description": "Stable opaque value emitted on each rendered Checkbox child within the group."
         }
       }
     },
@@ -2312,6 +2730,50 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "connection-status",
+      "capabilities": [
+        "submit",
+        "dismiss"
+      ],
+      "state": [
+        {
+          "name": "status",
+          "type": "string",
+          "description": "Connection state of the external service: 'connected', 'disconnected', 'pending', or 'error'.",
+          "descriptionKey": "ui.agent.connectionStatus.state.status"
+        }
+      ],
+      "actions": [
+        {
+          "name": "connect",
+          "safety": "write",
+          "openWorld": true,
+          "description": "Begin connecting the external service — invokes the consumer-supplied onConnect handler.",
+          "descriptionKey": "ui.agent.connectionStatus.actions.connect"
+        },
+        {
+          "name": "disconnect",
+          "safety": "destructive",
+          "openWorld": true,
+          "description": "Disconnect the external service — invokes the consumer-supplied onDisconnect handler.",
+          "descriptionKey": "ui.agent.connectionStatus.actions.disconnect"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "connection-status",
+          "description": "Marks the ConnectionStatus wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "contact-card",
@@ -2352,6 +2814,97 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "control-room-rail",
+      "capabilities": [
+        "open",
+        "close",
+        "select_single"
+      ],
+      "state": [
+        {
+          "name": "activeToolId",
+          "type": "string | null",
+          "description": "Id of the tool whose panel is currently open, or null when the rail is collapsed to its strip. No panel content is ever exposed.",
+          "descriptionKey": "ui.toolRail.agent.state.activeToolId"
+        }
+      ],
+      "actions": [
+        {
+          "name": "open",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "inbox"
+              },
+              "note": "Open the inbox tool panel."
+            }
+          ],
+          "description": "Open the given tool's panel.",
+          "descriptionKey": "ui.toolRail.agent.actions.open"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Collapse the rail to its strip (no active tool).",
+          "descriptionKey": "ui.toolRail.agent.actions.close"
+        },
+        {
+          "name": "select_tool",
+          "safety": "read",
+          "argsType": "{ id: string | null }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set the active tool by id (opens its panel), or pass null to collapse.",
+          "descriptionKey": "ui.toolRail.agent.actions.selectTool"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "control-room-rail",
+          "description": "Marks the ControlRoomRail wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific rail from the agent."
+        },
+        "item": {
+          "attr": "data-tool-id",
+          "description": "Stable tool id emitted on each strip IconButton. The active icon also carries data-active set to its id."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "copy-field",
@@ -2413,6 +2966,77 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "country-select",
+      "capabilities": [
+        "select_single",
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string | null",
+          "description": "Selected ISO 3166-1 alpha-2 country code (lowercased), or null when nothing is selected.",
+          "descriptionKey": "ui.agent.countrySelect.state.value"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string | null }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "ISO 3166-1 alpha-2 country code (lowercased) to select, or null to clear."
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "it"
+              },
+              "note": "Select Italy."
+            }
+          ],
+          "description": "Set the selected country by ISO alpha-2 code.",
+          "descriptionKey": "ui.agent.countrySelect.actions.setValue"
+        },
+        {
+          "name": "clear_selection",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Clear the selected country.",
+          "descriptionKey": "ui.agent.countrySelect.actions.clearSelection"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "country-select"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-option-id",
+          "description": "Each country option emits its alpha-2 code as data-option-id."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "cycle-calculator",
@@ -3224,58 +3848,160 @@
           "descriptionKey": "ui.agent.emailInput.state.value"
         },
         {
-          "name": "isValid",
-          "type": "boolean",
-          "description": "True when the value is non-empty AND parses as a valid email per RFC 5322.",
-          "descriptionKey": "ui.agent.emailInput.state.isValid"
+          "name": "isValid",
+          "type": "boolean",
+          "description": "True when the value is non-empty AND parses as a valid email per RFC 5322.",
+          "descriptionKey": "ui.agent.emailInput.state.isValid"
+        }
+      ],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "email-input",
+          "description": "Marks the EmailInput wrapper. The inline error element carries `role=\"alert\"` when validation fails."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop, when provided."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "empty-state",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "empty-state",
+          "description": "Marks the EmptyState wrapper. CTAs inside are kit Buttons / Links and carry their own DOM hooks."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "entity-summary",
+      "capabilities": [
+        "close"
+      ],
+      "state": [
+        {
+          "name": "sections",
+          "type": "Array<{ id: string; heading: string; tone: \"default\" | \"attention\"; itemCount: number }>",
+          "description": "Structural section list — ids, fixed category headings, tone and item counts. Never the entity name or the bullet items (both PHI).",
+          "descriptionKey": "ui.agent.entitySummary.state.sections"
+        },
+        {
+          "name": "generatedAtIso",
+          "type": "string | undefined",
+          "description": "ISO-8601 instant the brief was generated, when known.",
+          "descriptionKey": "ui.agent.entitySummary.state.generatedAtIso"
+        }
+      ],
+      "actions": [
+        {
+          "name": "regenerate",
+          "safety": "write",
+          "openWorld": true,
+          "description": "Request the host to regenerate the AI brief. No-op when the regenerate affordance is not available.",
+          "descriptionKey": "ui.agent.entitySummary.actions.regenerate"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Dismiss the summary panel. No-op when the close affordance is not available (e.g. docked in the rail).",
+          "descriptionKey": "ui.agent.entitySummary.actions.close"
         }
       ],
-      "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "email-input",
-          "description": "Marks the EmailInput wrapper. The inline error element carries `role=\"alert\"` when validation fails."
+          "value": "entity-summary",
+          "description": "Marks the EntitySummary panel region."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop, when provided."
+          "description": "Sourced from the id prop. Required to address a specific summary panel from the agent."
         }
       }
     },
     {
       "kind": "component",
-      "id": "empty-state",
-      "capabilities": [],
+      "id": "fetal-weight",
+      "capabilities": [
+        "set_value"
+      ],
       "state": [],
       "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "empty-state",
-          "description": "Marks the EmptyState wrapper. CTAs inside are kit Buttons / Links and carry their own DOM hooks."
+          "value": "fetal-weight",
+          "description": "Marks the FetalWeight calculator (estimated fetal weight from ultrasound biometry)."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific calculator instance from the agent."
         }
       }
     },
     {
       "kind": "component",
-      "id": "fetal-weight",
+      "id": "field-array",
       "capabilities": [
-        "set_value"
+        "edit_inline"
+      ],
+      "state": [
+        {
+          "name": "count",
+          "type": "number",
+          "description": "Number of rows currently rendered.",
+          "descriptionKey": "ui.agent.fieldArray.state.count"
+        }
+      ],
+      "actions": [
+        {
+          "name": "add",
+          "safety": "write",
+          "description": "Append a new row.",
+          "descriptionKey": "ui.agent.fieldArray.actions.add"
+        },
+        {
+          "name": "remove",
+          "safety": "destructive",
+          "argsType": "{ index: number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "index": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "index"
+            ]
+          },
+          "description": "Remove the row at the given index.",
+          "descriptionKey": "ui.agent.fieldArray.actions.remove"
+        }
       ],
-      "state": [],
-      "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "fetal-weight",
-          "description": "Marks the FetalWeight calculator (estimated fetal weight from ultrasound biometry)."
+          "value": "field-array",
+          "description": "Marks the FieldArray fieldset."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop. Required to address a specific calculator instance from the agent."
+          "description": "Sourced from the id prop."
         }
       }
     },
@@ -3696,6 +4422,81 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "iban-input",
+      "capabilities": [
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Current IBAN, normalised (uppercased, [A-Z0-9], no spaces, ≤34 characters).",
+          "descriptionKey": "ui.agent.ibanInput.state.value"
+        },
+        {
+          "name": "isValid",
+          "type": "boolean",
+          "description": "Whether the value is a structurally complete IBAN with a passing mod-97-10 checksum.",
+          "descriptionKey": "ui.agent.ibanInput.state.isValid"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "DE89370400440532013000"
+              },
+              "note": "A complete, checksum-valid German IBAN."
+            }
+          ],
+          "description": "Replace the IBAN. The value is uppercased and stripped to [A-Z0-9], capped at 34 characters.",
+          "descriptionKey": "ui.agent.ibanInput.actions.setValue"
+        },
+        {
+          "name": "clear",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Empty the input. Loses any typed value.",
+          "descriptionKey": "ui.agent.ibanInput.actions.clear"
+        },
+        {
+          "name": "focus",
+          "safety": "read",
+          "description": "Move keyboard focus to the IBAN input.",
+          "descriptionKey": "ui.agent.ibanInput.actions.focus"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "iban-input",
+          "description": "Marks the IbanInput wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "icon-button",
@@ -3708,19 +4509,208 @@
           "value": "icon-button",
           "description": "Marks the element as a kit IconButton. Safety is declared by the host pattern, not the button. IconButtons inherit native `id` from props, which is what agents address them by."
         }
-      }
-    },
-    {
-      "kind": "component",
-      "id": "icon-button-group",
-      "capabilities": [],
-      "state": [],
-      "actions": [],
+      }
+    },
+    {
+      "kind": "component",
+      "id": "icon-button-group",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "icon-button-group",
+          "description": "Marks the IconButtonGroup wrapper. Agents target individual IconButtons inside the group via their native `id`."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "icon-picker",
+      "capabilities": [
+        "pick",
+        "filter",
+        "open",
+        "close"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Id of the currently selected icon, or an empty string when nothing is picked.",
+          "descriptionKey": "ui.agent.iconPicker.state.value"
+        },
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "True when the picker popover is currently open.",
+          "descriptionKey": "ui.agent.iconPicker.state.isOpen"
+        },
+        {
+          "name": "query",
+          "type": "string",
+          "description": "Current search query filtering the icon grid by label.",
+          "descriptionKey": "ui.agent.iconPicker.state.query"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Id of an icon in the supplied `icons` set."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "star"
+              },
+              "note": "Pick the \"star\" icon."
+            }
+          ],
+          "description": "Select the icon with the given id.",
+          "descriptionKey": "ui.agent.iconPicker.actions.setValue"
+        },
+        {
+          "name": "open",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Open the picker popover.",
+          "descriptionKey": "ui.agent.iconPicker.actions.open"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Close the picker popover.",
+          "descriptionKey": "ui.agent.iconPicker.actions.close"
+        },
+        {
+          "name": "filter",
+          "safety": "write",
+          "argsType": "{ query: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "Case-insensitive substring matched against icon labels."
+              }
+            },
+            "required": [
+              "query"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "query": "star"
+              },
+              "note": "Show icons whose label contains \"star\"."
+            }
+          ],
+          "description": "Filter the icon grid to labels containing the query.",
+          "descriptionKey": "ui.agent.iconPicker.actions.filter"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "icon-picker",
+          "description": "Marks the IconPicker trigger button."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "image-cropper",
+      "capabilities": [
+        "range_pick"
+      ],
+      "state": [
+        {
+          "name": "crop",
+          "type": "object",
+          "description": "Current crop rectangle in normalised [0,1] coordinates: { x, y, width, height }.",
+          "descriptionKey": "ui.agent.imageCropper.state.crop"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_crop",
+          "safety": "write",
+          "argsType": "{ x: number; y: number; width: number; height: number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "x": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "width": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "height": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              }
+            },
+            "required": [
+              "x",
+              "y",
+              "width",
+              "height"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set the crop rectangle (normalised [0,1]). Values are clamped to the image bounds and the minimum crop size.",
+          "descriptionKey": "ui.agent.imageCropper.actions.setCrop"
+        },
+        {
+          "name": "reset",
+          "safety": "write",
+          "idempotent": true,
+          "description": "Reset the crop to the centred default for the current aspect.",
+          "descriptionKey": "ui.agent.imageCropper.actions.reset"
+        }
+      ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "icon-button-group",
-          "description": "Marks the IconButtonGroup wrapper. Agents target individual IconButtons inside the group via their native `id`."
+          "value": "image-cropper",
+          "description": "Marks the ImageCropper wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
         }
       }
     },
@@ -4039,7 +5029,8 @@
         "open",
         "close",
         "select_single",
-        "dismiss"
+        "dismiss",
+        "navigate"
       ],
       "state": [
         {
@@ -4142,6 +5133,20 @@
           "idempotent": true,
           "description": "Request the host to dismiss / archive the message with the given id.",
           "descriptionKey": "ui.agent.messageTray.actions.dismiss"
+        },
+        {
+          "name": "mark_all_read",
+          "safety": "write",
+          "idempotent": true,
+          "description": "Request the host to mark every message as read.",
+          "descriptionKey": "ui.agent.messageTray.actions.markAllRead"
+        },
+        {
+          "name": "view_all",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Navigate to the full inbox / message list.",
+          "descriptionKey": "ui.agent.messageTray.actions.viewAll"
         }
       ],
       "domHooks": {
@@ -4283,6 +5288,68 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "nav-grid",
+      "capabilities": [
+        "navigate"
+      ],
+      "state": [
+        {
+          "name": "itemCount",
+          "type": "number",
+          "description": "Number of navigable tiles currently rendered in the grid.",
+          "descriptionKey": "ui.agent.navGrid.state.itemCount"
+        }
+      ],
+      "actions": [
+        {
+          "name": "open_item",
+          "safety": "write",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Stable opaque tile id (emitted as data-nav-item-id on each tile)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "openWorld": false,
+          "examples": [
+            {
+              "args": {
+                "id": "billing"
+              },
+              "note": "Open the \"billing\" settings section."
+            }
+          ],
+          "description": "Activate the tile with the given id (navigates or fires its select handler).",
+          "descriptionKey": "ui.agent.navGrid.actions.openItem"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "nav-grid",
+          "description": "Marks the NavGrid nav landmark."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific grid from the agent."
+        },
+        "item": {
+          "attr": "data-nav-item-id",
+          "sourceProp": "item id",
+          "description": "Stable opaque id of a tile, sourced from each item.id. open_item targets this attribute."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "navigation-menu",
@@ -4380,6 +5447,113 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "notes-panel",
+      "capabilities": [
+        "submit"
+      ],
+      "state": [
+        {
+          "name": "notes",
+          "type": "Array<{ id?: string; pinned: boolean; flagged: boolean; clinical: boolean }>",
+          "description": "Timeline note ids + pinned / flagged / clinical flags. Never the note body or author (both PHI).",
+          "descriptionKey": "ui.agent.notesPanel.state.notes"
+        },
+        {
+          "name": "canAddClinical",
+          "type": "boolean",
+          "description": "Whether the current user may write clinical notes (the practice_add_clinical_note permission gate).",
+          "descriptionKey": "ui.agent.notesPanel.state.canAddClinical"
+        }
+      ],
+      "actions": [
+        {
+          "name": "add_note",
+          "safety": "phi",
+          "argsType": "{ content: string; clinical: boolean }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "content": {
+                "type": "string",
+                "description": "Note body. Rich HTML for the rich composer, else plain text."
+              },
+              "clinical": {
+                "type": "boolean",
+                "description": "Whether the note is clinical. Requires the clinical-note permission; the submission is dropped when the gate is closed."
+              }
+            },
+            "required": [
+              "content",
+              "clinical"
+            ]
+          },
+          "openWorld": true,
+          "examples": [
+            {
+              "args": {
+                "content": "Patient reported improvement.",
+                "clinical": true
+              },
+              "note": "Add a clinical note."
+            }
+          ],
+          "description": "Compose and commit a new note. A clinical note requires the clinical-note permission (read canAddClinical first).",
+          "descriptionKey": "ui.agent.notesPanel.actions.addNote"
+        },
+        {
+          "name": "toggle_pin",
+          "safety": "write",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": false,
+          "description": "Toggle the pinned state of the note with the given id.",
+          "descriptionKey": "ui.agent.notesPanel.actions.togglePin"
+        },
+        {
+          "name": "toggle_flag",
+          "safety": "write",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": false,
+          "description": "Toggle the flagged state of the note with the given id.",
+          "descriptionKey": "ui.agent.notesPanel.actions.toggleFlag"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "notes-panel",
+          "description": "Marks the NotesPanel region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific notes panel from the agent."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "notification-card",
@@ -4408,7 +5582,8 @@
         "open",
         "close",
         "select_single",
-        "dismiss"
+        "dismiss",
+        "navigate"
       ],
       "state": [
         {
@@ -4531,6 +5706,20 @@
           ],
           "description": "Request the host to dismiss the notification with the given id.",
           "descriptionKey": "ui.agent.notificationTray.actions.dismiss"
+        },
+        {
+          "name": "mark_all_read",
+          "safety": "write",
+          "idempotent": true,
+          "description": "Request the host to mark every notification as read.",
+          "descriptionKey": "ui.agent.notificationTray.actions.markAllRead"
+        },
+        {
+          "name": "view_all",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Navigate to the full notification list.",
+          "descriptionKey": "ui.agent.notificationTray.actions.viewAll"
         }
       ],
       "domHooks": {
@@ -4819,6 +6008,20 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "panel-header",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "panel-header",
+          "description": "Marks the element as a kit PanelHeader."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "password-input",
@@ -4877,26 +6080,159 @@
           "name": "focus",
           "safety": "read",
           "idempotent": true,
-          "description": "Move keyboard focus to the input.",
-          "descriptionKey": "ui.agent.passwordInput.actions.focus"
+          "description": "Move keyboard focus to the input.",
+          "descriptionKey": "ui.agent.passwordInput.actions.focus"
+        },
+        {
+          "name": "toggle_visibility",
+          "safety": "read",
+          "description": "Toggle between masked and plain-text display.",
+          "descriptionKey": "ui.agent.passwordInput.actions.toggleVisibility"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "password-input",
+          "description": "Marks the PasswordInput wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "patient-details",
+      "capabilities": [
+        "view_change",
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "visibleFieldOrder",
+          "type": "string[]",
+          "description": "Ordered list of visible field KEYS (e.g. \"fiscalCode\"). Never a field value.",
+          "descriptionKey": "ui.agent.patientDetails.state.visibleFieldOrder"
+        },
+        {
+          "name": "patientId",
+          "type": "string | undefined",
+          "description": "Opaque patient id the panel is bound to. No patient-identifiable data.",
+          "descriptionKey": "ui.agent.patientDetails.state.patientId"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_visible_fields",
+          "safety": "write",
+          "argsType": "{ fieldIds: string[] }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fieldIds": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "fieldIds"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "fieldIds": [
+                  "lastName",
+                  "firstName",
+                  "phone",
+                  "email"
+                ]
+              },
+              "note": "Show only name + contact fields."
+            }
+          ],
+          "description": "Set which fields are visible (and their order). Unknown ids are ignored.",
+          "descriptionKey": "ui.agent.patientDetails.actions.setVisibleFields"
+        },
+        {
+          "name": "set_field_order",
+          "safety": "write",
+          "argsType": "{ orderedIds: string[] }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "orderedIds": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "orderedIds"
+            ]
+          },
+          "idempotent": true,
+          "description": "Reorder the visible fields. Order within a section is honoured; sections stay fixed.",
+          "descriptionKey": "ui.agent.patientDetails.actions.setFieldOrder"
         },
         {
-          "name": "toggle_visibility",
-          "safety": "read",
-          "description": "Toggle between masked and plain-text display.",
-          "descriptionKey": "ui.agent.passwordInput.actions.toggleVisibility"
+          "name": "update_field",
+          "safety": "phi",
+          "argsType": "{ fieldId: string; value: unknown }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fieldId": {
+                "type": "string"
+              },
+              "value": {}
+            },
+            "required": [
+              "fieldId",
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "openWorld": true,
+          "errors": [
+            "no-save-handler",
+            "validation-failed",
+            "permission-denied"
+          ],
+          "examples": [
+            {
+              "args": {
+                "fieldId": "job",
+                "value": "Architect"
+              },
+              "note": "Update the patient’s occupation."
+            }
+          ],
+          "description": "Write a patient field value via the consumer's audited save path. Subject to the same permissions and validation as a human edit.",
+          "descriptionKey": "ui.agent.patientDetails.actions.updateField"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "password-input",
-          "description": "Marks the PasswordInput wrapper."
+          "value": "patient-details",
+          "description": "Marks the PatientDetails root region."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop."
+          "description": "Sourced from the id prop. Addresses a specific panel."
+        },
+        "item": {
+          "attr": "data-field-id",
+          "description": "Stable field KEY on each row. Never the field value (no PHI in the DOM hook)."
         }
       }
     },
@@ -5237,6 +6573,75 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "permission-matrix",
+      "capabilities": [
+        "select_multiple"
+      ],
+      "state": [
+        {
+          "name": "selection",
+          "type": "string[]",
+          "description": "Ids of currently-granted editable permissions. Locked owner permissions are excluded.",
+          "descriptionKey": "ui.agent.permissionMatrix.state.selection"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_selection",
+          "safety": "write",
+          "argsType": "{ values: string[] }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "values": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "required": [
+              "values"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "values": [
+                  "patients.view",
+                  "billing.view"
+                ]
+              },
+              "note": "Grant exactly the view permissions for patients and billing."
+            }
+          ],
+          "description": "Replace the granted permissions with the given ids. Locked and unknown ids are ignored.",
+          "descriptionKey": "ui.agent.permissionMatrix.actions.setSelection"
+        },
+        {
+          "name": "clear",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Revoke every editable permission. Locked owner permissions are unaffected.",
+          "descriptionKey": "ui.agent.permissionMatrix.actions.clear"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "permission-matrix",
+          "description": "Marks the PermissionMatrix root group."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "phone-input",
@@ -5253,8 +6658,187 @@
         {
           "name": "isEmpty",
           "type": "boolean",
-          "description": "Whether the input has no value.",
-          "descriptionKey": "ui.agent.phoneInput.state.isEmpty"
+          "description": "Whether the input has no value.",
+          "descriptionKey": "ui.agent.phoneInput.state.isEmpty"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string",
+                "description": "Phone number in E.164 or national format; the parser infers the country."
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "+393331234567"
+              },
+              "note": "Set an Italian mobile."
+            }
+          ],
+          "description": "Replace the phone number (E.164 or national format; parser will infer country).",
+          "descriptionKey": "ui.agent.phoneInput.actions.setValue"
+        },
+        {
+          "name": "clear",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Empty the input. Loses any typed value.",
+          "descriptionKey": "ui.agent.phoneInput.actions.clear"
+        },
+        {
+          "name": "focus",
+          "safety": "read",
+          "description": "Move keyboard focus to the phone-number input.",
+          "descriptionKey": "ui.agent.phoneInput.actions.focus"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "phone-input",
+          "description": "Marks the PhoneInput wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "popover",
+      "capabilities": [
+        "open",
+        "close"
+      ],
+      "state": [
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "True when the popover is currently open.",
+          "descriptionKey": "ui.agent.popover.state.isOpen"
+        }
+      ],
+      "actions": [
+        {
+          "name": "open",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Open the popover.",
+          "descriptionKey": "ui.agent.popover.actions.open"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Close the popover.",
+          "descriptionKey": "ui.agent.popover.actions.close"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "popover"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop on Popover.Root."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "position-grid",
+      "capabilities": [
+        "select_single"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Currently selected position value (e.g. \"top-start\"), or empty string when none.",
+          "descriptionKey": "ui.agent.positionGrid.state.value"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "center"
+              },
+              "note": "Selects the centre cell of the default 3×3 grid."
+            }
+          ],
+          "description": "Select the cell with the given position value.",
+          "descriptionKey": "ui.agent.positionGrid.actions.setValue"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "position-grid",
+          "description": "Marks the PositionGrid root."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-option-id",
+          "description": "Position value emitted on each rendered cell."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "postal-code-input",
+      "capabilities": [
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Current postal code value.",
+          "descriptionKey": "ui.agent.postalCodeInput.state.value"
+        },
+        {
+          "name": "isEmpty",
+          "type": "boolean",
+          "description": "Whether the field has no value.",
+          "descriptionKey": "ui.agent.postalCodeInput.state.isEmpty"
         }
       ],
       "actions": [
@@ -5266,8 +6850,7 @@
             "type": "object",
             "properties": {
               "value": {
-                "type": "string",
-                "description": "Phone number in E.164 or national format; the parser infers the country."
+                "type": "string"
               }
             },
             "required": [
@@ -5278,33 +6861,26 @@
           "examples": [
             {
               "args": {
-                "value": "+393331234567"
+                "value": "20121"
               },
-              "note": "Set an Italian mobile."
+              "note": "An Italian CAP."
             }
           ],
-          "description": "Replace the phone number (E.164 or national format; parser will infer country).",
-          "descriptionKey": "ui.agent.phoneInput.actions.setValue"
+          "description": "Replace the postal code value.",
+          "descriptionKey": "ui.agent.postalCodeInput.actions.setValue"
         },
         {
           "name": "clear",
           "safety": "destructive",
           "idempotent": true,
-          "description": "Empty the input. Loses any typed value.",
-          "descriptionKey": "ui.agent.phoneInput.actions.clear"
-        },
-        {
-          "name": "focus",
-          "safety": "read",
-          "description": "Move keyboard focus to the phone-number input.",
-          "descriptionKey": "ui.agent.phoneInput.actions.focus"
+          "description": "Empty the field. Loses any typed value.",
+          "descriptionKey": "ui.agent.postalCodeInput.actions.clear"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "phone-input",
-          "description": "Marks the PhoneInput wrapper."
+          "value": "postal-code-input"
         },
         "instanceId": {
           "attr": "data-component-id",
@@ -5313,49 +6889,6 @@
         }
       }
     },
-    {
-      "kind": "component",
-      "id": "popover",
-      "capabilities": [
-        "open",
-        "close"
-      ],
-      "state": [
-        {
-          "name": "isOpen",
-          "type": "boolean",
-          "description": "True when the popover is currently open.",
-          "descriptionKey": "ui.agent.popover.state.isOpen"
-        }
-      ],
-      "actions": [
-        {
-          "name": "open",
-          "safety": "read",
-          "idempotent": true,
-          "description": "Open the popover.",
-          "descriptionKey": "ui.agent.popover.actions.open"
-        },
-        {
-          "name": "close",
-          "safety": "read",
-          "idempotent": true,
-          "description": "Close the popover.",
-          "descriptionKey": "ui.agent.popover.actions.close"
-        }
-      ],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "value": "popover"
-        },
-        "instanceId": {
-          "attr": "data-component-id",
-          "sourceProp": "id",
-          "description": "Sourced from the id prop on Popover.Root."
-        }
-      }
-    },
     {
       "kind": "component",
       "id": "practice-results",
@@ -5672,6 +7205,77 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "province-select",
+      "capabilities": [
+        "select_single",
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string | null",
+          "description": "Selected province code (UPPERCASED sigla for Italy), or null when nothing is selected.",
+          "descriptionKey": "ui.agent.provinceSelect.state.value"
+        }
+      ],
+      "actions": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string | null }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Province code to select (UPPERCASED), or null to clear."
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "MI"
+              },
+              "note": "Select Milano."
+            }
+          ],
+          "description": "Set the selected province by code.",
+          "descriptionKey": "ui.agent.provinceSelect.actions.setValue"
+        },
+        {
+          "name": "clear_selection",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Clear the selected province.",
+          "descriptionKey": "ui.agent.provinceSelect.actions.clearSelection"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "province-select"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-option-id",
+          "description": "Each province option emits its code as data-option-id."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "public-footer",
@@ -5827,6 +7431,65 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "radiograph-panel",
+      "capabilities": [
+        "pick",
+        "view_change"
+      ],
+      "state": [
+        {
+          "name": "radiographs",
+          "type": "Array<{ id: string; kind?: string }>",
+          "description": "Structural references (id + kind) to the films shown for the selected tooth.",
+          "descriptionKey": "ui.agent.radiographPanel.state.radiographs"
+        }
+      ],
+      "actions": [
+        {
+          "name": "view_radiograph",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Open a film in the fullscreen viewer by id.",
+          "descriptionKey": "ui.agent.radiographPanel.actions.viewRadiograph"
+        },
+        {
+          "name": "close_viewer",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Close the fullscreen radiograph viewer.",
+          "descriptionKey": "ui.agent.radiographPanel.actions.closeViewer"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "radiograph-panel"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-radiograph-id",
+          "description": "Each film row (`<li>`) carries its radiograph id as `data-radiograph-id`. The panel root additionally carries the selected tooth's FDI id as `data-tooth`."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "rating",
@@ -7352,8 +9015,102 @@
         {
           "name": "items",
           "type": "Array<{ id: string; status: string }>",
-          "description": "Currently-displayed tasks. Ids + status only — never task title / patient.",
-          "descriptionKey": "ui.agent.taskTray.state.items"
+          "description": "Currently-displayed tasks. Ids + status only — never task title / patient.",
+          "descriptionKey": "ui.agent.taskTray.state.items"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_item",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Activate the task with the given id.",
+          "descriptionKey": "ui.agent.taskTray.actions.selectItem"
+        },
+        {
+          "name": "toggle_done",
+          "safety": "write",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "description": "Request the host to toggle the done state of a task.",
+          "descriptionKey": "ui.agent.taskTray.actions.toggleDone"
+        },
+        {
+          "name": "dismiss",
+          "safety": "destructive",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Request the host to dismiss / remove the task with the given id.",
+          "descriptionKey": "ui.agent.taskTray.actions.dismiss"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "task-tray",
+          "description": "Marks the TaskTray wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific tray from the agent."
+        },
+        "item": {
+          "attr": "data-task-id",
+          "description": "Stable task id emitted on each rendered TaskCard inside the tray."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "tasks-panel",
+      "capabilities": [
+        "pick",
+        "dismiss",
+        "scroll",
+        "filter",
+        "view_change",
+        "paginate"
+      ],
+      "state": [
+        {
+          "name": "items",
+          "type": "Array<{ id: string; status: string }>",
+          "description": "Currently-rendered tasks. Ids + status only — never task note / patient.",
+          "descriptionKey": "ui.agent.tasksPanel.state.items"
         }
       ],
       "actions": [
@@ -7374,7 +9131,7 @@
           },
           "idempotent": true,
           "description": "Activate the task with the given id.",
-          "descriptionKey": "ui.agent.taskTray.actions.selectItem"
+          "descriptionKey": "ui.agent.tasksPanel.actions.selectItem"
         },
         {
           "name": "toggle_done",
@@ -7392,7 +9149,7 @@
             ]
           },
           "description": "Request the host to toggle the done state of a task.",
-          "descriptionKey": "ui.agent.taskTray.actions.toggleDone"
+          "descriptionKey": "ui.agent.tasksPanel.actions.toggleDone"
         },
         {
           "name": "dismiss",
@@ -7411,23 +9168,96 @@
           },
           "idempotent": true,
           "description": "Request the host to dismiss / remove the task with the given id.",
-          "descriptionKey": "ui.agent.taskTray.actions.dismiss"
+          "descriptionKey": "ui.agent.tasksPanel.actions.dismiss"
+        },
+        {
+          "name": "jump_to_overdue",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Re-anchor the panel scroll on the overdue tasks.",
+          "descriptionKey": "ui.agent.tasksPanel.actions.jumpToOverdue"
+        },
+        {
+          "name": "set_filter",
+          "safety": "read",
+          "argsType": "{ status?: 'todo' | 'done' | 'all'; type?: string | null; assignee?: string | null; overdueOnly?: boolean }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "status": {
+                "type": "string",
+                "enum": [
+                  "todo",
+                  "done",
+                  "all"
+                ]
+              },
+              "type": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "assignee": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "overdueOnly": {
+                "type": "boolean"
+              }
+            }
+          },
+          "idempotent": true,
+          "description": "Set the task filters (status segment, type, assignee, overdue-only). Omitted keys are left unchanged.",
+          "descriptionKey": "ui.agent.tasksPanel.actions.setFilter"
+        },
+        {
+          "name": "change_scope",
+          "safety": "read",
+          "argsType": "{ scope: 'patient' | 'mine' }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "scope": {
+                "type": "string",
+                "enum": [
+                  "patient",
+                  "mine"
+                ]
+              }
+            },
+            "required": [
+              "scope"
+            ]
+          },
+          "idempotent": true,
+          "description": "Switch the task scope segment between this patient ('patient') and the operator's own tasks ('mine'). The host re-feeds the items.",
+          "descriptionKey": "ui.agent.tasksPanel.actions.changeScope"
+        },
+        {
+          "name": "load_more",
+          "safety": "read",
+          "openWorld": true,
+          "description": "Request the host to append the next page of tasks.",
+          "descriptionKey": "ui.agent.tasksPanel.actions.loadMore"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "task-tray",
-          "description": "Marks the TaskTray wrapper."
+          "value": "tasks-panel",
+          "description": "Marks the TasksPanel wrapper."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop. Required to address a specific tray from the agent."
+          "description": "Sourced from the id prop. Required to address a specific panel from the agent."
         },
         "item": {
           "attr": "data-task-id",
-          "description": "Stable task id emitted on each rendered TaskCard inside the tray."
+          "description": "Stable task id emitted on each rendered TaskCard inside the panel."
         }
       }
     },
@@ -7865,6 +9695,167 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "token-insert-menu",
+      "capabilities": [
+        "open",
+        "close"
+      ],
+      "state": [
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "True when the token menu is currently open.",
+          "descriptionKey": "ui.agent.tokenInsertMenu.state.isOpen"
+        }
+      ],
+      "actions": [
+        {
+          "name": "open",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Open the token menu.",
+          "descriptionKey": "ui.agent.tokenInsertMenu.actions.open"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Close the token menu.",
+          "descriptionKey": "ui.agent.tokenInsertMenu.actions.close"
+        },
+        {
+          "name": "insert",
+          "safety": "write",
+          "argsType": "{ token: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "token": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "token"
+            ]
+          },
+          "examples": [
+            {
+              "args": {
+                "token": "{{patient.name}}"
+              },
+              "note": "Emit the patient-name placeholder for cursor insertion."
+            }
+          ],
+          "description": "Emit a merge-token to the consumer for cursor insertion.",
+          "descriptionKey": "ui.agent.tokenInsertMenu.actions.insert"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "token-insert-menu",
+          "description": "Marks the TokenInsertMenu wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "tool-rail",
+      "capabilities": [
+        "open",
+        "close",
+        "select_single"
+      ],
+      "state": [
+        {
+          "name": "activeToolId",
+          "type": "string | null",
+          "description": "Id of the tool whose panel is currently open, or null when the rail is collapsed to its strip. No panel content is ever exposed.",
+          "descriptionKey": "ui.toolRail.agent.state.activeToolId"
+        }
+      ],
+      "actions": [
+        {
+          "name": "open",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "inbox"
+              },
+              "note": "Open the inbox tool panel."
+            }
+          ],
+          "description": "Open the given tool's panel.",
+          "descriptionKey": "ui.toolRail.agent.actions.open"
+        },
+        {
+          "name": "close",
+          "safety": "read",
+          "idempotent": true,
+          "description": "Collapse the rail to its strip (no active tool).",
+          "descriptionKey": "ui.toolRail.agent.actions.close"
+        },
+        {
+          "name": "select_tool",
+          "safety": "read",
+          "argsType": "{ id: string | null }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set the active tool by id (opens its panel), or pass null to collapse.",
+          "descriptionKey": "ui.toolRail.agent.actions.selectTool"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "tool-rail",
+          "description": "Marks the ToolRail wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific rail from the agent."
+        },
+        "item": {
+          "attr": "data-tool-id",
+          "description": "Stable tool id emitted on each strip IconButton. The active icon also carries data-active set to its id."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "tooltip",
@@ -7892,14 +9883,26 @@
         {
           "name": "chart",
           "type": "object",
-          "description": "Current dental chart — findings (and marked surfaces) keyed by FDI id.",
+          "description": "Current dental chart — findings (and marked surfaces) keyed by FDI id, or by a special-element id (quadrant / sextant / arch / general) for region-spanning findings.",
           "descriptionKey": "ui.agent.toothScheme.state.chart"
         },
         {
           "name": "chartedTeeth",
           "type": "string[]",
-          "description": "FDI ids of every tooth carrying at least one finding.",
+          "description": "Ids carrying at least one finding — FDI tooth ids and/or special-element ids (quadrant / sextant / arch / general).",
           "descriptionKey": "ui.agent.toothScheme.state.chartedTeeth"
+        },
+        {
+          "name": "radiographs",
+          "type": "Record<string, { id: string; kind?: string }[]>",
+          "description": "Structural references (id + kind) to the radiographs on each tooth, keyed by FDI id. Notes, dates and image URLs are not exposed here — fetch them on demand via get_radiographs.",
+          "descriptionKey": "ui.agent.toothScheme.state.radiographs"
+        },
+        {
+          "name": "teethWithRadiographs",
+          "type": "string[]",
+          "description": "FDI ids of every tooth carrying at least one radiograph.",
+          "descriptionKey": "ui.agent.toothScheme.state.teethWithRadiographs"
         }
       ],
       "actions": [
@@ -7912,7 +9915,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
               }
             },
             "required": [
@@ -7932,7 +9935,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
               }
             },
             "required": [
@@ -7994,12 +9997,92 @@
             "type": "array",
             "items": {
               "type": "string",
-              "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+              "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+            }
+          },
+          "idempotent": true,
+          "description": "List the ids carrying a given finding — FDI tooth ids and/or special-element ids (e.g. all teeth with caries).",
+          "descriptionKey": "ui.agent.toothScheme.actions.teethWith"
+        },
+        {
+          "name": "get_radiographs",
+          "safety": "read",
+          "argsType": "{ id: FdiId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "returns": "Radiograph[]",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "url": {
+                  "type": "string"
+                },
+                "thumbnailUrl": {
+                  "type": "string"
+                },
+                "date": {
+                  "type": "string",
+                  "description": "ISO acquisition date (YYYY-MM-DD)."
+                },
+                "note": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "periapical",
+                    "bitewing",
+                    "panoramic",
+                    "other"
+                  ]
+                },
+                "alt": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "url"
+              ]
             }
           },
           "idempotent": true,
-          "description": "List the FDI ids of every tooth carrying a given finding (e.g. all teeth with caries).",
-          "descriptionKey": "ui.agent.toothScheme.actions.teethWith"
+          "description": "Read the radiographs (x-rays) attached to one tooth.",
+          "descriptionKey": "ui.agent.toothScheme.actions.getRadiographs"
+        },
+        {
+          "name": "open_radiographs",
+          "safety": "read",
+          "argsType": "{ id: FdiId }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Focus a tooth and open its radiograph archive (fires the host's onOpenRadiographs).",
+          "descriptionKey": "ui.agent.toothScheme.actions.openRadiographs"
         },
         {
           "name": "set_finding",
@@ -8010,7 +10093,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
               },
               "condition": {
                 "enum": [
@@ -8046,7 +10129,7 @@
             ]
           },
           "idempotent": true,
-          "description": "Record a finding on a tooth (crown, implant, root canal, caries, …). Optionally mark the affected surfaces for a surface finding.",
+          "description": "Record a finding on a tooth or region element (crown, implant, root canal, caries, …). Optionally mark the affected surfaces for a surface finding.",
           "descriptionKey": "ui.agent.toothScheme.actions.setFinding"
         },
         {
@@ -8058,7 +10141,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
               },
               "condition": {
                 "enum": [
@@ -8094,7 +10177,7 @@
             "properties": {
               "id": {
                 "type": "string",
-                "description": "FDI tooth id, e.g. '11'–'48' permanent, '51'–'85' primary."
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary) or a special-element id ('Q1'–'Q4' quadrants, 'S1'–'S6' sextants, 'AS'/'AI' arches, 'general'; primary mirrors with an 'm' prefix)."
               }
             },
             "required": [
@@ -8118,7 +10201,7 @@
         },
         "item": {
           "attr": "data-fdi",
-          "description": "Each rendered tooth `<g>` carries its FDI id as `data-fdi`. The `data-projection` attribute on the root exposes the side/plan view."
+          "description": "Each rendered tooth `<g>` carries its FDI id as `data-fdi`; selectable special-element slots carry their id there too (plus `data-special` naming the kind). The `data-projection` / `data-view-mode` attributes on the root expose the side/plan/both view."
         }
       }
     },
@@ -8740,6 +10823,16 @@
             "alia.cancelGeneration"
           ]
         },
+        {
+          "name": "retry_message",
+          "safety": "write",
+          "description": "Re-send a message that failed to send. The failed message is located by its `data-status=\"error\"` ChatMessage (addressed via `data-component-id`); activating that message's built-in retry control re-submits it. No adapter action — the retry control is a DOM-click affordance on the errored message.",
+          "descriptionKey": "ui.agent.aliaAssistant.workflows.retryMessage",
+          "uiActions": [],
+          "apiActions": [
+            "alia.sendMessage"
+          ]
+        },
         {
           "name": "toggle_popout",
           "safety": "read",
@@ -9028,6 +11121,184 @@
         }
       ]
     },
+    {
+      "kind": "pattern",
+      "id": "care-plan-editor",
+      "composes": [
+        {
+          "component": "care-plan-header",
+          "as": "planHeader"
+        },
+        {
+          "component": "tooth-scheme",
+          "as": "odontogram",
+          "entity": "tooth"
+        },
+        {
+          "component": "data-table",
+          "as": "treatmentsGrid",
+          "entity": "treatment"
+        },
+        {
+          "component": "radiograph-panel",
+          "as": "radiographs",
+          "entity": "radiograph"
+        },
+        {
+          "component": "control-room-rail",
+          "as": "toolRail"
+        },
+        {
+          "component": "notes-panel",
+          "as": "planNotes",
+          "entity": "note"
+        },
+        {
+          "component": "tasks-panel",
+          "as": "planTasks",
+          "entity": "task"
+        },
+        {
+          "component": "entity-summary",
+          "as": "planSummary"
+        }
+      ],
+      "workflows": [
+        {
+          "name": "select_plan",
+          "safety": "read",
+          "description": "Open one of the patient's care plans from the plan list. Activation is a native click on the plan row; the host loads the plan into the editor.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.selectPlan",
+          "uiActions": [],
+          "apiActions": [
+            "carePlan.get"
+          ]
+        },
+        {
+          "name": "add_plan",
+          "safety": "write",
+          "description": "Create a new care plan for the patient.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.addPlan",
+          "uiActions": [],
+          "apiActions": [
+            "carePlan.create"
+          ]
+        },
+        {
+          "name": "inspect_tooth",
+          "safety": "read",
+          "description": "Focus a tooth on the odontogram and read its charted dental status.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.inspectTooth",
+          "uiActions": [
+            "tooth-scheme.focus_tooth"
+          ],
+          "stateReads": [
+            "tooth-scheme.chart"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "open_tooth_radiographs",
+          "safety": "read",
+          "description": "Open the radiograph drawer for a tooth that carries imaging (the docked Control Room radiographs tool).",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.openToothRadiographs",
+          "uiActions": [
+            "tooth-scheme.open_radiographs",
+            "control-room-rail.select_tool"
+          ],
+          "stateReads": [
+            "tooth-scheme.teethWithRadiographs"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "mark_treatment_done",
+          "safety": "write",
+          "description": "Mark a planned treatment as executed from its row action in the treatments grid.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.markTreatmentDone",
+          "uiActions": [],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "carePlanTreatment.update"
+          ]
+        },
+        {
+          "name": "add_treatment",
+          "safety": "write",
+          "description": "Add a planned treatment row to the current plan.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.addTreatment",
+          "uiActions": [],
+          "apiActions": [
+            "carePlanTreatment.create"
+          ]
+        },
+        {
+          "name": "remove_treatment",
+          "safety": "destructive",
+          "description": "Remove the selected planned treatment(s) from the plan (read data-table.selection for the targets).",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.removeTreatment",
+          "uiActions": [],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "carePlanTreatment.delete"
+          ]
+        },
+        {
+          "name": "save_plan",
+          "safety": "write",
+          "description": "Persist the current edits to the care plan.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.savePlan",
+          "uiActions": [],
+          "apiActions": [
+            "carePlan.update"
+          ]
+        },
+        {
+          "name": "add_plan_note",
+          "safety": "phi",
+          "description": "Add a note to the plan via the docked Notes tool. A clinical note requires the clinical-note permission.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.addPlanNote",
+          "uiActions": [
+            "notes-panel.add_note"
+          ],
+          "apiActions": [
+            "note.create"
+          ]
+        },
+        {
+          "name": "triage_plan_tasks",
+          "safety": "write",
+          "description": "Open or complete a follow-up task from the docked Tasks tool.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.triagePlanTasks",
+          "uiActions": [
+            "tasks-panel.select_item",
+            "tasks-panel.toggle_done"
+          ],
+          "stateReads": [
+            "tasks-panel.items"
+          ],
+          "apiActions": [
+            "task.update"
+          ]
+        },
+        {
+          "name": "regenerate_summary",
+          "safety": "write",
+          "description": "Regenerate the AI plan summary in the docked AI summary tool.",
+          "descriptionKey": "ui.agent.carePlanEditor.workflows.regenerateSummary",
+          "uiActions": [
+            "entity-summary.regenerate"
+          ],
+          "apiActions": [
+            "alia.summarise"
+          ]
+        }
+      ]
+    },
     {
       "kind": "pattern",
       "id": "care-plans",
@@ -9037,10 +11308,6 @@
           "as": "register",
           "entity": "carePlan"
         },
-        {
-          "component": "select",
-          "as": "periodFilter"
-        },
         {
           "component": "button",
           "as": "newPlan"
@@ -9053,10 +11320,6 @@
           "component": "icon-button-group",
           "as": "rowActions"
         },
-        {
-          "component": "tag",
-          "as": "planStatus"
-        },
         {
           "component": "transaction-chip",
           "as": "invoiceChip"
@@ -9067,27 +11330,15 @@
         },
         {
           "component": "counter",
-          "as": "totalsFooter"
+          "as": "planRollupCount"
         },
         {
           "component": "card",
-          "as": "planDetail"
-        },
-        {
-          "component": "description-list",
-          "as": "planSummary"
-        },
-        {
-          "component": "tooth-scheme",
-          "as": "odontogram"
+          "as": "gridCard"
         },
         {
           "component": "warning-stack",
           "as": "planWarnings"
-        },
-        {
-          "component": "badge",
-          "as": "rollupCount"
         }
       ],
       "workflows": [
@@ -9108,14 +11359,12 @@
         {
           "name": "filter_by_period",
           "safety": "read",
-          "description": "Choose a period preset (e.g. this month, this year) and filter the register to it.",
+          "description": "Filter the register to a created/scheduled date range via the per-column date filters.",
           "descriptionKey": "ui.agent.carePlans.workflows.filterByPeriod",
           "uiActions": [
-            "select.set_value",
             "data-table.apply_filter"
           ],
           "stateReads": [
-            "select.value",
             "data-table.filter"
           ],
           "apiActions": []
@@ -9285,7 +11534,7 @@
           "as": "topbar"
         },
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "rail"
         },
         {
@@ -9332,11 +11581,11 @@
           "description": "Open the inline-end AI tools rail to the Inbox tool to read the merged notifications / messages / product-update feed.",
           "descriptionKey": "ui.agent.dashboard.workflows.openInbox",
           "uiActions": [
-            "ai-tools-rail.open",
-            "ai-tools-rail.select_tool"
+            "tool-rail.open",
+            "tool-rail.select_tool"
           ],
           "stateReads": [
-            "ai-tools-rail.activeToolId"
+            "tool-rail.activeToolId"
           ],
           "apiActions": [
             "inbox.list"
@@ -9661,26 +11910,167 @@
           ]
         },
         {
-          "name": "delete_selected",
+          "name": "delete_selected",
+          "safety": "destructive",
+          "description": "Delete every selected row. Irreversible.",
+          "descriptionKey": "ui.agent.entityIndexTable.workflows.deleteSelected",
+          "uiActions": [
+            "data-table.get_selection",
+            "data-table.clear_selection"
+          ],
+          "apiActions": [
+            "entity.delete"
+          ]
+        },
+        {
+          "name": "export_csv",
+          "safety": "read",
+          "description": "Trigger the CSV export of the current filtered set.",
+          "descriptionKey": "ui.agent.entityIndexTable.workflows.exportCsv",
+          "uiActions": [],
+          "apiActions": [
+            "entity.export"
+          ]
+        }
+      ]
+    },
+    {
+      "kind": "pattern",
+      "id": "invoices",
+      "composes": [
+        {
+          "component": "data-table",
+          "as": "ledger",
+          "entity": "invoice"
+        },
+        {
+          "component": "icon-button-group",
+          "as": "tableActions"
+        },
+        {
+          "component": "icon-button",
+          "as": "tableAction"
+        },
+        {
+          "component": "badge",
+          "as": "statusBadge"
+        },
+        {
+          "component": "button",
+          "as": "rowAction"
+        }
+      ],
+      "workflows": [
+        {
+          "name": "filter_invoices",
+          "safety": "read",
+          "description": "Narrow the ledger by number, relation, status, date range or amount using the per-column filters.",
+          "descriptionKey": "ui.agent.invoices.workflows.filterInvoices",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
+          ],
+          "apiActions": [
+            "invoice.list"
+          ]
+        },
+        {
+          "name": "sort_ledger",
+          "safety": "read",
+          "description": "Re-sort the ledger by any column (e.g. issue date, total, balance).",
+          "descriptionKey": "ui.agent.invoices.workflows.sortLedger",
+          "uiActions": [
+            "data-table.sort_by"
+          ],
+          "stateReads": [
+            "data-table.sort"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "paginate",
+          "safety": "read",
+          "description": "Move to another page of the ledger.",
+          "descriptionKey": "ui.agent.invoices.workflows.paginate",
+          "uiActions": [
+            "data-table.go_to_page"
+          ],
+          "stateReads": [
+            "data-table.currentPage"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "export_ledger",
+          "safety": "read",
+          "description": "Export the current (optionally filtered) ledger from the page-header table-tools cluster — CSV / Excel / PDF.",
+          "descriptionKey": "ui.agent.invoices.workflows.exportLedger",
+          "uiActions": [],
+          "apiActions": [
+            "invoice.export"
+          ]
+        },
+        {
+          "name": "view_invoice",
+          "safety": "read",
+          "description": "Open a single invoice from its row action to inspect line items and payment history.",
+          "descriptionKey": "ui.agent.invoices.workflows.viewInvoice",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "invoice.get"
+          ]
+        },
+        {
+          "name": "download_pdf",
+          "safety": "read",
+          "description": "Download the selected invoice as a PDF from its row action.",
+          "descriptionKey": "ui.agent.invoices.workflows.downloadPdf",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "invoice.downloadPdf"
+          ]
+        },
+        {
+          "name": "send_reminder",
+          "safety": "write",
+          "description": "Send a payment reminder for the selected invoice through its eligible channel (email or SMS).",
+          "descriptionKey": "ui.agent.invoices.workflows.sendReminder",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "invoice.sendReminder"
+          ]
+        },
+        {
+          "name": "delete_invoice",
           "safety": "destructive",
-          "description": "Delete every selected row. Irreversible.",
-          "descriptionKey": "ui.agent.entityIndexTable.workflows.deleteSelected",
+          "description": "Delete the selected invoice from its row action. Paid invoices cannot be deleted. Irreversible.",
+          "descriptionKey": "ui.agent.invoices.workflows.deleteInvoice",
           "uiActions": [
             "data-table.get_selection",
             "data-table.clear_selection"
           ],
+          "stateReads": [
+            "data-table.selection"
+          ],
           "apiActions": [
-            "entity.delete"
-          ]
-        },
-        {
-          "name": "export_csv",
-          "safety": "read",
-          "description": "Trigger the CSV export of the current filtered set.",
-          "descriptionKey": "ui.agent.entityIndexTable.workflows.exportCsv",
-          "uiActions": [],
-          "apiActions": [
-            "entity.export"
+            "invoice.delete"
           ]
         }
       ]
@@ -9941,7 +12331,7 @@
       "id": "patient-ai-summary",
       "composes": [
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "toolRail"
         },
         {
@@ -9991,11 +12381,11 @@
           "description": "Open one of the rail tools — the Patient Summary brief or the Ask Alia chat — making its panel the active complementary landmark.",
           "descriptionKey": "ui.agent.patientAiSummary.workflows.openTool",
           "uiActions": [
-            "ai-tools-rail.open",
-            "ai-tools-rail.select_tool"
+            "tool-rail.open",
+            "tool-rail.select_tool"
           ],
           "stateReads": [
-            "ai-tools-rail.activeToolId"
+            "tool-rail.activeToolId"
           ],
           "apiActions": []
         },
@@ -10049,10 +12439,10 @@
           "description": "Open the Ask Alia tool and send a question about this patient; Alia can answer with an in-conversation entity card.",
           "descriptionKey": "ui.agent.patientAiSummary.workflows.askAlia",
           "uiActions": [
-            "ai-tools-rail.select_tool"
+            "tool-rail.select_tool"
           ],
           "stateReads": [
-            "ai-tools-rail.activeToolId"
+            "tool-rail.activeToolId"
           ],
           "apiActions": [
             "alia.sendMessage"
@@ -10547,8 +12937,8 @@
           "as": "bulkAction"
         },
         {
-          "component": "select",
-          "as": "viewSwitcher"
+          "component": "icon-button-group",
+          "as": "tableActions"
         }
       ],
       "workflows": [
@@ -10626,21 +13016,14 @@
           ]
         },
         {
-          "name": "apply_view",
+          "name": "export_roster",
           "safety": "read",
-          "description": "Choose a saved view from the switcher to apply its filter and sort (and saved column layout) to the roster.",
-          "descriptionKey": "ui.agent.patients.workflows.applyView",
-          "uiActions": [
-            "select.set_value",
-            "data-table.apply_filter",
-            "data-table.sort_by"
-          ],
-          "stateReads": [
-            "select.value",
-            "data-table.filter",
-            "data-table.sort"
-          ],
-          "apiActions": []
+          "description": "Export the current (optionally filtered) patient roster from the page-header table-tools cluster — CSV / Excel / PDF.",
+          "descriptionKey": "ui.agent.patients.workflows.exportRoster",
+          "uiActions": [],
+          "apiActions": [
+            "patient.export"
+          ]
         }
       ]
     },
@@ -10940,7 +13323,7 @@
           "as": "mainNav"
         },
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "inboxRail",
           "entity": "notification"
         },
@@ -11033,10 +13416,10 @@
           "description": "Open the inbox rail's notifications/messages tool and read which tool is active.",
           "descriptionKey": "ui.agent.roiDashboard.workflows.openInbox",
           "uiActions": [
-            "ai-tools-rail.open"
+            "tool-rail.open"
           ],
           "stateReads": [
-            "ai-tools-rail.activeToolId"
+            "tool-rail.activeToolId"
           ],
           "apiActions": []
         },
@@ -11065,6 +13448,147 @@
         }
       ]
     },
+    {
+      "kind": "pattern",
+      "id": "services",
+      "composes": [
+        {
+          "component": "data-table",
+          "as": "catalogue",
+          "entity": "service"
+        },
+        {
+          "component": "card",
+          "as": "gridShell"
+        },
+        {
+          "component": "icon-button-group",
+          "as": "tableActions"
+        },
+        {
+          "component": "icon-button",
+          "as": "tableAction"
+        },
+        {
+          "component": "switch",
+          "as": "compactActionsToggle"
+        }
+      ],
+      "workflows": [
+        {
+          "name": "filter_services",
+          "safety": "read",
+          "description": "Narrow the catalogue by name, code, category, VAT rate or active status using the per-column filters.",
+          "descriptionKey": "ui.agent.services.workflows.filterServices",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
+          ],
+          "apiActions": [
+            "service.list"
+          ]
+        },
+        {
+          "name": "sort_catalogue",
+          "safety": "read",
+          "description": "Re-sort the catalogue by any column (e.g. price, duration, active).",
+          "descriptionKey": "ui.agent.services.workflows.sortCatalogue",
+          "uiActions": [
+            "data-table.sort_by"
+          ],
+          "stateReads": [
+            "data-table.sort"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "compact_actions",
+          "safety": "read",
+          "description": "Toggle the ColumnToggle settings-footer switch to compact the per-row action column.",
+          "descriptionKey": "ui.agent.services.workflows.compactActions",
+          "uiActions": [
+            "switch.set_checked"
+          ],
+          "stateReads": [
+            "switch.checked"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "toggle_active",
+          "safety": "write",
+          "description": "Flip a service’s availability via its per-row Active toggle so it is offered (or withdrawn) on new plans.",
+          "descriptionKey": "ui.agent.services.workflows.toggleActive",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "service.setActive"
+          ]
+        },
+        {
+          "name": "export_catalogue",
+          "safety": "read",
+          "description": "Export the current (optionally filtered) catalogue from the page-header table-tools cluster — CSV / Excel / PDF.",
+          "descriptionKey": "ui.agent.services.workflows.exportCatalogue",
+          "uiActions": [],
+          "apiActions": [
+            "service.export"
+          ]
+        },
+        {
+          "name": "edit_service",
+          "safety": "write",
+          "description": "Edit the selected service (e.g. price, duration, VAT) from its row action.",
+          "descriptionKey": "ui.agent.services.workflows.editService",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "service.update"
+          ]
+        },
+        {
+          "name": "duplicate_service",
+          "safety": "write",
+          "description": "Duplicate the selected service into a new editable copy from its row action.",
+          "descriptionKey": "ui.agent.services.workflows.duplicateService",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "service.duplicate"
+          ]
+        },
+        {
+          "name": "delete_service",
+          "safety": "destructive",
+          "description": "Delete the selected service from its row action. A service in use on a plan cannot be deleted. Irreversible.",
+          "descriptionKey": "ui.agent.services.workflows.deleteService",
+          "uiActions": [
+            "data-table.get_selection",
+            "data-table.clear_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "service.delete"
+          ]
+        }
+      ]
+    },
     {
       "kind": "pattern",
       "id": "settings",
@@ -11082,33 +13606,69 @@
           "as": "primaryNav"
         },
         {
-          "component": "ai-tools-rail",
+          "component": "control-room-rail",
           "as": "toolRail"
         },
         {
-          "component": "tabs",
-          "as": "sectionNav",
-          "entity": "settingsSection"
+          "component": "data-table",
+          "as": "sectionList",
+          "entity": "settingsRecord"
+        },
+        {
+          "component": "dialog",
+          "as": "recordDialog"
         },
         {
           "component": "form-field",
-          "as": "displayNameField"
+          "as": "field"
         },
         {
           "component": "text-input",
-          "as": "displayName"
+          "as": "textField"
+        },
+        {
+          "component": "iban-input",
+          "as": "ibanField"
+        },
+        {
+          "component": "permission-matrix",
+          "as": "permissions"
+        },
+        {
+          "component": "connection-status",
+          "as": "paymentConnection"
+        },
+        {
+          "component": "image-cropper",
+          "as": "photoCropper"
         },
         {
           "component": "switch",
-          "as": "emailDigest"
+          "as": "toggle"
         },
         {
           "component": "select",
-          "as": "language"
+          "as": "choice"
         },
         {
-          "component": "button",
-          "as": "cancel"
+          "component": "radio-group",
+          "as": "optionGroup"
+        },
+        {
+          "component": "checkbox-group",
+          "as": "multiChoice"
+        },
+        {
+          "component": "color-picker",
+          "as": "colour"
+        },
+        {
+          "component": "file-upload",
+          "as": "imageUpload"
+        },
+        {
+          "component": "copy-field",
+          "as": "secret"
         },
         {
           "component": "button",
@@ -11117,78 +13677,227 @@
       ],
       "workflows": [
         {
-          "name": "switch_section",
+          "name": "open_section",
           "safety": "read",
-          "description": "Switch the active settings section (Profile / Notifications / Billing / Security) via the vertical tab strip.",
-          "descriptionKey": "ui.agent.settings.workflows.switchSection",
+          "description": "Open a settings section from the Hub or the grouped section nav. Read-only navigation.",
+          "descriptionKey": "ui.agent.settings.workflows.openSection",
+          "uiActions": [],
+          "apiActions": []
+        },
+        {
+          "name": "edit_text_setting",
+          "safety": "write",
+          "description": "Set a text field in the active section (e.g. practice name, booking address, bank IBAN); marks the form dirty and enables Save.",
+          "descriptionKey": "ui.agent.settings.workflows.editTextSetting",
           "uiActions": [
-            "tabs.select_tab"
+            "text-input.set_value",
+            "text-input.clear",
+            "iban-input.set_value"
           ],
           "stateReads": [
-            "tabs.activeTab"
+            "text-input.value",
+            "iban-input.value"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "toggle_setting",
+          "safety": "write",
+          "description": "Turn a boolean setting on or off (e.g. yearly numbering, group services).",
+          "descriptionKey": "ui.agent.settings.workflows.toggleSetting",
+          "uiActions": [
+            "switch.set_checked",
+            "switch.toggle"
+          ],
+          "stateReads": [
+            "switch.checked"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "choose_option",
+          "safety": "write",
+          "description": "Pick a single option from a select or radio group (e.g. tax regime, document type, stamp method).",
+          "descriptionKey": "ui.agent.settings.workflows.chooseOption",
+          "uiActions": [
+            "select.set_value",
+            "select.open",
+            "select.close",
+            "radio-group.set_value"
+          ],
+          "stateReads": [
+            "select.value",
+            "radio-group.value"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "set_multi_choice",
+          "safety": "write",
+          "description": "Select or clear members of a multi-choice group (e.g. accepted insurers, active branches, per-area permissions).",
+          "descriptionKey": "ui.agent.settings.workflows.setMultiChoice",
+          "uiActions": [
+            "checkbox-group.set_selection",
+            "checkbox-group.clear_selection",
+            "permission-matrix.set_selection",
+            "permission-matrix.clear"
+          ],
+          "stateReads": [
+            "checkbox-group.selection",
+            "permission-matrix.selection"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "pick_colour",
+          "safety": "write",
+          "description": "Choose a colour from the practice palette (e.g. booking page accent).",
+          "descriptionKey": "ui.agent.settings.workflows.pickColour",
+          "uiActions": [
+            "color-picker.set_value"
+          ],
+          "stateReads": [
+            "color-picker.value"
           ],
           "apiActions": []
         },
         {
-          "name": "edit_display_name",
+          "name": "save_section",
+          "safety": "write",
+          "description": "Persist the dirty section form. Save is disabled until a field changes.",
+          "descriptionKey": "ui.agent.settings.workflows.saveSection",
+          "uiActions": [],
+          "apiActions": [
+            "settings.updateSection"
+          ]
+        },
+        {
+          "name": "add_record",
           "safety": "write",
-          "description": "Set the display-name text field; changing it marks the form dirty and enables Save.",
-          "descriptionKey": "ui.agent.settings.workflows.editDisplayName",
+          "description": "Open the create dialog for a list section (cash & banks, chairs, payment types…) and persist a new record.",
+          "descriptionKey": "ui.agent.settings.workflows.addRecord",
           "uiActions": [
+            "dialog.open",
             "text-input.set_value",
-            "text-input.clear"
+            "dialog.close"
+          ],
+          "apiActions": [
+            "settings.createRecord"
+          ]
+        },
+        {
+          "name": "delete_record",
+          "safety": "destructive",
+          "description": "Remove a record from a list section after confirmation. Irreversible.",
+          "descriptionKey": "ui.agent.settings.workflows.deleteRecord",
+          "uiActions": [
+            "data-table.clear_selection"
           ],
           "stateReads": [
-            "text-input.value",
-            "text-input.isEmpty"
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "settings.deleteRecord"
+          ]
+        },
+        {
+          "name": "filter_records",
+          "safety": "read",
+          "description": "Filter the rows of a list section by a column value.",
+          "descriptionKey": "ui.agent.settings.workflows.filterRecords",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
           ],
           "apiActions": []
         },
         {
-          "name": "toggle_email_digest",
+          "name": "upload_practice_photo",
           "safety": "write",
-          "description": "Turn the weekly email digest preference on or off.",
-          "descriptionKey": "ui.agent.settings.workflows.toggleEmailDigest",
+          "description": "Upload, crop, or remove the practice / profile photo.",
+          "descriptionKey": "ui.agent.settings.workflows.uploadPracticePhoto",
           "uiActions": [
-            "switch.set_checked",
-            "switch.toggle"
+            "file-upload.remove_file",
+            "file-upload.clear",
+            "image-cropper.set_crop"
+          ],
+          "stateReads": [
+            "file-upload.files",
+            "image-cropper.crop"
+          ],
+          "apiActions": [
+            "settings.uploadImage"
+          ]
+        },
+        {
+          "name": "copy_secret",
+          "safety": "read",
+          "description": "Copy a read-only secret to the clipboard (API key, data-import key, support PIN, iCal feed URL).",
+          "descriptionKey": "ui.agent.settings.workflows.copySecret",
+          "uiActions": [
+            "copy-field.copy"
           ],
           "stateReads": [
-            "switch.checked"
+            "copy-field.value"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "revoke_api_key",
+          "safety": "destructive",
+          "description": "Revoke or regenerate an API key. Apps using the old key lose access immediately.",
+          "descriptionKey": "ui.agent.settings.workflows.revokeApiKey",
+          "uiActions": [],
+          "stateReads": [
+            "data-table.selection"
           ],
-          "apiActions": []
+          "apiActions": [
+            "apiKey.revoke",
+            "apiKey.regenerate"
+          ]
         },
         {
-          "name": "set_language",
+          "name": "connect_online_payments",
           "safety": "write",
-          "description": "Choose the display language from the language select.",
-          "descriptionKey": "ui.agent.settings.workflows.setLanguage",
+          "description": "Connect or disconnect the Stripe account used for online payments.",
+          "descriptionKey": "ui.agent.settings.workflows.connectOnlinePayments",
           "uiActions": [
-            "select.set_value",
-            "select.open",
-            "select.close"
+            "connection-status.connect",
+            "connection-status.disconnect"
           ],
           "stateReads": [
-            "select.value"
+            "connection-status.status"
           ],
-          "apiActions": []
+          "apiActions": [
+            "onlinePayment.connectStripe",
+            "onlinePayment.disconnectStripe"
+          ]
         },
         {
-          "name": "save_settings",
-          "safety": "write",
-          "description": "Persist the dirty profile form. Save is disabled until a field changes.",
-          "descriptionKey": "ui.agent.settings.workflows.saveSettings",
-          "uiActions": [],
+          "name": "delete_archive",
+          "safety": "destructive",
+          "description": "Delete the current archive after a password-gated confirmation. Permanently removes all of its data. Irreversible.",
+          "descriptionKey": "ui.agent.settings.workflows.deleteArchive",
+          "uiActions": [
+            "dialog.open",
+            "text-input.set_value"
+          ],
           "apiActions": [
-            "settings.updateProfile"
+            "archive.delete"
           ]
         },
         {
-          "name": "discard_changes",
+          "name": "open_tool",
           "safety": "read",
-          "description": "Cancel and reset the form to its last-saved baseline, re-disabling Save.",
-          "descriptionKey": "ui.agent.settings.workflows.discardChanges",
-          "uiActions": [],
+          "description": "Open or switch a Control-Room rail tool (inbox, Alia) without leaving Settings.",
+          "descriptionKey": "ui.agent.settings.workflows.openTool",
+          "uiActions": [
+            "control-room-rail.open",
+            "control-room-rail.select_tool",
+            "control-room-rail.close"
+          ],
           "apiActions": []
         },
         {
@@ -11199,9 +13908,6 @@
           "uiActions": [
             "sidebar.toggle_collapsed"
           ],
-          "stateReads": [
-            "sidebar.isCollapsed"
-          ],
           "apiActions": []
         }
       ]
@@ -11466,6 +14172,153 @@
         }
       ]
     },
+    {
+      "kind": "pattern",
+      "id": "tasks",
+      "composes": [
+        {
+          "component": "data-table",
+          "as": "roster",
+          "entity": "task"
+        },
+        {
+          "component": "warning-stack",
+          "as": "notices"
+        },
+        {
+          "component": "switch",
+          "as": "doneToggle"
+        },
+        {
+          "component": "button",
+          "as": "noticeAction"
+        },
+        {
+          "component": "icon-button-group",
+          "as": "tableActions"
+        },
+        {
+          "component": "icon-button",
+          "as": "tableAction"
+        },
+        {
+          "component": "smart-date",
+          "as": "dueDate"
+        }
+      ],
+      "workflows": [
+        {
+          "name": "filter_tasks",
+          "safety": "read",
+          "description": "Narrow the roster by title, type, assignee, due range or status using the per-column filters.",
+          "descriptionKey": "ui.agent.tasks.workflows.filterTasks",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
+          ],
+          "apiActions": [
+            "task.list"
+          ]
+        },
+        {
+          "name": "filter_from_notice",
+          "safety": "read",
+          "description": "Apply a WarningStack notice’s \"View\" action (e.g. \"View overdue\", \"View collections\") to narrow the roster to the flagged tasks.",
+          "descriptionKey": "ui.agent.tasks.workflows.filterFromNotice",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "sort_roster",
+          "safety": "read",
+          "description": "Re-sort the roster by any column (e.g. soonest due first, created date).",
+          "descriptionKey": "ui.agent.tasks.workflows.sortRoster",
+          "uiActions": [
+            "data-table.sort_by"
+          ],
+          "stateReads": [
+            "data-table.sort"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "toggle_done",
+          "safety": "write",
+          "description": "Mark a task as done (or reopen it) via its per-row done toggle.",
+          "descriptionKey": "ui.agent.tasks.workflows.toggleDone",
+          "uiActions": [
+            "switch.set_checked"
+          ],
+          "stateReads": [
+            "switch.checked"
+          ],
+          "apiActions": [
+            "task.setDone"
+          ]
+        },
+        {
+          "name": "compact_actions",
+          "safety": "read",
+          "description": "Toggle the ColumnToggle settings-footer switch to compact the per-row action column.",
+          "descriptionKey": "ui.agent.tasks.workflows.compactActions",
+          "uiActions": [
+            "switch.set_checked"
+          ],
+          "stateReads": [
+            "switch.checked"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "export_roster",
+          "safety": "read",
+          "description": "Export the current (optionally filtered) roster from the page-header table-tools cluster — CSV / Excel / PDF.",
+          "descriptionKey": "ui.agent.tasks.workflows.exportRoster",
+          "uiActions": [],
+          "apiActions": [
+            "task.export"
+          ]
+        },
+        {
+          "name": "edit_task",
+          "safety": "write",
+          "description": "Edit the selected task from its row action.",
+          "descriptionKey": "ui.agent.tasks.workflows.editTask",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "task.update"
+          ]
+        },
+        {
+          "name": "delete_task",
+          "safety": "destructive",
+          "description": "Delete the selected task from its row action. Completed tasks cannot be deleted. Irreversible.",
+          "descriptionKey": "ui.agent.tasks.workflows.deleteTask",
+          "uiActions": [
+            "data-table.get_selection",
+            "data-table.clear_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "task.delete"
+          ]
+        }
+      ]
+    },
     {
       "kind": "pattern",
       "id": "two-factor-login",
@@ -11636,6 +14489,156 @@
           ]
         }
       ]
+    },
+    {
+      "kind": "pattern",
+      "id": "warehouse",
+      "composes": [
+        {
+          "component": "data-table",
+          "as": "inventory",
+          "entity": "inventoryItem"
+        },
+        {
+          "component": "icon-button-group",
+          "as": "tableActions"
+        },
+        {
+          "component": "icon-button",
+          "as": "tableAction"
+        },
+        {
+          "component": "badge",
+          "as": "statusBadge"
+        },
+        {
+          "component": "switch",
+          "as": "compactActionsToggle"
+        },
+        {
+          "component": "dialog",
+          "as": "importDialog"
+        },
+        {
+          "component": "file-upload",
+          "as": "xmlUpload"
+        }
+      ],
+      "workflows": [
+        {
+          "name": "filter_inventory",
+          "safety": "read",
+          "description": "Narrow the inventory by product, SKU, category, supplier or stock status using the per-column filters.",
+          "descriptionKey": "ui.agent.warehouse.workflows.filterInventory",
+          "uiActions": [
+            "data-table.apply_filter"
+          ],
+          "stateReads": [
+            "data-table.filter"
+          ],
+          "apiActions": [
+            "inventory.list"
+          ]
+        },
+        {
+          "name": "sort_inventory",
+          "safety": "read",
+          "description": "Re-sort the inventory by any column (e.g. in-stock, total value, last restocked).",
+          "descriptionKey": "ui.agent.warehouse.workflows.sortInventory",
+          "uiActions": [
+            "data-table.sort_by"
+          ],
+          "stateReads": [
+            "data-table.sort"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "compact_actions",
+          "safety": "read",
+          "description": "Toggle the ColumnToggle settings-footer switch to compact the per-row action column.",
+          "descriptionKey": "ui.agent.warehouse.workflows.compactActions",
+          "uiActions": [
+            "switch.set_checked"
+          ],
+          "stateReads": [
+            "switch.checked"
+          ],
+          "apiActions": []
+        },
+        {
+          "name": "export_inventory",
+          "safety": "read",
+          "description": "Export the current (optionally filtered) inventory from the page-header table-tools cluster — CSV / Excel / PDF.",
+          "descriptionKey": "ui.agent.warehouse.workflows.exportInventory",
+          "uiActions": [],
+          "apiActions": [
+            "inventory.export"
+          ]
+        },
+        {
+          "name": "stock_in",
+          "safety": "write",
+          "description": "Record incoming stock for the selected item from its row action.",
+          "descriptionKey": "ui.agent.warehouse.workflows.stockIn",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "inventory.stockIn"
+          ]
+        },
+        {
+          "name": "stock_out",
+          "safety": "write",
+          "description": "Record outgoing stock for the selected item from its row action.",
+          "descriptionKey": "ui.agent.warehouse.workflows.stockOut",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "inventory.stockOut"
+          ]
+        },
+        {
+          "name": "edit_item",
+          "safety": "write",
+          "description": "Edit the selected inventory item (e.g. min-stock threshold, supplier) from its row action.",
+          "descriptionKey": "ui.agent.warehouse.workflows.editItem",
+          "uiActions": [
+            "data-table.get_selection"
+          ],
+          "stateReads": [
+            "data-table.selection"
+          ],
+          "apiActions": [
+            "inventory.update"
+          ]
+        },
+        {
+          "name": "import_fatturapa",
+          "safety": "write",
+          "description": "Open the FatturaPA XML import dialog, upload supplier e-invoice XML files, review the classified line preview, deselect any unwanted lines, and confirm to create articles and stock movements.",
+          "descriptionKey": "ui.agent.warehouse.workflows.importFatturapa",
+          "uiActions": [
+            "dialog.open",
+            "file-upload.clear"
+          ],
+          "stateReads": [
+            "dialog.isOpen",
+            "file-upload.files"
+          ],
+          "apiActions": [
+            "inventory.importFatturapa"
+          ]
+        }
+      ]
     }
   ]
 }