house-lights 1.3.0 → 1.5.0

package/skills/cast-list/examples/agents/bodega-orquestrador/actions/AgenteFidelidade.mcs.yml

@@ -0,0 +1,24 @@
+mcs.metadata:
+  componentName: Agente Fidelidade
+  description: Agente conectado Bodega Azul - Fidelidade.
+kind: TaskDialog
+inputs:
+  - kind: ManualTaskInput
+    propertyName: CategoriaSolicitacao
+    value: =Global.CategoriaSolicitacao
+
+modelDisplayName: Bodega Azul - Fidelidade
+modelDescription: "Agente especialista no programa de fidelidade: pontos, níveis e resgates. Use quando a categoria for Fidelidade."
+action:
+  kind: InvokeConnectedAgentTaskAction
+  inputType:
+    properties:
+      CategoriaSolicitacao:
+        displayName: CategoriaSolicitacao
+        description: Categoria da solicitação definida pelo orquestrador.
+        isRequired: true
+        type: String
+
+  botSchemaName: cr7b2_bodegaFidelidade
+  historyType:
+    kind: ConversationHistory

package/skills/cast-list/examples/agents/bodega-orquestrador/actions/AgenteFrete.mcs.yml

@@ -2,23 +2,11 @@ mcs.metadata:
   componentName: Agente Frete
   description: Agente conectado Bodega Azul - Frete.
 kind: TaskDialog
-inputs:
-  - kind: ManualTaskInput
-    propertyName: CategoriaSolicitacao
-    value: =Global.CategoriaSolicitacao
-
 modelDisplayName: Bodega Azul - Frete
 modelDescription: "Agente especialista em frete e entregas: modalidades, prazos por região e frete grátis. Use quando a categoria for Frete."
 action:
   kind: InvokeConnectedAgentTaskAction
-  inputType:
-    properties:
-      CategoriaSolicitacao:
-        displayName: CategoriaSolicitacao
-        description: Categoria da solicitação definida pelo orquestrador.
-        isRequired: true
-        type: String
-
+  inputType: {}
   botSchemaName: cr7b2_bodegaFrete
   historyType:
-    kind: ConversationHistory
+    kind: NoHistory

package/skills/cast-list/examples/agents/bodega-pedidos/topics/Escalate.topic.mcs.yml

@@ -18,3 +18,8 @@ beginDialog:
     - kind: SendActivity
       id: sendMessage_X7qDFG
       activity: "A transferência para um atendente ainda não está disponível neste canal. Fale com a nossa equipe pelo e-mail pedidos@bodegaazul.example, de segunda a sábado, das 9h às 18h."
+
+    - kind: SendActivity
+      id: sendMessage_kDOncS
+      disabled: true
+      activity: "Aguarde, estamos transferindo você para um atendente."

package/skills/cast-list/examples/agents/bodega-pedidos/workflows/AbrirChamadoERP-7d1c2a4e/metadata.yml

@@ -0,0 +1,3 @@
+displayName: Abrir chamado no ERP
+workflowId: 7d1c2a4e-3b5f-4c6d-8e9f-0a1b2c3d4e5f
+jsonFileName: workflow.json

package/skills/cast-list/examples/agents/bodega-pedidos/workflows/AbrirChamadoERP-7d1c2a4e/workflow.json

@@ -0,0 +1,56 @@
+{
+  "properties": {
+    "displayName": "Abrir chamado no ERP",
+    "connectionReferences": {},
+    "definition": {
+      "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
+      "contentVersion": "1.0.0.0",
+      "triggers": {
+        "manual": {
+          "type": "Request",
+          "kind": "Skills",
+          "inputs": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "resumo": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "actions": {
+        "Abrir_chamado": {
+          "type": "Scope",
+          "actions": {
+            "Chamar_ERP": {
+              "type": "Http",
+              "inputs": {
+                "method": "POST",
+                "uri": "https://erp.bodega-azul.example/chamados",
+                "body": "@triggerBody()"
+              }
+            }
+          }
+        },
+        "Responder": {
+          "type": "Response",
+          "kind": "Skills",
+          "runAfter": {
+            "Abrir_chamado": [
+              "Succeeded"
+            ]
+          },
+          "inputs": {
+            "statusCode": 200,
+            "body": {
+              "resultado": "@outputs('Resultado')"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/cast-list/examples/equipe.csv

@@ -0,0 +1,7 @@
+Agente;KPI;Dono
+Bodega Azul - Pedidos;pedido localizado em até 2 trocas de mensagem;Squad Pedidos
+Bodega Azul - Devoluções;troca aberta sem atendente em 80% dos casos;Squad Pós-venda
+Bodega Azul - Frete;cotação em menos de 5 s;Squad Logística
+Bodega Azul - Cupons;cupom validado na primeira tentativa;Squad Promoções
+Bodega Azul - Loja Física;;Squad Lojas
+Sobre a Bodega Azul;respostas gerais sem encaminhar;Squad Atendimento

package/skills/cast-list/examples/inventario.csv

@@ -0,0 +1,10 @@
+Item name,Item type,Schema name,Owner,Environment,Created on,Last published
+Bodega Azul - Orquestrador,Agent,cr7b2_bodegaOrquestrador,atendimento@bodegaazul.example,Bodega Azul (Produção),2026-03-02,2026-10-28
+Bodega Azul - Pedidos,Agent,cr7b2_bodegaPedidos,pedidos@bodegaazul.example,Bodega Azul (Produção),2026-03-05,2026-10-21
+Bodega Azul - Devoluções,Agent,cr7b2_bodegaDevolucoes,trocas@bodegaazul.example,Bodega Azul (Produção),2026-03-05,2026-10-14
+Bodega Azul - Frete,Agent,cr7b2_bodegaFrete,frete@bodegaazul.example,Bodega Azul (Produção),2026-03-09,2026-09-30
+Bodega Azul - Cupons,Agent,cr7b2_bodegaCupons,,Bodega Azul (Produção),2026-03-12,2026-10-02
+Bodega Azul - Loja Física,Agent,cr7b2_bodegaLojaFisica,loja@bodegaazul.example,Bodega Azul (Produção),2026-04-01,
+Bodega Azul - Fidelidade,Agent,cr7b2_bodegaFidelidade,fidelidade@bodegaazul.example,Bodega Azul (Testes),2026-08-20,
+Painel de Pedidos,Canvas app,,pedidos@bodegaazul.example,Bodega Azul (Produção),2026-02-11,
+Abrir chamado no ERP,Agent flow,,pedidos@bodegaazul.example,Bodega Azul (Produção),2026-03-05,

package/skills/cast-list/examples/telemetria.csv

@@ -0,0 +1,10 @@
+agente,evento,vezes
+Bodega Azul - Orquestrador,TopicStart,1840
+Bodega Azul - Orquestrador,BodegaOrquestrador_OnError,12
+Bodega Azul - Pedidos,TopicStart,610
+Bodega Azul - Pedidos,BodegaPedidos_OnError,7
+Bodega Azul - Devoluções,TopicStart,402
+Bodega Azul - Devoluções,BodegaDevolucoes_OnError,3
+Bodega Azul - Frete,TopicStart,355
+Bodega Azul - Cupons,TopicStart,290
+Bodega Azul - Cupons,bodega_cupons_onerror,5

package/skills/cast-list/references/format.md

@@ -35,6 +35,15 @@ decisions:                   # what the team decided about a pattern
 
 ## The workbook back
 
+## A spreadsheet from outside
+
+`--declared <table.csv|.xlsx>` (more than once is fine) reads a table the team already has — the admin center's
+inventory download, the team's list — and proposes a `declared:` line per agent and column, with the source
+`<file> › line <n>` (`<file> › <sheet> › line <n>` for an .xlsx). The agent's column is found by its values; the key is
+the column's title in lower case with `-` (`Linha de base` → `linha-de-base`; `Dono`/`Owner` → `owner`, `KPI`/`Indicador`
+→ `kpi`). Listed with keys (`d1`…), written with `--take`, like the workbook below. Two tables saying the same key of
+the same agent: the later one holds.
+
 In Excel, fill the **Declared** sheet (who, key, value, source) and the **Decision** column of **Patterns** (`accepted` /
 `aceito`, `rejected` / `rejeitado`; **Scope** and **Why** beside it). Then:
 
@@ -55,3 +64,29 @@ A line deleted or a decision cleared is a change too.
                 "facts": { "trigger:OnUnknownIntent": [ { "file": "topics/Fallback.topic.mcs.yml", "line": 7 } ] },
                 "children": [], "unknown": [] } ] }
 ```
+
+An orchestrator's agent also has `contract` — a line per connected-agent action: `calls` (the schema name it calls),
+`name` (the action's name for it), `history` (it passes the conversation history), `inputs`, `description` (the
+routing description), `file` and `line` — and every agent has `flows`: `id` (the `workflowId`), `name`, `folder`,
+`uses` (`http:<host>`, `connector:<api>`, `operation:<api>/<op>`, `child-flow`), `returns`, `called` and `file`.
+
+## The facts of the contract, the flows and what nobody uses
+
+| Key | On which agent | From |
+|---|---|---|
+| `called-with:history` | the one called | the orchestrator's action has `historyType: ConversationHistory` |
+| `called-with:input:<name>` | the one called | each input the orchestrator's action passes |
+| `routing:described` | the one called | the action has a `modelDescription` |
+| `flow-uses:http:<host>`, `flow-uses:connector:<api>`, `flow-uses:operation:<api>/<op>`, `flow-uses:child-flow` | the one whose node calls the flow | the actions of `workflow.json`, at any depth |
+| `flow-returns` | the same | the flow has a `Response` action |
+| `orphan:topic:<name>`, `orphan:action:<name>`, `orphan:variable:<name>`, `orphan:flow:<name>` | the one that has it | nothing can reach it (see SKILL.md, step 2) |
+| `disabled:node:<kind>`, `disabled:<topic\|action\|variable\|knowledge>:<name>` | the one that has it | `disabled: true` on a node; `state` or `status: Inactive` on a component |
+
+| `telemetry:event:<form>` | the one that logs it | a `LogCustomTelemetryEvent` node; the form is its `eventName` with the agent's own name as `{agent}` (part of `node:LogCustomTelemetryEvent`) |
+| `telemetry:field:<form>/<field>` | the same | each field of the node's `properties` record (part of its event) |
+
+Every agent also has `telemetry` in `<id>.facts.json`: `name` (as written), `form`, `fields` (absent when the record is
+a formula), `file` and `line`. An event spelt another way counts as the most common form in the comparison.
+
+The contract's facts cite the orchestrator's file (`<orchestrator>/actions/X.mcs.yml`). `orphan:` and `disabled:` are
+never a pattern nor a solo, and what an unused flow calls is not a fact.

package/skills/cast-list/references/keys.md

@@ -30,6 +30,11 @@ Every fact cast-list finds is a key. The keys below have a name; any other key k
 
 | Key | Name | Nome |
 |---|---|---|
+| `flow-returns` | The flow returns an answer | O fluxo devolve uma resposta |
+| `flow-uses:child-flow` | The flow calls another flow | O fluxo chama outro fluxo |
+| `flow-uses:http:<value>` | Flow calls <value> | Fluxo chama <valor> |
+| `flow-uses:connector:<value>` | Flow uses the connector <value> | Fluxo usa o conector <valor> |
+| `flow-uses:operation:<value>` | Flow uses the operation <value> | Fluxo usa a operação <valor> |
 | `connector:<value>` | Connector <value> | Conector <valor> |
 | `operation:<value>` | Operation <value> | Operação <valor> |
 | `connref:<value>` | Connection reference <value> | Referência de conexão <valor> |
@@ -58,6 +63,9 @@ Every fact cast-list finds is a key. The keys below have a name; any other key k
 | `trigger:OnRedirect` | Takes a call from the orchestrator | Recebe chamada do orquestrador |
 | `trigger:OnToolSelected` | Child chosen as a tool | Filho escolhido como ferramenta |
 | `setting:connectable` | Can be called by an orchestrator | Pode ser chamado por um orquestrador |
+| `called-with:history` | Receives the conversation history | Recebe o histórico da conversa |
+| `routing:described` | Has a routing description | Tem descrição de roteamento |
+| `called-with:input:<value>` | Receives <value> from the orchestrator <value> | Recebe <valor> do orquestrador <valor> |
 | `calls:<value>` | Calls <value> | Chama <valor> |
 | `child:<value>` | Child <value> | Filho <valor> |
 | `var-in:<value>` | Receives from the orchestrator <value> | Recebe do orquestrador <valor> |
@@ -72,6 +80,14 @@ Every fact cast-list finds is a key. The keys below have a name; any other key k
 | `instructions:present` | Has instructions | Tem instruções |
 | `node:LogCustomTelemetryEvent` | Logs telemetry | Registra telemetria |
 | `node:CSATQuestion` | Asks for satisfaction (CSAT) | Pergunta a satisfação (CSAT) |
+| `orphan:topic:<value>` | Topic nobody calls <value> | Tópico que ninguém chama <valor> |
+| `orphan:action:<value>` | Tool nobody can choose <value> | Ferramenta que ninguém escolhe <valor> |
+| `orphan:variable:<value>` | Variable nobody uses <value> | Variável que ninguém usa <valor> |
+| `orphan:flow:<value>` | Flow nobody calls <value> | Fluxo que ninguém chama <valor> |
+| `disabled:node:<value>` | Switched-off node <value> | Nó desligado <valor> |
+| `telemetry:event:<value>` | Logs the event <value> | Registra o evento <valor> |
+| `telemetry:field:<value>` | The event carries the field (<event>/<field>) <value> | O evento leva o campo (<evento>/<campo>) <valor> |
+| `disabled:<value>` | Switched off <value> | Desligado <valor> |
 | `node:<value>` | Node <value> | Nó <valor> |
 | `model:<value>` | Model <value> | Modelo <valor> |
 | `auth:<value>` | Sign-in <value> | Login <valor> |

package/skills/cast-list/references/telemetry.md

@@ -0,0 +1,39 @@
+# What fired: the export of Application Insights
+
+The YAML shows what an agent **should** log (`LogCustomTelemetryEvent`). What it **does** log is in Application
+Insights, when the agent is connected to it (Copilot Studio › Settings › Advanced › Application Insights). cast-list
+never reads it over the network: the person runs one query and exports the result, and the analysis reads the file.
+
+## The query
+
+In the Application Insights resource, open **Logs**, paste this, and export the result (**Export › CSV**):
+
+```kusto
+customEvents
+| where timestamp > ago(30d)
+| where tostring(customDimensions['designMode']) == "False"
+| summarize vezes = count() by agente = cloud_RoleInstance, evento = name
+```
+
+- `designMode` leaves out the conversations of the test panel.
+- `cloud_RoleInstance` is the agent's name in the default telemetry. When the team puts the agent's name in a field of
+  its own events (such as `Agente`), use that instead: `agente = tostring(customDimensions['Agente'])`. cast-list finds
+  the agent's column by its values (the schema name, the folder or the display name), not by its title.
+- Change `30d` to the period you want, and pass the same number with `--telemetry-days`.
+- **Export only these three columns.** Never add `text`, `fromName`, `user_Id` or any other column with what people
+  said or who they are: cast-list reads only the agent, the event and the times, and the rest has no place in the file.
+
+## Run
+
+```
+node scripts/build.mjs <agents-folder> --all --telemetry eventos.csv [--telemetry-days 30] [--lang pt]
+```
+
+The file is read on this run only (it is not kept in the cast file): pass it again on the next one.
+
+- «O evento «X» de y não disparou em 30 dias» — the event is in y's YAML, y has lines in the export, and none is X.
+- «y não tem nenhuma linha na telemetria: está ligado ao Application Insights?» — y is not in the export at all.
+- An event of the export that no YAML has — Copilot Studio's own (`TopicStart`, `BotMessageReceived`…) — is left out.
+
+The map's Cast tab shows each agent's events with the times they fired, and the workbook's **Telemetry** sheet has a
+column with the times.

package/skills/cast-list/scripts/build.mjs

@@ -9,6 +9,11 @@
 //   node build.mjs <agents-folder> --from <edited.xlsx> [--take <key,key…|all>] [--out <folder>]
 //                                  what was filled in the workbook (Declared, the Decision column): listed with a key each,
 //                                  and with --take written to the cast file
+//   node build.mjs <agents-folder> --declared <table.csv|.xlsx> [--declared <another>] [--agent-column <title>] [--take <key,…|all>]
+//                                  what a spreadsheet says about the agents (the team's, the admin center's inventory): each
+//                                  column becomes a declared fact, listed with a key, and with --take written to the cast file
+//   … --telemetry <export.csv|.xlsx> [--telemetry-days <n>]   what fired, from Application Insights (references/telemetry.md):
+//                                  the events in the YAML that did not fire, and who has no line at all
 //
 // With no --html/--xlsx/--lesson it makes the map. Files go in --out (or beside the folder), named by the folder:
 // <id>.html, <id>.xlsx, <id>.lesson.html (a chalk-talk lesson), and <id>.cast.yaml, kept up to date (read again on every
@@ -20,23 +25,26 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { runPage } from './browser.mjs'
-import { agentsIn, applyChanges, compare, DEFAULT_PROFILE, extractAgent, fromSheets, knownKinds, labelOf, lessonOf, problemText, readCast, readProfile, reviewCast, validateScene, workbookFile, workbookOf, writeCast } from './engine.mjs'
+import { agentsIn, applyChanges, compare, declaredFrom, DEFAULT_PROFILE, extractAgent, firedFrom, fromSheets, mergeDeclared, knownKinds, labelOf, lessonOf, problemText, readCast, readCsv, readProfile, reviewCast, validateScene, workbookFile, workbookOf, writeCast } from './engine.mjs'
 import { readXlsx } from './read-xlsx.mjs'
 import { fill, inline } from './page.mjs'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const argv = process.argv.slice(2)
-const valued = new Set(['--lang', '--out', '--profile', '--from', '--take'])
+const valued = new Set(['--lang', '--out', '--profile', '--from', '--take', '--declared', '--agent-column', '--telemetry', '--telemetry-days'])
 const flags = new Set(['--check', '--html', '--xlsx', '--lesson', '--all', '--facts', ...valued])
 const option = (name) => {
   const at = argv.indexOf(name)
   return at >= 0 ? argv[at + 1] : undefined
 }
+const options = (name) => argv.flatMap((a, i) => (a === name && argv[i + 1] ? [argv[i + 1]] : []))
 const args = argv.filter((a, i) => !a.startsWith('--') && !valued.has(argv[i - 1]))
 const usage = `usage: node build.mjs <agents-folder> --check [--profile <p.cast.yaml>] [--lang en|pt]
        node build.mjs <agents-folder> [--profile <p.cast.yaml>] [--html] [--xlsx] [--lesson] [--all] [--lang en|pt] [--out <folder>]
        node build.mjs <agents-folder> --facts [--out <folder>]
-       node build.mjs <agents-folder> --from <edited.xlsx> [--take <key,key…|all>] [--out <folder>]`
+       node build.mjs <agents-folder> --from <edited.xlsx> [--take <key,key…|all>] [--out <folder>]
+       node build.mjs <agents-folder> --declared <table.csv|.xlsx> [--agent-column <title>] [--take <key,key…|all>] [--out <folder>]
+       … [--telemetry <export.csv|.xlsx>] [--telemetry-days <n>]`
 const lang = option('--lang') ?? 'en'
 const fail = (msg) => {
   console.error(`${msg}\n${usage}`)
@@ -47,7 +55,11 @@ const unknown = argv.find((a) => a.startsWith('--') && !flags.has(a))
 if (unknown) fail(`✗ unknown option ${unknown}`)
 if (!['en', 'pt'].includes(lang)) fail('✗ --lang is en or pt')
 for (const v of valued) if (argv.includes(v) && !option(v)) fail(`✗ ${v} needs a value`)
-if (argv.includes('--take') && !argv.includes('--from')) fail('✗ --take goes with --from')
+if (argv.includes('--take') && !argv.includes('--from') && !argv.includes('--declared')) fail('✗ --take goes with --from or --declared')
+if (argv.includes('--from') && argv.includes('--declared')) fail('✗ --from or --declared, one at a time')
+for (const f of [...options('--declared'), ...options('--telemetry')]) if (!existsSync(f) || !/\.(csv|xlsx)$/i.test(f)) fail(`✗ ${f}: a .csv or an .xlsx that is there`)
+const days = Number(option('--telemetry-days') ?? 30)
+if (!Number.isInteger(days) || days < 1) fail('✗ --telemetry-days is a whole number of days')
 
 const T = {
   en: {
@@ -57,6 +69,12 @@ const T = {
     changes: (n) => (n ? `${n} change${n === 1 ? '' : 's'} in the workbook (take them with --take <key,…> or --take all):` : '✓ the workbook changes nothing'),
     took: (n, f) => `✓ took ${n} change${n === 1 ? '' : 's'} into ${f}`, unknownKey: (k) => `✗ no change with the key «${k}»`,
     declared: 'declared', decision: 'decision', add: '+', set: '~', remove: '−', accepted: 'accepted', rejected: 'rejected', platform: 'platform', specialist: 'specialist', orchestrator: 'orchestrator', none: (f) => `✗ ${f} has no folder with agent.mcs.yml`, privacy: '• the files hold the client’s data: keep them in the client’s environment',
+    noColumn: (f, cols) => `✗ ${f}: no column names the agents of the folder (by schema name, folder or display name): say which with --agent-column "<title>" (columns: ${cols.join(', ')})`,
+    tie: (f, cols) => `✗ ${f}: the columns ${cols.map((c) => `«${c}»`).join(' and ')} name the agents in different ways: say which with --agent-column "<title>"`,
+    noHeader: (f, cols) => `✗ ${f}: no column with that title (columns: ${cols.join(', ')})`,
+    noEvent: (f, cols) => `✗ ${f}: no column of the event («evento», «event» or «name»; columns: ${cols.join(', ')})`,
+    unmatched: (n, f, list) => `• ${f}: ${n} ${n === 1 ? 'row names' : 'rows name'} nobody in the folder: ${list}`, line: 'line',
+    telemetry: (f, n, d) => `✓ telemetry ${f}: ${n} ${n === 1 ? 'row' : 'rows'} of the folder's agents, ${d} days`,
   },
   pt: {
     found: (n, o, s) => `✓ ${n} no elenco: ${o} ${o === 1 ? 'orquestrador' : 'orquestradores'}, ${s} ${s === 1 ? 'especialista' : 'especialistas'}`,
@@ -65,6 +83,12 @@ const T = {
     changes: (n) => (n ? `${n} ${n === 1 ? 'mudança' : 'mudanças'} na planilha (aceite com --take <chave,…> ou --take all):` : '✓ a planilha não muda nada'),
     took: (n, f) => `✓ ${n} ${n === 1 ? 'mudança gravada' : 'mudanças gravadas'} em ${f}`, unknownKey: (k) => `✗ nenhuma mudança com a chave «${k}»`,
     declared: 'declarado', decision: 'decisão', add: '+', set: '~', remove: '−', accepted: 'aceito', rejected: 'rejeitado', platform: 'plataforma', specialist: 'especialista', orchestrator: 'orquestrador', none: (f) => `✗ ${f} não tem nenhuma pasta com agent.mcs.yml`, privacy: '• os arquivos têm dados do cliente: deixe-os no ambiente dele',
+    noColumn: (f, cols) => `✗ ${f}: nenhuma coluna cita os agentes da pasta (pelo nome de esquema, pela pasta ou pelo nome de exibição): diga qual com --agent-column "<título>" (colunas: ${cols.join(', ')})`,
+    tie: (f, cols) => `✗ ${f}: as colunas ${cols.map((c) => `«${c}»`).join(' e ')} citam os agentes de jeitos diferentes: diga qual com --agent-column "<título>"`,
+    noHeader: (f, cols) => `✗ ${f}: nenhuma coluna com esse título (colunas: ${cols.join(', ')})`,
+    noEvent: (f, cols) => `✗ ${f}: nenhuma coluna do evento («evento», «event» ou «name»; colunas: ${cols.join(', ')})`,
+    unmatched: (n, f, list) => `• ${f}: ${n} ${n === 1 ? 'linha não cita' : 'linhas não citam'} ninguém da pasta: ${list}`, line: 'linha',
+    telemetry: (f, n, d) => `✓ telemetria ${f}: ${n} ${n === 1 ? 'linha' : 'linhas'} dos agentes da pasta, ${d} dias`,
   },
 }[lang]
 
@@ -84,36 +108,45 @@ const castFile = join(out, `${id}.cast.yaml`)
 const castText = existsSync(castFile) ? readFileSync(castFile, 'utf8') : undefined
 const cast = castText !== undefined ? read(castFile, readCast).cast : { ...(profile.name ? { name: profile.name } : {}), agents: [], blocks: [], declared: [], decisions: [] }
 
-// ---- the way back: an edited workbook as the changes it proposes ----
-if (argv.includes('--from')) {
-  const edited = fromSheets(cast, readXlsx(readFileSync(resolve(option('--from')))), Object.fromEntries(profile.types.map((t) => [t.id, t.name])))
-  if (edited.problems.length) {
-    for (const p of edited.problems) console.error(`✗ ${basename(option('--from'))}: ${p}`)
-    process.exit(1)
-  }
-  const line = (c) => {
-    const x = c.after ?? c.before
-    // a key with no kind («kpi») is something only people know: declared:<key>
-    if (c.kind === 'declared') return `${T[c.op]} ${T.declared}  ${x.agent} · ${labelOf(x.key.includes(':') ? x.key : `declared:${x.key}`, lang)}${x.value ? ` = «${x.value}»` : ''}${x.source ? ` (${x.source})` : ''}`
-    return `${T[c.op]} ${T.decision}  ${labelOf(x.key, lang)}: ${T[x.status]} (${T[x.scope]})${x.why ? ` — ${x.why}` : ''}`
-  }
+// a table from outside: the sheets of an .xlsx, or a .csv
+const tablesOf = (file) => (/\.xlsx$/i.test(file) ? readXlsx(readFileSync(file)) : [readCsv(readFileSync(file, 'utf8'), '')])
+const tableProblem = (file, p) => {
+  console.error(p.problem === 'tie' ? T.tie(basename(file), p.titles) : p.problem === 'header' ? T.noHeader(basename(file), p.titles) : p.problem === 'event' ? T.noEvent(basename(file), p.titles) : T.noColumn(basename(file), p.titles))
+  process.exit(1)
+}
+const line = (c) => {
+  const x = c.after ?? c.before
+  if (c.kind === 'declared') return `${T[c.op]} ${T.declared}  ${x.agent} · ${labelOf(x.key.includes(':') ? x.key : `declared:${x.key}`, lang)}${x.value ? ` = «${x.value}»` : ''}${x.source ? ` (${x.source})` : ''}`
+  return `${T[c.op]} ${T.decision}  ${labelOf(x.key, lang)}: ${T[x.status]} (${T[x.scope]})${x.why ? ` — ${x.why}` : ''}`
+}
+// what changes the cast file: listed, each with its key, and with --take written
+const proposeOrTake = (changes) => {
   const take = option('--take')
   if (!take) {
-    console.log(T.changes(edited.changes.length))
-    for (const c of edited.changes) console.log(`  ${c.key}  ${line(c)}`)
+    console.log(T.changes(changes.length))
+    for (const c of changes) console.log(`  ${c.key}  ${line(c)}`)
     process.exit(0)
   }
-  const keys = take === 'all' ? edited.changes.map((c) => c.key) : take.split(',').map((k) => k.trim()).filter(Boolean)
-  const missing = keys.find((k) => !edited.changes.some((c) => c.key === k))
+  const keys = take === 'all' ? changes.map((c) => c.key) : take.split(',').map((k) => k.trim()).filter(Boolean)
+  const missing = keys.find((k) => !changes.some((c) => c.key === k))
   if (missing) {
     console.error(T.unknownKey(missing))
     process.exit(2)
   }
   mkdirSync(out, { recursive: true })
-  writeFileSync(castFile, writeCast(applyChanges(cast, edited.changes, keys), castText))
+  writeFileSync(castFile, writeCast(applyChanges(cast, changes, keys), castText))
   console.log(T.took(keys.length, basename(castFile)))
   process.exit(0)
 }
+// ---- the way back: an edited workbook as the changes it proposes ----
+if (argv.includes('--from')) {
+  const edited = fromSheets(cast, readXlsx(readFileSync(resolve(option('--from')))), Object.fromEntries(profile.types.map((t) => [t.id, t.name])))
+  if (edited.problems.length) {
+    for (const p of edited.problems) console.error(`✗ ${basename(option('--from'))}: ${p}`)
+    process.exit(1)
+  }
+  proposeOrTake(edited.changes)
+}
 
 // the schema's kinds, to tell a made-up one; without the schema every kind is taken as real
 const schema = join(here, '../vendor/microsoft/reference/bot.schema.yaml-authoring.json')
@@ -132,7 +165,41 @@ if (argv.includes('--facts')) {
   console.log(T.privacy)
   process.exit(0)
 }
-const result = compare(found, profile, cast)
+if (argv.includes('--declared')) {
+  const changes = []
+  for (const file of options('--declared')) {
+    const sheets = tablesOf(file)
+    let read = 0
+    let problem
+    for (const t of sheets) {
+      const r = declaredFrom(t, found, cast, { file: basename(file), lang, agentColumn: option('--agent-column') })
+      if (r.problem) {
+        problem ??= r.problem
+        continue
+      }
+      read++
+      changes.push(...r.changes)
+      if (r.unmatched.length) console.log(T.unmatched(r.unmatched.length, basename(file), `${r.unmatched.slice(0, 5).map((u) => `${T.line} ${u.line} («${u.value}»)`).join(', ')}${r.unmatched.length > 5 ? ', …' : ''}`))
+    }
+    if (!read) tableProblem(file, problem)
+  }
+  proposeOrTake(mergeDeclared(changes))
+}
+let fired
+if (option('--telemetry')) {
+  const file = option('--telemetry')
+  let problem
+  for (const t of tablesOf(file)) {
+    const r = firedFrom(t, found, { file: basename(file), days, agentColumn: option('--agent-column') })
+    if ('problem' in r) problem ??= r.problem
+    else {
+      fired = r
+      break
+    }
+  }
+  if (!fired) tableProblem(file, problem)
+}
+const result = compare(found, profile, cast, fired)
 const looks = reviewCast(result)
 const roles = Object.values(result.roles)
 console.log(T.found(found.length, roles.filter((r) => r === 'orchestrator').length, roles.filter((r) => r === 'specialist').length))