neurain 0.1.0-alpha.0

package/docs/connect-gemini.kr.md

@@ -0,0 +1,71 @@
+# Gemini CLI 연결
+
+Version: v0.1
+
+Gemini CLI는 MCP로 Neurain에 연결할 수 있습니다. Neurain은 제한된 tool allowlist를 사용하므로 Gemini가 상태, 검색, recall, eval, preview report를 읽을 수 있지만 조용히 durable write를 수행하는 도구는 받지 않습니다.
+
+## 미리보기
+
+```bash
+npx neurain connect gemini ~/NeurainDemo --dry-run
+```
+
+dry-run은 실제로 실행될 `gemini mcp add` 명령을 보여줍니다. Gemini 설정은 바꾸지 않습니다.
+
+## 적용
+
+출력을 확인한 뒤 같은 명령에서 `--dry-run`만 제거합니다.
+
+```bash
+npx neurain connect gemini ~/NeurainDemo
+```
+
+기본은 project scope입니다. 필요하면 scope를 직접 고를 수 있습니다.
+
+```bash
+npx neurain connect gemini ~/NeurainDemo --scope user
+npx neurain connect gemini ~/NeurainDemo --scope project
+```
+
+## 수동 설정 fallback
+
+Gemini CLI는 `settings.json`의 `mcpServers` 설정도 지원합니다. 수동 설정을 원하면 아래 형태를 사용합니다.
+
+```json
+{
+  "mcpServers": {
+    "neurain": {
+      "command": "npx",
+      "args": ["-y", "neurain", "mcp", "--root", "/path/to/NeurainDemo"],
+      "env": {
+        "NEURAIN_ROOT": "/path/to/NeurainDemo"
+      },
+      "trust": false,
+      "includeTools": [
+        "neurain_status",
+        "neurain_search",
+        "neurain_adopt_scan",
+        "neurain_recall_hybrid_search",
+        "neurain_answer_quality_eval",
+        "neurain_live_cases_scaffold",
+        "neurain_wrap_preview"
+      ]
+    }
+  }
+}
+```
+
+## Lifecycle boundary
+
+Gemini MCP 연결은 지원됩니다. 다만 native Gemini lifecycle hook 자동화는 이번 alpha에서는 manual-only입니다. boundary receipt가 필요하면 명시적으로 lifecycle command를 실행합니다.
+
+```bash
+npx neurain lifecycle emit ~/NeurainDemo --host gemini --event turn_end --session-id gemini-session-1 --turn-id turn-1 --confirm "1건 저장 진행"
+```
+
+## 안전 기준
+
+- MCP는 preview와 eval을 실행할 수 있습니다.
+- MCP는 lesson을 조용히 승격하거나 durable wiki knowledge를 쓰지 않습니다.
+- Gemini allowlist는 기본적으로 raw capture를 제외합니다.
+- redacted live-case scaffold는 hash-only source ref를 반환하고 raw source text를 저장하지 않습니다.

package/docs/connect-runtime.en.md

@@ -0,0 +1,61 @@
+# Connect Agent Runtime
+
+Agent Runtime means a generic AI host that owns prompt assembly, model calls, tool execution, and session lifecycle. It is not an LLM. The clean Neurain path is to let the runtime stay in front while Neurain runs behind it as a bounded MCP knowledge server.
+
+Preview a bounded runtime MCP config:
+
+```bash
+npx neurain connect runtime ~/NeurainDemo --dry-run
+```
+
+The alpha does not edit any host config directly. It prints a bounded config snippet like this:
+
+```yaml
+mcp_servers:
+  neurain:
+    command: "npx"
+    args: ["-y", "neurain", "mcp", "--root", "/path/to/NeurainDemo"]
+    env:
+      NEURAIN_ROOT: "/path/to/NeurainDemo"
+    tools:
+      include:
+        - neurain_status
+        - neurain_search
+        - neurain_recall_search
+        - neurain_recall_status
+        - neurain_recall_verify
+        - neurain_recall_cross_host_eval
+        - neurain_lifecycle_report
+        - neurain_watch_report
+        - neurain_review_worker
+        - neurain_scheduler_tick
+        - neurain_scheduler_eval
+        - neurain_wrap_preview
+      resources: false
+      prompts: false
+```
+
+After adding the snippet to the target host config, reload MCP using that host's normal reload flow.
+
+Safety boundary:
+
+- The agent runtime gets a small read-heavy Neurain tool surface.
+- Neurain does not become dependent on any single runtime.
+- MCP cannot silently promote lessons, rebuild recall cache, or write durable wiki knowledge.
+- Durable Neurain writes still require explicit CLI confirmation.
+- The alpha snippet does not support paths containing newline or control bytes.
+- Scheduler access is read-only and cannot install background jobs or start daemons.
+- Scheduler eval access is read-only and checks trigger precision, trigger recall, no-recursion, private-boundary handling, case-file size limits, and target-root non-write snapshots.
+- Lifecycle access is read-only through MCP. The runtime can inspect session lineage, while deeper lifecycle event emission uses the separate host-proxy contract below.
+
+## Lifecycle Boundary
+
+Runtime does not have a Neurain-owned native config writer in alpha. Instead, Neurain exposes a host-proxy lifecycle contract that an agent runtime can call when it knows a turn boundary:
+
+```bash
+npx neurain connect runtime ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+The preview prints a JSON contract with the command and supported direct lifecycle events such as `session_start`, `turn_start`, `turn_end`, `review_due`, `compaction`, `resume`, and `session_end`.
+
+This is not a claim that Neurain owns the agent loop. The runtime remains the front agent host. Neurain receives only boundary metadata, requires explicit confirmation in the command, and does not store prompt bodies, messages, transcript paths, tool stdout, or tool stderr.

package/docs/connect-runtime.kr.md

@@ -0,0 +1,61 @@
+# Agent Runtime 연결
+
+Agent Runtime은 prompt assembly, model call, tool execution, session lifecycle을 소유하는 일반 AI host를 뜻합니다. LLM 자체가 아닙니다. Neurain의 깔끔한 방향은 runtime을 앞단에 두고, Neurain은 뒤에서 bounded MCP knowledge server로 동작하게 하는 것입니다.
+
+Bounded runtime MCP config를 preview합니다.
+
+```bash
+npx neurain connect runtime ~/NeurainDemo --dry-run
+```
+
+Alpha에서는 어떤 host config도 직접 수정하지 않습니다. 대신 아래와 같은 bounded config snippet을 출력합니다.
+
+```yaml
+mcp_servers:
+  neurain:
+    command: "npx"
+    args: ["-y", "neurain", "mcp", "--root", "/path/to/NeurainDemo"]
+    env:
+      NEURAIN_ROOT: "/path/to/NeurainDemo"
+    tools:
+      include:
+        - neurain_status
+        - neurain_search
+        - neurain_recall_search
+        - neurain_recall_status
+        - neurain_recall_verify
+        - neurain_recall_cross_host_eval
+        - neurain_lifecycle_report
+        - neurain_watch_report
+        - neurain_review_worker
+        - neurain_scheduler_tick
+        - neurain_scheduler_eval
+        - neurain_wrap_preview
+      resources: false
+      prompts: false
+```
+
+Snippet을 대상 host config에 추가한 뒤, 해당 host의 일반 MCP reload flow를 사용합니다.
+
+Safety boundary:
+
+- Agent runtime은 작은 read-heavy Neurain tool surface만 받습니다.
+- Neurain은 특정 runtime에 dependency를 갖지 않습니다.
+- MCP는 lesson을 조용히 promote하거나 recall cache를 rebuild하거나 durable wiki knowledge를 write할 수 없습니다.
+- Durable Neurain write는 여전히 explicit CLI confirmation이 필요합니다.
+- Alpha snippet은 newline 또는 control byte가 포함된 path를 지원하지 않습니다.
+- Scheduler access는 read-only이며 background job을 설치하거나 daemon을 시작할 수 없습니다.
+- Scheduler eval access도 read-only이며 trigger precision, trigger recall, no-recursion, private-boundary handling, case-file size limit, target-root non-write snapshot을 확인합니다.
+- Lifecycle access는 MCP에서 read-only입니다. Runtime은 session lineage를 읽을 수 있고, 더 깊은 lifecycle event emission은 아래 host-proxy contract를 사용합니다.
+
+## Lifecycle Boundary
+
+Alpha에서 Neurain은 runtime native config writer를 소유하지 않습니다. 대신 agent runtime이 turn boundary를 알고 있을 때 호출할 수 있는 host-proxy lifecycle contract를 제공합니다.
+
+```bash
+npx neurain connect runtime ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+Preview는 command와 지원하는 direct lifecycle event가 포함된 JSON contract를 출력합니다. 지원 event는 `session_start`, `turn_start`, `turn_end`, `review_due`, `compaction`, `resume`, `session_end` 등을 포함합니다.
+
+이것은 Neurain이 agent loop를 소유한다는 뜻이 아닙니다. Runtime은 앞단 agent host로 남고, Neurain은 boundary metadata만 받습니다. Command에는 explicit confirmation이 필요하며 prompt body, messages, transcript path, tool stdout, tool stderr는 저장하지 않습니다.

package/docs/development-status.en.md

@@ -0,0 +1,157 @@
+# Development Status
+
+Version: v0.1
+Last updated: 2026-06-09 KST
+Package: `neurain@0.1.0-alpha.0`
+Latest documented commit: `3496262 Add E24 onboarding and Gemini MCP connector`
+
+This document is the canonical product development snapshot for the public package. It tracks what is shipped, what has evidence, and what must not be claimed yet.
+
+## Current Product Stage
+
+Neurain is a publish-ready alpha CLI and MCP package. It is ready for private beta or alpha user tests, not public SaaS GA.
+
+Current verified score:
+
+| Gate | Result |
+|---|---:|
+| `npm test` | 37/37 pass |
+| `node scripts/readiness.mjs --json` | `ok:true`, score `100`, 35 checks |
+| `npm run readiness -- --json` | `ok:true`, score `100` |
+| `npm audit` | 0 vulnerabilities |
+| `npm pack --dry-run` | pass |
+| Temporary tarball install smoke | pass |
+
+## Shipped Development
+
+### Foundation Before E21
+
+- Starter vault initialization with `neurain init`.
+- Existing folder adoption scan, apply, receipt, and rollback.
+- Local doctor, search, capabilities, recap, and wrap preview.
+- Event journal add/list/verify with explicit confirmation.
+- Lesson list, candidates, eval, promotion, and rollback.
+- Watch report, review worker, scheduler tick, scheduler monitor, foreground daemon.
+- Curator status, run preview, confirmed status updates, snapshot, and rollback.
+- Optional SQLite FTS5 recall DB with markdown fallback and rebuild receipts.
+- Answer-quality eval with synthetic and reviewed case-file modes.
+
+### E21: Native Lifecycle Automation Eval
+
+Status: shipped.
+
+- CLI: `neurain lifecycle eval <folder>`.
+- MCP: `neurain_lifecycle_eval`, read-only.
+- Replays Claude Code, Codex, Runtime, and generic lifecycle payloads through actual adapters in isolated temp roots.
+- Proves prompt bodies, transcript paths, tool stdout, tool stderr, secret-like content, and injection-like content are not persisted.
+- Gates malformed, unsupported, missing-session, traversal, target-root non-write, coverage, and temp cleanup.
+- Honest scope: this is a lifecycle safety gate. It does not make Neurain own the host model loop and does not claim automatic background self-improvement.
+
+### E22: Semantic Recall Quality
+
+Status: shipped.
+
+- CLI: `neurain recall semantic-search`, `neurain recall eval --semantic`.
+- MCP: `neurain_recall_semantic_search`, `neurain_recall_semantic_eval`, read-only.
+- Adds deterministic local lexical-semantic recall using stemming, curated synonyms, and fuzzy character-trigram matching.
+- Makes no model call, has no external dependency, and keeps provider replacement possible.
+- Honest scope: this is not neural semantic understanding. It improves paraphrase recall within its local lexical scope.
+
+### Hybrid Recall Fix
+
+Status: shipped after real-content live-eval exposed a regression.
+
+- CLI: `neurain recall hybrid-search`.
+- MCP: `neurain_recall_hybrid_search`, read-only.
+- Combines exact-token recall with local lexical-semantic recall.
+- Guarantees the hybrid union is not worse than exact-token for covered results.
+- `--top` is per branch, so returned union can be longer than `--top`.
+
+### E23: Live Use Eval Infrastructure
+
+Status: shipped for first increment and redacted scaffold.
+
+- CLI: `neurain recall live-eval <folder>`.
+- CLI: `neurain live-cases scaffold <folder>`.
+- MCP: `neurain_live_cases_scaffold`, read-only.
+- Live-eval measures real-folder recall coverage without storing source content.
+- Scaffold creates hash-only source refs and reviewed case templates without raw source text, absolute local paths, secret-like content, or injection-like content.
+- Scaffold intentionally reports `reviewed_live_user_evidence:false` and `human_judged:false` until a human fills cases.
+- Honest scope: this prepares safe live evidence. It does not fabricate external user proof, and three real user walkthroughs are still required for that claim.
+
+### E24: Non-Developer Onboarding
+
+Status: shipped.
+
+- CLI: `neurain onboard <folder>`.
+- Read-only first screen for new users.
+- Tells a user whether to initialize, scan an existing folder, connect a host, or preview wrap.
+- Reports what Neurain stores and does not store.
+- Makes no model call, no external call, and no durable write.
+
+### E25: Installable CLI Readiness
+
+Status: shipped as publish-ready alpha.
+
+- `package.json` exposes the `neurain` binary.
+- README, quickstart, safety, privacy, support, pricing, troubleshooting, and release checklist exist.
+- CI workflow, issue templates, PR template, license, and security doc exist.
+- Full readiness verifies npm audit, pack dry-run, and temporary tarball install smoke.
+- Honest scope: npm publish or package name reservation still requires an explicit release action.
+
+### E26: Thin MCP Connector
+
+Status: shipped.
+
+- Codex MCP command dry-run and apply command generation.
+- Claude Code MCP command dry-run and apply command generation.
+- Gemini CLI MCP command dry-run and apply command generation with bounded read-first tool allowlist.
+- Runtime MCP config-preview snippet.
+- MCP server exposes bounded alpha tools for status, search, scan, recall, eval, live-case scaffold, lesson preview, scheduler preview, lifecycle report/eval, and wrap preview.
+- MCP does not expose silent durable wiki writes, lifecycle emit, daemon run/stop, curator write, recall rebuild write, or lesson promotion.
+
+## Current Connector Truth Table
+
+| Host | MCP connection | Lifecycle hook preview | Notes |
+|---|---|---|---|
+| Codex | shipped | shipped | `.codex/hooks.json` preview |
+| Claude Code | shipped | shipped | Claude settings preview |
+| Gemini CLI | shipped | manual lifecycle only | MCP config and `gemini mcp add` command supported |
+| Agent Runtime | config-preview shipped | host-proxy contract shipped | Neurain does not edit Runtime config |
+
+## Still Not Shipped
+
+- External user walkthrough evidence from at least three real folders.
+- Non-developer GUI.
+- Hosted control plane.
+- Public Trust Center and status page.
+- npm publish or package name reservation.
+- Public GitHub publication if the repo is intentionally kept private during beta.
+
+## Documentation Maintenance Rule
+
+Update this file and the Korean pair whenever any of the following changes:
+
+- CLI command surface.
+- MCP tool surface.
+- Safety, privacy, write, rollback, or lifecycle boundary.
+- Readiness score, test count, or package version.
+- E milestone status.
+- Product claim level, such as alpha, private beta, public beta, or SaaS GA.
+
+Minimum update procedure:
+
+```bash
+npm test
+node scripts/readiness.mjs --json
+npm run readiness -- --json
+```
+
+Then update:
+
+- `README.md`
+- `docs/development-status.en.md`
+- `docs/development-status.kr.md`
+- affected connector docs
+- affected workflow, readiness, or release docs
+

package/docs/development-status.kr.md

@@ -0,0 +1,157 @@
+# 개발 진행 상태
+
+Version: v0.1
+Last updated: 2026-06-09 KST
+Package: `neurain@0.1.0-alpha.0`
+Latest documented commit: `3496262 Add E24 onboarding and Gemini MCP connector`
+
+이 문서는 public package 기준의 canonical 개발 상태 스냅샷입니다. 무엇이 shipped인지, 어떤 증거가 있는지, 아직 주장하면 안 되는 것이 무엇인지 함께 기록합니다.
+
+## 현재 제품 단계
+
+Neurain은 publish-ready alpha CLI 및 MCP package입니다. private beta 또는 alpha user test에는 들어갈 수 있지만 public SaaS GA는 아닙니다.
+
+현재 검증된 상태:
+
+| Gate | Result |
+|---|---:|
+| `npm test` | 37/37 pass |
+| `node scripts/readiness.mjs --json` | `ok:true`, score `100`, 35 checks |
+| `npm run readiness -- --json` | `ok:true`, score `100` |
+| `npm audit` | 0 vulnerabilities |
+| `npm pack --dry-run` | pass |
+| Temporary tarball install smoke | pass |
+
+## shipped 개발 범위
+
+### E21 이전 foundation
+
+- `neurain init` starter vault initialization.
+- 기존 폴더 adoption scan, apply, receipt, rollback.
+- local doctor, search, capabilities, recap, wrap preview.
+- 명시적 confirmation이 필요한 event journal add/list/verify.
+- lesson list, candidates, eval, promotion, rollback.
+- watch report, review worker, scheduler tick, scheduler monitor, foreground daemon.
+- curator status, run preview, confirmed status update, snapshot, rollback.
+- markdown fallback과 rebuild receipt가 있는 optional SQLite FTS5 recall DB.
+- synthetic 및 reviewed case-file mode를 지원하는 answer-quality eval.
+
+### E21: Native Lifecycle Automation Eval
+
+Status: shipped.
+
+- CLI: `neurain lifecycle eval <folder>`.
+- MCP: read-only `neurain_lifecycle_eval`.
+- Claude Code, Codex, Runtime, generic lifecycle payload를 실제 adapter로 격리된 temp root에서 재생합니다.
+- prompt body, transcript path, tool stdout, tool stderr, secret-like content, injection-like content가 저장되지 않음을 증명합니다.
+- malformed, unsupported, missing-session, traversal, target-root non-write, coverage, temp cleanup을 gate로 봅니다.
+- 정직한 범위: lifecycle 안전 gate입니다. Neurain이 host model loop를 소유한다거나 automatic background self-improvement를 완성했다고 주장하지 않습니다.
+
+### E22: Semantic Recall Quality
+
+Status: shipped.
+
+- CLI: `neurain recall semantic-search`, `neurain recall eval --semantic`.
+- MCP: read-only `neurain_recall_semantic_search`, `neurain_recall_semantic_eval`.
+- stemming, curated synonym, fuzzy char-trigram matching을 이용한 deterministic local lexical-semantic recall을 추가합니다.
+- model call이 없고, external dependency가 없고, provider 교체 가능성을 유지합니다.
+- 정직한 범위: neural semantic understanding은 아닙니다. local lexical scope 안에서 paraphrase recall을 개선합니다.
+
+### Hybrid Recall Fix
+
+Status: real-content live-eval이 regression을 잡은 뒤 shipped.
+
+- CLI: `neurain recall hybrid-search`.
+- MCP: read-only `neurain_recall_hybrid_search`.
+- exact-token recall과 local lexical-semantic recall을 합칩니다.
+- covered result 기준 hybrid union이 exact-token보다 나빠지지 않게 합니다.
+- `--top`은 branch별 후보 깊이라 반환 union은 `--top`보다 길어질 수 있습니다.
+
+### E23: Live Use Eval Infrastructure
+
+Status: first increment와 redacted scaffold shipped.
+
+- CLI: `neurain recall live-eval <folder>`.
+- CLI: `neurain live-cases scaffold <folder>`.
+- MCP: read-only `neurain_live_cases_scaffold`.
+- live-eval은 source content를 저장하지 않고 실제 폴더의 recall coverage를 측정합니다.
+- scaffold는 raw source text, absolute local path, secret-like content, injection-like content 없이 hash-only source ref와 reviewed case template을 만듭니다.
+- scaffold는 사람이 case를 채우기 전까지 의도적으로 `reviewed_live_user_evidence:false`, `human_judged:false`를 보고합니다.
+- 정직한 범위: 안전한 live evidence 준비물입니다. 외부 사용자 증거를 만들었다고 주장하지 않으며, 최소 3개 실제 user walkthrough는 아직 필요합니다.
+
+### E24: Non-Developer Onboarding
+
+Status: shipped.
+
+- CLI: `neurain onboard <folder>`.
+- 신규 사용자를 위한 read-only 첫 화면입니다.
+- 사용자가 initialize, existing-folder scan, host connect, wrap preview 중 무엇을 해야 하는지 알려줍니다.
+- Neurain이 저장하는 것과 저장하지 않는 것을 설명합니다.
+- model call, external call, durable write가 없습니다.
+
+### E25: Installable CLI Readiness
+
+Status: publish-ready alpha로 shipped.
+
+- `package.json`이 `neurain` binary를 노출합니다.
+- README, quickstart, safety, privacy, support, pricing, troubleshooting, release checklist가 존재합니다.
+- CI workflow, issue template, PR template, license, security doc이 존재합니다.
+- full readiness가 npm audit, pack dry-run, temporary tarball install smoke를 검증합니다.
+- 정직한 범위: npm publish 또는 package name reservation은 별도 release action이 필요합니다.
+
+### E26: Thin MCP Connector
+
+Status: shipped.
+
+- Codex MCP command dry-run 및 apply command generation.
+- Claude Code MCP command dry-run 및 apply command generation.
+- Gemini CLI MCP command dry-run 및 bounded read-first tool allowlist가 포함된 apply command generation.
+- Runtime MCP config-preview snippet.
+- MCP server는 status, search, scan, recall, eval, live-case scaffold, lesson preview, scheduler preview, lifecycle report/eval, wrap preview용 bounded alpha tool을 노출합니다.
+- MCP는 silent durable wiki write, lifecycle emit, daemon run/stop, curator write, recall rebuild write, lesson promotion을 노출하지 않습니다.
+
+## 현재 connector truth table
+
+| Host | MCP connection | Lifecycle hook preview | Notes |
+|---|---|---|---|
+| Codex | shipped | shipped | `.codex/hooks.json` preview |
+| Claude Code | shipped | shipped | Claude settings preview |
+| Gemini CLI | shipped | manual lifecycle only | MCP config와 `gemini mcp add` command 지원 |
+| Agent Runtime | config-preview shipped | host-proxy contract shipped | Neurain은 Runtime config를 직접 수정하지 않음 |
+
+## 아직 shipped가 아닌 것
+
+- 최소 3개 실제 폴더 기준 external user walkthrough evidence.
+- non-developer GUI.
+- hosted control plane.
+- public Trust Center 및 status page.
+- npm publish 또는 package name reservation.
+- beta 동안 repo를 private으로 유지한다면 public GitHub publication.
+
+## 문서 유지관리 규칙
+
+아래가 바뀌면 이 문서와 영어 pair를 업데이트합니다.
+
+- CLI command surface.
+- MCP tool surface.
+- safety, privacy, write, rollback, lifecycle boundary.
+- readiness score, test count, package version.
+- E milestone status.
+- alpha, private beta, public beta, SaaS GA 같은 product claim level.
+
+최소 업데이트 절차:
+
+```bash
+npm test
+node scripts/readiness.mjs --json
+npm run readiness -- --json
+```
+
+그 다음 아래 문서를 업데이트합니다.
+
+- `README.md`
+- `docs/development-status.en.md`
+- `docs/development-status.kr.md`
+- 영향을 받은 connector docs
+- 영향을 받은 workflow, readiness, release docs
+

package/docs/knowledge-os.en.md

@@ -0,0 +1,105 @@
+# Neurain Knowledge OS
+
+Version: 0.2
+
+Neurain Knowledge OS is the external product name for Neurain's local-first knowledge layer.
+
+For current shipped scope, test evidence, and remaining gaps, see `docs/development-status.en.md`.
+
+It is designed for a simple customer promise:
+
+> Bring your folder, keep your knowledge, use any AI agent.
+
+## What It Is
+
+Neurain Knowledge OS is a source-grounded operating layer for a user's working folder.
+
+It gives AI agents a consistent way to:
+
+- understand the folder structure
+- keep a durable wiki
+- preserve source evidence
+- capture important work
+- expose reviewed lessons from prior sessions
+- avoid unsafe durable writes
+- recover and continue across agents
+
+## What It Is Not
+
+Neurain is not an LLM.
+
+It does not replace Claude, GPT, Gemini, DeepSeek, or local models. It also does not need one fixed model provider to work.
+
+Neurain is also not a hidden cloud memory database. The default product direction is local-first. The user's folder and Neurain vault remain the source of truth unless the user explicitly connects another service.
+
+## Layer Model
+
+Neurain should be explained with three layers.
+
+| Layer | Examples | Job |
+|---|---|---|
+| Model layer | Claude, GPT, Gemini, DeepSeek, local models | Generate reasoning and text |
+| Agent runtime layer | Agent Runtime, Codex, Claude Code, Gemini CLI, OpenClaw | Assemble prompts, call models, execute tools, manage turns |
+| Knowledge OS layer | Neurain Knowledge OS | Store source-grounded knowledge, memory, wiki, lessons, receipts, and recovery state |
+
+Agent Runtime means a generic AI host that owns prompt assembly, model calls, tool execution, and session lifecycle. In this document, "Agent Runtime" always refers to a runtime, not an LLM. Comparing a runtime to Claude or Gemini model families is a category mistake.
+
+## Why Use Neurain With An Agent Runtime
+
+Runtime can own the agent loop and provide a strong self-improving runtime. Neurain's role is different.
+
+Neurain helps when the user wants:
+
+- the working folder to remain the durable source of truth
+- knowledge to be portable across Codex, Claude Code, Gemini CLI, Agent Runtime, and future hosts
+- source-grounded wiki pages instead of chat-only memory
+- safety gates before durable writes
+- rollback receipts for changes
+- private material to stay local
+- a plain markdown fallback when the AI host changes
+
+The preferred relationship is not "runtime versus Neurain." It is "runtime in front, Neurain behind" when the user wants an agent runtime to own the loop.
+
+Before/after example:
+
+- Before Neurain: the user repeats project context whenever they switch from Codex to Claude Code or Agent Runtime.
+- After Neurain: each host can read the same local startup, wiki, receipts, and reviewed lessons, so the folder carries the memory instead of one chat.
+
+## Product Vocabulary
+
+Use these terms in external product material:
+
+- Neurain Knowledge OS
+- local-first knowledge layer
+- source-grounded wiki
+- portable AI memory
+- reviewed lessons
+- safety receipts
+- folder adoption
+- agent-independent continuity
+
+Avoid these claims until they are proven by product evidence:
+
+- fully autonomous self-improvement
+- automatic durable learning
+- public SaaS ready
+- enterprise governance ready
+- better than a dedicated runtime as a runtime
+
+## First-Run Customer Story
+
+1. The user has a work folder.
+2. The user runs `npx neurain init <folder>`.
+3. Neurain creates a clean local vault.
+4. The user runs `npx neurain adopt <work-folder> --dry-run`.
+5. Neurain scans before writing and explains the plan.
+6. The user connects Codex, Claude Code, Gemini CLI, Agent Runtime, or another host.
+7. During work, the user runs `neurain wrap <folder> --dry-run`.
+8. Neurain previews the state, risks, recap, and lesson candidates.
+9. Durable changes require explicit human confirmation.
+
+## Branding Rule
+
+For external-facing docs, prefer "Neurain Knowledge OS" on first mention. After that, "Neurain" is fine.
+
+For internal engineering docs, "AI Knowledge OS" may still describe the category, but "Neurain Knowledge OS" is the product brand.