@zaip-ai/cli 1.0.7 → 1.0.8

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,65 @@ 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,27 @@ 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 +192,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 +239,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 +259,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 +292,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-sales-methodology/SKILL.md

@@ -0,0 +1,14 @@
+---
+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
+
+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.

package/templates/.agents/skills/zaip-skill-sqlite-read-model/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: zaip-skill-sqlite-read-model
+description: Install the Node.js prerequisite and create, incrementally update, validate, or rebuild the disposable SQLite read model from canonical ZAIP records.
+---
+
+# SQLite read model
+
+Use this skill when installing, refreshing, or rebuilding the disposable SQLite
+read model. The canonical inputs are `.agents/records` and `.agents/config`;
+never load lifecycle overviews, dashboard projections, or other aggregates as
+an input.
+
+## Prerequisite and rebuild
+
+1. Confirm Node.js 22 or newer with `node --version`. If it is absent, install
+   the LTS release with `winget install --id OpenJS.NodeJS.LTS --exact` and
+   restart the terminal if `node` is still not on `PATH`.
+2. Rebuild the local runtime before rebuilding SQLite. The rebuild script imports
+   `packages/local-runtime/dist/server.cjs`; using an old bundle can create an
+   old schema even when `src/sqlite-read-model.ts` is current.
+3. Prefer the normal incremental refresh on dashboard startup. Do a full rebuild
+   after any schema/view/index change or when validation detects drift.
+4. Keep database files under `.local` (or another disposable local path),
+   untracked. Do not make DBeaver or a SQLite server a dependency.
+
+```powershell
+node .agents/dashboard/packages/local-runtime/scripts/build-sqlite-runtime.mjs
+node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs
+```
+
+If Windows reports `EPERM` or `EBUSY` replacing
+`.local/dashboard-sqlite/read-model.sqlite`, a live dashboard owns that file.
+Do not treat its old schema as validation evidence. Rebuild and validate an
+isolated generation instead:
+
+```powershell
+$env:ZAIP_SQLITE_DB_PATH = (Join-Path $PWD '.local/dashboard-sqlite/read-model-verify.sqlite')
+node .agents/dashboard/packages/local-runtime/scripts/rebuild-sqlite-read-model.mjs
+node .agents/dashboard/packages/local-runtime/scripts/validate-sqlite-read-model.mjs
+```
+
+Clear `ZAIP_SQLITE_DB_PATH` after the isolated check when the shell will start
+the normal dashboard again.
+
+## Current persisted schema and objective verification
+
+The current generator (`packages/local-runtime/src/sqlite-read-model.ts`) owns
+the schema. At schema version 60 it persists exactly these tables:
+
+- `zaip_aios_activities`
+- `zaip_dim_zaip_agent`
+- `zaip_dim_llm_model`
+- `zaip_dim_provider`
+- `cost_invocation_dimension_facts`
+
+Temporary staging tables and compatibility aliases are connection-local and are
+not persisted. Persisted views use exactly one `zaip_vw_` prefix; query them
+through the documented runtime view names rather than creating duplicate
+unprefixed objects. The generator also requires the activity, cost-dimension,
+and unique run indexes listed below.
+
+After every full rebuild, run this check against the same database generation.
+It verifies database integrity, the exact table inventory, view namespace and
+compilability, and the required indexes. It exits non-zero on drift.
+
+```powershell
+@'
+import assert from 'node:assert/strict';
+import { DatabaseSync } from 'node:sqlite';
+import { resolve } from 'node:path';
+
+const databasePath = process.env.ZAIP_SQLITE_DB_PATH ?? resolve('.local/dashboard-sqlite/read-model.sqlite');
+const database = new DatabaseSync(databasePath, { readOnly: true });
+try {
+  assert.equal(database.prepare('PRAGMA integrity_check').get().integrity_check, 'ok');
+  const objects = database.prepare("SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'").all();
+  const tables = objects.filter(({ type }) => type === 'table').map(({ name }) => name).sort();
+  assert.deepEqual(tables, ['cost_invocation_dimension_facts', 'zaip_aios_activities', 'zaip_dim_llm_model', 'zaip_dim_provider', 'zaip_dim_zaip_agent']);
+  const views = objects.filter(({ type }) => type === 'view').map(({ name }) => name);
+  assert.ok(views.length > 0, 'no persisted views');
+  assert.ok(views.every((name) => name.startsWith('zaip_vw_') && !name.startsWith('zaip_vw_vw_')), 'invalid persisted-view prefix');
+  for (const name of views) database.prepare(`SELECT * FROM main."${name.replaceAll('"', '""')}" LIMIT 0`).all();
+  const indexes = new Set(database.prepare("SELECT name FROM sqlite_master WHERE type='index'").all().map(({ name }) => name));
+  for (const name of ['zaip_activities_agent_run', 'zaip_activities_task_day', 'zaip_activities_spec_day', 'zaip_activities_prd_day', 'zaip_activities_run_id', 'zaip_activities_period_invocation', 'cost_dimension_facts_day_model', 'cost_dimension_facts_day_provider', 'cost_dimension_facts_invocation']) assert.ok(indexes.has(name), `missing index ${name}`);
+  console.log(JSON.stringify({ databasePath, tableCount: tables.length, viewCount: views.length, requiredIndexCount: 9 }));
+} finally {
+  database.close();
+}
+'@ | node --input-type=module
+```
+
+The checked-in `validate-sqlite-read-model.mjs` and
+`test-sqlite-read-model.mjs` are the installation gates for schema 60. They
+assert the five persisted tables, the `zaip_vw_` view namespace and required
+indexes against a freshly rebuilt database. Do not use an old database or
+weaken those assertions to hide a schema mismatch.

package/templates/.agents/skills/zaip-skill-sqlite-read-model/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP SQLite Read Model"
+  short_description: "Refresh the disposable SQLite dashboard read model."
+  default_prompt: "Use $zaip-skill-sqlite-read-model to prepare or refresh the SQLite read model from canonical ZAIP records."

package/templates/.agents/skills/zaip-skill-sqlite-read-model/scripts/ensure-node.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from "node:child_process";
+
+const minimumMajor = 22;
+function version() {
+  try { return execFileSync(process.execPath, ["--version"], { encoding: "utf8" }).trim(); } catch { return null; }
+}
+const current = version();
+if (current && Number.parseInt(current.slice(1), 10) >= minimumMajor) {
+  process.stdout.write(`${current} is ready\n`);
+  process.exit(0);
+}
+if (process.platform !== "win32") throw new Error(`Node.js ${minimumMajor}+ is required; automatic installation is only configured for Windows.`);
+try {
+  execFileSync("winget", ["install", "--id", "OpenJS.NodeJS.LTS", "--exact", "--accept-source-agreements", "--accept-package-agreements"], { stdio: "inherit" });
+} catch (error) {
+  throw new Error("Node.js 22+ is missing and winget could not install the LTS release. Install Node.js manually and retry.", { cause: error });
+}
+process.stdout.write("Node.js LTS installation completed. Restart the terminal before running the SQLite generator.\n");

package/templates/.agents/zaip-aios/INDEX.md

@@ -20,6 +20,7 @@ Use esta pagina como roteador de baixo custo de tokens.
 | Diagnosticar problemas | `guides/14-troubleshooting.md` |
 | Configurar MCPs, APIs e Codex | `guides/15-tools-e-codex.md` |
 | Entender status, Runs e reconciliação | `guides/16-lifecycle-e-reconciliacao.md` |
+| Entender tokens, precificacao e conversao de moeda | `guides/17-como-o-custo-e-calculado.md` |
 | Escolher MCP ou API | `../tools/catalog.yaml` |
 
 Antes de agir, prevalecem `../config/project.yaml`, as Rules aplicaveis e os