nativesoul 0.1.0

package/docs/adr/ADR-001-node-first-runtime.md

@@ -0,0 +1,20 @@
+# ADR-001: Node-first runtime for MVP
+
+## Status
+
+Accepted for MVP.
+
+## Context
+
+The PRD leaves Q-002 open and recommends a single binary. The product owner compared this with OpenClaw and chose a Node-first implementation for speed and host ecosystem fit.
+
+## Decision
+
+NativeSoul M0/M1 uses TypeScript on Node.js 22.17+ with npm-compatible distribution. Native binary packaging is a pre-beta decision, not an M1 blocker.
+
+## Consequences
+
+- The MVP can ship quickly through `npm install -g nativesoul`.
+- The core must avoid long-running daemons and hidden schedulers.
+- CI must cover macOS, Linux, and Windows before beta.
+- A future ADR must decide whether to keep a Node runtime requirement or bundle a platform binary.

package/docs/adr/ADR-002-workspace-and-state.md

@@ -0,0 +1,16 @@
+# ADR-002: Canonical workspace and state
+
+## Status
+
+Accepted for M0.
+
+## Decision
+
+NativeSoul uses `~/.nativesoul` by default, overridable with `NATIVESOUL_HOME` or `--home`. Human-readable files are Markdown/YAML. Transactional state lives in SQLite under `state/nativesoul.sqlite`.
+
+## Rules
+
+- Initialization is idempotent.
+- Existing human files are never overwritten.
+- Managed writes happen under the NativeSoul home only.
+- `SOUL.md` and `POLICY.md` are proposal-only for automated changes.

package/docs/adr/ADR-003-schemas-and-adapter-sdk.md

@@ -0,0 +1,15 @@
+# ADR-003: Schemas and adapter SDK v1
+
+## Status
+
+Accepted for M0.
+
+## Decision
+
+Public records use versioned JSON schemas in `schemas/`. Host adapters implement the v1 contract in `packages/adapter-sdk`.
+
+## Rules
+
+- Unsupported host operations return a typed result, never fake success.
+- Readiness keeps Installed, Enabled, Active, Authenticated, Healthy, Allowed, and Ready as separate states.
+- Metadata from manifests, skills, plugins, MCPs, and connectors is untrusted input.

package/docs/adr/ADR-004-policy-leases-and-heartbeat.md

@@ -0,0 +1,15 @@
+# ADR-004: Policy, leases, and heartbeat boundaries
+
+## Status
+
+Accepted for M0.
+
+## Decision
+
+M0 defines policy and lease contracts but does not install schedules. Heartbeat execution remains read-only by default until standing orders and scheduler adapters are implemented.
+
+## Rules
+
+- External writes and destructive actions require approval unless covered by a standing order.
+- Lease records use idempotency keys to prevent duplicate work.
+- Grok and Gemini standalone get no hidden cron fallback.

package/docs/adr/ADR-005-privacy-export-delete-and-supply-chain.md

@@ -0,0 +1,16 @@
+# ADR-005: Privacy, export/delete, and supply-chain
+
+## Status
+
+Accepted for M0.
+
+## Decision
+
+NativeSoul stores no secrets in memory, audit, registry, fixtures, or exports. Telemetry is off by default. Releases require signed artifacts, checksum/provenance, and rollback before beta.
+
+## Rules
+
+- Redaction runs before persistence.
+- Export/delete must be local and auditable.
+- Installers must backup before managed writes.
+- Beta release requires a packaging ADR and release checklist.

package/docs/adr/ADR-006-adapter-preview-before-install.md

@@ -0,0 +1,21 @@
+# ADR-006: Adapter preview before install
+
+## Status
+
+Accepted for M2.1.
+
+## Context
+
+The PRD requires native-first adapters but also requires reversible installation, backups, diff, and no credential copying. The first adapter slice should therefore inspect and diagnose before mutating host configuration.
+
+## Decision
+
+Codex and Claude adapters start with read-only `detect`, `coldScan`, `doctor`, and managed-block preview. `install`, `uninstall`, `reload`, `update`, and `scheduleReconcile` return typed unsupported results until dedicated stories implement safe writes.
+
+Each adapter package keeps `adapter.config.md` with the official host documentation link as the primary reference index (see Story 2.1).
+
+## Consequences
+
+- M2 starts without touching `~/.codex/AGENTS.md`, `~/.claude/CLAUDE.md`, plugins, MCP configs, or schedules.
+- CLI users can inspect what would be installed before any write path exists.
+- Adapter readiness remains honest: preview support is not the same as Ready native integration.

package/docs/adr/ADR-007-managed-block-backup-and-rollback.md

@@ -0,0 +1,16 @@
+# ADR-007: Managed-block backup and rollback
+
+## Status
+
+Accepted for M2.2.
+
+## Decision
+
+Managed-block installation is dry-run by default. Writes require `--apply`, create a local backup snapshot under the NativeSoul home, and are idempotent. Rollback also requires `--apply`.
+
+## Rules
+
+- Only the selected host instruction target may be written.
+- Backups preserve the complete previous file content locally with restrictive file permissions.
+- A missing target is represented in the snapshot and is removed again on rollback.
+- No scheduler, plugin install, MCP registration, credential probing, or external write is part of this story.

package/docs/adr/ADR-008-mcp-registration-manifest-before-write.md

@@ -0,0 +1,16 @@
+# ADR-008: MCP registration manifest before write
+
+## Status
+
+Accepted for M2.3.
+
+## Decision
+
+NativeSoul exposes MCP registration manifests and snippets before any automatic host MCP registration. The manifest is deterministic, local-first, and secret-free. Host config mutation remains a future reversible install story.
+
+## Rules
+
+- `nativesoul-mcp` is the package-mode command.
+- Local development mode may point to `node dist/packages/mcp-server/src/index.js`.
+- Snippets are review artifacts and must not claim active registration.
+- No host config files are modified in this story.

package/docs/adr/ADR-009-local-capability-registry.md

@@ -0,0 +1,16 @@
+# ADR-009: Local capability registry
+
+## Status
+
+Accepted for M2.4.
+
+## Decision
+
+Adapter scan results are persisted locally in SQLite as capability records. Readiness states remain separate and `Ready` is never inferred from mere discovery.
+
+## Rules
+
+- Registry values are sanitized metadata, not executable instructions.
+- No credentials, tokens, OAuth material, or tool arguments are stored.
+- `capabilities refresh` may write local registry state but does not execute native capabilities.
+- Bootstrap injects only ready capabilities.

package/docs/adr/ADR-010-mcp-capability-tools-read-only.md

@@ -0,0 +1,15 @@
+# ADR-010: MCP capability tools are read-only
+
+## Status
+
+Accepted for M2.5.
+
+## Decision
+
+MCP capability tools read the local capability registry only. They do not run adapter refresh, execute native tools, probe authentication, or write host configuration.
+
+## Rules
+
+- `life_capability_search` returns persisted records filtered by query/host/readiness.
+- `life_capability_status` returns one persisted record by UID or an explicit not-found error.
+- `Ready` remains a stored readiness state, not a derived shortcut.

package/docs/adr/ADR-011-local-audit-cli-export.md

@@ -0,0 +1,16 @@
+# ADR-011: Local audit CLI list and export
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul exposes local audit inspection through the CLI before any UI. Audit list/export read persisted SQLite audit events and export to stdout; no daemon, cloud sync, host probing, or host configuration writes are involved.
+
+## Rules
+
+- `audit list` returns persisted audit events in newest-first order with type/result/limit filters.
+- `audit export --format json|jsonl` writes audit events to stdout.
+- Export is auditable by appending an `audit_exported` event after the selected export set is read.
+- Audit payloads must already be redacted before persistence; export does not reintroduce secrets.

package/docs/adr/ADR-012-npm-package-runtime-scope.md

@@ -0,0 +1,16 @@
+# ADR-012: npm package runtime scope
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+The MVP package ships only the compiled runtime, public schemas, and install documentation needed to run the Node-first CLI and MCP stdio server. Source-tree agent framework folders, local IDE integrations, tests, fixtures, and development configuration are excluded from the npm tarball.
+
+## Rules
+
+- Runtime package contents are controlled with `package.json` `files`.
+- The package must not include `.aiox-core`, `.codex`, `.claude`, `.gemini`, `.github`, `.antigravity`, `.env*`, tests, or TypeScript source files.
+- Runtime dependencies must be required by shipped code; unused framework dependencies stay out of `dependencies`.
+- Local install smoke must install the tarball into an isolated npm prefix and run installed binaries.

package/docs/adr/ADR-013-core-domain-ledger-v1.md

@@ -0,0 +1,16 @@
+# ADR-013: Core domain ledger v1
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul will create the PRD P0 domain ledger tables in SQLite before implementing higher-level lifecycle behavior. The ledger is transactional, local-first, and inert until specific services start writing domain records.
+
+## Rules
+
+- Migration v3 owns `hosts`, `sessions`, `memory_edges`, `commitments`, `standing_orders`, `capability_sources`, `capability_experience`, `schedules`, `leases`, and `runs`.
+- Structured fields are stored as JSON text and must remain redacted before persistence.
+- Creating the ledger must not start a scheduler, mutate host configuration, call models, or change human Markdown files.
+- `status --json` reports zero-safe counts so follow-up stories can verify adoption incrementally.

package/docs/adr/ADR-014-memory-lifecycle-v1.md

@@ -0,0 +1,16 @@
+# ADR-014: Memory lifecycle v1
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul memory lifecycle starts with explicit local states: `candidate`, `active`, `rejected`, and `forgotten`. The CLI can propose, promote, reject, forget, and export memories while preserving redaction and auditability.
+
+## Rules
+
+- Candidate memories are persisted and audited but are not returned by active recall.
+- Promotion changes status to `active`; rejection changes status to `rejected`; forgetting changes status to `forgotten`.
+- Export returns non-forgotten memories by default and records a redacted `memory_exported` audit event.
+- Existing `memory add` remains a direct active write for compatibility until policy-based promotion replaces it.

package/docs/adr/ADR-015-policy-standing-orders-v1.md

@@ -0,0 +1,16 @@
+# ADR-015: Policy and standing orders v1
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul provides a deterministic local policy evaluator before implementing autonomous action execution. Standing orders can adjust decisions for named actions, while identity and policy changes remain proposal-only.
+
+## Rules
+
+- Policy evaluation is local, auditable, and side-effect free except for explicit proposal creation.
+- `SOUL.md` and `POLICY.md` are never autoedited by NativeSoul.
+- Destructive actions remain denied in M1 even if a standing order names them.
+- External writes require approval unless a standing order explicitly allows the named action.

package/docs/adr/ADR-016-heartbeat-lease-idempotency-v1.md

@@ -0,0 +1,16 @@
+# ADR-016: Heartbeat lease idempotency v1
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul implements local heartbeat claim and completion primitives before installing or reconciling any native scheduler. A heartbeat slot is keyed by project and slot, so concurrent hosts cannot execute the same useful heartbeat twice.
+
+## Rules
+
+- The core may claim and complete local leases, but must not install schedules, cron jobs, daemons, or host automations in M1.
+- The idempotency key is derived from `heartbeat:<project>:<slot>`, independent of host.
+- A duplicate claim for an active or completed slot returns `HEARTBEAT_OK` and does not create a new lease.
+- `life_heartbeat_claim` and `life_heartbeat_complete` are local-write MCP tools only; they do not perform external writes.

package/docs/adr/ADR-017-reversible-mcp-registration-install.md

@@ -0,0 +1,17 @@
+# ADR-017: Reversible MCP registration install
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul may write an MCP registration entry only through an explicit, reversible install command. The operation is dry-run by default, creates a backup snapshot before applying, preserves unrelated config keys, and can roll back from the snapshot.
+
+## Rules
+
+- `nativesoul mcp install` is dry-run by default.
+- `--apply` writes only the selected MCP registration target.
+- Tests and package smoke use `--target` paths outside real host configs.
+- The install writes an `mcpServers.nativesoul` entry using package mode by default.
+- No scheduler, plugin, host reload, daemon, credential probe, or external network call is part of this story.

package/docs/adr/ADR-018-schedule-reconcile-guardrails-v1.md

@@ -0,0 +1,17 @@
+# ADR-018: Schedule reconcile guardrails v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul exposes schedule reconciliation commands before implementing native scheduler creation. The command records desired local state and adapter capability status, but never installs cron, daemons, or undocumented scheduler fallbacks.
+
+## Rules
+
+- `schedule reconcile` is dry-run by default.
+- `--apply` may persist desired state in SQLite.
+- Unsupported native scheduler status is explicit and auditable.
+- `native_id` remains `null` until an adapter creates or verifies an official native schedule.
+- Grok/Gemini-style hidden cron fallback remains forbidden.

package/docs/adr/ADR-019-commitments-lifecycle-v1.md

@@ -0,0 +1,17 @@
+# ADR-019: Commitments lifecycle v1
+
+## Status
+
+Accepted for M1.
+
+## Decision
+
+NativeSoul stores lightweight commitments as local follow-ups with project scope, TTL, deduplication, and explicit completion or dismissal. Commitments are not schedules and do not create native scheduler state.
+
+## Rules
+
+- Commitments are local SQLite records with `project_id`, `summary`, `status`, optional `due_at`, and optional `ttl_expires_at`.
+- Creating a duplicate open commitment for the same project and normalized summary returns the existing record.
+- Expired commitments transition to `expired` during list/status operations.
+- Commitment summaries and sources are redacted before persistence and audit.
+- MCP commitment tools are local-write only and do not perform external actions.

package/docs/adr/ADR-020-mcp-memory-lifecycle-tools.md

@@ -0,0 +1,16 @@
+# ADR-020: MCP memory lifecycle tools
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul exposes memory proposal and promotion through MCP using the same local core services as the CLI. MCP memory writes remain local-only, redacted before persistence, project-scoped, and audited.
+
+## Rules
+
+- `life_remember_propose` creates a candidate memory, never an active memory.
+- `life_memory_promote` promotes an existing candidate by id.
+- Tools support direct JSON-RPC and `tools/call`.
+- No external write, scheduler, host reload, or model call is performed.

package/docs/adr/ADR-021-unified-install-orchestrator-v1.md

@@ -0,0 +1,17 @@
+# ADR-021: Unified install orchestrator v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul provides a CLI-first install orchestrator that composes existing reversible local operations: workspace init, adapter managed blocks, MCP registration, capability refresh, and schedule desired-state reconciliation. The installer is dry-run by default.
+
+## Rules
+
+- `nativesoul install` is dry-run by default and requires `--apply` to write managed host files.
+- The installer only uses existing reversible operations with snapshots.
+- Tests and package smoke use `--target-root` to avoid real host config paths.
+- Schedule reconciliation may persist unsupported desired state, but never creates hidden cron, daemons, or host automations.
+- The installer reports degraded status when any host capability remains unsupported or not ready.

package/docs/adr/ADR-022-unified-uninstall-orchestrator-v1.md

@@ -0,0 +1,20 @@
+# ADR-022: Unified uninstall orchestrator v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul provides a CLI-first uninstall orchestrator that removes only the local integration artifacts written by the current installer: adapter managed blocks and `mcpServers.nativesoul` registrations. The uninstaller is dry-run by default and preserves the NativeSoul home/data directory unless an explicit purge flag and confirmation token are supplied.
+
+## Rules
+
+- `nativesoul uninstall` is dry-run by default and requires `--apply` to write host files.
+- Uninstall removes only NativeSoul managed markers and MCP registration entries.
+- Unrelated host instructions, host config keys, and non-NativeSoul MCP servers must be preserved.
+- Apply operations create backup snapshots before modifying managed host files.
+- Re-running apply must be idempotent and report `noop` actions when NativeSoul artifacts are already absent.
+- NativeSoul home/data is preserved by default.
+- Data purge requires both `--purge-data` and `--confirm-purge-nativesoul-data DELETE_NATIVESOUL_HOME`.
+- No host reload, plugin removal, native scheduler teardown, daemon stop, credential deletion, or external network call is performed.

package/docs/adr/ADR-023-deep-doctor-install-readiness-v1.md

@@ -0,0 +1,18 @@
+# ADR-023: Deep doctor install readiness v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul provides a CLI-first deep doctor that aggregates local workspace health, managed-block presence, MCP registration health, persisted schedule state, persisted capability counts, and native adapter diagnostics when inspecting real host paths.
+
+## Rules
+
+- `nativesoul doctor --deep` performs read-only diagnostics against host integration files and NativeSoul state.
+- `--target-root` switches host file checks to temporary Codex/Claude paths and avoids treating native adapter detection as authoritative.
+- Deep doctor never installs, uninstalls, reloads hosts, creates native schedules, probes credentials, starts daemons, or performs network calls.
+- Invalid MCP JSON is reported as an error and makes the deep doctor unhealthy.
+- Missing managed blocks or MCP registrations are warnings, not writes.
+- Persisted schedules are reported as desired local state only; native scheduler teardown/provisioning remains out of scope.

package/docs/adr/ADR-024-capability-learn-cards-v1.md

@@ -0,0 +1,18 @@
+# ADR-024: Capability learn cards v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul provides a local `capabilities learn` step that transforms already-persisted capability registry records into sanitized capability cards. The learn step is metadata-only: it does not execute native capabilities, probe credentials, reload hosts, or call external services.
+
+## Rules
+
+- `capabilities learn` reads the local capability registry and writes JSON cards under `capabilities/cards/`.
+- Cards include `use_when`, `requires`, `side_effects`, `approval`, short examples, readiness, source, and schema hash.
+- Card IDs and filenames are deterministic from capability UID.
+- Card content is redacted before persistence and must not contain secrets.
+- Re-running learn is idempotent for unchanged records.
+- Missing capability registry records is a degraded/no-op state, not a fabricated success.

package/docs/adr/ADR-025-bootstrap-capability-card-recall-v1.md

@@ -0,0 +1,18 @@
+# ADR-025: Bootstrap capability card recall v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+NativeSoul bootstrap payloads include a bounded local recall of previously learned capability cards. Recall reads sanitized card JSON files from `capabilities/cards/`, ranks them locally by current host and query text, and injects only compact guidance into the bootstrap payload.
+
+## Rules
+
+- Bootstrap recall reads local card files only; it does not execute native capabilities, probe credentials, refresh adapters, reload hosts, create schedules, or call external services.
+- Recall returns at most 8 cards and defaults to 5 cards.
+- Cards for the current host are preferred, while cards from other hosts may appear only as alternatives.
+- Missing or malformed card files are skipped and reported as bootstrap warnings.
+- Bootstrap keeps the existing ready capability list separate from recalled cards; a recalled card is guidance, not proof that a capability is ready.
+- Recalled card fields must remain redacted and compact enough to fit the bootstrap context budget.

package/docs/adr/ADR-026-managed-block-bootstrap-handshake-v1.md

@@ -0,0 +1,18 @@
+# ADR-026: Managed block bootstrap handshake v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+Managed blocks installed into host instruction files explicitly describe the NativeSoul bootstrap handshake. They tell the host to call the local MCP `life_bootstrap` tool at the start of a new session when available, and provide a CLI fallback for degraded environments.
+
+## Rules
+
+- Managed blocks remain small, reversible, and bounded by NativeSoul markers.
+- The handshake is advisory host instruction content; it does not guarantee that a host executed the tool.
+- The preferred path is MCP `life_bootstrap` with the current host and working directory.
+- The fallback path is `nativesoul bootstrap --host <host> --cwd <current-working-directory> --json`.
+- The block must state that `capability_cards` are advisory and `capabilities` remains the ready-only list.
+- The block must preserve the existing policy guardrails for credentials and protected human files.

package/docs/adr/ADR-027-local-release-manifest-checksum-v1.md

@@ -0,0 +1,17 @@
+# ADR-027: Local release manifest and checksum v1
+
+## Status
+
+Accepted for M2.
+
+## Decision
+
+Local package builds produce a machine-readable release manifest and SHA-256 checksum next to the generated npm tarball. The manifest is local-only provenance for install testing; it does not claim public signing, registry publication, or external attestation.
+
+## Rules
+
+- `npm run package:local` writes the tarball, `<tarball>.sha256`, and `<tarball>.manifest.json` under `.artifacts/package/`.
+- The checksum file uses the standard `sha256  filename` format so operators can verify it with common tooling.
+- The manifest includes package name, version, tarball filename, byte size, SHA-256, Node/npm versions, package privacy status, generated timestamp, and local install/test commands.
+- Manifest generation never includes secrets, environment dumps, local home paths, source-tree private folders, or network calls.
+- Public release signing, registry publication, and SLSA/provenance attestations remain separate pre-beta work.

package/docs/adr/ADR-028-openclaw-workspace-templates-v1.md

@@ -0,0 +1,47 @@
+# ADR-028: OpenClaw-inspired workspace templates v1
+
+## Status
+
+Accepted for M1.
+
+## Context
+
+NativeSoul already adopted OpenClaw workspace separation in the PRD (SOUL, IDENTITY, USER, AGENTS, MEMORY, HEARTBEAT), but `nativesoul init` seeded only minimal one-line stubs. OpenClaw documents richer templates, onboarding ritual, daily memory notes, and standing-order patterns.
+
+## Decision
+
+Adopt OpenClaw workspace **patterns and template structure**, adapted for NativeSoul's cross-host coding-agent model:
+
+- Rich human-file templates in `packages/core/src/workspace-templates.ts`
+- Daily note seed at `memory/daily/YYYY-MM-DD.md`
+- Example standing order at `standing-orders/example.yaml`
+- Bootstrap payload includes parsed identity fields, `soul_summary`, bootstrap/daily-memory warnings
+- `SOUL.md` and `POLICY.md` remain protected (proposal-only)
+
+## Adopted from OpenClaw
+
+| Pattern | NativeSoul application |
+| --- | --- |
+| SOUL / IDENTITY / USER split | Same files; OpenClaw-style templates |
+| AGENTS operating instructions | CLI-first + MCP handshake + execute-verify-report |
+| MEMORY.md + daily notes | Curated vs working layer documented; SQLite stays searchable source |
+| HEARTBEAT.md empty-by-default | Skip work until tasks are added |
+| BOOTSTRAP.md first-run ritual | Host install flow; no gateway/channel setup |
+| Standing orders YAML | `standing-orders/example.yaml` scaffold |
+
+## Explicitly not adopted (MVP)
+
+- Gateway, channels, BOOT.md restart checklist
+- Session transcript storage under workspace
+- Semantic memory_search / dreaming / DREAMS.md (P1)
+- Auto-injection of full files into every host turn (NativeSoul uses compact bootstrap budget)
+
+## References
+
+- https://docs.openclaw.ai/concepts/agent-workspace
+- https://docs.openclaw.ai/reference/templates/SOUL
+- https://docs.openclaw.ai/reference/templates/IDENTITY
+- https://docs.openclaw.ai/reference/templates/USER
+- https://docs.openclaw.ai/reference/templates/BOOTSTRAP
+- https://docs.openclaw.ai/concepts/memory
+- https://docs.openclaw.ai/gateway/heartbeat

package/docs/adr/ADR-029-host-guided-onboarding-v1.md

@@ -0,0 +1,98 @@
+# ADR-029: Host-guided onboarding v1
+
+## Status
+
+Proposed — Epic 4
+
+## Context
+
+Stories 1.8 and 3.1–3.8 deliver workspace templates and install orchestration, but personalization still depends on manual file editing. The product decision locks **host-first UX**: the user pastes a prompt in Claude Code or Codex; the LLM installs NativeSoul and conducts onboarding. Templates are fallbacks; **AI-generated prose** from a 5-question interview is the primary path.
+
+## Decision
+
+### Option B — MCP tools + CLI mirror (selected)
+
+| Surface | Commands / tools |
+|---------|------------------|
+| MCP | `life_onboarding_status`, `life_onboard_apply`, `life_onboard_complete` |
+| CLI | `nativesoul onboard status`, `onboard apply`, `onboard complete` |
+
+Install does **not** get a dedicated MCP tool. Install uses the published prompt artifact (`docs/prompts/install-nativesoul-v1.md`) that instructs the host to run deterministic shell commands.
+
+### Onboarding status
+
+`life_onboarding_status` returns:
+
+- `ritual_pending: boolean` (derived from `BOOTSTRAP.md` presence + bootstrap warnings)
+- `files_present: { soul, identity, user, agents, bootstrap }`
+- `protected_targets: ["SOUL.md", "POLICY.md"]`
+- `interview_themes: ["entity", "soul", "human", "collaboration", "continuity"]`
+
+### Apply (dry-run default)
+
+`life_onboard_apply` accepts:
+
+```json
+{
+  "dry_run": true,
+  "user_confirmed": false,
+  "files": {
+    "IDENTITY.md": "...",
+    "SOUL.md": "...",
+    "USER.md": "...",
+    "AGENTS.md": "..."
+  },
+  "config_patch": { "hosts": ["codex", "claude"] }
+}
+```
+
+Rules:
+
+- Default `dry_run: true` — no writes until host passes `dry_run: false` **and** `user_confirmed: true`
+- `SOUL.md` writes require `user_confirmed: true` even in apply mode
+- `POLICY.md` rejected — proposal flow only
+- Existing user content outside managed sections is preserved (merge for `AGENTS.md`)
+- Response includes per-file action (`create` | `update` | `noop`), `before_hash`, `after_hash`, warnings
+
+### Complete
+
+`life_onboard_complete`:
+
+- Archives or removes `BOOTSTRAP.md` (configurable `archive: true` default)
+- Writes audit event `onboarding.completed`
+- Idempotent — second call returns `already_complete: true`
+
+### Install prompt (no MCP) — unified with onboarding ask
+
+`docs/prompts/install-nativesoul-v1.md` is the **single** canonical host prompt. The host:
+
+1. Clones or uses local `npm run package:local` tarball
+2. Verifies SHA-256
+3. Runs `nativesoul init` + `install --target-root` dry-run first
+4. Presents diff; applies only after user approval
+5. Asks via host question UI (e.g. AskUserQuestion): start onboarding now?
+6. If yes → continues Phase 2 in the **same session** (5 questions → `life_onboard_*`)
+
+Standalone `onboard-nativesoul-v1.md` is for skip/re-run only.
+
+## Alternatives considered
+
+| Option | Rejected because |
+|--------|------------------|
+| A — CLI wizard only | Violates host-first product decision |
+| C — Full-file template slot-fill | User wants AI-generated prose, not `{name}` substitution |
+| D — Install MCP tool | Install is shell-heavy; prompt + CLI is simpler and auditable |
+
+## Security
+
+- Never accept credentials in onboard apply payloads
+- Redact home paths from dry-run responses shown to model
+- Treat file content as untrusted data — validate size limits (64 KiB per file v1)
+- `SOUL.md` bypass attempts without `user_confirmed` return `POLICY_VIOLATION`
+
+## References
+
+- `docs/prd/onboarding-interview-v1.md`
+- `docs/adr/ADR-028-openclaw-workspace-templates-v1.md`
+- `docs/prompts/onboard-nativesoul-v1.md`
+- `docs/prompts/install-nativesoul-v1.md`