nativesoul 0.1.0

package/docs/adr/ADR-042-control-plane-direction-and-deferral.md

@@ -0,0 +1,80 @@
+# ADR-042: Control Plane — Direction, Deferral & Guardrails
+
+## Status
+Accepted (2026-06-27) — direction approved, **build deferred** to post-monetization
+
+## Context
+
+Avaliamos uma proposta de engenharia para integrar funcionalidades do **Mission Control** (https://github.com/builderz-labs/mission-control — dashboard MIT de orquestração de agentes: task board, agent management, cost tracking, SSE/WebSocket, RBAC, an automated AI reviewer ("Aegis"), webhooks) ao NativeSoul, criando um "NativeSoul Control Plane".
+
+Revisão pela equipe (Pax @po + Aria @architect + Quinn @qa) contra o código real. A direção macro é sã, mas o relatório original tinha imprecisões e o timing/forma exigem correção. Detalhe técnico nos vereditos de Aria/Quinn (memória de agente) e em `docs/architecture/project-overview-v1.md`.
+
+## Decision
+
+**Adotar a DIREÇÃO (camada operacional inspirada no Mission Control), mas NÃO construir agora.** Build deferido para **depois do EPIC-018 (monetização) shipar e o `npm publish` desbloquear**.
+
+Quando retomado, a forma é **corrigida** vs. a proposta original:
+
+1. **Não importar o Mission Control (app Next.js inteiro).** Manteria o anti-padrão de dependências; rejeitado.
+
+2. **Clean-room: inspirar e reimplementar, copiar ZERO código MIT.** NativeSoul é `UNLICENSED`/proprietário com EULA que proíbe redistribuição (ADR-040). Embutir código MIT criaria um *one-way trap* que enfraquece a cláusula de não-redistribuição do modelo pago. Reimplementar ideias (não expressão) não gera obrigação MIT e mantém o footprint de terceiros em **zero** — que já é ativo de marca. Decisão @legal-chief + fundador.
+
+3. **`dependencies: {}` é inegociável.** Control plane = **pacote separado, opt-in, NÃO publicado** no tarball `nativesoul` core. UI = static build (React em build-time, não runtime); server local = `node:http` + SSE (proibido `ws`/`express`). O `release:security:audit` do core não pode virar refém de CVE do ecossistema React.
+
+4. **Sequência corrigida (Opção D primeiro):**
+   ```
+   EPIC-018 (monetização — launch-blocker)
+     → EPIC-019 19.1 (project registry)
+     → [Onda 1] work_items core + DASHBOARD ESTÁTICO EXPANDIDO  ← ~80% do valor de observabilidade, custo ~zero, SEM servidor
+     → [Onda 2+] MCP work tools → control serve (só com guardrails) → Operator UI → bridge (PoC)
+   ```
+
+5. **Reusar, não reinventar:** `work_items` consome o registry de projetos do EPIC-019 (`resolveProjectIdFromCwd`) e referencia `runs` (1:N) para execução — sem ledger paralelo. `approvals` = transição de estado sobre a máquina existente (policy/proposals), não 3ª tabela inventada.
+
+6. **`control serve` só com 6 guardrails de marca/segurança** (senão, cortar e ficar no dashboard estático):
+   - **No-daemon:** foreground-only, sem fork/detach, sem auto-start em hook/install/heartbeat; teste de regressão "**no port at rest**" no release gate. (A badge "no daemon" já causou um incidente de badge falsa — ADR-040; é sagrada.)
+   - **Segurança do server local:** bind `127.0.0.1` apenas; **defesa de DNS-rebinding** (Host-header allowlist); **CSRF** (token em header custom `X-NativeSoul-Token`, nunca cookie/URL); **CORS** travado na origem exata da UI (sem `*`); token **efêmero in-memory** (`crypto.randomBytes`, nunca persistido — preserva "never copies credentials"); auth em todo endpoint incl. SSE; audit em todo WRITE.
+   - Documentar que **NÃO é** o "remote runtime" (P6) rejeitado por vaporware.
+
+## Consequences
+
+- **Sequenciamento:** monetização ship primeiro. Iniciar control plane agora seria scope creep que adia os R$10k.
+- **Product boundary after ADR-045:** there is no Free/Pro split. `work_items`, cost telemetry, and dashboard expansion are capabilities of the single paid product once licensed; the distinction here is sequencing and surface area (core data/CLI first, UI/server/future surfaces later), not commercial tiering.
+- **Gates obrigatórios antes de qualquer código:** (1) EPIC-018 shipou; (2) ADR de licença com decisão @legal-chief (recomendado: reimplementar, copiar zero); (3) isolamento de pacote/deps; (4) gate de marca "no port at rest"; (5) mitigações de segurança G2.1–G2.7.
+- **Carry-forward (futuro EPIC-020):** work_items core, dashboard expandido, MCP work tools, control serve, Operator UI, Mission Control bridge (PoC).
+- **O modelo de orquestração CENTRALIZADA do Mission Control (agentes registram + fazem polling num server central) NÃO é adotado** — contradiz o DNA local-first/native-first. NativeSoul absorve o *valor* (governança, aprovação humana, visibilidade, work tracking) com seus *próprios* mecanismos locais. Ver §"Fit" em `project-overview` / análise da equipe.
+
+## Pre-flight refinements (multi-agent review, 2026-06-27)
+
+> Review @po+@architect+@qa+@data+@ux dos epics Ready. **Não bloqueiam** o início de 18.x ou 19.1. Aplicar quando o epic dono for pego pelo @dev.
+>
+> **Rodada 1 aplicada (2026-06-27):** R1 (custo honesto em 22.1 — never implicit 0), R4 (contador reconciliado: EPIC-018 Ready, 28 Ready), R5/T6 (22.1 não cita "EPIC-023 cost tables" — não existem), R6 (marker committable).
+>
+> **Rodada 2 aplicada (2026-06-27):** 22.2 AC4 (honestidade alinhada — coverage/not-reported, nunca $0; + copy "approve via CLI" na AC3) · 20.1 idempotency key inclui `project`+`host` (T4) · 19.1 AC6 persiste `first_basis` (T5) · 23.2 `CostReport`/`RunCost` types em `packages/domain` compartilhados com 22.1/23.3 (T6) · 19.5 AC4 expõe `project reactivate <id>` CLI (B4) · 21.3 AC4 "claimed by host X" + `claim` salta para `in_progress` (UX) · EPIC-023 nota de cobertura honest-empty MVP (B1).
+>
+> **Rodada 3 aplicada (2026-06-27 — "todos os refinamentos"):** T2/B3 convenção work↔run documentada (`metadata_json.run_id` em 21.2 Dev Notes + `work update --run` em 21.3 + dashboard "when present") · QA1 19.4 edge cases adicionados (CRLF, tabs, alias-collision) · B5 nota help-center (continuity-gap + `project merge` indisponível) na EPIC-019.
+>
+> **Já cobertos nas specs (confirmado, sem edit necessário):** T3 re-check turn-based (20.3 AC6 + Dev Notes já especificam `getApproval`/`life_status` no próximo turno) · QA1 matriz de precedência (20.4 AC7 + tasks) · QA1 transições ilegais (21.2 AC9 + tasks) · QA1 absent-table guards (22.1) · 19.3 precedência 5-fontes + folder-move (AC2/AC5). **Todos os itens do review consolidado estão agora aplicados ou cobertos.**
+
+| ID | Owner | Refinamento | Resolução recomendada |
+|----|-------|-------------|------------------------|
+| R2/T2 | 21.x ↔ 22.x | Link work↔run (1:N) não definido | Convenção `work_items.metadata_json.run_id`; cards do board leem dela. Adicionar AC em 21.2; 22.x consome |
+| R3/T3 | 20.4 | Precedência `allowed[]` vs `approval_required` | Documentar decision tree antes da impl (gate wrapper vs `evaluatePolicy` puro) |
+| T1 | 23.2 + 22.1 | Tipo de custo compartilhado | `CostReport`/`getCostReport` em `packages/domain`; 22.1 consome o shape de 23.2 (não reimplementa) |
+| T4 | 20.3 | Agente re-checar approval | AC para `life_approval_get` (ou campos em `life_status`) — agente re-lê no próximo turno |
+| T5 | 19.1+19.3 | `touchProject` no write-boundary | Único ponto no bootstrap, **nunca** no hot path de `insertMemory` (confirmar 19.1 AC7) |
+| D1 | 19.1 | `first_basis` sem AC de escrita | Adicionar AC: persistir `first_basis` no upsert |
+| D2 | 20.1 | Idempotency key sem project | Incluir `project` no match: `(action, class, target, project)` |
+| D3 | 23.2 | API abre 2ª conexão | `getCostReport({ db })` aceita handle compartilhado (22.1/23.3 reusam) |
+| UX1 | 19.2/19.4/22.2 | Micro-copy | `project show`: linha "continuity gap" (base_id vs id); rename: aviso "cosmético, não move memórias"; dashboard: nota "approve via CLI" |
+| UX2 | 21.2 | Claim UX (pula `assigned`) | Label "claimed by host X" em vez de estado intermediário |
+| QA1 | 20.4/20.3/21.2/22.1+23.2/19.4 | ACs de teste | matriz de precedência standing-order; E2E re-check MCP; transições ilegais; paridade dashboard↔CLI no mesmo fixture `{}`; config-writer CRLF/tabs/collision |
+| R6 ✅ | 19.3 | Marker `.nativesoul/project`: commitável vs gitignore | **DECIDIDO (fundador, 2026-06-27): COMMITÁVEL** — sem segredos, compartilha o id no time. Não vai pro `.gitignore` |
+
+## References
+- Proposta original (relatório de engenharia, 2026-06-27) + vereditos Aria/Quinn (memória de agente)
+- Multi-agent Ready-review (2026-06-27): @po/@architect/@data/@ux/@qa
+- [ADR-045](ADR-045-paid-only-closed-distribution.md) (paid-only closed distribution — current licensing/distribution authority)
+- [ADR-041](ADR-041-project-identity-and-lightweight-registry.md) (registry que `work_items` reusa)
+- `docs/stories/epics/EPIC-018-monetization-entitlements.md` (launch-blocker que precede isto)
+- `packages/core/src/dashboard-viewer.ts` (dashboard estático a expandir — Opção D)

package/docs/adr/ADR-043-versioning-and-release-policy.md

@@ -0,0 +1,60 @@
+# ADR-043: Versioning & Release Policy
+
+## Status
+Accepted (2026-06-27) — **amended 2026-06-30 by [ADR-045](ADR-045-paid-only-closed-distribution.md):** SemVer + perpetual-fallback + 1-year-updates + the major-version soft-nudge (18.10) **stand unchanged**. Only the *distribution* mechanics change — the package is now a **closed/minified npm release for a paid-only product**, and licensing is **Dodo-managed** (not the offline Ed25519 model referenced here). Read distribution/licensing details from ADR-045.
+
+## Context
+
+A infraestrutura de release já existe e está validada (EPIC-011 — `package:local`/`package:smoke`/`package:dry-run`, `release:security:audit`, `release:provenance:dry-run`; ADR-012 npm scope; ADR-027 local manifest+checksum). A distribuição/licenciamento vigente agora é ADR-045: produto pago único, fechado/minificado no npm, $29 one-time, 1 ano de updates, perpetual build, Dodo-managed license check. Mas **três peças de política nunca foram formalizadas**:
+
+1. **Não há estratégia de versionamento.** `package.json` está em `0.1.0` sem regra de semver, sem gatilho de `1.0.0`, sem fronteira "update grátis" × "upgrade pago".
+2. **A promessa comercial não tem mecanismo.** A EULA §1.3 e o ADR-040 vendem "1 ano de updates + upgrade na próxima major", mas o `LicensePayload` (ADR-039) **não carrega versão de produto** e o CLI não sabe distinguir uma feature Pro de uma major nova fora da janela de updates. Isso é marketing sem código — o "faking it" que a marca proíbe.
+3. **Não há `CHANGELOG`** — o comprador não consegue verificar "esta major tem a feature que paguei" (quebra o pilar "verify, don't trust").
+
+Decisões do fundador (2026-06-27): **soft-nudge** (nunca capa o que foi pago), **cobertura de updates em metadata local no `license.json`** (sem reemitir token), **canal beta via npm `@beta` dist-tag** (leve).
+
+## Decision
+
+### 1. SemVer
+NativeSoul adota **SemVer 2.0.0** (`MAJOR.MINOR.PATCH`):
+
+| Nível | Significado | Efeito comercial |
+|---|---|---|
+| **PATCH** (`0.1.0→0.1.1`) | bugfix, sem mudança de API/CLI | update grátis (dentro da janela) |
+| **MINOR** (`0.1.0→0.2.0`) | feature aditiva, retrocompatível | update grátis (dentro da janela) |
+| **MAJOR** (`0.x→1.0.0`, `1.x→2.0.0`) | breaking change na CLI/MCP/schema **e** fronteira de upgrade pago | **soft-nudge** após a janela |
+
+### 2. Fase 0.x = beta pública; gatilho de 1.0.0
+Enquanto a versão for `0.x`, o produto é pré-1.0 e sai pelo canal `@beta`. **`1.0.0` é cortado quando:** EPIC-018 (monetização) shipado, primeiro Pro estável em produção, e `npm publish` público desbloqueado (story 18.9). Pré-releases de uma major usam `1.0.0-beta.N` no canal `@beta`.
+
+### 3. Update × Upgrade (perpetual fallback)
+- O token Pro é **`exp: null`** (não expira — ADR-039). O build adquirido roda Pro **para sempre**.
+- A compra inclui **12 meses de updates** (todo MINOR/PATCH grátis nesse período).
+- Uma **nova MAJOR após a janela** dispara **soft-nudge**, nunca bloqueio (ver §4).
+
+### 4. Acoplamento versão↔licença = soft-nudge (advisory, nunca gate)
+- `requireFeature` (entitlements-design §4) **permanece inalterado**: uma licença Pro habilita todas as features Pro, em qualquer versão. **Nada do que foi pago é capado.**
+- A cobertura de updates é uma camada **advisory separada**, baseada em **metadata local** gravada no `~/.nativesoul/license.json` na ativação: `purchased_at` (= o `iat` assinado do token, ou seja, a data de compra/emissão — **não** a data de ativação, para honrar a EULA §1.3 mesmo se o comprador ativar meses depois), `version_at_activation` e `updates_until` (= `purchased_at + 365d`). O **token assinado não ganha campo de versão** — fica `exp: null`, sem churn de `kid`, sem mudança no issuer (o `iat` já existe).
+- A função advisory expõe um estado **tri-state** `updates_status: "active" | "lapsed" | "unknown"` — "unknown" é valor de primeira classe para metadata ausente/corrompida, nunca inventado.
+- **"Existe uma MAJOR mais nova" é fato externo (registry), não derivável da versão instalada.** A comparação é `major(latestKnownVersion) > major(version_at_activation)` (a major coberta pela compra, não a instalada). `latestKnownVersion` **não** é buscado automaticamente: por padrão fica `"unknown"` (zero rede, nudge suprimido); a única consulta online é o **opt-in explícito** `nativesoul license status --check-updates` (`npm view nativesoul version`). Isso preserva o invariante de marca "no telemetry / no phone-home" — só checa quando o usuário pede.
+- Quando `updates_status === "lapsed"` **e** existe uma MAJOR mais nova que a comprada, o CLI mostra um **banner dismissível** sugerindo upgrade. Não há trava, degradação ou perda de feature. (Mecanismo especificado na story 18.10.)
+- Metadata ausente/corrompida → `updates_status: "unknown"`, nudge suprimido, nada inventado (degradação graciosa, alinhada à honestidade de custo do EPIC-023).
+
+### 5. Canais de distribuição
+| Canal | Conteúdo | Comando |
+|---|---|---|
+| `@beta` | `0.x` e pré-releases `-beta.N` | `npm publish --tag beta` |
+| `@latest` | builds estáveis (≥1.0.0) | `npm dist-tag add nativesoul@<v> latest` |
+
+Critério de promoção beta→latest e runbook operacional vivem em [`docs/guides/versioning-and-releases.md`](../guides/versioning-and-releases.md). `npm publish` e `dist-tag` são **exclusivos do @devops** (agent-authority).
+
+### 6. CHANGELOG
+`CHANGELOG.md` (raiz, formato *Keep a Changelog* + SemVer) é mantido a cada release e **incluído no tarball publicado** (`package.json` `files`, ADR-012), para o comprador verificar quais features cada major entrega.
+
+## Consequences
+
+- **A promessa perpetual-fallback passa a ter mecanismo real** (advisory) + CHANGELOG verificável — fecha o honesty-risk de "marketing sem código". Alinhado a "He doesn't fake it".
+- **Zero acoplamento novo ao servidor de emissão** — cobertura mora local; o issuer (18.6) não precisa carimbar versão no token. `dependencies: {}` preservado.
+- **A copy do perpetual fallback** continua governada pelo `feature-registry.yaml` (`pricing_perpetual_fallback`, `versioning_semver`); soft-nudge não permite a claim proibida "free updates forever".
+- **Implementação:** o mecanismo de §4 é a story **18.10** (EPIC-018), obrigatória antes de comunicar publicamente o perpetual fallback. A política de canais/§5 reusa scripts já existentes (EPIC-011) — sem novo pipeline.
+- **Relação com outros ADRs:** estende ADR-012 (npm scope — adiciona `CHANGELOG.md`), ADR-027 (manifest/checksum), ADR-039 (token segue `exp: null`, sem campo de versão), ADR-040 (operacionaliza o preço perpetual fallback).

package/docs/adr/ADR-044-pro-awareness-and-upgrade-nudge-policy.md

@@ -0,0 +1,53 @@
+# ADR-044: Pro awareness & upgrade-nudge policy
+
+## Status
+**RETIRED (2026-06-30) by [ADR-045](ADR-045-paid-only-closed-distribution.md)** — the pivot to **paid-only (no free tier)** removes the free→Pro discovery problem this ADR solved: there is no free user to nudge. Stories **18.11 and 18.12 are retired** with it. Kept for history.
+
+~~Accepted (2026-06-28)~~
+
+## Context
+
+The free→Pro conversion path (EPIC-018) has a **discovery hole**. The existing entitlement gate is **reactive**: `requireFeature` / `gatedTool` only surface Pro at the moment a user *tries* a Pro feature (`dashboard`, `import`, hybrid recall, policy packs). But NativeSoul's primary UX is **inside the host** — the user talks to the agent, which calls the MCP `life_*` tools; they rarely type `nativesoul dashboard` in a terminal. A 100% host-resident user therefore **never trips the reactive gate and never learns Pro exists**.
+
+Hard brand constraints rule out the usual fixes:
+- **No telemetry / no phone-home / no background process / never copies credentials** (registry badges; ADR-040; ADR-043 §4). The installed product **cannot** know who installed it, **cannot** collect an email, **cannot** push a notification.
+- Founder decisions (2026-06-28): **no email opt-in in the CLI** (it dirties "never phones home"); email capture lives in the **sales page**, not the binary; a **single dismissible in-product discovery line** is welcome; the post-install community signal must be **zero-PII** (`nativesoul changelog`, not "star the repo" — the repo is private/source-available per ADR-040, so there is nothing public to star).
+
+So awareness must (a) ride the surface where host-resident users actually are — `life_bootstrap` and MCP results — not only the CLI; (b) be rate-limited, dismissible, and never bother a paying customer; (c) make **zero** network calls.
+
+## Decision
+
+**A local, frequency-capped, dismissible Pro-awareness layer that rides the bootstrap/MCP plane, sharing one ledger and one helper. Awareness precedes intent; the reactive gate confirms it.**
+
+### 1. One helper, one ledger
+- `proHint({ surface, home, tier })` (sibling of `proNudge` from 18.5, same copy source) returns a single short line **or `null`**, deciding purely from local state. Pure, **no network**, side-effect-free except advancing the ledger.
+- Ledger: `~/.nativesoul/nudges.json` (0600) — `{ shown: { [surface]: count }, last_shown_at, session_count, dismissed, activated_tier }`. **No PII, never sent anywhere.**
+
+### 2. Surfaces (where), in reach order for a host-resident user
+| Surface | Mechanism | Reaches host-only user? |
+|---|---|---|
+| **`life_bootstrap` `pro_hint`** | optional field in the bootstrap payload (`bootstrap.ts`), rendered by `bootstrap-injector.ts`; the agent relays it | **Yes — universal** |
+| **Onboarding complete** | one-time line at end of setup | Yes |
+| **`doctor` / `license status`** | a line when the user runs it | CLI only |
+| **`gatedTool` / `proNudge` (reactive, existing 18.5)** | when a Pro feature is attempted | Yes (via agent) |
+| ~~`life_recall` footer~~ | **out of scope (MVP)** — avoids over-instrumenting | — |
+
+### 3. Frequency & suppression (how often)
+- **`tier === pro` → ZERO.** Never upsell a paying customer (the ledger records `activated_tier`).
+- **Dismiss is permanent:** `nativesoul license --hide-tips` sets `dismissed: true` → zero forever. Respected across all surfaces.
+- **At most one hint per session**, coordinated across surfaces by the single ledger (the reactive gate is exempt — it is intent-driven, not an interruption).
+- **Backoff + cap on the bootstrap hint:** show at session **3**, then **+14 days**, then **+30 days**, **cap ~3 impressions**, then stop. Onboarding hint fires **once**. `doctor`/`status` is user-pulled (shown whenever run, still suppressed by tier/dismiss).
+- **Never auto-open a browser** or run anything — only **print** `UPGRADE_URL`. Auto-opening would read as phone-home.
+
+### 4. Honesty invariants
+- Every hint reaffirms that **free keeps working** (same rule as 18.3 §8) — never a dark pattern, never implies the free tier is crippled.
+- The hint states what Pro adds, factually, from the registry (dashboard, importers, hybrid recall, policy packs) — no invented benefit.
+- Post-install community signal = `nativesoul changelog` (local, prints the bundled `CHANGELOG.md`, zero network) + an optional "if it helped, tell a dev you trust". **No "star the repo"** (no public repo; ADR-040).
+
+## Consequences
+
+- **Closes the discovery hole** for host-resident users via the `life_bootstrap` `pro_hint` — the single most important piece.
+- **Zero new brand risk:** local ledger, no network, no PII, no auto-open; a paying customer is never nagged; dismiss is permanent. The "never phones home" claim is untouched.
+- **Implementation:** stories **18.11** (bootstrap `pro_hint` + ledger + `proHint()` helper) and **18.12** (CLI `doctor`/`license status` line + onboarding one-time + `--hide-tips` + post-install `changelog` fix). Additive to EPIC-018, `dependencies: {}`.
+- **`UPGRADE_URL`** remains the placeholder from 18.3 (`https://nativesoul.dev/pro`) — confirm the real checkout/landing URL before release.
+- **Relation:** builds on ADR-039 (gate), ADR-040 (no public repo → no star), ADR-043 §4 (the no-network/opt-in discipline mirrors the soft-nudge's `--check-updates`). Distinct from the **soft-nudge** (18.10), which targets *existing Pro buyers* about a new major; this ADR targets *free users* about Pro's existence.

package/docs/adr/ADR-045-paid-only-closed-distribution.md

@@ -0,0 +1,55 @@
+# ADR-045: Paid-only closed distribution ($29) + Dodo-managed licensing
+
+## Status
+Accepted (2026-06-30) — supersedes ADR-040 (free-to-install) and ADR-044 (pro-awareness); largely supersedes ADR-039 (offline Ed25519 licensing)
+
+## Context
+
+NativeSoul shipped as **proprietary free-to-install, source-available** (ADR-040), with a generous uncapped Free core and a thin Pro tier ($47 perpetual fallback). A monetization review concluded this is **structurally unsellable**: the Free core delivers the entire painkiller (identity, memory, continuity, honesty, follow-ups, all hosts) while Pro is 4 local conveniences — a rational developer pays **$0**. Copy/price tweaks cannot fix a give-away-the-product structure.
+
+The founder evaluated the **DevUtils model** (one-time, no free tier, $29, 30-day money-back) — same persona (offline-loving devs), and the same pricing mechanics NativeSoul already uses (one-time + 1 year of updates + perpetual build). The decision (2026-06-30, informed, overriding the advisory recommendation): **adopt the DevUtils model — single paid plan, no free tier, closed code.**
+
+This was taken **eyes-open** to real trade-offs (recorded here, not to be relitigated):
+- Removes both pre-purchase trust levers: "install free and see it work" (no free tier) **and** "read the code" (closed source). What remains is the **30-day money-back guarantee** + a demo + the privacy posture below.
+- A closed **JS/npm** tool is **convenience-grade**, not piracy-proof — minified JS is patchable. Revenue rests on **convenience + money-back + honest-majority goodwill** (Sublime Text economics), **not** on the lock.
+- Higher conversion risk given no audience, **cumulative** value (cannot be demoed instantly like DevUtils' paste-JSON→result), and an unknown brand.
+
+## Decision
+
+### 1. Commercial model
+- **Single paid plan, no free tier.** $29 one-time, **1 year of updates**, perpetual build, renew-at-discount (= DevUtils; = the existing perpetual-fallback in ADR-043).
+- **30-day money-back guarantee** replaces a free trial (risk reversal).
+
+### 2. Closed distribution — zero-cost path
+- **Private repo** (the readable source is no longer published/distributed) + **minified/obfuscated `dist/` published to npm** (esbuild bundle+minify, build-time, OSS `javascript-obfuscator` optional). Keeps `npm i -g nativesoul`.
+- **No compiled binary / no code-signing** in this phase: an npm package runs via the user's own Node, so it **does not** trip Gatekeeper/SmartScreen and needs **no signing certificate**. This avoids ~$99/yr Apple + Windows certs + a per-platform CI matrix. A signed SEA binary is a **possible future upgrade**, not now.
+- The lock is **convenience-grade** (minified-npm is weaker than a SEA binary; both are bypassable). Documented as such; **never** marketed as "uncrackable"/"piracy-proof".
+
+### 3. Licensing — Dodo Payments (native license keys)
+- **Dodo Payments** is checkout + billing + **merchant-of-record** **and** issues/manages/revokes the **license key**. As Merchant of Record, **Dodo handles VAT/GST/sales tax and refunds globally** — NativeSoul never registers for or remits tax in any jurisdiction. This **removes the custom Ed25519 issuer** (keygen, serverless signer, key rotation, webhook hardening) — a large simplification.
+- **Validation: online, throttled to once-per-day, with an offline grace window.** The product validates the key against Dodo's **public** license endpoints via **native `fetch`** (no SDK → `dependencies: {}` preserved, no secret in the product):
+  - `POST /licenses/activate {license_key, name}` → returns a `license_key_instance_id` on **first activation** (per-machine slot; respects the activation limit per key, e.g. laptop + desktop).
+  - `POST /licenses/validate {license_key}` → `{valid}`, called **at most once every 24h** (cached); on a failed check (Dodo down / offline / on a plane) it keeps working for an offline **grace window (default 14 days, configurable)** before requesting reactivation — a paying customer is **never** bricked by gateway downtime.
+  - `POST /licenses/deactivate {license_key, license_key_instance_id}` → frees the slot so the buyer can move to another machine.
+  - Activation limits use a **random per-install UUID**, not a hardware fingerprint.
+- The product holds **no secret** — only Dodo's public license endpoints. `DODO_PAYMENTS_API_KEY` / `DODO_PAYMENTS_WEBHOOK_SECRET` live only in Dodo, never in the npm package.
+- **Key delivery (RESOLVED):** Dodo delivers the license key to the buyer **automatically** — by **email** and on the **success-page URL** (`?license_key=...`) after checkout. The seller does **not** email it, and **no backend/webhook is required**. The buyer simply runs `nativesoul license activate <key>`. **No Ed25519/custom issuer.**
+
+### 4. Privacy posture — repositioned honestly
+The "**never phones home / zero network**" claim is **dropped** (the product now makes a daily license check). The honest replacement, **logged to the audit log** so a skeptic can verify exactly what leaves the machine:
+
+> **No usage telemetry. Your code and memory never leave your machine. The only network call is a once-a-day license check that sends nothing but your license key.**
+
+A license check is not usage telemetry; this remains a strong, truthful privacy claim — but it is **not** "zero network", and no doc/marketing may say so.
+
+## Consequences
+
+- **Reverses ADR-040** (free-to-install, source-available) and the earlier "do not close the source" decision — deliberate.
+- **Supersedes ADR-044 + retires stories 18.11/18.12** (free→Pro awareness nudge): with no free tier there is no one to nudge.
+- **Largely supersedes ADR-039**: licensing is Dodo-managed online (daily-check + grace), not offline Ed25519. The boot gate is `licensed | unlicensed` (no `Tier`/`FeatureId`/`PRO_FEATURES`, no "degrade to Free").
+- **EPIC-018 re-scoped**: 18.1 collapses to licensed|unlicensed; 18.2 swaps Ed25519 verify/store for Dodo-validate + 24h cache + grace + instance UUID; **18.6 issuer removed**; 18.3/18.5 become a single boot gate; 18.9 release-prep targets minified npm; 18.10 (major soft-nudge to paying users) kept.
+- **Registry/EULA/README/brief** updated: drop "free to install", "source-available", "read the source", "never phones home"; the product is "$29, closed, runs on your machine, no usage telemetry, one daily license check, 30-day money-back". Governed by `feature-registry.yaml` + the `marketing-audit` gate (18.7).
+- **Sales page must move out of the repo** (the product repo goes private; a public landing page cannot live in a private repo) — separate public repo or a hosted/no-code page.
+- **Cost:** recurring ≈ $0 (no certs, no SEA, no CI matrix; only per-sale gateway fees + an optional free-tier serverless function).
+- **Accepted risk:** the lock is bypassable; revenue depends on convenience + money-back + goodwill, not enforcement; conversion is unproven for a cumulative-value, no-audience product. This is the founder's deliberate bet.
+- **Relation to ADR-043:** perpetual-fallback + 1-year-updates + the major-version soft-nudge (18.10) are kept; only the distribution/licensing mechanics change.

package/docs/legal/EULA.md

@@ -0,0 +1,70 @@
+# NativeSoul — End User License Agreement (EULA)
+
+> **Status:** Draft v2 (2026-06-30, ADR-045 pivot) — **requer revisão @legal-chief antes de `npm publish`** (obrigatória para venda global).
+> **Natureza:** software **proprietário, pago e de código fechado** (NÃO open source, NÃO source-available, NÃO free tier). Ver [ADR-045](../adr/ADR-045-paid-only-closed-distribution.md).
+> **Jurisdição/idioma:** definir com revisão legal (provável Brasil — fundador UTC-3 — com termos em PT/EN).
+
+Este Contrato de Licença de Usuário Final ("EULA") rege o uso do software **NativeSoul** ("Software"), fornecido por Fillipe Cordeiro / InnoDev ("Licenciante").
+
+Ao instalar ou usar o Software, você ("Licenciado") concorda com estes termos.
+
+---
+
+## 1. Concessão de licença
+
+### 1.1 Licença paga única (sem tier gratuito)
+O Software é **pago**: **não há tier gratuito**. O Licenciante concede uma licença **não exclusiva e intransferível** para instalar e usar o Software em máquinas sob seu controle, para uso pessoal ou comercial, **mediante aquisição de uma chave de licença válida** e sua ativação (`nativesoul license activate <key>`). A chave é emitida e gerenciada pelo processador de pagamento (**Dodo Payments**) e concedida ao Licenciado identificado na compra.
+
+### 1.2 Modelo de pagamento — pagamento único (perpetual fallback)
+A licença é adquirida por **pagamento único de US$ 29** que inclui:
+- uso **perpétuo** da versão adquirida do Software; e
+- atualizações por **12 (doze) meses** a partir da data de compra.
+
+Após 12 meses, o Licenciado **mantém o direito perpétuo** de usar o último build liberado dentro do período, sem expiração. Atualizações posteriores (novas versões major) podem exigir uma compra de upgrade. **Não há cobrança recorrente nem assinatura.**
+
+O lembrete de upgrade de major é **meramente informativo** (*soft-nudge*): a licença adquirida **nunca deixa de funcionar** nem tem funcionalidades removidas por término da janela de updates ou lançamento de nova versão major (ver ADR-043 §3). O upgrade para uma nova major é sempre **opcional**.
+
+---
+
+## 2. Restrições
+
+O Licenciado **NÃO** poderá:
+- fazer fork, redistribuir, revender, sublicenciar ou disponibilizar o Software a terceiros;
+- criar e distribuir obras derivadas do Software;
+- descompilar, desofuscar ou fazer engenharia reversa do Software, exceto na medida permitida por lei imperativa;
+- contornar, remover ou adulterar o mecanismo de licenciamento;
+- compartilhar chaves de licença.
+
+---
+
+## 3. Privacidade e dados (local-first)
+
+- O Software é **local-first**: os dados do Licenciado (identidade, memória, logs) permanecem na máquina do Licenciado, em `~/.nativesoul/`.
+- O Software **não coleta telemetria de uso** nem transmite o código ou a memória do Licenciado a terceiros.
+- O Software **não copia credenciais** dos hosts.
+- **Verificação de licença:** o Software realiza, **no máximo uma vez por dia**, uma checagem da chave de licença junto ao processador de pagamento (Dodo Payments, endpoint `/licenses/validate`), enviando **apenas a chave de licença** — nenhum dado de uso, código ou conteúdo. Um **identificador aleatório de instalação** é enviado **uma única vez, na ativação** (`/licenses/activate`), apenas para o controle de limite de ativações (jamais um *fingerprint* de hardware). Em caso de falha de rede, o Software continua funcionando por uma **janela de tolerância (grace) de 14 dias (configurável)** antes de solicitar reativação. **Toda checagem é registrada no audit log local.**
+
+> Estas garantias são verificáveis pelo Licenciado por comportamento observável (ex.: inspeção de rede, `nativesoul doctor`, leitura do audit log). **Observação:** após o pivô de 2026-06-30 (ADR-045), o Software **não** é mais "zero rede" — a checagem diária de licença é o único tráfego de saída.
+
+## 4. Propriedade
+
+O Software é licenciado, não vendido. Todos os direitos de propriedade intelectual permanecem com o Licenciante.
+
+## 5. Garantia e responsabilidade
+
+O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIAS DE QUALQUER NATUREZA, EXPRESSAS OU IMPLÍCITAS. NA MÁXIMA EXTENSÃO PERMITIDA EM LEI, O LICENCIANTE NÃO SE RESPONSABILIZA POR DANOS DECORRENTES DO USO DO SOFTWARE.
+
+## 6. Reembolso
+
+**Reembolso integral em até 30 (trinta) dias** da compra, sem questionamento, processado via Dodo Payments. Ao reembolsar, a chave de licença é **revogada**; na próxima checagem diária (após a janela de grace) o Software passa ao estado não licenciado. Os termos vigentes prevalecem no ponto de venda.
+
+> **Merchant of Record:** A **Dodo Payments** atua como *Merchant of Record* (vendedor formal de registro) da transação. Como tal, a Dodo é responsável por apurar e recolher os **impostos aplicáveis (VAT/GST/imposto sobre vendas)** conforme a jurisdição do Licenciado e por **processar reembolsos** globalmente.
+
+## 7. Rescisão
+
+A violação destes termos encerra automaticamente a licença. O Software pode ser desinstalado a qualquer momento (`nativesoul uninstall`), restaurando o estado anterior do sistema.
+
+---
+
+> **Pendências antes de publicar (legal):** jurisdição/foro, dados de contato do Licenciante, tratamento da chave de licença + UUID de instalação sob LGPD/GDPR (dado mínimo, mas é transmitido ao Dodo na checagem diária), e conformidade com legislação aplicável (consumidor). Encaminhar para revisão @legal-chief.
+> **Confirmado (ADR-045):** a **Dodo Payments** é o *Merchant of Record* e cuida de impostos (VAT/GST/imposto sobre vendas) e reembolsos globalmente — ver §6.

package/llm-install.txt

@@ -0,0 +1,222 @@
+# NativeSoul — LLM Install & Onboarding Guide
+# Version: 1
+# Audience: Claude Code, Codex, Gemini CLI, Grok Build, Antigravity, and any host LLM with terminal + MCP access
+#
+# HOW TO USE THIS FILE
+# The user pastes a short install prompt that points HERE. You (the host LLM) must
+# read this file first and execute it step by step. Do not invent steps outside this guide.
+
+## Resolve this file
+
+1. If working inside the nativesoul git repo: `./llm-install.txt` (repo root)
+2. After global npm install: `$(npm root -g)/nativesoul/llm-install.txt`
+3. After local prefix install: `<prefix>/lib/node_modules/nativesoul/llm-install.txt`
+
+---
+
+## PHASE 1 — INSTALL
+
+Prerequisites: Node.js 22.17+, npm, terminal access.
+
+Safety (non-negotiable):
+- Dry-run before any `--apply` on real host config
+- Never skip checksum verification on release tarball
+- Never overwrite user-edited host files silently
+- Never copy credentials into workspace or host instruction files
+
+Steps:
+
+1. `npm install && npm run lint && npm run typecheck && npm test && npm run build`
+2. `npm run package:local`
+3. Verify: `cd .artifacts/package && shasum -a 256 -c nativesoul-*.tgz.sha256`
+4. Set paths:
+   PREFIX="$PWD/.artifacts/local-prefix"
+   HOME_DIR="$PWD/.artifacts/local-home"
+   TARBALL="$(ls .artifacts/package/nativesoul-*.tgz | tail -n 1)"
+   npm install -g --prefix "$PREFIX" "$TARBALL"
+5. `"$PREFIX/bin/nativesoul" init --home "$HOME_DIR" --json`
+6. Safe test with temp target (NOT real host files):
+   TARGET_ROOT="$(mktemp -d)"
+   `"$PREFIX/bin/nativesoul" install --all-hosts --target-root "$TARGET_ROOT" --home "$HOME_DIR" --json`
+   Show report → wait for user approval → `--apply` → `doctor --deep --all-hosts --target-root "$TARGET_ROOT"`
+7. Real host integration (only after approval):
+   `"$PREFIX/bin/nativesoul" install --all-hosts --home "$HOME_DIR" --json`
+   Show diff → wait for approval → `--apply`
+8. Review MCP manifests: `mcp manifest --host codex|claude|gemini|grok|antigravity --json`
+9. Summarize install state, pending OAuth/trust items, rollback commands.
+
+---
+
+## PHASE 2 — ONBOARDING (same session, optional)
+
+After Phase 1 summary, ask ONE question using the host question UI:
+- Claude Code: AskUserQuestion
+- Codex: native confirmation UI
+- Fallback: ask in chat and wait for explicit yes/no
+
+Question: "NativeSoul está instalado. Quer iniciar o onboarding da sua entidade agora?"
+Options: "Sim, iniciar onboarding" | "Não, depois"
+
+If "Não" → stop. Tell user they can run `nativesoul onboard status` later.
+If "Sim" → continue below. Do NOT ask user to paste another prompt.
+
+### Knowledge sources for file generation
+
+During onboarding you MUST use these sources (in order):
+
+1. `life_onboarding_status` MCP tool (or `nativesoul onboard status --json`)
+   → returns interview themes, protected files, and `file_generation_rules`
+2. This file (sections FILE RULES below)
+3. `life_onboard_apply` enforces server-side guards — invalid writes are rejected
+
+You do NOT need prior training on NativeSoul if MCP is registered and you call
+`life_onboarding_status` before drafting files.
+
+### Interview (5 anchor themes)
+
+Ask follow-ups as needed, but cover all five:
+1. entity — name, creature/type, emoji, one-line mission
+2. soul — tone, boundaries, never-do rules
+3. human — how to address user, timezone, languages
+4. collaboration — workflow style, stack, review expectations
+5. continuity — which hosts (Claude/Codex/Gemini/Grok/Antigravity), what must persist
+
+### Draft → approve → apply → complete
+
+1. Call `life_onboarding_status` — if `ritual_pending` is false, summarize identity and stop.
+2. Draft IDENTITY.md, SOUL.md, USER.md, AGENTS.md in your own words (NOT slot-fill of placeholders).
+3. Show drafts → wait for explicit user approval.
+4. `life_onboard_apply` with `dry_run: true`, `user_confirmed: false`
+5. After user confirms: `life_onboard_apply` with `dry_run: false`, `user_confirmed: true`
+6. `life_onboard_complete`
+7. Verify: `life_bootstrap` — identity fields populated, no BOOTSTRAP_RITUAL_PENDING warning.
+
+CLI equivalents:
+- `nativesoul onboard status --json`
+- `nativesoul onboard apply --payload-file onboarding.json --json` (dry-run default)
+- `nativesoul onboard apply --payload-file onboarding.json --apply --user-confirmed --json`
+- `nativesoul onboard complete --json`
+
+---
+
+## PHASE 3 — ACTIVATION (same session, must complete)
+
+After onboarding, you MUST continue with activation to operationalize continuity.
+
+Ask explicitly for approval before each apply action. `onboard activation` and `onboard verify` are read-only unless `--apply` is passed.
+
+1. Read activation defaults and current status:
+   `"$PREFIX/bin/nativesoul" activate status --all-hosts --home "$HOME_DIR" --json`
+
+2. Show a QuickStart activation plan and ask approval:
+   `"$PREFIX/bin/nativesoul" onboard activation --profile quickstart --home "$HOME_DIR" --json`
+
+   Ask explicitly:
+   - `Do you approve applying QuickStart heartbeat settings now?` (heartbeat enabled + scheduler defaults)
+   - `Do you approve memory candidate hooks now?` (candidate-only by default)
+   - `Do you approve recall auto-trigger settings now?`
+
+3. If approved, apply once:
+   `"$PREFIX/bin/nativesoul" onboard activation --profile quickstart --home "$HOME_DIR" --apply --user-confirmed --json`
+
+4. If the user wants advanced control, ask each option and call:
+   - heartbeat host and cadence (`--scheduler-host`, `--heartbeat-cadence`)
+   - memory candidate mode (`--memory-candidates`, `--recall-auto-trigger`, `--recall-keywords`, `--recall-denylist`)
+   - promotion policy (`--promotion-policy manual|explicit_approval`) and optional threshold (`--candidate-confidence-threshold`)
+
+   Apply only after the same explicit host confirmation.
+
+5. Run read-only verification first and summarize:
+   `"$PREFIX/bin/nativesoul" onboard verify --host all --home "$HOME_DIR" --json`
+
+6. Ask for optional explicit verification persistence and promotion review:
+   - `Do you want to apply activation verification with explicit review and promotion?`
+   - If yes, re-run with `--apply --user-confirmed`.
+   - If no, keep verification read-only and document blockers.
+
+7. Final summary:
+   `"$PREFIX/bin/nativesoul" doctor --deep --all-hosts --home "$HOME_DIR" --json`
+   Report hosts in `active`, `degraded`, or `blocked_by_host` states.
+
+Important: Do not claim hidden or implicit scheduler creation. If a host lacks native scheduler support, mark it as blocked and instruct explicit user-led alternatives.
+
+---
+
+## FILE RULES — how to generate human files
+
+Generate prose Markdown. The server validates size (64 KiB/file) and protection rules.
+
+### IDENTITY.md (writable during onboarding)
+
+Required fields (use `- **Label:** value` format):
+- Name, Creature, Role, Vibe, Emoji, Mission
+
+Structure:
+```
+# Identity
+
+- **Name:** ...
+- **Creature:** ...
+- **Role:** ...
+- **Vibe:** ...
+- **Emoji:** ...
+- **Mission:** ...
+```
+
+Parsed by bootstrap into `identity.name`, `identity.mission`, etc.
+
+### SOUL.md (writable ONLY with user_confirmed: true)
+
+Sections: Core truths, Boundaries, Vibe, Continuity
+Voice and boundaries in prose — not bullet placeholders.
+Protected after onboarding — future edits require proposal flow.
+
+### USER.md (writable during onboarding)
+
+Fields: Name, What to call them, Timezone, Languages, Notes
+Optional sections: Context, Engineering preferences
+Summarized into bootstrap `user.preferences_summary`.
+
+### AGENTS.md (merge, do not erase)
+
+Add/update operating instructions. Preserve:
+- Existing user content outside `<!-- nativesoul:start v1 -->` managed block
+- NativeSoul managed block if present
+Append onboarding-specific workflow if file already customized.
+
+### POLICY.md (NEVER write during onboarding)
+
+Use `policy propose-change` after onboarding if needed.
+
+---
+
+## MCP tools reference
+
+| Tool | When |
+|------|------|
+| life_onboarding_status | Start onboarding — get rules + ritual state |
+| life_onboard_apply | Dry-run or write human files |
+| life_onboard_complete | Archive BOOTSTRAP.md, mark ritual done |
+| life_bootstrap | Verify identity loaded after complete |
+
+---
+
+## Host shortcuts (optional)
+
+| Host | Shortcut |
+|------|----------|
+| Claude Code | `/nativesoul-install` |
+| Codex | skill `nativesoul-install` |
+| Gemini CLI | `/nativesoul-install` |
+| Antigravity | skill `nativesoul-install` via `/skills` |
+
+All shortcuts point to this file (`llm-install.txt`) for full Phase 1 + Phase 2 protocol.
+
+---
+
+## Rollback
+
+```
+nativesoul uninstall --all-hosts --apply
+nativesoul mcp rollback --snapshot <path> --apply
+```

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "nativesoul",
+  "version": "0.1.0",
+  "description": "Local-first continuity layer for coding agents.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "main": "dist/packages/cli/src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fillipeweb/nativesoul.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fillipeweb/nativesoul/issues"
+  },
+  "homepage": "https://github.com/fillipeweb/nativesoul#readme",
+  "files": [
+    "dist/",
+    "plugins/",
+    "policy-packs/",
+    "schemas/",
+    "docs/adr/",
+    "docs/legal/",
+    "llm-install.txt",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "nativesoul": "dist/packages/cli/src/index.js",
+    "nativesoul-mcp": "dist/packages/mcp-server/src/index.js"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && npm run test:non-e2e",
+    "test:non-e2e": "node scripts/run-non-e2e-tests.mjs",
+    "build": "npm run build:ts && npm run build:minify",
+    "build:ts": "tsc -p tsconfig.build.json",
+    "build:minify": "node scripts/build-min.mjs",
+    "policy:generate": "node scripts/generate-policy-fail-closed.mjs",
+    "policy:check": "node scripts/generate-policy-fail-closed.mjs --check",
+    "release:security:audit": "node scripts/release-security-audit.mjs",
+    "release:provenance:dry-run": "node scripts/release-provenance-dry-run.mjs",
+    "package:local": "node scripts/package-local.mjs",
+    "package:dry-run": "node scripts/package-dry-run.mjs",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "test:e2e": "npm run build && vitest run tests/e2e"
+  },
+  "engines": {
+    "node": ">=22.17.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.0.0",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.5.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.0",
+    "vitest": "^4.1.9"
+  }
+}

package/plugins/antigravity-nativesoul/GEMINI.md

@@ -0,0 +1,17 @@
+<!-- nativesoul:start v1 -->
+# NativeSoul bridge for Antigravity
+
+At the start of continuity-sensitive work, load NativeSoul context.
+
+Preferred path: use MCP `life_bootstrap` with `host="antigravity"` and the current working directory.
+
+Fallback path: run `nativesoul bootstrap --host antigravity --cwd <current-working-directory> --format inject --json`.
+
+Use `relevant_memories` for durable facts, `capability_cards` as advisory guidance, and `capabilities` only as the ready-only list.
+
+Native hooks and scheduler support are not declared unless Antigravity official documentation exposes them. Do not create cron, daemons, or sidecars.
+
+Never copy credentials or auto-edit `SOUL.md`/`POLICY.md`; propose those changes for approval.
+
+Host adapter: antigravity.
+<!-- nativesoul:end -->