@johpaz/hive-agents 0.0.35 → 0.0.37

package/packages/skills/src/bundled/canvas/a2ui_dashboard/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: a2ui_dashboard
+description: "Create real-time interactive dashboards using A2UI v0.9 protocol with dynamic data binding and live updates"
+version: 1.0.0
+author: Hive Team
+icon: "📊"
+category: canvas
+permissions:
+  - canvas_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "dashboard A2UI"
+  - "panel de control A2UI"
+  - "A2UI dashboard"
+  - "mostrar métricas A2UI"
+  - "A2UI metrics"
+  - "dashboard interactivo A2UI"
+  - "interactive dashboard"
+  - "A2UI dashboard en tiempo real"
+  - "real-time dashboard A2UI"
+  - "mostrar datos A2UI"
+  - "visualizar datos con A2UI"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface for the dashboard. Set theme with primaryColor matching project branding."
+    params:
+      surfaceId: "Descriptive ID (e.g. 'project_dashboard', 'metrics_dashboard')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#10B981', agentDisplayName: 'Dashboard' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Build dashboard layout using Row, Column, Card, and Text components. Use weight for proportional sizing."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions for dashboard layout"
+    output: dashboard_layout
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Populate dashboard with initial data using JSON Pointer paths. All dynamic values should use path bindings."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/"
+      value: "Full data model object with all metric values"
+    output: data_populated
+
+  - step: 4
+    action: a2ui_update_data_model
+    instruction: "Update specific data model paths to refresh dashboard metrics in real-time."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/metrics/completionRate"
+      value: "Updated value"
+    output: metrics_updated
+
+  - step: 5
+    action: a2ui_delete_surface
+    instruction: "Delete the dashboard surface when no longer needed."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use Row with weight for side-by-side metrics (e.g. weight: 1 vs weight: 3)"
+  - "Use Card to group related metrics together"
+  - "Use Text with usageHint: 'h2' for section titles, 'h1' for dashboard title"
+  - "Use Text with usageHint: 'caption' for labels"
+  - "Use data binding { path: '/metrics/name' } for all dynamic values"
+  - "Update metrics with a2ui_update_data_model using specific JSON Pointer paths"
+  - "Use a2ui_update_data_model with path: '/' to replace entire data model if needed"
+  - "Delete surfaces with a2ui_delete_surface when dashboard is no longer needed"
+  - "For static dashboards prefer canvas_render with chart type; use A2UI for interactive/live dashboards"
+
+output_format:
+  structure: a2ui_dashboard
+  sections:
+    - "surface_creation"
+    - "dashboard_layout"
+    - "data_model"
+    - "live_updates"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "mostrá el dashboard del proyecto"
+    expected_behavior: "a2ui_create_surface(surfaceId:'project_dash', theme:{primaryColor:'#10B981'}) → a2ui_update_components with Row[Column[Card[metrics]],Column[tasks]] → a2ui_update_data_model(path:'/', value:{metrics:{...}})"
+
+  - user_input: "actualizá las métricas del dashboard"
+    expected_behavior: "a2ui_update_data_model(surfaceId:'project_dash', path:'/metrics/completionRate', value:75)"
+
+  - user_input: "show a real-time dashboard with server metrics"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Cards for each metric → a2ui_update_data_model → periodic updates with a2ui_update_data_model"
+---
+
+# A2UI Dashboard Skill
+
+## Cuándo se Activa
+
+Para crear dashboards interactivos en tiempo real usando A2UI v0.9. Usar cuando se necesita:
+- Métricas que se actualizan dinámicamente
+- Dashboards con data binding
+- Paneles con Cards, Rows, Columns
+- Visualización de datos que cambia en tiempo real
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía componentes | Para layout del dashboard |
+| `a2ui_update_data_model` | Actualiza datos | Para métricas dinámicas |
+| `a2ui_delete_surface` | Elimina la superficie | Al cerrar dashboard |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // datos iniciales
+4. [actualizar métricas con a2ui_update_data_model según necesidad]
+5. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Patrón de Dashboard Típico
+
+```json
+[
+  {"id": "root", "component": "Column", "children": ["title", "metrics_row", "tasks_list"]},
+  {"id": "title", "component": "Text", "text": "Dashboard de Proyecto", "variant": "h1"},
+
+  {"id": "metrics_row", "component": "Row", "children": ["card1", "card2", "card3"]},
+  {"id": "card1", "component": "Card", "child": "card1_content", "weight": 1},
+  {"id": "card1_content", "component": "Column", "children": ["card1_label", "card1_value"]},
+  {"id": "card1_label", "component": "Text", "text": "Completado", "variant": "caption"},
+  {"id": "card1_value", "component": "Text", "text": {"path": "/metrics/completionRate"}, "variant": "h2"},
+
+  {"id": "tasks_list", "component": "List", "children": {"path": "/tasks", "componentId": "task_template"}},
+  {"id": "task_template", "component": "Card", "child": "task_content"},
+  {"id": "task_content", "component": "Column", "children": ["task_name", "task_status"]},
+  {"id": "task_name", "component": "Text", "text": {"path": "/name"}},
+  {"id": "task_status", "component": "Text", "text": {"path": "/status"}, "variant": "caption"}
+]
+```
+
+## Actualización en Tiempo Real
+
+Para actualizar métricas específicas sin reenviar componentes:
+```json
+a2ui_update_data_model(surfaceId: "dash", path: "/metrics/completionRate", value: 85)
+a2ui_update_data_model(surfaceId: "dash", path: "/metrics/totalTasks", value: 24)
+```
+
+Para reemplazar todo el data model:
+```json
+a2ui_update_data_model(surfaceId: "dash", path: "/", value: {metrics: {completionRate: 90, totalTasks: 25}, tasks: [...]})
+```
+
+## Mejores Prácticas
+
+- Usar `weight` en Row/Column para proporciones (weight:1 vs weight:3 = 25% vs 75%)
+- Agrupar métricas en Cards para separación visual
+- Usar `usageHint: "caption"` para labels, `"h1"/"h2"` para valores
+- Bind todos los valores dinámicos con `{ path: "/..." }`
+- Actualizar métricas con `a2ui_update_data_model` path específico
+- Eliminar surfaces al terminar para evitar memory leaks

package/packages/skills/src/bundled/canvas/a2ui_form/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: a2ui_form
+description: "Create rich interactive forms using A2UI v0.9 protocol with validation, data binding, and multi-step flows"
+version: 1.0.0
+author: Hive Team
+icon: "📝"
+category: canvas
+permissions:
+  - canvas_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "crear formulario A2UI"
+  - "create A2UI form"
+  - "formulario interactivo A2UI"
+  - "A2UI form"
+  - "pedir datos con A2UI"
+  - "collect data A2UI"
+  - "formulario con validación"
+  - "form with validation"
+  - "formulario multi-paso"
+  - "multi-step form A2UI"
+  - "form dinámico A2UI"
+  - "dynamic form A2UI"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface with a unique surfaceId and catalog. Set theme with primaryColor and agentDisplayName."
+    params:
+      surfaceId: "Unique identifier (e.g. 'contact_form', 'signup_form')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#3B82F6', agentDisplayName: 'Asistente' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Send the form layout as a flat list of A2UI components. Must include a 'root' component. Use Column/Row for layout, TextField for inputs, Button for submit."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions"
+    output: components_sent
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Populate initial form values using JSON Pointer paths (e.g. '/form/name'). Sets default values and enables two-way binding."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/form"
+      value: "{ name: '', email: '' }"
+    output: data_populated
+
+  - step: 4
+    action: a2ui_delete_surface
+    instruction: "Delete the A2UI surface when the form is completed or no longer needed."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use data binding with { path: '/form/field' } for TextField values to enable two-way binding"
+  - "Add checks (validation) to TextField: [{ call: 'required', args: { value: { path: '/form/email' } }, message: 'Email is required' }]"
+  - "Button actions use event format: { event: { name: 'submit_form', context: { email: { path: '/form/email' } } } }"
+  - "Use Column for vertical layouts, Row for horizontal layouts"
+  - "Set weight on Row/Column children for proportional sizing (e.g. weight: 1 vs weight: 3)"
+  - "Delete surfaces with a2ui_delete_surface when no longer needed to prevent memory leaks"
+  - "Prefer A2UI forms over canvas_ask for complex forms with validation"
+
+output_format:
+  structure: a2ui_form
+  sections:
+    - "surface_creation"
+    - "component_layout"
+    - "data_model"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "creá un formulario de contacto"
+    expected_behavior: "a2ui_create_surface(surfaceId:'contact_form', theme:{primaryColor:'#3B82F6',agentDisplayName:'Asistente'}) → a2ui_update_components(surfaceId:'contact_form', components:[root,Column,hdr,name_fld,email_fld,msg_fld,submit_btn]) → a2ui_update_data_model(surfaceId:'contact_form', path:'/form', value:{name:'',email:'',message:''})"
+
+  - user_input: "I need a signup form with email validation"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with TextField({value:{path:'/form/email'}, checks:[{call:'required',...},{call:'email',...}]}) → a2ui_update_data_model"
+
+  - user_input: "creá un formulario multi-paso"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Tabs+Column per step → a2ui_update_data_model for all fields"
+---
+
+# A2UI Form Skill
+
+## Cuándo se Activa
+
+Para crear formularios interactivos ricos usando el protocolo A2UI v0.9. Usar cuando se necesita:
+- Validación de campos (required, email, regex)
+- Data binding dinámico
+- Formularios multi-paso
+- Choice pickers, sliders, checkboxes
+- Formularios con acciones personalizadas
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía componentes | Después de crear surface |
+| `a2ui_update_data_model` | Actualiza datos | Para valores iniciales o dinámicos |
+| `a2ui_delete_surface` | Elimina la superficie | Al terminar |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // opcional, para datos iniciales
+4. [esperar acción del usuario]
+5. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Componentes Disponibles
+
+| Componente | Descripción | Props clave |
+|------------|-------------|-------------|
+| `Column` | Layout vertical | `children`, `distribution`, `alignment` |
+| `Row` | Layout horizontal | `children`, `distribution`, `alignment` |
+| `Text` | Texto | `text`, `usageHint` (h1-h5, body, caption, code) |
+| `Button` | Botón | `child`, `variant`, `action` |
+| `TextField` | Campo de texto | `label`, `value`, `variant` (shortText/longText/number/obscured), `validationRegexp`, `checks`, `action` |
+| `CheckBox` | Checkbox | `label`, `value` |
+| `ChoicePicker` | Selector múltiple | `options`, `value` (DynamicStringList), `variant` (mutuallyExclusive/multipleSelection), `displayStyle`, `filterable`, `action` |
+| `Slider` | Slider numérico | `value`, `minValue`, `maxValue` |
+| `DateTimeInput` | Fecha/hora | `value`, `enableDate`, `enableTime` |
+| `Card` | Tarjeta | `child` |
+| `Divider` | Separador | `axis` |
+| `Image` | Imagen | `url`, `fit` |
+| `Tabs` | Pestañas | `tabItems` |
+
+## Data Binding
+
+- Literal: `"texto directo"` o número
+- Path: `{ "path": "/form/name" }` — se resuelve contra el data model
+- Function call: `{ "call": "formatDate", "args": {...} }`
+
+## Cuándo disparan acciones los inputs
+
+| Componente | Cuándo dispara | Formato de action |
+|------------|---------------|-------------------|
+| `Button` | Al hacer click | `{name: "...", context: {...}}` o `{event: {name: "...", context: {...}}}` |
+| `TextField` | Al perder foco (blur) o presionar Enter (en shortText) | `{name: "...", context: {...}}` |
+| `ChoicePicker` | Inmediatamente al seleccionar/deseleccionar | `{name: "...", context: {...}}` |
+| `Slider` | Al soltar el slider (onValueCommit) | `{name: "...", context: {...}}` |
+| `CheckBox` | Al cambiar estado | — (solo two-way binding) |
+| `DateTimeInput` | Al cambiar valor | — (solo two-way binding) |
+
+**Nota**: Tanto `{name: "...", context: {...}}` (directo) como `{event: {name: "...", context: {...}}}` (con wrapper) son formatos válidos.
+
+**Nota**: Para ChoicePicker usa siempre `selections: {path: "..."}` (no `value`) para two-way binding.
+
+## Validación (checks)
+
+```json
+"checks": [
+  { "call": "required", "args": { "value": { "path": "/form/email" } }, "message": "Email is required" },
+  { "call": "email", "args": { "value": { "path": "/form/email" } }, "message": "Invalid email" },
+  { "call": "regex", "args": { "value": { "path": "/form/phone" }, "pattern": "^\\d{10}$" }, "message": "10 digits required" }
+]
+```
+
+## Ejemplo: Formulario de Contacto
+
+```json
+// 1. Create surface
+a2ui_create_surface(surfaceId: "contact_form", catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json", theme: {primaryColor: "#3B82F6", agentDisplayName: "Asistente"})
+
+// 2. Send components
+a2ui_update_components(surfaceId: "contact_form", components: [
+  {"id": "root", "component": "Column", "children": ["header","name_field","email_field","msg_field","submit_btn"]},
+  {id: "header", component: "Text", text: "Contacto", variant: "h2"},
+  {id: "name_field", component: "TextField", label: "Nombre", value: {path: "/form/name"}, variant: "shortText"},
+  {id: "email_field", component: "TextField", label: "Email", value: {path: "/form/email"}, variant: "shortText", validationRegexp: "^[^@]+@[^@]+\\.[^@]+$", checks: [{call: "required", args: {value: {path: "/form/email"}}, message: "Email obligatorio"}, {call: "email", args: {value: {path: "/form/email"}}, message: "Email inválido"}]},
+  {id: "msg_field", component: "TextField", label: "Mensaje", value: {path: "/form/message"}, variant: "longText"},
+  {id: "submit_label", component: "Text", text: "Enviar"},
+  {id: "submit_btn", component: "Button", child: "submit_label", variant: "primary", action: {event: {name: "submit_contact", context: {name: {path: "/form/name"}, email: {path: "/form/email"}, message: {path: "/form/message"}}}}
+])
+
+// 3. Initialize data model
+a2ui_update_data_model(surfaceId: "contact_form", path: "/form", value: {name: "", email: "", message: ""})
+```
+
+## Mejores Prácticas
+
+- Siempre incluir un componente `root` con id="root"
+- Usar `{ path: "/..." }` para data binding en TextField values
+- Agregar `checks` para validación de campos obligatorios
+- Usar `variant: "primary"` para botones principales
+- Eliminar surfaces con `a2ui_delete_surface` al terminar
+- Preferir A2UI forms sobre `canvas_ask` para formularios complejos con validación

package/packages/skills/src/bundled/canvas/a2ui_interactive/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: a2ui_interactive
+description: "Create multi-step interactive workflows using A2UI v0.9 protocol with tabs, modals, choice pickers, and dynamic updates based on user actions"
+version: 1.0.0
+author: Hive Team
+icon: "🔄"
+category: canvas
+permissions:
+  - canvas_write
+dependencies: []
+tools: [a2ui_create_surface, a2ui_update_components, a2ui_update_data_model, a2ui_delete_surface]
+
+# Structured skill fields
+triggers:
+  - "interfaz interactiva A2UI"
+  - "A2UI interactive UI"
+  - "flujo A2UI"
+  - "A2UI workflow"
+  - "asistente A2UI"
+  - "A2UI assistant"
+  - "wizard A2UI"
+  - "flujo multi-paso A2UI"
+  - "multi-step flow A2UI"
+  - "workflow interactivo"
+  - "interactive workflow"
+  - "asistente paso a paso"
+  - "step-by-step assistant"
+  - "A2UI con tabs y modales"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: a2ui_create_surface
+    instruction: "Create an A2UI surface for the interactive workflow. Set theme with agent display name."
+    params:
+      surfaceId: "Descriptive ID (e.g. 'onboarding_flow', 'booking_assistant')"
+      catalogId: "https://a2ui.org/specification/v0_9/basic_catalog.json"
+      theme: "{ primaryColor: '#8B5CF6', agentDisplayName: 'Asistente' }"
+    output: surface_created
+
+  - step: 2
+    action: a2ui_update_components
+    instruction: "Build the initial workflow layout. Use Tabs for multi-step flows, Modal for confirmations, ChoicePicker for selections."
+    params:
+      surfaceId: "Same surfaceId from step 1"
+      components: "Array of A2UI component definitions for workflow steps"
+    output: workflow_layout
+
+  - step: 3
+    action: a2ui_update_data_model
+    instruction: "Initialize workflow state data. Include all fields needed across steps."
+    params:
+      surfaceId: "Same surfaceId"
+      path: "/"
+      value: "Initial workflow state object"
+    output: state_initialized
+
+  - step: 4
+    action: a2ui_update_components
+    instruction: "Update components based on user actions. Show/hide steps, change options, add validation feedback."
+    params:
+      surfaceId: "Same surfaceId"
+      components: "Updated component definitions reflecting state changes"
+    output: workflow_updated
+
+  - step: 5
+    action: a2ui_delete_surface
+    instruction: "Delete the workflow surface when the flow is completed or cancelled."
+    params:
+      surfaceId: "Same surfaceId"
+    output: surface_deleted
+
+rules:
+  - "Always call a2ui_create_surface BEFORE a2ui_update_components"
+  - "Components MUST include a root component with id='root'"
+  - "Use Tabs for multi-step workflows with tabItems: [{title, child}]"
+  - "Use Modal for confirmation dialogs: {entryPointChild, contentChild}"
+  - "Use ChoicePicker for selections: variant='mutuallyExclusive' for single, omit for multiple"
+  - "Use Button actions with event format: {event: {name: 'action_name', context: {key: {path: '/data/key'}}}}"
+  - "Update workflow state with a2ui_update_data_model after each user action"
+  - "Use a2ui_update_components to change the UI structure between steps"
+  - "Show progress indicators with Text components showing current step"
+  - "Validate inputs with checks on TextField: [{call: 'required', args: {value: {path: '...'}}, message: 'Required'}]"
+  - "Delete surfaces with a2ui_delete_surface when workflow is completed"
+  - "For simple confirmations prefer canvas_confirm; use A2UI for multi-step workflows"
+
+output_format:
+  structure: a2ui_interactive
+  sections:
+    - "surface_creation"
+    - "workflow_layout"
+    - "state_initialization"
+    - "dynamic_updates"
+    - "cleanup"
+  max_length: "Structured JSON components"
+
+examples:
+  - user_input: "creá un asistente de reserva"
+    expected_behavior: "a2ui_create_surface(surfaceId:'booking', theme:{primaryColor:'#8B5CF6'}) → a2ui_update_components with Tabs[step1:service, step2:datetime, step3:confirm] → a2ui_update_data_model(path:'/', value:{service:'', date:'', time:''})"
+
+  - user_input: "I need a multi-step onboarding flow"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with Column[step indicator, step content, nav buttons] → a2ui_update_data_model with empty state → on action: a2ui_update_components for next step"
+
+  - user_input: "creá un wizard con selección de opciones"
+    expected_behavior: "a2ui_create_surface → a2ui_update_components with ChoicePicker for options, Button for navigation → a2ui_update_data_model with initial state"
+---
+
+# A2UI Interactive Skill
+
+## Cuándo se Activa
+
+Para crear flujos interactivos multi-paso usando A2UI v0.9. Usar cuando se necesita:
+- Wizards paso a paso
+- Flujos de onboarding
+- Asistentes de reserva/configuración
+- Formularios con selections dinámicas
+- Interacciones con modales de confirmación
+- UIs que cambian según las acciones del usuario
+
+## Herramientes Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| `a2ui_create_surface` | Crea la superficie A2UI | Siempre primero |
+| `a2ui_update_components` | Envía/actualiza componentes | Para layout y cambios de UI |
+| `a2ui_update_data_model` | Actualiza datos | Para estado del workflow |
+| `a2ui_delete_surface` | Elimina la superficie | Al terminar flujo |
+
+## Flujo Obligatorio
+
+```
+1. a2ui_create_surface(surfaceId, catalogId, theme)
+2. a2ui_update_components(surfaceId, components[])
+3. a2ui_update_data_model(surfaceId, path, value)  // estado inicial
+4. [recibir acción del usuario]
+5. a2ui_update_data_model(...)  // actualizar estado con respuesta
+6. a2ui_update_components(...)  // cambiar UI al siguiente paso
+7. ... repetir 4-6 según necesidad ...
+8. a2ui_delete_surface(surfaceId)  // al terminar
+```
+
+## Patrones de Flujo Interactivo
+
+### Wizard con Tabs (multi-paso)
+
+```json
+[
+  {id: "root", component: "Column", children: ["step_indicator", "tabs"]},
+  {id: "step_indicator", component: "Text", text: {path: "/stepLabel"}, variant: "caption"},
+  {id: "tabs", component: "Tabs", tabs: [
+    {title: "Servicio", child: "step1"},
+    {title: "Fecha", child: "step2"},
+    {title: "Confirmar", child: "step3"}
+  ]},
+  {id: "step1", component: "Column", children: ["svc_label", "svc_picker"]},
+  {id: "svc_label", component: "Text", text: "Seleccioná un servicio", variant: "h3"},
+  {id: "svc_picker", component: "ChoicePicker", variant: "mutuallyExclusive", options: [...], value: {path: "/data/service"}},
+  // ... más pasos
+]
+```
+
+### Confirmación con Modal
+
+```json
+[
+  {id: "confirm_modal", component: "Modal", trigger: "confirm_btn", content: "confirm_dialog"},
+  {id: "confirm_btn", component: "Button", child: "confirm_btn_text", action: {}},
+  {id: "confirm_btn_text", component: "Text", text: "Confirmar Reserva"},
+  {id: "confirm_dialog", component: "Column", children: ["confirm_msg", "confirm_yes", "confirm_no"]},
+  {id: "confirm_msg", component: "Text", text: "¿Confirmás tu reserva?"},
+  {id: "confirm_yes", component: "Button", child: "yes_text", variant: "primary", action: {event: {name: "confirm_booking", context: {service: {path: "/data/service"}}}}},
+  {id: "yes_text", component: "Text", text: "Sí, confirmar"},
+  {id: "confirm_no", component: "Button", child: "no_text", variant: "borderless", action: {event: {name: "cancel"}}}},
+  {id: "no_text", component: "Text", text: "Cancelar"}
+]
+```
+
+### Selección con ChoicePicker
+
+```json
+[
+  {id: "service_picker", component: "ChoicePicker",
+    variant: "mutuallyExclusive",
+    options: [
+      {label: "Consulta General", value: "general"},
+      {label: "Especializada", value: "specialist"},
+      {label: "Urgencia", value: "urgent"}
+    ],
+    value: {path: "/data/serviceType"},
+    action: {event: {name: "service_selected", context: {service: {path: "/data/serviceType"}}}}
+  }
+]
+```
+
+## Mejores Prácticas
+
+- Usar Tabs para wizards multi-paso
+- Usar Modal para confirmaciones antes de acciones críticas
+- Usar ChoicePicker con `variant: "mutuallyExclusive"` para selección única
+- Mostrar indicador de progreso (paso X de Y)
+- Actualizar data model después de cada acción del usuario
+- Usar `a2ui_update_components` para cambiar la UI entre pasos
+- Agregar validación con `checks` en TextField
+- Mantener el estado del flujo en el data model (`/data/step`, `/data/serviceType`, etc.)
+- Eliminar surfaces con `a2ui_delete_surface` al completar o cancelar