sinapse-ai 1.23.0 → 1.25.0

package/.sinapse-ai/product/templates/statusline/track-agent.cjs

@@ -16,6 +16,12 @@
  *   - /squad:cmd         -> sets squad (when not :agents:)
  *   - *exit / *reset     -> clears agent/squad/role/specialists + imperator.active
  *
+ * Badge injection (selo):
+ *   - Primary voice has a 6h freshness TTL (voiceTs) — no more ghost voices
+ *     leaking across sessions.
+ *   - With the Imperator active, the block also ships the handoff CAST (core
+ *     agents + squad orchestrators) so auto-routed voices can stamp their seal.
+ *
  * Writes the per-CWD cache to:
  *   ~/.claude/session-cache/{simpleHash(cwd)}.json   (Session-Cache v2 shape)
  *
@@ -68,6 +74,7 @@ function normalizeCache(raw) {
     role: null,
     imperator: { active: false, ts: 0 },
     specialists: [],
+    voiceTs: 0,
     updated: '',
   };
   if (!raw || typeof raw !== 'object') return base;
@@ -75,6 +82,17 @@ function normalizeCache(raw) {
   base.agent = typeof raw.agent === 'string' ? raw.agent : '';
   base.squad = typeof raw.squad === 'string' ? raw.squad : '';
   base.role = typeof raw.role === 'string' ? raw.role : null;
+  base.voiceTs = Number.isFinite(raw.voiceTs) && raw.voiceTs > 0 ? raw.voiceTs : 0;
+  base.updated = typeof raw.updated === 'string' ? raw.updated : '';
+  // One-time migration for legacy caches (written before voiceTs existed):
+  // freeze the voice-freshness point at the cache's ORIGINAL last-activity
+  // time. This runs at READ time, before any writer refreshes `updated`, and
+  // the migrated value persists on the next write — so `updated` refreshes
+  // (Stop hook, delegation tracker, /squad:cmd) can never resurrect a ghost.
+  if (!base.voiceTs && base.updated) {
+    const parsed = Date.parse(base.updated);
+    if (Number.isFinite(parsed)) base.voiceTs = Math.floor(parsed / 1000);
+  }
 
   if (raw.imperator && typeof raw.imperator === 'object') {
     base.imperator = {
@@ -102,6 +120,9 @@ function applyName(cache, name, ts) {
   if (!name) return;
   const lower = name.toLowerCase();
 
+  // Any explicit mention renews the primary-voice freshness window (TTL below).
+  cache.voiceTs = ts;
+
   if (MASTERS.has(lower)) {
     // Master -> imperator. Does NOT enter specialists.
     cache.imperator = { active: true, ts };
@@ -142,18 +163,42 @@ function applyName(cache, name, ts) {
 // Load ~/.claude/agent-badges.json and index by last path segment. Keys are
 // either bare ids ("developer") or "squad/id" ("squad-brand/brand-orqx"); the
 // session-cache only ever stores the bare id, so we index on the last segment.
+// Also derives the handoff CAST (core agents + squad orchestrators) so the
+// model can stamp the seal of any agent it routes to — auto-routing means the
+// user never types those @ids, so the roster can't come from the prompt.
+// A few badge entries carry double-escaped emoji ("\\U0001F9E0" as literal
+// text). Decode them for display; garbage never reaches the user's selo.
+function fixEmoji(e) {
+  if (typeof e !== 'string' || !e) return '◆';
+  if (!e.includes('\\u') && !e.includes('\\U')) return e;
+  try {
+    const decoded = e
+      .replace(/\\U([0-9A-Fa-f]{8})/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+      .replace(/\\u([0-9A-Fa-f]{4})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+    return decoded || '◆';
+  } catch {
+    return '◆';
+  }
+}
+
 function loadBadges() {
   try {
     const p = path.join(os.homedir(), '.claude', 'agent-badges.json');
     const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
     if (!raw || typeof raw !== 'object') return null;
     const byId = {};
+    const core = [];
+    const orqx = [];
     for (const key of Object.keys(raw)) {
       const v = raw[key];
       if (!v || typeof v !== 'object' || !v.emoji || !v.name) continue;
-      byId[key.split('/').pop()] = v;
+      const id = key.split('/').pop();
+      const b = { emoji: fixEmoji(v.emoji), area: v.area, name: v.name };
+      byId[id] = b;
+      if (!key.includes('/')) core.push({ id, b });
+      else if (id.endsWith('-orqx')) orqx.push({ id, b });
     }
-    return Object.keys(byId).length ? byId : null;
+    return Object.keys(byId).length ? { byId, core, orqx } : null;
   } catch {
     return null;
   }
@@ -178,20 +223,35 @@ function resolvePrimary(cache, byId) {
   return null;
 }
 
+// Freshness of the primary voice: an explicit mention within BADGE_TTL keeps
+// the voice alive; older than that → the voice expired. Kills ghost voices
+// that used to leak across sessions (the primary voice had no TTL at all).
+// voiceTs is the SINGLE source here — legacy caches are migrated at read time
+// by normalizeCache (frozen at their original `updated`), so a `updated`
+// refresh by any writer can never resurrect an expired voice.
+function voiceIsFresh(cache, now) {
+  const ts = Number.isFinite(cache.voiceTs) && cache.voiceTs > 0 ? cache.voiceTs : 0;
+  return ts > 0 && now - ts < BADGE_TTL;
+}
+
 // Build the additionalContext string, or null when no SINAPSE voice is active.
 function buildBadgeContext(cache) {
-  const byId = loadBadges();
-  if (!byId) return null;
+  const badges = loadBadges();
+  if (!badges) return null;
+  const byId = badges.byId;
 
   const now = nowSec();
-  const primary = resolvePrimary(cache, byId);
+  const primary = voiceIsFresh(cache, now) ? resolvePrimary(cache, byId) : null;
 
   // The specialist roster is only meaningful while the Imperator is coordinating
   // a multi-agent orchestration; a plain specialist↔specialist switch shows just
-  // the active voice (no roster noise).
+  // the active voice (no roster noise). `imperator.active` is turn-scoped (the
+  // Stop hook lowers it), so cross-turn orchestration is detected by the ROLE,
+  // which survives turns and expires with the voice TTL.
   const imperatorActive =
     cache.imperator && cache.imperator.active && now - (cache.imperator.ts || 0) < BADGE_TTL;
-  const specs = imperatorActive
+  const imperatorLeading = imperatorActive || (cache.role === 'imperator' && !!primary);
+  const specs = imperatorLeading
     ? (cache.specialists || [])
         .filter((s) => s && s.id && s.id !== cache.agent && now - (s.ts || 0) < BADGE_TTL)
         .map((s) => byId[s.id])
@@ -211,6 +271,32 @@ function buildBadgeContext(cache) {
     lines.push('Especialistas em jogo nesta orquestração:');
     for (const b of specs) lines.push(`  • ${fullBadge(b)}   (curto: ${shortBadge(b)})`);
   }
+  // With the Imperator coordinating, ship the handoff cast (core + squad
+  // orchestrators) so every voice the plan routes to can enter with its own
+  // seal — auto-routing means these ids never appear in the user's prompt.
+  if (imperatorLeading && (badges.core.length || badges.orqx.length)) {
+    const cast = badges.core.filter((e) => e.id !== IMPERATOR_KEY).concat(badges.orqx);
+    const castLines = cast.map(
+      (e) => `  ${e.id} → ${e.b.emoji} · ${e.b.area || '—'} · ${e.b.name}`
+    );
+    // Hard budget: the whole <sinapse-selo> block stays ≤ 2500 chars even as
+    // squads grow. RESERVE covers the protocol tail pushed after this section.
+    const RESERVE = 900;
+    let room = 2500 - RESERVE - lines.join('\n').length;
+    const kept = [];
+    for (const l of castLines) {
+      if (room - (l.length + 1) < 0) break;
+      kept.push(l);
+      room -= l.length + 1;
+    }
+    lines.push('');
+    lines.push('Elenco pra handoffs — cada voz entra com o selo `▌ {emoji} · SNPS · {área} · {nome}`:');
+    lines.push(...kept);
+    if (kept.length < castLines.length) {
+      lines.push(`  … +${castLines.length - kept.length} no arquivo abaixo`);
+    }
+    lines.push('  (especialista de squad fora do elenco: chave "squad/id" em ~/.claude/agent-badges.json)');
+  }
   lines.push('');
   lines.push('Protocolo (NON-NEGOTIABLE):');
   lines.push('1. Abra a resposta com o selo do agente que está falando — 1ª linha, SÓ na troca de voz. Mesma voz em blocos seguidos não repete o selo.');
@@ -278,6 +364,7 @@ function main() {
     cache.role = null;
     cache.specialists = [];
     cache.imperator = { active: false, ts: cache.imperator.ts || 0 };
+    cache.voiceTs = 0;
     changed = true;
   } else {
     // /ns:agents:name  (e.g. /SINAPSE:agents:developer) -> classify as @name.

package/.sinapse-ai/product/templates/statusline/track-delegation.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * SINAPSE Delegation Tracker — Session-Cache v2
+ *
+ * Called via Claude Code PreToolUse hook with matcher "Task".
+ *
+ * Auto-routing means the user never types specialist @ids — so the prompt
+ * detector (track-agent.cjs) can't see programmatic delegations. This hook
+ * closes that gap: every real delegation (Task tool spawn) registers its
+ * `subagent_type` in the per-CWD session-cache `specialists[]`, so the next
+ * turn's badge injection lists the voices actually in play and the statusline
+ * can show the orchestration cast.
+ *
+ * Rules:
+ *   - Only ids that resolve to a badge in ~/.claude/agent-badges.json enter
+ *     the cache (harness-generic types like "general-purpose" are ignored).
+ *   - Never mutates the primary voice (agent/role) — delegation does not
+ *     change who is speaking; the orchestrator remains the voice.
+ *   - Cap of 6 specialists (oldest evicted), mirroring track-agent.cjs.
+ *
+ * OBSERVER ONLY / FAIL-OPEN: always exits 0 — a tracking hook must NEVER
+ * block a Task call, on any error whatsoever.
+ *
+ * Installed automatically by `npx sinapse-ai install`.
+ * Source: .sinapse-ai/product/templates/statusline/
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SPECIALIST_CAP = 6;
+// Masters are never a delegated "specialist in play" — they ARE the primary
+// voice. Squad orchestrators delegated as subagents DO enter the cast.
+const MASTERS = new Set(['sinapse', 'snps', 'sinapse-orqx', 'snps-orqx']);
+
+// Identical to track-agent.cjs and statusline-script.js.
+function simpleHash(str) {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    h = ((h << 5) - h) + str.charCodeAt(i);
+    h |= 0;
+  }
+  return Math.abs(h).toString(16);
+}
+
+function nowSec() {
+  return Math.floor(Date.now() / 1000);
+}
+
+// Badge ids indexed by last path segment (same contract as track-agent.cjs).
+function loadBadgeIds() {
+  try {
+    const p = path.join(os.homedir(), '.claude', 'agent-badges.json');
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    const ids = new Set();
+    for (const key of Object.keys(raw)) {
+      const v = raw[key];
+      if (!v || typeof v !== 'object' || !v.emoji || !v.name) continue;
+      ids.add(key.split('/').pop().toLowerCase());
+    }
+    return ids.size ? ids : null;
+  } catch {
+    return null;
+  }
+}
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch {
+    process.exit(0);
+  }
+
+  if (!input || input.tool_name !== 'Task') process.exit(0);
+
+  const subagent = ((input.tool_input || {}).subagent_type || '').toLowerCase().trim();
+  if (!subagent || MASTERS.has(subagent)) process.exit(0);
+
+  // Only SINAPSE agents (present in the badge map) enter the cast.
+  const badgeIds = loadBadgeIds();
+  if (!badgeIds || !badgeIds.has(subagent)) process.exit(0);
+
+  const cacheDir = path.join(os.homedir(), '.claude', 'session-cache');
+  const cacheFile = path.join(cacheDir, `${simpleHash(process.cwd())}.json`);
+
+  let cache;
+  try {
+    cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+  } catch {
+    cache = null;
+  }
+  if (!cache || typeof cache !== 'object') {
+    cache = {
+      version: 2,
+      agent: '',
+      squad: '',
+      role: null,
+      imperator: { active: false, ts: 0 },
+      specialists: [],
+      voiceTs: 0,
+      updated: '',
+    };
+  }
+  if (!Array.isArray(cache.specialists)) cache.specialists = [];
+
+  const ts = nowSec();
+  const existing = cache.specialists.find(
+    (s) => s && typeof s.id === 'string' && s.id.toLowerCase() === subagent
+  );
+  if (existing) {
+    existing.ts = ts; // renew freshness, no duplicate
+  } else {
+    cache.specialists.push({ id: subagent, label: subagent, icon: '🤖', ts });
+    if (cache.specialists.length > SPECIALIST_CAP) {
+      let minIdx = 0;
+      for (let i = 1; i < cache.specialists.length; i++) {
+        if (cache.specialists[i].ts < cache.specialists[minIdx].ts) minIdx = i;
+      }
+      cache.specialists.splice(minIdx, 1);
+    }
+  }
+
+  cache.version = 2;
+  // Freeze the voice-freshness point BEFORE refreshing `updated` — a legacy
+  // cache (pre-voiceTs) must not have its ghost voice resurrected by this
+  // write (same migration as track-agent.cjs/track-agent-clear.cjs).
+  if (!(Number.isFinite(cache.voiceTs) && cache.voiceTs > 0)) {
+    let frozen = 0;
+    if (typeof cache.updated === 'string' && cache.updated) {
+      const parsed = Date.parse(cache.updated);
+      if (Number.isFinite(parsed)) frozen = Math.floor(parsed / 1000);
+    }
+    cache.voiceTs = frozen;
+  }
+  cache.updated = new Date().toISOString();
+
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // Atomic (tmp+rename): concurrent readers (statusline, track-agent) must
+    // never see a torn file. Parallel Task spawns remain last-write-wins —
+    // acceptable for an observer-only cast (worst case: one specialist waits
+    // for its next delegation to appear).
+    const tmp = `${cacheFile}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(cache));
+    fs.renameSync(tmp, cacheFile);
+  } catch {
+    /* best-effort */
+  }
+
+  process.exit(0);
+}
+
+try {
+  main();
+} catch {
+  process.exit(0);
+}

package/AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md
 
 > SINAPSE AI -- AI-Orchestrated System for Full Stack Development
-> 17 squads · 172 agents (all `@`-resolvable in Codex) · 1,411 task files, 1,347 resolvable via the parametric activator
+> 17 squads · 172 native Codex agents · 1,412 task files, 1,348 resolvable via the parametric activator
 >
 > Codex resolves every agent and its real tasks at runtime from source (no frozen
 > snapshot): `node .codex/scripts/resolve-codex-agent.js <agent> [command]`.
@@ -30,6 +30,7 @@ SINAPSE is a meta-framework that orchestrates AI agents into specialized squads
 - **CLI First** -- All intelligence lives in the CLI. Dashboards observe, never control.
 - **4-Layer Boundary** -- L1 (core, immutable) / L2 (templates, extend-only) / L3 (config, mutable) / L4 (runtime, always modify).
 - **Documentation-First Development** -- No code without a validated story. Pipeline: Epic -> Story -> Validation -> Implementation.
+- **Engineering Applicability** -- Classify greenfield/brownfield, surfaces and risk before selecting workflows. Follow `docs/framework/software-engineering-applicability.md`; legacy `optional` QA flags do not waive the mandatory baseline.
 - **Constitution** -- 11 articles with automatic gates that block violations (full text: `.sinapse-ai/constitution.md`):
   - **I. CLI First** -- intelligence in the CLI; dashboards observe, never control.
   - **II. Agent Authority** -- exclusive authorities (only @devops pushes/PRs/releases); no agent assumes another's role.
@@ -58,7 +59,7 @@ tests/                    # Test suites
 
 The core SDC agents below are documented in full. They are NOT the whole roster:
 **every one of the 172 agents** (12 core + 160 specialists/orchestrators distributed
-across 17 squads) resolves by `@name` and so do their real tasks. Resolution is parametric —
+across 17 squads) resolves through `$sinapse-agent <id>` and the native Codex agent catalog, as do their real tasks. Resolution is parametric —
 read from the source agent definitions at runtime, never from a frozen list:
 
 ```bash
@@ -67,8 +68,8 @@ node .codex/scripts/resolve-codex-agent.js <agent> <command>  # resolve a specif
 node .codex/scripts/resolve-codex-agent.js --stats            # ecosystem counts (measured from disk)
 ```
 
-Examples that resolve (no "Unknown Codex agent"): `@brand-orqx`, `@meta-ads-specialist`,
-`@cyber-orqx`, `@headline-specialist`, `@simon-sinek`, `@developer`. Squad specialists
+Examples that resolve: `$sinapse-agent brand-orqx`, `$sinapse-agent meta-ads-specialist`,
+`$sinapse-agent cyber-orqx`, `$sinapse-agent headline-specialist`, `$sinapse-agent simon-sinek`, and `$sinapse-agent developer`. Squad specialists
 inherit their squad's task pool; orchestrators (`*-orqx`) govern their whole squad.
 Every task pointer the activator emits is verified to exist on disk before it is returned.
 

package/CHANGELOG.md

@@ -1,8 +1,22 @@
-## [1.23.0](https://github.com/caioimori/sinapse-ai/compare/1.22.0...1.23.0) (2026-07-08)
+## [1.25.0](https://github.com/caioimori/sinapse-ai/compare/1.24.0...1.25.0) (2026-07-15)
 
 ### Features
 
-* **gate:** cobertura doc-first por extensao em qualquer pasta — marco de release [Story mesa2-docfirst-gate-coverage] ([#371](https://github.com/caioimori/sinapse-ai/issues/371)) ([a77b4e1](https://github.com/caioimori/sinapse-ai/commit/a77b4e1b3d4ba250e488d229071e341e3f763bfc)), closes [#370](https://github.com/caioimori/sinapse-ai/issues/370)
+* **cli:** ship native Claude and Codex parity [Story cross-provider-cli-quality] ([191a525](https://github.com/caioimori/sinapse-ai/commit/191a525027178cd46aaf7aa24a0dd445a60634cb))
+
+### Bug Fixes
+
+* **badges:** decodifica emoji double-escaped no gerador + regenera selos pos-renames [Story badges-emoji-decode] ([#375](https://github.com/caioimori/sinapse-ai/issues/375)) ([39a97f9](https://github.com/caioimori/sinapse-ai/commit/39a97f9cc992d36f50ac8b544b2dd7f07a4bf2fd)), closes [#332](https://github.com/caioimori/sinapse-ai/issues/332)
+* **ci:** use supported macOS Intel runner [Story cross-provider-cli-quality] ([1d1ca4f](https://github.com/caioimori/sinapse-ai/commit/1d1ca4f61adf9cb9425f25ba5683bf32bea03eaf))
+* **docs:** sync canonical task metrics [Story cross-provider-cli-quality] ([a6031de](https://github.com/caioimori/sinapse-ai/commit/a6031deb0e98e9897af8ae302962b36e08dc8883))
+* **release:** harden cross-provider package gates [Story cross-provider-cli-quality] ([57dff2d](https://github.com/caioimori/sinapse-ai/commit/57dff2d166e1011c14a359140a00a974526e3976))
+
+### Maintenance
+
+* **manifest:** sync registry package hash [Story cross-provider-cli-quality] ([357905f](https://github.com/caioimori/sinapse-ai/commit/357905f21cb6a34e266e25e6eb81c7545245bf20))
+* **registry:** sync provider adapter checksum [Story cross-provider-cli-quality] ([ef65ce8](https://github.com/caioimori/sinapse-ai/commit/ef65ce881354ae95f09512c1ffe5d49e4134eb92))
+* **release:** sync da main pos-release 1.24.0 ([#374](https://github.com/caioimori/sinapse-ai/issues/374)) ([d1fee0a](https://github.com/caioimori/sinapse-ai/commit/d1fee0a36e780ddc1eb4abc33af1649810bc0c97))
+* **repo:** remove landing estatica da vitrine [Story cleanup-landing-coderabbit] ([5391bfa](https://github.com/caioimori/sinapse-ai/commit/5391bfa6e69f5cb289b4eabcc1ea0822852a5462))
 
 # Changelog
 
@@ -13,6 +27,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.24.0] — 2026-07-09 — 🎭 Handoffs visíveis: selo de cada agente na orquestração
+
+> Minor. Atualização segura via `npx sinapse-ai update`. Fecha as 4 causas dos handoffs invisíveis ("nunca vejo o nome dos outros agentes"): a identidade pública dos especialistas agora chega ao modelo e aparece na conversa.
+
+### Features
+
+- **selo:** elenco de selos (core + orquestradores de squad) injetado quando o Imperator lidera, com teto auto-aplicado ≤2500 chars e emoji double-escaped decodificado; TTL de 6h na voz primária mata a voz fantasma entre sessões, com migração de caches legados congelada anti-ressurreição (validada por verificação adversarial + teste de regressão) (#373)
+- **selo:** hook novo `track-delegation.cjs` (PreToolUse[Task]) rastreia delegações reais no session-cache — só ids com badge, masters excluídos, observer-only fail-open, escrita atômica; o Stop hook passa a preservar o elenco entre turnos (#373)
+- **installer:** setup do statusline copia/registra o hook novo com guarda de preservação — settings legado não-array nunca é sobrescrito (3 eventos) (#373)
+
+### Documentation
+
+- **rules:** selo vira o canal único de identidade de agente — fim do "Delegando para @id" e do "sem nomes de agentes" (token-economy §7, mandatory-delegation, squad-awareness); seção NON-NEGOTIABLE de selo em handoffs no orquestrador mestre + timing plano→"pode ir" reconciliado (#373)
+
+## [1.23.0] — 2026-07-08 — 🛡️ Gates doc-first cobrem código em qualquer pasta
+
+> Minor. Atualização segura via `npx sinapse-ai update`. Fecha a brecha de cobertura dos gates doc-first: a detecção deixa de depender de uma allowlist de 8 pastas e passa a valer por extensão de código em qualquer lugar do projeto.
+
+### Features
+
+- **gate:** amplia cobertura dos gates doc-first pra código em qualquer pasta — detecção por (pasta de código expandida OU extensão de código), isentando config-by-pattern (`*.config.*`, `*.d.ts`, `.*rc`) e build outputs (`.next/`, `dist/`, `coverage/`, `.vercel/`); exceção `isFrameworkRepo` no story gate (Art. III); +25 testes, fail-open preservado (#370, #371)
+
 ## [1.22.0] — 2026-07-07 — 🎛️ Mesa AF-20260704: guards doc-first + economia de contexto + calibração do juiz
 
 > Minor. Atualização segura via `npx sinapse-ai update`. Executa integralmente a Mesa da rodada 2 (épicos `epic-rodada2-mesa` + `epic-rodada2-mesa-fase2`, PRs #357–#368) — dos guards de qualidade ao contexto enxuto, tudo com verificação adversarial.

package/README.en.md

@@ -263,7 +263,7 @@ Each squad is an autonomous team with its own orchestrator, specialist agents, k
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 specialized agents, 1,200 tasks**
+**Total: 17 squads, 172 specialized agents, 1,201 tasks**
 
 Activate any squad via its orchestrator:
 

package/README.md

@@ -23,7 +23,7 @@
 
 SINAPSE é um meta-framework open source que organiza **172 agentes de IA em 17 squads especializados**, operando direto no terminal via Claude Code ou Codex CLI. Cada agente tem um papel definido, cada squad domina uma disciplina, e o sistema inteiro é governado por uma **Constitution com enforcement real** — 20 hooks registrados que bloqueiam violações em tempo de execução.
 
-O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks — totalizando **1.200 tasks executáveis** prontas para uso, distribuídas pelos 17 squads.
+O conceito central é simples: em vez de um único assistente de IA tentando fazer tudo, o SINAPSE estrutura o trabalho em equipes especializadas. Um squad de branding cuida da identidade visual. Um squad de cybersecurity cuida de compliance e pentest. Um squad de copywriting cuida de persuasão e conversão. Cada um com sua própria knowledge base, workflows e tasks — totalizando **1.201 tasks executáveis** prontas para uso, distribuídas pelos 17 squads.
 
 Diferente de ferramentas que apenas conversam com IA, o SINAPSE impõe disciplina. O pipeline **Documentation-First** exige que uma story seja criada e validada antes de qualquer linha de código. Quality gates rodam automaticamente antes de merge. Agentes não autorizados são bloqueados de fazer push. Tudo isso via hooks que interceptam operações em tempo real — não depois.
 
@@ -41,10 +41,13 @@ O diferencial não é apenas a quantidade de agentes. É **governança real**: 2
 
 ## Quick Start
 
+> Use `@latest` nos comandos publicos para evitar que o cache do `npx` execute
+> uma versao anterior durante instalacoes e atualizacoes.
+
 ### 1. Instale
 
 ```bash
-npx sinapse-ai install
+npx sinapse-ai@latest install
 ```
 
 O wizard detecta seu ambiente, escolhe a IDE (Claude Code ou Codex) e instala os 17 squads automaticamente. Re-rodar o comando faz upsert idempotente — preserva suas customizações e só atualiza o que mudou.
@@ -52,8 +55,8 @@ O wizard detecta seu ambiente, escolhe a IDE (Claude Code ou Codex) e instala os
 ### 2. Verifique
 
 ```bash
-npx sinapse-ai status   # Lista de squads + agentes instalados
-npx sinapse-ai doctor   # 16 health checks contra o ambiente
+npx sinapse-ai@latest status   # Lista de squads + agentes instalados
+npx sinapse-ai@latest doctor   # 16 health checks contra o ambiente
 ```
 
 Se algo estiver fora do lugar, `doctor --fix` corrige automaticamente.
@@ -120,7 +123,7 @@ Cada release passa por uma matriz de instalação de 27 combinações (3 OSes ×
 ### "Como atualizar sem perder minhas customizações?"
 
 ```bash
-npx sinapse-ai update
+npx sinapse-ai@latest update
 ```
 
 O update é **idempotente por design**. L1 (framework core) e L2 (templates) são atualizados. L3 (configuração) e L4 (suas stories, packages, customizações) **nunca são tocados**. Você pode rodar `update` quantas vezes quiser, inclusive após customizar rules localmente. Nada se perde.
@@ -282,7 +285,7 @@ Cada squad é uma equipe autônoma com orquestrador, agentes especialistas, know
 | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
 | **squad-finance** | Budget, pricing, profitability analysis | 8 |
 
-**Total: 17 squads, 172 agentes especializados, 1.200 tasks**
+**Total: 17 squads, 172 agentes especializados, 1.201 tasks**
 
 Cada squad é ativado via seu orquestrador:
 
@@ -303,8 +306,8 @@ O SINAPSE suporta duas IDEs com integrações profundas:
 
 | IDE | Ativação | Destaques |
 |-----|----------|-----------|
-| **Claude Code** | `@agent-name` | Hooks, rules contextuais, deny/allow, Chrome Brain |
-| **Codex CLI** | `/skills` ou `$skill-name` | Skills nativas, multi-model, `codex exec` para CI/CD |
+| **Claude Code** | `@agent-name` ou `/skill-name` | Subagentes e skills nativos, hooks e rules contextuais |
+| **Codex CLI** | `$snps` ou `$sinapse-agent agent-id` | Agentes TOML, skills nativas e `codex exec` para CI/CD |
 
 Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowledge bases. O installer detecta e configura automaticamente.
 
@@ -312,7 +315,7 @@ Ambas as IDEs têm acesso a todos os 17 squads, 172 agentes, workflows e knowled
 
 | Funcionalidade | Claude Code | Codex CLI |
 |---------------|:-----------:|:---------:|
-| Ativação de agentes (@agent) | Completo | Completo |
+| Ativação dos 172 agentes | `@agent-name` | `$sinapse-agent agent-id` |
 | Hooks constitucionais (20) | Completo | Parcial (5) |
 | Story-driven development | Completo | Completo |
 | Quality gates | Completo | Completo |
@@ -401,6 +404,18 @@ Pre-commit e pre-push hooks validam automaticamente antes de cada operação.
 
 ## CLI Reference
 
+Comandos deterministas para o pacote publico:
+
+```bash
+# Projeto novo ou existente
+npx sinapse-ai@latest install
+npx sinapse-ai@latest update
+
+# Instalacao global existente
+npm install -g sinapse-ai@latest
+sinapse-ai update
+```
+
 A superfície pública é proposital — quatro comandos canônicos de lifecycle, dois diagnósticos, um sub-comando avançado.
 
 ```bash
@@ -421,7 +436,7 @@ npx sinapse-ai doctor --dry-run  # Mostra o que `--fix` faria sem aplicar
 npx sinapse-ai chrome-brain install   # Instala browser automation
 ```
 
-Todos os comandos são seguros para re-rodar. Para listar agentes ativos depois de instalar, abra o Claude Code ou o Codex CLI e digite `@` para autocompletar.
+Todos os comandos são seguros para re-rodar. No Claude Code, digite `@` para selecionar um subagente ou use `/snps`. No Codex, use `$snps` para o orquestrador supremo e `$sinapse-agent <id>` para qualquer agente do catálogo.
 
 ### Orquestração (avançado)