sanook-cli 0.5.1 → 0.5.5

package/second-brain/Projects/sanook-cli/_Index.md

@@ -0,0 +1,30 @@
+---
+tags: [index, moc, project, sanook-cli]
+note_type: moc
+created: 2026-06-18
+updated: 2026-06-20
+parent: "[[Projects/_Index]]"
+---
+
+# Sanook CLI
+
+> Project workspace for Sanook CLI product decisions, implementation plans, and current project-specific state.
+
+## Notes
+
+- [[Projects/sanook-cli/overview]] — goal, scope, stack, verify
+- [[Projects/sanook-cli/current-state]] — NOW / blockers / next
+- [[Projects/sanook-cli/context]] — architecture + conventions for AI
+- [[Projects/sanook-cli/repo]] — repo path mapping (Sanook auto-detect)
+- [[Projects/sanook-cli/second-brain-feature-roadmap]] — second-brain CLI roadmap
+
+## AI Routing Contract
+
+- ก่อนเขียน: ใช้โฟลเดอร์นี้เฉพาะงานที่เกี่ยวกับ Sanook CLI product/codebase โดยตรง
+- ก่อนสร้างไฟล์ใหม่: ค้นหา note เดิมใน `Projects/sanook-cli/` ก่อน เพื่อ merge/update แทน append ซ้ำ
+- เมื่อสร้างโน้ตในโฟลเดอร์นี้: ตั้ง `parent: "[[Projects/sanook-cli/_Index]]"` และท้ายไฟล์ `up:: [[Projects/sanook-cli/_Index]]`
+- หลังเขียน: เชื่อม link ไป session/source/code path ที่เกี่ยวข้อง และอัปเดต index นี้ถ้าโน้ตควรถูกค้นเจอในอนาคต
+
+> รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
+
+up:: [[Projects/_Index]]

package/second-brain/Projects/sanook-cli/context.md

@@ -0,0 +1,35 @@
+---
+tags: [project, context, sanook-cli]
+note_type: project-context
+created: 2026-06-20
+updated: 2026-06-20
+parent: "[[Projects/sanook-cli/_Index]]"
+---
+
+> Stable AI context — architecture, conventions, and gotchas before editing Sanook CLI code.
+
+# Context — Sanook CLI
+
+> สิ่งที่ AI ต้องรู้ก่อนแตะโค้ด
+
+## Architecture
+
+- **Entry:** `src/bin.ts` → CLI routing; `src/loop.ts` → agent loop (Vercel AI SDK)
+- **Brain:** `src/memory.ts`, `src/brain-*.ts`, `src/project-registry.ts` — vault context + project detect
+- **Search:** `src/search/` — BM25 + optional semantic; indexes vault + memory + sessions + skills
+- **Bundled vault:** `second-brain/` ships with npm; user `brainPath` usually points here or a copy
+
+## Conventions
+
+- Branch: `main`
+- Verify: `npm run typecheck && npm test` (1210+ tests)
+- Commit style: complete sentences, focus on why
+- Minimize diff scope; match existing TS patterns; Thai comments OK in CLI strings
+
+## Gotchas
+
+- `brainPath` in `~/.sanook/config.json` — brain CLI commands need it configured
+- Bundled vault path in repo: `second-brain/` (not only user's external vault)
+- `loadBrainContext(cwd)` auto-injects matching `Projects/<slug>/` when cwd is inside `repo_path`
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/Projects/sanook-cli/current-state.md

@@ -0,0 +1,32 @@
+---
+tags: [project, operating-state, sanook-cli]
+note_type: project-state
+status: active
+created: 2026-06-20
+updated: 2026-06-20
+parent: "[[Projects/sanook-cli/_Index]]"
+---
+
+> Live project status — update when NOW / blockers / next actions change.
+
+# Current State — Sanook CLI
+
+> สถานะ project ปัจจุบัน (อัปเดตเมื่อ priority/blocker เปลี่ยน)
+
+## Now
+
+- 2026-06-20: Release **0.5.3** — brain pack/new/repair/consolidate/metrics, MCP enable/risk, gateway doctor, web_fetch, sanook init, TUI session/transcript polish
+- 2026-06-20: **Project workspace auto-detect** — cwd ↔ `Projects/<slug>/repo.md` injects hot project context into agent prompt
+- Active focus: multi-project vault under `Projects/` as single Sanook brain for all repos
+
+## Blockers
+
+_(none)_
+
+## Next
+
+- [ ] Dogfood project auto-detect on every repo under `Projects/`
+- [ ] Add next project workspace with `sanook brain new project --title "..." --repo /path`
+- [ ] Scheduled `sanook brain consolidate --apply` (weekly hook)
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/Projects/sanook-cli/overview.md

@@ -0,0 +1,41 @@
+---
+tags: [project, project-overview, sanook-cli]
+note_type: project-overview
+status: active
+created: 2026-06-20
+updated: 2026-06-20
+parent: "[[Projects/sanook-cli/_Index]]"
+repo_path: /Users/chawakornbuasontorn/dev/sanook-cli
+---
+
+> Project overview — goal, scope, stack, and verify commands for Sanook CLI.
+
+# Sanook CLI
+
+## เป้าหมาย (Goal)
+
+Terminal AI coding agent (BYOK) with durable second-brain memory across sessions — the moat vs Claude Code / Codex / Gemini CLI.
+
+## Scope / Non-goals
+
+- In scope: agent loop, MCP, gateway, second-brain vault tooling, search, TUI
+- Out of scope: hosted SaaS, OAuth/subscription key reuse, Hermes full TUI port
+
+## Tech / Stack
+
+- Node ≥ 22, TypeScript strict, Vercel AI SDK 6, Ink REPL
+- Vitest CI, bundled `second-brain/` vault template ships with npm package
+
+## Verify
+
+```bash
+npm run typecheck && npm test
+```
+
+## Related
+
+- Repo map: [[Projects/sanook-cli/repo]]
+- Live status: [[Projects/sanook-cli/current-state]]
+- Roadmap: [[Projects/sanook-cli/second-brain-feature-roadmap]]
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/Projects/sanook-cli/repo.md

@@ -0,0 +1,34 @@
+---
+tags: [project, repo, sanook-cli]
+note_type: project-repo
+created: 2026-06-20
+updated: 2026-06-20
+parent: "[[Projects/sanook-cli/_Index]]"
+---
+
+> Machine-readable repo mapping — Sanook auto-detects this project when cwd is inside the repo.
+
+# Repo — Sanook CLI
+
+> Machine-readable repo mapping for Sanook project auto-detect.
+
+repo_path: /Users/chawakornbuasontorn/dev/sanook-cli
+default_branch: main
+verify: npm run typecheck && npm test
+
+## Paths
+
+| What | Path |
+|---|---|
+| Repository | `/Users/chawakornbuasontorn/dev/sanook-cli` |
+| Vault (bundled) | `second-brain/` |
+| Project notes | `second-brain/Projects/sanook-cli/` |
+
+## Commands
+
+```bash
+cd /Users/chawakornbuasontorn/dev/sanook-cli
+npm run typecheck && npm test
+```
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/Projects/sanook-cli/second-brain-feature-roadmap.md

@@ -0,0 +1,197 @@
+---
+tags: [project, sanook-cli, second-brain, roadmap]
+note_type: project-overview
+created: 2026-06-18
+updated: 2026-06-20
+parent: "[[Projects/sanook-cli/_Index]]"
+source::
+  - src/bin.ts
+  - src/brain.ts
+  - src/memory.ts
+  - src/knowledge.ts
+  - src/mcp-server.ts
+  - src/search/indexer.ts
+  - src/brain-pack.ts
+  - src/brain-new.ts
+  - src/brain-repair.ts
+  - src/brain-consolidate.ts
+  - src/brain-metrics.ts
+  - src/context-pack.ts
+  - second-brain/SANOOK.md
+related:: [[Research/2026-06-18-hermes-cli-second-brain-expansion-research]]
+---
+
+# Sanook CLI Second-Brain Feature Roadmap
+
+> Implementation roadmap for doing the second-brain work inside Sanook CLI itself. This supersedes Hermes-specific next actions unless the task is explicitly about Hermes compatibility.
+
+## Current Sanook Capabilities
+
+- `sanook brain init [path]` scaffolds the vault, writes `SANOOK.md`, and stores `brainPath`.
+- `wireBrainMcp()` adds a filesystem MCP server for the vault under `~/.sanook/mcp.json`.
+- `buildBrainContext()` injects `Shared/AI-Context-Index.md`, `current-state.md`, Memory-Inbox candidates, and **auto-selected context packs** into agent context.
+- `remember` writes to Sanook memory store and routes facts into vault Memory-Inbox.
+- Headless sessions append a daily worklog into `Sessions/`.
+- `sanook index` incrementally indexes vault + memory + sessions + skills.
+- `sanook search` gives BM25 plus optional semantic/hybrid search over the unified index.
+- `sanook mcp serve` exposes `sanook_search`, `sanook_recall`, `sanook_remember`, `sanook_index`, and `sanook_stats`.
+- `sanook brain pack list|show`, `brain new`, `brain repair`, `brain consolidate`, and `brain metrics` operate on the configured vault from the CLI.
+
+## Correct Direction
+
+Do not make the next step `HERMES.md`. For Sanook CLI, the better work is:
+
+1. Make Sanook able to inspect and repair its own second-brain.
+2. Make Sanook able to assemble task-focused context from the vault.
+3. Make Sanook able to run lightweight evals against the vault.
+4. Keep the scaffold taxonomy stable until a command proves a new folder is necessary.
+
+## P0 Features
+
+### `sanook brain doctor`
+
+Status: implemented.
+
+Check the vault itself, not just installation:
+
+- `brainPath` configured and exists.
+- Hot files exist: `SANOOK.md`, `Shared/AI-Context-Index.md`, `Vault Structure Map.md`, `Shared/Operating-State/current-state.md`.
+- Every markdown seed has purpose blockquote, `parent`, and `up::` where expected.
+- `Vault Structure Map.md` mentions every `FOLDERS[]` entry.
+- Search index exists and is fresh enough compared with vault mtimes.
+- MCP wiring points to the configured vault.
+
+### `sanook brain context [--task "..."]`
+
+Status: implemented.
+
+Show the exact context Sanook would inject or retrieve:
+
+- Hot context sources and character counts.
+- Optional task query that runs search and prints top vault/session/skill hits.
+- Clear warning when context is stale, too large, or missing expected files.
+
+### `sanook brain eval`
+
+Status: implemented.
+
+Turn `Evals/second-brain-benchmarks.md` into a runnable sanity check:
+
+- Static cases: required files, routing links, memory policy, index presence.
+- Retrieval cases: search for known benchmark phrases and verify expected files appear.
+- Output pass/partial/fail with file evidence.
+
+## P1 Features
+
+### `sanook brain review`
+
+Status: implemented.
+
+Curator-style health review for the vault:
+
+- Stale context packs.
+- Duplicate or contradictory memory candidates.
+- Sessions without index entries.
+- Evals that have not been updated after framework changes.
+- Markdown routing hygiene: purpose blockquote, `parent`, and `up::`.
+
+### `sanook brain pack list|show`
+
+Status: implemented (2026-06-20).
+
+- List available packs with descriptions and index link status.
+- Show pack sources, load order, done criteria, and expected use cases.
+- Agent auto-selects a pack via `buildBrainContext({ taskQuery })` and per-turn retrieval when the query matches a pack.
+
+### `sanook brain new <type>`
+
+Status: implemented (2026-06-20).
+
+Template-backed note creation:
+
+- `session`, `bug`, `handoff`, `project`, `golden-case`, `checklist`.
+- Reads destination `_Index.md`, fills frontmatter, and prevents wrong-folder drift.
+
+### `sanook brain consolidate`
+
+Status: implemented (2026-06-20).
+
+Sleep-time consolidation runner based on `Runbooks/sleep-time-consolidation.md`:
+
+- Inbox routing/dedup, stale → archive, retrieval eval, optional auto-memory merge.
+- Dry-run by default; `--apply` / `--apply --archive` / `--memory` for writes.
+
+## P2 Features
+
+- `sanook brain export --for claude|gemini|codex|hermes` for adapter files only when explicitly needed.
+- `sanook brain metrics` — **implemented (2026-06-20)**: counts, stale notes, index freshness, retrieval coverage.
+- `sanook brain repair` — **implemented (2026-06-20)**: safe one-line fixes after `doctor`/`review` (purpose blockquote, `parent`, `up::`, pack links, scaffold folders).
+
+## Folder Policy
+
+No new root folder is needed yet.
+
+Add folders only when a Sanook command needs stable output:
+
+- `Evals/Benchmarks/` when `sanook brain eval` wants per-case files.
+- `Acceptance/Golden-Cases/` when golden fixtures multiply.
+- `Reviews/Vault-Health/` when `sanook brain review` starts writing scheduled reports. The current command is read-only, so no new folder is needed yet.
+
+Avoid broad folders:
+
+- No `Resources/`
+- No `Notes/`
+- No root `AI/`
+- No root `Experiments/`
+
+## First Implementation Slice
+
+Completed on 2026-06-18:
+
+1. Added `src/brain-doctor.ts` with pure check functions and CLI wiring.
+2. Added `src/brain-context.ts` so Sanook can inspect the exact prompt context and task retrieval hits.
+3. Added `src/brain-eval.ts` as a runnable benchmark sanity checker over `Evals/second-brain-benchmarks.md`.
+4. Updated shell/REPL help and changelog.
+5. Verified with targeted second-brain tests and typecheck.
+
+## Second Implementation Slice
+
+Completed on 2026-06-18:
+
+1. Added `src/brain-review.ts` for curator-style vault review.
+2. Wired `sanook brain review [--no-hygiene]` into CLI and help.
+3. Updated generated `Shared/Context-Packs/_Index.md` to link bundled context packs.
+4. Verified with review/scaffold/memory tests and typecheck.
+
+## Third Implementation Slice
+
+Completed on 2026-06-20 (release 0.5.3):
+
+1. Added `src/brain-pack.ts` — `sanook brain pack list|show`.
+2. Added `src/brain-new.ts` — `sanook brain new <type>`.
+3. Added `src/brain-repair.ts` — `sanook brain repair [--dry-run]`.
+4. Added `src/brain-consolidate.ts` — `sanook brain consolidate [--apply]`.
+5. Added `src/brain-metrics.ts` — `sanook brain metrics`.
+6. Added `src/context-pack.ts` — pack catalog + auto-select in `buildBrainContext()` / `buildTurnRetrieval()`.
+7. Verified with targeted tests, full suite (1210 tests), and typecheck.
+
+## Next Implementation Slice
+
+Best next code slice:
+
+1. Scheduled `sanook brain consolidate --apply` hook/cron integration for unattended sleep-time loops.
+2. Richer pack auto-select (user-defined packs beyond bundled three) with `brain pack` discoverability in setup wizard.
+3. `sanook brain export --for claude|gemini|codex|hermes` when adapter portability is explicitly needed.
+
+## Project Portfolio (2026-06-20)
+
+Status: **implemented** — multi-project vault via `Projects/<slug>/` + cwd auto-detect.
+
+- Standard workspace files: `overview.md`, `current-state.md`, `context.md`, `repo.md` (`repo_path`, `verify`, `default_branch`)
+- `sanook brain new project --title "..." --repo /path`
+- `sanook brain projects list`
+- Agent injects `<project_workspace>` when cwd matches `repo_path`
+- `sanook brain context --project <slug>` for forced selection
+- `brain init` skips copying bundled `Projects/<slug>/` (add projects explicitly)
+
+up:: [[Projects/sanook-cli/_Index]]

package/second-brain/README.md

@@ -23,7 +23,7 @@
 1. เปิดโฟลเดอร์นี้ใน **Obsidian** (Open folder as vault)
 2. ให้ AI agent อ่าน `Shared/AI-Context-Index.md` ก่อนทำงานเสมอ
 3. ก่อนสร้างหรือย้ายโน้ต ให้เลือกปลายทางจาก `Vault Structure Map.md` แล้วอ่าน `_Index.md` ของโฟลเดอร์นั้นเพื่อทำตาม **AI Routing Contract**
-4. constitution อยู่ที่ `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` — กฎปฏิบัติของ AI
+4. constitution อยู่ที่ `CLAUDE.md` / `GEMINI.md` / `AGENTS.md` / `SANOOK.md` — กฎปฏิบัติของ AI
 
 ## ปรับให้เป็นของคุณ
 

package/second-brain/Research/2026-06-17-ai-second-brain-method-experiment.md

@@ -0,0 +1,108 @@
+---
+tags: [research, second-brain, ai, experiment]
+note_type: research-note
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Research/_Index]]"
+source::
+  - "[[Shared/Scripts/ai-second-brain-method-eval.mjs]]"
+  - "https://arxiv.org/abs/2307.03172"
+  - "https://arxiv.org/abs/2310.11511"
+  - "https://arxiv.org/abs/2404.16130"
+---
+
+# AI Second-Brain Method Experiment — 2026-06-17
+
+> คำถามทดลอง: วิธีจัด second-brain แบบไหนทำให้ AI ใช้งาน vault ได้แม่นที่สุด โดยไม่โหลด context เกินจำเป็น?
+
+## Hypothesis
+
+วิธีที่ดีที่สุดไม่ใช่การให้ AI โหลดทั้ง vault หรือจำจาก session log แต่คือ:
+
+**Single Retrieval Path + JIT Task Rules + Explicit Write Routing + Eval/Consolidation Loop**
+
+ชื่อที่ใช้ใน framework: **Scientific Loop Sequence**.
+
+## Method
+
+รันสคริปต์:
+
+```bash
+node second-brain/Shared/Scripts/ai-second-brain-method-eval.mjs second-brain
+```
+
+สคริปต์เทียบ 5 วิธี:
+
+| Method | แนวคิด |
+|---|---|
+| Session-log only | ใช้ session history เป็น memory หลัก |
+| Folder map only | ใช้ `Vault Structure Map.md` และ index ปลายทาง |
+| Single retrieval index | เริ่มจาก `Shared/AI-Context-Index.md` |
+| Index + JIT context policy | single index + context assembly + โหลดเฉพาะไฟล์จำเป็น |
+| Scientific loop sequence | single index + JIT + write protocol + eval + sleep consolidation + coordination |
+
+Scenarios ที่ใช้วัด:
+
+1. เริ่มงานกับ AI โดยไม่หลุด source of truth
+2. สร้าง/แก้ durable note ให้ถูกที่และค้นเจอภายหลัง
+3. บันทึก preference/decision/fact โดยไม่ append ซ้ำ
+4. นำข้อมูลภายนอกเข้า vault แบบปลอด prompt injection
+5. ทำ sleep-time consolidation และปิด loop ความจำ
+6. กันหลาย agent ชนกันและส่งต่องานได้
+7. งานเทคนิคที่ต้อง verify ก่อนสรุป
+
+Metric:
+
+- **File coverage**: context มีไฟล์ที่ scenario ต้องใช้ไหม
+- **Capability coverage**: วิธีนั้นมี retrieval/routing/eval/memory/coordination ครบไหม
+- **Token economy**: context เฉลี่ยยังใกล้ budget หรือไม่
+
+## Results
+
+| Rank | Method | Score | File Coverage | Capability Coverage | Avg Tokens |
+|---:|---|---:|---:|---:|---:|
+| 1 | Scientific loop sequence | 97.0 | 100% | 100% | ~2890 |
+| 2 | Index + JIT context policy | 62.6 | 64% | 43% | ~2235 |
+| 3 | Single retrieval index | 40.6 | 39% | 18% | ~1932 |
+| 4 | Folder map + destination indexes | 20.8 | 13% | 18% | ~2598 |
+| 5 | Session-log only | 16.4 | 6% | 10% | ~313 |
+
+## Interpretation
+
+**Winner: Scientific Loop Sequence.**
+
+เหตุผล:
+
+- ครอบคลุมงาน AI กับ second-brain ได้ครบทุก scenario
+- ลด hallucination เพราะเริ่มจาก single source of truth แล้วค่อย expand context
+- ลด memory rot เพราะ write operation ต้องเลือก ADD/UPDATE/DELETE/NOOP
+- ลด context rot เพราะใช้ `context-assembly-policy` ก่อนโหลด task rules
+- มี feedback loop จริงผ่าน `eval-loop` และ `sleep-time-consolidation`
+
+ข้อควรระวัง:
+
+- Avg tokens ~2890 สูงกว่า target ~2k
+- บาง scenario สูงเพราะต้องโหลดไฟล์ใหญ่ เช่น `Vault Structure Map.md` และ ingest rules
+- ดังนั้น implementation ต้องใช้แบบ **JIT**: โหลด heading/index ก่อน, expand body เฉพาะเมื่อจำเป็น, และอย่า preload ทุก rule ทุกครั้ง
+
+## Literature Anchor
+
+- Lost in the Middle สนับสนุนว่า context ยาวและตำแหน่งกลางทำให้ retrieval/usefulness ลดลง จึงควรวาง load-bearing context ไว้หัว/ท้าย
+- Self-RAG สนับสนุน retrieve-then-critique/evaluate loop แทนการตอบจาก memory ล้วน
+- GraphRAG สนับสนุนการจัดความรู้เป็น graph/index แทนการกองเอกสารแบบ flat
+
+## Decision
+
+ใช้ **Scientific Loop Sequence** เป็น default AI operating sequence ของ vault:
+
+1. Frame objective/DoD
+2. Retrieve hot context via `Shared/AI-Context-Index.md`
+3. Select AI role for the current phase
+4. Load task-specific rules JIT
+5. Act and verify
+6. Write memory with explicit operation
+7. Eval if non-trivial
+8. Consolidate later via sleep-time loop
+
+related:: [[Runbooks/ai-second-brain-operating-sequence]]
+up:: [[Research/_Index]]

package/second-brain/Research/2026-06-18-ai-token-reduction-frameworks.md

@@ -0,0 +1,55 @@
+---
+tags: [research, token-reduction, ai-agent, sanook-cli]
+note_type: research
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source:
+  - https://github.com/microsoft/LLMLingua
+  - https://github.com/liyucheng09/Selective_Context
+  - https://github.com/chopratejas/headroom
+---
+
+# AI Token Reduction Frameworks for Sanook CLI
+
+> Research note for choosing a token-reduction framework/pattern to integrate into Sanook CLI.
+
+## Candidates
+
+- Microsoft LLMLingua: strong prompt-compression family, but Python/model-heavy for a Node CLI default.
+- Selective Context: removes low-information lexical units; good fit for a zero-LLM local compressor.
+- Headroom: TypeScript package with Vercel AI SDK adapter, but direct compression requires a running proxy or cloud API key.
+
+## Decision
+
+Use a Sanook-native zero-dependency selective context compressor as the default, and expose Headroom as an optional framework mode.
+
+Rationale:
+
+- Works by default without a Python runtime, model download, proxy, or extra API key.
+- Fits the current Sanook architecture because the biggest waste is stale tool output in multi-step agent loops.
+- Keeps recent tool results full, preserving local correctness while reducing old transcript bloat.
+- Lets users opt into the actual `headroom-ai` Vercel AI SDK adapter when they have a Headroom proxy/cloud compression layer.
+
+## Implementation Shape
+
+- New `contextCompression` config: `selective` (default), `headroom`, or `off`.
+- `SANOOK_CONTEXT_COMPRESSION=off` disables it.
+- `SANOOK_CONTEXT_COMPRESSION=headroom` wraps the Vercel AI SDK model with `headroom-ai/vercel-ai`.
+- `SANOOK_HEADROOM_BASE_URL` and `SANOOK_HEADROOM_API_KEY` can point Sanook at the user's Headroom setup.
+- `selectiveCompressText()` keeps head/tail anchors and high-information lines:
+  - current user-query matches
+  - errors, warnings, failures, tracebacks
+  - file paths and line numbers
+  - diffs and code structure
+  - headings / JSON-like structure
+  - rare lexical terms
+- `selectivelyCompressStaleToolResults()` applies it only to old large tool outputs before each model step.
+- Older stale tool outputs get tighter budgets; the newest tail remains full.
+
+## Verification
+
+- Unit tests cover preservation of query matches, errors, code/diff structure, unchanged short text, stale-tool compression, recency budgets, and recent-tail preservation.
+- Full validation still needs `typecheck`, full test suite, and build after implementation.
+
+up:: [[Research/_Index]]