aicrm-mcp 0.2.0 → 0.2.1

package/README.md

@@ -26,9 +26,9 @@ Outros clientes:
 | `aicrm-mcp skill [install] [--project \| --dir <pasta>]` | Imprime ou instala o SKILL.md para agentes |
 | `aicrm-mcp` | Inicia o servidor MCP (stdio) |
 
-## Ferramentas (43)
+## Ferramentas (44)
 
-- **Leads**: `list_workspaces`, `search_leads`, `get_lead`, `create_lead`, `update_lead`, `move_lead`, `mark_won`, `mark_lost`, `reopen_lead`, `add_note`, `bulk_update_leads`, `delete_lead`
+- **Leads**: `list_workspaces`, `search_leads`, `get_lead`, `create_lead`, `update_lead`, `move_lead`, `mark_won`, `mark_lost`, `reopen_lead`, `handoff_lead`, `add_note`, `bulk_update_leads`, `delete_lead`
 - **Importação**: `import_leads_csv` (`dry_run`, `columns`, `template_name`), `rename_import_template`, `delete_import_template`
 - **Campos**: `list_fields`, `create_field`, `update_field`, `archive_field`, `set_standard_fields`
 - **Metas**: `get_dashboard`, `get_forecast`, `get_goals`, `set_goals`, `list_commission_plans`, `save_commission_plan`, `delete_commission_plan`

package/dist/cli.js

@@ -314,7 +314,9 @@ var workspaceSchema = z.object({
 var workspaceUpdateSchema = z.object({
   name: z.string().trim().min(1, "Informe um nome").max(80).optional(),
   visibility: z.enum(VISIBILITIES).optional(),
-  hiddenFields: z.array(z.enum(HIDEABLE_FIELDS)).transform((a) => [...new Set(a)]).optional()
+  hiddenFields: z.array(z.enum(HIDEABLE_FIELDS)).transform((a) => [...new Set(a)]).optional(),
+  /** Raster data URL (PNG/JPEG/WebP), or null to remove. SVG is rejected: the browser rasterizes it first. */
+  logo: z.string().regex(/^data:image\/(png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/, "Envie uma imagem PNG, JPG ou WebP").max(4e5, "Imagem muito grande (m\xE1x. ~300 KB)").nullable().optional()
 });
 var fieldOptions = z.array(z.string().trim().min(1).max(60)).max(100, "No m\xE1ximo 100 op\xE7\xF5es").transform((o) => [...new Set(o)]);
 var leadFieldSchema = z.object({
@@ -344,13 +346,15 @@ var funnelSchema = z.object({
   goalKpi: z.enum(GOAL_KPIS).default("revenue"),
   goalStageIndex: z.number().int().min(0).optional(),
   template: z.enum(Object.keys(FUNNEL_TEMPLATES)).optional(),
-  stages: z.array(stageInputSchema).min(1).max(20).optional()
+  stages: z.array(stageInputSchema).min(1).max(20).optional(),
+  nextFunnelId: id.nullish()
 });
 var funnelUpdateSchema = z.object({
   name: z.string().trim().min(1).max(80).optional(),
   goalKpi: z.enum(GOAL_KPIS).optional(),
   goalStageId: id.nullable().optional(),
   stages: z.array(stageInputSchema).min(1).max(20).optional(),
+  nextFunnelId: id.nullable().optional(),
   archived: z.boolean().optional()
 });
 var optionalText = (max) => z.string().trim().max(max).nullish().transform((v) => v ? v : null);
@@ -375,9 +379,16 @@ var moveLeadSchema = z.object({
   funnelId: id.optional(),
   stageId: id
 });
+var handoffSchema = z.object({
+  funnelId: id,
+  stageId: id.optional(),
+  ownerId: id.nullish(),
+  valueCents: z.number().int().min(0).max(1e13).optional()
+});
 var leadStatusSchema = z.discriminatedUnion("status", [
-  z.object({ status: z.literal("open") }),
-  z.object({ status: z.literal("won"), valueCents: z.number().int().min(0).optional() }),
+  /** undoHandoff also deletes continuations nobody has touched yet (used by the "Desfazer" of a win). */
+  z.object({ status: z.literal("open"), undoHandoff: z.boolean().optional() }),
+  z.object({ status: z.literal("won"), valueCents: z.number().int().min(0).optional(), handoff: handoffSchema.optional() }),
   z.object({ status: z.literal("lost"), lostReason: z.enum(LOST_REASONS), note: z.string().max(500).optional() })
 ]);
 var noteSchema = z.object({ body: z.string().trim().min(1).max(5e3) });
@@ -740,6 +751,20 @@ var targetLabel = (fields, t) => {
   return p.kind === "std" ? CSV_FIELD_LABEL[p.field] : fields.find((f) => f.id === p.fieldId)?.label ?? "campo removido";
 };
 var findUser = (c, ref) => c.users.find((u) => norm(u.email) === norm(ref)) ?? resolve(c.users, ref, "Usu\xE1rio");
+var isNoOwner = (ref) => ["none", "ninguem", "sem responsavel"].includes(norm(ref));
+function handoffBody(c, source, a) {
+  const funnel = pickFunnel(c, a.funnel, a.workspace ?? source.workspaceId);
+  const stage = resolve(funnel.stages, a.stage, "Etapa");
+  return {
+    funnel,
+    body: {
+      funnelId: funnel.id,
+      ...stage ? { stageId: stage.id } : {},
+      ...a.owner ? { ownerId: isNoOwner(a.owner) ? null : findUser(c, a.owner).id } : {},
+      ...a.value != null ? { valueCents: Math.round(a.value * 100) } : {}
+    }
+  };
+}
 var MONTH = /^\d{4}-\d{2}$/;
 
 // src/tools/admin.ts
@@ -981,11 +1006,33 @@ function registerLeadTools(server) {
       return text({ reopened: leadSummary(c, lead) });
     })
   );
+  server.registerTool(
+    "handoff_lead",
+    {
+      title: "Enviar lead ganho para outro funil",
+      description: "Continua um lead GANHO em outro funil (ex.: de Aquisi\xE7\xE3o para Relacionamento/p\xF3s-venda): cria um lead novo, aberto e ligado ao original, na etapa escolhida (padr\xE3o: a primeira). O lead ganho fica onde est\xE1 e continua contando na meta e na comiss\xE3o. O novo lead copia contato e campos, come\xE7a com valor R$ 0 (informe value se j\xE1 houver nova venda prevista) e mant\xE9m o respons\xE1vel (ou use owner). S\xF3 funciona para leads com status won; cada lead s\xF3 pode continuar uma vez em cada funil.",
+      inputSchema: {
+        lead_id: z4.string().uuid().describe("Lead ganho"),
+        funnel: z4.string().describe("Funil onde o cliente continua (nome ou id)"),
+        stage: z4.string().optional().describe("Etapa de entrada (padr\xE3o: a primeira)"),
+        workspace: z4.string().optional().describe("Workspace do funil, se for outro (s\xF3 admins)"),
+        owner: z4.string().optional().describe('Respons\xE1vel no novo funil (nome ou email; "none" = sem respons\xE1vel). Padr\xE3o: o mesmo do lead ganho'),
+        value: z4.number().min(0).optional().describe("Valor em reais no novo funil (padr\xE3o: 0)")
+      }
+    },
+    withApi(async (api, a) => {
+      const c = await ctx(api);
+      const source = (await api.get(`/leads/${a.lead_id}`)).lead;
+      const { body } = handoffBody(c, source, a);
+      const r = await api.post(`/leads/${a.lead_id}/handoff`, body);
+      return text({ won: leadSummary(c, r.source), continuation: leadSummary(c, r.lead) });
+    })
+  );
   server.registerTool(
     "bulk_update_leads",
     {
       title: "Atualizar leads em massa",
-      description: "Reatribui (s\xF3 admins) e/ou move at\xE9 1000 leads de uma vez. Pegue os ids com search_leads. Para mover, informe stage (e funnel, se for outro funil; sem funnel, vale o funil do primeiro lead). Leads que voc\xEA n\xE3o pode editar s\xE3o pulados.",
+      description: "Reatribui (s\xF3 admins) e/ou move at\xE9 1000 leads de uma vez. Pegue os ids com search_leads. Para mover, informe stage (e funnel, se for outro funil; sem funnel, vale o funil do primeiro lead). Leads que voc\xEA n\xE3o pode editar s\xE3o pulados, assim como leads ganhos numa troca de funil (use handoff_lead para eles).",
       inputSchema: {
         lead_ids: z4.array(z4.string().uuid()).min(1).max(1e3),
         owner: z4.string().optional().describe("Nome ou email do novo respons\xE1vel"),
@@ -1036,12 +1083,15 @@ var stageInput = z5.object({
   probability: z5.number().int().min(0).max(100).describe("Chance (%) de um lead nesta etapa virar venda"),
   was: z5.string().optional().describe("Nome atual da etapa, se voc\xEA est\xE1 renomeando uma existente")
 });
-var describeFunnel = (f) => ({
+var describeFunnel = (f, ws) => ({
   name: f.name,
   goal_kpi: `${f.goalKpi} (${GOAL_KPI_LABEL[f.goalKpi]})`,
   ...f.goalKpi === "stage_reached" ? { goal_stage: f.stages.find((s) => s.id === f.goalStageId)?.name ?? null } : {},
+  ...f.nextFunnelId ? { after_won_continue_in: ws?.funnels.find((x) => x.id === f.nextFunnelId)?.name ?? f.nextFunnelId } : {},
   stages: f.stages.map((s) => `${s.name} (${s.probability}%)`)
 });
+var nextFunnelArg = z5.string().nullable().optional().describe('Funil (do mesmo workspace) onde o cliente continua depois de ganho, ex.: "Relacionamento". Sugerido no app ao marcar ganho. null ou "none" remove.');
+var nextFunnelId = (ws, ref) => ref === void 0 ? void 0 : ref === null || norm(ref) === "none" ? null : resolve(ws.funnels, ref, "Funil").id;
 function registerStructureTools(server) {
   server.registerTool(
     "create_workspace",
@@ -1102,7 +1152,8 @@ function registerStructureTools(server) {
         template: z5.enum(TEMPLATE_KEYS).optional(),
         stages: z5.array(stageInput.omit({ was: true })).min(1).max(20).optional(),
         goal_kpi: z5.enum(GOAL_KPIS).default("revenue"),
-        goal_stage: z5.string().optional().describe("Etapa que conta como meta (s\xF3 para stage_reached; padr\xE3o: a \xFAltima)")
+        goal_stage: z5.string().optional().describe("Etapa que conta como meta (s\xF3 para stage_reached; padr\xE3o: a \xFAltima)"),
+        next_funnel: nextFunnelArg
       }
     },
     withApi(
@@ -1116,9 +1167,10 @@ function registerStructureTools(server) {
           name: a.name,
           goalKpi: a.goal_kpi,
           ...a.stages ? { stages: a.stages } : { template: a.template ?? "sales" },
-          ...goalIdx >= 0 ? { goalStageIndex: goalIdx } : {}
+          ...goalIdx >= 0 ? { goalStageIndex: goalIdx } : {},
+          ...a.next_funnel ? { nextFunnelId: nextFunnelId(ws, a.next_funnel) } : {}
         });
-        return text({ workspace: ws.name, created: describeFunnel(f) });
+        return text({ workspace: ws.name, created: describeFunnel(f, ws) });
       }
     )
   );
@@ -1126,18 +1178,22 @@ function registerStructureTools(server) {
     "update_funnel",
     {
       title: "Alterar funil",
-      description: "Renomeia o funil, troca o KPI de meta ou redefine as etapas (s\xF3 admins). stages \xE9 a lista completa e na ordem: etapas com o mesmo nome (ou com was) s\xE3o mantidas, as novas s\xE3o criadas e as que ficarem de fora s\xE3o removidas \u2014 o que s\xF3 funciona se n\xE3o tiverem leads (mova antes com bulk_update_leads).",
+      description: "Renomeia o funil, troca o KPI de meta ou redefine as etapas (s\xF3 admins). stages \xE9 a lista completa e na ordem: etapas com o mesmo nome (ou com was) s\xE3o mantidas, as novas s\xE3o criadas e as que ficarem de fora s\xE3o removidas \u2014 o que s\xF3 funciona se n\xE3o tiverem leads (mova antes com bulk_update_leads). next_funnel define para onde o cliente vai depois de ganho (ex.: Aquisi\xE7\xE3o \u2192 Relacionamento).",
       inputSchema: {
         funnel: z5.string(),
         workspace: z5.string().optional(),
         name: z5.string().min(1).max(80).optional(),
         goal_kpi: z5.enum(GOAL_KPIS).optional(),
         goal_stage: z5.string().optional(),
-        stages: z5.array(stageInput).min(1).max(20).optional()
+        stages: z5.array(stageInput).min(1).max(20).optional(),
+        next_funnel: nextFunnelArg
       }
     },
     withApi(async (api, a) => {
-      const funnel = pickFunnel(await ctx(api), a.funnel, a.workspace);
+      const c = await ctx(api);
+      const funnel = pickFunnel(c, a.funnel, a.workspace);
+      const ws = c.workspaces.find((w) => w.id === funnel.workspaceId);
+      const next = nextFunnelId(ws, a.next_funnel);
       const stages = a.stages?.map((s) => {
         const existing = funnel.stages.find((x) => norm(x.name) === norm(s.was ?? s.name));
         return { ...existing ? { id: existing.id } : {}, name: s.name, probability: s.probability };
@@ -1145,13 +1201,14 @@ function registerStructureTools(server) {
       let f = await api.patch(`/funnels/${funnel.id}`, {
         ...a.name ? { name: a.name } : {},
         ...a.goal_kpi ? { goalKpi: a.goal_kpi } : {},
-        ...stages ? { stages } : {}
+        ...stages ? { stages } : {},
+        ...next !== void 0 ? { nextFunnelId: next } : {}
       });
       if (a.goal_stage || a.goal_kpi === "stage_reached" && !f.goalStageId) {
         const goal = a.goal_stage ? resolve(f.stages, a.goal_stage, "Etapa") : f.stages[f.stages.length - 1];
         f = await api.patch(`/funnels/${funnel.id}`, { goalStageId: goal.id });
       }
-      return text({ updated: describeFunnel(f) });
+      return text({ updated: describeFunnel(f, ws) });
     })
   );
   server.registerTool(
@@ -1281,7 +1338,7 @@ async function startServer() {
   const server = new McpServer(
     { name: "aicrm", version: "0.2.0" },
     {
-      instructions: "AICRM \xE9 um CRM de vendas. Workspaces cont\xEAm funis; funis cont\xEAm etapas e leads. Status do lead: open, won, lost. Workspaces, funis, etapas e vendedores podem ser referenciados por nome. Valores monet\xE1rios est\xE3o em reais (BRL). Use get_dashboard/get_forecast para metas e proje\xE7\xF5es estat\xEDsticas (Monte Carlo bayesiano). Cada workspace pode ter campos personalizados (ex.: Cidade, Porte) e esconder campos padr\xE3o: veja list_fields. Em create_lead/update_lead, preencha-os em custom_fields usando o nome do campo. Antes de importar um CSV desconhecido, rode import_leads_csv com dry_run=true para revisar o mapeamento de colunas. Admins tamb\xE9m gerenciam time (invite_user, update_user), estrutura (create_workspace, create_funnel, update_funnel), metas e comiss\xF5es (set_goals, save_commission_plan) e modo TV. O servidor aplica as permiss\xF5es do usu\xE1rio logado: se uma a\xE7\xE3o for negada, explique que precisa de um admin. A\xE7\xF5es destrutivas (delete_*, archive_field, revoke_*) exigem confirma\xE7\xE3o expl\xEDcita da pessoa antes."
+      instructions: "AICRM \xE9 um CRM de vendas. Workspaces cont\xEAm funis; funis cont\xEAm etapas e leads. Status do lead: open, won, lost. Workspaces, funis, etapas e vendedores podem ser referenciados por nome. Valores monet\xE1rios est\xE3o em reais (BRL). Use get_dashboard/get_forecast para metas e proje\xE7\xF5es estat\xEDsticas (Monte Carlo bayesiano). Cada workspace pode ter campos personalizados (ex.: Cidade, Porte) e esconder campos padr\xE3o: veja list_fields. Em create_lead/update_lead, preencha-os em custom_fields usando o nome do campo. Lead ganho n\xE3o troca de funil: para levar o cliente adiante (ex.: Aquisi\xE7\xE3o \u2192 Relacionamento), use handoff_lead ou next_funnel em mark_won, que criam um lead novo ligado ao ganho. Antes de importar um CSV desconhecido, rode import_leads_csv com dry_run=true para revisar o mapeamento de colunas. Admins tamb\xE9m gerenciam time (invite_user, update_user), estrutura (create_workspace, create_funnel, update_funnel), metas e comiss\xF5es (set_goals, save_commission_plan) e modo TV. O servidor aplica as permiss\xF5es do usu\xE1rio logado: se uma a\xE7\xE3o for negada, explique que precisa de um admin. A\xE7\xF5es destrutivas (delete_*, archive_field, revoke_*) exigem confirma\xE7\xE3o expl\xEDcita da pessoa antes."
     }
   );
   server.registerTool(
@@ -1306,6 +1363,7 @@ async function startServer() {
             id: f.id,
             goal_kpi: f.goalKpi,
             ...f.goalKpi === "stage_reached" ? { goal_stage: f.stages.find((s) => s.id === f.goalStageId)?.name ?? null } : {},
+            ...f.nextFunnelId ? { after_won_continue_in: c.funnels.get(f.nextFunnelId)?.name ?? null } : {},
             stages: f.stages.map((s) => `${s.name} (${s.probability}%)`)
           }))
         })),
@@ -1379,6 +1437,8 @@ async function startServer() {
         source: d.lead.source,
         lost_reason: d.lead.lostReason,
         expected_close: d.lead.expectedCloseAt,
+        ...d.links.source ? { came_from: { lead_id: d.links.source.id, funnel: d.links.source.funnelName, won_at: d.links.source.wonAt, value: formatMoney(d.links.source.valueCents) } } : {},
+        ...d.links.continuations.length ? { continues_in: d.links.continuations.map((x) => ({ lead_id: x.id, funnel: x.funnelName, stage: x.stageName, status: x.status })) } : {},
         history: d.events.slice(0, 30).map((e) => ({
           at: e.createdAt,
           by: e.actorName,
@@ -1386,6 +1446,7 @@ async function startServer() {
           ...e.type === "note" ? { note: e.payload?.body } : {},
           ...e.fromStageId || e.toStageId ? { from: d.names[e.fromStageId ?? ""], to: d.names[e.toStageId ?? ""] } : {},
           ...e.type === "status_changed" ? { status: e.payload } : {},
+          ...e.type === "handed_off" ? { to_funnel: d.names[String(e.payload?.toFunnelId ?? "")] } : {},
           ...e.type === "updated" && Array.isArray(e.payload?.fields) ? { changed: e.payload.fields.map(fieldLabel) } : {}
         }))
       });
@@ -1450,7 +1511,7 @@ async function startServer() {
     },
     withApi(async (api, a) => {
       const c = await ctx(api);
-      const unassign = a.owner != null && ["none", "ninguem", "sem responsavel"].includes(norm(a.owner));
+      const unassign = a.owner != null && isNoOwner(a.owner);
       const owner = a.owner && !unassign ? findUser(c, a.owner) : void 0;
       let fields;
       if (a.custom_fields) fields = await listFields(api, (await api.get(`/leads/${a.lead_id}`)).lead.workspaceId);
@@ -1466,7 +1527,7 @@ async function startServer() {
     "move_lead",
     {
       title: "Mover lead",
-      description: "Move um lead para outra etapa \u2014 e opcionalmente para outro funil (entre workspaces: s\xF3 admins).",
+      description: "Move um lead para outra etapa \u2014 e opcionalmente para outro funil (entre workspaces: s\xF3 admins). Lead ganho n\xE3o muda de funil (a venda precisa continuar contando onde foi fechada): para lev\xE1-lo a outro funil, use handoff_lead.",
       inputSchema: { lead_id: z7.string().uuid(), stage: z7.string().describe("Nome ou id da etapa de destino"), funnel: z7.string().optional().describe("Funil de destino (padr\xE3o: o atual)") }
     },
     withApi(async (api, a) => {
@@ -1482,13 +1543,34 @@ async function startServer() {
     "mark_won",
     {
       title: "Marcar como ganho",
-      description: "Marca o lead como ganho. Informe value (R$) se o valor fechado for diferente do cadastrado.",
-      inputSchema: { lead_id: z7.string().uuid(), value: z7.number().min(0).optional() }
+      description: "Marca o lead como ganho. Informe value (R$) se o valor fechado for diferente do cadastrado. Para j\xE1 continuar o cliente em outro funil (ex.: Relacionamento), informe next_funnel: \xE9 criado um lead novo ligado ao ganho, na mesma opera\xE7\xE3o. Se o funil tiver um funil seguinte configurado, a resposta avisa \u2014 pergunte \xE0 pessoa antes de usar handoff_lead.",
+      inputSchema: {
+        lead_id: z7.string().uuid(),
+        value: z7.number().min(0).optional(),
+        next_funnel: z7.string().optional().describe("Funil onde o cliente continua depois do ganho"),
+        next_stage: z7.string().optional().describe("Etapa de entrada no pr\xF3ximo funil (padr\xE3o: a primeira)"),
+        next_owner: z7.string().optional().describe("Respons\xE1vel no pr\xF3ximo funil (padr\xE3o: o mesmo)"),
+        next_value: z7.number().min(0).optional().describe("Valor em reais no pr\xF3ximo funil (padr\xE3o: 0)")
+      }
     },
     withApi(async (api, a) => {
       const c = await ctx(api);
-      const lead = await api.post(`/leads/${a.lead_id}/status`, { status: "won", ...a.value != null ? { valueCents: Math.round(a.value * 100) } : {} });
-      return text({ won: leadSummary(c, lead) });
+      const current = (await api.get(`/leads/${a.lead_id}`)).lead;
+      const next = a.next_funnel ? handoffBody(c, current, { funnel: a.next_funnel, stage: a.next_stage, owner: a.next_owner, value: a.next_value }) : null;
+      const lead = await api.post(`/leads/${a.lead_id}/status`, {
+        status: "won",
+        ...a.value != null ? { valueCents: Math.round(a.value * 100) } : {},
+        ...next ? { handoff: next.body } : {}
+      });
+      if (lead.handoffLeadId) {
+        const continuation = (await api.get(`/leads/${lead.handoffLeadId}`)).lead;
+        return text({ won: leadSummary(c, lead), continuation: leadSummary(c, continuation) });
+      }
+      const suggested = c.funnels.get(c.funnels.get(lead.funnelId)?.nextFunnelId ?? "");
+      return text({
+        won: leadSummary(c, lead),
+        ...suggested ? { tip: `Este funil sugere continuar o cliente em "${suggested.name}". Se a pessoa quiser, use handoff_lead.` } : {}
+      });
     })
   );
   server.registerTool(

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "aicrm-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server for AICRM — operate your CRM from Claude, Opencode and other MCP clients.",
   "type": "module",
-  "bin": { "aicrm-mcp": "dist/cli.js" },
-  "files": ["dist", "skill"],
+  "bin": {
+    "aicrm-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsx src/cli.ts",
@@ -23,5 +28,7 @@
     "tsx": "^4.23.15",
     "typescript": "^5.9.3"
   },
-  "engines": { "node": ">=20" }
+  "engines": {
+    "node": ">=20"
+  }
 }

package/skill/aicrm/SKILL.md

@@ -102,8 +102,9 @@ Como ler as respostas de erro:
 5. **Campos personalizados** vão em `custom_fields` pelo nome: `{ "Cidade": "Recife", "Porte": "Média" }`. Em `select`, use uma das opções (veja `list_fields`); `null` limpa o campo.
 6. **Ações destrutivas exigem confirmação explícita da pessoa** antes: `delete_lead`, `delete_workspace`, `delete_funnel`, `archive_field`, `delete_import_template`, `delete_commission_plan`, `revoke_tv_link`, `revoke_api_token`, e `update_user` com `active: false`. Diga o que será afetado (ex.: quantos leads) e espere o "sim".
 7. **Para tirar um lead do funil sem apagar**, prefira `mark_lost` com o motivo certo.
-8. **Responda em português simples.** A pessoa pode não ter experiência com CRM nem estatística: traduza números ("~70% de chance de bater a meta"), destaque o que fazer em seguida, evite jargão e ids.
-9. **Volume:** `search_leads` devolve até 200 por chamada (padrão 25); `bulk_update_leads` aceita até 1000 ids; o CSV aceita até 10.000 linhas.
+8. **Lead ganho não muda de funil.** A venda precisa continuar contando na meta e na comissão de onde foi fechada. Para levar o cliente adiante (ex.: Aquisição → Relacionamento), use `handoff_lead` (ou `next_funnel` no `mark_won`): isso cria um lead novo, aberto e ligado ao ganho, no outro funil.
+9. **Responda em português simples.** A pessoa pode não ter experiência com CRM nem estatística: traduza números ("~70% de chance de bater a meta"), destaque o que fazer em seguida, evite jargão e ids.
+10. **Volume:** `search_leads` devolve até 200 por chamada (padrão 25); `bulk_update_leads` aceita até 1000 ids; o CSV aceita até 10.000 linhas.
 
 ## 5. Ferramentas
 
@@ -115,8 +116,9 @@ Como ler as respostas de erro:
 | `get_lead` | Todos os campos (inclusive personalizados) e o histórico. |
 | `create_lead` | Criar (nome obrigatório; demais opcionais, inclusive `custom_fields`). |
 | `update_lead` | Alterar só o que for informado; `owner: "none"` tira o responsável; `""` limpa um campo padrão. |
-| `move_lead` | Mudar de etapa (e de funil). |
-| `mark_won` / `mark_lost` / `reopen_lead` | Fechar como ganho (com valor final), perdido (motivo: `price`, `timing`, `competitor`, `no_response`, `no_fit`, `other`) ou reabrir. |
+| `move_lead` | Mudar de etapa (e de funil, só para leads abertos ou perdidos). |
+| `mark_won` / `mark_lost` / `reopen_lead` | Fechar como ganho (com valor final; `next_funnel` já continua o cliente em outro funil), perdido (motivo: `price`, `timing`, `competitor`, `no_response`, `no_fit`, `other`) ou reabrir. |
+| `handoff_lead` | Continuar um lead **ganho** em outro funil (pós-venda, relacionamento): cria um lead novo ligado ao original, na 1ª etapa (ou `stage`), valor R$ 0 (ou `value`), mesmo responsável (ou `owner`). O `get_lead` mostra o vínculo em `came_from` / `continues_in`. |
 | `add_note` | Registrar conversa, ligação, contexto. |
 | `bulk_update_leads` | Mover e/ou reatribuir vários leads de uma vez (ids do `search_leads`). |
 | `delete_lead` | Apagar com histórico (admin, destrutivo). |
@@ -176,6 +178,8 @@ Como ler as respostas de erro:
 
 ### Fechar negócio
 - Ganho: `mark_won` (com `value` se o valor final mudou). Perdido: `mark_lost` com o motivo mais próximo e uma `note` curta. Errou? `reopen_lead`.
+- Depois do ganho: se o funil tiver um funil seguinte (`after_won_continue_in` no `list_workspaces`, ou o `tip` na resposta do `mark_won`), pergunte se o cliente deve seguir para lá e use `handoff_lead`. Se a pessoa já pediu ("fechou, manda pro Relacionamento"), faça tudo de uma vez com `mark_won` + `next_funnel`.
+- Para configurar o caminho padrão (admin): `update_funnel` com `next_funnel: "Relacionamento"`.
 
 ### Redistribuir carteira (férias, saída, rodízio)
 1. `search_leads` com `owner` e `status: "open"` (aumente `limit` se precisar).