@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.mjs

@@ -1,6 +1,7 @@
-import { appendFile, open, readFile, rm } from "node:fs/promises";
+import { open, readFile, rename, rm, writeFile } from "node:fs/promises";
 import {
   aggregate,
+  exactCompletedSegment,
   exactRemeasurementSegment,
   jsonLines,
   pricingFor,
@@ -9,6 +10,7 @@ import {
   recordType,
   usageStatus,
   usageView,
+  withSequence,
 } from "./reconcile-telemetry-lib.mjs";
 
 export const remeasureSelectedRuns = async ({
@@ -26,19 +28,35 @@ export const remeasureSelectedRuns = async ({
       remeasurement.push({ run_id: runId, eligible: false, reason: "run-not-found" });
       continue;
     }
-    const effective = usageStatus(run.usage).effective.filter(
-      (usage) => usage.tokens?.input !== null && usage.tokens?.output !== null,
-    );
+    const effectiveUsage = usageStatus(run.usage).effective;
+    const effective = timingOnly
+      ? effectiveUsage
+      : effectiveUsage.filter(
+          (usage) => usage.tokens?.input !== null && usage.tokens?.output !== null,
+        );
     const superseded = effective.at(-1) ?? null;
     const finished = run.records.find((record) => recordType(record) === "run.finished");
-    const match = exactRemeasurementSegment(
-      run.started,
-      superseded?.source_segment_key,
-      allSegments,
-    );
+    // Timing-only reconciliation is deliberately narrower than normal
+    // remeasurement: it may enrich a missing source interval only when the
+    // persisted client turn identifies exactly one completed local segment.
+    const match = timingOnly
+      ? exactCompletedSegment(run.started, allSegments)
+      : exactRemeasurementSegment(
+          run.started,
+          superseded?.source_segment_key,
+          allSegments,
+          superseded?.source_occurred_at,
+          superseded?.tokens,
+        );
     const segment = match.segment;
     const ambiguous = match.ambiguous;
-    if (!finished || segment === null || ambiguous || superseded === null) {
+    if (
+      !finished ||
+      segment === null ||
+      segment.finished_at === null ||
+      ambiguous ||
+      superseded === null
+    ) {
       remeasurement.push({
         run_id: runId,
         eligible: false,
@@ -121,36 +139,75 @@ export const remeasureSelectedRuns = async ({
   return remeasurement;
 };
 
+export function timingEnrichmentRunIds({ remeasure, applyBackfill, selectedRunIds, runs }) {
+  if (remeasure) return selectedRunIds;
+  if (!applyBackfill) return new Set();
+  return new Set(
+    runs
+      .filter(
+        (run) =>
+          run.nativeMeasured && run.records.some((record) => recordType(record) === "run.finished"),
+      )
+      .map((run) => run.started.run_id),
+  );
+}
+
 export async function appendRetrospectiveUsage(file, expectedRecords, event) {
-  assertRetrospectiveAppend(expectedRecords, event);
+  assertRetrospectiveAppend(expectedRecords, event, { allowPostTerminalCorrections: true });
   const lockPath = `${file}.lock`;
   const handle = await open(lockPath, "wx");
   await handle.close();
   try {
     const persisted = jsonLines(await readFile(file, "utf8"));
-    const expectedLast = expectedRecords.at(-1);
-    const persistedLast = persisted.at(-1);
+    const expectedIds = expectedRecords.map((record) => record?.event_id ?? record?.[2]);
+    const persistedIds = persisted.map((record) => record?.event_id ?? record?.[2]);
     if (
       persisted.length !== expectedRecords.length ||
-      recordSequence(persistedLast) !== recordSequence(expectedLast) ||
-      recordType(persistedLast) !== "run.finished"
+      persistedIds.some((id, index) => id !== expectedIds[index])
     ) {
       throw new Error("Run history changed before retrospective append");
     }
-    assertRetrospectiveAppend(persisted, event);
-    await appendFile(file, `${JSON.stringify(event)}\n`, "utf8");
+    assertRetrospectiveAppend(persisted, event, { allowPostTerminalCorrections: true });
+    const finishIndex = persisted.findIndex((record) => recordType(record) === "run.finished");
+    const beforeFinish = persisted.slice(0, finishIndex);
+    const finish = persisted[finishIndex];
+    const historicalCorrections = persisted.slice(finishIndex + 1);
+    const updated = [...beforeFinish, ...historicalCorrections, event, finish].map(
+      (record, index) => withSequence(record, index + 1),
+    );
+    const temporary = `${file}.remeasure.tmp`;
+    await writeFile(
+      temporary,
+      `${updated.map((record) => JSON.stringify(record)).join("\n")}\n`,
+      "utf8",
+    );
+    await rename(temporary, file);
   } finally {
     await rm(lockPath, { force: true });
   }
 }
 
-export function assertRetrospectiveAppend(records, event) {
-  const finished = records.at(-1);
+export function assertRetrospectiveAppend(
+  records,
+  event,
+  { allowPostTerminalCorrections = false } = {},
+) {
+  const finishIndex = records.findIndex((record) => recordType(record) === "run.finished");
+  const finished = records[finishIndex];
   const target = records.find(
     (record) => usageView(record)?.event_id === event.supersedes_event_id,
   );
   if (
     recordType(finished) !== "run.finished" ||
+    (!allowPostTerminalCorrections && finishIndex !== records.length - 1) ||
+    (allowPostTerminalCorrections &&
+      records
+        .slice(finishIndex + 1)
+        .some(
+          (record) =>
+            usageView(record)?.activity_kind !== "retrospective_local_remeasurement" ||
+            usageView(record)?.retrospective_correction !== true,
+        )) ||
     event.type !== "usage.recorded" ||
     event.retrospective_correction !== true ||
     event.activity_kind !== "retrospective_local_remeasurement" ||

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.test.mjs

@@ -9,12 +9,34 @@ import {
   assertRetrospectiveAppend,
   remeasureSelectedRuns,
   retrospectiveCorrectionOccurredAt,
+  timingEnrichmentRunIds,
 } from "./reconcile-telemetry-remeasurement.mjs";
 
 const roots = [];
 after(async () => Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))));
 
-test("appends under an exclusive lock without rewriting the terminal history", async () => {
+test("selects completed native Runs for default timing-only backfill", () => {
+  const selected = timingEnrichmentRunIds({
+    remeasure: false,
+    applyBackfill: true,
+    selectedRunIds: new Set(),
+    runs: [
+      {
+        nativeMeasured: true,
+        started: { run_id: "RUN-NATIVE" },
+        records: [{ type: "run.started" }, { type: "run.finished" }],
+      },
+      {
+        nativeMeasured: true,
+        started: { run_id: "RUN-RUNNING" },
+        records: [{ type: "run.started" }],
+      },
+    ],
+  });
+  assert.deepEqual([...selected], ["RUN-NATIVE"]);
+});
+
+test("inserts a correction before the terminal event under an exclusive lock", async () => {
   const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-append-"));
   roots.push(root);
   const file = join(root, "RUN.jsonl");
@@ -38,8 +60,51 @@ test("appends under an exclusive lock without rewriting the terminal history", a
   await appendRetrospectiveUsage(file, records, correction);
 
   const persisted = await readFile(file, "utf8");
-  assert.ok(persisted.startsWith(original));
-  assert.equal(persisted, `${original}${JSON.stringify(correction)}\n`);
+  const events = jsonLines(persisted);
+  assert.equal(events.at(-2).event_id, correction.event_id);
+  assert.equal(events.at(-1).type, "run.finished");
+  assert.deepEqual(
+    events.map((event) => event.sequence),
+    [1, 2, 3, 4],
+  );
+});
+
+test("restores historical retrospective corrections before the terminal event", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-restore-"));
+  roots.push(root);
+  const file = join(root, "RUN.jsonl");
+  const records = [
+    { type: "run.started", event_id: "RUN:1", sequence: 1, phase: "execution" },
+    { type: "usage.recorded", event_id: "RUN:2", sequence: 2, phase: "execution" },
+    { type: "run.finished", event_id: "RUN:3", sequence: 3, phase: "execution" },
+    {
+      type: "usage.recorded",
+      event_id: "RUN:4",
+      sequence: 4,
+      phase: "execution",
+      activity_kind: "retrospective_local_remeasurement",
+      retrospective_correction: true,
+    },
+  ];
+  await writeFile(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`, "utf8");
+  await appendRetrospectiveUsage(file, records, {
+    type: "usage.recorded",
+    event_id: "RUN:5",
+    sequence: 5,
+    phase: "execution",
+    activity_kind: "retrospective_local_remeasurement",
+    supersedes_event_id: "RUN:2",
+    retrospective_correction: true,
+  });
+  const events = jsonLines(await readFile(file, "utf8"));
+  assert.deepEqual(
+    events.map((event) => event.event_id),
+    ["RUN:1", "RUN:2", "RUN:4", "RUN:5", "RUN:3"],
+  );
+  assert.deepEqual(
+    events.map((event) => event.sequence),
+    [1, 2, 3, 4, 5],
+  );
 });
 
 test("an unavailable lock leaves the original history byte-identical", async () => {
@@ -151,17 +216,17 @@ test("uses run.finished phase after planning transitions to execution and reread
     workspace: root,
   });
   const persisted = jsonLines(await readFile(file, "utf8"));
-  const correction = usageView(persisted.at(-1));
+  const correction = usageView(persisted.at(-2));
   assert.equal(result.applied, true);
   assert.equal(correction.phase, "execution");
   assert.equal(usageStatus([...run.usage, correction]).effective.at(-1).tokens.total, 9);
   assert.throws(
-    () => assertRetrospectiveAppend(records, { ...persisted.at(-1), phase: "planning" }),
+    () => assertRetrospectiveAppend(records, { ...persisted.at(-2), phase: "planning" }),
     /Invalid retrospective/,
   );
 });
 
-test("enriches exact source timing without changing canonical tokens when remeasurement drifts", async () => {
+test("timing-only preserves exact measured tokens and cost while enriching source timing", async () => {
   const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-timing-"));
   roots.push(root);
   await mkdir(join(root, ".agents", "config", "pricing"), { recursive: true });
@@ -198,6 +263,7 @@ test("enriches exact source timing without changing canonical tokens when remeas
       phase: "execution",
       activity_kind: "retrospective_local_reconciliation",
       tokens: { input: 10, cached_input: 0, output: 2, reasoning: 0, total: 12 },
+      cost: { usd: 0.000012, brl: 0.00006, fx_rate: 5 },
       supersedes_event_id: null,
       source_segment_key: "session#timing",
       source_occurred_at: "2026-07-25T04:01:00.000Z",
@@ -217,6 +283,7 @@ test("enriches exact source timing without changing canonical tokens when remeas
     records,
     started: {
       run_id: "RUN-TIMING",
+      occurred_at: "2026-07-25T04:00:00.000Z",
       phase: "execution",
       client_turn_id: "turn-timing",
       model: "gpt-test",
@@ -249,15 +316,158 @@ test("enriches exact source timing without changing canonical tokens when remeas
     timingOnly: true,
     workspace: root,
   });
-  const correction = usageView(jsonLines(await readFile(file, "utf8")).at(-1));
+  const correction = usageView(jsonLines(await readFile(file, "utf8")).at(-2));
   assert.equal(result.unchanged, false);
   assert.equal(result.timing_enrichment, true);
+  assert.equal(result.eligible, true);
   assert.equal(result.applied, true);
   assert.equal(correction.tokens.total, 12);
+  assert.deepEqual(correction.tokens, usageView(records[1]).tokens);
+  assert.deepEqual(correction.cost, usageView(records[1]).cost);
+  assert.equal(correction.source_started_at, segment.started_at);
+  assert.equal(correction.source_finished_at, segment.finished_at);
+});
+
+test("timing-only appends exact source timing while preserving null tokens and cost", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-null-timing-"));
+  roots.push(root);
+  const file = join(root, "RUN-NULL.jsonl");
+  const records = timingRunRecords("RUN-NULL", "turn-null", {
+    input: null,
+    cached_input: null,
+    output: null,
+    reasoning: null,
+    total: null,
+  });
+  await writeFile(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+  const run = timingRun(file, records, "RUN-NULL", "turn-null");
+  const segment = completedSegment("segment-null", "turn-null");
+
+  const [result] = await remeasureSelectedRuns({
+    apply: true,
+    allSegments: [segment],
+    runs: [run],
+    selectedRunIds: new Set(["RUN-NULL"]),
+    timingOnly: true,
+    workspace: root,
+  });
+  const correction = usageView(jsonLines(await readFile(file, "utf8")).at(-2));
+  assert.equal(result.eligible, true);
+  assert.equal(result.applied, true);
+  assert.deepEqual(correction.tokens, records[1].tokens);
+  assert.deepEqual(correction.cost, records[1].cost);
   assert.equal(correction.source_started_at, segment.started_at);
   assert.equal(correction.source_finished_at, segment.finished_at);
 });
 
+test("timing-only rejects a mismatched or ambiguous client turn without appending", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-exact-turn-"));
+  roots.push(root);
+  for (const [runId, turnId, segments, reason] of [
+    [
+      "RUN-MISMATCH",
+      "turn-persisted",
+      [completedSegment("segment-other", "turn-other")],
+      "exact-segment-not-found",
+    ],
+    [
+      "RUN-AMBIGUOUS",
+      "turn-ambiguous",
+      [
+        completedSegment("segment-one", "turn-ambiguous"),
+        completedSegment("segment-two", "turn-ambiguous"),
+      ],
+      "ambiguous-segment",
+    ],
+  ]) {
+    const file = join(root, `${runId}.jsonl`);
+    const records = timingRunRecords(runId, turnId, {
+      input: null,
+      cached_input: null,
+      output: null,
+      reasoning: null,
+      total: null,
+    });
+    await writeFile(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+    const [result] = await remeasureSelectedRuns({
+      apply: true,
+      allSegments: segments,
+      runs: [timingRun(file, records, runId, turnId)],
+      selectedRunIds: new Set([runId]),
+      timingOnly: true,
+      workspace: root,
+    });
+    assert.equal(result.eligible, false);
+    assert.equal(result.reason, reason);
+    assert.deepEqual(jsonLines(await readFile(file, "utf8")), records);
+  }
+});
+
+function timingRunRecords(runId, turnId, tokens) {
+  return [
+    {
+      type: "run.started",
+      event_id: `${runId}:1`,
+      run_id: runId,
+      sequence: 1,
+      occurred_at: "2026-07-29T12:29:45.637Z",
+      phase: "execution",
+      client_turn_id: turnId,
+    },
+    {
+      type: "usage.recorded",
+      event_id: `${runId}:2`,
+      run_id: runId,
+      sequence: 2,
+      occurred_at: "2026-07-29T12:30:00.000Z",
+      phase: "execution",
+      tokens,
+      cost: { usd: null, brl: null },
+      supersedes_event_id: null,
+    },
+    {
+      type: "run.finished",
+      event_id: `${runId}:3`,
+      run_id: runId,
+      sequence: 3,
+      occurred_at: "2026-07-29T12:31:00.000Z",
+      phase: "execution",
+    },
+  ];
+}
+
+function timingRun(file, records, runId, turnId) {
+  return {
+    file,
+    records,
+    started: {
+      run_id: runId,
+      occurred_at: "2026-07-29T12:29:45.637Z",
+      phase: "execution",
+      client_turn_id: turnId,
+    },
+    usage: records.map(usageView).filter(Boolean),
+  };
+}
+
+function completedSegment(key, turnId) {
+  return {
+    key,
+    turn_id: turnId,
+    started_at: "2026-07-29T12:29:45.637Z",
+    finished_at: "2026-07-29T12:40:07.773Z",
+    usage: [
+      {
+        input_tokens: 10,
+        cached_input_tokens: 0,
+        output_tokens: 2,
+        reasoning_output_tokens: 0,
+        total_tokens: 12,
+      },
+    ],
+  };
+}
+
 test("uses the current correction clock instead of fabricating a pre-finish timestamp", () => {
   const current = new Date("2026-07-25T04:06:14.352Z");
   assert.equal(

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/source-size-telemetry/model-identity-reconciliation.mjs

@@ -0,0 +1,77 @@
+import { rename, writeFile } from "node:fs/promises";
+
+export async function reconcileGenericModelIdentities({
+  applyBackfill,
+  pricingFor,
+  runs,
+  segments,
+  usageView,
+  withSequence,
+  workspace,
+}) {
+  const segmentsByKey = new Map(segments.map((segment) => [segment.key, segment]));
+  const genericModel = (model) => typeof model === "string" && /^gpt-5$/i.test(model.trim());
+  let correctionsCount = 0;
+  for (const run of runs) {
+    const superseded = new Set(run.usage.map((usage) => usage.supersedes_event_id).filter(Boolean));
+    const effective = run.usage.filter((usage) => !superseded.has(usage.event_id));
+    const corrections = effective.flatMap((usage) => {
+      if (!genericModel(usage.model ?? run.started.model)) return [];
+      const segment = usage.source_segment_key
+        ? (segmentsByKey.get(usage.source_segment_key) ?? null)
+        : null;
+      return segment?.model && !genericModel(segment.model) ? [{ usage, segment }] : [];
+    });
+    correctionsCount += corrections.length;
+    if (!applyBackfill || corrections.length === 0) continue;
+
+    const correctionByTarget = new Map(corrections.map((item) => [item.usage.event_id, item]));
+    const updated = [];
+    let correctionIndex = run.usage.filter(
+      (usage) => usage.activity_kind === "model_identity_reconciliation",
+    ).length;
+    for (const record of run.records) {
+      updated.push(record);
+      const original = usageView(record);
+      const correction = original ? correctionByTarget.get(original.event_id) : null;
+      if (!correction) continue;
+      correctionIndex += 1;
+      const cost = await pricingFor(workspace, correction.segment.model, original.tokens);
+      updated.push({
+        schema_version: 2,
+        event_id: `${run.started.run_id}:model:${String(correctionIndex).padStart(6, "0")}`,
+        run_id: run.started.run_id,
+        sequence: 0,
+        occurred_at: original.occurred_at,
+        type: "usage.recorded",
+        phase: original.phase,
+        activity_kind: "model_identity_reconciliation",
+        classification_source: original.classification_source ?? "current_context",
+        tokens: original.tokens,
+        cost,
+        provider: original.provider ?? run.started.provider ?? "openai",
+        model: correction.segment.model,
+        source_segment_key: original.source_segment_key,
+        supersedes_event_id: original.event_id,
+        source_occurred_at:
+          original.source_occurred_at ??
+          correction.segment.finished_at ??
+          correction.segment.started_at,
+        ...(original.context_stats === undefined ? {} : { context_stats: original.context_stats }),
+        runtime: {
+          reasoning_effort: correction.segment.effort ?? original.runtime?.reasoning_effort ?? null,
+          service_tier: correction.segment.service_tier ?? original.runtime?.service_tier ?? null,
+        },
+      });
+    }
+    const resequenced = updated.map((record, index) => withSequence(record, index + 1));
+    const temporary = `${run.file}.model.tmp`;
+    await writeFile(
+      temporary,
+      `${resequenced.map((record) => JSON.stringify(record)).join("\n")}\n`,
+      "utf8",
+    );
+    await rename(temporary, run.file);
+  }
+  return correctionsCount;
+}

package/templates/.agents/skills/zaip-skill-sales-methodology/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: zaip-skill-sales-methodology
+description: Design evidence-backed sales processes, qualification playbooks, and configurable scripts. Use for internal sales-methodology work; not for external commercial acts or campaign production.
+---
+
+# Metodologia comercial
+
+## Localização canônica
+
+Salve processos comerciais, playbooks, scripts internos, matrizes de objeções e materiais de enablement em `.agents/sales/`. Não salve esses artefatos em `docs/`, na raiz do repositório ou em diretórios de brand, marketing ou growth.
+
+O arquivo central da área é `.agents/sales/playbook.md`; atualize-o quando uma decisão mudar o processo comercial, qualificação, handoff ou narrativa sales-facing. Materiais específicos podem ser arquivos adicionais na mesma pasta.
+
+1. Delimite empresa, oferta, ICP, persona, canal, origem inbound/outbound, etapa, nível de awareness, complexidade, ticket, ciclo, regiões, compliance e autoridade. Separe fato, evidência, hipótese e decisão; não fabrique consciência, urgência, prova, ROI, preço ou autoridade.
+2. Desenhe um playbook por etapa com objetivo, dono, entrada, abertura, perguntas, evidência, campos SPIN/BANT, transição, objeções, prova autorizada, microcompromisso, saída, CRM, handoff/SLA e próximo passo. Inclua caminhos de not-qualified, nurture e no-decision.
+3. Use as três etapas ZAIP: descoberta/pré-qualificação (tipicamente SDR), alinhamento/qualificação com handoff definido para closer, e fechamento/negociação pelo closer. O preço só pode ser apresentado como aprovado; proposta e contrato seguem o handoff autorizado.
+4. Aplique SPIN como banco adaptativo de Situation, Problem, Implication e Need-payoff, nunca como interrogatório ou ordem rígida. Use BANT como campos e gates de evidência (Budget, Authority, Need, Timing), nunca para pressionar ou desqualificar de forma manipulativa.
+5. Adapte narrativa, perguntas e CTA a unaware, problem-aware, solution-aware, product-aware e most-aware somente quando houver evidência do estágio. Use o roteiro genérico de qualificação curta e a estrutura de fechamento em [referência de processo](references/sales-process-framework.md).
+6. Aaron somente desenha ou melhora processo, playbook e script internos. Não contata prospects, envia proposta ou link de pagamento, altera preço/desconto, assina contrato nem executa ato comercial externo ou vinculante sem autoridade explícita.
+7. Encaminhe estratégia Growth/RevOps, estratégia empresarial e economia end-to-end para Robert; campanha e copy de aquisição para Lúcia; marca e tom ainda não decididos para Sarah; dados e métodos quantitativos para Gabi; políticas ou limites legais para Renata; e produção documental genérica para Clara. Sales-facing scripts e enablement pertencem a Aaron; copy de campanha pertence a Lúcia.

package/templates/.agents/skills/zaip-skill-sales-methodology/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Sales Specialist"
+  short_description: "Design evidence-based sales process and playbooks."
+  default_prompt: "Use $zaip-skill-sales-methodology to design a compliant sales process or playbook."

package/templates/.agents/skills/zaip-skill-sales-methodology/references/sales-process-framework.md

@@ -0,0 +1,77 @@
+# Framework de processo comercial
+
+## Fronteira e papéis
+
+O papel separa prospecção/SDR, qualificação inbound, closer/AE e gestão de conta ou Customer Success quando a operação exigir especialização. Aaron documenta as interfaces e os handoffs, mas não substitui a decisão de capacidade, estratégia de canal ou economia do funil de Robert.
+
+## Princípios adaptados
+
+Use Positioning, Pace e Practice como lentes de diagnóstico: adequação da narrativa ao mercado, ritmo e investimento autorizados, e capacidade de transformar o plano em prática observável. Organize o playbook nos blocos Targeting, Tools, Prospecting, Qualification e Follow-through. São uma adaptação conceitual das fontes listadas, não uma cópia nem uma sequência obrigatória.
+
+## Gates das três etapas
+
+| Etapa | Dono típico | Entrada | Saída | Handoff |
+| --- | --- | --- | --- | --- |
+| Descoberta e pré-qualificação | SDR | Lead ou conta elegível com origem registrada | Dor, urgência e contato adequado registrados, ou rota alternativa | Qualificação, nurture ou not-qualified |
+| Alinhamento e qualificação | SDR com closer definido | Contexto mínimo e interesse verificável | Fit, necessidade e próximo passo documentados antes de discutir preço | Handoff com CRM e SLA acordado ao closer |
+| Fechamento e negociação | Closer | Oportunidade aceita e escopo de conversa autorizado | Próximo passo, proposta ou contrato somente por fluxo autorizado; ou no-decision | Proposta/contrato autorizado, nurture ou encerramento registrado |
+
+Os gates são critérios de evidência, não metas de pressão. Dados indisponíveis ficam explícitos como lacuna.
+
+## Playbook configurável
+
+Configure empresa, oferta, ICP, persona, canal, origem, etapa, awareness, complexidade, ticket, ciclo, região e limites de compliance. Para cada etapa, registre objetivo, dono, critérios de entrada e saída, abertura, banco de perguntas, evidências, campos SPIN/BANT, transição, objeções, prova autorizada, microcompromisso, registro de CRM, handoff/SLA e próximo passo.
+
+Os três estágios ZAIP são: descoberta e pré-qualificação (dor, urgência e contato adequado); alinhamento e qualificação (fit e solução antes de preço, com handoff definido); e fechamento e negociação (closer, preço aprovado, objeções e próximo passo autorizado). Rotas explícitas para `not-qualified`, `nurture` e `no-decision` evitam fabricar avanço de pipeline.
+
+### Contrato de saída do script
+
+Um script reutilizável retorna campos configuráveis: `empresa`, `oferta`, `ICP`, `persona`, `canal`, `origem`, `etapa`, `awareness`, `complexidade`, `ticket`, `ciclo`, `região`, `compliance`, `objetivo`, `dono`, `entry_criteria`, `abertura`, `perguntas`, `evidências`, `BANT`, `SPIN`, `objeções`, `prova_autorizada`, `microcompromisso`, `exit_criteria`, `CRM`, `handoff_SLA` e `next_step`. O valor de cada campo pode ser placeholder neutro; campos ausentes não devem ser preenchidos por inferência.
+
+## Qualificação curta: outline configurável
+
+O modelo abaixo usa uma duração curta configurável (por exemplo, dez minutos), sem promessa rígida.
+
+1. Confirme contexto e permissão para a conversa.
+2. Declare a agenda ou objetivo em termos neutros.
+3. Verifique empresa, papel e origem conhecidos.
+4. Explore situação e prioridade atual.
+5. Pergunte por problema ou impacto já declarado.
+6. Investigue implicações sem presumir perda, risco ou urgência.
+7. Convide a pessoa a definir o valor de uma solução adequada.
+8. Registre participantes, processo decisório e BANT conhecido, desconhecido ou não aplicável.
+9. Recapitule somente o que foi confirmado e cheque o fit.
+10. Acorde informações obrigatórias, microcompromisso e próximo passo autorizado.
+
+Os itens 1–3 formam abertura/contexto; 4–8, diagnóstico; e 9–10, preparação/transição.
+
+SPIN organiza um banco de perguntas adaptável: Situation busca contexto já conhecido; Problem explora dificuldade declarada; Implication pergunta por consequências sem alegá-las; Need-payoff convida a pessoa a descrever valor. BANT registra Budget, Authority, Need e Timing com estado `known`, `unknown` ou `not-applicable`, fonte e data. Esses estados são evidência ou lacuna, nunca justificativa para pressão.
+
+| Awareness | Narrativa | CTA |
+| --- | --- | --- |
+| unaware | Contexto e hipótese aberta, sem presumir problema | Pedir permissão para explorar relevância |
+| problem-aware | Dor já declarada e impacto confirmado | Convidar diagnóstico adicional |
+| solution-aware | Critérios e alternativas reconhecidas | Alinhar critérios de avaliação |
+| product-aware | Oferta e fit sob análise | Confirmar lacunas e próximo passo |
+| most-aware | Informação previamente confirmada | Propor ação permitida e reversível |
+
+## Fechamento e negociação: outline configurável
+
+Um fechamento mais longo pode seguir: (1) rapport e contexto; (2) diagnóstico de dor, impacto e prioridade; (3) riscos e acordo sobre o problema; (4) solução ligada apenas às dores confirmadas; (5) prova autorizada; (6) objeções antes de preço; (7) preço e escopo aprovados; (8) negociação dentro da autoridade; e (9) handoff de proposta ou contrato autorizado. Não inclua depoimentos, ROI, escassez, descontos, links de pagamento ou alegações legais sem evidência e autorização.
+
+## Checklist de QA
+
+- Cada etapa contém dono, entrada, saída, CRM e handoff/SLA.
+- Perguntas e transições permanecem adaptáveis; não simulam necessidade, urgência ou consciência.
+- BANT/SPIN distinguem evidência de lacuna e não usam coerção.
+- Preço, proposta, desconto, contrato e negociação permanecem sob aprovação e autoridade explícitas.
+- Provas, ROI, depoimentos e claims legais só aparecem quando autorizados e rastreáveis.
+- Rotas `not-qualified`, `nurture` e `no-decision` existem e não são tratadas como falha do prospect.
+
+## Referências metodológicas
+
+- Predictable Revenue, [Sales Development Methodology](https://predictablerevenue.com/methodology/): referência para separar princípios estratégicos de playbook e para os blocos targeting, tools, prospecting, qualification e follow-through.
+- Predictable Revenue, [Specialize Your Sales Roles](https://predictablerevenue.com/guides/specialize-your-sales-roles/): referência para especialização de papéis e handoffs entre funções comerciais.
+- Huthwaite International, [origem do acrônimo SPIN](https://www.huthwaiteinternational.com/blog/spin-acronym): referência para os conceitos Situation, Problem, Implication e Need-payoff.
+
+As fontes são referência conceitual. Não reproduza conteúdo proprietário, não converta seus exemplos em regras rígidas e não introduza afirmações, nomes, preços, descontos, links ou obrigações externas.

package/templates/.agents/skills/zaip-skill-setup/SKILL.md

@@ -5,6 +5,11 @@ description: Install, diagnose, migrate, upgrade, or roll back ZAIP configuratio
 
 # Configurar ZAIP-AIOS
 
+For the isolated SQLite dashboard, also discover and use `$zaip-skill-sqlite-read-model`.
+The setup must verify Node.js 22+, install the LTS release with `winget` when the user has
+authorized automatic prerequisite installation, and create the disposable database only from
+canonical `.agents/records` and `.agents/config` sources.
+
 1. Faça dry-run, descubra a versão/layout e rejeite conflitos de checksum, ownership ou arquivos divergentes do usuário.
 2. Instale/valide `config/project.yaml`, `config/framework.lock.yaml`, as cinco Rules core diretamente em `rules/`, as Rules locais fora do lock preservadas, todos os Requirements/skills gerenciados pelo manifest, as raízes V2 de `data` e o dashboard frontend-only em `.agents/dashboard` quando ele fizer parte da distribuição.
 3. Nunca mantenha lista fixa da quantidade de Requirements ou skills no workflow; derive o catálogo do release/lock vigente.