hobots 2.3.0 → 3.0.0

package/dist/protocol.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  InstanceInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\n\n/**\n * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e\n * 'warning' viram issue; 'success' é ingerido e nunca abre issue.\n * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)\n * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.\n */\nexport type EventType = 'fatal' | 'error' | 'warning' | 'success';\n\n/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */\nexport type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: BreadcrumbLevel;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  type: EventType;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: string;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: string;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Tipos do protocolo do Hobots (SDK → servidor).\n *\n * Este arquivo é a fonte de verdade do wire format e só pode reexportar tipos:\n * o app valida os payloads com zod e trava o drift via `satisfies z.ZodType<...>`\n * contra estes tipos (importados de `hobots/protocol`).\n */\n\nimport type { EnvironmentInput } from './environment-protocol';\nimport type { MachineSnapshot } from './machine-protocol';\n\n// Wire format de tasks (agente ↔ servidor) — reexportado aqui para o app\n// consumir tudo de `hobots/protocol`.\nexport type {\n  RunStatus,\n  RunUpdateStatus,\n  RunLogLevel,\n  RunLogEntry,\n  InstanceInfo,\n  PollRequest,\n  RunDescriptor,\n  PollResponse,\n  RunCreateRequest,\n  RunCreateResponse,\n  RunError,\n  RunProgress,\n  RunUpdateRequest,\n  RunUpdateResponse,\n  RunItemStatus,\n  RunItemInput,\n  RunItemsCreateRequest,\n  RunItemsCreateResponse,\n  RunAttachmentContentType,\n  RunAttachmentCreateRequest,\n  RunAttachmentCreateResponse,\n  RunAttachmentConfirmRequest,\n  RunAttachmentConfirmResponse,\n} from './tasks/protocol';\n\n// Snapshot de recursos da máquina — usado no heartbeat, no poll e em contexts.machine.\nexport type { MachineProcess, MachineSnapshot } from './machine-protocol';\nexport type { Environment, EnvironmentInput } from './environment-protocol';\n\n/**\n * Tipo de um evento — o que ele é, não o quanto ele fala. Só 'fatal', 'error' e\n * 'warning' viram issue; 'success' é ingerido e nunca abre issue.\n * Ruído de log não é evento: para isso existem os logs da execução (RunLogLevel)\n * e as breadcrumbs, que têm níveis próprios com 'debug'/'info'.\n */\nexport type EventType = 'fatal' | 'error' | 'warning' | 'success';\n\n/** Nível de uma breadcrumb — trilha do que aconteceu antes, aqui log é bem-vindo. */\nexport type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';\n\n/** Frames em ordem innermost-first (mesma ordem impressa pelo V8). */\nexport interface StackFrame {\n  function?: string;\n  filename?: string;\n  lineno?: number;\n  colno?: number;\n  in_app: boolean;\n}\n\nexport interface Breadcrumb {\n  /** ISO 8601 */\n  timestamp: string;\n  type?: string;\n  category?: string;\n  message?: string;\n  level?: BreadcrumbLevel;\n  data?: Record<string, unknown>;\n}\n\nexport interface ExceptionData {\n  type: string;\n  value: string;\n  stacktrace?: { frames: StackFrame[] };\n}\n\nexport interface EventUser {\n  id?: string;\n  username?: string;\n  email?: string;\n}\n\nexport interface EventPayload {\n  /** uuid v4 sem hífens (32 hex), gerado pelo SDK */\n  event_id: string;\n  /** ISO 8601 */\n  timestamp: string;\n  type: EventType;\n  message?: string;\n  exception?: ExceptionData;\n  /** Override de agrupamento; quando ausente o servidor calcula pelo stack trace */\n  fingerprint?: string[];\n  breadcrumbs?: Breadcrumb[];\n  tags?: Record<string, string>;\n  user?: EventUser;\n  contexts?: Record<string, Record<string, unknown>>;\n  extra?: Record<string, unknown>;\n  release?: string;\n  environment?: EnvironmentInput;\n}\n\n/** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */\nexport type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';\n\nexport interface StepData {\n  /** 16 hex */\n  step_id: string;\n  parent_step_id?: string;\n  op?: string;\n  description?: string;\n  status?: StepStatus;\n  /** ISO 8601 */\n  start_timestamp: string;\n  /** ISO 8601 (fim da step) */\n  timestamp: string;\n  data?: Record<string, unknown>;\n}\n\nexport interface TransactionPayload {\n  event_id: string;\n  name: string;\n  op?: string;\n  status: string;\n  start_timestamp: string;\n  timestamp: string;\n  steps: StepData[];\n  tags?: Record<string, string>;\n  release?: string;\n  environment?: EnvironmentInput;\n  /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */\n  run_id?: string;\n}\n\nexport interface HeartbeatPayload {\n  instance_id: string;\n  name?: string;\n  interval_ms: number;\n  /** ISO 8601 */\n  timestamp: string;\n  metadata?: Record<string, unknown>;\n  release?: string;\n  /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */\n  environment?: EnvironmentInput;\n  /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */\n  machine?: MachineSnapshot;\n}\n\nexport type EnvelopeItem =\n  | { type: 'event'; payload: EventPayload }\n  | { type: 'transaction'; payload: TransactionPayload }\n  | { type: 'heartbeat'; payload: HeartbeatPayload };\n\nexport interface Envelope {\n  sdk: { name: string; version: string };\n  /** ISO 8601 */\n  sent_at: string;\n  items: EnvelopeItem[];\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/protocol.d.cts

@@ -1,3 +1,25 @@
+/**
+ * Ambiente lógico onde o robô roda.
+ *
+ * Arquivo-folha do protocolo (não importa nada): referenciado pelo heartbeat, pelo
+ * poll de tasks (`InstanceInfo.environment`) e pelos eventos/transactions, e
+ * reexportado por `hobots/protocol`.
+ *
+ * A fonte única do vocabulário (rótulos em pt-BR, apelidos legados aceitos e a
+ * normalização) vive no servidor, em packages/utils/src/environments.ts — o SDK é
+ * publicado sozinho no npm e não depende do monorepo, então o union é redeclarado
+ * aqui. O servidor normaliza o que chega: valores antigos de texto livre ('prod',
+ * 'qa', 'homologacao') continuam sendo aceitos e classificados.
+ */
+type Environment = 'development' | 'testing' | 'staging' | 'production';
+/**
+ * O que o wire realmente aceita: o ambiente canônico ou uma string legada que o
+ * servidor normaliza ('prod', 'qa', 'homologacao'...). O `string & {}` preserva o
+ * autocomplete dos quatro valores sem fechar a porta para o que já roda em campo
+ * — e mantém os `satisfies z.ZodType<...>` da api fechando contra `z.string()`.
+ */
+type EnvironmentInput = Environment | (string & {});
+
 /**
  * Snapshot dos recursos da máquina onde a instância roda.
  *
@@ -82,6 +104,8 @@ interface InstanceInfo {
     version?: string;
     /** Hostname da máquina */
     host?: string;
+    /** Ambiente da instância — mesmo valor do heartbeat; agentes poll-only só o informam aqui */
+    environment?: EnvironmentInput;
     /** Tasks registradas no agente */
     tasks?: string[];
     /**
@@ -108,7 +132,7 @@ interface RunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
+    /** Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' (informativo; 'agent' = aberta pelo próprio SDK, modo start) */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;
@@ -116,6 +140,19 @@ interface RunDescriptor {
 interface PollResponse {
     runs: RunDescriptor[];
 }
+/**
+ * POST /v1/tasks/runs — modo start do SDK: a própria instância abre a run, que já
+ * nasce 'running' (started_at = now), sem formulário nem solicitante. Dali em diante
+ * ela é reportada pelas mesmas rotas de uma run reivindicada no poll.
+ */
+interface RunCreateRequest {
+    /** slug da task (1..255) — vira task_runs.task_slug */
+    task: string;
+    /** presença da instância — obrigatória: a run nasce vinculada à instância */
+    instance: InstanceInfo;
+}
+/** Resposta (201): o mesmo descritor do poll, com params {}, form null e source 'agent'. */
+type RunCreateResponse = RunDescriptor;
 interface RunError {
     /** ex.: nome da classe do erro */
     type?: string;
@@ -275,7 +312,7 @@ interface EventPayload {
     contexts?: Record<string, Record<string, unknown>>;
     extra?: Record<string, unknown>;
     release?: string;
-    environment?: string;
+    environment?: EnvironmentInput;
 }
 /** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
 type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
@@ -302,7 +339,7 @@ interface TransactionPayload {
     steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
-    environment?: string;
+    environment?: EnvironmentInput;
     /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
     run_id?: string;
 }
@@ -314,6 +351,8 @@ interface HeartbeatPayload {
     timestamp: string;
     metadata?: Record<string, unknown>;
     release?: string;
+    /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */
+    environment?: EnvironmentInput;
     /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */
     machine?: MachineSnapshot;
 }
@@ -337,4 +376,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EnvironmentInput, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload };

package/dist/protocol.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Ambiente lógico onde o robô roda.
+ *
+ * Arquivo-folha do protocolo (não importa nada): referenciado pelo heartbeat, pelo
+ * poll de tasks (`InstanceInfo.environment`) e pelos eventos/transactions, e
+ * reexportado por `hobots/protocol`.
+ *
+ * A fonte única do vocabulário (rótulos em pt-BR, apelidos legados aceitos e a
+ * normalização) vive no servidor, em packages/utils/src/environments.ts — o SDK é
+ * publicado sozinho no npm e não depende do monorepo, então o union é redeclarado
+ * aqui. O servidor normaliza o que chega: valores antigos de texto livre ('prod',
+ * 'qa', 'homologacao') continuam sendo aceitos e classificados.
+ */
+type Environment = 'development' | 'testing' | 'staging' | 'production';
+/**
+ * O que o wire realmente aceita: o ambiente canônico ou uma string legada que o
+ * servidor normaliza ('prod', 'qa', 'homologacao'...). O `string & {}` preserva o
+ * autocomplete dos quatro valores sem fechar a porta para o que já roda em campo
+ * — e mantém os `satisfies z.ZodType<...>` da api fechando contra `z.string()`.
+ */
+type EnvironmentInput = Environment | (string & {});
+
 /**
  * Snapshot dos recursos da máquina onde a instância roda.
  *
@@ -82,6 +104,8 @@ interface InstanceInfo {
     version?: string;
     /** Hostname da máquina */
     host?: string;
+    /** Ambiente da instância — mesmo valor do heartbeat; agentes poll-only só o informam aqui */
+    environment?: EnvironmentInput;
     /** Tasks registradas no agente */
     tasks?: string[];
     /**
@@ -108,7 +132,7 @@ interface RunDescriptor {
         id: string;
         name: string;
     } | null;
-    /** Origem da run: 'hobots' | 'link' | 'schedule' (informativo) */
+    /** Origem da run: 'hobots' | 'link' | 'schedule' | 'agent' (informativo; 'agent' = aberta pelo próprio SDK, modo start) */
     source: string;
     /** ISO 8601 (relógio do servidor) */
     created_at: string;
@@ -116,6 +140,19 @@ interface RunDescriptor {
 interface PollResponse {
     runs: RunDescriptor[];
 }
+/**
+ * POST /v1/tasks/runs — modo start do SDK: a própria instância abre a run, que já
+ * nasce 'running' (started_at = now), sem formulário nem solicitante. Dali em diante
+ * ela é reportada pelas mesmas rotas de uma run reivindicada no poll.
+ */
+interface RunCreateRequest {
+    /** slug da task (1..255) — vira task_runs.task_slug */
+    task: string;
+    /** presença da instância — obrigatória: a run nasce vinculada à instância */
+    instance: InstanceInfo;
+}
+/** Resposta (201): o mesmo descritor do poll, com params {}, form null e source 'agent'. */
+type RunCreateResponse = RunDescriptor;
 interface RunError {
     /** ex.: nome da classe do erro */
     type?: string;
@@ -275,7 +312,7 @@ interface EventPayload {
     contexts?: Record<string, Record<string, unknown>>;
     extra?: Record<string, unknown>;
     release?: string;
-    environment?: string;
+    environment?: EnvironmentInput;
 }
 /** Status de uma step (etapa). `warning` = terminou, mas merece atenção (não é falha). */
 type StepStatus = 'ok' | 'warning' | 'error' | 'cancelled';
@@ -302,7 +339,7 @@ interface TransactionPayload {
     steps: StepData[];
     tags?: Record<string, string>;
     release?: string;
-    environment?: string;
+    environment?: EnvironmentInput;
     /** Correlaciona esta transaction a uma execução de task (ctx.tx dentro de um task handler) */
     run_id?: string;
 }
@@ -314,6 +351,8 @@ interface HeartbeatPayload {
     timestamp: string;
     metadata?: Record<string, unknown>;
     release?: string;
+    /** Ambiente da instância — é ele que o app exibe e que as regras de alerta filtram */
+    environment?: EnvironmentInput;
     /** Recursos da máquina no momento do beat (CPU, memória, disco, processo) */
     machine?: MachineSnapshot;
 }
@@ -337,4 +376,4 @@ interface Envelope {
     items: EnvelopeItem[];
 }
 
-export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload };
+export type { Breadcrumb, BreadcrumbLevel, Envelope, EnvelopeItem, Environment, EnvironmentInput, EventPayload, EventType, EventUser, ExceptionData, HeartbeatPayload, InstanceInfo, MachineProcess, MachineSnapshot, PollRequest, PollResponse, RunAttachmentConfirmRequest, RunAttachmentConfirmResponse, RunAttachmentContentType, RunAttachmentCreateRequest, RunAttachmentCreateResponse, RunCreateRequest, RunCreateResponse, RunDescriptor, RunError, RunItemInput, RunItemStatus, RunItemsCreateRequest, RunItemsCreateResponse, RunLogEntry, RunLogLevel, RunProgress, RunStatus, RunUpdateRequest, RunUpdateResponse, RunUpdateStatus, StackFrame, StepData, StepStatus, TransactionPayload };

package/docs/README.md

@@ -1,49 +1,32 @@
 # Documentação — hobots
 
-SDK JavaScript da **Hobots** para instrumentar agentes (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, para Node 18+ (a telemetria também roda no browser para captura de erros).
+SDK JavaScript da **Hobots** para robôs (RPAs) e integrações. Cliente HTTP puro, sem dependências de runtime, Node 18+.
 
-O SDK expõe **duas capabilities** autenticadas pelo **mesmo Client Secret do agente**, configuradas em **um único `init()`** com **um único import** (`import * as Hobots from 'hobots'`):
+**Tudo é uma task.** Não existe `init()`: a primeira chamada a `register()`/`start()` configura o processo (credenciais do ambiente, heartbeat sempre ligado, captura de erros não tratados). O objeto global `hobots` expõe a execução atual — `hobots.log`, `hobots.items`, `hobots.progress`, `hobots.transaction`… — de qualquer lugar do programa.
 
-| Capability | Como habilita | Para quê |
+| Modo | Chamada | Para quê |
 | --- | --- | --- |
-| **Telemetria** | sempre ativa no `init()` | O que o programa **emite** sozinho: erros com stack trace (módulo **Issues**), performance (transactions/etapas) e heartbeats de uptime (módulo **Agentes**). Instala handlers globais de erro; os timers são `unref`'d, então nunca seguram o processo vivo. |
-| **Tasks** | `tasks: true` (ou opções) no `init()` | Execução **sob demanda**: o agente faz polling no app, executa handlers registrados e reporta status/logs — o módulo **Solicitações**. `start()` **mantém o processo vivo** até `stop()`/`close()`. |
+| **Sob demanda** | `hobots.register(task, handler, options?)` | O robô faz polling e executa uma solicitação do app (formulário/agendamento) por vez — módulo **Solicitações**. |
+| **Sempre ligado** | `hobots.start(task, handler, options?)` | O robô abre a própria execução e roda o handler (o seu loop) dentro dela; a plataforma recebe logs, itens e progresso. |
 
 ## Páginas
 
-Se termos como transaction, step, breadcrumb, tag, context, extra, flush e close ainda não são familiares, comece por **Conceitos** — as outras páginas assumem esse vocabulário.
-
-- [Conceitos](./concepts.md) — o vocabulário: o que cada coisa é, por que existe e quando escolher uma em vez da outra.
-- [Getting started](./getting-started.md) — instalação, Client Secret, o `init` único, telemetria e tasks.
-- [Telemetria](./telemetry.md) — erros, breadcrumbs, escopo, transactions/etapas e heartbeat.
-- [Tasks](./tasks.md) — registro de handlers, `RunContext`, cancelamento, concorrência, idempotência.
-- [Referência de API](./api-reference.md) — todas as funções e tabelas de opções com defaults.
-- [Protocolo & transporte](./protocol.md) — o Client Secret, endpoints, envelope, retries e onde vive o claim atômico.
+- [Getting started](./getting-started.md) — instalação, envs, primeira task nos dois modos, encerramento.
+- [Tasks](./tasks.md) — handler, o objeto `hobots`, itens, progresso, anexos, cancelamento automático, retry, concorrência, idempotência.
+- [Conceitos](./concepts.md) — o vocabulário: task, execução, evento, issue, transaction, step, heartbeat, instância, claim.
+- [Referência de API](./api-reference.md) — assinaturas, tabelas de opções e tempos.
+- [Protocolo & transporte](./protocol.md) — Client Secret, endpoints (`/v1/ingest`, `/v1/tasks/*`), envelope, retries, claim atômico.
 
 ## Exemplo mínimo
 
 ```js
-import * as Hobots from 'hobots';
-
-// O Client Secret do agente — copie em Configurações → Agentes no app
-const clientSecret = 'hb_<64 hex>';
-
-// Um init só: telemetria sempre ativa; tasks habilita a execução sob demanda.
-// O instanceId é a identidade única — o robô aparece como um agente só no painel.
-Hobots.init({
-  clientSecret,
-  instanceId: 'vm-cliente-01',
-  heartbeat: true,
-  tasks: true,
-});
+import hobots from 'hobots'; // HOBOTS_CLIENT_SECRET e HOBOTS_INSTANCE_ID no ambiente
 
-Hobots.register('processar-nfe', async (params, ctx) => {
-  ctx.log.info(`processando lote ${params.lote}…`);
-  ctx.log.info('12 notas processadas'); // o retorno do handler é ignorado — reporte por log
+hobots.register('processar-nfe', async params => {
+  hobots.log.info(`processando lote ${params.lote}…`);
+  hobots.items.succeeded({ numero_nota: '123' }, { id: '123' });
+  hobots.log.success('concluído'); // o retorno do handler é ignorado — reporte por log/itens
 });
-Hobots.start(); // mantém o processo vivo aguardando execuções
 ```
 
-> Exemplos runnable de toda a API pública (incluindo as duas capabilities juntas em
-> [`full.ts`](../../hobots-sdk-demos/src/full.ts)) estão em
-> [`packages/hobots-sdk-demos`](../../hobots-sdk-demos).
+> Exemplos runnable em [`packages/hobots-sdk-demos`](../../hobots-sdk-demos).