@alfadocs/ui-kit 0.73.0 → 0.75.0

package/dist/agent-catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "0.73.0",
+  "packageVersion": "0.75.0",
   "components": [
     {
       "kind": "component",
@@ -3048,6 +3048,156 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "data-table-tabs",
+      "capabilities": [
+        "select_single",
+        "view_change"
+      ],
+      "state": [
+        {
+          "name": "activeTabId",
+          "type": "string | null",
+          "description": "Id of the currently-active saved-filter tab.",
+          "descriptionKey": "ui.agent.dataTableTabs.state.activeTabId"
+        },
+        {
+          "name": "tabs",
+          "type": "Array<{ id, label }>",
+          "description": "The saved-filter tabs, in strip order (ids + labels).",
+          "descriptionKey": "ui.agent.dataTableTabs.state.tabs"
+        }
+      ],
+      "actions": [
+        {
+          "name": "select_tab",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Tab id to activate."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Activate a saved-filter tab: snapshots the outgoing tab, applies the incoming filter model to the table.",
+          "descriptionKey": "ui.agent.dataTableTabs.actions.selectTab"
+        },
+        {
+          "name": "get_tabs",
+          "safety": "read",
+          "returns": "Array<{ id: string, label: string }>",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "label": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "label"
+              ]
+            }
+          },
+          "idempotent": true,
+          "description": "Return the saved-filter tabs (ids + labels) in order.",
+          "descriptionKey": "ui.agent.dataTableTabs.actions.getTabs"
+        },
+        {
+          "name": "add_tab",
+          "safety": "write",
+          "argsType": "{ label?: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "label": {
+                "type": "string",
+                "description": "Display name for the new tab. Defaults to a numbered name."
+              }
+            },
+            "required": []
+          },
+          "returns": "string",
+          "returnsSchema": {
+            "type": "string"
+          },
+          "idempotent": false,
+          "description": "Add a new tab capturing the table's current filter model, and activate it. Returns the new tab id.",
+          "descriptionKey": "ui.agent.dataTableTabs.actions.addTab"
+        },
+        {
+          "name": "rename_tab",
+          "safety": "write",
+          "argsType": "{ id: string, label: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Tab id to rename."
+              },
+              "label": {
+                "type": "string",
+                "description": "New display name."
+              }
+            },
+            "required": [
+              "id",
+              "label"
+            ]
+          },
+          "idempotent": true,
+          "description": "Rename a saved-filter tab. No-op on locked tabs and empty labels.",
+          "descriptionKey": "ui.agent.dataTableTabs.actions.renameTab"
+        },
+        {
+          "name": "remove_tab",
+          "safety": "destructive",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Tab id to remove."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "description": "Remove a saved-filter tab (its saved filter is lost). No-op on locked tabs and the last remaining tab.",
+          "descriptionKey": "ui.agent.dataTableTabs.actions.removeTab"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "data-table-tabs"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id"
+        },
+        "item": {
+          "attr": "data-tab-id"
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "date-picker",
@@ -3444,6 +3594,47 @@
         }
       }
     },
+    {
+      "kind": "component",
+      "id": "document-preview",
+      "capabilities": [],
+      "state": [
+        {
+          "name": "kind",
+          "type": "'pdf' | 'image' | 'metadata' | 'empty'",
+          "description": "Which render branch is active: pdf, image, metadata (no inline preview), or empty (no document). Structural — never the document name.",
+          "descriptionKey": "ui.agent.documentPreview.state.kind"
+        }
+      ],
+      "actions": [
+        {
+          "name": "get_name",
+          "safety": "phi",
+          "returns": "string | undefined",
+          "returnsSchema": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "idempotent": true,
+          "description": "Read the display name of the previewed document. May identify a patient (PHI).",
+          "descriptionKey": "ui.agent.documentPreview.actions.getName"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "document-preview",
+          "description": "Marks the DocumentPreview region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
     {
       "kind": "component",
       "id": "document-scanner",
@@ -4237,125 +4428,404 @@
     },
     {
       "kind": "component",
-      "id": "file-upload",
+      "id": "file-manager",
       "capabilities": [
-        "dismiss"
+        "select_multiple",
+        "navigate",
+        "filter",
+        "open"
       ],
       "state": [
         {
-          "name": "files",
-          "type": "Array<{ id, name, size, status }>",
-          "description": "Files currently tracked by the uploader. Identifiers and metadata only — never file content.",
-          "descriptionKey": "ui.agent.fileUpload.state.files"
+          "name": "selection",
+          "type": "string[]",
+          "description": "Item ids of the currently-selected files and folders.",
+          "descriptionKey": "ui.agent.fileManager.state.selection"
+        },
+        {
+          "name": "currentFolder",
+          "type": "string | null",
+          "description": "Id of the folder being viewed, or null for the root.",
+          "descriptionKey": "ui.agent.fileManager.state.currentFolder"
+        },
+        {
+          "name": "typeFilter",
+          "type": "string[]",
+          "description": "Active document-type filter applied to the open folder (empty = no filter).",
+          "descriptionKey": "ui.agent.fileManager.state.typeFilter"
+        },
+        {
+          "name": "items",
+          "type": "Array<{ id, kind, parentId, size, updatedAt, documentType, signatureStatus }>",
+          "description": "Structural metadata for every item — ids, kinds, sizes, dates, document types, signature states. Names are PHI and never included; read them via get_item_names.",
+          "descriptionKey": "ui.agent.fileManager.state.items"
+        },
+        {
+          "name": "activeAction",
+          "type": "'none' | 'create-folder' | 'rename' | 'delete' | 'move'",
+          "description": "The single in-flight action dialog. Only one action can be active at a time.",
+          "descriptionKey": "ui.agent.fileManager.state.activeAction"
         }
       ],
       "actions": [
         {
-          "name": "remove_file",
-          "safety": "destructive",
-          "argsType": "{ id: string }",
+          "name": "select_items",
+          "safety": "read",
+          "argsType": "{ ids: string[] }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "id": {
-                "type": "string",
-                "description": "Id of the tracked file to remove (data-file-id)."
+              "ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Item ids to select (replaces the current selection)."
               }
             },
             "required": [
-              "id"
+              "ids"
             ]
           },
           "idempotent": true,
           "examples": [
             {
               "args": {
-                "id": "file-1"
+                "ids": [
+                  "doc-1",
+                  "doc-2"
+                ]
               },
-              "note": "Remove the first tracked file."
+              "note": "Select two items."
             }
           ],
-          "description": "Remove the file with the given id from the upload list.",
-          "descriptionKey": "ui.agent.fileUpload.actions.removeFile"
+          "description": "Replace the current selection with the given item ids.",
+          "descriptionKey": "ui.agent.fileManager.actions.selectItems"
         },
         {
-          "name": "clear",
-          "safety": "destructive",
+          "name": "clear_selection",
+          "safety": "read",
           "idempotent": true,
-          "description": "Remove all files from the upload list.",
-          "descriptionKey": "ui.agent.fileUpload.actions.clear"
-        }
-      ],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "value": "file-upload"
-        },
-        "instanceId": {
-          "attr": "data-component-id",
-          "sourceProp": "id",
-          "description": "Sourced from the id prop."
-        },
-        "item": {
-          "attr": "data-file-id",
-          "description": "Each tracked file emits its id as data-file-id."
-        }
-      }
-    },
-    {
-      "kind": "component",
-      "id": "finished-terminal",
-      "capabilities": [],
-      "state": [],
-      "actions": [],
-      "domHooks": {
-        "root": {
-          "attr": "data-component",
-          "value": "finished-terminal",
-          "description": "Marks the element as a kit FinishedTerminal."
-        }
-      }
-    },
-    {
-      "kind": "component",
-      "id": "fiscal-code-input",
-      "capabilities": [
-        "set_value"
-      ],
-      "state": [
-        {
-          "name": "value",
-          "type": "string",
-          "description": "Current codice fiscale, normalised (uppercased, 0–16 [A-Z0-9] characters).",
-          "descriptionKey": "ui.agent.fiscalCodeInput.state.value"
+          "description": "Deselect every item.",
+          "descriptionKey": "ui.agent.fileManager.actions.clearSelection"
         },
         {
-          "name": "isValid",
-          "type": "boolean",
-          "description": "Whether the value is 16 structurally-sound characters with a matching control character.",
-          "descriptionKey": "ui.agent.fiscalCodeInput.state.isValid"
-        }
-      ],
-      "actions": [
-        {
-          "name": "set_value",
-          "safety": "write",
-          "argsType": "{ value: string }",
+          "name": "navigate",
+          "safety": "read",
+          "argsType": "{ folderId: string | null }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "value": {
-                "type": "string"
+              "folderId": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Folder id to open, or null for the root."
               }
             },
             "required": [
-              "value"
+              "folderId"
             ]
           },
           "idempotent": true,
-          "examples": [
-            {
-              "args": {
+          "description": "Open the given folder (null for the root). Clears the current selection.",
+          "descriptionKey": "ui.agent.fileManager.actions.navigate"
+        },
+        {
+          "name": "set_type_filter",
+          "safety": "read",
+          "argsType": "{ documentTypes: string[] }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "documentTypes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Document-type values to keep. Empty array clears the filter."
+              }
+            },
+            "required": [
+              "documentTypes"
+            ]
+          },
+          "idempotent": true,
+          "description": "Filter the open folder to the given document types (empty clears the filter).",
+          "descriptionKey": "ui.agent.fileManager.actions.setTypeFilter"
+        },
+        {
+          "name": "open_item",
+          "safety": "read",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Item id — folders navigate, files open via the host."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "openWorld": true,
+          "description": "Open an item: folders navigate into the folder, files resolve through the host preview callback.",
+          "descriptionKey": "ui.agent.fileManager.actions.openItem"
+        },
+        {
+          "name": "list_items",
+          "safety": "read",
+          "argsType": "{ folderId?: string | null }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "folderId": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "Folder whose children to list (null = root). Omit for every item."
+              }
+            }
+          },
+          "returns": "Array<{ id, kind, parentId, size, updatedAt }>",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "file",
+                    "folder"
+                  ]
+                },
+                "parentId": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Parent folder id, null at the root."
+                },
+                "size": {
+                  "type": "number",
+                  "description": "Bytes — files only."
+                },
+                "updatedAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp."
+                },
+                "documentType": {
+                  "type": "string",
+                  "description": "Document-type category (non-identifying)."
+                },
+                "signatureStatus": {
+                  "enum": [
+                    "none",
+                    "pending",
+                    "signed"
+                  ],
+                  "description": "Signature workflow state."
+                }
+              },
+              "required": [
+                "id",
+                "kind",
+                "parentId"
+              ]
+            }
+          },
+          "idempotent": true,
+          "description": "List structural metadata (ids, kinds, sizes, dates — never names) for a folder or the whole tree.",
+          "descriptionKey": "ui.agent.fileManager.actions.listItems"
+        },
+        {
+          "name": "get_item_names",
+          "safety": "phi",
+          "argsType": "{ ids: string[] }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "ids": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Item ids whose display names to read."
+              }
+            },
+            "required": [
+              "ids"
+            ]
+          },
+          "returns": "Array<{ id: string; name: string }>",
+          "returnsSchema": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "name"
+              ]
+            }
+          },
+          "idempotent": true,
+          "description": "Read the display names for the given item ids. Names may identify patients (PHI).",
+          "descriptionKey": "ui.agent.fileManager.actions.getItemNames"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "file-manager",
+          "description": "Marks the FileManager region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-item-id",
+          "description": "Grid cards and folder-tree nodes carry the item id as data-item-id (ids only — never names). List-view rows are AG Grid rows inside the composed DataTable and carry its native row-id attribute keyed to the same ids."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "file-upload",
+      "capabilities": [
+        "dismiss"
+      ],
+      "state": [
+        {
+          "name": "files",
+          "type": "Array<{ id, name, size, status }>",
+          "description": "Files currently tracked by the uploader. Identifiers and metadata only — never file content.",
+          "descriptionKey": "ui.agent.fileUpload.state.files"
+        }
+      ],
+      "actions": [
+        {
+          "name": "remove_file",
+          "safety": "destructive",
+          "argsType": "{ id: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Id of the tracked file to remove (data-file-id)."
+              }
+            },
+            "required": [
+              "id"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "id": "file-1"
+              },
+              "note": "Remove the first tracked file."
+            }
+          ],
+          "description": "Remove the file with the given id from the upload list.",
+          "descriptionKey": "ui.agent.fileUpload.actions.removeFile"
+        },
+        {
+          "name": "clear",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Remove all files from the upload list.",
+          "descriptionKey": "ui.agent.fileUpload.actions.clear"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "file-upload"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-file-id",
+          "description": "Each tracked file emits its id as data-file-id."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "finished-terminal",
+      "capabilities": [],
+      "state": [],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "finished-terminal",
+          "description": "Marks the element as a kit FinishedTerminal."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "fiscal-code-input",
+      "capabilities": [
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "value",
+          "type": "string",
+          "description": "Current codice fiscale, normalised (uppercased, 0–16 [A-Z0-9] characters).",
+          "descriptionKey": "ui.agent.fiscalCodeInput.state.value"
+        },
+        {
+          "name": "isValid",
+          "type": "boolean",
+          "description": "Whether the value is 16 structurally-sound characters with a matching control character.",
+          "descriptionKey": "ui.agent.fiscalCodeInput.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": "RSSMRA85T10A562S"
               },
               "note": "A complete, structurally-sound codice fiscale."
@@ -7091,187 +7561,771 @@
       "state": [],
       "actions": [
         {
-          "name": "submit",
-          "safety": "destructive",
-          "returns": "Promise<void>",
-          "openWorld": true,
-          "errors": [
-            "Validation failed (incomplete or invalid card details).",
-            "Payment was declined by the processor.",
-            "Network or processor error during the charge."
-          ],
-          "description": "Submit the payment. Charges the configured payment method — irreversible.",
-          "descriptionKey": "ui.agent.paymentForm.actions.submit"
+          "name": "submit",
+          "safety": "destructive",
+          "returns": "Promise<void>",
+          "openWorld": true,
+          "errors": [
+            "Validation failed (incomplete or invalid card details).",
+            "Payment was declined by the processor.",
+            "Network or processor error during the charge."
+          ],
+          "description": "Submit the payment. Charges the configured payment method — irreversible.",
+          "descriptionKey": "ui.agent.paymentForm.actions.submit"
+        },
+        {
+          "name": "reset",
+          "safety": "destructive",
+          "idempotent": true,
+          "description": "Reset the form to its initial state. Loses any in-progress input.",
+          "descriptionKey": "ui.agent.paymentForm.actions.reset"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "payment-form"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "payment-request-card",
+      "capabilities": [],
+      "state": [
+        {
+          "name": "status",
+          "type": "'new' | 'authorization_requested' | 'authorized' | 'paid' | 'failed' | 'cancelled'",
+          "description": "Current lifecycle status of the payment request. Structural state only.",
+          "descriptionKey": "ui.agent.paymentRequestCard.state.status"
+        }
+      ],
+      "actions": [],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "payment-request-card",
+          "description": "Marks the PaymentRequestCard root region."
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop. Addresses a specific request card."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "pdf-viewer",
+      "capabilities": [
+        "paginate",
+        "set_value",
+        "filter"
+      ],
+      "state": [],
+      "actions": [
+        {
+          "name": "go_to_page",
+          "safety": "read",
+          "argsType": "{ page: number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "page": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "1-indexed target page."
+              }
+            },
+            "required": [
+              "page"
+            ]
+          },
+          "idempotent": true,
+          "errors": [
+            "Page is out of range for the loaded document."
+          ],
+          "examples": [
+            {
+              "args": {
+                "page": 2
+              }
+            }
+          ],
+          "description": "Navigate to a specific 1-indexed page.",
+          "descriptionKey": "ui.agent.pdfViewer.actions.goToPage"
+        },
+        {
+          "name": "set_zoom",
+          "safety": "read",
+          "argsType": "{ zoom: PDFZoomPreset }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "zoom": {
+                "description": "Either a named preset ('fit-width' | 'fit-page' | 'actual-size') or a numeric scale factor (e.g. 1.5).",
+                "oneOf": [
+                  {
+                    "enum": [
+                      "fit-width",
+                      "fit-page",
+                      "actual-size"
+                    ]
+                  },
+                  {
+                    "type": "number",
+                    "exclusiveMinimum": 0
+                  }
+                ]
+              }
+            },
+            "required": [
+              "zoom"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "zoom": "fit-width"
+              }
+            },
+            {
+              "args": {
+                "zoom": 1.5
+              }
+            }
+          ],
+          "description": "Apply a zoom preset or numeric scale factor.",
+          "descriptionKey": "ui.agent.pdfViewer.actions.setZoom"
+        },
+        {
+          "name": "search",
+          "safety": "read",
+          "argsType": "{ query: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "Text to find and highlight in the loaded document."
+              }
+            },
+            "required": [
+              "query"
+            ]
+          },
+          "idempotent": true,
+          "examples": [
+            {
+              "args": {
+                "query": "consent"
+              }
+            }
+          ],
+          "description": "Search the document for the given query and highlight matches.",
+          "descriptionKey": "ui.agent.pdfViewer.actions.search"
+        },
+        {
+          "name": "print",
+          "safety": "read",
+          "description": "Open the browser print dialog for the document.",
+          "descriptionKey": "ui.agent.pdfViewer.actions.print"
+        }
+      ],
+      "domHooks": {
+        "root": {
+          "attr": "data-component",
+          "value": "pdf-viewer"
+        },
+        "instanceId": {
+          "attr": "data-component-id",
+          "sourceProp": "id",
+          "description": "Sourced from the id prop."
+        }
+      }
+    },
+    {
+      "kind": "component",
+      "id": "periodontal-chart",
+      "capabilities": [
+        "pick",
+        "set_value",
+        "edit_inline"
+      ],
+      "state": [
+        {
+          "name": "indices",
+          "type": "object",
+          "description": "Derived whole-mouth indices: mean probing depth, mean attachment level, plaque %, bleeding %, scored-site and deep-pocket counts. Aggregates only — no per-site or patient data.",
+          "descriptionKey": "ui.agent.periodontalChart.state.indices"
+        },
+        {
+          "name": "missingTeeth",
+          "type": "string[]",
+          "description": "FDI ids of every tooth flagged as missing.",
+          "descriptionKey": "ui.agent.periodontalChart.state.missingTeeth"
+        },
+        {
+          "name": "chartedTeeth",
+          "type": "string[]",
+          "description": "FDI ids of teeth carrying at least one probing reading or flag. Identifiers only — never patient identity or the free-text note.",
+          "descriptionKey": "ui.agent.periodontalChart.state.chartedTeeth"
+        }
+      ],
+      "actions": [
+        {
+          "name": "focus_site",
+          "safety": "read",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; field: \"pocketDepthMm\" | \"recessionMm\" }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "site": {
+                "enum": [
+                  "db",
+                  "b",
+                  "mb",
+                  "dl",
+                  "l",
+                  "ml"
+                ],
+                "description": "Probing site: (m/d)b = mesio-/disto-/mid buccal, (m/d)l = mesio-/disto-/mid lingual."
+              },
+              "field": {
+                "enum": [
+                  "pocketDepthMm",
+                  "recessionMm"
+                ]
+              }
+            },
+            "required": [
+              "fdi",
+              "site",
+              "field"
+            ]
+          },
+          "idempotent": true,
+          "description": "Move focus to a specific probing-measurement input.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.focusSite"
+        },
+        {
+          "name": "get_tooth",
+          "safety": "read",
+          "argsType": "{ fdi: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              }
+            },
+            "required": [
+              "fdi"
+            ]
+          },
+          "returns": "object | null",
+          "returnsSchema": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "idempotent": true,
+          "description": "Read one tooth’s structural readings (sites, flags, mobility, furcation). The free-text note is never returned.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.getTooth"
+        },
+        {
+          "name": "get_indices",
+          "safety": "read",
+          "argsType": "{}",
+          "argsSchema": {
+            "type": "object",
+            "properties": {}
+          },
+          "returns": "PeriodontalIndices",
+          "returnsSchema": {
+            "type": "object",
+            "properties": {
+              "meanPocketDepthMm": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "meanAttachmentLevelMm": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "plaquePercent": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "bleedingPercent": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "scoredSiteCount": {
+                "type": "number"
+              },
+              "deepPocketCount": {
+                "type": "number"
+              }
+            }
+          },
+          "idempotent": true,
+          "description": "Read the derived whole-mouth summary indices.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.getIndices"
+        },
+        {
+          "name": "set_depth",
+          "safety": "write",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; mm: number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "site": {
+                "enum": [
+                  "db",
+                  "b",
+                  "mb",
+                  "dl",
+                  "l",
+                  "ml"
+                ],
+                "description": "Probing site: (m/d)b = mesio-/disto-/mid buccal, (m/d)l = mesio-/disto-/mid lingual."
+              },
+              "mm": {
+                "type": "integer",
+                "description": "Whole millimetres — perio probing is recorded in integer mm."
+              }
+            },
+            "required": [
+              "fdi",
+              "site",
+              "mm"
+            ]
+          },
+          "idempotent": true,
+          "description": "Record the probing pocket depth (mm) at a site.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.setDepth"
+        },
+        {
+          "name": "set_recession",
+          "safety": "write",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; mm: number }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "site": {
+                "enum": [
+                  "db",
+                  "b",
+                  "mb",
+                  "dl",
+                  "l",
+                  "ml"
+                ],
+                "description": "Probing site: (m/d)b = mesio-/disto-/mid buccal, (m/d)l = mesio-/disto-/mid lingual."
+              },
+              "mm": {
+                "type": "integer",
+                "description": "Whole millimetres — perio probing is recorded in integer mm."
+              }
+            },
+            "required": [
+              "fdi",
+              "site",
+              "mm"
+            ]
+          },
+          "idempotent": true,
+          "description": "Record the gingival recession (mm) at a site.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.setRecession"
+        },
+        {
+          "name": "toggle_bleeding",
+          "safety": "write",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; value: boolean }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "site": {
+                "enum": [
+                  "db",
+                  "b",
+                  "mb",
+                  "dl",
+                  "l",
+                  "ml"
+                ],
+                "description": "Probing site: (m/d)b = mesio-/disto-/mid buccal, (m/d)l = mesio-/disto-/mid lingual."
+              },
+              "value": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "fdi",
+              "site",
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set bleeding on probing at a site.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.toggleBleeding"
+        },
+        {
+          "name": "toggle_plaque",
+          "safety": "write",
+          "argsType": "{ fdi: string; site: PeriodontalSiteId; value: boolean }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "site": {
+                "enum": [
+                  "db",
+                  "b",
+                  "mb",
+                  "dl",
+                  "l",
+                  "ml"
+                ],
+                "description": "Probing site: (m/d)b = mesio-/disto-/mid buccal, (m/d)l = mesio-/disto-/mid lingual."
+              },
+              "value": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "fdi",
+              "site",
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set plaque presence at a site.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.togglePlaque"
+        },
+        {
+          "name": "set_mobility",
+          "safety": "write",
+          "argsType": "{ fdi: string; grade: 0 | 1 | 2 | 3 }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "grade": {
+                "enum": [
+                  0,
+                  1,
+                  2,
+                  3
+                ]
+              }
+            },
+            "required": [
+              "fdi",
+              "grade"
+            ]
+          },
+          "idempotent": true,
+          "description": "Set a tooth’s Miller mobility grade (0–3).",
+          "descriptionKey": "ui.agent.periodontalChart.actions.setMobility"
+        },
+        {
+          "name": "set_missing",
+          "safety": "write",
+          "argsType": "{ fdi: string; value: boolean }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              },
+              "value": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "fdi",
+              "value"
+            ]
+          },
+          "idempotent": true,
+          "description": "Flag a tooth present or absent.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.setMissing"
         },
         {
-          "name": "reset",
+          "name": "clear_tooth",
           "safety": "destructive",
+          "argsType": "{ fdi: string }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "fdi": {
+                "type": "string",
+                "description": "FDI tooth id ('11'–'48' permanent, '51'–'85' primary)."
+              }
+            },
+            "required": [
+              "fdi"
+            ]
+          },
           "idempotent": true,
-          "description": "Reset the form to its initial state. Loses any in-progress input.",
-          "descriptionKey": "ui.agent.paymentForm.actions.reset"
+          "description": "Clear every reading from a tooth.",
+          "descriptionKey": "ui.agent.periodontalChart.actions.clearTooth"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "payment-form"
+          "value": "periodontal-chart",
+          "description": "Marks the PeriodontalChart root group."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
           "description": "Sourced from the id prop."
+        },
+        "item": {
+          "attr": "data-fdi",
+          "description": "Each tooth column header carries its FDI id as `data-fdi`. Every measurement input also carries `data-fdi` + `data-site` + `data-field`. The root `data-mode` exposes interactive vs display."
         }
       }
     },
     {
       "kind": "component",
-      "id": "payment-request-card",
+      "id": "periodontal-chart-card",
       "capabilities": [],
       "state": [
         {
-          "name": "status",
-          "type": "'new' | 'authorization_requested' | 'authorized' | 'paid' | 'failed' | 'cancelled'",
-          "description": "Current lifecycle status of the payment request. Structural state only.",
-          "descriptionKey": "ui.agent.paymentRequestCard.state.status"
+          "name": "toothIds",
+          "type": "string[]",
+          "description": "FDI ids of the teeth currently charted. Tooth identifiers only — no patient identity.",
+          "descriptionKey": "ui.agent.periodontalChartCard.state.toothIds"
+        },
+        {
+          "name": "siteCount",
+          "type": "number",
+          "description": "Total number of probing sites rendered.",
+          "descriptionKey": "ui.agent.periodontalChartCard.state.siteCount"
+        },
+        {
+          "name": "deepPocketCount",
+          "type": "number",
+          "description": "Number of sites with a probing depth at or above the 6mm severe threshold.",
+          "descriptionKey": "ui.agent.periodontalChartCard.state.deepPocketCount"
         }
       ],
       "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "payment-request-card",
-          "description": "Marks the PaymentRequestCard root region."
+          "value": "periodontal-chart-card",
+          "description": "Marks the PeriodontalChartCard root region."
         },
         "instanceId": {
           "attr": "data-component-id",
           "sourceProp": "id",
-          "description": "Sourced from the id prop. Addresses a specific request card."
+          "description": "Sourced from the id prop."
         }
       }
     },
     {
       "kind": "component",
-      "id": "pdf-viewer",
+      "id": "periodontal-diagnosis",
       "capabilities": [
-        "paginate",
-        "set_value",
-        "filter"
+        "set_value"
+      ],
+      "state": [
+        {
+          "name": "diagnosis",
+          "type": "object",
+          "description": "Recorded stage (1–4), grade (A–C), extent, and ticked contributing-factor ids. The free-text note is never included.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.state.diagnosis"
+        },
+        {
+          "name": "summary",
+          "type": "string",
+          "description": "The composed, localised diagnosis sentence (e.g. \"Periodontitis — Stage III · Grade B · generalised\").",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.state.summary"
+        },
+        {
+          "name": "complete",
+          "type": "boolean",
+          "description": "True once both a stage and a grade are recorded.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.state.complete"
+        }
       ],
-      "state": [],
       "actions": [
         {
-          "name": "go_to_page",
+          "name": "get_diagnosis",
           "safety": "read",
-          "argsType": "{ page: number }",
+          "argsType": "{}",
+          "argsSchema": {
+            "type": "object",
+            "properties": {}
+          },
+          "returns": "object",
+          "returnsSchema": {
+            "type": "object"
+          },
+          "idempotent": true,
+          "description": "Read the recorded stage / grade / extent / factors. The note is never returned.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.getDiagnosis"
+        },
+        {
+          "name": "set_stage",
+          "safety": "write",
+          "argsType": "{ stage: 1 | 2 | 3 | 4 }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "page": {
-                "type": "integer",
-                "minimum": 1,
-                "description": "1-indexed target page."
+              "stage": {
+                "enum": [
+                  1,
+                  2,
+                  3,
+                  4
+                ],
+                "description": "Periodontitis stage I–IV, as the integers 1–4."
               }
             },
             "required": [
-              "page"
+              "stage"
             ]
           },
           "idempotent": true,
-          "errors": [
-            "Page is out of range for the loaded document."
-          ],
-          "examples": [
-            {
-              "args": {
-                "page": 2
-              }
-            }
-          ],
-          "description": "Navigate to a specific 1-indexed page.",
-          "descriptionKey": "ui.agent.pdfViewer.actions.goToPage"
+          "description": "Record the periodontitis stage (I–IV).",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.setStage"
         },
         {
-          "name": "set_zoom",
-          "safety": "read",
-          "argsType": "{ zoom: PDFZoomPreset }",
+          "name": "set_grade",
+          "safety": "write",
+          "argsType": "{ grade: 'A' | 'B' | 'C' }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "zoom": {
-                "description": "Either a named preset ('fit-width' | 'fit-page' | 'actual-size') or a numeric scale factor (e.g. 1.5).",
-                "oneOf": [
-                  {
-                    "enum": [
-                      "fit-width",
-                      "fit-page",
-                      "actual-size"
-                    ]
-                  },
-                  {
-                    "type": "number",
-                    "exclusiveMinimum": 0
-                  }
-                ]
+              "grade": {
+                "enum": [
+                  "A",
+                  "B",
+                  "C"
+                ],
+                "description": "Periodontitis grade A–C (rate of progression)."
               }
             },
             "required": [
-              "zoom"
+              "grade"
             ]
           },
           "idempotent": true,
-          "examples": [
-            {
-              "args": {
-                "zoom": "fit-width"
+          "description": "Record the periodontitis grade (A–C).",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.setGrade"
+        },
+        {
+          "name": "set_extent",
+          "safety": "write",
+          "argsType": "{ extent: 'localised' | 'generalised' | 'molarIncisor' }",
+          "argsSchema": {
+            "type": "object",
+            "properties": {
+              "extent": {
+                "enum": [
+                  "localised",
+                  "generalised",
+                  "molarIncisor"
+                ],
+                "description": "Distribution: localised (<30%), generalised (≥30%), or molar-incisor."
               }
             },
-            {
-              "args": {
-                "zoom": 1.5
-              }
-            }
-          ],
-          "description": "Apply a zoom preset or numeric scale factor.",
-          "descriptionKey": "ui.agent.pdfViewer.actions.setZoom"
+            "required": [
+              "extent"
+            ]
+          },
+          "idempotent": true,
+          "description": "Record the distribution / extent.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.setExtent"
         },
         {
-          "name": "search",
-          "safety": "read",
-          "argsType": "{ query: string }",
+          "name": "toggle_factor",
+          "safety": "write",
+          "argsType": "{ id: string; value: boolean }",
           "argsSchema": {
             "type": "object",
             "properties": {
-              "query": {
+              "id": {
                 "type": "string",
-                "description": "Text to find and highlight in the loaded document."
+                "description": "Contributing-factor id."
+              },
+              "value": {
+                "type": "boolean"
               }
             },
             "required": [
-              "query"
+              "id",
+              "value"
             ]
           },
           "idempotent": true,
-          "examples": [
-            {
-              "args": {
-                "query": "consent"
-              }
-            }
-          ],
-          "description": "Search the document for the given query and highlight matches.",
-          "descriptionKey": "ui.agent.pdfViewer.actions.search"
+          "description": "Tick or clear a contributing factor.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.toggleFactor"
         },
         {
-          "name": "print",
-          "safety": "read",
-          "description": "Open the browser print dialog for the document.",
-          "descriptionKey": "ui.agent.pdfViewer.actions.print"
+          "name": "clear_diagnosis",
+          "safety": "destructive",
+          "argsType": "{}",
+          "argsSchema": {
+            "type": "object",
+            "properties": {}
+          },
+          "idempotent": true,
+          "description": "Reset the whole diagnosis to empty.",
+          "descriptionKey": "ui.agent.periodontalDiagnosis.actions.clearDiagnosis"
         }
       ],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "pdf-viewer"
+          "value": "periodontal-diagnosis",
+          "description": "Marks the PeriodontalDiagnosis root group."
         },
         "instanceId": {
           "attr": "data-component-id",
@@ -7282,34 +8336,28 @@
     },
     {
       "kind": "component",
-      "id": "periodontal-chart-card",
+      "id": "periodontal-risk-chart",
       "capabilities": [],
       "state": [
         {
-          "name": "toothIds",
-          "type": "string[]",
-          "description": "FDI ids of the teeth currently charted. Tooth identifiers only — no patient identity.",
-          "descriptionKey": "ui.agent.periodontalChartCard.state.toothIds"
-        },
-        {
-          "name": "siteCount",
-          "type": "number",
-          "description": "Total number of probing sites rendered.",
-          "descriptionKey": "ui.agent.periodontalChartCard.state.siteCount"
+          "name": "overall",
+          "type": "string",
+          "description": "Overall periodontal risk verdict — \"low\" | \"moderate\" | \"high\". Aggregate only.",
+          "descriptionKey": "ui.agent.periodontalRiskChart.state.overall"
         },
         {
-          "name": "deepPocketCount",
-          "type": "number",
-          "description": "Number of sites with a probing depth at or above the 6mm severe threshold.",
-          "descriptionKey": "ui.agent.periodontalChartCard.state.deepPocketCount"
+          "name": "factorLevels",
+          "type": "object",
+          "description": "Per-factor risk levels keyed by factor (bleeding, pockets, toothLoss, boneLossAge, smoking, systemic) — each \"low\" | \"moderate\" | \"high\". No raw values.",
+          "descriptionKey": "ui.agent.periodontalRiskChart.state.factorLevels"
         }
       ],
       "actions": [],
       "domHooks": {
         "root": {
           "attr": "data-component",
-          "value": "periodontal-chart-card",
-          "description": "Marks the PeriodontalChartCard root region."
+          "value": "periodontal-risk-chart",
+          "description": "Marks the PeriodontalRiskChart root region."
         },
         "instanceId": {
           "attr": "data-component-id",
@@ -14848,15 +15896,18 @@
         },
         {
           "component": "select",
-          "as": "patientSigner"
+          "as": "signerPerson",
+          "entity": "signer"
         },
         {
-          "component": "radio-group",
-          "as": "deliveryChannel"
+          "component": "checkbox",
+          "as": "signerChannel",
+          "entity": "signer"
         },
         {
           "component": "switch",
-          "as": "otpWaiver"
+          "as": "otpWaiver",
+          "entity": "signer"
         },
         {
           "component": "alert",
@@ -14864,15 +15915,33 @@
         },
         {
           "component": "alert",
-          "as": "otpWarning"
+          "as": "otpWarning",
+          "entity": "signer"
+        },
+        {
+          "component": "alert",
+          "as": "submissionError"
         },
         {
           "component": "button",
           "as": "assignToMe"
         },
+        {
+          "component": "button",
+          "as": "addSigner"
+        },
+        {
+          "component": "icon-button",
+          "as": "removeSigner",
+          "entity": "signer"
+        },
         {
           "component": "button",
           "as": "requestSignature"
+        },
+        {
+          "component": "button",
+          "as": "close"
         }
       ],
       "workflows": [
@@ -14890,10 +15959,10 @@
           "apiActions": []
         },
         {
-          "name": "choose_patient_signer",
+          "name": "manage_signer_roster",
           "safety": "write",
-          "description": "Pick who signs on the patient side: the patient, a legal guardian, or a third-party signer.",
-          "descriptionKey": "ui.agent.signatureRequest.workflows.choosePatientSigner",
+          "description": "Build the patient-side signer roster: pick who signs in each row (the patient or their configured signee, e.g. a legal guardian), add a second signer up to the cap, or remove a row. People already on the roster are excluded from the other rows.",
+          "descriptionKey": "ui.agent.signatureRequest.workflows.manageSignerRoster",
           "uiActions": [
             "select.set_value"
           ],
@@ -14905,20 +15974,20 @@
         {
           "name": "choose_delivery_channel",
           "safety": "write",
-          "description": "Choose how the signature request reaches the patient: SMS, e-mail, WhatsApp, or signing on this device.",
+          "description": "Choose how each signer's request is delivered via the per-row channel checkboxes (mutually exclusive — checking one channel unchecks the others): SMS, e-mail, WhatsApp, or signing on this device. On-device signers sign sequentially in roster order.",
           "descriptionKey": "ui.agent.signatureRequest.workflows.chooseDeliveryChannel",
           "uiActions": [
-            "radio-group.set_value"
+            "checkbox.set_checked"
           ],
           "stateReads": [
-            "radio-group.value"
+            "checkbox.checked"
           ],
           "apiActions": []
         },
         {
           "name": "waive_otp",
           "safety": "write",
-          "description": "Toggle the on-device OTP waiver. Waiving OTP lowers the evidentiary value of the signature; the pattern surfaces a warning alert while waived.",
+          "description": "Toggle a signer's on-device OTP waiver. Waiving OTP lowers the evidentiary value of that signature; the pattern surfaces a warning alert while waived.",
           "descriptionKey": "ui.agent.signatureRequest.workflows.waiveOtp",
           "uiActions": [
             "switch.toggle",
@@ -14932,14 +16001,14 @@
         {
           "name": "request_signature",
           "safety": "phi",
-          "description": "Send the signature request. Notifies the chosen signers over the selected channel and closes the modal.",
+          "description": "Send the signature request. Notifies every roster signer over their selected channel and hands the submission to the host.",
           "descriptionKey": "ui.agent.signatureRequest.workflows.requestSignature",
           "uiActions": [
             "dialog.close"
           ],
           "stateReads": [
             "select.value",
-            "radio-group.value",
+            "checkbox.checked",
             "switch.checked",
             "dialog.isOpen"
           ],
@@ -14950,7 +16019,7 @@
         {
           "name": "dismiss",
           "safety": "destructive",
-          "description": "Close the modal without sending a signature request. Discards the in-progress signer, channel, and OTP choices.",
+          "description": "Close the modal without sending a signature request. Discards the in-progress operator, roster, channel, and OTP choices.",
           "descriptionKey": "ui.agent.signatureRequest.workflows.dismiss",
           "uiActions": [
             "dialog.dismiss"