neurain 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+- Expanded the recall markdown corpus to the general area knowledge class (`10_areas/<area>/**`, hubs, area registry), with config-extensible include/exclude (`recall.include`/`recall.exclude`).
+- Added label-based privacy gating (`labels.mjs`): per-file frontmatter `sensitivity`, area baseline from `_area.md`, and boundary-aware path markers exclude private content at index time. Fixes a substring marker that could exclude a whole legitimate folder.
+- Added a routed lexical recall branch (`recall_lexical.mjs`): BM25 + structural/layer/entity/domain/fact-ledger boosts, unioned ahead of exact-token and semantic in hybrid search. Auto-enabled when a search index registry has areas or `--area` is set; off by default on a bare vault.
+- Added `--area <name>` scoping to `recall search`, `semantic-search`, and `hybrid-search`.
+- Added `recall bench` and `recall scorecard` to score external benchmark suites (strict/loose matchers, gate verdict, `--case --explain` traces, Hit@K/R@K/MRR/latency).
+- Added read-only view commands `status`, `digest`, `queue`, and `review-queue`, with matching MCP tools (`neurain_session_status`, `neurain_digest_preview`, `neurain_queue_view`, `neurain_review_queue`). They read vault state formats (session-state, wrap-journal, writeback queue + per-area registry, source-digest manifest) and degrade gracefully when absent. `status` is read-only (no digest ack, no maintenance); `digest` never acks; `review-queue` redacts private item paths; `digest` redacts cross-area references and stays within the session's area.
+
+## 0.1.0-alpha.0
+
+- Added installable `neurain` CLI package.
+- Added `init`, `adopt`, `doctor`, `search`, `connect`, and `mcp` alpha commands.
+- Added Codex and Claude Code MCP connection dry-runs.
+- Added stdio MCP server with status, search, capture, and adopt scan tools.
+- Added adoption receipts and rollback.
+- Added public alpha docs for quickstart, safety, privacy, and troubleshooting.

package/LICENSE

@@ -0,0 +1,57 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" or "Your" shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works in any medium, with or without modifications, provided that You meet the conditions of this License, including giving recipients a copy of this License and retaining required notices.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" basis, without warranties or conditions of any kind, either express or implied.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory shall any Contributor be liable to You for damages arising as a result of this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works, You may choose to offer support, warranty, indemnity, or other liability obligations, but only on Your own behalf and on Your sole responsibility.

package/README.md

@@ -0,0 +1,205 @@
+# Neurain Knowledge OS
+
+Neurain Knowledge OS is a local-first knowledge operating layer for AI agents. It helps Codex, Claude Code, Gemini CLI, Agent Runtime, or another AI host work with a user-owned folder without turning that folder into a hidden cloud memory database.
+
+Neurain is not an LLM and does not compete with Claude, GPT, Gemini, or local models. It sits underneath agent runtimes as a source-grounded, portable memory and wiki layer.
+
+Layer model:
+
+- Model layer: Claude, GPT, Gemini, DeepSeek, local models.
+- Agent runtime layer: Codex, Claude Code, Gemini CLI, Agent Runtime, OpenClaw.
+- Knowledge OS layer: Neurain Knowledge OS.
+
+Alpha promise:
+
+- Bring a folder.
+- Initialize a clean Neurain vault.
+- Scan an existing work folder before any write.
+- Connect Codex, Claude Code, Gemini CLI, or Agent Runtime through MCP.
+- Connect Gemini CLI through MCP with a bounded read-first tool allowlist.
+- Keep source material local and review risky writes.
+- Let sessions improve over time through reviewed lesson candidates.
+- Surface local watch reports for recent files, events, review triggers, and unsafe signal handling.
+- Turn local signals into read-only review worker proposals before any durable improvement is promoted.
+- Run one-shot scheduler ticks that decide whether review should run without starting daemons or writing.
+- Run bounded foreground scheduler monitors that repeat read-only ticks only while the user keeps the command running.
+- Keep a user-started foreground daemon running so review checks repeat while the user works, with only operational state written.
+- Measure background review trigger precision, recall, no-recursion, and private-boundary handling before claiming automation quality.
+- Record host lifecycle boundary events and report session lineage without pretending Neurain owns the host model loop.
+- Evaluate Claude Code, Codex, Runtime, and generic host lifecycle hook payloads for safe event mapping, ignored handling of malformed, unsupported, and missing-session payloads, and non-persistence of prompt bodies, transcript paths, tool output, secrets, and private payloads, without writing to the target root.
+- Manage lesson lifecycle with curator dry-runs, snapshots, rollback, pinned protection, and no deletion.
+- Build an optional local SQLite FTS5 recall cache for faster cross-session search while keeping markdown as canonical truth.
+- Find paraphrased queries with a local lexical-semantic recall layer (stemming, synonyms, fuzzy) that is deterministic, makes no model call, and keeps the embedding provider swappable without LLM lock-in.
+- Use hybrid recall (exact-token union semantic) as the robust default that is never worse than exact-token and adds paraphrase catches on top. For hybrid search, `--top` is the candidate depth for each branch, so the returned union can be longer than `top` when semantic-only catches exist.
+- Measure recall coverage on a real folder's own content with read-only, metrics-only live-eval (no stored content, safe on a private vault) as a first step toward live user evidence.
+- Prepare reviewed live case packs with a redacted E23 scaffold that stores hash-only source refs, no raw source text, and no absolute local paths.
+- Measure cross-session recall with synthetic fixtures and reviewed case files without touching the target root.
+- Measure lesson candidate detection with a read-only precision, recall, false-positive, and unsafe-blocking eval.
+- Keep your knowledge portable across AI hosts instead of locked inside one chat product.
+
+## Quickstart
+
+```bash
+npx neurain onboard ~/NeurainDemo --lang en
+npx neurain init ~/NeurainDemo --lang en
+npx neurain doctor ~/NeurainDemo
+npx neurain connect codex ~/NeurainDemo --dry-run
+npx neurain connect claude ~/NeurainDemo --dry-run
+npx neurain connect gemini ~/NeurainDemo --dry-run
+npx neurain connect runtime ~/NeurainDemo --dry-run
+npx neurain connect codex ~/NeurainDemo --lifecycle-hooks --dry-run
+npx neurain connect claude ~/NeurainDemo --lifecycle-hooks --dry-run
+npx neurain connect runtime ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+`onboard` is the non-developer first screen. It is read-only and tells a new user whether to initialize, scan, connect, or preview wrap next.
+
+When the Codex, Claude, or Gemini dry-run command looks right, run the same command without `--dry-run`. Gemini uses a bounded MCP tool allowlist. Runtime connector alpha prints a bounded MCP config snippet for an agent host that supports MCP instead of editing host config directly.
+
+Lifecycle hook previews are connector-specific. Claude Code prints a `.claude/settings.local.json` style snippet for SessionStart, UserPromptSubmit, Stop, and SessionEnd. Codex prints a `.codex/hooks.json` style snippet for SessionStart plus review_due after Edit or Write PostToolUse. Runtime prints a host-proxy contract for agent loops that can forward direct lifecycle boundary events. All adapters map host payloads into Neurain lifecycle receipts without storing prompt bodies, transcript paths, tool stdout, or tool stderr in model context.
+
+## Self-Improving Workflow
+
+Neurain can preview what the next session should learn from recent work. This is the first alpha step toward a host-agnostic self-improving workflow, adapted for a local-first Knowledge OS rather than a single owned agent loop:
+
+```bash
+npx neurain wrap ~/NeurainDemo --dry-run
+npx neurain watch ~/NeurainDemo --poll-once
+npx neurain review ~/NeurainDemo --json
+npx neurain scheduler tick ~/NeurainDemo --json
+npx neurain scheduler monitor ~/NeurainDemo --interval-seconds 60 --max-ticks 3 --json
+npx neurain scheduler eval ~/NeurainDemo --fixture-size 100 --json
+npx neurain scheduler eval ~/NeurainDemo --case-file scheduler-cases.json --min-cases 5 --json
+npx neurain daemon run ~/NeurainDemo --interval-seconds 300 --max-ticks 2 --json
+npx neurain daemon status ~/NeurainDemo --json
+npx neurain lifecycle report ~/NeurainDemo --json
+npx neurain lifecycle eval ~/NeurainDemo --fixture-size 100 --json
+npx neurain lifecycle eval ~/NeurainDemo --case-file lifecycle-cases.json --min-cases 6 --json
+npx neurain connect codex ~/NeurainDemo --lifecycle-hooks --dry-run --json
+npx neurain connect claude ~/NeurainDemo --lifecycle-hooks --dry-run --json
+npx neurain connect gemini ~/NeurainDemo --lifecycle-hooks --dry-run --json
+npx neurain connect runtime ~/NeurainDemo --lifecycle-hooks --dry-run --json
+npx neurain curator status ~/NeurainDemo --json
+npx neurain curator run ~/NeurainDemo --dry-run --json
+npx neurain recall status ~/NeurainDemo --json
+npx neurain recall rebuild ~/NeurainDemo --dry-run --json
+npx neurain recall search ~/NeurainDemo "rollback lesson" --json
+npx neurain recall semantic-search ~/NeurainDemo "fixed the login bug" --json
+npx neurain recall hybrid-search ~/NeurainDemo "fixed the login bug" --json
+npx neurain recall eval ~/NeurainDemo --json
+npx neurain recall eval ~/NeurainDemo --fixture-size 100 --private-probes 20 --json
+npx neurain recall eval ~/NeurainDemo --case-file recall-cases.json --min-cases 1 --json
+npx neurain recall eval ~/NeurainDemo --semantic --fixture-size 60 --min-cases 50 --json
+npx neurain recall live-eval ~/NeurainDemo --sample-size 60 --json
+npx neurain live-cases scaffold ~/NeurainDemo --sample-size 12 --json
+npx neurain live-cases scaffold ~/NeurainDemo --write --confirm "1건 저장 진행" --output output/live-cases/e23-live-case-pack.json --json
+npx neurain answer eval ~/NeurainDemo --fixture-size 120 --json
+npx neurain answer eval ~/NeurainDemo --case-file answer-cases.json --min-cases 5 --json
+npx neurain lessons eval ~/NeurainDemo --fixture-size 100 --json
+npx neurain lessons eval ~/NeurainDemo --case-file lesson-cases.json --min-cases 4 --json
+npx neurain journal list ~/NeurainDemo
+npx neurain lessons candidates ~/NeurainDemo
+npx neurain capabilities "rollback lesson"
+```
+
+Event journal writes are append-only and require explicit confirmation:
+
+```bash
+npx neurain journal add ~/NeurainDemo --type test --summary "npm test passed after setup" --confirm "1건 저장 진행"
+npx neurain journal verify ~/NeurainDemo
+npx neurain lifecycle emit ~/NeurainDemo --host codex --event turn_end --session-id codex-session-1 --turn-id turn-1 --confirm "1건 저장 진행"
+```
+
+Safe lesson candidates can be promoted through CLI only after human review:
+
+```bash
+npx neurain lessons promote ~/NeurainDemo --candidate-id <candidate-id> --confirm "1건 저장 진행"
+npx neurain lessons rollback ~/NeurainDemo --receipt output/receipts/lessons/<receipt>.json
+```
+
+MCP remains preview-only. It does not silently promote durable lessons.
+
+## Development Status
+
+The canonical product development snapshot is maintained in:
+
+- `docs/development-status.en.md`
+- `docs/development-status.kr.md`
+
+As of 2026-06-09 KST, the package is a publish-ready alpha for private beta or alpha user tests. It is not public SaaS GA. The current verified gates are `npm test` 37/37, `node scripts/readiness.mjs --json` score 100, and `npm run readiness -- --json` score 100.
+
+Watch reports are also read-only. They do not start a daemon and do not write durable knowledge. They observe recent text files, event journal entries, recap hints, and lesson candidates so a future review worker can decide what deserves attention.
+
+Review worker reports are read-only too. They convert watch signals, journal events, and lesson candidates into manual improvement proposals. They do not call a model, start a daemon, promote a lesson, or write durable wiki knowledge.
+
+Scheduler ticks are read-only. They inspect watch signals, decide whether a local review fork should run, and include a review worker report only when thresholds are met. They do not install background jobs, start daemons, call models, promote lessons, or write durable wiki knowledge.
+
+Scheduler eval is a separate read-only quality gate. `scheduler eval` checks whether background review triggers turn on for meaningful correction, rollback, review, lesson, test, curator, and journal-integrity signals while staying quiet for ordinary notes. It also checks no-recursion on triggered review reports, private boundary handling only on private-marker cases, case-file size limits, temp cleanup, and broad target-root non-write snapshots. Synthetic fixtures use `--fixture-size`; reviewed live cases can be supplied with `--case-file`.
+
+Scheduler monitors are bounded foreground runs. They repeat read-only scheduler ticks for a user-specified number of ticks, do not install background jobs, do not run after the command exits, and do not write durable wiki knowledge.
+
+Daemon run is a user-started foreground loop. It repeats scheduler ticks until stopped or until `--max-ticks` is reached. Stop requests are checked during the sleep interval with about one-second polling. It writes only `00_system/neurain/daemon-state.json` as operational state, never writes wiki knowledge, never promotes lessons, never calls models, never calls external tools, and is not exposed through MCP.
+
+Lifecycle reports are read-only. Lifecycle emits are append-only host boundary receipts for events such as `session_start`, `turn_start`, `turn_end`, `wrap_complete`, `review_due`, `compaction`, and `resume`. Emits require the exact confirmation phrase. MCP exposes `neurain_lifecycle_report` only, not lifecycle emit, so connected hosts can inspect lineage without writing to it through MCP.
+
+Lifecycle hook adapters are connector-specific. In alpha, Claude Code gets a dry-run settings preview that can call `neurain lifecycle hook` from Claude Code hooks. Codex gets a `.codex/hooks.json` preview for SessionStart and Edit or Write PostToolUse review markers. Runtime gets a host-proxy contract for runtimes that can forward direct lifecycle events. The adapters record only boundary metadata and operational turn-pairing state, not prompt body text, transcript file paths, tool stdout, tool stderr, or success stdout in model context. They do not expose a lifecycle write tool through MCP. For lower hook latency, install Neurain globally or replace `npx -y neurain` in the preview snippet with your local `neurain` binary path.
+
+Curator reports manage lesson lifecycle safely. `curator status` and `curator run --dry-run` are read-only. A real curator run requires the exact confirmation phrase, writes a snapshot receipt, changes only lesson `Status` fields, protects pinned, human-authored, private, and non-agent-created lessons, never deletes lessons, and can be rolled back from the receipt.
+
+Recall search is an optional generated cache. `recall status`, `recall search`, `recall verify`, and `recall eval` are read-only. `recall rebuild` writes only `00_system/neurain/recall.sqlite` and a rebuild receipt, and markdown remains the source of truth. If the SQLite file is deleted, Neurain falls back to markdown search and can rebuild the cache later. Private paths, raw source bodies, secret-like content, instruction-injection content, and recall rebuild receipts are excluded from the index. `recall eval` checks whether safe host-tagged events can be found under the right host filter without leaking into the wrong host. `recall eval --fixture-size 100 --private-probes 20` runs a larger synthetic regression suite without touching the target root. `recall eval --case-file recall-cases.json` runs reviewed recall cases supplied by a human reviewer, also without touching the target root. Both modes gate on host filtering, source-supporting snippets, host isolation, and private leakage. They do not count as semantic recall quality benchmarks by themselves.
+
+Answer eval is a separate read-only quality gate. `answer eval` checks whether source-grounded answers stay faithful to cited sources, cite sources accurately, surface conflicts, abstain when evidence is missing, respect private boundaries, and prefer current sources over stale ones. Synthetic fixtures use `--fixture-size`; reviewed live cases can be supplied with `--case-file`. It does not call a model, does not write to the target root, and does not replace external user testing.
+
+Lessons eval is a separate read-only self-improvement gate. `lessons eval` checks whether Neurain can detect real lesson candidates, avoid ordinary notes as false positives, and block unsafe secret-like or instruction-injection candidates. Synthetic fixtures use `--fixture-size`; reviewed live cases can be supplied with `--case-file`. It does not call a model and does not write to the target root.
+
+Live case scaffolding is the E23 storage-safety bridge between real folders and reviewed case files. `live-cases scaffold` samples eligible local markdown, stores only hash-only source refs, and outputs recall, answer, and lesson case templates that a human reviewer must fill locally. It deliberately reports `reviewed_live_user_evidence: false` and `human_judged: false`; it prepares safe evidence handling but does not fabricate external user proof. With `--write`, it requires the exact confirmation phrase and writes only the redacted pack under `output/live-cases/`.
+
+For multi-area vaults, preview commands do not scan every area by default. Use `--area <name>` when you want recap or lesson candidates for one specific area.
+
+See also:
+
+- `docs/knowledge-os.en.md`
+- `docs/self-improve-90-roadmap.en.md`
+- `docs/connect-runtime.en.md`
+
+## Existing Folder Adoption
+
+```bash
+npx neurain adopt ~/Work --dry-run
+```
+
+Neurain scans first and recommends one of three modes:
+
+- `in-place`: clean folder, low risk.
+- `hybrid`: source stays in place, Neurain adds adapters.
+- `copy`: risky folder, secrets, symlinks, or private material detected.
+
+Writes require an explicit confirmation phrase shown by the scan.
+
+## MCP
+
+The alpha MCP server is stdio-only:
+
+```bash
+npx neurain mcp --root ~/NeurainDemo
+```
+
+It exposes read/capture/scan/preview tools only. It does not silently compile, promote lessons, or overwrite durable wiki knowledge. MCP paths are confined to the configured `--root`.
+
+## Status
+
+This is `0.1.0-alpha.0`. It is not a public SaaS GA release. The alpha exists to prove installability, local-first onboarding, Codex, Claude, Gemini, and Runtime connectivity, plus safety receipts.
+
+Alpha publish command:
+
+```bash
+npm publish --tag alpha
+```
+
+## Release Readiness Check
+
+```bash
+npm run readiness
+```
+
+This runs tests, packaging checks, audit, tarball install smoke, host connect dry-runs, and a product leakage scan.

package/SECURITY.md

@@ -0,0 +1,22 @@
+# Security
+
+Neurain alpha is local-first. The package does not include a hosted knowledge store.
+
+## Reporting
+
+Report security issues privately before opening a public issue. Until the public GitHub organization is live, use the maintainer contact listed in the release notes.
+
+## Data Boundary
+
+- Neurain writes local files inside the folder you choose.
+- MCP tools expose status, search, append-only capture, adoption scan, lesson preview, recap, and capability preview.
+- MCP alpha does not expose silent durable wiki writes or silent lesson promotion.
+- Secret-like capture input is refused.
+- The alpha has no web admin page. Any future admin surface must require authentication before showing controls or sensitive state.
+- Do not place API keys, recovery codes, private keys, or passwords in source files or docs.
+
+## Supported Versions
+
+| Version | Supported |
+|---|---|
+| 0.1.x alpha | Security fixes only |

package/bin/neurain.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.mjs';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  process.stderr.write(`${error.message || error}\n`);
+  process.exit(1);
+});

package/docs/comparison-mem0.en.md

@@ -0,0 +1,22 @@
+# Neurain And Mem0
+
+Mem0 is a production memory infrastructure for AI agents and apps. Neurain is a local-first AI Knowledge OS.
+
+## What Neurain Learns From Mem0
+
+- one-line install
+- agent-friendly setup
+- MCP as the universal connector
+- clear pricing and trust surface
+- proof through benchmarks and docs
+
+## Where Neurain Is Different
+
+- Markdown remains the source of truth.
+- The user's folder is not replaced by a hidden memory database.
+- Durable knowledge writes are review-gated.
+- The product is designed for source-grounded wiki maintenance, not only memory retrieval.
+
+## Product Implication
+
+Neurain should copy Mem0's low-friction product surface, not its storage model.

package/docs/connect-claude.en.md

@@ -0,0 +1,48 @@
+# Connect Claude Code
+
+Preview:
+
+```bash
+npx neurain connect claude ~/NeurainDemo --dry-run
+```
+
+Apply:
+
+```bash
+npx neurain connect claude ~/NeurainDemo
+```
+
+The command uses Claude Code's official MCP CLI:
+
+```bash
+claude mcp add --scope local -e NEURAIN_ROOT=<folder> neurain -- npx -y neurain mcp --root <folder>
+```
+
+Use `--scope user` or `--scope project` when you want a wider or project-specific configuration.
+
+## Lifecycle Hook Preview
+
+Claude Code has command hooks for session and turn boundaries. Neurain can preview a lifecycle hook setup:
+
+```bash
+npx neurain connect claude ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+The preview prints a `.claude/settings.local.json` style snippet for:
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `Stop`
+- `SessionEnd`
+
+When those hooks call `neurain lifecycle hook`, Neurain maps Claude Code hook payloads into lifecycle events such as `session_start`, `turn_start`, `turn_end`, `resume`, `compaction`, and `session_end`.
+
+Safety boundary:
+
+- The connect command does not edit Claude settings in lifecycle hook alpha.
+- The hook adapter stores no prompt body text.
+- The hook adapter stores no transcript path.
+- The hook adapter runs with `--quiet`, so successful SessionStart and UserPromptSubmit hooks do not inject status text into Claude's model context.
+- The hook adapter writes append-only lifecycle receipts only when the user has copied a command containing the exact confirmation phrase.
+- MCP can report lifecycle lineage, but cannot emit lifecycle events.
+- For lower hook latency, install Neurain globally or replace `npx -y neurain` in the preview snippet with your local `neurain` binary path.

package/docs/connect-claude.kr.md

@@ -0,0 +1,51 @@
+# Claude Code 연결
+
+Claude Code는 MCP를 통해 Neurain을 local-first Knowledge OS로 사용할 수 있습니다.
+
+MCP setup을 preview합니다.
+
+```bash
+npx neurain connect claude ~/NeurainDemo --dry-run
+```
+
+MCP setup을 적용합니다.
+
+```bash
+npx neurain connect claude ~/NeurainDemo
+```
+
+이 명령은 Claude Code의 공식 MCP CLI를 사용합니다.
+
+```bash
+claude mcp add --scope local -e NEURAIN_ROOT=<folder> neurain -- npx -y neurain mcp --root <folder>
+```
+
+더 넓은 범위나 project-specific 설정이 필요하면 `--scope user` 또는 `--scope project`를 사용합니다.
+
+## Lifecycle Hook Preview
+
+Claude Code는 session과 turn boundary용 command hook을 제공합니다. Neurain은 lifecycle hook setup을 preview할 수 있습니다.
+
+```bash
+npx neurain connect claude ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+Preview는 아래 hook을 위한 `.claude/settings.local.json` style snippet을 출력합니다.
+
+- `SessionStart`
+- `UserPromptSubmit`
+- `Stop`
+- `SessionEnd`
+
+이 hook들이 `neurain lifecycle hook`을 호출하면 Neurain은 Claude Code hook payload를 `session_start`, `turn_start`, `turn_end`, `resume`, `compaction`, `session_end` 같은 lifecycle event로 매핑합니다.
+
+Safety boundary:
+
+- Lifecycle hook alpha에서 connect command는 Claude settings를 직접 수정하지 않습니다.
+- Hook adapter는 prompt body text를 저장하지 않습니다.
+- Hook adapter는 transcript path를 저장하지 않습니다.
+- Hook adapter는 custom instruction을 저장하지 않습니다.
+- Hook adapter는 `--quiet`으로 실행되므로 성공한 SessionStart와 UserPromptSubmit hook이 Claude model context에 status text를 주입하지 않습니다.
+- Hook adapter는 사용자가 정확한 확인 문구가 포함된 command를 직접 복사했을 때만 append-only lifecycle receipt를 씁니다.
+- MCP는 lifecycle lineage를 report할 수 있지만 lifecycle event를 emit할 수 없습니다.
+- Hook latency를 낮추려면 Neurain을 global install하거나 preview snippet의 `npx -y neurain`을 local `neurain` binary path로 바꿉니다.

package/docs/connect-codex.en.md

@@ -0,0 +1,38 @@
+# Connect Codex
+
+Preview:
+
+```bash
+npx neurain connect codex ~/NeurainDemo --dry-run
+```
+
+Apply:
+
+```bash
+npx neurain connect codex ~/NeurainDemo
+```
+
+The command uses Codex's official MCP CLI:
+
+```bash
+codex mcp add neurain --env NEURAIN_ROOT=<folder> -- npx -y neurain mcp --root <folder>
+```
+
+Neurain does not manually edit Codex config files in alpha.
+
+## Lifecycle Boundary
+
+Codex MCP connection is supported in alpha. Neurain can also preview a `.codex/hooks.json` lifecycle setup:
+
+Preview the lifecycle hook setup:
+
+```bash
+npx neurain connect codex ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+The preview does not edit Codex config. It prints a hook snippet that maps:
+
+- `SessionStart` to `session_start`
+- `PostToolUse` after `Edit|Write` to `review_due`
+
+The hook calls `neurain lifecycle hook` with the exact confirmation phrase. Neurain stores only lifecycle metadata, not prompt bodies, transcript paths, tool stdout, or tool stderr. Codex can also read `neurain_lifecycle_report` through MCP, but MCP cannot emit lifecycle events.

package/docs/connect-codex.kr.md

@@ -0,0 +1,40 @@
+# Codex 연결
+
+Codex는 MCP를 통해 Neurain을 local-first Knowledge OS로 사용할 수 있습니다.
+
+MCP setup을 preview합니다.
+
+```bash
+npx neurain connect codex ~/NeurainDemo --dry-run
+```
+
+MCP setup을 적용합니다.
+
+```bash
+npx neurain connect codex ~/NeurainDemo
+```
+
+이 명령은 Codex의 공식 MCP CLI를 사용합니다.
+
+```bash
+codex mcp add neurain --env NEURAIN_ROOT=<folder> -- npx -y neurain mcp --root <folder>
+```
+
+Alpha에서 Neurain은 Codex config file을 직접 수정하지 않습니다.
+
+## Lifecycle Boundary
+
+Codex MCP connection은 alpha에서 지원됩니다. Neurain은 `.codex/hooks.json` lifecycle setup도 preview할 수 있습니다.
+
+Lifecycle hook setup을 preview합니다.
+
+```bash
+npx neurain connect codex ~/NeurainDemo --lifecycle-hooks --dry-run
+```
+
+Preview는 Codex config를 직접 수정하지 않습니다. 대신 아래 boundary를 매핑하는 hook snippet을 출력합니다.
+
+- `SessionStart` -> `session_start`
+- `Edit|Write` 뒤의 `PostToolUse` -> `review_due`
+
+Hook은 정확한 confirmation phrase가 포함된 `neurain lifecycle hook`을 호출합니다. Neurain은 lifecycle metadata만 저장하고 prompt body, transcript path, tool stdout, tool stderr는 저장하지 않습니다. Codex는 MCP를 통해 `neurain_lifecycle_report`를 읽을 수 있지만, MCP로 lifecycle event를 emit할 수는 없습니다.

package/docs/connect-gemini.en.md

@@ -0,0 +1,71 @@
+# Connect Gemini CLI
+
+Version: v0.1
+
+Gemini CLI can connect to Neurain through MCP. Neurain uses a bounded tool allowlist so Gemini can read status, search, recall, eval, and preview reports without receiving silent durable-write tools.
+
+## Preview
+
+```bash
+npx neurain connect gemini ~/NeurainDemo --dry-run
+```
+
+The dry-run prints the exact `gemini mcp add` command. It does not change Gemini settings.
+
+## Apply
+
+After reviewing the dry-run output, run the same command without `--dry-run`:
+
+```bash
+npx neurain connect gemini ~/NeurainDemo
+```
+
+By default this uses project scope. You can choose scope explicitly:
+
+```bash
+npx neurain connect gemini ~/NeurainDemo --scope user
+npx neurain connect gemini ~/NeurainDemo --scope project
+```
+
+## Manual Settings Fallback
+
+Gemini CLI also supports `mcpServers` in `settings.json`. Use this shape if you prefer manual config:
+
+```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 connection is supported. Native Gemini lifecycle hook automation is manual-only in this alpha, so use explicit lifecycle commands if you need boundary receipts:
+
+```bash
+npx neurain lifecycle emit ~/NeurainDemo --host gemini --event turn_end --session-id gemini-session-1 --turn-id turn-1 --confirm "1건 저장 진행"
+```
+
+## Safety
+
+- MCP can preview and evaluate.
+- MCP cannot silently promote lessons or write durable wiki knowledge.
+- The Gemini allowlist omits raw capture by default.
+- Redacted live-case scaffolds return hash-only source refs and no raw source text.