@zaip-ai/cli 6.2.0 → 7.5.0

package/templates/.agents/skills/zaip-skill-screenshot-intake/references/runtime-workflow.md

@@ -0,0 +1,110 @@
+# Portable screenshot intake
+
+The installed consumer uses only Node builtins in `.agents/tools/visual-intake/`.
+No maintainer adapters/testing package, Figma connector or dependency installation is
+needed. Inspect whether that directory exists before claiming runtime capability.
+
+Every invocation supplies an existing workspace, a stable conversation ID and session
+ID explicitly. IDs contain letters, digits, `_` or `-` (maximum 64 characters).
+Persistence remains `.agents/private/state/visual-intake/<session-id>/`; `identity.json` binds the
+conversation and a hash of the real workspace path. A collision with another chat or
+workspace is rejected. Never resolve a session by “latest”. Sensitive request files,
+notes and exported analysis belong in ignored `.local/` destinations.
+
+```powershell
+node .agents/tools/visual-intake/cli.mjs create --workspace . --conversation chat-001 --session screenshots-001 --input .local/temp/intake-create.json
+node .agents/tools/visual-intake/cli.mjs batch --workspace . --conversation chat-001 --session screenshots-001 --input .local/temp/intake-batch.json
+node .agents/tools/visual-intake/cli.mjs read --workspace . --conversation chat-001 --session screenshots-001
+node .agents/tools/visual-intake/cli.mjs finish --workspace . --conversation chat-001 --session screenshots-001 --input .local/temp/intake-finish.json
+node .agents/tools/visual-intake/cli.mjs report --workspace . --conversation chat-001 --session screenshots-001 --input .local/temp/intake-export.json
+```
+
+Create input: `{"request_id":"create-001","expected_revision":0,"mode":"report-only"}`.
+Use a new request ID for each deliberate operation; `expected_revision` is the latest
+verified revision. Optional total is `{ "value":23, "origin":"user-reported" }`.
+The first verified revision is 1. A batch increments it once, regardless of image count.
+
+Batch input follows [request example](request-example.json). Supply 1–10 images with
+new stable IDs. Save each image's own classified notes after actually examining it.
+`viewed:true` is an agent assertion, not something this runtime certifies. For an
+unviewed image use only unknown observations and keep finalization pending. The
+example is structural guidance, not evidence that any image was examined.
+
+For bytes available through authorized local access, `source.path` is a relative image
+file inside the workspace, and `unavailable_reason:null`. The runtime measures bytes,
+SHA-256 and recognized header metadata, then preserves the bytes in `sources/`.
+It does not decode/render images or prove they are visually meaningful. If attachment
+pixels are visible in chat but no bytes/path are accessible, set `path:null`, retain the
+observed attachment locator and explain the gap. No image hash/path/byte count is invented.
+
+The returned receipt acknowledges notes only after the manifest, every note and all
+claimed saved assets can be read and verified. `assets_preserved` and
+`assets_unavailable` explicitly separate byte retention from note retention.
+An exact same command/request returns its original receipt, without adding images.
+A changed replay payload is rejected. A deliberate duplicate uses a new request/image
+ID and keeps its own context and position; `duplicate_of` references the earlier image
+with matching actual bytes or the same observed attachment locator. A filename or
+visual resemblance does not establish duplicate identity.
+
+`correct` takes `{request_id,expected_revision,image_id,note}`; its note has the same
+three fields as the batch example. Correction requires collecting state and preserves
+the earlier manifest revision. After finalization call `reopen` with
+`{"request_id":"reopen-001","expected_revision":5,"reopen":true}` before new input.
+Earlier revisions and immutable report exports remain retained.
+
+Finish input includes the actual human message locator and its observed timestamp:
+
+```json
+{"request_id":"finish-001","expected_revision":4,"finish":{"explicit":true,"observed_at":"2026-10-11T22:00:00-03:00","reference":"observed-human-message-locator"}}
+```
+
+Replace those values from observation; do not copy them as proof. Empty intake,
+unviewed notes and a reported-total mismatch prevent finalization. No total or finish
+is inferred from batch length or silence. Without finish, an explicitly requested
+partial export is permitted and labeled partial.
+
+Export input:
+`{"partial":false,"destination":".agents/private/state/visual-intake-exports/base-001.md","export_authorized":true}`.
+Set `destination:null` to return the report without another export. A destination must
+be authorized, inside that namespace and end in `.md`; existing different content is
+not overwritten. This deterministic export is a verified evidence base. Complete the
+agent's detailed synthesis using the visual-report workflow, as a separate authorized
+artifact linked to snapshot/revision/image IDs. Do not call the base alone a full analysis.
+
+## Recovery
+
+The kernel holds exclusion for the entire invocation: a Windows named pipe; on other
+platforms an exclusive listener bound only to 127.0.0.1. The mechanism is selected before
+acquisition. A busy pipe, local port collision or other acquisition error fails closed,
+without switching authority or bypassing the writer. It accepts no commands or image
+data. JSON is metadata, not the authority for exclusion. Unexpected path replacement,
+symlinks/reparse points, traversal and corrupt notes/assets/receipts fail closed.
+
+Files are staged and individually atomically replaced. A checksummed `journal.json`
+permits roll-forward after a crash. Before a complete journal exists, stages remain
+unacknowledged and the prior manifest stays authoritative; reissue the exact request.
+After a sealed journal exists, the next invocation verifies and completes it, including
+a crash in finalizing or before/after receipt. No whole-filesystem atomic transaction
+or power-loss durability is promised. Retained stages/quarantine are recovery material,
+not receipts; do not delete them during normal intake.
+
+A complete claim left by a dead process is reclaimed under kernel exclusion. A
+partial/unreadable claim is preserved and requires an explicit technical recovery:
+
+```powershell
+node .agents/tools/visual-intake/cli.mjs recover --workspace . --conversation chat-001 --session screenshots-001 --input .local/temp/intake-recover.json
+```
+
+Input: `{"request_id":"repair-001","expected_revision":2,"repair":true}`. Determine
+the revision from the explicitly bound state/journal, not a global intake. Under
+exclusion the runtime validates namespace and existing state/journal, completes a
+valid journal, verifies notes/assets, and quarantines unreadable metadata without loss.
+Use the post-journal revision when recovery completes a pending journal. A failed
+integrity check preserves metadata for diagnosis; restore only known correct scoped
+bytes or seek a bounded repair. The command needs no OAuth, host restart or user
+confirmation beyond existing authorization to recover this intake. Future manifest
+schema versions remain unchanged and are rejected; migration needs a separate contract.
+
+Checksums prove local consistency only. They do not authenticate visual observations,
+human messages, outside modifications or image ownership. Fault-injection options are
+maintainer fixtures only and must never be used on a live intake.

package/templates/.agents/skills/zaip-skill-search-observability/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: zaip-skill-search-observability
+description: Inspect Search Console, Bing Webmaster and GA4 search evidence with verified property, windows and provenance; use for visibility, indexing, AI citations or search traffic analysis, with read-only export fallback.
+---
+
+# Search observability
+
+Use for an actual search-measurement question. This workflow reads evidence; it never
+changes accounts, indexing settings, bot policy or website content by implication.
+
+1. Define question, property, owner, dates, timezone, comparison and filters. Discover
+   tools in this session; verify authenticated account and exact property before reading.
+   Availability is not permission or completeness. Never use another account as fallback.
+2. Follow [the workflow](references/workflow.md) using observed schemas and pagination;
+   never invent connector names, report fields or API metrics.
+3. Missing read tools use an authorized sanitized aggregate export with
+   [the template](references/report-template.md). Do not request tokens or raw personal queries.
+4. Normalize evidence offline when useful:
+   `node .agents/skills/zaip-skill-search-observability/scripts/search-report.mjs evidence.json`.
+   This validates declared metadata, not account authentication or export truth.
+5. Compare matching windows/filters. Keep indexed pages, impressions, clicks, citations,
+   sessions and conversions separate. Unavailable is not zero; AI export zero may be ambiguous.
+6. Deliver provenance, observations, limitations and next bounded diagnostic. No ranking,
+   AI-placement or attribution guarantees. Technical fixes use
+   [website readiness](../zaip-skill-website-readiness/SKILL.md); real submissions follow
+   its [change-discovery workflow](../zaip-skill-website-readiness/references/change-discovery.md)
+   under separate authorization.

package/templates/.agents/skills/zaip-skill-search-observability/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Search Observability"
+  short_description: "Inspect search evidence with account-aware provenance."
+  default_prompt: "Use $zaip-skill-search-observability to inspect search performance with verified property, dates and evidence limits."

package/templates/.agents/skills/zaip-skill-search-observability/references/report-template.md

@@ -0,0 +1,32 @@
+# Aggregate evidence template
+
+Synthetic example, not account proof. Fill only from authorized aggregate observation;
+omit contacts, tokens, individual identifiers and raw personal queries. Helper rejects
+extra fields and performs no fetch or cross-provider totals.
+
+```json
+{
+  "schema_version": 1,
+  "provider": "search-console-ai",
+  "property": "https://example.test/",
+  "window": {"start": "2026-10-01", "end": "2026-10-07", "timezone": "America/Los_Angeles"},
+  "source": {"kind": "export", "locator": "aggregate.csv", "extracted_at": "2026-10-29T12:00:00Z", "complete": false},
+  "filters": {"country": "BR", "device": "mobile"},
+  "metrics": {"impressions": {"status": "ambiguous", "value": 0}},
+  "preliminary": true
+}
+```
+
+Providers: search-console, search-console-ai, bing-webmaster, ga4. Metrics are separate:
+ordinary search impressions/clicks/indexed_pages; AI Search Console impressions only;
+Bing citations/cited_pages/impressions/clicks where actually observed; GA4 sessions/
+conversions when defined in that report. These are permitted aggregate fields, not
+claims that a given report/API exposes them.
+
+Status observed requires a nonnegative number; unavailable requires null; ambiguous
+permits null or export zero. AI export zero becomes ambiguous unless `zero_verified:true`
+records an independent UI/source-metadata check. That field is a declaration requiring
+review, never proof by itself. Incomplete/preliminary data cannot become complete.
+
+Deliver question, exact scope/provenance, metrics with status, comparable changes,
+limitations, actual artifact locator/hash and next action. No sum of overlapping reports.

package/templates/.agents/skills/zaip-skill-search-observability/references/workflow.md

@@ -0,0 +1,56 @@
+# Read-only search evidence workflow
+
+Official sources reviewed by host 2026-10-29; revalidate changed features before adoption.
+Availability is account/rollout dependent, not a universal capability requirement.
+
+## Collection and provenance
+
+Confirm account and property/domain/URL-prefix, owner, requested read scope and actual
+tool schema. Record report/API version, extraction time, source window/timezone, filters,
+pagination completeness, aggregation, preliminary status and artifact locator/hash.
+Read-only OAuth scopes still require permission. Missing tools use UI or authorized
+aggregate export, never fabricated API results or another account. No tokens, contacts,
+raw personal queries, submissions or configuration changes belong in this workflow.
+
+## Search Console
+
+- URL indexing/inspection, impressions and clicks are different observations. HTTP200,
+  crawl permission and sitemap acceptance do not prove indexing or search appearance.
+- Record canonical URL, date in Pacific Time, country, device and search type. Chart
+  property aggregation differs from page-table aggregation. Record text/multimodal only
+  when exposed by the actual report; do not invent equivalent API dimensions.
+- Generative AI report concerns impressions for AI Overviews/AI Mode; do not promise
+  clicks or an API. Those observations are already included in Web Performance: never
+  sum these reports as additional traffic. Latest values may be preliminary.
+- Missing report can mean low observed activity or access/capability limits, not zero.
+  UI `~`/`-` unavailable values become zero in download. Preserve export origin and
+  ambiguity; zero without distinguishing metadata cannot be claimed as observed zero.
+- Include/Exclude/Inherit is a separate setting: root default Include, child default
+  Inherit. Verify exact property and inherited/explicit value; changing it requires owner
+  authorization. It is distinct from training and traditional search ranking.
+
+## Bing Webmaster Tools
+
+Confirm site, report/window/filters and capabilities actually returned. June2026 AI
+visibility/citation features may be preview/account dependent. Citations/citation share,
+indexed pages, ranking and visits are distinct. Never infer zero from unavailable reports.
+
+## GA4
+
+Confirm property/stream, timezone, report identity, filters, consent effects and sampling/
+thresholds where observed. Organic/referral sessions, events and key events are not Search
+Console clicks or AI citations. Referrers cannot identify every AI visit. Changing key
+events, consent or attribution settings is outside this read-only workflow.
+
+## Handoff
+
+Align windows, cohorts and definitions before comparisons; distinguish observation from
+hypothesis. Propose one bounded HTTP/rendering, indexing, content, filters or tracking
+investigation. No raw personal data or claims of account-authentication from helper JSON.
+
+Sources:
+- https://support.google.com/webmasters/answer/16984139
+- https://support.google.com/webmasters/answer/16908024
+- https://developers.google.com/search/docs/fundamentals/ai-optimization-guide
+- https://blogs.bing.com/search/2026/6/New-AI-Visibility-Insights-in-Bing-Webmaster-Tools-Intents-Topics-Citation-Share-Compare/
+- https://support.google.com/analytics/answer/9317498

package/templates/.agents/skills/zaip-skill-search-observability/scripts/search-report.mjs

@@ -0,0 +1,139 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const metrics = {
+  "search-console": ["impressions", "clicks", "indexed_pages"],
+  "search-console-ai": ["impressions"],
+  "bing-webmaster": ["citations", "cited_pages", "impressions", "clicks"],
+  ga4: ["sessions", "conversions"],
+};
+function shape(value, keys) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some((k) => !keys.includes(k))
+  )
+    throw Error("Unsupported evidence fields");
+}
+export function searchReport(input) {
+  shape(input, [
+    "schema_version",
+    "provider",
+    "property",
+    "window",
+    "source",
+    "filters",
+    "metrics",
+    "preliminary",
+  ]);
+  if (input.schema_version !== 1 || !Object.hasOwn(metrics, input.provider))
+    throw Error("Unsupported provider/version");
+  if (typeof input.property !== "string" || input.property.length > 512)
+    throw Error("Expected property identity");
+  if (input.provider === "ga4") {
+    if (!/^properties\/\d+$/.test(input.property)) throw Error("Expected GA4 property resource");
+  } else if (!/^sc-domain:[a-z\d.-]+$/i.test(input.property)) {
+    const url = new URL(input.property);
+    if (
+      !["http:", "https:"].includes(url.protocol) ||
+      url.username ||
+      url.password ||
+      url.search ||
+      url.hash
+    )
+      throw Error("Unsafe property URL");
+  }
+  shape(input.window, ["start", "end", "timezone"]);
+  for (const name of ["start", "end"])
+    if (
+      !/^\d{4}-\d{2}-\d{2}$/.test(input.window[name]) ||
+      new Date(input.window[name]).toISOString().slice(0, 10) !== input.window[name]
+    )
+      throw Error("Invalid date window");
+  if (input.window.end < input.window.start || typeof input.window.timezone !== "string")
+    throw Error("Invalid date window/timezone");
+  new Intl.DateTimeFormat("en", { timeZone: input.window.timezone }).format();
+  shape(input.source, ["kind", "locator", "extracted_at", "complete"]);
+  if (
+    !["export", "api", "connector", "ui"].includes(input.source.kind) ||
+    typeof input.source.complete !== "boolean" ||
+    !Number.isFinite(Date.parse(input.source.extracted_at)) ||
+    !/^[a-z\d._/-]{1,160}$/i.test(input.source.locator ?? "") ||
+    input.source.locator.split("/").includes("..") ||
+    input.source.locator.startsWith("/")
+  )
+    throw Error("Invalid sanitized provenance");
+  shape(input.filters ?? {}, ["country", "device", "search_type"]);
+  if (input.filters?.country && !/^[A-Z]{2,3}$/.test(input.filters.country))
+    throw Error("Invalid country filter");
+  if (
+    input.filters?.device &&
+    !["mobile", "desktop", "tablet", "all"].includes(input.filters.device)
+  )
+    throw Error("Invalid device filter");
+  if (
+    input.filters?.search_type &&
+    !["web", "image", "video", "news", "text", "multimodal"].includes(input.filters.search_type)
+  )
+    throw Error("Invalid search type");
+  if (typeof input.preliminary !== "boolean") throw Error("Declare preliminary status");
+  shape(input.metrics, metrics[input.provider]);
+  if (!Object.keys(input.metrics).length) throw Error("No metric fields");
+  const result = {};
+  for (const [key, value] of Object.entries(input.metrics)) {
+    shape(value, ["status", "value", "zero_verified"]);
+    if (
+      !["observed", "unavailable", "ambiguous"].includes(value.status) ||
+      (value.zero_verified !== undefined && typeof value.zero_verified !== "boolean")
+    )
+      throw Error("Invalid metric status");
+    if (
+      value.status === "observed"
+        ? typeof value.value !== "number" || !Number.isFinite(value.value) || value.value < 0
+        : value.value !== null && !(value.status === "ambiguous" && value.value === 0)
+    )
+      throw Error("Invalid metric value/status");
+    const ambiguous =
+      input.provider === "search-console-ai" &&
+      input.source.kind === "export" &&
+      value.value === 0 &&
+      value.zero_verified !== true;
+    result[key] = {
+      status: ambiguous ? "ambiguous" : value.status,
+      value: ambiguous ? null : value.value,
+    };
+  }
+  return {
+    schema_version: 1,
+    kind: "search-observation",
+    provider: input.provider,
+    property: input.property,
+    window: input.window,
+    source: input.source,
+    filters: input.filters ?? {},
+    preliminary: input.preliminary,
+    metrics: result,
+    complete:
+      input.source.complete &&
+      !input.preliminary &&
+      Object.values(result).every((m) => m.status === "observed"),
+    authenticity: "declared_metadata_not_authenticated",
+    limitations: [
+      "No network or account authentication performed",
+      "Metrics are not interchangeable; no cross-report totals calculated",
+    ],
+  };
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    if (process.argv.length !== 3) throw Error("Usage: search-report.mjs evidence.json");
+    const bytes = await readFile(resolve(process.argv[2]));
+    if (bytes.length > 65536) throw Error("Evidence exceeds 64KiB");
+    console.log(JSON.stringify(searchReport(JSON.parse(bytes)), null, 2));
+  } catch {
+    console.error("Search evidence rejected: review schema, scope and sanitized provenance");
+    process.exitCode = 1;
+  }
+}

package/templates/.agents/skills/zaip-skill-search-observability/scripts/search-report.test.mjs

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { searchReport } from "./search-report.mjs";
+
+function fixture() {
+  return {
+    schema_version: 1,
+    provider: "search-console-ai",
+    property: "https://example.test/",
+    window: { start: "2026-10-01", end: "2026-10-07", timezone: "America/Los_Angeles" },
+    source: {
+      kind: "export",
+      locator: "aggregate.csv",
+      extracted_at: "2026-10-29T12:00:00Z",
+      complete: true,
+    },
+    filters: { device: "mobile" },
+    metrics: { impressions: { status: "observed", value: 0 } },
+    preliminary: false,
+  };
+}
+test("AI export zero is ambiguous without independent source metadata", () => {
+  const f = fixture();
+  assert.deepEqual(searchReport(f).metrics.impressions, { status: "ambiguous", value: null });
+  assert.equal(searchReport(f).complete, false);
+  f.metrics.impressions.zero_verified = true;
+  assert.equal(searchReport(f).metrics.impressions.value, 0);
+});
+test("unavailable stays null and preliminary never complete", () => {
+  const f = fixture();
+  f.metrics.impressions = { status: "unavailable", value: null };
+  assert.equal(searchReport(f).metrics.impressions.value, null);
+  assert.equal(searchReport(f).complete, false);
+  f.metrics.impressions = { status: "observed", value: 12 };
+  f.preliminary = true;
+  assert.equal(searchReport(f).complete, false);
+});
+test("provider metric boundaries reject invented AI clicks and personal fields", () => {
+  const f = fixture();
+  f.metrics.clicks = { status: "observed", value: 1 };
+  assert.throws(() => searchReport(f));
+  delete f.metrics.clicks;
+  f.filters.query = "personal@example.test";
+  assert.throws(() => searchReport(f));
+});
+test("scope, missing status, dates and unsafe provenance reject", () => {
+  for (const edit of [
+    (f) => (f.property = "https://user:password@example.test"),
+    (f) => (f.window.end = "2026-09-01"),
+    (f) => (f.source.locator = "../private"),
+    (f) => (f.metrics.impressions = { value: 1 }),
+    (f) => (f.provider = "unknown"),
+  ]) {
+    const f = fixture();
+    edit(f);
+    assert.throws(() => searchReport(f));
+  }
+});
+test("GA4 sessions remain separate and provenance is never self-authenticated", () => {
+  const f = fixture();
+  f.provider = "ga4";
+  f.property = "properties/123";
+  f.metrics = { sessions: { status: "observed", value: 7 } };
+  const r = searchReport(f);
+  assert.equal(r.metrics.sessions.value, 7);
+  assert.equal(r.authenticity, "declared_metadata_not_authenticated");
+});
+test("HTTP URL-prefix property remains valid independently of crawler transport", () => {
+  const f = fixture();
+  f.property = "http://example.test/prefix/";
+  assert.equal(searchReport(f).property, f.property);
+});

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

@@ -5,15 +5,37 @@ description: Install or update ZAIP-AIOS and format the final chat response afte
 
 # Instalar ZAIP-AIOS
 
+O onboarding padrão verifica somente dependências locais, instalação, Git, identidade,
+origin GitHub e primeiro commit local, com pendências claras. Siga o
+[contrato de onboarding básico](references/basic-onboarding.md).
+Não ofereça novos agentes, mudanças no core ou na lógica de orquestração.
+
 Aplique a proteção do computador local de `RULE-CORE`: nunca reinicie/desligue o PC. Antes de executar instaladores, confirme opções documentadas que suprimam reinício automático; não use `--allow-reboot`. Se a supressão não puder ser garantida, pare essa etapa. Informe reinício pendente para ação manual do usuário.
 
-Para Supabase, a instalação nunca cria branch, preview ou custo hospedado. O fluxo protegido de migrations exige uma branch beta persistente e GitHub Integration verificada; explique o custo antes de qualquer provisionamento e registre confirmação informada na configuração. Sem beta, prepare localmente e pare: migrations nunca seguem para `main`. Somente uma recusa explícita da beta permite o modo manual: uma pessoa executa SQL exportado no SQL Editor; agente, pipeline e startup nunca o aplicam.
+Integrações hospedadas, branches de banco e migrations não fazem parte do onboarding
+básico. Não provisione recursos nem gere custos durante o init. Uma configuração
+específica posterior segue os contratos de `$zaip-skill-config`.
 
 Use somente o pacote público `@zaip-ai/cli`: `npx @zaip-ai/cli@latest init`.
 Para escolher o perfil, acrescente `--profile full|dev-lite|lite` ao comando `init`.
 
+Instalações novas usam somente Codex, sem pergunta sobre cliente. Claude é opcional:
+somente a pedido explícito, use `npx @zaip-ai/cli@latest init --claude`.
+Essa opção habilita os adapters Claude; não instala o aplicativo Claude Code.
+Atualizações preservam a seleção existente em `project.yaml#clients`, inclusive
+Claude já habilitado; não desabilite escolhas anteriores nem apague customizações.
+
 ## Atualização solicitada
 
+Antes do primeiro comando de atualização em projeto com governança ativa, capture o pedido
+como trabalho executável (`conversation start --intent new-work`, ou `continue` com foco
+válido da mesma thread), com título semântico de 4 a 10 palavras e escopo do instalador.
+Obtenha `task workspace TASK --run RUN` antes da escrita. Não capture uma atualização
+explicitamente pedida como `conversation`: isso deixa os reparos sem Run/claim autorizado.
+Inclua no escopo os arquivos efetivamente planejados, adapters e arquivos de dependências
+do perfil. Reutilize a autorização humana do update e siga a execução/fechamento canônicos.
+Instalação inicial sem runtime instalado não depende de criar uma Task inexistente.
+
 Pedido simples de “update”, “atualize o ZAIP” ou equivalente em projeto instalado usa, por padrão,
 `npx --yes @zaip-ai/cli@latest init --force --yes --profile full` (Windows: `npx.cmd`).
 O pedido autoriza a reinstalação com backup automático e a instalação das dependências e
@@ -21,58 +43,48 @@ pré-requisitos do perfil completo, sem nova confirmação ou dry-run obrigatór
 dry-run ou restrições explícitas prevalecem. O primeiro `--yes` aceita baixar a CLI; o segundo
 confirma o force. Preserve as proteções transacionais e de ownership do instalador.
 Se houver falha, diagnostique o erro concreto; não apague arquivos para contorná-la.
+Leia a lista `Divergentes` completa e o motivo por caminho; não filtre o log apenas pela
+palavra conflito. Use comandos literais separados: pipes/redirecionamentos podem exigir
+autoridade adicional no hook. Um bloqueio de captura/claim deve ser resolvido no fluxo
+canônico, sem desligar hooks, fabricar identidade ou repetir o mesmo comando em loop.
+Rules locais na raiz ou em `.agents/rules/project` são preservadas. `--force --yes`
+substitui conteúdo oficial e arquiva no backup os arquivos oficiais aposentados, mesmo
+editados; colisões entre dois conteúdos locais ou configuração inválida continuam exigindo
+resolução concreta. `project.yaml` recebe defaults compatíveis ausentes e migrações explícitas,
+preservando extensões e escolhas existentes; não importa silenciosamente novos modos de
+execução, autonomia ou deploy. Configurações pessoais Claude e entradas cloud do consumidor
+também sobrevivem. Backup planejado e ações previstas não comprovam aplicação.
 Valide pelo resultado do init e `doctor --json` do runtime instalado, sem auditar abas do
 Dashboard ou exportações XLSX. Informe versão, backup, dependências e pendências observadas.
 Esse fluxo instala dependências ausentes e preserva as já instaladas; não executa `npm update`.
 
 ## Instalação inicial
 
-For the isolated SQLite dashboard, also discover and use `$zaip-skill-sqlite-read-model`.
-Create the disposable dashboard database only from canonical `.agents/records` and
-`.agents/config` sources.
+O init pode preparar o cache SQLite a partir das fontes canônicas. Essa preparação
+não exige abrir, testar abas ou executar a suíte do dashboard interno no consumidor.
 
-1. Se o `init` acabou de concluir neste turno, vá diretamente ao modelo obrigatório de resposta abaixo; não reinstale nem inicie configuração. Para uma nova instalação, use o pedido explícito de instalação como autorização. Se já houver `.agents/config/project.yaml` e o pedido for atualização, aplique o fluxo acima; encaminhe configuração, personalização ou primeiros passos para `$zaip-skill-config`.
+1. Se o `init` acabou de concluir nesta etapa, verifique o resultado e responda sem reinstalar. Para uma nova instalação, use o pedido explícito de instalação como autorização. Se já houver `.agents/config/project.yaml` e o pedido for atualização, aplique o fluxo acima. Instalação/update autorizado inclui reparos gerenciados necessários, migração compatível e dependências do perfil; preserve customizações, histórico e dados. Configuração/personalização pertence a `$zaip-skill-config` e só avança se fizer parte do pedido autorizado.
 2. Faça dry-run e detecte apenas conflitos que impeçam a instalação inicial, como checksum, ownership ou arquivos do usuário que seriam sobrescritos.
-3. Verifique Node.js 22+; instale a versão LTS com `winget` somente quando o usuário tiver autorizado a instalação automática do pré-requisito.
+3. Verifique a versão de Node.js exigida pelo manifesto do release e os pré-requisitos do perfil; instale dependências ausentes somente no escopo autorizado, sem reiniciar o host.
 4. Instale e valide o conteúdo do release: `config/project.yaml`, `config/framework.lock.yaml`, Rules core, Requirements e skills gerenciados pelo manifest, raízes V3 de `records` e, quando distribuído, o dashboard frontend-only em `.agents/dashboard`. Preserve arquivos e Rules locais do projeto.
 5. Nunca mantenha lista fixa da quantidade de Requirements ou skills; derive o catálogo do release/lock instalado.
-6. Rode as validações aplicáveis à instalação, incluindo `doctor`, skills, encoding, architecture e adapters; repita o dry-run e exija ausência de drift.
-7. Após a instalação, use `$zaip-skill-dev-environment` para inventariar apenas nomes e presença de pré-requisitos. Para configurar o projeto, personalizar perfis Codex ou seguir os primeiros passos, use `$zaip-skill-config`.
-8. A instalação deixa `beta` como ramo padrão de frontend, backend e banco, mas não cria uma branch Supabase hospedada, integração GitHub, credencial ou custo adicional. A configuração protegida de migrations é uma escolha posterior e explícita pelo `$zaip-skill-config`.
+6. Confira o resultado do init, `doctor --json`, `adapters check --json` e o estado separado dos hooks. Não execute auditoria de arquitetura, suítes do produto ou dashboard por padrão. Investigue somente falhas observadas; não repita init/dry-run sem motivo novo.
+7. Use `$zaip-skill-dev-environment` quando um pré-requisito estiver ausente ou for necessário diagnosticar a instalação; inventarie somente nomes/presença. Não abra uma entrevista de configuração nem ofereça CTA obrigatório se nada depender de uma escolha humana.
+8. Preserve destinos de deploy existentes, inclusive frontend/backend em `main`. Não configure hosting ou banco durante onboarding básico. A configuração protegida de migrations é uma escolha posterior e explícita pelo `$zaip-skill-config`.
 
 ## Ativação Codex em instalação e atualização
 
-Sempre consulte `node .agents/runtime/bin/zaip.mjs hook status --json` após instalar
-ou atualizar. `doctor` reporta hooks separadamente da validade dos arquivos.
-Use hooks somente do repositório; não instale fallback global. Preserve terceiros
-e configurações personalizadas na migração, com backup dos hooks ZAIP removidos.
-
-Sem prova atual, informe “Arquivos instalados; integração Codex ainda não validada”.
-Oriente: “Abra o ícone de hooks (âncora) na área de digitação do chat do Codex,
-sem depender da cor do ícone. Quando houver o aviso ‘precisam de revisão’, abra
-a revisão dos hooks ZAIP-AIOS e clique em Permitir tudo. Se houver terceiros,
-selecione somente ZAIP. Interruptor ligado não comprova revisão nem aprovação.”
-A âncora de resultado/estatística é outro controle; a revisão dos hooks fica no input.
-Termine com **Depois de aprovar os hooks, pode me avisar para validar?** Essa pergunta
-substitui o CTA Git/configuração abaixo enquanto a ativação estiver pendente.
-Não peça nova aprovação quando a integração atual já estiver validada.
-
-Após o aviso, confira eventos reais pelo Codex: leitura segura e um subagente pequeno
-com início/término observados, autorizado no onboarding. Executar o script direto
-não prova aprovação. Sem confirmação, consultas e planejamento continuam disponíveis;
-entregas dependentes da integração aguardam validação. Nunca autoaprove a trust store.
-
-Stop só ocorre depois da resposta: confirme essa segunda etapa na interação seguinte,
-com recibo exato, sem gerar continuação automática. `closure_pending` não é sucesso.
-Mudanças de scripts/configuração invalidam evidência anterior; atualização sempre
-reverifica, mas não exige aprovação repetida sem necessidade. Ausência de prova é
-“não confirmado”, não prova de recusa. Telemetria pendente não deve apagar respostas.
+Leia [a ativação Codex](references/codex-activation.md) antes de instalar ou atualizar.
+Preserve a distinção entre confiança, aprovação dos hooks e agentes carregados.
+Valide com eventos reais; não autoaprove hooks nem peça aprovação já concedida.
 
 ## Resposta final obrigatória após instalação
 
 Este contrato vale para a **resposta final do assistente no chat**, além do output da CLI. Aplique-o mesmo quando o usuário pediu apenas o comando npx, a instalação começou sem skills disponíveis ou esta skill só foi descoberta depois do init. Releia esta seção antes de responder. A existência de project.yaml recém-instalado não deve desviar a resposta para uma configuração automática.
 
-Reproduza a estrutura abaixo como Markdown renderizado: frase inicial, linha “Resumo:”, lista de bullets e uma pergunta final. Não use bloco de código para envolver a resposta, não converta a lista em parágrafos e não substitua o link por negrito, texto simples ou código. Use o comando realmente executado ou sua forma npx equivalente; nunca copie a versão ou as contagens do exemplo do usuário.
+Reproduza a estrutura abaixo como Markdown renderizado: frase inicial, linha “Resumo:” e lista de bullets. Não use bloco de código para envolver a resposta, não converta a lista em parágrafos e não substitua o link por negrito, texto simples ou código. Use o comando realmente executado ou sua forma npx equivalente; nunca copie a versão ou as contagens do exemplo. Pergunte somente quando uma escolha indispensável ainda não estiver resolvida pelo pedido, configuração existente ou default autorizado.
+
+Para instalar especificamente a versão 7.5.0, o destino npm previsto é `npx @david.alpa/cli@7.5.0 init`. Confira primeiro que essa versão está publicada. No resumo de uma instalação dessa versão, use o comando efetivamente executado e o link `https://www.npmjs.com/package/@david.alpa/cli/v/7.5.0`. As demais versões usam o escopo padrão.
 
 Modelo (substitua todos os campos por resultados observados):
 
@@ -87,22 +99,17 @@ Resumo:
 - Dashboard SQLite configurado
 - `doctor --json`: válido, sem problemas
 - {ESTADO_OBSERVADO_DO_GIT_GITHUB}
-
-Deseja ajuda para configurar seu repositório Git?
+- {CONFIANÇA_DO_PROJETO_APROVAÇÃO_HOOKS_E_AGENTES_CARREGADOS_SEPARADAMENTE}
 ```
 
 - Substitua VERSÃO pela versão instalada, sem prefixo v no URL. Obtenha números e resultados da execução; dado ausente deve aparecer como “não informado”. Não declare sucesso de SQLite/doctor quando não executados ou falhos. Dry-run e instalação falha não usam a frase de sucesso.
 - Se não houver repositório, use “O diretório ainda não possui um repositório Git configurado.” Outros estados devem descrever a pendência real. Git, identidade, repositório, commit inicial e GitHub não são pré-requisitos de instalação; informe que podem ser configurados depois. Estado local não comprova autenticação.
-- Com GitHub pendente ou inconclusivo, termine com **Deseja ajuda para configurar seu repositório Git?** Com GitHub configurado localmente, substitua apenas a pergunta por **Deseja ajuda para realizar a configuração inicial do ZAIP-AIOS?**
-- Termine com exatamente uma pergunta: aprovação dos hooks enquanto não verificada, ou a pergunta Git/configuração correspondente quando a integração estiver validada. Não escreva nada depois dela nem ofereça alternativas juntas. Antes de enviar, confirme: bullets presentes; versão clicável no npm correto; pergunta correspondente ao estado e última linha da resposta.
+- GitHub pendente ou integração host não confirmada é estado observado, não autorização para ampliar a instalação nem razão para CTA obrigatório. Se setup/configuração estiverem autorizados no mesmo pedido, prossiga com as skills pertinentes e os defaults aprovados; caso contrário, relate a pendência sem oferta automática.
+- Antes de enviar, confira bullets, link npm e resultados observados. Sem escolha humana indispensável, encerre o resumo sem pergunta. Uma pergunta necessária deve identificar a informação ausente e a etapa que dela depende; continue o trabalho independente disponível.
 
 ## Aceite e encerramento do onboarding
 
-O CTA da CLI é texto, sem bloquear aguardando entrada. No chat, “sim” à pergunta de Git ativa `$zaip-skill-github-setup`; “sim” à configuração inicial ativa `$zaip-skill-config`. A skill explica opções e faz perguntas curtas antes de aplicar escolhas; o aceite não autoriza valores presumidos, credenciais, recursos externos ou publicação.
-
-Depois de configurar e verificar GitHub, ofereça a configuração inicial com **Deseja ajuda para realizar a configuração inicial do ZAIP-AIOS?** Depois de concluir a configuração inicial, encerre o onboarding. Recusa ou adiamento encerra a oferta sem insistência; uma solicitação posterior pode retomá-la.
-
-Esta skill não executa nem descreve upgrade, migração ou rollback como ações primárias. Esses fluxos somente podem ser encaminhados às skills `zaip-update` ou `zaip-rollback` quando estiverem disponíveis e forem aplicáveis; elas não são uma dependência portátil desta skill.
+Pedido de configuração GitHub encaminha a `$zaip-skill-github-setup`; pedido de configuração ZAIP encaminha a `$zaip-skill-config`. Reutilize escolhas existentes e defaults humanos aprovados sem perguntar de novo. Esses pedidos não autorizam credenciais expostas, provisionamento fora do escopo ou publicação não pedida. Recusa ou adiamento encerra o onboarding sem insistência. Atualização usa o fluxo portátil acima; rollback requer escolha explícita de versão e skill disponível aplicável.
 
 ## Perfis Codex ZAIP-AIOS
 

package/templates/.agents/skills/zaip-skill-setup/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "ZAIP Setup"
   short_description: "Install or update ZAIP-AIOS and report the result."
-  default_prompt: "Use $zaip-skill-setup to install ZAIP-AIOS or format the final reply after init with Markdown bullets, the installed-version npm link and the final setup question."
+  default_prompt: "Use $zaip-skill-setup to install ZAIP-AIOS with Codex by default, enable Claude only when explicitly requested, and report the result with Markdown bullets and the installed-version npm link. Ask only about an indispensable unresolved choice."