nativesoul 0.1.0

package/docs/adr/ADR-030-host-surface-matrix-v1.md

@@ -0,0 +1,93 @@
+# ADR-030: Host surface matrix v1
+
+## Status
+
+Accepted — Story 6.1. Provider parity details are superseded by ADR-031.
+
+## Context
+
+NativeSoul `install --all-hosts` registers MCP and managed blocks using single paths per host id (`~/.claude/mcp.json`, `~/.codex/mcp.json`). Real validation (2026-06-23) showed Claude Code, Claude Desktop, and Codex App read **different configuration surfaces**.
+
+Epic 6 requires a canonical matrix before further install or plugin work.
+
+## Decision
+
+Each **host id** maps to one or more **surfaces** (install targets). Install orchestrator writes to every surface for that host on the current OS.
+
+| Host id | Surface | Managed block target | MCP config target | Plugin / package target | OS notes |
+|---------|---------|----------------------|-------------------|-------------------------|----------|
+| `claude` | Claude Code CLI | `~/.claude/CLAUDE.md` | `~/.claude.json` -> `mcpServers` (user scope) | `~/.claude/plugins/nativesoul/` or installed `.claude-plugin` package | Cross-platform under the user's home directory. |
+| `claude` | Claude Desktop | N/A — no global `CLAUDE.md` | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Linux: `${XDG_CONFIG_HOME:-~/.config}/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json` | Shared `~/.claude/plugins/nativesoul/` plus `~/.claude/settings.json` hooks per ADR-031 | Target path is resolved by platform; no macOS-only default. |
+| `codex` | Codex CLI / App single surface | `~/.codex/AGENTS.md` | `~/.codex/mcp.json` | `~/.codex/plugins/nativesoul/` or installed `.codex-plugin` package | Cross-platform under the user's home directory. Story 6.4 local spike confirmed no separate Codex App MCP target on the operator macOS machine. |
+| `grok` | Grok Build | `~/.grok/AGENTS.md` | `~/.grok/mcp.json` | `~/.grok/plugins/nativesoul/` | Native plugin hooks per ADR-031; no hidden scheduler fallback. |
+| `antigravity` | Antigravity CLI | `~/.gemini/GEMINI.md` | `~/.gemini/antigravity-cli/mcp_config.json` | `~/.antigravity/plugins/nativesoul/` | Native plugin hooks per ADR-031; no hidden scheduler fallback. |
+| `gemini` | Gemini CLI | `~/.gemini/GEMINI.md` | `~/.gemini/settings.json` | `~/.gemini/extensions/nativesoul/` | Native extension hooks per ADR-031; `/memory refresh` is reload guidance, not a scheduler. |
+
+### Migration notes
+
+- Existing NativeSoul writes to `~/.claude/mcp.json` are treated as legacy for Claude Code.
+- Deep doctor should report `LEGACY_MCP_PATH` when `~/.claude/mcp.json` contains `mcpServers.nativesoul` but `~/.claude.json` does not.
+- Migration is explicit and reversible: install the new surface, verify doctor, then uninstall or rollback the legacy target.
+- No existing non-NativeSoul MCP servers, preferences, credentials, or comments are removed during migration.
+
+### Command resolution
+
+- MCP `command` MUST resolve on install (absolute path or verified PATH).
+- Doctor MUST execute `which`/existence check, not string match on `"nativesoul-mcp"`.
+- Platform-specific app config paths MUST be resolved in code, not hard-coded to macOS paths.
+
+### Codex App path spike (Story 6.4)
+
+Local read-only discovery on the operator macOS machine found:
+
+- `~/.codex/mcp.json` exists and contains the JSON MCP `mcpServers.nativesoul` registration shape.
+- `~/.codex/config.toml` exists, but is a broader Codex configuration surface and is not the NativeSoul MCP JSON target for this MVP.
+- `~/Library/Application Support/Codex`, `~/Library/Application Support/com.openai.codex`, and `~/Library/Application Support/OpenAI/Codex` exist, but inspected files were app state, Chromium/Electron cache, crashpad, or native-host metadata. No additional Codex App MCP JSON config target was found.
+
+Decision for M2: treat Codex CLI and Codex App as a **single MCP install surface** backed by `~/.codex/mcp.json`. NativeSoul MUST NOT write into Codex `Application Support` directories unless a future validated ADR identifies a supported MCP path there.
+
+### Bootstrap tier per surface
+
+| Surface | Preferred tier | Fallback |
+|---------|----------------|----------|
+| Claude Code | A — SessionStart hook via plugin | D — `generated/claude/last-context.md` |
+| Claude Desktop | A — if hooks available; else MCP at connect | D — cache + first-turn instruction |
+| Codex | A — session hook via plugin | D — cache |
+| Grok Build | A — plugin lifecycle hook plus managed block fallback | D — `bootstrap --format cache` degraded context |
+| Antigravity CLI | A — plugin lifecycle hook plus managed block fallback | D — `bootstrap --format cache` degraded context |
+| Gemini CLI | A — extension lifecycle hook plus managed block fallback and `/memory refresh` guidance | D — `bootstrap --format cache` degraded context |
+
+Providers must stay synchronized through native hooks where validated and Tier B/D fallbacks where necessary. Do not emulate schedulers or hooks with hidden cron/daemon behavior.
+
+## Consequences
+
+- `packages/core/src/host-integration.ts` gains surface-aware targets (breaking change to default paths — migration + doctor warning).
+- `install --all-hosts` may touch more files; backups per target required (ADR-007, ADR-017).
+- Epic 5 plugins bundle MCP registration to avoid drift across surfaces.
+- `plugins/` becomes the planned repository location for host-native package sources generated by Stories 5.1, 5.2, and 6.6.
+
+## Alternatives considered
+
+| Alternative | Rejected because |
+|-------------|------------------|
+| Single `~/.claude/mcp.json` for all Claude surfaces | Not read by Claude Code user scope or Desktop |
+| Document manual steps only | Fails FR-002 automatic bootstrap operator experience |
+
+## References
+
+- Story 6.1, Epic 006
+- Real-host validation Wave 4 / FifoClaw 2026-06-23
+- Claude Code MCP docs: `~/.claude.json` user scope
+
+## Review
+
+- Architect sign-off: GO recorded in `docs/stories/epics/VALIDATION-REPORT.md`.
+- PO sign-off: Story 6.1 validated 10/10 and moved to Done on 2026-06-23.
+
+## Change Log
+
+- 2026-06-23: Drafted from Wave 4 real-host validation.
+- 2026-06-23: Accepted in Story 6.1; added surface matrix, plugin targets, OS notes, and legacy migration rule.
+- 2026-06-23: Story 5.7 added explicit Tier B/D parity for Grok, Antigravity, and Gemini.
+- 2026-06-23: Story 6.4 confirmed Codex CLI/App single MCP surface on the operator macOS machine.
+- 2026-06-24: Claude Desktop MCP target changed from macOS-only to platform-resolved macOS/Linux/Windows paths.

package/docs/adr/ADR-031-host-parity-matrix-v2.md

@@ -0,0 +1,91 @@
+# ADR-031: Host parity matrix v2
+
+## Status
+
+Accepted — Epic 10
+
+## Context
+
+ADR-030 correctly mapped install surfaces, but Grok, Antigravity, and Gemini still read as "preview". The product requirement is stronger: these hosts must deliver the same operator benefit as Codex/Claude when official surfaces allow it, while never claiming native hooks or schedulers that are not documented.
+
+Gemini CLI has official extension, context, command, MCP, and extension hook surfaces. Grok exposes plugin hooks and MCP through its local plugin manager. Antigravity exposes package hooks and MCP through its local plugin validation/install surface. Native scheduler support still requires separate proof and is not claimed for Gemini, Grok, or Antigravity.
+
+## Decision
+
+Provider parity is reported by capability level, not by implementation identity.
+
+| Level | Meaning |
+|-------|---------|
+| `native` | Host exposes a documented native hook/package/scheduler surface and NativeSoul installed it. |
+| `official-fallback` | Host has no validated native hook/scheduler, but NativeSoul installed an explicit package/command/MCP/context fallback using supported file/config surfaces. |
+| `unsupported-native` | No supported native or fallback package surface is installed for this capability. |
+| `ready` | The host delivers the end-user flow through native or official fallback surfaces. |
+
+## Host matrix
+
+| Host | Package surface | Hooks | Scheduler | Expected parity |
+|------|-----------------|-------|-----------|-----------------|
+| `codex` | native plugin | `native` | native if Codex Automations manifest is detected; otherwise fallback heartbeat command | `ready` when plugin/MCP/block are installed |
+| `claude` Code | native plugin | `native` | native if Claude Scheduled Tasks manifest is detected; otherwise fallback heartbeat command | `ready` when plugin/MCP/block are installed |
+| `claude` Desktop | shared Claude plugin/settings hooks + MCP config | `native` | fallback heartbeat command | `ready` when plugin/settings/MCP are installed |
+| `gemini` | official extension at `~/.gemini/extensions/nativesoul/` | `native` through extension hooks | `official-fallback`; no hidden cron | `ready` through extension hooks + MCP + `GEMINI.md` + commands |
+| `grok` | native plugin at `~/.grok/plugins/nativesoul/`; post-copy `grok plugin install --trust` registers hooks with the CLI | `native` through `hooks/hooks.json` | `official-fallback`; no hidden cron | `ready` through plugin hooks + MCP + `AGENTS.md` + commands |
+| `antigravity` | native plugin at `~/.antigravity/plugins/nativesoul/` | `native` through root `hooks.json` | `official-fallback`; no hidden cron | `ready` through plugin hooks + MCP + shared `GEMINI.md` block + commands |
+
+## Capability Status Semantics
+
+`ready` is not the same as `full native capability`.
+
+- `ready` means the operator flow works through installed NativeSoul surfaces: bootstrap, MCP, package/plugin or extension, managed block, memory recall, policy guard, and heartbeat fallback where needed.
+- `ready with fallback` means NativeSoul is operational but one or more host capabilities use explicit fallback or are blocked by missing native host support. This is valid support language, but not a full-native claim.
+- `full native capability` means every capability for that host is native or fully ready, including native scheduler support and non-degraded capability scan.
+- `official-fallback` is an accepted, honest mode. It is not a failure, but it must not be described as native support.
+- `degraded` capability scan means NativeSoul can still operate, but the host capability inventory came from a fallback or partial source and must not be overclaimed.
+
+## Current Real-Host Snapshot
+
+Snapshot source: `nativesoul doctor --deep --all-hosts --json` on the operator machine, 2026-06-25.
+
+| Host surface | Operational parity | Hooks | Bootstrap/MCP/package | Capability scan | Heartbeat / scheduler | Full native capability? |
+|--------------|--------------------|-------|------------------------|-----------------|-----------------------|-------------------------|
+| `codex` | `ready` | `native` | `ready` | `degraded` | `official-fallback`; `native_scheduler_supported=false` | No |
+| `claude` Code | `ready` | `native` | `ready` | `ready` | `official-fallback`; `native_scheduler_supported=false` | No |
+| `claude` Desktop | `ready` | `native` | `ready` | `ready` | `official-fallback`; `native_scheduler_supported=false` | No |
+| `gemini` | `ready` | `native` via official extension hooks | `ready` | `ready` through official extension/config inventory | `official-fallback`; `native_scheduler_supported=false`; blocked by host for full-native scheduler | No |
+| `grok` | `ready` | `native` via plugin hooks | `ready` | `ready` through native plugin/hook/MCP/command inventory | `official-fallback`; `native_scheduler_supported=false`; blocked by host for full-native scheduler | No |
+| `antigravity` | `ready` | `native` via package hooks | `ready` | `degraded` | `official-fallback`; `native_scheduler_supported=false` | No |
+
+Current conclusion: all supported hosts are operationally ready for NativeSoul continuity, but no host should be marketed or documented as `full native capability` until native scheduler mappings are proven and capability scans are non-degraded for that host.
+
+The release gate for public support claims is:
+
+```sh
+nativesoul doctor --deep --all-hosts --require-full-native --json
+```
+
+The command prints `full_native_matrix` and exits non-zero unless every selected host surface is full-native. Release copy may claim `ready` or `ready with fallback` for operational hosts that do not pass this strict gate.
+
+## Consequences
+
+- `doctor --deep` emits `provider_parity` per host with bootstrap, MCP, package, hooks, memory recall, policy guard, capability scan, and heartbeat status.
+- `doctor --deep` emits `full_native_matrix` for aggregate release decisions. `--require-full-native` turns that matrix into a strict gate.
+- Gemini and Antigravity may share `~/.gemini/GEMINI.md`; managed blocks therefore use host-scoped markers and can coexist.
+- Plugin/package doctor separates `enabled` package presence from `hook_registered`; Gemini, Grok, and Antigravity must now report hook registration when their hook manifests are installed.
+- `native_schedule_supported=false` remains visible for Gemini/Grok/Antigravity. Heartbeat parity is provided by explicit package commands, not a daemon, cron, or fake native scheduler.
+- Documentation and sales copy must distinguish `ready` from `full native capability`; fallback/degraded states are acceptable only when labeled explicitly.
+
+## References
+
+- `nativesoul-prd-v1.0.md` §9.4, §11.1, §14, §25.2
+- `docs/adr/ADR-030-host-surface-matrix-v1.md`
+- `docs/stories/epics/EPIC-010-provider-parity.md`
+
+## Change Log
+
+- 2026-06-24: Accepted for Epic 10 provider parity.
+- 2026-06-24: Updated after local official discovery proved Gemini extension hooks, Grok plugin hooks, and Antigravity plugin hooks. Scheduler support remains fallback-only.
+- 2026-06-25: Added current real-host capability snapshot and clarified `ready` vs `full native capability`.
+- 2026-06-26: Story 16.4 updated Gemini: official extension/config inventory is machine-readable; persistent scheduler remains undocumented and blocked for full-native.
+- 2026-06-26: Story 16.5 updated Grok: native plugin/hook/MCP/command inventory is machine-readable; headless/external scheduling remains non-native.
+- 2026-06-26: Story 16.7 added `full_native_matrix`, `--require-full-native`, and release-claim audit language.
+- 2026-06-27: Grok install now auto-registers copied plugins via `grok plugin install --trust`; capability scan dedupes `~/.grok/plugins/*` inventory.

package/docs/adr/ADR-032-nativesoul-hard-cut-rebrand.md

@@ -0,0 +1,54 @@
+# ADR-032: NativeSoul hard-cut rebrand
+
+## Status
+
+Accepted for Epic 12.
+
+## Context
+
+The project name is now NativeSoul. The repo is still local/private, so the rename can be a hard cut before M7 instead of a compatibility migration for public users.
+
+Keeping old command names, environment variables, managed markers, MCP keys, package paths, or home directories would increase host-install ambiguity and make operator diagnosis harder.
+
+## Decision
+
+NativeSoul is the only supported public name after Epic 12.
+
+| Surface | Decision |
+|---------|----------|
+| Package name | `nativesoul` |
+| CLI binaries | `nativesoul`, `nativesoul-mcp` |
+| Environment variables | `NATIVESOUL_*` only |
+| Local home | `~/.nativesoul` |
+| SQLite path | `~/.nativesoul/state/nativesoul.sqlite` |
+| MCP server key | `nativesoul` |
+| Host package directories | `nativesoul` under each host plugin or extension root |
+| Managed markers | `<!-- nativesoul:<host>:start v1 -->` / `<!-- nativesoul:<host>:end -->` |
+| Repository target | `fillipeweb/nativesoul` |
+
+No compatibility aliases are retained in code, docs, package metadata, host manifests, or active install configuration.
+
+## Consequences
+
+- Existing local data must be copied to `~/.nativesoul` before old local install paths are removed.
+- Installed host configs must reference `nativesoul` and `nativesoul-mcp`.
+- Global npm link must expose only the new binaries.
+- Release and package smoke gates must validate the new package metadata.
+- Final verification includes a hard-cut search for the former package strings in active tracked files.
+
+## Validation
+
+- `nativesoul --help`
+- `nativesoul-mcp` JSON-RPC initialize smoke
+- `nativesoul init -> status -> doctor`
+- `nativesoul install --all-hosts --apply --target-root <tmp>`
+- `nativesoul doctor --deep --all-hosts --target-root <tmp>`
+- `nativesoul uninstall --all-hosts --apply --target-root <tmp>`
+- `npm run lint`
+- `npm run typecheck`
+- `npm run policy:check`
+- `npm test`
+- `npm run test:e2e`
+- `npm run package:smoke`
+- `npm run release:provenance:dry-run -- --json`
+- `npm run release:security:audit -- --dependency-audit=offline`

package/docs/adr/ADR-033-local-hybrid-memory-reflection.md

@@ -0,0 +1,49 @@
+# ADR-033: Local hybrid memory and reflection
+
+## Status
+
+Accepted for M7 backlog
+
+## Context
+
+Epic 13 introduces semantic indexing, hybrid recall, reflection reports, and memory transition guardrails. These features touch the highest-risk NativeSoul state: durable memories and the evidence used to recall or promote them.
+
+The review of the M7 backlog identified that stories 13.1-13.4 were Ready, but the architectural boundary was not explicit enough for implementation. The missing decisions were local-only indexing, additive hybrid search, a defined reflection algorithm, and a required transition state machine before memory automation can safely run in M9.
+
+## Decision
+
+NativeSoul memory search remains local-first and additive.
+
+1. FTS remains the baseline recall path.
+2. Semantic vectors are optional local indexes, never a replacement for canonical memory records.
+3. Hybrid recall must merge FTS and semantic candidates with deterministic scope filtering by project, host, source, and sensitivity before results reach bootstrap or MCP responses.
+4. Reflection consolidation produces reviewable proposals, not direct durable memory writes.
+5. Memory status changes must pass a transition matrix before M9 memory automation may enable recurring candidate or promotion workflows.
+
+## Reflection Algorithm Boundary
+
+Story 13.3 must implement a transparent pipeline:
+
+1. Collect daily notes, candidates, stale active records, and duplicate clusters.
+2. Redact or exclude secret-like content before ranking.
+3. Group candidates by project and intent.
+4. Score consolidation opportunities by recency, repetition, confidence, and conflict risk.
+5. Emit a report with proposed create/update/reject/expire actions and before/after evidence.
+6. Require human approval or an explicit policy before applying durable changes.
+
+## Consequences
+
+- Story 13.4 is a prerequisite for M9 story 17.4.
+- Story 13.2 must cite NFR-001 and keep local recall within bounded latency and context budget.
+- MCP handlers and CLI commands must share the same recall and transition services.
+- Dashboard work in Epic 15 may read reflection output but must not introduce write authority.
+
+## References
+
+- `docs/stories/epics/EPIC-013-m7-hybrid-memory-reflection.md`
+- `docs/stories/13.1-local-semantic-index-v1.md`
+- `docs/stories/13.2-hybrid-memory-recall-v1.md`
+- `docs/stories/13.3-reflection-consolidation-report-v1.md`
+- `docs/stories/13.4-memory-transition-guardrails-v1.md`
+- `docs/adr/ADR-014-memory-lifecycle-v1.md`
+

package/docs/adr/ADR-034-memory-importers-provenance.md

@@ -0,0 +1,38 @@
+# ADR-034: Memory importers and provenance
+
+## Status
+
+Accepted for M7 backlog
+
+## Context
+
+Epic 14 adds OpenClaw and native host importers. Importers can accidentally over-trust external data, leak secrets, or blur the difference between imported material and NativeSoul-approved memories.
+
+The M7 review identified that importer safety needs an explicit architecture decision before implementation.
+
+## Decision
+
+All memory importers are dry-run-first and provenance-preserving.
+
+1. Importers read only documented export files, user-selected paths, or explicit CLI inputs.
+2. Importers never read private host databases or undocumented binary stores.
+3. Dry-run output is required before any write.
+4. Imported records are created as candidates unless a stricter human-approved policy exists.
+5. Every imported record stores source system, source path or logical origin, import timestamp, mapping confidence, and redaction status.
+6. Secret-like content is redacted or rejected before candidate creation.
+
+## Consequences
+
+- Story 14.1 must prove OpenClaw import mapping without writes by default.
+- Story 14.2 must keep host-specific importers opt-in and documented.
+- Imported memories cannot bypass ADR-033 transition guardrails.
+- Audit events are required for dry-run summaries and applied imports.
+
+## References
+
+- `docs/stories/epics/EPIC-014-m7-importers-policy-packs.md`
+- `docs/stories/14.1-openclaw-importer-dry-run-v1.md`
+- `docs/stories/14.2-native-memory-importers-v1.md`
+- `docs/adr/ADR-014-memory-lifecycle-v1.md`
+- `docs/adr/ADR-033-local-hybrid-memory-reflection.md`
+

package/docs/adr/ADR-035-policy-pack-apply-rollback.md

@@ -0,0 +1,34 @@
+# ADR-035: Policy pack apply and rollback
+
+## Status
+
+Accepted for M7 backlog
+
+## Context
+
+Epic 14 also introduces policy packs. Policy packs are useful for repeatable operator setup, but they affect standing orders and other authority-bearing files. NativeSoul already treats `SOUL.md`, `POLICY.md`, and standing orders as human-authoritative surfaces.
+
+## Decision
+
+Policy packs are declarative, previewed, audited, and reversible.
+
+1. A policy pack declares files, managed blocks, standing-order entries, required approvals, and rollback strategy.
+2. Applying a pack requires a diff preview and explicit approval.
+3. Protected identity and policy files are never overwritten wholesale.
+4. Rollback must restore only the managed material that NativeSoul wrote.
+5. Each apply and rollback operation emits an audit event with pack id, version, affected files, and approval evidence.
+
+## Consequences
+
+- Story 14.3 owns the schema, catalog, validation rules, and sample packs.
+- Story 14.4 owns apply, rollback, audit, and failure recovery.
+- M9 activation may offer policy-pack recommendations, but cannot silently apply them.
+- Existing managed-block backup and rollback decisions remain authoritative.
+
+## References
+
+- `docs/stories/14.3-policy-pack-schema-catalog-v1.md`
+- `docs/stories/14.4-policy-pack-apply-rollback-v1.md`
+- `docs/adr/ADR-007-managed-block-backup-and-rollback.md`
+- `docs/adr/ADR-015-policy-standing-orders-v1.md`
+

package/docs/adr/ADR-036-local-operator-dashboard-readonly.md

@@ -0,0 +1,38 @@
+# ADR-036: Local operator dashboard read-only boundary
+
+## Status
+
+Accepted for M7 backlog
+
+## Context
+
+Epic 15 adds a local dashboard, host skills, and feedback metrics. The product value is operator visibility, but the architecture must preserve the existing rule: CLI first, observability second, UI third.
+
+The review flagged that dashboard data API and "smart explore" behavior need a clear boundary.
+
+## Decision
+
+The M7 dashboard is read-only and backed by CLI-readable data contracts.
+
+1. Dashboard state must be available through CLI/API before UI rendering.
+2. The dashboard may show memories, capabilities, runs, schedules, approvals, audit events, and metrics.
+3. The dashboard cannot approve, promote, forget, schedule, or edit policy in M7.
+4. Host skills for recall, planning, and exploration must call existing NativeSoul services and honor capability status.
+5. Local feedback metrics are stored locally and exclude prompts, memory bodies, secrets, and raw filesystem paths unless explicitly approved.
+
+## Consequences
+
+- Story 15.1 defines the data contract.
+- Story 15.2 consumes the contract without adding write authority.
+- Story 15.3 must define "explore" as scoped read-only discovery, not autonomous code mutation.
+- Story 15.4 must prove local-only feedback and retention behavior.
+
+## References
+
+- `docs/stories/epics/EPIC-015-m7-local-dashboard-skills.md`
+- `docs/stories/15.1-local-dashboard-data-api-v1.md`
+- `docs/stories/15.2-read-only-dashboard-viewer-v1.md`
+- `docs/stories/15.3-host-skills-recall-plan-explore-v1.md`
+- `docs/stories/15.4-local-feedback-metrics-v1.md`
+- `docs/adr/ADR-011-local-audit-cli-export.md`
+

package/docs/adr/ADR-037-full-native-evidence-contract.md

@@ -0,0 +1,45 @@
+# ADR-037: Full-native evidence contract
+
+## Status
+
+Accepted for M8 backlog
+
+## Context
+
+ADR-031 introduced the distinction between operational `ready` and `full native capability`. Epic 16 needs a stricter evidence contract so NativeSoul can stop relying on honest fallback language where official host-native scheduler and inventory surfaces are proven.
+
+The M8 review also confirmed that all-host full-native cannot be promised while Grok has no native scheduler.
+
+## Decision
+
+`full_native` is an evidence-backed status, not a marketing label.
+
+A host capability may be marked `full_native` only when all required evidence fields are present:
+
+1. Host id and version/source observed.
+2. Official documentation or local CLI/app help proving the native surface.
+3. Native scheduler support when the capability includes heartbeat or recurring work.
+4. Native capability inventory or non-degraded scan source.
+5. Native install/package/hook registration evidence.
+6. Verification command and timestamp.
+7. Failure mode for unsupported hosts: `blocked_by_host`, `degraded_scan`, or `ready_fallback`.
+
+The public JSON contract is `schemas/full-native-evidence.schema.json`. `doctor --deep` emits this contract per host under `full_native_evidence` without changing the existing operational `status` or `provider_parity` fields.
+
+Reference repositories such as `thedotmack/claude-mem`, `openclaw/openclaw`, and `openclaw/clawhub` may inform implementation patterns, but they do not satisfy this evidence contract. Full-native evidence must come from official host docs, local CLI/app help, local config/API proof, or machine-readable inventory.
+
+## Consequences
+
+- Story 16.1 owns schema, CLI output, doctor integration, and examples.
+- Stories 16.2-16.6 must populate evidence rather than hard-code claims.
+- Story 16.7 must fail strict full-native gates when evidence is missing.
+- Grok can be `ready` or `blocked_by_host` for scheduler, but must not become all-host full-native without vendor support.
+- M9 heartbeat onboarding depends on this contract to avoid offering fake native scheduler setup.
+
+## References
+
+- `docs/adr/ADR-031-host-parity-matrix-v2.md`
+- `docs/research/m8-full-native-host-parity-research.md`
+- `docs/research/external-architecture-references.md`
+- `docs/stories/epics/EPIC-016-m8-full-native-host-parity.md`
+- `docs/stories/16.1-full-native-evidence-contract-v1.md`

package/docs/adr/ADR-038-identity-vs-activation-onboarding.md

@@ -0,0 +1,39 @@
+# ADR-038: Identity vs activation onboarding
+
+## Status
+
+Accepted for M9 backlog
+
+## Context
+
+Story 1.9 introduced host-guided onboarding for identity and project setup. Epic 17 adds activation onboarding for heartbeat, memory automation, recall behavior, and cross-host verification.
+
+The M9 review identified an overlap risk: install must not mix identity creation with recurring automation setup in a way that hides approvals or makes onboarding irreversible.
+
+## Decision
+
+NativeSoul onboarding has two distinct phases.
+
+1. Identity onboarding defines who the agent is, project scope, protected identity/policy files, and host-managed blocks.
+2. Activation onboarding enables operational automation: heartbeat, recall triggers, memory candidate creation, promotion policy, standing orders, and verification.
+3. Install may chain from identity onboarding into activation, but activation must present a separate plan and approval prompt.
+4. QuickStart activation uses conservative defaults: no sensitive auto-promotion, no hidden scheduler, and no unsupported host writes.
+5. Advanced activation exposes scheduler host, cadence, memory policy, recall trigger, verification depth, and standing-order options.
+6. Re-running onboarding preserves existing configuration unless reset is explicit.
+
+## Consequences
+
+- Story 17.1 owns QuickStart/Advanced activation profiles.
+- Story 17.2 owns activation status and dry-run plan semantics.
+- Story 17.3 depends on ADR-037 for scheduler honesty.
+- Story 17.4 depends on ADR-033 for memory transition safety.
+- Story 17.6 may update install prompts only after 17.1-17.5 are implemented.
+
+## References
+
+- `docs/adr/ADR-029-host-guided-onboarding-v1.md`
+- `docs/adr/ADR-033-local-hybrid-memory-reflection.md`
+- `docs/adr/ADR-037-full-native-evidence-contract.md`
+- `docs/research/openclaw-onboarding-activation-reference.md`
+- `docs/stories/epics/EPIC-017-m9-activation-onboarding.md`
+

package/docs/adr/ADR-039-entitlements-offline-licensing.md

@@ -0,0 +1,47 @@
+# ADR-039: Entitlements & Offline Ed25519 Licensing
+
+## Status
+**LARGELY SUPERSEDED (2026-06-30) by [ADR-045](ADR-045-paid-only-closed-distribution.md)** — licensing is now **Dodo-managed online keys (once-a-day check + offline grace)**, not an offline Ed25519 token from a custom issuer. The boot gate is `licensed | unlicensed` (no `Tier`/`FeatureId`/`PRO_FEATURES`, no "degrade to Free"). The custom Ed25519 issuer is removed. Retained only as historical context.
+
+~~Accepted — for EPIC-018 (Onda 0 monetization)~~
+
+## Context
+
+O NativeSoul tem um tier Free (core de continuidade, uncapped) e um tier Pro pago, mas **não existe nenhuma camada de entitlement no código** (`packages/domain/src/types.ts` só tem `HandshakeTier`, que é qualidade de bootstrap — não plano comercial). Hoje todas as features rodam grátis, inclusive as que serão Pro (painel, importers).
+
+Precisamos de um mecanismo para distinguir Free de Pro e gatear features pagas **sem violar os pilares do produto**: local-first, sem daemon, sem telemetria, "never copies credentials", e a marca "He doesn't fake it". Qualquer verificação que telefone para casa quebraria esses pilares.
+
+O design técnico completo já existe em [`docs/architecture/entitlements-free-pro-design-v1.md`](../architecture/entitlements-free-pro-design-v1.md) (§1-11). Este ADR formaliza a **decisão de arquitetura**; o design-doc é a especificação de implementação que as stories do EPIC-018 executam.
+
+## Decision
+
+Adotar **licença offline assinada com Ed25519, verificada 100% localmente** via `node:crypto` (zero dependências novas — alinhado ao `dependencies: {}` do projeto).
+
+1. **Modelo de entitlement (domain layer).** `Tier = 'free' | 'pro'`, `FeatureId` (allowlist fechada de features ADITIVAS), `PRO_FEATURES`, `Entitlement`, `LicensePayload`. O core **nunca** recebe `FeatureId` → é estruturalmente impossível gatear o core (ver Consequences "never cripple free"). Ref design §1.
+
+2. **Licença = token `payload.assinatura`** (base64url do payload `.` base64url da assinatura Ed25519). O CLI **embute apenas a chave pública**; a chave privada vive só no emissor. HMAC simétrico foi rejeitado: exigiria a chave secreta no cliente, permitindo forja de licenças. Ref design §2.
+
+3. **`LicensePayload v:1` inclui `kid?: string`** (key id) desde a primeira versão, para permitir rotação de chave sem migração dolorosa. Documentado na story 18.1, não só no runbook.
+
+4. **Storage:** `~/.nativesoul/license.json` (modo `0600`, padrão de `workspace.ts`), **não** no SQLite — a licença é fato global da instalação, não do projeto, e evita migration de schema. Ref design §3.
+
+5. **Gate único:** `packages/core/src/entitlements.ts` expõe `loadEntitlements`/`hasFeature`/`requireFeature` em typed-result (nunca lança exceção solta; retorna `{ ok:false, reason:'REQUIRES_PRO', upgrade_url, message }`). Licença inválida/expirada/corrompida **sempre degrada para Free, nunca trava o produto** (graceful degradation, igual a `isCodeIntelAvailable()`). Ref design §4.
+
+6. **Três pontos de enforcement:** (a) guards de comando no CLI; (b) `gatedTool()` wrapper no MCP server (deny tipado, never fake success); (c) branch interna no recall (`maxMode: 'fts' | 'hybrid'` — Free usa FTS, que é core e nunca desligado; Pro ganha o re-ranking). Aditivo, não subtrativo. Ref design §5.
+
+7. **Anti-pirataria pragmática:** Ed25519 impede geração casual de chaves (99% do risco real). **Sem DRM, ofuscação, fingerprint ou validação online** — contradiriam a marca de confiança e não detêm o pirata determinado. Ref design §9.
+
+## Consequences
+
+- **Pré-requisito de receita.** Sem esta camada, não há como cobrar — hoje o Pro roda grátis. Desbloqueia a Onda 0.
+- **Local-first preservado.** A verificação é matemática e local; nenhum servidor é contatado em runtime nem na ativação. O único componente com servidor (emissor) é tratado no [ADR-040](ADR-040-proprietary-free-to-install-distribution.md) e no runbook `monetization-issuer-runbook.md`, e só EMITE licença — nunca é runtime.
+- **Guardrail "never cripple free" garantido por construção.** Como `FeatureId` é allowlist fechada e o core não tem `FeatureId`, nenhum PR consegue gatear o core sem adicionar a feature a `PRO_FEATURES` (rejeitável em review). Reforçado por teste de invariante (story 18.3).
+- **Stories afetadas:** EPIC-018 (18.1 domain model com `kid`; 18.2 verify/store/keygen; 18.3 gate; 18.4 activation; 18.5 enforcement; 18.6 issuer).
+- **Risco de segurança a endurecer no emissor:** anti-replay/idempotência do webhook — tratado no runbook e na story 18.6 (auditoria de segurança H2).
+
+## References
+- [`docs/architecture/entitlements-free-pro-design-v1.md`](../architecture/entitlements-free-pro-design-v1.md) §1-11 (spec de implementação)
+- [ADR-040: Proprietary Free-to-Install Distribution](ADR-040-proprietary-free-to-install-distribution.md)
+- [`docs/architecture/feature-registry.yaml`](../architecture/feature-registry.yaml) (fonte de verdade marketing↔código)
+- `docs/stories/epics/EPIC-018-monetization-entitlements.md`
+- ADR-005 (privacy/export/supply-chain) — coerência local-first

package/docs/adr/ADR-040-proprietary-free-to-install-distribution.md

@@ -0,0 +1,52 @@
+# ADR-040: Proprietary Free-to-Install Distribution
+
+## Status
+**SUPERSEDED (2026-06-30) by [ADR-045](ADR-045-paid-only-closed-distribution.md)** — the model flipped from *free-to-install, source-available* to **paid-only, closed (private repo + minified npm), $29, Dodo-managed licensing**. The PRD Q-008 resolution (proprietary, not OSS) still holds; only the *free-to-install + source-available* mechanics are superseded.
+
+~~Accepted (2026-06-26) — supersedes PRD Q-008~~
+
+## Context
+
+O PRD (`nativesoul-prd-v1.0.md`, Q-008) deixou em aberto: "core open source vs enterprise/comercial". A sales page e o brief de marketing chegaram a apoiar confiança em "open source / read the source / build-in-public". Na prática:
+
+- O repositório é **privado** (`isPrivate: true`); o `package.json` tem `"private": true`; **não existia arquivo LICENSE** (criado depois nesta spec pass do EPIC-018 — `LICENSE` + `docs/legal/EULA.md`); o pacote npm não foi publicado.
+- O selo "Open source" era, portanto, **falso hoje** (auditoria §12.4, honesty-risk H1).
+- Os concorrentes diretos (AgentMemory, CMEM) são Apache-2.0 — competir como "open source pela metade" é incoerente.
+
+O fundador decidiu: **produto proprietário, gratuito para instalar, não open source.** Este ADR formaliza o modelo de distribuição, preço e o reposicionamento de confiança que isso exige.
+
+## Decision
+
+**Proprietário free-to-install + Pro pago, source-available, não OSS.**
+
+1. **Distribuição npm.** Publicar o pacote (`dist/` transpilado) no registry público; remover `"private": true`; `"license": "UNLICENSED"` no `package.json` apontando para o EULA. **Não minificar/ofuscar agressivamente** nesta fase — o JS legível preserva inspecionabilidade e custa nada. Compilar para binário (Node SEA / `bun --compile`) fica para a **Onda 2**, não é bloqueador de launch.
+
+2. **Licenciamento.** `LICENSE` na raiz (texto curto) apontando para [`docs/legal/EULA.md`](../legal/EULA.md): uso **gratuito** do core local; tier **Pro** via licença paga; **sem direito de fork/redistribuição**. Source-available ≠ open source: o código é legível, mas não licenciado para redistribuição.
+
+3. **Preço Pro = perpetual fallback** (não lifetime puro). $47 = produto + **1 ano de updates**; após, o usuário mantém o último build para sempre e paga upgrade (~$27-47) na próxima major. Modelo validado de Sublime Text / TablePlus. Resolve a ausência de MRR sem virar assinatura. Custo marginal por usuário ≈ zero (local-first/offline), o que torna o modelo seguro. A linguagem de copy correspondente é governada pelo `feature-registry.yaml` (`pricing_perpetual_fallback`).
+
+4. **Reposicionamento de confiança** (substitui o pilar "leia a fonte", que cai com o código fechado):
+
+| Removido | Substituto |
+|---|---|
+| "Open source" / "read the source" | "Verify with one command" (`doctor`, `cat SOUL.md`, `ls ~/.nativesoul/`, audit log) |
+| Build-in-public (repo público) | Source-available npm + EULA |
+| Selo "Open source" | "No telemetry — verificável com seu próprio network inspector" |
+
+A prova de honestidade migra de "ler o código" (que quase ninguém faz) para **comportamento verificável** (que qualquer dev confirma com 5 comandos e um network monitor) — mais forte para a objeção real de privacidade. Modelo de mercado: Raycast, Warp, TablePlus (free-but-closed, vendem confiança via comportamento + trust center).
+
+## Consequences
+
+- **Resolve PRD Q-008** → marcado como decidido (proprietário). PRD atualizado.
+- **Sales page / brief:** remover badge "Open source", "read the source", build-in-public; pricing passa a perpetual fallback. Governado pelo `feature-registry.yaml` e refletido no brief in-project (`docs/marketing/nativesoul-marketing-brief-v1.md`). A sales page externa (`rmbc-v1.md`, equipe de copy) consome o registry.
+- **Pré-requisitos de `npm publish`:** LICENSE + EULA presentes; `"private": true` removido. Tratado na story 18.9 (handoff @devops — push/publish é exclusivo de @devops).
+- **Revisão legal recomendada** (@legal-chief) do EULA antes de venda global — não opcional.
+- **Risco residual:** parte do público dev valoriza OSS. Mitigação: liderar com o que os concorrentes abertos NÃO têm (identidade/SOUL, no-daemon, zero cópia de credencial) + free uncapped + refund 30 dias reduzem o risco percebido a quase zero.
+
+## References
+- [`docs/architecture/entitlements-free-pro-design-v1.md`](../architecture/entitlements-free-pro-design-v1.md) §4 (impacto "free mas não open source"), §9 (anti-pirataria)
+- [ADR-039: Entitlements & Offline Licensing](ADR-039-entitlements-offline-licensing.md)
+- [`docs/architecture/feature-registry.yaml`](../architecture/feature-registry.yaml)
+- `docs/legal/EULA.md`, `LICENSE`
+- `nativesoul-prd-v1.0.md` Q-008 (superseded por este ADR)
+- Pesquisa de mercado (Raycast/Warp/TablePlus/Sublime) — `docs/architecture/project-overview-v1.md` §4

package/docs/adr/ADR-041-project-identity-and-lightweight-registry.md

@@ -0,0 +1,35 @@
+# ADR-041: Project Identity & Lightweight Registry
+
+## Status
+Accepted — for EPIC-019 (Onda 1, project management)
+
+## Context
+
+O NativeSoul escopa memória, commitments, runs e sessions por `project_id`, **derivado on-the-fly** do diretório de trabalho (`resolveProjectIdFromCwd`: alias → git-remote → git-root → path). Não existe tabela `projects` nem comando `project`. Isso é zero-config e local-first, mas impede o usuário de **enumerar, renomear, fixar ou limpar** projetos, e o id por-path **orfana memórias** se a pasta for movida (repos sem remote git).
+
+Precisamos habilitar gestão de projetos **sem** sacrificar o local-first nem a derivação zero-config. Design técnico completo: [`docs/architecture/project-management-design-v1.md`](../architecture/project-management-design-v1.md) (Aria @architect + Dara @data-engineer).
+
+## Decision
+
+1. **Registry como projeção lazy, não como autoridade.** Introduzir tabela `projects` (migração 5), populada por upsert lazy no write-boundary do bootstrap e backfill retroativo dos `scope_project` distintos. **A derivação continua a fonte da verdade do id**; o registry é um índice para enumerar/renomear/lifecycle. DB sem `projects` = comportamento idêntico ao atual (graceful degradation). Sem FK física das 5 tabelas para `projects`.
+
+2. **Path-stability via marker `.nativesoul/project`.** Nova precedência `alias → marker → git-remote → git-root → path`. Auto-criado **apenas** quando a fonte é `git-root`/`path` (o caso frágil); repos com remote não geram marker. O id deixa de depender do caminho.
+
+3. **`rename` é cosmético** (só `projects.display_name`). **Cascade de `scope_project` é proibido** — quebraria o `hash` da memória, exigiria transação multi-tabela e criaria divergência permanente derivação↔armazenamento. Mudança de id real = `alias`, com gap de continuidade documentado em `project show`.
+
+4. **CLI-first; sem MCP na v1.** Surface `nativesoul project list/show/rename/pin/alias/forget`. `alias add/remove` é o primeiro escritor de `config.yaml` `project.aliases`. Tools `life_project_*` ficam como carry-forward read-only.
+
+5. **Produto único licenciado.** Project management é a fundação de continuidade (custo marginal zero) e não tem gate por feature. Sob ADR-045, ele fica disponível quando o boot gate do produto está licenciado.
+
+## Consequences
+
+- **Escopo correto: 5 tabelas** (memories, semantic_memory_index, commitments, runs, sessions). `schedules` é host-only (sem `project_id`) → fora de cascade/forget. Migração 5 também adiciona o índice faltante `idx_memories_project_status`.
+- **Stories:** EPIC-019 (19.1 registry+backfill, 19.2 list/show, 19.3 marker/path-stability, 19.4 rename/alias+config-writer, 19.5 forget lifecycle).
+- **Risco concentrado em 19.3** (altera a precedência da derivação em produção) → gate de QA reforçado; regressão orfana memórias silenciosamente.
+- **Carry-forward:** `project merge` (re-unificação com re-hash), `life_project_*` read-only, sync cross-device do registry.
+- **Backward-compat total:** toda a epic é aditiva.
+
+## References
+- [`docs/architecture/project-management-design-v1.md`](../architecture/project-management-design-v1.md)
+- `packages/core/src/project.ts` (derivação), `packages/db/src/schema.ts` (migração)
+- `docs/stories/epics/EPIC-019-project-management.md`