nativesoul 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to NativeSoul are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versioning and release policy: [ADR-043](docs/adr/ADR-043-versioning-and-release-policy.md).
+
+Each release lists product changes so a buyer can verify which features a given
+major delivers (the "verify, don't trust" pillar). NativeSoul is a single paid
+product after ADR-045; there is no Free/Pro split.
+
+## [Unreleased]
+
+### Product
+- _Nothing yet._
+
+## [0.1.0] — 2026-06-23
+
+Initial pre-1.0 (`@beta`) baseline. Local-first continuity layer for coding
+agents: CLI (`nativesoul`) + MCP stdio server (`nativesoul-mcp`), workspace at
+`~/.nativesoul/`. Zero runtime dependencies (`dependencies: {}`); no daemon, no
+telemetry, never copies credentials.
+
+### Product
+- Identity bootstrap, project-scoped memory (recall/propose/promote), policy
+  evaluation, heartbeat, capability scan, host install/detection across the
+  supported hosts. (Epics 0–17, all Done — see `docs/stories/INDEX.md`.)
+- Paid-only Dodo licensing: `licensed | unlicensed` boot gate, license
+  activation/status/deactivation, once-a-day validation cache, offline grace,
+  update entitlement metadata, and marketing-audit guardrails. (EPIC-018 Done.)
+- Project management CLI: registry/backfill, `project list/show`, path-stability
+  marker, rename/alias, archive/reactivate, and guarded forget lifecycle.
+  (EPIC-019 Done.)
+- Approval gate: approval domain, CLI, MCP tools, standing-order auto-approval,
+  and audit events while preserving side-effect-free policy evaluation.
+  (EPIC-020 Done.)
+- Closed npm distribution remains in launch prep under EPIC-024; this beta
+  package uses minified runtime entrypoints and release audit/provenance gates.
+
+<!-- Version links omitted intentionally: NativeSoul is proprietary and closed
+     (ADR-045), not a public OSS repo — compare/release URLs would not resolve for
+     installers. Versions are tagged in the private repo for the team. -->

package/LICENSE

@@ -0,0 +1,19 @@
+NativeSoul — Proprietary License (Closed, Paid)
+
+Copyright (c) 2026 Fillipe Cordeiro / InnoDev. All rights reserved.
+
+This software is proprietary, closed-source, and paid. It is NOT open source,
+NOT source-available, and has NO free tier.
+
+- Use requires a valid paid license ($29 one-time; 1 year of updates; perpetual
+  build), activated with `nativesoul license activate <key>`, subject to the
+  End User License Agreement. 30-day money-back guarantee.
+- You may NOT fork, redistribute, sublicense, sell, decompile, reverse-engineer,
+  or create derivative works for distribution.
+- You may NOT circumvent or tamper with the licensing mechanism, nor share keys.
+
+Full terms: see docs/legal/EULA.md
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. See EULA.
+
+For licensing questions: <contact pending — fill before npm publish>

package/README.md

@@ -0,0 +1,384 @@
+<h1 align="center">NativeSoul</h1>
+
+<p align="center"><strong>A coding agent that's actually yours.</strong></p>
+
+<p align="center">Shape how it talks and works once, and the same agent shows up in every tool you open — with a durable memory of your projects, an honest inventory of what actually works, and follow-ups you can trust. Local-first. One prompt to install.</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> &nbsp;·&nbsp;
+  <a href="#first-run-walkthrough">First Run</a> &nbsp;·&nbsp;
+  <a href="#command-reference">Commands</a> &nbsp;·&nbsp;
+  <a href="#mcp-tools">MCP Tools</a> &nbsp;·&nbsp;
+  <a href="#pricing">Pricing</a> &nbsp;·&nbsp;
+  <a href="#dont-trust-us-check-us">Verify It</a> &nbsp;·&nbsp;
+  <a href="https://native-soul.mintlify.site/">Help Center</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/local--first-on%20your%20machine-0d9488" alt="Local-first">
+  <img src="https://img.shields.io/badge/no%20daemon-no%20background%20process-475569" alt="No daemon">
+  <img src="https://img.shields.io/badge/no%20usage%20telemetry-verifiable-475569" alt="No usage telemetry">
+  <img src="https://img.shields.io/badge/credentials-never%20copied-475569" alt="Never copies credentials">
+  <img src="https://img.shields.io/badge/node-%3E%3D22.17-339933?logo=node.js&logoColor=white" alt="Node >= 22.17">
+  <img src="https://img.shields.io/badge/license-proprietary%20(closed%2C%20paid)-8957E5" alt="Proprietary, closed, paid">
+</p>
+
+---
+
+NativeSoul is a **local-first continuity layer for coding agents**. If you run more than one coding assistant — Claude Code, Codex, Gemini CLI, Grok, Antigravity — you start over every session: re-pasting context, re-explaining decisions, and trusting integrations that quietly break. NativeSoul installs, with **one prompt**, a layer that gives your agent an **identity you shape**, a **searchable memory of your work**, **safe follow-ups**, and an **honest capability inventory** — and carries all of it across every host you use.
+
+It runs entirely on your machine (`~/.nativesoul/`), keeps **no background process**, **never copies your credentials**, and sends **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, written to the audit log. You can read your own files, run one health check, and remove it cleanly at any time. It doesn't fake it — a capability only reads "ready" after it passes a real auth and health check.
+
+> **Proprietary, closed-source, paid — not open source, no free tier.** NativeSoul is **$29 one-time** (1 year of updates, perpetual build, 30-day money-back). You may not fork, redistribute, decompile, or create derivative works. See [License](#license).
+
+<p align="center">
+  <img src="docs/assets/nativesoul-architecture.svg" alt="NativeSoul architecture — one identity, native across every host" width="100%">
+</p>
+
+---
+
+## Every session, you start over. It doesn't have to be that way.
+
+| Today | With NativeSoul |
+| --- | --- |
+| You paste the same context again, every session | It already knows who you are and how you work |
+| The agent forgets what you decided an hour ago | Your decisions stick, session after session |
+| Switch tools and you start from zero | The same agent follows you into every tool |
+| It says an integration is connected, then it breaks | It tells you the truth about what actually works |
+| You hold it all together by hand | You go back to building |
+
+---
+
+## Requirements
+
+- **Node.js 22.17+**
+- An npm-compatible package manager
+- One or more supported coding hosts (see [Host Readiness](#host-readiness))
+
+---
+
+## Quick Start
+
+> **Note on distribution.** NativeSoul is a proprietary, **closed** package (minified `dist/`, private repo) published to npm as a **paid** product. The public `npm publish` is pending, so today you install via the **host prompt** (recommended) or a **local tarball** (for testing). `npm install -g nativesoul` will be the path once published — usage requires an activated license (`nativesoul license activate <key>`).
+
+### Option A — Host-first install (recommended)
+
+Paste **one short prompt** into your coding host. The host reads [`llm-install.txt`](llm-install.txt) and runs the full install + onboarding for you.
+
+- Prompt: [`docs/prompts/install-nativesoul-v1.md`](docs/prompts/install-nativesoul-v1.md)
+
+```text
+Install NativeSoul on this machine.
+
+Read and follow llm-install.txt completely before doing anything:
+- repo root: ./llm-install.txt
+- or after npm install: $(npm root -g)/nativesoul/llm-install.txt
+
+Execute Phase 1 (install) and Phase 2 (onboarding) exactly as defined there.
+Use the host question UI to ask if I want onboarding — if I say yes, continue in this same session.
+Do not invent steps outside llm-install.txt.
+```
+
+The installer writes NativeSoul to **global host surfaces** (`~/.claude`, `~/.codex`, `~/.gemini`, Grok, Antigravity, and equivalent plugin/config locations) via `nativesoul install --all-hosts --apply`, so continuity works across every project. It **always dry-runs first** and waits for your approval before mutating any real config. After install it asks if you want onboarding — answer the ~5 questions and your agent is shaped.
+
+### Option B — Local install (CLI, for testing)
+
+```sh
+npm install
+npm run build
+npm run package:local
+
+PREFIX="$(pwd)/.artifacts/local-prefix"
+HOME_DIR="$(pwd)/.artifacts/local-home"
+TARBALL="$(ls .artifacts/package/nativesoul-*.tgz | tail -n 1)"
+
+# verify checksum, then install into a local prefix
+(cd .artifacts/package && shasum -a 256 -c "$(basename "$TARBALL").sha256")
+npm install -g --prefix "$PREFIX" "$TARBALL"
+
+"$PREFIX/bin/nativesoul" init --home "$HOME_DIR"
+"$PREFIX/bin/nativesoul" status --home "$HOME_DIR" --json
+```
+
+> **Test against a temp host root first.** Use `install --target-root "$(mktemp -d)"` to exercise the Claude/Codex/Gemini/Grok/Antigravity integration files in a throwaway folder before touching your real host config. Dry-run (no `--apply`) → review the JSON report → then `--apply`.
+
+---
+
+## First Run Walkthrough
+
+Real output from `nativesoul` (Node 22, fresh `--home`):
+
+**1. Initialize the local workspace**
+
+```console
+$ nativesoul init --home ~/.nativesoul
+NativeSoul initialized at <nativesoul-home>
+```
+
+**2. Check status (everything is local)**
+
+```console
+$ nativesoul status --json
+{
+  "home": "<nativesoul-home>",
+  "initialized": true,
+  "database": "<nativesoul-home>/state/nativesoul.sqlite",
+  "migrations": 4,
+  "memories": 0,
+  "events": 1,
+  "capabilities": 0,
+  "ledger": { "hosts": 0, "sessions": 0, "commitments": 0, "schedules": 0, "leases": 0, "runs": 0 }
+}
+```
+
+**3. One-command health check**
+
+```console
+$ nativesoul doctor
+NativeSoul healthy at <nativesoul-home>
+```
+
+**4. Remember a decision, then find it**
+
+```console
+$ nativesoul memory add --text "Use Node-first for the MVP." --project demo
+Memory added: mem_c7470a4c-f174-4043-a33c-669622ca4f10
+
+$ nativesoul memory search "Node-first" --project demo
+1 memory found
+```
+
+**5. Everything it did is auditable**
+
+```console
+$ nativesoul audit list --limit 3
+3 audit event(s)
+```
+
+> Add `--json` to any command for structured output. Every command supports `--home <path>` to point at an alternate workspace.
+
+---
+
+## Workspace
+
+`nativesoul init` seeds an OpenClaw-inspired workspace under `~/.nativesoul/` (override with `--home`):
+
+| File / Dir | Purpose |
+| --- | --- |
+| `SOUL.md` | Voice and boundaries — **protected**; propose changes only |
+| `IDENTITY.md` | Name, creature, vibe, emoji, mission |
+| `USER.md` | Your preferences and collaboration style |
+| `AGENTS.md` | Operating instructions injected into every host session |
+| `MEMORY.md` | Curated long-term memory (SQLite FTS5 remains the searchable source) |
+| `HEARTBEAT.md` | Heartbeat / follow-up state |
+| `POLICY.md` | Risk policy — **protected**; propose changes only |
+| `TOOLS.md` | Capability/tool notes |
+| `BOOTSTRAP.md` | First-run onboarding ritual — delete when done |
+| `memory/daily/YYYY-MM-DD.md` | Daily working notes |
+| `standing-orders/*.yaml` | Persistent authority scaffolds |
+| `state/nativesoul.sqlite` | Memory (FTS5), capabilities, leases, schedules, runs |
+| `logs/audit.jsonl` | Append-only audit log (`0600`) |
+| `generated/`, `backups/`, `proposals/` | Dashboard output, reversible snapshots, pending proposals |
+
+Guide: [`docs/framework/workspace-templates.md`](docs/framework/workspace-templates.md)
+
+---
+
+## Command Reference
+
+`nativesoul <command> [--home <path>] [--json]` — full help: `nativesoul` (no args) prints every command.
+
+### Core
+
+```sh
+nativesoul init                                   # seed the local workspace
+nativesoul status --json                          # local state snapshot
+nativesoul doctor                                 # one-command health check
+nativesoul doctor --deep --all-hosts --json       # per-host deep diagnostics
+nativesoul bootstrap --host claude --cwd "$PWD"    # resume identity + memory for a session
+```
+
+### Install / uninstall (reversible)
+
+```sh
+nativesoul install --all-hosts --json             # dry-run: review the plan
+nativesoul install --all-hosts --apply --json     # apply: managed blocks + MCP + plugins
+nativesoul uninstall --all-hosts --apply --json   # roll back host integration
+```
+
+`install --apply` registers MCP servers, inserts **reversible managed blocks**, enables host plugins from `plugins/*-nativesoul/` (SessionStart bootstrap hooks), and deploys heartbeat skills. It never runs a daemon, reloads hosts, copies credentials, calls external services, or auto-creates native schedulers without operator setup.
+
+### Memory
+
+```sh
+nativesoul memory add --text "..." --project demo
+nativesoul memory propose --text "..." --project demo    # candidate (promoted on review)
+nativesoul memory promote <id>                           # promote a candidate
+nativesoul memory search "<query>" --project demo
+nativesoul memory reflect --project demo --apply          # dedupe + consolidation pass
+nativesoul memory export --project demo --json
+```
+
+### Follow-ups (idempotent heartbeat)
+
+```sh
+nativesoul commitments create --summary "Follow up on X." --project demo
+nativesoul commitments list --project demo --json
+nativesoul heartbeat claim --slot demo --project demo     # lease: runs once, even with 2 agents
+nativesoul heartbeat complete --slot demo --project demo
+nativesoul schedule reconcile --host codex --mode leader  # align with the host's native scheduler
+```
+
+### Capabilities & policy (honest inventory)
+
+```sh
+nativesoul capabilities refresh --host all --json
+nativesoul capabilities list --host claude --ready-only --json
+nativesoul policy evaluate --action deploy --class external_write --json
+nativesoul audit list --json
+```
+
+### Operator features (M7+)
+
+```sh
+nativesoul dashboard viewer --json                # generate a local read-only HTML panel
+nativesoul import openclaw --source <path> --dry-run --json
+nativesoul import native --host codex --source <path> --dry-run --json
+nativesoul policy packs list --json
+nativesoul onboard activation status --json
+```
+
+> **Hybrid recall is lexical today.** It blends FTS5 full-text with **local token-similarity ranking** — not real vector embeddings. We say "hybrid recall," never "semantic." See [`docs/architecture/entitlements-free-pro-design-v1.md`](docs/architecture/entitlements-free-pro-design-v1.md).
+
+---
+
+## MCP Tools
+
+NativeSoul ships an MCP **stdio** server (`nativesoul-mcp`) so any MCP-capable host can call these tools. It starts on demand — there is no long-running process.
+
+| Tool | Purpose |
+| --- | --- |
+| `life_bootstrap` | Resume identity, policy, capabilities, and memory at session start |
+| `life_recall` | Search durable memory (FTS / hybrid) |
+| `life_remember_propose` | Propose a new memory (promoted on review) |
+| `life_memory_promote` / `_reject` / `_forget` / `_expire` | Memory lifecycle |
+| `life_commitment_create` / `_complete` | Long-running follow-ups |
+| `life_heartbeat_claim` / `_complete` | Idempotent lease — one host executes per slot |
+| `life_capability_search` / `_status` | Honest capability inventory |
+| `life_policy_evaluate` | Evaluate an action against the risk policy |
+| `life_status` | Local system status |
+| `life_onboarding_status` / `life_onboard_apply` / `life_onboard_complete` | Onboarding flow |
+
+Run the server directly:
+
+```sh
+printf '{"jsonrpc":"2.0","id":1,"method":"life_status"}\n' | nativesoul-mcp --home ~/.nativesoul
+```
+
+---
+
+## Pricing
+
+NativeSoul is a **single paid product — no free tier**: **$29 one-time**, 1 year of updates, perpetual build, **30-day money-back**, no subscription.
+
+| Everything is in the one product | Terms |
+| --- | --- |
+| Identity across every host | **$29 one-time** |
+| Searchable local memory (FTS5) | 1 year of updates, then keep the build forever (perpetual fallback) |
+| Honest capability inventory + idempotent follow-ups | New major = optional paid upgrade |
+| Hybrid recall ranking (local), read-only dashboard, importers, policy packs | **30-day money-back**, no questions |
+| Reversible install/uninstall, `doctor`, audit log | No subscription |
+
+> **Honesty note.** The **licensing/boot gate is not shipped yet** — it is specced in [`EPIC-018`](docs/stories/epics/EPIC-018-monetization-entitlements.md) ([ADR-045](docs/adr/ADR-045-paid-only-closed-distribution.md), authoritative). Until it lands, the product runs ungated. Pricing is **perpetual fallback** ($29 + 1 year of updates), not "lifetime." Licensing is **Dodo-managed** — the product checks the license **once a day** (sending only the key, logged to the audit log) with an **offline grace window**; it is **not** "zero network." The single source of truth for what may be claimed is [`docs/architecture/feature-registry.yaml`](docs/architecture/feature-registry.yaml).
+
+---
+
+## Host Readiness
+
+Readiness is **capability-level, not absolute**. NativeSoul reports honest states — `ready`, `ready with fallback`, `degraded` — and never claims `full native capability` without evidence.
+
+| Host family / surface | Status (ADR-031) |
+| --- | --- |
+| Claude Code | `ready` (native hook) |
+| Claude Desktop | `ready` (MCP surface) |
+| Codex CLI/App | `ready` (native hook) |
+| Gemini CLI | `ready with fallback` (scheduler blocked by host) |
+| Grok Build | `ready with fallback` (scheduler blocked by host) |
+| Antigravity | `ready with fallback` |
+
+**5 host families, 6 install surfaces. Zero are `full_native` today** — heartbeat runs on each host's official scheduler with honest fallback; NativeSoul never installs a cron or daemon. Verify before making any public full-native claim:
+
+```sh
+nativesoul doctor --deep --all-hosts --require-full-native --json   # exits non-zero unless every host proves native scheduler + non-degraded inventory
+```
+
+Matrix and definitions: [`docs/adr/ADR-031-host-parity-matrix-v2.md`](docs/adr/ADR-031-host-parity-matrix-v2.md).
+
+---
+
+## Don't trust us. Check us.
+
+The trust model is **verifiable behavior**, not a license badge. Run these yourself:
+
+| You're worried that… | Run this | And you'll see |
+| --- | --- | --- |
+| Your code is leaving your machine | `ls ~/.nativesoul/` | All local files. No cloud, no account. |
+| The "personality" is just hype | `cat ~/.nativesoul/SOUL.md` | Plain text you wrote. Edit it. Delete it. |
+| It only claims to work | `nativesoul doctor --deep --all-hosts` | Real status, and what's degraded. |
+| It'll wreck your config | `nativesoul uninstall --all-hosts --apply` | Your setup comes back; managed blocks are reversible. |
+| It did something behind your back | `nativesoul audit list --json` | Every action it took, written down. |
+| It spies on me | run it behind a network monitor | No usage telemetry; your code/memory never leave. The only call is a once-a-day license check sending just the key — logged in `audit list`. |
+
+---
+
+## Build, Test & Release
+
+```sh
+npm install
+npm run lint
+npm run typecheck
+npm run build
+npm test            # build + non-e2e suite
+npm run test:e2e
+```
+
+Release gates (no real publish, tokens, or signing keys):
+
+```sh
+npm run package:local            # local tarball + provenance manifest
+npm run package:smoke            # install + smoke the tarball
+npm run release:security:audit   # lint + typecheck + policy + tests + build + secret/path scan
+npm run release:provenance:dry-run
+```
+
+`npm publish` remains blocked until package visibility and npm authentication are explicitly approved (handled by @devops; see [`docs/guides/npm-beta-release-rollback.md`](docs/guides/npm-beta-release-rollback.md)). The security audit does not read npm tokens, sign with real keys, or claim public SLSA/registry attestation.
+
+---
+
+## Documentation
+
+**Help center (customers):** [native-soul.mintlify.site](https://native-soul.mintlify.site/) — published from [`docs/help/`](docs/help/) via Mintlify. Install, hosts, commands, FAQ, pricing & licensing.
+
+**Internal map (contributors):**
+
+| Area | Doc |
+| --- | --- |
+| Project overview (business + architecture) | [`docs/architecture/project-overview-v1.md`](docs/architecture/project-overview-v1.md) |
+| Legacy entitlements design (superseded by ADR-045) | [`docs/architecture/entitlements-free-pro-design-v1.md`](docs/architecture/entitlements-free-pro-design-v1.md) |
+| Feature registry (marketing ↔ code source of truth) | [`docs/architecture/feature-registry.yaml`](docs/architecture/feature-registry.yaml) |
+| Host parity matrix | [`docs/adr/ADR-031-host-parity-matrix-v2.md`](docs/adr/ADR-031-host-parity-matrix-v2.md) |
+| Monetization (license issuer) runbook | [`docs/guides/monetization-issuer-runbook.md`](docs/guides/monetization-issuer-runbook.md) |
+| Operator: native pulse / scheduler | [`docs/guides/native-pulse-operator-guide.md`](docs/guides/native-pulse-operator-guide.md) |
+| Workspace templates | [`docs/framework/workspace-templates.md`](docs/framework/workspace-templates.md) |
+| Epics & stories index | [`docs/stories/INDEX.md`](docs/stories/INDEX.md) |
+| Architecture Decision Records | [`docs/adr/`](docs/adr/) |
+
+---
+
+## License
+
+**Proprietary, closed-source, paid — not open source, no free tier.** Use requires a paid license (**$29 one-time**, 1 year of updates, perpetual build, 30-day money-back). You may **not** fork, redistribute, decompile, reverse-engineer, or create derivative works for distribution.
+
+See [`LICENSE`](LICENSE) and the full [`docs/legal/EULA.md`](docs/legal/EULA.md). Licensing is **Dodo-managed** ([ADR-045](docs/adr/ADR-045-paid-only-closed-distribution.md)): a once-a-day license check (sends only the key, logged to the audit log) with an offline grace window. No usage telemetry; your code and memory never leave your machine.
+
+<p align="center"><sub>NativeSoul — the native soul for your coding agents. Local. Honest. Yours.</sub></p>