hobots 1.5.1 → 1.7.0

package/docs/concepts.md

@@ -8,42 +8,55 @@ Os defaults numéricos **não** estão aqui — eles vivem em [Tempos e interval
 
 ## Mapa rápido
 
-| Conceito | Em uma frase | Quando você usa |
-| --- | --- | --- |
-| [Evento](#evento) | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage` |
-| [Level](#level-severity) | A gravidade do evento | Para separar o que acorda alguém do que é só registro |
-| [Fingerprint](#fingerprint) | A chave de agrupamento dos eventos em issues | Quando o agrupamento automático erra |
-| [Scope](#scope) | A mochila de contexto que viaja com todo evento | Você raramente mexe direto; mexe pelos `set*` |
-| [withScope](#withscope) | Um scope temporário e isolado | Contexto que **não** deve vazar para o resto do programa |
-| [Tag](#tag) | Rótulo curto e indexável (`string` → `string`) | Você vai **filtrar** ou **agrupar** por isso |
-| [Context](#context) | Grupo nomeado de dados estruturados | Você vai **ler** isso ao abrir o evento |
-| [Extra](#extra) | Depósito livre, sem estrutura | Não é filtro nem grupo coerente — é anexo |
-| [Breadcrumb](#breadcrumb) | Migalha da trilha que levou até o erro | Marcar cada passo relevante do robô |
-| [Transaction](#transaction) | Unidade de trabalho nomeada, com duração | Medir quanto uma rotina inteira demorou |
-| [Span](#span) | Uma etapa medida dentro da transaction | Descobrir **onde** o tempo foi gasto |
-| [ctx.tx](#transaction-de-run-ctxtx) | A transaction que o SDK já abriu para a run | Medir as etapas de um handler do Manager |
-| [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece | Volume alto demais para enviar tudo |
-| [Check-in](#check-in) | Par de avisos "comecei" / "terminei" de um job agendado | Cron que precisa ser vigiado |
-| [Heartbeat](#heartbeat) | Batimento "estou vivo" | Saber que o robô está de pé, mesmo parado |
-| [instanceId](#instanceid) | A identidade da instância do robô | Sempre — é obrigatório no `init()` |
-| [Release e environment](#release-e-environment) | Qual versão, em qual ambiente | Separar produção de homologação; achar a versão que quebrou |
-| [Run](#run) | Uma execução solicitada no app | O Manager inteiro gira em volta disso |
-| [Claim](#claim) | O ato de um agente pegar uma run para si | Entender por que dois agentes nunca colidem |
-| [Drain mode](#drain-mode) | O agente acelera o poll enquanto tem trabalho | Entender o ritmo do polling |
-| [Fila, flush e close](#fila-flush-e-close) | Nada é enviado na hora — vai para uma fila | Encerrar o processo sem perder telemetria |
-| [beforeSend](#beforesend) | O último gancho antes do envio | Censurar ou descartar eventos |
+| Conceito                                                | Em uma frase                                             | Quando você usa                                             |
+| ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------- |
+| [Evento](#evento)                                       | Uma foto de algo que aconteceu — um erro ou uma mensagem | `captureException` / `captureMessage`                       |
+| [Level](#level-severity)                                | A gravidade do evento                                    | Para separar o que acorda alguém do que é só registro       |
+| [Fingerprint](#fingerprint)                             | A chave de agrupamento dos eventos em issues             | Quando o agrupamento automático erra                        |
+| [Scope](#scope)                                         | A mochila de contexto que viaja com todo evento          | Você raramente mexe direto; mexe pelos `set*`               |
+| [withScope](#withscope)                                 | Um scope temporário e isolado                            | Contexto que **não** deve vazar para o resto do programa    |
+| [Tag](#tag)                                             | Rótulo curto e indexável (`string` → `string`)           | Você vai **filtrar** ou **agrupar** por isso                |
+| [Context](#context)                                     | Grupo nomeado de dados estruturados                      | Você vai **ler** isso ao abrir o evento                     |
+| [Extra](#extra)                                         | Depósito livre, sem estrutura                            | Não é filtro nem grupo coerente — é anexo                   |
+| [Breadcrumb](#breadcrumb)                               | Migalha da trilha que levou até o erro                   | Marcar cada passo relevante do robô                         |
+| [Transaction](#transaction)                             | Unidade de trabalho nomeada, com duração                 | Medir quanto uma rotina inteira demorou                     |
+| [Span](#span)                                           | Uma etapa medida dentro da transaction                   | Descobrir **onde** o tempo foi gasto                        |
+| [ctx.tx](#transaction-de-run-ctxtx)                     | A transaction que o SDK já abriu para a run              | Medir as etapas de um handler de task                       |
+| [Amostragem](#amostragem-samplerate-e-tracessamplerate) | Enviar só uma fração do que acontece                     | Volume alto demais para enviar tudo                         |
+| [Check-in](#check-in)                                   | Par de avisos "comecei" / "terminei" de um job agendado  | Cron que precisa ser vigiado                                |
+| [Heartbeat](#heartbeat)                                 | Batimento "estou vivo"                                   | Saber que o robô está de pé, mesmo parado                   |
+| [instanceId](#instanceid)                               | A identidade da instância do robô                        | Sempre — é obrigatório no `init()`                          |
+| [Release e environment](#release-e-environment)         | Qual versão, em qual ambiente                            | Separar produção de homologação; achar a versão que quebrou |
+| [Run](#run)                                             | Uma execução solicitada no app                           | As tasks inteiras giram em volta disso                      |
+| [Claim](#claim)                                         | O ato de um agente pegar uma run para si                 | Entender por que dois agentes nunca colidem                 |
+| [Drain mode](#drain-mode)                               | O agente acelera o poll enquanto tem trabalho            | Entender o ritmo do polling                                 |
+| [Fila, flush e close](#fila-flush-e-close)              | Nada é enviado na hora — vai para uma fila               | Encerrar o processo sem perder telemetria                   |
+| [beforeSend](#beforesend)                               | O último gancho antes do envio                           | Censurar ou descartar eventos                               |
 
 > **Nota de manutenção:** esta página é a fonte canônica das explicações de conceito. As outras páginas da doc, o `README.md` do pacote e os tooltips do app parafraseiam daqui — quando um conceito muda, muda aqui primeiro.
 
+## O SDK e os módulos do app
+
+Cada API do SDK alimenta um módulo do app da Hobots (app.hobots.app). O mapa:
+
+| No SDK | No app |
+| --- | --- |
+| **Projeto** — o "funcionário digital"; dono do Client Secret (`hb_…`) que autentica tudo | **Configurações → Projetos** (é lá que você copia a credencial) |
+| **Agente / instância** — o par `(project_id, instance_id)`; heartbeat e poll de tasks convergem nele | Módulo **Agentes** (uptime, performance) |
+| **[Evento](#evento)** agrupado em **issue** — `captureException` / `captureMessage` | Módulo **Issues** |
+| **Monitor (cron)** — `withMonitor` / `checkIn` com `schedule` | Módulo **Monitores** |
+| **[Transaction](#transaction) / spans** — `startTransaction` (e [`ctx.tx`](#transaction-de-run-ctxtx) dentro de uma run) | Performance no módulo **Agentes**; nas execuções, a aba de performance da solicitação |
+| **Task / [run](#run)** — `register('task-slug', …)` casa com o `task_slug` do formulário | Módulo **Solicitações** (formulários em **Configurações → Formulários**) |
+
 ---
 
 ## Evento
 
-Um **evento** é a foto de um instante que vale a pena registrar: uma exceção que estourou ou uma mensagem que você mandou. É a unidade básica do Monitor.
+Um **evento** é a foto de um instante que vale a pena registrar: uma exceção que estourou ou uma mensagem que você mandou. É a unidade básica da telemetria.
 
 Quando você chama `captureException` ou `captureMessage`, o SDK monta o evento com o que a exceção traz (tipo, mensagem, stack trace com os frames em ordem) e **anexa tudo que está no [scope](#scope)** naquele momento: tags, usuário, contexts, extras e a trilha de [breadcrumbs](#breadcrumb). Depois disso o evento vai para a [fila](#fila-flush-e-close) e é enviado em lote.
 
-No servidor, eventos parecidos são agrupados numa **issue** — é por isso que 4.000 falhas do mesmo timeout não viram 4.000 linhas na sua tela. Quem decide o que é "parecido" é o [fingerprint](#fingerprint).
+No servidor, eventos parecidos são agrupados numa **issue** — o que você vê no módulo Issues do app. É por isso que 4.000 falhas do mesmo timeout não viram 4.000 linhas na sua tela. Quem decide o que é "parecido" é o [fingerprint](#fingerprint).
 
 ```js
 Hobots.captureException(error);
@@ -112,7 +125,7 @@ Dois pontos importantes:
 `withScope` executa um callback com uma **cópia isolada** do scope. O que você escrever lá dentro vale para os eventos capturados dentro do callback e **não vaza** para fora.
 
 ```js
-Hobots.withScope((scope) => {
+Hobots.withScope(scope => {
   scope.setTag('lote', '128').setFingerprint(['reprocessamento']);
   Hobots.captureMessage('Reprocessando lote 128');
 });
@@ -172,11 +185,11 @@ Hobots.setExtra('tentativas', [1, 2, 3]);
 
 É deliberadamente o menos estruturado dos três, e por isso o critério de escolha é simples:
 
-| Você vai… | Use |
-| --- | --- |
-| filtrar, agrupar, contar por isso | [tag](#tag) |
-| ler isso como um conjunto coerente | [context](#context) |
-| nenhum dos dois — é só um dado a mais | **extra** |
+| Você vai…                             | Use                 |
+| ------------------------------------- | ------------------- |
+| filtrar, agrupar, contar por isso     | [tag](#tag)         |
+| ler isso como um conjunto coerente    | [context](#context) |
+| nenhum dos dois — é só um dado a mais | **extra**           |
 
 Extra não é indexado: não dá para filtrar por ele nem construir gráfico com ele. Se você se pegar querendo isso, o campo era uma tag.
 
@@ -207,7 +220,7 @@ Tamanho do buffer: [`maxBreadcrumbs`](./api-reference.md#initoptions).
 
 Uma **transaction** é uma unidade de trabalho **nomeada** e **medida**: ela começa, termina, e o que fica registrado é quanto tempo levou. É a resposta para "quanto demora minha rotina de emissão?" — e, quando você adiciona [spans](#span), para "onde foram esses minutos?".
 
-Enquanto o [evento](#evento) responde *o que quebrou*, a transaction responde *quanto tempo levou*. São os dois eixos do Monitor.
+Enquanto o [evento](#evento) responde _o que quebrou_, a transaction responde _quanto tempo levou_. São os dois eixos da telemetria.
 
 ```js
 const tx = Hobots.startTransaction('processar-lote', 'rpa.job');
@@ -226,7 +239,7 @@ Três coisas que valem saber:
 
 O `status` default é `'ok'`; encadeáveis: `setStatus`, `setName`, `setTag`.
 
-Dentro de um handler do Manager você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx).
+Dentro de um handler de task você **não** cria transaction — já existe uma em [`ctx.tx`](#transaction-de-run-ctxtx), e o `startTransaction()` chamado lá dentro devolve exatamente ela.
 
 ## Span
 
@@ -249,7 +262,7 @@ O `op` é a categoria (útil para agrupar "todas as queries") e a `description`
 
 ## Transaction de run (ctx.tx)
 
-Dentro de um handler do Manager você **não precisa** criar uma transaction: o SDK já abriu uma para aquela execução e entregou em `ctx.tx`. Ela nasce quando o agente captura a run, é **correlacionada** à execução pelo `run_id`, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina — você nunca chama `ctx.tx.finish()`.
+Dentro de um handler de task você **não precisa** criar uma transaction: o SDK já abriu uma para aquela execução e entregou em `ctx.tx`. Ela nasce quando o agente captura a run, é **correlacionada** à execução pelo `run_id`, recebe o status conforme o desfecho (`ok`, `error` ou `cancelled`) e é **finalizada automaticamente** quando o handler termina — você nunca chama `ctx.tx.finish()`.
 
 O que sobra para você é a parte interessante: marcar as **etapas** do trabalho com [spans](#span). Cada `startChild` vira uma barra no waterfall da aba de performance daquela execução no app.
 
@@ -270,9 +283,9 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 
 Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da run — o waterfall só fica com uma barra. Cada span que você abre é uma resposta a mais para "onde foram os 4 minutos".
 
-- **Não chame `Hobots.startTransaction()` dentro de um handler.** Você criaria uma segunda transaction, **sem** correlação com a run, e ela não apareceria na execução.
-- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale para as transactions que **você** abre com `startTransaction()`.
-- O nome é `run:<task>` e o `op` é `manager.run`, preenchidos pelo SDK.
+- **`Hobots.startTransaction()` dentro de um handler devolve a própria `ctx.tx`.** Cada execução tem exatamente **uma** transaction: o SDK detecta o contexto da run e reutiliza a transaction dela em vez de criar uma segunda — os spans caem no mesmo waterfall. Fora de um handler, `startTransaction()` cria uma transaction nova, sem `run_id`.
+- `ctx.tx` **não respeita o `tracesSampleRate`** — toda run gera uma transaction. A amostragem vale para as transactions que **você** abre com `startTransaction()` fora de uma run.
+- O nome é `run:<task>` e o `op` é `hobots.task`, preenchidos pelo SDK.
 
 ## Amostragem (sampleRate e tracesSampleRate)
 
@@ -280,9 +293,9 @@ Sem nenhum `startChild` a transaction ainda existe e ainda mede o tempo total da
 
 São dois controles independentes, os dois de `0` a `1`:
 
-| Opção | Afeta | `0.1` significa |
-| --- | --- | --- |
-| `sampleRate` | [eventos](#evento) (`captureException`, `captureMessage`) | ~10% dos erros são enviados |
+| Opção              | Afeta                                                         | `0.1` significa                    |
+| ------------------ | ------------------------------------------------------------- | ---------------------------------- |
+| `sampleRate`       | [eventos](#evento) (`captureException`, `captureMessage`)     | ~10% dos erros são enviados        |
 | `tracesSampleRate` | [transactions](#transaction) abertas por `startTransaction()` | ~10% das transactions são enviadas |
 
 O sorteio é por item, no momento em que ele é criado — nunca "1 a cada 10", e sim 10% de chance cada.
@@ -319,7 +332,7 @@ Detalhes que importam:
 
 O **heartbeat** é um batimento periódico dizendo "estou vivo". O servidor conhece a cadência esperada e marca a instância como **offline** quando os batimentos param.
 
-É o complemento do [check-in](#check-in): check-in vigia *execuções agendadas*, heartbeat vigia *o processo*. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
+É o complemento do [check-in](#check-in): check-in vigia _execuções agendadas_, heartbeat vigia _o processo_. Um robô que fica de plantão esperando trabalho não tem cron para monitorar — mas você ainda quer saber quando a VM dele caiu.
 
 ```js
 Hobots.init({
@@ -338,11 +351,13 @@ Dois detalhes:
 
 O timer do heartbeat é `unref`'d — ele **não** segura o processo vivo.
 
+Com `tasks: true`, o heartbeat é **opcional**: o próprio poll de tasks já marca a presença do agente no painel. Ele continua essencial para agentes só de telemetria.
+
 ## instanceId
 
 O **`instanceId`** é a identidade da instância do robô: qual VM, qual container, qual máquina. É **obrigatório** no `init()` e deve ser **estável entre reinícios** (`vm-cliente-01`, `container-nfe-3`) — se você gerar um valor novo a cada boot, o app vê uma frota de robôs fantasmas em vez de um robô que reiniciou.
 
-O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo tempo: o [heartbeat](#heartbeat) do Monitor e o agente do [Manager](./manager.md) enviam o mesmo `instanceId`. O servidor correlaciona os dois, e o robô aparece como **um agente só** no painel — sem nenhuma configuração extra.
+O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo tempo: o [heartbeat](#heartbeat) e o agente de [tasks](./tasks.md) enviam o mesmo `instanceId`. O servidor correlaciona os dois, e o robô aparece como **um agente só** no módulo Agentes — sem nenhuma configuração extra.
 
 ## Release e environment
 
@@ -350,8 +365,8 @@ O que o torna especial é que ele é a identidade dos **dois** canais ao mesmo t
 
 Servem a duas perguntas concretas:
 
-- *"quebrou desde quando?"* — com `release`, você compara o antes e o depois de um deploy e sabe qual versão introduziu o erro.
-- *"isso é real ou é teste?"* — com `environment`, o ruído da homologação não polui os alertas de produção.
+- _"quebrou desde quando?"_ — com `release`, você compara o antes e o depois de um deploy e sabe qual versão introduziu o erro.
+- _"isso é real ou é teste?"_ — com `environment`, o ruído da homologação não polui os alertas de produção.
 
 `environment` default é `production`. Se você roda homologação sem definir isso, os dois ambientes se misturam na mesma issue — vale configurar no primeiro dia.
 
@@ -359,7 +374,7 @@ Servem a duas perguntas concretas:
 
 Uma **run** (execução) é um pedido concreto de trabalho criado no app: alguém preencheu o formulário da task, ou uma automação disparou, e agora existe uma solicitação esperando um agente pegar.
 
-É a unidade em volta da qual o [Manager](./manager.md) inteiro gira. O ciclo de vida no servidor:
+É a unidade em volta da qual as [tasks](./tasks.md) inteiras giram — no app, cada run é uma solicitação no módulo **Solicitações**. O ciclo de vida no servidor:
 
 ```
 pending → claimed → running → succeeded | failed | canceled
@@ -372,7 +387,7 @@ pending → claimed → running → succeeded | failed | canceled
 
 O agente só transiciona para `running`, `succeeded` e `failed`. `pending` e `claimed` são do servidor; `canceled` vem de alguém cancelando no app.
 
-Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu código como o primeiro argumento do handler, junto de um [`RunContext`](./api-reference.md#managertaskhandler--runcontext) com logs, sinal de cancelamento e a [transaction](#transaction-de-run-ctxtx).
+Cada run carrega os **`params`** (o JSON validado do formulário) e chega ao seu código como o primeiro argumento do handler, junto de um [`RunContext`](./api-reference.md#taskhandler--runcontext) com logs, sinal de cancelamento e a [transaction](#transaction-de-run-ctxtx).
 
 ## Claim
 
@@ -406,13 +421,13 @@ Devolve `true` se tudo saiu dentro do tempo e `false` se estourou. `false` **nã
 
 ### `close(timeoutMs?)` — "acabou, encerra"
 
-Encerra tudo, **nesta ordem**: para o agente do Manager (aguardando as runs em execução) → para o heartbeat → faz o flush final e fecha o transport. É sempre a última linha do seu programa.
+Encerra tudo, **nesta ordem**: para o agente de tasks (aguardando as runs em execução) → para o heartbeat → faz o flush final e fecha o transport. É sempre a última linha do seu programa.
 
 > **Atenção:** `close()` é **terminal e sem volta**. Depois dele, todo `captureException`, transaction, check-in ou heartbeat é **descartado** com um aviso no console — não existe `reopen()`. Se o programa precisar voltar a emitir telemetria, chame `Hobots.init()` de novo.
 
-> **Atenção:** o `timeoutMs` do `close()` é aplicado **duas vezes, em sequência** — uma para esperar as runs do Manager, outra para o flush final. `close(15_000)` pode levar até ~30s no pior caso. Se você tem um SIGTERM com prazo curto (Kubernetes, systemd), dimensione por aí.
+> **Atenção:** o `timeoutMs` do `close()` é aplicado **duas vezes, em sequência** — uma para esperar as runs de tasks, outra para o flush final. `close(15_000)` pode levar até ~30s no pior caso. Se você tem um SIGTERM com prazo curto (Kubernetes, systemd), dimensione por aí.
 
-O `flush` cobre a fila do **Monitor**. Os logs de uma run do Manager (`ctx.log`) são um canal separado, com o próprio ritmo — quem espera por eles é o `close()`/`stop()`, ao aguardar a run terminar.
+O `flush` cobre a fila da **telemetria**. Os logs de uma run de task (`ctx.log`) são um canal separado, com o próprio ritmo — quem espera por eles é o `close()`/`stop()`, ao aguardar a run terminar.
 
 Defaults e tempos dos dois: [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
 
@@ -424,9 +439,9 @@ Defaults e tempos dos dois: [Tempos e intervalos](./api-reference.md#tempos-e-in
 Hobots.init({
   clientSecret,
   instanceId: 'vm-cliente-01',
-  beforeSend: (event) => {
+  beforeSend: event => {
     if (event.exception?.type === 'AbortError') return null; // não me interessa
-    delete event.extra?.senha;                                // censura
+    delete event.extra?.senha; // censura
     return event;
   },
 });

package/docs/getting-started.md

@@ -6,7 +6,7 @@
 pnpm add hobots
 ```
 
-Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). O Monitor também funciona no browser para captura de erros.
+Sem dependências de runtime. Requer **Node 18+** (usa o `fetch` global). A telemetria também funciona no browser para captura de erros.
 
 ## Conceitos em 2 minutos
 
@@ -23,13 +23,13 @@ Os termos que aparecem nesta página, em uma frase cada. Explicação completa d
 
 ## O Client Secret
 
-Cada projeto tem **um único Client Secret** — a mesma credencial autentica o Monitor **e** o Manager:
+Cada projeto tem **um único Client Secret** — a mesma credencial autentica a telemetria **e** as tasks:
 
 ```
 hb_<64 hex>
 ```
 
-(Chaves antigas, 64 hex puros, continuam válidas no servidor.) A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos.
+A credencial é **secreta** e viaja sempre no header `Authorization: Bearer` — nunca na URL. Copie o Client Secret no app, em **Configurações → Projetos** — os snippets de integração já vêm prontos.
 
 O SDK fala com a API oficial `https://api2.hobots.app` automaticamente — não há configuração de host no `init()`. Em desenvolvimento, aponte para outro host com a env `HOBOTS_API_URL`:
 
@@ -39,13 +39,13 @@ HOBOTS_API_URL=http://localhost:3001 node meu-robo.js
 
 Veja [Protocolo & transporte](./protocol.md) para os endpoints derivados da URL base.
 
-## Monitor e Manager — qual usar
+## Telemetria e tasks — qual usar
 
 As duas capabilities vivem no mesmo `init()` e você usa **uma, outra ou as duas**:
 
 - Quer só saber se o robô quebrou, quanto demora e se está vivo? → `init({ clientSecret, heartbeat: true })`.
-- Quer disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, manager: true })` + `register()` + `start()`.
-- Ambos? Passe `heartbeat` e `manager` no **mesmo `init()`**. É o cenário do
+- Quer disparar o robô sob demanda a partir de um formulário no app? → `init({ clientSecret, tasks: true })` + `register()` + `start()`.
+- Ambos? Passe `heartbeat` e `tasks` no **mesmo `init()`**. É o cenário do
   [`full.ts`](../../hobots-sdk-demos/src/full.ts) nos demos do SDK.
 
 ## O `init` único
@@ -57,7 +57,7 @@ Hobots.init({
   clientSecret: 'hb_<64 hex>',
   environment: 'production',
   release: 'robo-nfe@1.4.2',
-  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente Manager
+  instanceId: 'vm-cliente-01', // identidade única: heartbeat + agente de tasks
   heartbeat: true, // "estou vivo" a cada 30s
 });
 
@@ -71,11 +71,11 @@ try {
 }
 ```
 
-Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Monitor](./monitor.md).
+Chame `Hobots.init` **uma vez**, o mais cedo possível no processo. Detalhes em [Telemetria](./monitor.md).
 
-## Primeiro agente (Manager)
+## Primeiro agente (tasks)
 
-Habilite a execução sob demanda com o campo `manager` no mesmo `init()`:
+Habilite a execução sob demanda com o campo `tasks` no mesmo `init()`:
 
 ```js
 import * as Hobots from 'hobots';
@@ -83,7 +83,7 @@ import * as Hobots from 'hobots';
 Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
-  manager: true, // ou { pollIntervalMs, concurrency, ... }
+  tasks: true, // ou { pollIntervalMs, concurrency, ... }
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -93,21 +93,21 @@ Hobots.register('processar-nfe', async (params, ctx) => {
 Hobots.start(); // mantém o processo vivo até stop()/close()
 ```
 
-> O `instanceId` é a identidade dos **dois** canais (heartbeat do Monitor e agente do Manager) — o robô aparece como **um agente só** no painel, sem configuração extra.
+> O `instanceId` é a identidade dos **dois** canais (heartbeat e poll de tasks) — o robô aparece como **um agente só** no módulo Agentes do app, sem configuração extra. Com `tasks: true`, o heartbeat é opcional: o próprio poll já marca a presença do agente.
 
-Detalhes (cancelamento, concorrência, idempotência) em [Manager](./manager.md).
+As execuções aparecem no módulo **Solicitações** do app; o `task` do `register()` é o `task_slug` do formulário em **Configurações → Formulários**. Detalhes (cancelamento, concorrência, idempotência) em [Tasks](./tasks.md).
 
 ## Encerramento
 
-`close()` encerra tudo na ordem certa: para o Manager (aguardando a run atual), o heartbeat e faz o flush final do transport.
+`close()` encerra tudo na ordem certa: para o polling de tasks (aguardando a run atual), o heartbeat e faz o flush final do transport.
 
-Sem Manager iniciado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
+Sem `start()` chamado, o SDK não segura o processo (timers `unref`'d), mas faça o flush final para não perder eventos em buffer:
 
 ```js
 await Hobots.close(2000);
 ```
 
-Com o Manager, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
+Com as tasks, `start()` segura o processo por design. Encerre de forma graciosa aguardando a run atual:
 
 ```js
 process.on('SIGINT', () => {
@@ -115,6 +115,6 @@ process.on('SIGINT', () => {
 });
 ```
 
-> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, outra no flush final. O `close(15_000)` acima pode levar até ~30s no pior caso. Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí. Os defaults, quando você omite o argumento, estão em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
+> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs de tasks, outra no flush final. O `close(15_000)` acima pode levar até ~30s no pior caso. Se o seu SIGTERM tem prazo curto (Kubernetes, systemd), dimensione por aí. Os defaults, quando você omite o argumento, estão em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
 
 Para parar de aceitar execuções **sem** derrubar a telemetria, use `Hobots.stop(timeoutMs?)`. Conceito das duas funções em [Fila, flush e close](./concepts.md#fila-flush-e-close).

package/docs/monitor.md

@@ -1,6 +1,6 @@
-# Monitor
+# Telemetria
 
-Capability de telemetria: erros, performance, crons e uptime. Sempre ativa no `init()` único:
+Capability de telemetria: erros (módulo **Issues**), performance e uptime (módulo **Agentes**), crons (módulo **Monitores**). Sempre ativa no `init()` único:
 
 ```js
 import * as Hobots from 'hobots';
@@ -114,11 +114,11 @@ tx.finish(); // só aqui a transaction é enviada (respeitando tracesSampleRate)
 - A decisão de amostragem acontece no **`startTransaction()`**, não no `finish()`. Esquecer o `finish()` de um span não perde o dado: ele é fechado no instante em que a transaction fecha.
 - Uma transaction leva as tags do `init()` e as que você marcar com `tx.setTag()` — ela **não** herda as tags do scope.
 
-Dentro de um handler do Manager não abra transaction: já existe uma em [`ctx.tx`](./concepts.md#transaction-de-run-ctxtx).
+Dentro de um handler de task, `startTransaction()` **retorna a transaction da própria run** ([`ctx.tx`](./concepts.md#transaction-de-run-ctxtx)) em vez de criar uma segunda — cada execução tem exatamente **uma** transaction. Fora de um handler, ela cria uma transaction nova, sem correlação com run nenhuma.
 
 ## Crons (check-ins)
 
-Monitora jobs agendados: um check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
+Monitora jobs agendados — o módulo **Monitores** do app: um check-in `in_progress` na entrada, `ok`/`error` na saída, com duração medida. O jeito recomendado é `withMonitor`, que faz o par e captura exceções:
 
 ```js
 await Hobots.withMonitor(
@@ -153,7 +153,7 @@ Hobots.init({
 
 O primeiro batimento sai **na hora** em que o `init()` roda — não depois do primeiro intervalo. O batimento também carrega o intervalo configurado: é assim que o servidor sabe quanto silêncio é normal antes de declarar o robô offline.
 
-Essa identidade é a mesma que o Manager envia no poll (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** em Monitor → Agentes automaticamente.
+Essa identidade é a mesma que o poll de tasks envia (`agent.instance_id`) — os dois canais derivam do `instanceId` do `init()`, então o robô aparece como **um agente só** no módulo Agentes automaticamente. Por isso, com `tasks: true` o heartbeat é **opcional** (o poll já marca a presença do agente); ele é essencial para agentes só de telemetria.
 
 ## Flush e close
 
@@ -161,13 +161,13 @@ Nada é enviado na hora: cada evento, transaction, check-in e heartbeat entra nu
 
 ```js
 await Hobots.flush(2000); // envia o que está em buffer, mantém o SDK vivo
-await Hobots.close(2000); // para o Manager (se ativo) + heartbeat + flush final do transport
+await Hobots.close(2000); // para o polling de tasks (se ativo) + heartbeat + flush final do transport
 ```
 
 O `timeoutMs` é opcional nas duas — o default é 5s (veja [Tempos e intervalos](./api-reference.md#tempos-e-intervalos)). As duas devolvem `false` quando estouram o prazo, o que significa que o SDK parou de esperar, **não** que os dados foram perdidos: os envios em voo continuam tentando enquanto o processo existir.
 
-Chame `close` antes do processo sair. Os timers do Monitor são `unref`'d, então a telemetria **não** segura o processo vivo sozinha (só o `start()` do Manager segura).
+Chame `close` antes do processo sair. Os timers da telemetria são `unref`'d, então ela **não** segura o processo vivo sozinha (só o `start()` das tasks segura).
 
 > **Atenção:** `close()` é **terminal**. Depois dele, todo evento, transaction, check-in ou heartbeat novo é **descartado** com aviso no console — não existe `reopen()`. Se o programa precisar voltar a emitir telemetria, chame `Hobots.init()` de novo.
 
-> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs do Manager, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.
+> **Atenção:** o `timeoutMs` do `close()` é gasto **duas vezes, em sequência** — uma esperando as runs de tasks, outra no flush final. `close(15_000)` pode levar até ~30s no pior caso. Dimensione por aí se o seu SIGTERM tem prazo curto.

package/docs/protocol.md

@@ -2,7 +2,7 @@
 
 O SDK é um **cliente HTTP puro**, sem dependências de runtime: ele só fala com o app da Hobots por HTTP. Não abre conexão com banco e **não** roda `SKIP LOCKED` — a reivindicação atômica de runs é server-side (veja o fim desta página).
 
-Os arquivos `src/protocol.ts` e `src/manager/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift.
+Os arquivos `src/protocol.ts` e `src/tasks/protocol.ts` são a **fonte de verdade do wire format**: o app valida os payloads com zod travados nesses tipos (`satisfies z.ZodType<...>`), então não podem sofrer drift. Todos os tipos são exportados por `hobots/protocol` (e reexportados pelo import raiz `hobots`).
 
 ## O Client Secret e os endpoints derivados
 
@@ -14,20 +14,18 @@ hb_<64 hex>
 
 | Canal | Endpoint | Autenticação |
 | --- | --- | --- |
-| Monitor (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
-| Manager (execução) | `<baseUrl>/v1/manager/*` | `Authorization: Bearer <clientSecret>` |
+| Telemetria (ingestão) | `POST <baseUrl>/v1/ingest` | `Authorization: Bearer <clientSecret>` |
+| Tasks (execução) | `<baseUrl>/v1/tasks/*` | `Authorization: Bearer <clientSecret>` |
 
-`resolveConfig({ clientSecret }) → { key, baseUrl, ingestEndpoint, managerBaseUrl }` (em `src/config.ts`, com a constante `DEFAULT_BASE_URL = 'https://api2.hobots.app'`; em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base). A credencial é **secreta** (formato `hb_<64 hex>`; chaves antigas de 64 hex puros continuam válidas no servidor) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
+A resolução da credencial nos endpoints é interna ao `init()` (em `src/config.ts`, com a constante exportada `DEFAULT_BASE_URL = 'https://api2.hobots.app'`); o resultado fica acessível em `getClient()?.config` → `{ key, baseUrl, ingestEndpoint, tasksBaseUrl }`. Em desenvolvimento a env `HOBOTS_API_URL` sobrescreve a URL base — apenas `http(s)`, e `http` para host fora de loopback gera aviso porque o secret trafega sem TLS. A credencial é **secreta** (formato `hb_` + 64 hex — chaves de outro formato são rejeitadas no `init()`) e viaja **só no header** `Authorization: Bearer` — nunca na URL da requisição.
 
-> As DSNs foram **descontinuadas** em favor do Client Secret — tanto a antiga do Monitor (public key na URL, `POST /v1/ingest/<key>`, que responde **410** e o transport descarta sem retry) quanto a de key-na-URL (`https://<secretKey>@host/<slug>`). Copie o Client Secret em **Configurações → Projetos** no app.
-
-## Monitor — ingestão
+## Telemetria — ingestão
 
 Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Bearer. O transport mantém uma fila em memória, agrupa itens em envelopes e faz POST via `fetch`.
 
 ```jsonc
 {
-  "sdk": { "name": "hobots", "version": "1.0.0" },
+  "sdk": { "name": "hobots", "version": "2.0.0" },
   "sent_at": "2024-01-01T00:00:00.000Z",
   "items": [
     { "type": "event",       "payload": { /* EventPayload */ } },
@@ -40,24 +38,24 @@ Endpoint fixo `POST /v1/ingest` recebe **envelopes** JSON autenticados por Beare
 
 Tipos de item: `event`, `transaction`, `check_in`, `heartbeat` (definidos em `hobots/protocol`).
 
-Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run do Manager](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) é correlacionada à execução, e o que permite o app montar o waterfall de performance dentro da solicitação. Transactions abertas com `startTransaction()` não têm esse campo.
+Um `transaction` pode carregar `run_id`: é assim que a [transaction de uma run](./concepts.md#transaction-de-run-ctxtx) (`ctx.tx`) é correlacionada à execução, e o que permite o app montar o waterfall de performance dentro da solicitação. Transactions abertas com `startTransaction()` fora de uma run não têm esse campo.
 
 **Flush & retries:** o transport flusha por `flushIntervalMs` ou ao atingir `maxBatchSize`. Ladder de retry de 3 tentativas; respostas 4xx (exceto 429) são descartadas sem retry; a fila tem teto fixo e descarta os itens **mais antigos** ao encher. Todos os valores em [Tempos e intervalos](./api-reference.md#tempos-e-intervalos).
 
-## Manager — polling e reporte
+## Tasks — polling e reporte
 
-Dois endpoints sob `<baseUrl>/v1/manager`, ambos com `Authorization: Bearer <clientSecret>` (a credencial única do projeto):
+Dois endpoints sob `<baseUrl>/v1/tasks`, ambos com `Authorization: Bearer <clientSecret>` (a credencial única do projeto):
 
-### `POST /v1/manager/poll`
+### `POST /v1/tasks/poll`
 
-Corpo `ManagerPollRequest`:
+Corpo `PollRequest`:
 
 ```jsonc
 {
   "agent": {
     "instance_id": "vm-01",       // identidade canônica do agente (obrigatória)
     "name": "VM 01",
-    "version": "1.0.0",
+    "version": "2.0.0",
     "host": "vm-01",
     "tasks": ["processar-nfe"]
   },
@@ -66,15 +64,15 @@ Corpo `ManagerPollRequest`:
 }
 ```
 
-Resposta `ManagerPollResponse` = `{ runs: ManagerRunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
+Resposta `PollResponse` = `{ runs: RunDescriptor[] }`, cada `{ id, task, params, form, source, created_at }`.
 
-O `agent.instance_id` é a **mesma identidade** do heartbeat do Monitor (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente.
+O `agent.instance_id` é a **mesma identidade** do heartbeat de telemetria (`instance_id`): o servidor correlaciona os dois canais numa tabela `agents` por `(project_id, instance_id)`. Com o `init()` único, os dois derivam do `instanceId` — o robô aparece como um agente só no painel automaticamente. O próprio poll marca a presença do agente (`last_poll_at`), por isso o heartbeat é opcional quando as tasks estão habilitadas.
 
 **Backoff:** um request por poll; o loop decide o ritmo. HTTP 401 (key rejeitada) → retry lento a 30s com log throttled; outros erros → ladder `[1s, 4s, 16s]`.
 
-### `PATCH /v1/manager/runs/{id}`
+### `PATCH /v1/tasks/runs/{id}`
 
-Corpo `ManagerRunUpdateRequest`:
+Corpo `RunUpdateRequest`:
 
 ```jsonc
 {
@@ -88,17 +86,15 @@ Corpo `ManagerRunUpdateRequest`:
 - Ordem garantida `running → logs → terminal` (PATCHes serializados numa cadeia de promise).
 - Retry `[1s, 4s, 16s]`; 4xx exceto 429 é terminal (**409** = run cancelada / transição inválida → marca a run como morta e dispara `ctx.signal`).
 - Todo PATCH atualiza `last_report_at` no servidor (relógio do servidor) — é o **sinal de vida da run**. O heartbeat de cancelamento (PATCH `running` vazio a cada `cancelCheckIntervalMs`, máx 15s) garante reporte contínuo; um sweep server-side marca como `failed` com erro `AgentTerminated` ("execução encerrada inesperadamente") toda run `running` sem reporte há **60s**, sem re-entrega. No exit path (sinal/erro fatal com runs ativas), o SDK envia um único PATCH `failed`/`AgentTerminated` com timeout curto (~2s), sem retry — o sweep é o backstop.
-- O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` de SDKs antigos (dados de negócio podem ser sensíveis e não são coletados).
+- O protocolo **não transporta resultado** de execução: o retorno do handler é ignorado pelo SDK e o servidor descarta qualquer campo `result` (dados de negócio podem ser sensíveis e não são coletados).
 
-Ciclo de vida completo da run no servidor: `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed`.
+Ciclo de vida completo da run no servidor (`RunStatus`): `pending → claimed → running → succeeded | failed | canceled`. O agente só transiciona para `running`/`succeeded`/`failed` (`RunUpdateStatus`).
 
 ## Onde vive o claim atômico
 
-O `POST /v1/manager/poll` no app chama `claimPendingRuns()` em
-[`apps/api/lib/manager/claim.ts`](../../../apps/api/lib/manager/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
+O `POST /v1/tasks/poll` no app chama `claimPendingRuns()` em
+[`apps/api/lib/tasks/claim.ts`](../../../apps/api/lib/tasks/claim.ts): um CTE que seleciona runs `pending` vencidas com `FOR UPDATE SKIP LOCKED` e as promove a `claimed` num único `UPDATE ... RETURNING`. Isso garante que dois agentes concorrentes nunca peguem a mesma run. **Nada disso está no SDK** — ele só faz o HTTP.
 
 ## Identidade do SDK
 
-`SDK_NAME = 'hobots'` e `SDK_VERSION` ficam em `src/utils.ts` e vão em todo envelope (campo `sdk`) e no `agent.version` do poll.
-
-> **Nota de manutenção:** `SDK_VERSION` é uma constante fixa e precisa ser mantida em sincronia com a `version` do `package.json` manualmente ao publicar.
+`SDK_NAME = 'hobots'` e `SDK_VERSION` ficam em `src/utils.ts` e vão em todo envelope (campo `sdk`) e no `agent.version` do poll. A `SDK_VERSION` é **injetada pelo build** (o `define` do tsup lê a `version` do `package.json`) — não há sincronização manual ao publicar.