@alfadocs/ui-kit 0.70.0 → 0.71.0

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "0.70.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",
@@ -406,97 +514,6 @@
         }
       }
     },
-    {
-      "kind": "component",
-      "id": "ai-tools-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.aiToolsRail.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.aiToolsRail.agent.actions.open"
-        },
-        {
-          "name": "close",
-          "safety": "read",
-          "idempotent": true,
-          "description": "Collapse the rail to its strip (no active tool).",
-          "descriptionKey": "ui.aiToolsRail.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.aiToolsRail.agent.actions.selectTool"
-        }
-      ],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "value": "ai-tools-rail",
-          "description": "Marks the AiToolsRail 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": "alert",
@@ -2181,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)."
         }
       }
     },
@@ -2301,6 +2318,74 @@
         }
       }
     },
+    {
+      "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",
+          "idempotent": true,
+          "description": "Empty the field. Loses any typed value.",
+          "descriptionKey": "ui.agent.cityInput.actions.clear"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "city-input"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "clinical-note-card",
@@ -2645,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",
@@ -2687,14 +2816,105 @@
     },
     {
       "kind": "component",
-      "id": "copy-field",
+      "id": "control-room-rail",
       "capabilities": [
-        "copy"
+        "open",
+        "close",
+        "select_single"
       ],
       "state": [
         {
-          "name": "value",
-          "type": "string",
+          "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",
+      "capabilities": [
+        "copy"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
           "description": "The value displayed in the read-only field.",
           "descriptionKey": "ui.agent.copyField.state.value"
         },
@@ -2746,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",
@@ -3591,6 +3882,55 @@
         }
       }
     },
+    {
+      "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"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "entity-summary",
+          "description": "Marks the EntitySummary panel region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Required to address a specific summary panel from the agent."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "fetal-weight",
@@ -3612,6 +3952,59 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "field-array",
+      "capabilities": [
+        "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"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "field-array",
+          "description": "Marks the FieldArray fieldset."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "file-upload",
@@ -4031,33 +4424,297 @@
     },
     {
       "kind": "component",
-      "id": "icon-button",
-      "capabilities": [],
-      "state": [],
-      "actions": [],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "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": [],
-      "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`."
+      "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",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "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": [],
+      "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": "image-cropper",
+          "description": "Marks the ImageCropper wrapper."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
       "kind": "component",
       "id": "kbd",
       "capabilities": [],
@@ -4372,7 +5029,8 @@
         "open",
         "close",
         "select_single",
-        "dismiss"
+        "dismiss",
+        "navigate"
       ],
       "state": [
         {
@@ -4475,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": {
@@ -4618,56 +5290,118 @@
     },
     {
       "kind": "component",
-      "id": "navigation-menu",
+      "id": "nav-grid",
       "capabilities": [
-        "select_single",
-        "navigate",
-        "open",
-        "close"
+        "navigate"
       ],
       "state": [
         {
-          "name": "activeItem",
-          "type": "string | null",
-          "description": "Id of the currently-active top-level navigation item, or null when none is active.",
-          "descriptionKey": "ui.agent.navigationMenu.state.activeItem"
-        },
-        {
-          "name": "isOpen",
-          "type": "boolean",
-          "description": "Whether a dropdown / mega-menu panel is currently open.",
-          "descriptionKey": "ui.agent.navigationMenu.state.isOpen"
+          "name": "itemCount",
+          "type": "number",
+          "description": "Number of navigable tiles currently rendered in the grid.",
+          "descriptionKey": "ui.agent.navGrid.state.itemCount"
         }
       ],
       "actions": [
         {
-          "name": "select_item",
-          "safety": "read",
+          "name": "open_item",
+          "safety": "write",
           "argsType": "{ id: string }",
           "argsSchema": {
             "type": "object",
             "properties": {
               "id": {
                 "type": "string",
-                "description": "Stable opaque top-level item id (emitted as data-nav-id)."
+                "description": "Stable opaque tile id (emitted as data-nav-item-id on each tile)."
               }
             },
             "required": [
               "id"
             ]
           },
-          "idempotent": true,
+          "openWorld": false,
           "examples": [
             {
               "args": {
-                "id": "products"
+                "id": "billing"
               },
-              "note": "Open the \"products\" menu."
+              "note": "Open the \"billing\" settings section."
             }
           ],
-          "description": "Activate (open) the top-level item with the given id.",
-          "descriptionKey": "ui.agent.navigationMenu.actions.selectItem"
-        },
+          "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",
+      "capabilities": [
+        "select_single",
+        "navigate",
+        "open",
+        "close"
+      ],
+      "state": [
+        {
+          "name": "activeItem",
+          "type": "string | null",
+          "description": "Id of the currently-active top-level navigation item, or null when none is active.",
+          "descriptionKey": "ui.agent.navigationMenu.state.activeItem"
+        },
+        {
+          "name": "isOpen",
+          "type": "boolean",
+          "description": "Whether a dropdown / mega-menu panel is currently open.",
+          "descriptionKey": "ui.agent.navigationMenu.state.isOpen"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_item",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Stable opaque top-level item id (emitted as data-nav-id)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "products"
+              },
+              "note": "Open the \"products\" menu."
+            }
+          ],
+          "description": "Activate (open) the top-level item with the given id.",
+          "descriptionKey": "ui.agent.navigationMenu.actions.selectItem"
+        },
         {
           "name": "open",
           "safety": "read",
@@ -4713,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",
@@ -4741,7 +5582,8 @@
         "open",
         "close",
         "select_single",
-        "dismiss"
+        "dismiss",
+        "navigate"
       ],
       "state": [
         {
@@ -4864,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": {
@@ -5152,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",
@@ -5703,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",
@@ -5824,53 +6763,181 @@
     },
     {
       "kind": "component",
-      "id": "practice-results",
+      "id": "position-grid",
       "capabilities": [
-        "scroll",
-        "pick"
+        "select_single"
       ],
       "state": [
         {
-          "name": "variant",
+          "name": "value",
           "type": "string",
-          "description": "Active variant — one of `split-list-map`, `map-first`, `rich-cards`.",
-          "descriptionKey": "ui.agent.practiceResults.state.variant"
+          "description": "Currently selected position value (e.g. \"top-start\"), or empty string when none.",
+          "descriptionKey": "ui.agent.positionGrid.state.value"
         }
       ],
       "actions": [
         {
-          "name": "scroll_to_result",
-          "safety": "read",
-          "argsType": "{ id: string }",
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "id": {
-                "type": "string",
-                "description": "Stable result id (the data-result-id of the card)."
+              "value": {
+                "type": "string"
               }
             },
             "required": [
-              "id"
+              "value"
             ]
           },
           "idempotent": true,
           "examples": [
             {
               "args": {
-                "id": "practice-42"
+                "value": "center"
               },
-              "note": "Scroll to a specific result."
+              "note": "Selects the centre cell of the default 3×3 grid."
             }
           ],
-          "description": "Scroll the result card with the given id into the visible viewport.",
-          "descriptionKey": "ui.agent.practiceResults.actions.scrollToResult"
+          "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."
         },
-        {
-          "name": "focus_pin",
-          "safety": "read",
-          "argsType": "{ id: string }",
-          "argsSchema": {
+        "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": [
+        {
+          "name": "set_value",
+          "safety": "write",
+          "argsType": "{ value: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "value": "20121"
+              },
+              "note": "An Italian CAP."
+            }
+          ],
+          "description": "Replace the postal code value.",
+          "descriptionKey": "ui.agent.postalCodeInput.actions.setValue"
+        },
+        {
+          "name": "clear",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Empty the field. Loses any typed value.",
+          "descriptionKey": "ui.agent.postalCodeInput.actions.clear"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "postal-code-input"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "practice-results",
+      "capabilities": [
+        "scroll",
+        "pick"
+      ],
+      "state": [
+        {
+          "name": "variant",
+          "type": "string",
+          "description": "Active variant — one of `split-list-map`, `map-first`, `rich-cards`.",
+          "descriptionKey": "ui.agent.practiceResults.state.variant"
+        }
+      ],
+      "actions": [
+        {
+          "name": "scroll_to_result",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Stable result id (the data-result-id of the card)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "practice-42"
+              },
+              "note": "Scroll to a specific result."
+            }
+          ],
+          "description": "Scroll the result card with the given id into the visible viewport.",
+          "descriptionKey": "ui.agent.practiceResults.actions.scrollToResult"
+        },
+        {
+          "name": "focus_pin",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
             "type": "object",
             "properties": {
               "id": {
@@ -6138,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",
@@ -7956,6 +9094,173 @@
         }
       }
     },
+    {
+      "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": [
+        {
+          "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.tasksPanel.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.tasksPanel.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.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": "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 panel from the agent."
+        },
+        "item": {
+          "attr": "data-task-id",
+          "description": "Stable task id emitted on each rendered TaskCard inside the panel."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "text-area",
@@ -8390,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",
@@ -9357,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",
@@ -9645,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",
@@ -9880,7 +11534,7 @@
           "as": "topbar"
         },
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "rail"
         },
         {
@@ -9927,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"
@@ -10677,7 +12331,7 @@
       "id": "patient-ai-summary",
       "composes": [
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "toolRail"
         },
         {
@@ -10727,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": []
         },
@@ -10785,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"
@@ -11669,7 +13323,7 @@
           "as": "mainNav"
         },
         {
-          "component": "ai-tools-rail",
+          "component": "tool-rail",
           "as": "inboxRail",
           "entity": "notification"
         },
@@ -11762,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": []
         },
@@ -11952,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",
@@ -11987,38 +13677,34 @@
       ],
       "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",
-          "uiActions": [
-            "tabs.select_tab"
-          ],
-          "stateReads": [
-            "tabs.activeTab"
-          ],
+          "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_display_name",
+          "name": "edit_text_setting",
           "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": "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": [
             "text-input.set_value",
-            "text-input.clear"
+            "text-input.clear",
+            "iban-input.set_value"
           ],
           "stateReads": [
             "text-input.value",
-            "text-input.isEmpty"
+            "iban-input.value"
           ],
           "apiActions": []
         },
         {
-          "name": "toggle_email_digest",
+          "name": "toggle_setting",
           "safety": "write",
-          "description": "Turn the weekly email digest preference on or off.",
-          "descriptionKey": "ui.agent.settings.workflows.toggleEmailDigest",
+          "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"
@@ -12029,36 +13715,189 @@
           "apiActions": []
         },
         {
-          "name": "set_language",
+          "name": "choose_option",
           "safety": "write",
-          "description": "Choose the display language from the language select.",
-          "descriptionKey": "ui.agent.settings.workflows.setLanguage",
+          "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"
+            "select.close",
+            "radio-group.set_value"
           ],
           "stateReads": [
-            "select.value"
+            "select.value",
+            "radio-group.value"
           ],
           "apiActions": []
         },
         {
-          "name": "save_settings",
+          "name": "set_multi_choice",
           "safety": "write",
-          "description": "Persist the dirty profile form. Save is disabled until a field changes.",
-          "descriptionKey": "ui.agent.settings.workflows.saveSettings",
+          "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": "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.updateProfile"
+            "settings.updateSection"
+          ]
+        },
+        {
+          "name": "add_record",
+          "safety": "write",
+          "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",
+            "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": [
+            "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": "upload_practice_photo",
+          "safety": "write",
+          "description": "Upload, crop, or remove the practice / profile photo.",
+          "descriptionKey": "ui.agent.settings.workflows.uploadPracticePhoto",
+          "uiActions": [
+            "file-upload.remove_file",
+            "file-upload.clear",
+            "image-cropper.set_crop"
+          ],
+          "stateReads": [
+            "file-upload.files",
+            "image-cropper.crop"
+          ],
+          "apiActions": [
+            "settings.uploadImage"
           ]
         },
         {
-          "name": "discard_changes",
+          "name": "copy_secret",
           "safety": "read",
-          "description": "Cancel and reset the form to its last-saved baseline, re-disabling Save.",
-          "descriptionKey": "ui.agent.settings.workflows.discardChanges",
+          "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": [
+            "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": [
+            "apiKey.revoke",
+            "apiKey.regenerate"
+          ]
+        },
+        {
+          "name": "connect_online_payments",
+          "safety": "write",
+          "description": "Connect or disconnect the Stripe account used for online payments.",
+          "descriptionKey": "ui.agent.settings.workflows.connectOnlinePayments",
+          "uiActions": [
+            "connection-status.connect",
+            "connection-status.disconnect"
+          ],
+          "stateReads": [
+            "connection-status.status"
+          ],
+          "apiActions": [
+            "onlinePayment.connectStripe",
+            "onlinePayment.disconnectStripe"
+          ]
+        },
+        {
+          "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": [
+            "archive.delete"
+          ]
+        },
+        {
+          "name": "open_tool",
+          "safety": "read",
+          "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": []
         },
         {
@@ -12069,9 +13908,6 @@
           "uiActions": [
             "sidebar.toggle_collapsed"
           ],
-          "stateReads": [
-            "sidebar.isCollapsed"
-          ],
           "apiActions": []
         }
       ]