neurain 0.1.0-alpha.0 → 0.1.0-alpha.10

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 ## Unreleased
 
+- No unreleased changes recorded.
+
+## 0.1.0-alpha.10
+
+- Output consistency hardening (from an adversarial cross-review of alpha.9): the rendered command block is now ASCII-clean by construction and byte-identical between the CLI and the MCP. `render.mjs` sanitizes every cell, note, and title (glyphs like the heavy check/x, stop sign, bullet, and any emoji map to ASCII or are stripped; status stays a word), so a glyph in a payload field or in user input renders clean instead of leaking or crashing. The MCP `renderedResult` now appends the same trailing newline the CLI adds (CLI == MCP byte-identical) and falls back to JSON only when a rendered block is truly absent. `digest` always carries a non-empty rendered block (an unknown session no longer yields empty MCP output). `status` sanitizes user-supplied ids in its error paths. Added tests: `sanitizeAscii` mapping/stripping, a glyph-in-field renders clean, and MCP output equals the CLI byte-for-byte for `neurain_session_status` and `neurain_compile`. npm test 169/169, readiness 100.
+
+
+## 0.1.0-alpha.9
+
+- Output consistency (single render source): added `src/core/render.mjs` as the one place that renders user-facing command output, so every host shows the same block. `status`, `compile`, `sync`, and `capture` now build their output via `renderX(payload)`, expose it as `payload.rendered`, and return it as `{ text }` (the existing `digest.mjs` pattern). The MCP server's user-facing view tools (`neurain_session_status`, `neurain_compile`, `neurain_digest_preview`) now return that rendered markdown block instead of `JSON.stringify(payload)`, so an MCP host and the CLI emit byte-identical bytes; diagnostic/eval MCP tools still return JSON. Output is clean GitHub-flavored markdown tables, ASCII only, with status as words (ok/warn/missing/blocked) and no status glyphs or dashes. The `--json` payload shape is unchanged (machine consumers unaffected). Added `test/render.test.mjs` (per-renderer ascii/table/determinism, CLI-text == payload.rendered, MCP returns markdown not JSON). npm test 167/167, readiness 100.
+
+
+## 0.1.0-alpha.8
+
+- Privacy (exact recall freshness): the exact-token branch reads from the SQLite FTS index, which is a cache rebuilt only on demand, so a markdown file that was public when indexed but has since turned `sensitivity: private`, been deleted, or gained a secret could linger in `recall search` and `hybrid-search` exact results until the next rebuild. `searchRecall` now re-gates the returned markdown paths against the CURRENT files (same private/secret/exists gate the markdown branches already apply) and drops any that are no longer safe. Only the top-K returned paths are re-read, so the exact branch stays fast (~4ms warm); a fresh index drops nothing, so results are unchanged (golden 9/9 identical). Event and receipt rows keep their own collection-time gating and pass through. Added `test/perf_recall_equivalence.test.mjs` coverage that a public-then-private and a deleted file do not surface from a stale index.
+
+
+## 0.1.0-alpha.7
+
+- Hardening (recall perf, from an adversarial review): lock the "byte-identical results" claim and tighten the fast-path contracts, with no change to ranking/scores (golden-identical).
+
+  - Added `test/perf_recall_equivalence.test.mjs`: an oracle test that `countOccurrences` equals `split(term).length - 1` for every non-empty term (overlap/unicode/surrogate cases included), a proof that `scorePreparedSemantic` (prepare-once + per-doc trigram precompute) equals a naive per-doc reference scorer, a determinism check, and a guard that the shared corpus selector keeps private + secret-bearing files out of every branch.
+  - Extracted the lexical BM25 term-frequency count into an exported `countOccurrences(haystack, needle)` with an empty-needle guard (returns 0) so the index-loop form can never spin even if the term filter changes.
+  - `buildLexicalContext` now throws if a caller passes shared `markdownFiles` together with an `area` (the only safe share is whole-vault; an area context selects a strict subset, so this prevents a future caller from silently widening the corpus).
+  - `prepareSemanticQuery` now returns a frozen prepared query, and the provider fast-path contract (prepared query is immutable, no cross-call mutable state) is documented on the default provider.
+
+## 0.1.0-alpha.6
+
+- Performance (hybrid recall): `hybrid-search` now walks the markdown corpus ONCE and shares it across its semantic and routed-lexical branches instead of each branch re-walking and re-reading the whole vault. The walk is shared only when no `--area` is set (the two branches then select the same whole-vault corpus); with an area they still walk independently. Results stay byte-identical (golden-verified) because the shared file list is exactly what each branch would have walked. Measured: `recall hybrid-search` ~970ms -> ~763ms (warm median); combined with alpha.5 that is ~1234ms -> ~763ms (-38%). npm test 153/153.
+
+
+## 0.1.0-alpha.5
+
+- Performance (recall processing): cut recall/search processing time without changing results. The semantic scorer now prepares the query once and precomputes per-doc trigrams (instead of re-tokenizing the query and rebuilding `charTrigrams` per document), and the lexical BM25 counts term frequency with an index loop instead of `String.split`. Measured: `recall hybrid-search` ~1234ms -> ~970ms, `semantic-search` ~1031ms -> ~750ms (warm median), with byte-identical ranking/scores/matched_terms (golden-verified) and npm test 153/153.
+
+
+## 0.1.0-alpha.4
+
+- Performance: lazy dynamic-import CLI dispatch. Each command now imports only its own `core/*.mjs` module on demand instead of loading all ~54 command modules on every invocation. Engine subprocess latency drops ~60-75ms across the board (`tidy` 150->90ms, `structure-audit` 120->60ms, `--help`/`--version` 50ms), with no change to the command surface or behavior (npm test 153/153; reviewed).
+
+
+## 0.1.0-alpha.3
+
+- Destination resolver (`resolve_target.mjs`): `capture` and `compile` now derive one canonical target path from area, write intent, and sensitivity instead of leaving placement to the caller. Private, multi-area, and decision-required items still gate on the `<N>건 저장 진행` confirmation and are never auto-filed.
+
+- Janitor (`neurain tidy`): read-only detection of provably-junk residue only (empty Obsidian `Untitled*.canvas/.base`, zero-byte daily notes, stray empty top-level directories); quarantine is recoverable (30-day trash). Registered areas, archives, and structural directories are never touched.
+- Auto-filer (`neurain file`): finds loose durable markdown outside any canonical home and, gated by confirmation, relocates it recoverably and secret-gated; also surfaces read-only `raw/_inbox` routing proposals. Registered area roots and root-contract files are excluded.
+- Structure audit (`neurain structure-audit`): advisory flags for area-adapter gaps, the `output/` vs `outputs/` split, and `sources_map` drift; composed into `lint`. Never writes and never fails a build.
+- New-user organize (`neurain organize`): turns an unknown folder into a searchable area. Reuses the adopt scan, decides a per-file disposition, and on a gated apply scaffolds the area in copy mode (originals are never moved or deleted) and reindexes; hash-keyed receipt with `--rollback`. Secrets and already-structured KBs are protected.
+- Organize and adopt preserve non-ASCII (for example Korean) folder names as area slugs.
+
+## 0.1.0-alpha.2
+
+- Documentation currency gate: README and development-status version strings are asserted against package.json in readiness; volatile metric snapshots de-hardcoded (verified green in CI, not pinned in docs).
+
+
+## 0.1.0-alpha.1
+
+- Capture: file/asset capture + R2/R4/R6 enrichment (overlap candidates, numeric conflicts, sha256 duplicate detection) ported to the engine.
+- Memory-write: completed the generic ledger-primitive set (appendLine/enqueue/setQueueStatus/appendBlock/writeFileGuarded) so a consumer can forward every fact/task primitive to the engine.
+- Release automation: tag-triggered npm publish via Trusted Publishing (OIDC), a push-CI gate (fast readiness + `npm publish --dry-run`), and a prerelease-never-`latest` dist-tag guard.
 - 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.

package/README.md

@@ -126,7 +126,7 @@ 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.
+The package is a publish-ready alpha for private beta or alpha user tests, not public SaaS GA. All gates (`npm test`, the readiness leakage/secret/pack/tarball-install checks, and `npm audit`) run green in CI on every release — see `.github/workflows/release.yml`. The live score is `node scripts/readiness.mjs --json`.
 
 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.
 
@@ -159,7 +159,7 @@ For multi-area vaults, preview commands do not scan every area by default. Use `
 See also:
 
 - `docs/knowledge-os.en.md`
-- `docs/self-improve-90-roadmap.en.md`
+- `docs/self-improvement-90-roadmap.en.md`
 - `docs/connect-runtime.en.md`
 
 ## Existing Folder Adoption
@@ -176,6 +176,22 @@ Neurain scans first and recommends one of three modes:
 
 Writes require an explicit confirmation phrase shown by the scan.
 
+## Keeping the Vault Tidy
+
+Neurain keeps a working vault organized through read-only detection plus gated, recoverable writes. Nothing here moves or deletes a file without an explicit confirmation phrase, and registered areas, archives, and root-contract files are never touched.
+
+```bash
+npx neurain tidy ~/NeurainDemo                 # report provably-junk residue (read-only)
+npx neurain structure-audit ~/NeurainDemo      # advisory structure flags (read-only)
+npx neurain file ~/NeurainDemo                 # propose homes for loose docs (read-only)
+npx neurain organize ~/SomeUnknownFolder --dry-run   # turn an unknown folder into a searchable area
+```
+
+- `tidy` detects only provably-junk residue (empty Obsidian `Untitled*` canvas/base files, zero-byte daily notes, stray empty top-level directories) and quarantines recoverably.
+- `structure-audit` is advisory only: it flags area-adapter gaps, the `output/` vs `outputs/` split, and `sources_map` drift, and never fails a build.
+- `file` relocates loose durable markdown into its canonical home behind a confirmation gate, and surfaces `raw/_inbox` routing proposals.
+- `organize` turns an unknown folder into a searchable area in copy mode (originals are never moved or deleted), with a hash-keyed receipt and `--rollback`. Secrets and already-structured knowledge bases are protected.
+
 ## MCP
 
 The alpha MCP server is stdio-only:
@@ -188,7 +204,7 @@ It exposes read/capture/scan/preview tools only. It does not silently compile, p
 
 ## 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.
+This is `0.1.0-alpha.10`. 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:
 

package/docs/connect-runtime.en.md

@@ -45,7 +45,7 @@ Safety boundary:
 - 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.
+- Scheduler eval access is read-only and checks trigger precision, trigger recall, no-recursion, private-boundary handling, case-file size limits, temp cleanup, 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

package/docs/connect-runtime.kr.md

@@ -45,7 +45,7 @@ Safety boundary:
 - 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을 확인합니다.
+- Scheduler eval access도 read-only이며 trigger precision, trigger recall, no-recursion, private-boundary handling, case-file size limit, temp cleanup, target-root non-write snapshot을 확인합니다.
 - Lifecycle access는 MCP에서 read-only입니다. Runtime은 session lineage를 읽을 수 있고, 더 깊은 lifecycle event emission은 아래 host-proxy contract를 사용합니다.
 
 ## Lifecycle Boundary

package/docs/development-status.en.md

@@ -1,9 +1,9 @@
 # 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`
+Last updated: 2026-06-21 KST
+Package: `neurain@0.1.0-alpha.10`
+Latest documented commit: `fc907c2 fix(render): ascii-clean by construction + CLI==MCP byte-identical`
 
 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.
 
@@ -11,16 +11,9 @@ This document is the canonical product development snapshot for the public packa
 
 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:
+Current verification: every gate runs green in CI on each release — `npm test`, the full `npm run readiness` suite (leakage/secret scan, `npm audit`, `npm pack --dry-run`, and a temporary tarball-install smoke), and `node scripts/readiness.mjs --json` for the live score. See `.github/workflows/release.yml`.
 
-| 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 |
+Volatile metrics (exact test counts, readiness scores, check counts) are intentionally NOT pinned in this document — they are verified green in CI, not hand-copied, so this snapshot cannot silently drift from the suite.
 
 ## Shipped Development
 
@@ -28,6 +21,7 @@ Current verified score:
 
 - Starter vault initialization with `neurain init`.
 - Existing folder adoption scan, apply, receipt, and rollback.
+- Unified `reindex` (register areas + per-area index refresh + recall rebuild in one pass; curated indexes are never auto-overwritten); `adopt --apply` auto-reindexes so an adopted folder is registered and searchable in one command.
 - Local doctor, search, capabilities, recap, and wrap preview.
 - Event journal add/list/verify with explicit confirmation.
 - Lesson list, candidates, eval, promotion, and rollback.
@@ -97,7 +91,7 @@ Status: shipped as publish-ready alpha.
 - 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.
+- Status: npm publish is done. `neurain@0.1.0-alpha.3` is published under the `alpha` tag and the package name is secured.
 
 ### E26: Thin MCP Connector
 
@@ -110,6 +104,18 @@ Status: shipped.
 - 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.
 
+### E27: Auto-Organization System
+
+Status: shipped.
+
+- CLI: `neurain tidy`, `neurain file`, `neurain structure-audit`, `neurain organize`.
+- Destination resolver: `capture` and `compile` derive one canonical target path from area, write intent, and sensitivity. Private, multi-area, and decision-required items still gate on the `<N>건 저장 진행` confirmation and are never auto-filed.
+- Janitor (`tidy`) detects provably-junk residue only (empty Obsidian canvas/base files, zero-byte daily notes, stray empty top-level directories). Read-only; quarantine is recoverable. Registered areas, archives, and structural directories are never touched.
+- Auto-filer (`file`) relocates loose durable markdown into its canonical home behind a confirmation gate, recoverably and secret-gated, and surfaces read-only `raw/_inbox` routing proposals.
+- Structure audit (`structure-audit`) is advisory: it flags area-adapter gaps, the `output/` vs `outputs/` split, and `sources_map` drift, and composes into `lint` without ever writing or failing a build.
+- New-user organize (`organize`) turns an unknown folder into a searchable area in copy mode (originals are never moved or deleted), with a hash-keyed receipt and `--rollback`. Secrets and already-structured KBs are protected. Non-ASCII (for example Korean) folder names are preserved as area slugs.
+- Honest scope: these are vault-hygiene helpers. Detection is read-only and every relocation is gated and recoverable; Neurain does not autonomously reorganize a user's folder.
+
 ## Current Connector Truth Table
 
 | Host | MCP connection | Lifecycle hook preview | Notes |
@@ -125,7 +131,6 @@ Status: shipped.
 - 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

package/docs/development-status.kr.md

@@ -1,9 +1,9 @@
 # 개발 진행 상태
 
 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`
+Last updated: 2026-06-21 KST
+Package: `neurain@0.1.0-alpha.10`
+Latest documented commit: `fc907c2 fix(render): ascii-clean by construction + CLI==MCP byte-identical`
 
 이 문서는 public package 기준의 canonical 개발 상태 스냅샷입니다. 무엇이 shipped인지, 어떤 증거가 있는지, 아직 주장하면 안 되는 것이 무엇인지 함께 기록합니다.
 
@@ -11,16 +11,9 @@ Latest documented commit: `3496262 Add E24 onboarding and Gemini MCP connector`
 
 Neurain은 publish-ready alpha CLI 및 MCP package입니다. private beta 또는 alpha user test에는 들어갈 수 있지만 public SaaS GA는 아닙니다.
 
-현재 검증된 상태:
+현재 검증: 매 릴리스마다 모든 게이트가 CI에서 green으로 통과합니다 — `npm test`, 전체 `npm run readiness`(leakage/secret 스캔, `npm audit`, `npm pack --dry-run`, 임시 tarball-install smoke), 라이브 점수는 `node scripts/readiness.mjs --json`. `.github/workflows/release.yml` 참조.
 
-| 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 |
+휘발성 지표(정확한 테스트 수·readiness 점수·check 수)는 의도적으로 이 문서에 박지 않습니다 — CI에서 green으로 검증되며 손으로 복사하지 않으므로, 이 스냅샷이 suite와 조용히 어긋나지 않습니다.
 
 ## shipped 개발 범위
 
@@ -28,6 +21,7 @@ Neurain은 publish-ready alpha CLI 및 MCP package입니다. private beta 또는
 
 - `neurain init` starter vault initialization.
 - 기존 폴더 adoption scan, apply, receipt, rollback.
+- 통합 `reindex`(영역 등록 + per-area 색인 새로고침 + recall rebuild를 한 번에; 큐레이티드 색인은 자동 덮어쓰기 안 함); `adopt --apply`가 자동 reindex하여 채택한 폴더가 한 명령으로 등록·검색 가능.
 - local doctor, search, capabilities, recap, wrap preview.
 - 명시적 confirmation이 필요한 event journal add/list/verify.
 - lesson list, candidates, eval, promotion, rollback.
@@ -97,7 +91,7 @@ Status: publish-ready alpha로 shipped.
 - 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이 필요합니다.
+- 상태: npm publish 완료. `neurain@0.1.0-alpha.3`가 `alpha` 태그로 발행됐고 패키지 이름도 선점됨.
 
 ### E26: Thin MCP Connector
 
@@ -110,6 +104,18 @@ Status: shipped.
 - 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을 노출하지 않습니다.
 
+### E27: 자동 정리 시스템
+
+Status: shipped.
+
+- CLI: `neurain tidy`, `neurain file`, `neurain structure-audit`, `neurain organize`.
+- 목적지 리졸버: `capture`·`compile`이 영역·쓰기의도·민감도로부터 단일 canonical 목적지 경로를 도출합니다. private·다중영역·결정필요 항목은 여전히 `<N>건 저장 진행` 확인을 거치며 절대 자동 파일링되지 않습니다.
+- Janitor(`tidy`)는 증명 가능한 잔여물만 탐지합니다(빈 Obsidian canvas/base 파일, 0바이트 데일리노트, 빈 최상위 디렉터리). 읽기전용이고 격리는 복구 가능하며, 등록된 영역·아카이브·구조 디렉터리는 건드리지 않습니다.
+- Auto-filer(`file`)는 떠도는 durable 마크다운을 확인 게이트 뒤에서 복구 가능·시크릿 게이트로 canonical 위치로 옮기고, `raw/_inbox` 라우팅 제안을 읽기전용으로 보여줍니다.
+- 구조 점검(`structure-audit`)은 권고용입니다: 영역 어댑터 결손, `output/` 대 `outputs/` 분리, `sources_map` 드리프트를 표시하고 `lint`에 합성되며, 쓰기나 빌드 실패를 일으키지 않습니다.
+- 신규 사용자 organize(`organize`)는 미지의 폴더를 검색 가능한 영역으로 COPY 모드로 전환합니다(원본은 절대 이동·삭제 안 함). 해시 키 receipt + `--rollback`. 시크릿과 이미 구조화된 KB는 보호됩니다. 비ASCII(예: 한글) 폴더명은 영역 슬러그로 보존됩니다.
+- 정직한 범위: 이들은 vault 위생 도구입니다. 탐지는 읽기전용이고 모든 재배치는 게이트·복구 가능하며, Neurain이 사용자 폴더를 자율적으로 재편하지 않습니다.
+
 ## 현재 connector truth table
 
 | Host | MCP connection | Lifecycle hook preview | Notes |
@@ -125,7 +131,6 @@ Status: shipped.
 - non-developer GUI.
 - hosted control plane.
 - public Trust Center 및 status page.
-- npm publish 또는 package name reservation.
 - beta 동안 repo를 private으로 유지한다면 public GitHub publication.
 
 ## 문서 유지관리 규칙

package/docs/release-checklist.en.md

@@ -2,7 +2,40 @@
 
 Use this checklist before publishing an alpha release.
 
-## Local Checks
+## Automated Release (preferred)
+
+Releases are automated. You only decide WHEN to ship:
+
+```bash
+npm version prerelease --preid=alpha   # 0.1.0-alpha.0 -> 0.1.0-alpha.1 (commits + tags)
+git push origin main --follow-tags     # push the commit AND the new tag
+```
+
+The tag push triggers `.github/workflows/release.yml`, which runs the full
+readiness gate and then `npm publish --tag alpha` via npm Trusted Publishing
+(OIDC) — no stored token, no interactive 2FA. Every push (untagged) is gated by
+`.github/workflows/test.yml` (tests + fast readiness + `npm publish --dry-run`).
+
+One-time setup: on npmjs.com, the package -> Settings -> Trusted Publisher ->
+GitHub Actions, with this repo's owner/name and workflow `release.yml`.
+
+## Versioning policy
+
+- Pre-1.0 alpha: increment with `npm version prerelease --preid=alpha`
+  (`-alpha.0 -> -alpha.1 -> ...`). Publish ALWAYS with `--tag alpha`; never move
+  the `latest` dist-tag to a prerelease. Only a deliberate stable (>= the first
+  non-prerelease) should ever hold `latest`.
+
+## Rollback / yank
+
+- A published version cannot be overwritten and cannot be unpublished after 72h.
+  To pull a bad alpha: `npm deprecate neurain@<bad> "broken, use <good>"` and ship
+  a fixed `-alpha.<next>`.
+- To roll the consuming vault back to a prior engine: point `NEURAIN_ENGINE_BIN`
+  at the previous tag's checkout (or pin the previous npm version), or set
+  `NEURAIN_LEGACY=1` to fall back to the vault's preserved implementations.
+
+## Local Checks (manual fallback)
 
 ```bash
 npm ci

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neurain",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.10",
   "description": "Local-first Neurain Knowledge OS CLI and MCP connector.",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,7 +27,10 @@
   "scripts": {
     "test": "node --test",
     "pack:dry-run": "npm pack --dry-run",
-    "readiness": "node scripts/readiness.mjs --full"
+    "readiness": "node scripts/readiness.mjs --full",
+    "docs:check": "node scripts/sync-docs.mjs --check",
+    "docs:fix": "node scripts/sync-docs.mjs --write",
+    "version": "node scripts/sync-docs.mjs --write && git add -u README.md CHANGELOG.md docs/development-status.en.md docs/development-status.kr.md"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.5"

package/src/cli.mjs

@@ -1,41 +1,62 @@
 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';
+
+const COMMAND_HANDLERS = {
+  init: async (args) => (await import('./core/init.mjs')).initCommand(args),
+  onboard: async (args) => (await import('./core/onboard.mjs')).onboardCommand(args),
+  answer: async (args) => (await import('./core/answer_eval.mjs')).answerCommand(args),
+  doctor: async (args) => (await import('./core/doctor.mjs')).doctorCommand(args),
+  search: async (args) => (await import('./core/search.mjs')).searchCommand(args),
+  connect: async (args) => (await import('./core/connect.mjs')).connectCommand(args),
+  journal: async (args) => (await import('./core/journal.mjs')).journalCommand(args),
+  lifecycle: async (args) => (await import('./core/lifecycle.mjs')).lifecycleCommand(args),
+  'live-cases': async (args) => (await import('./core/live_cases.mjs')).liveCasesCommand(args),
+  lessons: async (args) => (await import('./core/lessons.mjs')).lessonsCommand(args),
+  curator: async (args) => (await import('./core/curator.mjs')).curatorCommand(args),
+  daemon: async (args) => (await import('./core/daemon.mjs')).daemonCommand(args),
+  recall: async (args) => (await import('./core/recall.mjs')).recallCommand(args),
+  reindex: async (args) => (await import('./core/reindex.mjs')).reindexCommand(args),
+  status: async (args) => (await import('./core/status.mjs')).statusCommand(args),
+  digest: async (args) => (await import('./core/digest.mjs')).digestCommand(args),
+  queue: async (args) => (await import('./core/queue.mjs')).queueCommand(args),
+  'review-queue': async (args) => (await import('./core/review_queue.mjs')).reviewQueueCommand(args),
+  route: async (args) => (await import('./core/route.mjs')).routeCommand(args),
+  'plan-writeback': async (args) => (await import('./core/plan_writeback.mjs')).planWritebackCommand(args),
+  flush: async (args) => (await import('./core/flush.mjs')).flushCommand(args),
+  'session-flush': async (args) => (await import('./core/flush.mjs')).sessionFlushCommand(args),
+  compile: async (args) => (await import('./core/compile_desk.mjs')).compileCommand(args),
+  'plan-receipt': async (args) => (await import('./core/plan_receipt.mjs')).planReceiptCommand(args),
+  'source-digest': async (args) => (await import('./core/source_digest_gen.mjs')).sourceDigestCommand(args),
+  stage: async (args) => (await import('./core/stage.mjs')).stageCommand(args),
+  'queue-archive': async (args) => (await import('./core/queue_archive.mjs')).queueArchiveCommand(args),
+  capture: async (args) => (await import('./core/capture_durable.mjs')).captureCommand(args),
+  complete: async (args) => (await import('./core/complete.mjs')).completeCommand(args),
+  'link-check': async (args) => (await import('./core/link_check.mjs')).linkCheckCommand(args),
+  'session-lint': async (args) => (await import('./core/session_lint.mjs')).sessionLintCommand(args),
+  label: async (args) => (await import('./core/label.mjs')).labelCommand(args),
+  orphans: async (args) => (await import('./core/orphans.mjs')).orphansCommand(args),
+  hubs: async (args) => (await import('./core/hubs.mjs')).hubsCommand(args),
+  'area-index': async (args) => (await import('./core/area_index.mjs')).areaIndexCommand(args),
+  lint: async (args) => (await import('./core/lint.mjs')).lintCommand(args),
+  tidy: async (args) => (await import('./core/tidy.mjs')).tidyCommand(args),
+  'structure-audit': async (args) => (await import('./core/structure_audit.mjs')).structureAuditCommand(args),
+  file: async (args) => (await import('./core/file_loose.mjs')).fileCommand(args),
+  organize: async (args) => (await import('./core/organize.mjs')).organizeCommand(args),
+  'session-pulse': async (args) => (await import('./core/session_pulse.mjs')).sessionPulseCommand(args),
+  sync: async (args) => (await import('./core/sync.mjs')).syncCommand(args),
+  health: async (args) => (await import('./core/health.mjs')).healthCommand(args),
+  memory: async (args) => (await import('./core/memory.mjs')).memoryCommand(args),
+  retention: async (args) => (await import('./core/retention.mjs')).retentionCommand(args),
+  freeze: async (args) => (await import('./core/freeze.mjs')).freezeCommand(args),
+  'memory-write': async (args) => (await import('./core/memory_write_cli.mjs')).memoryWriteCommand(args),
+  backup: async (args) => (await import('./core/backup.mjs')).backupCommand(args),
+  capabilities: async (args) => (await import('./core/capabilities.mjs')).capabilitiesCommand(args),
+  recap: async (args) => (await import('./core/recap.mjs')).recapCommand(args),
+  watch: async (args) => (await import('./core/watch.mjs')).watchCommand(args),
+  review: async (args) => (await import('./core/review_worker.mjs')).reviewCommand(args),
+  scheduler: async (args) => (await import('./core/scheduler.mjs')).schedulerCommand(args),
+  wrap: async (args) => (await import('./core/wrap.mjs')).wrapCommand(args),
+};
 
 export async function runCli(argv) {
   const [command, ...rest] = argv;
@@ -50,46 +71,17 @@ export async function runCli(argv) {
   }
 
   const args = parseArgs(rest);
-  if (command === 'init') return render(await initCommand(args));
-  if (command === 'onboard') return render(await onboardCommand(args));
   if (command === 'adopt') {
+    const { adoptCommand, rollbackAdoption } = await import('./core/adopt.mjs');
     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);
+  const handler = COMMAND_HANDLERS[command];
+  if (handler) return render(await handler(args));
+  if (command === 'mcp') {
+    const { startMcpServer } = await import('./mcp/server.mjs');
+    return startMcpServer(args);
+  }
   if (command === 'selftest') return runSelftest();
 
   throw new Error(`Unknown command: ${command}\n\n${helpText()}`);
@@ -152,8 +144,11 @@ function helpText() {
 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 <folder> [--dry-run] [--apply --confirm "<N>건 저장 진행"] [--no-reindex]
   neurain adopt --rollback <receipt> [--root <folder>]
+  neurain organize <folder> [--apply --confirm "<N>건 저장 진행"] [--allow-secret] [--no-reindex] [--json]
+  neurain organize --rollback <receipt> --root <folder> [--json]
+  neurain reindex <folder> [--dry-run] [--json]
   neurain doctor <folder> [--json]
   neurain search <folder> <query> [--top 10] [--json]
   neurain journal list <folder> [--type type] [--top 20] [--json]
@@ -203,6 +198,23 @@ Usage:
   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 session-lint <folder> [--stale-days 7] [--now ms] [--json]
+  neurain label <folder> [--check | --apply] [--area name | --all] [--glob substr] [--limit N] [--json]
+  neurain orphans <folder> [--area name] [--fix] [--json]
+  neurain hubs <folder> [--check | --apply] [--area name] [--json]
+  neurain area-index <folder> [--build area | --refresh area | --register-curated area [--sensitivity private] | --detect [--fix] [--restamp-curated]] [--force] [--dry-run] [--json]
+  neurain lint <folder> [--json]
+  neurain tidy <folder> [--json]
+  neurain structure-audit <folder> [--json]
+  neurain file <folder> [--apply --confirm "<N>건 저장 진행"] [--allow-secret] [--json]
+  neurain session-pulse <folder> --session-id id --summary "..." [--focus t] [--next t] [--max-notes 8] [--no-area-brief] [--queue ...] [--now ts] [--dry-run] [--allow-secret] [--json]
+  neurain sync <folder> --session-id id [--summary "..."] [--level light|standard|full] [--no-pulse] [--no-area-brief] [--queue ...] [--now ts] [--dry-run] [--json]
+  neurain health <folder> [--fix] [--now ts] [--json]
+  neurain memory <folder> [--facts q | --tasks q | --conflicts | --verify | --stats] [--area name] [--top 10] [--json]
+  neurain retention <folder> [--area name] [--stale-days 120] [--write] [--now ms] [--json]
+  neurain freeze <folder> <acquire|release|status> [--owner name] [--json]
+  neurain memory-write <folder> --area name --file ledger.md --op add-fact|add-task|set-status|append-event [--fields json] [--changes json] [--event json] [--fact-id id] [--id id] [--apply] [--json]
+  neurain backup <folder> --target <dir> [--label name] | --verify <name> | --restore <name> [--to <dir>] | --drill <name> [--target <dir>] | --list [--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]
@@ -249,7 +261,16 @@ Alpha principles:
   - 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.
+  - Link-check and session-lint (W-C) are read-only validators that write nothing. Link-check resolves every markdown link and wikilink against the vault and reports unresolved targets by file and area. Session-lint validates the session layer: required paths, session-state vs handoff consistency, pending-count drift vs the queue, handoff frontmatter, and queue rows referencing known sessions. Both use the configured structural dirs, not hardcoded area names.
+  - Label (W-C) is the label-system CLI: --check (default, read-only) proposes the managed label block (type/areas/entities/domains/sensitivity/tags) per knowledge file and reports private leaks; --apply writes it additively and idempotently, atomic per file, refusing symlinks. The label brain (label_intel) hard-codes nothing vault-specific — vocabulary comes from each area's entity dictionary and tuning from an optional label-config.json. A private/published file never gets entity/domain tags.
+  - Backup (W-E) is the local snapshot + EXACT restore + restore-drill: the manifest records files (sha256+size) and dirs, symlinks/special files are refused, and restore reconstructs the target byte-exactly (and proves it) via stage-verify-rename-aside-reverify, so a no-git vault still has a verifiable rollback. The macOS/iCloud encrypted external backup stays vault-side.
+  - Memory-write (W-E) is the registry-driven fact/task ledger writer: schemas, ID templates, mandatory/dash columns and paths come from memory-write-registry.json, so every area is handled by the same code. It appends rows or edits a fact's lifecycle columns while keeping every other row byte-identical, under an O_EXCL lock with a sha256 compare-and-swap (concurrent modification aborts) + fsync. Default dry-run; a live write needs the area's write_enabled:true, a realpath inside area_root, a fail-closed secret scan, and the freeze lock not held.
+  - Memory and retention (W-E, read-only) query the per-area fact/task ledgers via a config-driven reader that maps heterogeneous table schemas by column name. Memory does status-aware fact/task lookup, conflicts, and verify; retention flags active facts for human review (contradicted / unverified / stale / low-confidence / missing-metadata) and never deletes (optional --write emits a report). Neither touches the ledgers.
+  - Health (W-D) composes doctor + lint into one verdict and reconciles session-state drift: pending_count's source of truth is the writeback queue and last_pulse's is the handoff frontmatter, so a session can drift. Read-only without --fix; with --fix it repairs drift via the locked session-state path and runs the W-C maintenance fixers (orphans, label, area-index) before a final lint.
+  - Session-pulse (W-D) is the session working-memory writer: it pulses one durable note into the handoff, optionally the area brief and a queue row, then advances session-state. Hardened per cross-review: markdown is written first and the authoritative session-state.json last (a crash leaves the markdown ahead but state recoverable), every write is atomic, the area brief is rendered + labelled in memory and written once, and the note is secret-scanned fail-closed. session-state writes are this wave's (W-D) responsibility; W-B's capture/complete only returned a delta for it to apply.
+  - Lint (W-C) is a read-only STRUCTURAL aggregator: it composes the ported validators (link-check, session-lint, advisory orphans) into one health verdict. It deliberately does NOT re-implement the vault's documentation-governance checks (master version, clipper templates, instruction lengths, progressive disclosure) — those stay vault-side.
+  - Area-index (W-C) generates a per-area search index from the area's own signals (wiki/entities pages, frontmatter entity_candidates, area-tagged raw envelopes, salience-gated content terms), registers it, detects staleness via a file signature, and refreshes drifted generated indexes. Curated indexes are never auto-overwritten; --detect is read-only, writes happen only with --build/--refresh/--register-curated/--detect --fix.
+  - Orphans and hubs (W-C) are the graph connection layer. Orphans reports knowledge files with no inbound and no outbound wikilink, classified (structural / has-entities / no-entities); --fix adds one additive per-area graph-backlog page (source files untouched). Hubs generates per-entity hub pages linking member notes (dry-run by default, --apply writes and prunes only its own hub_generated pages); private areas and private files are excluded, member files are never modified.
   - 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.