neurain 0.1.0-alpha.0

package/docs/self-improving-workflows.kr.md

@@ -0,0 +1,163 @@
+# [kr] 자기개선 워크플로우
+
+버전: 0.14
+
+Neurain Knowledge OS는 LLM을 학습시키거나 대체하지 않습니다. Codex, Claude Code, Gemini CLI, Agent Runtime, OpenClaw 같은 AI host가 더 잘 일하도록 안전한 local memory layer를 제공합니다.
+
+Agent Runtime는 model이 아니라 agent runtime입니다. Neurain의 역할은 이런 runtime들이 함께 쓸 수 있는 local-first Knowledge OS layer를 제공하는 것입니다.
+
+Runtime에서 흡수한 핵심 루프는 다음과 같습니다.
+
+1. 사용자가 로컬 폴더에서 작업합니다.
+2. Neurain은 source-grounded evidence를 읽거나 캡처합니다.
+3. `neurain wrap <folder> --dry-run`이 최근 작업 신호를 요약합니다.
+4. `neurain journal add`가 검토된 local event를 receipt와 함께 append할 수 있습니다.
+5. `neurain watch <folder> --poll-once`가 최근 파일, journal event, recap hint, lesson candidate를 읽어 read-only candidate report를 만듭니다.
+6. `neurain review <folder> --json`이 그 신호를 read-only review worker report로 바꾸고 manual improvement proposal을 만듭니다.
+7. `neurain scheduler tick <folder> --json`이 해당 신호가 review worker report를 포함할 만큼 강한지 판단합니다.
+8. `neurain scheduler eval <folder> --fixture-size 100`이 background review 품질을 주장하기 전에 trigger precision, trigger recall, no-recursion, private boundary, target-root non-write를 확인합니다.
+9. `neurain scheduler monitor <folder> --max-ticks 3`가 사용자가 명령을 켜 둔 동안 read-only tick을 foreground에서 반복할 수 있습니다.
+10. `neurain daemon run <folder>`이 같은 scheduler check를 사용자가 켜 둔 foreground loop로 계속 실행할 수 있습니다. 이때 operational state만 씁니다.
+11. `neurain lifecycle emit`이 turn end, wrap complete, compaction, resume 같은 검토된 host boundary event를 append할 수 있습니다.
+12. `neurain connect claude <folder> --lifecycle-hooks --dry-run`이 Claude Code의 SessionStart, UserPromptSubmit, Stop, SessionEnd hook을 lifecycle receipt로 매핑하는 설정 preview를 제공합니다. Prompt body, transcript path, 성공 stdout은 저장하거나 model context에 주입하지 않습니다.
+13. `neurain lifecycle report`가 session lineage를 요약하고 review 또는 recall이 이어져야 할 지점을 보여줍니다.
+14. 반복되는 실수나 workflow pattern이 보이면 lesson candidate를 제안합니다.
+15. durable lesson으로 CLI 승격하기 전 사용자가 후보를 검토합니다.
+16. `neurain curator`가 오래된 agent-created lesson을 snapshot rollback과 pinned protection 아래 stale 또는 archived로 표시할 수 있습니다.
+17. `neurain recall`이 optional local SQLite FTS5 cache를 만들어 이전 handoff, event, receipt, lesson을 더 빠르게 찾을 수 있게 합니다.
+18. `neurain recall eval`이 synthetic fixture 또는 reviewed case file로 safe host-tagged event가 올바른 host filter에서 회수되는지 확인합니다.
+19. `neurain answer eval`이 synthetic fixture 또는 reviewed case file로 model call 또는 target-root write 없이 answer faithfulness, citation accuracy, conflict surfacing, abstention, private boundary, stale-source handling을 확인합니다.
+20. `neurain lessons eval`이 model call 또는 target-root write 없이 lesson candidate detection precision, recall, false-positive rate, unsafe candidate blocking을 확인합니다.
+21. `neurain lifecycle eval`이 Claude Code, Codex, Runtime, generic host의 lifecycle hook payload가 올바른 lifecycle event로 매핑되는지, malformed/unsupported/missing-session payload가 durable write 없이 ignored result가 되는지, 그리고 prompt body, transcript path, tool stdout, tool stderr, secret, private payload가 절대 저장되지 않는지를 model call 또는 target-root write 없이 확인합니다.
+22. Agent Runtime는 bounded MCP config snippet으로 연결할 수 있고, Neurain은 backend Knowledge OS로 남습니다.
+23. 다음 세션은 active lesson cover, lifecycle lineage, recall result, scheduler-trigger gate, lesson-detection gate, answer-quality gate, lifecycle-automation gate를 먼저 읽고 같은 실수를 줄입니다.
+
+## Neurain이 저장하는 것
+
+- `00_system/neurain/lessons.md`의 active lessons
+- `00_system/neurain/events.ndjson`의 append-only workflow events
+- 같은 journal에 `lifecycle` event로 저장되는 append-only host lifecycle boundary events
+- 필요할 경우 area별 `memory/lessons/`의 상세 lesson card
+- `00_system/neurain/recall.sqlite`의 optional generated recall cache
+- `00_system/neurain/daemon-state.json`의 foreground daemon operational state
+- 사용자 또는 MCP capture tool이 제공한 raw source
+- adoption, lesson promotion, lesson rollback 같은 safety-critical write의 receipt
+
+## Alpha에서 하지 않는 것
+
+- lesson candidate를 조용히 durable lesson으로 승격하지 않습니다.
+- MCP는 preview-only이며 lesson을 승격하지 않습니다.
+- MCP를 통해 durable wiki knowledge를 조용히 덮어쓰지 않습니다.
+- web admin page를 노출하지 않습니다.
+- 사용자의 폴더를 hosted memory service로 업로드하지 않습니다.
+- recall SQLite cache를 canonical truth로 취급하지 않습니다.
+
+## Commands
+
+```bash
+neurain onboard ~/NeurainDemo --lang ko
+neurain connect codex ~/NeurainDemo --dry-run
+neurain connect claude ~/NeurainDemo --dry-run
+neurain connect gemini ~/NeurainDemo --dry-run
+neurain connect runtime ~/NeurainDemo --dry-run
+neurain lessons list ~/NeurainDemo
+neurain journal list ~/NeurainDemo
+neurain journal add ~/NeurainDemo --type test --summary "npm test passed" --confirm "1건 저장 진행"
+neurain journal verify ~/NeurainDemo
+neurain watch ~/NeurainDemo --poll-once
+neurain review ~/NeurainDemo --json
+neurain scheduler tick ~/NeurainDemo --json
+neurain scheduler status ~/NeurainDemo --json
+neurain scheduler monitor ~/NeurainDemo --interval-seconds 60 --max-ticks 3 --json
+neurain scheduler eval ~/NeurainDemo --fixture-size 100 --json
+neurain scheduler eval ~/NeurainDemo --case-file scheduler-cases.json --min-cases 5 --json
+neurain daemon run ~/NeurainDemo --interval-seconds 300 --max-ticks 2 --json
+neurain daemon status ~/NeurainDemo --json
+neurain daemon stop ~/NeurainDemo --json
+neurain lifecycle emit ~/NeurainDemo --host codex --event turn_end --session-id codex-session-1 --turn-id turn-1 --confirm "1건 저장 진행" --json
+neurain lifecycle report ~/NeurainDemo --json
+neurain lifecycle eval ~/NeurainDemo --fixture-size 100 --json
+neurain lifecycle eval ~/NeurainDemo --case-file lifecycle-cases.json --min-cases 6 --json
+neurain curator status ~/NeurainDemo --json
+neurain curator run ~/NeurainDemo --dry-run --json
+neurain curator run ~/NeurainDemo --confirm "1건 저장 진행" --json
+neurain curator rollback ~/NeurainDemo --receipt output/receipts/curator/<receipt>.json
+neurain recall status ~/NeurainDemo --json
+neurain recall rebuild ~/NeurainDemo --dry-run --json
+neurain recall rebuild ~/NeurainDemo --json
+neurain recall search ~/NeurainDemo "rollback lesson" --json
+neurain recall semantic-search ~/NeurainDemo "fixed the login bug" --json
+neurain recall hybrid-search ~/NeurainDemo "fixed the login bug" --json
+neurain recall verify ~/NeurainDemo --json
+neurain recall eval ~/NeurainDemo --json
+neurain recall eval ~/NeurainDemo --fixture-size 100 --private-probes 20 --json
+neurain recall eval ~/NeurainDemo --case-file recall-cases.json --min-cases 1 --json
+neurain recall eval ~/NeurainDemo --semantic --fixture-size 60 --min-cases 50 --json
+neurain recall eval ~/NeurainDemo --semantic --case-file semantic-recall-cases.json --min-cases 50 --json
+neurain recall live-eval ~/NeurainDemo --sample-size 60 --json
+neurain live-cases scaffold ~/NeurainDemo --sample-size 12 --json
+neurain live-cases scaffold ~/NeurainDemo --write --confirm "1건 저장 진행" --output output/live-cases/e23-live-case-pack.json --json
+neurain answer eval ~/NeurainDemo --fixture-size 120 --json
+neurain answer eval ~/NeurainDemo --case-file answer-cases.json --min-cases 5 --json
+neurain lessons eval ~/NeurainDemo --fixture-size 100 --json
+neurain lessons eval ~/NeurainDemo --case-file lesson-cases.json --min-cases 4 --json
+neurain connect runtime ~/NeurainDemo --dry-run
+neurain lessons candidates ~/NeurainDemo
+neurain lessons promote ~/NeurainDemo --candidate-id <candidate-id> --confirm "1건 저장 진행"
+neurain lessons rollback ~/NeurainDemo --receipt output/receipts/lessons/<receipt>.json
+neurain recap ~/NeurainDemo
+neurain wrap ~/NeurainDemo --dry-run
+neurain capabilities "rollback lesson"
+```
+
+multi-area vault에서는 preview command가 모든 area를 기본으로 스캔하지 않습니다. 특정 area를 보려면 `--area <name>`을 전달합니다. secret-like 또는 instruction-injection content가 포함된 preview line은 redaction됩니다.
+
+## Safety Rules
+
+secret-like content 또는 "이전 지시를 무시하라" 같은 instruction-injection 문구가 포함된 lesson candidate는 차단되거나 sanitization 대상으로 표시됩니다. Private source에서 나온 lesson은 사용자가 명시적으로 declassify하지 않는 한 private 범위에 머뭅니다. Promotion은 append block과 receipt만 쓰고, rollback은 receipt에 기록된 정확한 block만 제거합니다.
+
+Journal event도 같은 안전 방향을 따릅니다. Secret-like 또는 instruction-injection summary는 저장 전 redaction되고, prompt context에 넣을 수 없는 event로 표시되며, cross-host recall indexing에서도 차단됩니다.
+
+Dry-run journal output은 `line_hash_status`를 `planned`로 표시합니다. Durable journal write는 NDJSON append 전에 pending receipt를 먼저 만들고, append 성공 뒤 receipt를 final 상태로 갱신합니다. Pending receipt는 `line_hash_status`를 `expected_pending_append`로 표시하고, finalized receipt는 `observed_after_append`로 표시합니다.
+
+`neurain journal verify`는 저장된 event line이 event hash와 계속 일치하는지, 각 line이 valid JSON인지 확인합니다. Alpha integrity check이며, 완전한 tamper-proof chain은 아닙니다. 삭제, 순서 변경, standalone hash까지 맞춘 forged event 탐지는 이후 sequence-chain 작업이 필요합니다.
+
+Watch report는 read-only입니다. Alpha에서는 daemon을 시작하지 않고, journal event를 append하지 않고, lesson을 promote하지 않고, durable wiki knowledge를 쓰지 않습니다. Private 또는 unsafe event summary는 local CLI 사용자가 명시적으로 포함하지 않는 한 withheld 처리되며, MCP watch report에는 append capability가 없습니다. Withheld event도 review trigger 계산을 위해 event id, event type, timestamp, sensitivity 같은 최소 routing metadata는 노출할 수 있지만 private content는 노출하지 않습니다.
+
+Review worker report도 read-only입니다. Watch report, event sequence, recap hint, lesson candidate를 manual review item, blocked item, suggested action으로 바꿉니다. Model을 호출하지 않고, nested review worker를 시작하지 않고, external tool을 실행하지 않고, lesson을 promote하지 않고, durable knowledge를 쓰지 않습니다. MCP는 같은 read-only 표면으로 `neurain_review_worker`를 노출합니다.
+
+Scheduler tick도 read-only입니다. Watch signal을 보고 local review fork를 실행할지 판단하며, threshold를 넘을 때만 review worker report를 포함합니다. Background job을 설치하지 않고, daemon을 시작하지 않고, model을 호출하지 않고, lesson을 promote하지 않고, durable knowledge를 쓰지 않습니다. MCP는 같은 read-only tick 표면으로 `neurain_scheduler_tick`을 노출합니다.
+
+Scheduler eval은 read-only이며 scheduler tick과 별도입니다. Meaningful event, lesson candidate, journal-integrity failure, ordinary no-review note를 기준으로 background review trigger의 precision과 recall이 충분한지 확인합니다. 또한 실제 review report가 실행된 case의 no-recursion, private marker가 있는 case의 private boundary, case-file size limit, temp cleanup, broad target-root non-write snapshot을 검증합니다. Synthetic fixture는 `--fixture-size`를 쓰고, 검토된 live case는 `--case-file`로 넣을 수 있습니다. MCP는 같은 read-only eval 표면으로 `neurain_scheduler_eval`을 노출합니다.
+
+Scheduler monitor는 bounded foreground run입니다. 사용자가 지정한 tick 수만큼 read-only scheduler tick을 반복하고, background job을 설치하지 않고, 명령 종료 뒤 계속 실행되지 않고, durable knowledge를 쓰지 않습니다. Alpha에서 MCP는 scheduler monitor를 노출하지 않습니다.
+
+Daemon run은 continuous local review check를 위한 user-started foreground loop입니다. 사용자가 멈추거나 `--max-ticks`에 도달할 때까지 scheduler tick을 반복합니다. Stop request는 sleep interval 중에도 약 1초 단위로 확인합니다. `00_system/neurain/daemon-state.json`에 operational state만 쓰고, 그 state에 private path를 저장하지 않으며, background job을 설치하지 않고, durable wiki knowledge를 쓰지 않고, lesson을 promote하지 않고, model을 호출하지 않고, external tool을 호출하지 않고, MCP에 노출되지 않습니다.
+
+Lifecycle event는 Neurain이 직접 소유하지 않는 host에서도 agent-loop awareness를 흡수하기 위한 장치입니다. `neurain lifecycle emit`은 `session_start`, `turn_start`, `turn_end`, `wrap_complete`, `review_due`, `review_complete`, `compaction`, `resume`, `session_end` 같은 boundary receipt를 append합니다. Emit은 정확한 confirmation phrase가 필요합니다. `neurain lifecycle report`는 read-only이며 completed turn, open turn, parent session, compaction, resume, review-due event를 요약합니다. MCP는 `neurain_lifecycle_report`만 노출하고 lifecycle emit은 노출하지 않습니다.
+
+Lifecycle hook preview는 connector-specific입니다. `neurain connect claude <folder> --lifecycle-hooks --dry-run`은 Claude Code settings snippet을 출력하고, `neurain connect codex <folder> --lifecycle-hooks --dry-run`은 `.codex/hooks.json` snippet을 출력하며, `neurain connect runtime <folder> --lifecycle-hooks --dry-run`은 host-proxy contract를 출력합니다. Adapter는 host hook payload를 lifecycle receipt로 매핑하고 operational metadata만 저장하며, prompt body text, transcript path, tool stdout, tool stderr, 성공 stdout을 저장하거나 model context에 주입하지 않습니다.
+
+Lifecycle eval은 read-only이며 lifecycle emit과 별도입니다. E21 native lifecycle automation gate로, 완전한 background self-improvement loop를 만드는 단계가 아니라 lifecycle 관찰 계층이 안전한지를 증명하는 단계입니다. Claude Code, Codex, Runtime, generic host의 synthetic lifecycle payload와 reviewed case file을 실제 hook adapter로 격리된 임시 root에서 재생한 뒤, 모든 durable artifact(journal, connector state, receipt)를 다시 읽어 prompt body, transcript path, tool stdout, tool stderr, 그리고 secret-like/instruction-injection content가 전혀 저장되지 않음을 증명합니다. 이는 그 위험 content를 lifecycle summary로 흘러드는 host-controlled source/reason/matcher/tool-name/tool 필드에 넣은 경우까지 포함합니다. 그 필드의 짧은 host lineage 라벨은 설계상 sanitized/lowercased/length-capped/redaction 처리된 형태로 저장되므로, non-persistence 주장은 payload body content와 secret/injection content에 한정되며 그 짧은 trigger 라벨에는 적용되지 않습니다. 매칭은 대소문자를 무시하며, `non_persistence_proof_complete` 플래그가 모든 non-persistence 차원이 실제로 시험됐는지 보고하여 프로브 없는 reviewed case file이 완전한 증명으로 오인되지 않게 합니다. 또한 host coverage, lifecycle event coverage, malformed/unsupported/missing-session payload의 ignored 처리, path-traversal containment, broad target-root non-write snapshot, temp cleanup을 gate로 확인합니다. Synthetic fixture는 `--fixture-size`를 쓰고, 검토된 live case는 `--case-file`로 넣을 수 있습니다. MCP는 같은 read-only eval 표면으로 `neurain_lifecycle_eval`을 노출하며 여전히 lifecycle emit은 노출하지 않습니다. Neurain이 host loop를 소유한다고 주장하지 않고, 자동 background review, 자동 lesson promotion, 자동 rollback을 수행하지 않습니다.
+
+Curator lifecycle change는 snapshot-gated입니다. `neurain curator status`와 `neurain curator run --dry-run`은 read-only입니다. Confirmed curator run은 lesson `Status` field만 변경하고, lesson을 삭제하지 않으며, pinned, human-authored, private, non-agent-created lesson을 보호하고, 이전 registry snapshot이 포함된 rollback receipt를 씁니다. Curator run 이후 registry가 바뀌면 rollback은 사용자 edit를 덮어쓰지 않기 위해 거부됩니다. MCP는 read-only curator status와 run-preview tool만 노출합니다.
+
+Recall DB는 optional이고 rebuildable입니다. `neurain recall status`, `neurain recall search`, `neurain recall verify`, `neurain recall eval`은 read-only입니다. `neurain recall rebuild`는 generated SQLite cache와 rebuild receipt만 씁니다. Markdown, event, handoff, receipt는 계속 canonical입니다. Private path, raw source body, secret-like content, instruction-injection content, recall rebuild receipt는 indexing에서 제외됩니다. SQLite file이 삭제되면 search는 markdown fallback으로 동작하고 cache는 나중에 다시 rebuild할 수 있습니다. `neurain recall eval --fixture-size 100 --private-probes 20`은 target root를 건드리지 않고 synthetic cross-host regression suite를 실행합니다. `neurain recall eval --case-file recall-cases.json`은 사람이 검토한 recall case를 target root write 없이 실행합니다. 두 모드 모두 host filtering, source-supporting snippet, host isolation, private leakage를 gate로 확인합니다. 이 둘만으로 semantic recall quality benchmark라고 주장하지는 않습니다.
+
+Semantic recall은 별도의 read-only 계층(E22)입니다. `neurain recall semantic-search`와 `neurain recall eval --semantic`은 exact-token recall 위에 local lexical-semantic provider를 얹어 의역 쿼리를 찾습니다. 어간(fix/fixed/fixing) + 동의어맵(resolved↔fixed, defect↔bug, authentication↔login) + 오타용 char-trigram 퍼지를 결합합니다. 기본 `local-lexical` provider는 완전 결정론적이고, model call이 없고, 외부 의존성이 없고, 별도 generated index가 필요 없으며(markdown이 canonical), 특정 LLM에 종속되지 않습니다. embedding provider는 교체 가능해서 나중에 진짜 벡터모델을 canonical 변경 없이 끼울 수 있습니다. 정직한 범위: 이 계층은 형태소 변형, 큐레이션된 동의어, 오타까지 다루며 neural의 임의 개념유사는 아닙니다. 맵에 없는 개념은 여전히 pluggable embedding provider가 필요합니다. semantic eval은 read-only이고, synthetic 의역 fixture에서 semantic recall이 exact-token 기준선을 명확히 능가함(Hit@top 개선)을 증명하면서 host isolation, private 제외, no-answer abstention, rebuild 동등성, target-root non-write를 유지합니다. 메커니즘을 결정론적으로 증명할 뿐 실사용자 recall benchmark를 대체하지는 않습니다. MCP는 read-only `neurain_recall_semantic_search`와 `neurain_recall_semantic_eval`만 노출합니다.
+
+Hybrid recall이 권장되는 견고한 recall입니다. `neurain recall hybrid-search`는 exact-token 결과와 local lexical-semantic 결과의 합집합을 반환하므로 exact-token보다 절대 나쁘지 않고 의역 케이스를 위에 더합니다. `--top`은 각 branch의 후보 깊이라서 semantic-only catch가 있으면 반환되는 합집합은 `--top`보다 길어질 수 있습니다. 이건 아래 live-eval을 실제 콘텐츠에 돌려보니 순수 semantic만으로는 실제 코퍼스에서 exact-token보다 recall이 더 낮을 수 있음이 드러났기 때문입니다: lexical-semantic 계층은 exact-token BM25의 희귀도 가중치가 없어 어휘가 겹치는 실제 코퍼스에서 구분력이 떨어집니다. hybrid 합집합이 이를 고칩니다. MCP는 read-only `neurain_recall_hybrid_search`를 노출합니다.
+
+Live-content recall coverage(E23 첫 increment)는 synthetic fixture에서 실사용자 증거로 가는 첫걸음입니다. `neurain recall live-eval <folder>`는 read-only로, 실제 폴더의 자기 콘텐츠가 의역 쿼리(실제 단어를 동의어로 교체)로 얼마나 회수되는지를 측정해 hybrid coverage(권장 exact-union-semantic), exact-token coverage, semantic-only coverage, kind별 coverage를 보고합니다. 그래서 실사용자가 자기 자료에서 recall이 충분한지, 무엇을 놓치는지 볼 수 있습니다. hybrid coverage가 exact-token coverage 이상인지를 gate로 봅니다. 이걸 실제 콘텐츠에 돌린 게 바로 순수 semantic-only coverage가 exact-token보다 낮을 수 있음을 드러냈고, 그게 위의 hybrid recall로 이어졌습니다. 단어 단위 semantic 우위는 E22 semantic eval이 따로 증명합니다. 출력은 메트릭만이고 콘텐츠를 저장하지 않아 private vault에서도 안전하며, model/external call이 없습니다. 정직한 범위: 쿼리는 자동 생성이지 사람이 판단한 relevance가 아니고, 폴더 하나는 3명이 아닙니다. live-content coverage는 실제 콘텐츠 단계일 뿐 외부 사용자 walkthrough를 대체하지 않으므로 synthetic-only 주장은 줄었지만 아직 완전히 제거되진 않았습니다. 완전한 E23(최소 3개 실제 업무 폴더의 reviewed live case)은 사람의 몫으로 남습니다.
+
+Live case scaffolding은 reviewed live case를 안전하게 저장 가능한 형태로 준비하는 E23 storage-safety bridge입니다. `neurain live-cases scaffold <folder>`는 eligible local markdown을 샘플링하고 hash-only source ref와 recall, answer, lesson template만 출력합니다. Raw source text, absolute local path, private path name, secret-like content, instruction-injection content를 저장하지 않습니다. 의도적으로 `reviewed_live_user_evidence: false`, `human_judged: false`를 보고합니다. 사람이 안전한 local case file을 채우고 eval을 실행해야만 reviewed live evidence라고 주장할 수 있습니다. `--write`를 쓰면 정확한 확인 문구가 필요하고 `output/live-cases/` 아래 redacted pack만 씁니다.
+
+Answer eval은 recall eval과 별도입니다. `neurain answer eval`은 read-only로 policy-level answer quality를 확인합니다. 출처에 충실한 답변인지, citation이 실제 claim을 support하는지, conflict를 숨기지 않는지, evidence가 부족하면 abstain하는지, private boundary와 stale-source handling이 지켜지는지 봅니다. Synthetic fixture는 `--fixture-size`를 쓰고, 검토된 live case는 `--case-file`로 넣을 수 있습니다. Model을 호출하지 않고 target root에 write하지 않으며, external user walkthrough 없이 production answer quality를 증명하지는 않습니다.
+
+Lessons eval은 lesson promotion과 별도입니다. `neurain lessons eval`은 read-only로 candidate detection quality를 확인합니다. 실제 lesson 후보를 잘 찾는지, 평범한 note를 false positive로 잘 피하는지, secret-like 또는 instruction-injection candidate를 안전하게 차단하는지 봅니다. Synthetic fixture는 `--fixture-size`를 쓰고, 검토된 live case는 `--case-file`로 넣을 수 있습니다. Model을 호출하지 않고 target root에 write하지 않으며, external user case 없이 production lesson quality를 증명하지는 않습니다.
+
+Onboarding은 E24 first-run layer입니다. `neurain onboard <folder>`는 read-only이고, 비개발자에게 다음 행동이 `init`, `adopt --dry-run`, host connection, `wrap --dry-run` 중 무엇인지 알려줍니다. Model call, external call, durable write가 없습니다.
+
+Gemini CLI connector support는 E26 일부로 shipped 상태입니다. `neurain connect gemini <folder> --dry-run`은 bounded `gemini mcp add` command를 출력하고, status, search, adopt scan, recall, eval, live-case scaffold, lifecycle report/eval, lesson preview, scheduler preview, wrap preview를 포함한 read-first allowlist를 사용합니다. Gemini lifecycle hook automation은 alpha에서 manual-only이므로 필요 시 explicit `lifecycle emit --host gemini`이 receipt path입니다.
+
+Runtime connector alpha는 config-preview only입니다. `neurain connect runtime <folder> --dry-run`은 host-managed config용 작은 read-heavy Neurain allowlist가 포함된 bounded MCP server snippet을 출력합니다. Host config를 직접 수정하지 않고, 특정 runtime을 Neurain dependency로 만들지 않습니다.

package/docs/support.en.md

@@ -0,0 +1,17 @@
+# Support
+
+Alpha support channels:
+
+- GitHub Issues for bugs and feature requests.
+- Security reports through the private contact listed in `SECURITY.md`.
+- Release notes in `CHANGELOG.md`.
+
+When opening an issue, include:
+
+- operating system
+- Node version
+- command run
+- output
+- whether the target folder contains private or secret material
+
+Do not paste secrets, credentials, or private documents into public issues.

package/docs/troubleshooting.en.md

@@ -0,0 +1,35 @@
+# Troubleshooting
+
+## `npx neurain` is not found
+
+Use Node 20 or newer.
+
+```bash
+node --version
+```
+
+## `connect codex` fails
+
+Check that Codex CLI is installed:
+
+```bash
+codex --version
+codex mcp --help
+```
+
+## `connect claude` fails
+
+Check that Claude Code CLI is installed:
+
+```bash
+claude --version
+claude mcp --help
+```
+
+## Adoption refuses to apply
+
+Use the exact confirmation phrase printed by `neurain adopt <folder> --dry-run`.
+
+## Capture refuses text
+
+The text probably contains a secret-like pattern. Redact credentials before capturing.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "neurain",
+  "version": "0.1.0-alpha.0",
+  "description": "Local-first Neurain Knowledge OS CLI and MCP connector.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "bin": {
+    "neurain": "bin/neurain.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "docs/",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "pack:dry-run": "npm pack --dry-run",
+    "readiness": "node scripts/readiness.mjs --full"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5"
+  },
+  "devDependencies": {}
+}

package/src/cli.mjs

@@ -0,0 +1,261 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { adoptCommand, rollbackAdoption, scanAdoption } from './core/adopt.mjs';
+import { answerCommand } from './core/answer_eval.mjs';
+import { connectCommand } from './core/connect.mjs';
+import { capabilitiesCommand } from './core/capabilities.mjs';
+import { curatorCommand } from './core/curator.mjs';
+import { daemonCommand } from './core/daemon.mjs';
+import { doctorCommand } from './core/doctor.mjs';
+import { initCommand } from './core/init.mjs';
+import { journalCommand } from './core/journal.mjs';
+import { lessonsCommand } from './core/lessons.mjs';
+import { lifecycleCommand } from './core/lifecycle.mjs';
+import { liveCasesCommand } from './core/live_cases.mjs';
+import { onboardCommand } from './core/onboard.mjs';
+import { recapCommand } from './core/recap.mjs';
+import { recallCommand } from './core/recall.mjs';
+import { reviewCommand } from './core/review_worker.mjs';
+import { statusCommand } from './core/status.mjs';
+import { digestCommand } from './core/digest.mjs';
+import { queueCommand } from './core/queue.mjs';
+import { reviewQueueCommand } from './core/review_queue.mjs';
+import { routeCommand } from './core/route.mjs';
+import { planWritebackCommand } from './core/plan_writeback.mjs';
+import { flushCommand, sessionFlushCommand } from './core/flush.mjs';
+import { compileCommand } from './core/compile_desk.mjs';
+import { planReceiptCommand } from './core/plan_receipt.mjs';
+import { sourceDigestCommand } from './core/source_digest_gen.mjs';
+import { stageCommand } from './core/stage.mjs';
+import { queueArchiveCommand } from './core/queue_archive.mjs';
+import { captureCommand } from './core/capture_durable.mjs';
+import { completeCommand } from './core/complete.mjs';
+import { linkCheckCommand } from './core/link_check.mjs';
+import { schedulerCommand } from './core/scheduler.mjs';
+import { searchCommand } from './core/search.mjs';
+import { watchCommand } from './core/watch.mjs';
+import { wrapCommand } from './core/wrap.mjs';
+import { startMcpServer } from './mcp/server.mjs';
+
+export async function runCli(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    process.stdout.write(helpText());
+    return;
+  }
+  if (command === '--version' || command === '-v') {
+    const version = await packageVersion();
+    process.stdout.write(`${version}\n`);
+    return;
+  }
+
+  const args = parseArgs(rest);
+  if (command === 'init') return render(await initCommand(args));
+  if (command === 'onboard') return render(await onboardCommand(args));
+  if (command === 'adopt') {
+    if (args.rollback) return render(await rollbackAdoption(args));
+    return render(await adoptCommand(args));
+  }
+  if (command === 'answer') return render(await answerCommand(args));
+  if (command === 'doctor') return render(await doctorCommand(args));
+  if (command === 'search') return render(await searchCommand(args));
+  if (command === 'connect') return render(await connectCommand(args));
+  if (command === 'journal') return render(await journalCommand(args));
+  if (command === 'lifecycle') return render(await lifecycleCommand(args));
+  if (command === 'live-cases') return render(await liveCasesCommand(args));
+  if (command === 'lessons') return render(await lessonsCommand(args));
+  if (command === 'curator') return render(await curatorCommand(args));
+  if (command === 'daemon') return render(await daemonCommand(args));
+  if (command === 'recall') return render(await recallCommand(args));
+  if (command === 'status') return render(await statusCommand(args));
+  if (command === 'digest') return render(await digestCommand(args));
+  if (command === 'queue') return render(await queueCommand(args));
+  if (command === 'review-queue') return render(await reviewQueueCommand(args));
+  if (command === 'route') return render(await routeCommand(args));
+  if (command === 'plan-writeback') return render(await planWritebackCommand(args));
+  if (command === 'flush') return render(await flushCommand(args));
+  if (command === 'session-flush') return render(await sessionFlushCommand(args));
+  if (command === 'compile') return render(await compileCommand(args));
+  if (command === 'plan-receipt') return render(await planReceiptCommand(args));
+  if (command === 'source-digest') return render(await sourceDigestCommand(args));
+  if (command === 'stage') return render(await stageCommand(args));
+  if (command === 'queue-archive') return render(await queueArchiveCommand(args));
+  if (command === 'capture') return render(await captureCommand(args));
+  if (command === 'complete') return render(await completeCommand(args));
+  if (command === 'link-check') return render(await linkCheckCommand(args));
+  if (command === 'capabilities') return render(await capabilitiesCommand(args));
+  if (command === 'recap') return render(await recapCommand(args));
+  if (command === 'watch') return render(await watchCommand(args));
+  if (command === 'review') return render(await reviewCommand(args));
+  if (command === 'scheduler') return render(await schedulerCommand(args));
+  if (command === 'wrap') return render(await wrapCommand(args));
+  if (command === 'mcp') return startMcpServer(args);
+  if (command === 'selftest') return runSelftest();
+
+  throw new Error(`Unknown command: ${command}\n\n${helpText()}`);
+}
+
+export function parseArgs(tokens) {
+  const args = { _: [] };
+  for (let i = 0; i < tokens.length; i += 1) {
+    const token = tokens[i];
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+    const eq = token.indexOf('=');
+    if (eq > 2) {
+      args[token.slice(2, eq)] = token.slice(eq + 1);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = tokens[i + 1];
+    if (next && !next.startsWith('--')) {
+      args[key] = next;
+      i += 1;
+    } else {
+      args[key] = true;
+    }
+  }
+  return args;
+}
+
+function render(result) {
+  if (result == null) return;
+  if (result.json) {
+    process.stdout.write(`${JSON.stringify(result.payload, null, 2)}\n`);
+    return;
+  }
+  if (result.text === '') return;
+  process.stdout.write(result.text.endsWith('\n') ? result.text : `${result.text}\n`);
+}
+
+async function runSelftest() {
+  const result = spawnSync('node', ['--test'], {
+    cwd: path.resolve(new URL('..', import.meta.url).pathname),
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  process.stdout.write(result.stdout || '');
+  process.stderr.write(result.stderr || '');
+  process.exitCode = result.status || 0;
+}
+
+async function packageVersion() {
+  const pkg = await import('../package.json', { with: { type: 'json' } });
+  return pkg.default.version;
+}
+
+function helpText() {
+  return `Neurain CLI
+
+Usage:
+  neurain init <folder> [--area general] [--lang ko|en] [--dry-run]
+  neurain onboard <folder> [--lang ko|en] [--host codex|claude|gemini|runtime] [--json]
+  neurain adopt <folder> [--dry-run] [--apply --confirm "<N>건 저장 진행"]
+  neurain adopt --rollback <receipt> [--root <folder>]
+  neurain doctor <folder> [--json]
+  neurain search <folder> <query> [--top 10] [--json]
+  neurain journal list <folder> [--type type] [--top 20] [--json]
+  neurain journal add <folder> --type type --summary text --confirm "1건 저장 진행" [--source rel] [--host name] [--dry-run] [--json]
+  neurain journal verify <folder> [--json]
+  neurain lifecycle emit <folder> --host codex|claude|gemini|runtime|openclaw|cli|generic --event session_start|turn_start|turn_end|wrap_complete|review_due|review_complete|compaction|resume|session_end --session-id id [--turn-id id] [--parent-session-id id] --confirm "1건 저장 진행" [--dry-run] [--json]
+  neurain lifecycle hook <folder> --host claude|codex|runtime --confirm "1건 저장 진행" [--quiet] [--json]
+  neurain lifecycle report <folder> [--host name] [--session-id id] [--json]
+  neurain lifecycle eval <folder> [--fixture-size 100] [--case-file rel.json] [--min-cases 100] [--json]
+  neurain live-cases scaffold <folder> [--sample-size 12] [--label name] [--write --confirm "1건 저장 진행" --output output/live-cases/e23-live-case-pack.json] [--json]
+  neurain lessons list <folder> [--area name] [--json]
+  neurain lessons candidates <folder> [--area name] [--top 5] [--json]
+  neurain lessons eval <folder> [--fixture-size 100] [--case-file rel.json] [--min-cases 100] [--json]
+  neurain lessons promote <folder> --candidate-id <candidate-id> --confirm "1건 저장 진행" [--area name] [--dry-run] [--json]
+  neurain lessons rollback <folder> --receipt <receipt> [--json]
+  neurain curator status <folder> [--stale-days 30] [--archive-days 90] [--json]
+  neurain curator run <folder> --dry-run [--stale-days 30] [--archive-days 90] [--json]
+  neurain curator run <folder> --confirm "1건 저장 진행" [--stale-days 30] [--archive-days 90] [--json]
+  neurain curator rollback <folder> --receipt <receipt> [--json]
+  neurain recall status <folder> [--json]
+  neurain recall rebuild <folder> [--dry-run] [--json]
+  neurain recall search <folder> <query> [--top 10] [--host name] [--area name] [--json]
+  neurain recall semantic-search <folder> <query> [--top 10] [--host name] [--area name] [--provider local-lexical] [--min-score 0.34] [--json]
+  neurain recall hybrid-search <folder> <query> [--top 10] [--host name] [--area name] [--routing auto|on|off] [--provider local-lexical] [--min-score 0.34] [--json]
+  neurain recall lexical-search <folder> <query> [--top 10] [--area name] [--max-per-layer 3] [--json]
+  neurain recall bench <folder> --suites <dir> [--area name] [--top 5] [--baseline 0.94] [--matcher strict|loose] [--case ID --explain] [--json]
+  neurain recall scorecard <folder> --suites <dir> [--area name] [--top 5] [--matcher strict|loose] [--json]
+  neurain recall verify <folder> [--json]
+  neurain recall eval <folder> [--min-cases 2] [--fixture-size 100] [--case-file rel.json] [--private-probes 20] [--json]
+  neurain recall eval <folder> --semantic [--fixture-size 60] [--case-file rel.json] [--min-cases 50] [--provider local-lexical] [--json]
+  neurain recall live-eval <folder> [--sample-size 60] [--top 5] [--provider local-lexical] [--json]
+  neurain answer eval <folder> [--fixture-size 120] [--case-file rel.json] [--min-cases 50] [--json]
+  neurain status <folder> [--session-id id] [--all] [--stale-days 7] [--now ms] [--json]
+  neurain digest <folder> --session <id> [--sources area-brief,wrap-journal] [--window-hours 72] [--now ms] [--json]
+  neurain queue <folder> [--queue name] [--status s] [--pending] [--stats] [--lossless-check] [--json]
+  neurain review-queue <folder> [--session-id id] [--queue rel] [--manifest rel] [--top 12] [--json]
+  neurain route <folder> [--text "..." | <text> | --file rel] [--session-id id] [--area name] [--sensitivity s] [--intent i] [--title t] [--type memo] [--json]
+  neurain plan-writeback <folder> [--source-id id | --text "..." | --file rel] [--session-id id] [--area name] [--sensitivity s] [--intent i] [--title t] [--type memo] [--json]
+  neurain flush <folder> [--queue rel] [--json]
+  neurain session-flush <folder> --session-id id [--level light|standard|full] [--queue rel] [--json]
+  neurain compile <folder> [<target> | --target q | --text q] [--session-id id] [--top 5] [--manifest rel] [--queue rel] [--list] [--auto] [--desk] [--json]
+  neurain source-digest <folder> [--scope raw] [--manifest rel] [--write] [--rehash] [--top 20] [--json]
+  neurain plan-receipt <folder> --plan rel --actual rel [--label name] [--allow-unplanned] [--write] [--json]
+  neurain plan-receipt <folder> --selftest [--json]
+  neurain stage <folder> --target <relpath> [--text "..." | --file rel] [--allow-secret] [--json]
+  neurain queue-archive <folder> [--dry-run] [--older-than-days N] [--json]
+  neurain capture <folder> [--text "..." | <text> | --file rel] [--session-id id] [--type memo] [--title t] [--area name] [--sensitivity s] [--intent i] [--allow-secret] [--dry-run] [--json]
+  neurain complete <folder> --source-id id --compiled-to "a.md,b.md" [--status compiled] [--completed-at ts] [--dry-run] [--json]
+  neurain link-check <folder> [--scope .] [--top 20] [--include-raw] [--include-archive] [--include-output] [--json]
+  neurain recap <folder> [--area name] [--json]
+  neurain watch <folder> [--area name] [--since-minutes 1440] [--top 10] [--poll-once] [--json]
+  neurain review <folder> [--area name] [--since-minutes 1440] [--top 10] [--json]
+  neurain scheduler tick <folder> [--area name] [--since-minutes 1440] [--top 10] [--json]
+  neurain scheduler status <folder> [--area name] [--since-minutes 1440] [--top 10] [--json]
+  neurain scheduler monitor <folder> [--area name] [--since-minutes 1440] [--interval-seconds 60, clamped 0..3600] [--max-ticks 3, clamped 1..20] [--json]
+  neurain scheduler eval <folder> [--fixture-size 100] [--case-file rel.json] [--min-cases 100] [--json]
+  neurain daemon status <folder> [--json]
+  neurain daemon run <folder> [--area name] [--since-minutes 1440] [--interval-seconds 300] [--max-ticks 0] [--json]
+  neurain daemon stop <folder> [--json]
+  neurain wrap <folder> [--area name] [--dry-run] [--json]
+  neurain capabilities [query] [--json]
+  neurain connect codex <folder> [--dry-run]
+  neurain connect claude <folder> [--dry-run] [--scope local|user|project]
+  neurain connect gemini <folder> [--dry-run] [--scope user|project]
+  neurain connect runtime <folder> --dry-run
+  neurain connect claude <folder> --lifecycle-hooks --dry-run [--json]
+  neurain connect codex|gemini|runtime <folder> --lifecycle-hooks --dry-run [--json]
+  neurain mcp --root <folder>
+
+Alpha principles:
+  - Local markdown is the source of truth.
+  - Adoption scans are read-only unless --apply is confirmed.
+  - Event journal writes are append-only and require an exact confirmation phrase.
+  - Lifecycle events are append-only host boundary receipts; MCP can report them but cannot emit them.
+  - Lifecycle hook previews map host hooks to lifecycle receipts without storing prompt bodies, transcript paths, tool stdout, or tool stderr.
+  - Lifecycle eval checks that Claude, Codex, Runtime, and generic host lifecycle payloads map safely, that malformed, unsupported, and missing-session events become ignored results with no durable write, and that prompt bodies, transcript paths, tool output, secrets, and private payloads are never persisted, without writing to the target root.
+  - Watch reports are read-only candidate reports, not background auto-writes.
+  - Review worker reports turn watch signals into manual improvement proposals only.
+  - Scheduler ticks and bounded foreground monitors decide whether review should run, but do not write knowledge.
+  - Scheduler eval checks background review trigger precision, recall, no-recursion, private boundaries, case-file size, and broad target-root non-write without writing to the target root.
+  - Daemon run is a user-started foreground loop; it writes only operational state and never writes wiki, promotes lessons, calls models, or exposes MCP tools.
+  - Curator runs snapshot first, never deletes lessons, and requires confirmation for lifecycle writes.
+  - Recall DB is an optional rebuildable SQLite FTS5 cache; markdown remains canonical.
+  - Recall eval can run a larger cross-host fixture or reviewed case file without touching the target root.
+  - Recall semantic-search and recall eval --semantic add a local lexical-semantic layer (stemming, synonyms, fuzzy) that recalls paraphrased queries exact-token misses. The default provider is deterministic with no model call, no external dependency, and no LLM lock-in; markdown stays canonical and the embedding provider is swappable.
+  - Recall live-eval measures recall coverage on a real folder's own content using auto-derived paraphrase queries. It is read-only, returns metrics only with no stored content, and is one real-content step toward live user evidence; it does not replace human-judged external user walkthroughs.
+  - Recall hybrid-search is the robust recall: exact-token union local lexical-semantic. It is never worse than exact-token and adds paraphrase catches on top. Its --top value is the candidate depth for each branch, so the returned union can be longer than --top when semantic-only catches exist. Live-eval on real content showed pure semantic alone can recall less than exact-token, so hybrid is the recommended strategy.
+  - Recall routing (auto when a search index registry has areas, or with --area, or recall.routing.enabled): adds a BM25 + structural/layer/entity/domain/fact-ledger lexical branch ranked first in the union, so the corpus includes general area knowledge with label-based private exclusion. Routing is off by default on a bare vault, preserving exact-token union semantic.
+  - Recall bench scores a directory of benchmark suites (passed as a runtime arg, never bundled) against the routed lexical branch, reporting strict and loose source recall, entity recall, and a gate verdict against an optional baseline. Read-only; --case ID --explain prints per-signal traces and whether each expected source is in the corpus at all. Recall scorecard reports Hit@K, R@K, MRR, entity recall, and latency.
+  - The recall markdown corpus is config-extensible (recall.include/exclude) and privacy-gated by labels (per-file frontmatter sensitivity, area baseline from _area.md, and boundary path markers), so private content is excluded at index time, not just hidden at query time.
+  - Status, digest, queue, and review-queue are read-only views over vault state (session-state, wrap-journal, writeback queue + per-area registry, source-digest manifest). They never write: status does not advance the digest ack pointer and does not run maintenance, and digest never acks. Every format degrades gracefully when absent. Private review-queue items redact their file paths; digest redacts cross-area references and stays within the session's own area.
+  - Route, plan-writeback, flush, session-flush, and compile are read-only W-B desks: they classify and PLAN the capture/queue/compile pipeline (area/sensitivity/intent routing, writeback targets + gates, flush scope, and the compile candidate picker) but write nothing. Private and needs-confirmation items are surfaced separately, never silently compiled, and compile reads no raw bodies.
+  - Source-digest and plan-receipt are W-B writers that touch only their own non-canonical artifacts: source-digest writes the rebuildable source-digest manifest (dry by default, --write to update) and plan-receipt writes an optional receipt under output/receipts/. Every durable write goes through an atomic temp+fsync+rename plus a cross-process lock, and the manifest's path sensitivity is decided by the label resolver, never hardcoded area names.
+  - Stage is the secret gate: content lands in .neurain-staging (excluded from every walk), is scanned fail-closed for high-confidence secret shapes, mnemonics, context-aware hex keys, and high-entropy tokens, and is promoted to its canonical target by an atomic rename ONLY if clean; a hit holds the content in staging, leaves the target untouched, and exits 2. Queue-archive moves terminal queue rows into an append-only archive under one lock (archive appended before the hot-queue rewrite, so a crash never loses a row).
+  - Capture and complete are the durable pipeline writers. They write raw markdown (capture, routed through the stage secret gate), the _inbox envelope, the writeback queue (capture appends, complete rewrites - both under a lock), and a wiki/log line, but they NEVER write session-state, handoff, or area-brief files: those stay W-D-owned, returned as an unapplied session_state_delta whose pending_count is advisory (the future vault shuttle recomputes at apply time). Capture is text-only in this increment; file capture and overlap/numeric enrichment are the documented flip gate.
+  - Link-check (W-C) is a read-only graph validator: it resolves every markdown link and wikilink against the vault and reports unresolved targets by file and area, writing nothing. Area buckets use the configured structural dirs, not hardcoded area names.
+  - Live-cases scaffold creates a redacted E23 reviewed-case pack scaffold with hash-only source refs. It does not claim human evidence and stores no raw source text or absolute paths.
+  - Onboard is a read-only first-run guide for non-developers. It explains the next command without creating files or calling a model.
+  - Answer eval checks faithfulness, citation accuracy, conflict surfacing, abstention, private boundaries, and stale-source handling without model calls or writes.
+  - Lessons eval checks candidate precision, recall, false positives, and unsafe blocking without model calls or writes.
+  - Gemini connector uses Gemini CLI MCP config with a bounded tool allowlist. Runtime connector alpha emits a bounded MCP config snippet instead of editing host config.
+  - Lessons are previewed before promotion, and promotion requires an exact confirmation phrase.
+  - MCP alpha exposes read/capture/scan/preview tools only, not silent durable wiki writes.
+`;
+}