neurain 0.1.0-alpha.0

package/docs/knowledge-os.kr.md

@@ -0,0 +1,106 @@
+# [kr] Neurain Knowledge OS
+
+버전: 0.2
+
+Neurain Knowledge OS는 Neurain을 외부에 설명할 때 쓰는 제품 브랜드명입니다.
+
+현재 shipped 범위, 테스트 증거, 남은 gap은 `docs/development-status.kr.md`를 기준으로 봅니다.
+
+고객에게 가장 짧게 설명하면 이렇습니다.
+
+> 내 폴더를 그대로 가져오고, 내 지식을 지키고, 어떤 AI agent든 붙여서 쓴다.
+
+## 무엇인가
+
+Neurain Knowledge OS는 사용자의 실제 업무 폴더 위에서 동작하는 local-first 지식 운영 레이어입니다.
+
+AI agent가 다음을 안정적으로 하도록 돕습니다.
+
+- 폴더 구조 이해
+- 오래 남길 wiki 유지
+- 출처 보존
+- 중요한 업무 기록 캡처
+- 이전 세션에서 배운 lesson 노출
+- 위험한 저장 전 확인
+- 다른 agent에서도 이어서 작업
+- 백업과 복구 기준 유지
+
+## 무엇이 아닌가
+
+Neurain은 LLM이 아닙니다.
+
+Claude, GPT, Gemini, DeepSeek, local model을 대체하지 않습니다. 특정 모델 하나에 종속될 필요도 없습니다.
+
+또한 Neurain은 숨겨진 cloud memory database가 아닙니다. 기본 방향은 local-first입니다. 사용자의 폴더와 Neurain vault가 source of truth입니다.
+
+## 3개 레이어
+
+정확한 설명은 3개 레이어로 해야 합니다.
+
+| 레이어 | 예시 | 역할 |
+|---|---|---|
+| Model layer | Claude, GPT, Gemini, DeepSeek, local models | 생각하고 답변 생성 |
+| Agent runtime layer | Agent Runtime, Codex, Claude Code, Gemini CLI, OpenClaw | prompt assembly, model call, tool execution, turn 관리 |
+| Knowledge OS layer | Neurain Knowledge OS | 출처 기반 지식, wiki, memory, lesson, receipt, recovery state 관리 |
+
+여기서 Agent Runtime은 prompt assembly, model call, tool execution, session lifecycle을 소유하는 일반 AI host를 뜻합니다. 이 문서의 "Agent Runtime"은 항상 runtime을 뜻하며, LLM을 뜻하지 않습니다. 그래서 이 runtime을 Claude나 Gemini 모델과 직접 비교하면 카테고리 오류입니다.
+
+## Runtime를 써도 Neurain이 필요한 이유
+
+Runtime는 agent loop를 강하게 소유하는 runtime입니다. Neurain의 역할은 다릅니다.
+
+Neurain은 사용자가 다음을 원할 때 필요합니다.
+
+- 내 업무 폴더를 source of truth로 유지
+- Codex, Claude Code, Gemini CLI, Agent Runtime 사이에서 지식 이동 가능
+- chat memory가 아니라 출처 기반 wiki 유지
+- durable write 전 safety gate
+- 변경사항 rollback receipt
+- private 자료 local 유지
+- AI host가 바뀌어도 markdown만으로 복구 가능한 구조
+
+가장 좋은 관계는 "runtime vs Neurain"이 아닙니다. 사용자가 agent runtime을 앞단에서 쓰고 싶다면, "runtime in front, Neurain behind"가 더 정확합니다.
+
+Before/after 예시:
+
+- Neurain 전: 사용자가 Codex에서 Claude Code나 Agent Runtime로 바꿀 때마다 프로젝트 맥락을 다시 설명합니다.
+- Neurain 후: 각 host가 같은 local startup, wiki, receipt, reviewed lesson을 읽으므로, 기억은 하나의 chat이 아니라 폴더에 남습니다.
+
+## 외부 브랜딩 단어
+
+외부 문서에서는 아래 표현을 우선 사용합니다.
+
+- Neurain Knowledge OS
+- local-first knowledge layer
+- source-grounded wiki
+- portable AI memory
+- reviewed lessons
+- safety receipts
+- folder adoption
+- agent-independent continuity
+
+아래 표현은 아직 증명 전까지 과장입니다.
+
+- 완전 자율 self-improvement
+- 자동 durable learning
+- public SaaS ready
+- enterprise governance ready
+- Runtime runtime보다 더 좋다
+
+## 신규 사용자 흐름
+
+1. 사용자는 기존 업무 폴더를 가지고 있습니다.
+2. `npx neurain init <folder>`를 실행합니다.
+3. Neurain이 깨끗한 local vault를 만듭니다.
+4. `npx neurain adopt <work-folder> --dry-run`으로 먼저 스캔합니다.
+5. Neurain은 쓰기 전에 계획과 위험을 설명합니다.
+6. 사용자는 Codex, Claude Code, Gemini CLI, Agent Runtime, 다른 host 중 하나를 연결합니다.
+7. 작업 후 `neurain wrap <folder> --dry-run`을 실행합니다.
+8. Neurain은 상태, 위험, recap, lesson 후보를 보여줍니다.
+9. 오래 남는 변경은 명시적 확인이 있어야만 진행됩니다.
+
+## 브랜딩 규칙
+
+외부 문서 첫 언급은 "Neurain Knowledge OS"를 사용합니다. 이후에는 "Neurain"으로 줄여도 됩니다.
+
+내부 문서에서 "AI Knowledge OS"는 카테고리 표현으로 사용할 수 있지만, 제품 브랜드는 "Neurain Knowledge OS"입니다.

package/docs/pricing.en.md

@@ -0,0 +1,14 @@
+# Pricing Hypothesis
+
+Neurain alpha is open-source local-first software.
+
+Future pricing should not charge for storing a user's private knowledge by default. The first paid layer should be a control plane:
+
+| Plan | Likely buyer | Included |
+|---|---|---|
+| Free | Individual trial users | CLI, local vault, MCP connector |
+| Pro | Solo founders, researchers, operators | guided setup, update channel, backup reminders |
+| Team | small teams | shared policies, team setup, support |
+| Enterprise | regulated teams | SSO, audit posture, deployment support, private onboarding |
+
+This is a hypothesis, not a live price list.

package/docs/privacy-and-data-flow.en.md

@@ -0,0 +1,25 @@
+# Privacy And Data Flow
+
+Neurain is local-first.
+
+## What Stays Local
+
+- Starter vault files.
+- Adopted folder metadata.
+- Raw captures.
+- Wiki and area files.
+- Adoption receipts and rollback receipts.
+
+## What An AI Host Can See
+
+When you connect Codex, Claude Code, Gemini CLI, or Runtime through MCP, that host can call the exposed Neurain tools allowed by that connector. In alpha those tools are limited to read, capture where explicitly exposed, scan, eval, redacted live-case scaffold, and preview surfaces. Gemini uses a read-first allowlist and does not include raw capture by default. MCP cannot promote lessons, append lifecycle events, run the daemon, or silently overwrite durable wiki files.
+
+## What Neurain Does Not Do In Alpha
+
+- It does not install a background daemon. A user can start a foreground daemon loop with `neurain daemon run`.
+- It does not upload your vault to a Neurain cloud.
+- It does not silently compile or overwrite durable wiki files through MCP.
+- It does not store source knowledge in a hidden vector database.
+- It does not claim human-reviewed live evidence from `live-cases scaffold`; that scaffold stores hash-only source refs until a human fills reviewed cases locally.
+
+Secret-like capture input is refused by the MCP capture tool.

package/docs/public-saas-readiness.en.md

@@ -0,0 +1,39 @@
+# Public SaaS Readiness
+
+Neurain alpha separates three scores:
+
+| Track | Meaning | Current alpha evidence |
+|---|---|---|
+| Internal system readiness | The private operating system works for the maintainer. | Existing private Neurain vault. |
+| Public alpha readiness | A new user can install, initialize, scan, and connect. | This CLI and MCP package. |
+| Public SaaS GA readiness | A broad market can self-serve, trust, pay, and recover. | Not complete yet. |
+
+## Current Alpha Readiness
+
+This repo raises public readiness by adding the missing product entrypoint. See `docs/development-status.en.md` for the canonical implementation snapshot.
+
+- publishable npm package
+- installable `neurain` binary
+- read-only non-developer onboarding with `neurain onboard`
+- starter vault initialization
+- existing-folder adoption scan
+- receipt-backed adoption apply and rollback
+- Codex, Claude Code, Gemini CLI, and Agent Runtime MCP connection paths
+- stdio MCP connector with bounded tool surface
+- lifecycle safety eval
+- semantic and hybrid recall
+- live-content recall coverage
+- redacted live-case scaffold
+- safety and privacy docs
+- CI test workflow
+
+Estimated public SaaS readiness after this alpha: 80/100 only if npm and GitHub publication are completed and at least one external tester succeeds. Without actual publication, readiness should be described as publish-ready alpha, not market live. Internal readiness scripts can report score 100 for publish-ready alpha gates, but that is not a public SaaS GA score.
+
+## Remaining For 90+
+
+- local GUI for non-developers
+- hosted control plane for account, license, updates, and optional team metadata
+- public Trust Center and status page
+- external user tests across real folders
+- pricing and support operations
+- backup and recovery UX that non-developers can complete

package/docs/quickstart.en.md

@@ -0,0 +1,64 @@
+# Neurain Quickstart
+
+Version: v0.2
+
+## 0. Ask Neurain what to do first
+
+```bash
+npx neurain onboard ~/NeurainDemo --lang en
+```
+
+This is read-only. If the folder is empty or missing, it tells you how to create a vault. If the folder already has work files, it tells you to scan before writing anything.
+
+## 1. Create a local vault
+
+```bash
+npx neurain init ~/NeurainDemo --lang en
+```
+
+## 2. Check it
+
+```bash
+npx neurain doctor ~/NeurainDemo
+```
+
+## 3. Connect an AI host
+
+```bash
+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
+```
+
+Run without `--dry-run` after reviewing the command.
+
+## 4. Search local knowledge
+
+```bash
+npx neurain search ~/NeurainDemo "what is this folder for"
+```
+
+## 5. Preview the self-improving loop
+
+```bash
+npx neurain wrap ~/NeurainDemo --dry-run
+npx neurain lessons candidates ~/NeurainDemo
+```
+
+Neurain can suggest recurring lesson candidates after meaningful work. MCP never promotes them. CLI can promote a safe reviewed candidate only when you pass the exact confirmation phrase:
+
+```bash
+npx neurain lessons promote ~/NeurainDemo --candidate-id <candidate-id> --confirm "1건 저장 진행"
+npx neurain lessons rollback ~/NeurainDemo --receipt output/receipts/lessons/<receipt>.json
+```
+
+For multi-area vaults, add `--area <name>` to inspect one area. Preview commands do not scan every area by default.
+
+## 6. Adopt an existing folder
+
+```bash
+npx neurain adopt ~/Work --dry-run
+```
+
+Neurain will scan first. It will not write adapter files unless you pass `--apply` and the exact confirmation phrase shown by the scan.

package/docs/quickstart.kr.md

@@ -0,0 +1,64 @@
+# Neurain 빠른 시작
+
+Version: v0.2
+
+## 0. 처음엔 Neurain에게 다음 행동을 물어보기
+
+```bash
+npx neurain onboard ~/NeurainDemo --lang ko
+```
+
+이 명령은 읽기 전용입니다. 폴더가 비어 있거나 없으면 vault 생성 방법을 알려주고, 이미 업무 파일이 있는 폴더라면 어떤 것도 쓰기 전에 먼저 스캔하라고 안내합니다.
+
+## 1. 로컬 vault 만들기
+
+```bash
+npx neurain init ~/NeurainDemo --lang ko
+```
+
+## 2. 상태 확인
+
+```bash
+npx neurain doctor ~/NeurainDemo
+```
+
+## 3. AI host 연결
+
+```bash
+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
+```
+
+출력된 명령이 맞으면 `--dry-run`을 제거하고 실행합니다.
+
+## 4. 로컬 지식 검색
+
+```bash
+npx neurain search ~/NeurainDemo "이 폴더는 무엇을 위한 폴더야"
+```
+
+## 5. 자기개선 루프 미리보기
+
+```bash
+npx neurain wrap ~/NeurainDemo --dry-run
+npx neurain lessons candidates ~/NeurainDemo
+```
+
+Neurain은 의미 있는 작업 후 반복될 만한 lesson 후보를 제안할 수 있습니다. MCP는 후보를 승격하지 않습니다. CLI에서는 안전한 후보를 사용자가 검토한 뒤 정확한 확인 문구를 넣을 때만 승격할 수 있습니다.
+
+```bash
+npx neurain lessons promote ~/NeurainDemo --candidate-id <candidate-id> --confirm "1건 저장 진행"
+npx neurain lessons rollback ~/NeurainDemo --receipt output/receipts/lessons/<receipt>.json
+```
+
+multi-area vault에서는 `--area <name>`을 붙여 특정 area만 확인합니다. Preview command는 모든 area를 기본으로 스캔하지 않습니다.
+
+## 6. 기존 업무 폴더 연결 전 스캔
+
+```bash
+npx neurain adopt ~/Work --dry-run
+```
+
+Neurain은 먼저 읽기 전용으로 스캔합니다. 어댑터 파일 쓰기는 `--apply`와 화면에 표시된 정확한 확인 문구가 있을 때만 진행됩니다.

package/docs/release-checklist.en.md

@@ -0,0 +1,38 @@
+# Release Checklist
+
+Use this checklist before publishing an alpha release.
+
+## Local Checks
+
+```bash
+npm ci
+npm test
+node scripts/readiness.mjs --json
+npm run readiness
+npm pack --dry-run
+npm publish --dry-run --tag alpha
+```
+
+## Product Safety
+
+- No private user content.
+- No local absolute paths.
+- No secrets.
+- No silent durable write through MCP.
+- Public docs explain local-first data flow.
+- `docs/development-status.en.md` and `docs/development-status.kr.md` match the latest shipped commit, test count, readiness score, and package version.
+
+## Publication
+
+- GitHub repo publication policy is decided. Private beta can remain private; public alpha should be public.
+- GitHub Actions test workflow passes.
+- npm package is published or package name is reserved with `npm publish --tag alpha`.
+- Release notes include alpha caveats.
+
+## External Validation
+
+- One user completes quickstart.
+- One Codex connection succeeds.
+- One Claude Code connection succeeds.
+- One Gemini CLI connection dry-run succeeds.
+- One existing folder scan produces a clear recommendation.

package/docs/safety.en.md

@@ -0,0 +1,36 @@
+# Safety
+
+Neurain alpha is designed around preview-first operation.
+
+## Adoption Safety
+
+`neurain adopt <folder>` is read-only by default. It checks for:
+
+- secret-like text
+- generated folders
+- caches
+- symlinks
+- large files
+- binary-heavy or risky folders
+
+Writes require:
+
+```bash
+--apply --confirm "<N>건 저장 진행"
+```
+
+## Rollback
+
+Adoption writes a receipt listing every created file. Rollback removes only files listed in that receipt and only if their content hash still matches.
+
+## MCP Safety
+
+The alpha MCP connector exposes no silent durable write tool. It can search, report status, scan adoption risk, run read-only evals, produce redacted live-case scaffolds, and preview workflow reports.
+
+Capture is append-only when exposed, and secret-like capture input is refused. Gemini CLI uses a read-first allowlist that omits raw capture by default.
+
+MCP does not expose lifecycle emit, daemon run/stop, curator write, recall rebuild write, lesson promotion, or silent durable wiki writes.
+
+## Live-Case Safety
+
+`neurain live-cases scaffold` stores hash-only source refs and templates. It does not store raw source text, absolute local paths, secret-like content, or instruction-injection content. It reports `reviewed_live_user_evidence:false` and `human_judged:false` until a human fills safe local case files.