sanook-cli 0.5.0 → 0.5.2

package/second-brain/Sessions/2026-06-18-token-reduction-framework-integration.md

@@ -0,0 +1,69 @@
+---
+tags: [session, token-reduction, sanook-cli, ai-agent]
+note_type: session-log
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Sessions/_Index]]"
+ai_surface: history
+---
+
+# 2026-06-18 - Token Reduction Framework Integration
+
+> Session log for researching GitHub token-reduction frameworks and integrating a safe default into Sanook CLI.
+
+## Summary
+
+- Compared GitHub frameworks/patterns: Microsoft LLMLingua, Selective Context, and Headroom.
+- Chose a Sanook-native selective context compressor as the default because it works without Python, model downloads, proxy services, or extra keys.
+- Added `contextCompression: selective | headroom | off` with `SANOOK_CONTEXT_COMPRESSION`.
+- Integrated the actual `headroom-ai` Vercel AI SDK adapter as an optional framework mode.
+- Improved local selective mode with query-aware scoring and adaptive budgets for older stale tool outputs.
+- Wired selective compression into the Vercel AI SDK `prepareStep` path, targeting stale huge tool outputs only.
+
+## What Was Tried
+
+- Inspected Sanook's existing token controls: prompt cache, auto-compaction, summarize-compaction, subagents, read ranges, output truncation.
+- Checked `headroom-ai` npm package and Vercel AI adapter.
+- Decided not to require Headroom by default because direct compression requires a proxy/cloud key, but added opt-in support.
+
+## Errors
+
+- A first patch to `selectivelyCompressStaleToolResults()` returned too early and left unreachable code; fixed by returning the mapped output only when a change occurred.
+- A broad test patch missed exact context; re-applied as focused patches.
+
+## Solutions
+
+- Added `src/context-compression.ts` with `selectiveCompressText()`.
+- Added `selectivelyCompressStaleToolResults()` in `src/compaction.ts`.
+- Updated `src/loop.ts` to apply selective compression before `autoCompact()`.
+- The compressor now uses the latest user message to boost relevant lines and spends fewer chars on older stale tool results.
+- Updated config schema, env parsing, CLI validation, README, changelog, and tests.
+- Added `headroom-ai` as a dependency for optional framework-backed compression.
+
+## Key Decisions
+
+- Preserve recent tool results fully.
+- Compress only stale large tool output, not user intent or recent evidence.
+- Keep this zero-LLM by default; use Headroom only when the user opts into a proxy/cloud setup.
+
+## Files Changed
+
+- `src/context-compression.ts`
+- `src/context-compression.test.ts`
+- `src/compaction.ts`
+- `src/compaction.test.ts`
+- `src/config.ts`
+- `src/config.test.ts`
+- `src/loop.ts`
+- `src/bin.ts`
+- `README.md`
+- `CHANGELOG.md`
+- `second-brain/Research/2026-06-18-ai-token-reduction-frameworks.md`
+
+## Next Steps
+
+- Run typecheck and tests.
+- Benchmark local selective mode with real multi-step traces.
+- Smoke test Headroom mode against a real proxy/cloud setup when credentials are available.
+
+up:: [[Sessions/_Index]]

package/second-brain/Sessions/_Index.md

@@ -25,6 +25,20 @@ code/config · subfolder (Sessions = flat เสมอ)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Sessions
+
+- [[Sessions/2026-06-17-ai-second-brain-sequence-experiment]] — ทดลองและปรับ AI operating sequence ของ second-brain
+- [[Sessions/2026-06-17-ai-framework-additional-zones]] — เพิ่ม benchmark, response examples, และ context packs เข้า framework
+- [[Sessions/2026-06-18-framework-dogfood-permission-and-memory]] — ใช้ context packs ใหม่กับ permission/tools + memory update + benchmark dogfood
+- [[Sessions/2026-06-18-cli-args-release-readiness]] — ตรวจ cli-args serve port UX + release readiness gates
+- [[Sessions/2026-06-18-hermes-second-brain-expansion-research]] — วิจัยว่า second-brain ควรเพิ่มอะไรเพื่อรองรับ Hermes CLI ให้ดีขึ้น
+- [[Sessions/2026-06-18-sanook-cli-second-brain-roadmap-correction]] — correction: เป้าจริงคือทำ second-brain feature ใน Sanook CLI
+- [[Sessions/2026-06-18-sanook-brain-cli-p0-implementation]] — implement `brain doctor`, `brain context`, `brain eval`, and `brain review`
+- [[Sessions/2026-06-18-final-gate-template]] — add evidence-backed [[Templates/final]] final gate
+- [[Sessions/2026-06-18-final-gate-template-final]] — evidence-backed closeout for the final gate template work
+- [[Sessions/2026-06-18-sanook-brain-final-cli]] — implement `sanook brain final`, final-lite, review validation, and eval coverage
+- [[Sessions/2026-06-18-sanook-brain-final-cli-final]] — evidence-backed closeout for the Sanook brain final CLI work
+- [[Sessions/2026-06-18-mcp-ecosystem-and-sanook-ux-scan]] — scan Sanook MCP support and registry-based integration opportunities
+- [[Sessions/2026-06-18-token-reduction-framework-integration]] — integrate selective context compression after GitHub framework scan
 
 up:: [[Home]]

package/second-brain/Shared/AI-Context-Index.md

@@ -28,6 +28,23 @@ ai_surface: hot
 4. [[Shared/Decision-Memory/decision-log]] — ตัดสินใจอะไรไปแล้ว
 5. งาน project → [[Projects/_Index]] → overview → context → current-state
 
+## Best AI Operating Sequence
+
+> default สำหรับงานไม่ trivial: [[Runbooks/ai-second-brain-operating-sequence]]
+
+**Frame → Retrieve → Role → JIT Rules → Act → Write → Eval → Consolidate**
+
+- เริ่มด้วย hot path ด้านบนเสมอ
+- เลือกบทบาท AI ก่อนลงมือ: Scientist / Cartographer / Librarian / Operator / Editor / Archivist
+- ถ้ามี pack ตรงงาน ให้ใช้ [[Shared/Context-Packs/_Index]] แทนการประกอบ context ใหม่จากศูนย์
+- โหลด rule/runbook เฉพาะ task นั้นแบบ JIT; อย่าโหลดทั้ง vault
+- งาน framework/หลาย session/แก้ durable memory ให้ eval และบันทึก evidence
+
+## Taste & Benchmarks
+
+- owner-facing tone/examples → [[Shared/User-Memory/response-examples]]
+- framework quality checks → [[Evals/second-brain-benchmarks]]
+
 ## Default Write Path (ก่อนสร้าง/แก้โน้ต)
 
 1. Classify artifact: project work, session log, decision, preference, source, reusable skill, runbook, or temporary scratch
@@ -50,11 +67,16 @@ ai_surface: hot
 | scratch ระหว่างงานเดียว | `Shared/Working-Memory/<topic>.md` |
 | expected output fixture | [[Acceptance/golden-case-template]] |
 | pre/postflight gate | [[Checklists/preflight-postflight-template]] |
+| final phase / evidence-backed closeout | [[Templates/final]] หรือ [[Templates/final-lite]]; CLI: `sanook brain final --task "..." [--from-diff] [--lite]` |
 | entity/person/org page | `Entities/<name>.md` |
 | อื่นๆ / ไม่แน่ใจว่าโฟลเดอร์ไหน | [[Vault Structure Map]] |
 
 ## Framework Rules (โหลดตาม task — ดู CLAUDE.md §19)
 
+- **งานไม่ trivial ทุกงาน** → [[Runbooks/ai-second-brain-operating-sequence]] (Scientific Loop Sequence + roles)
+- **งานซ้ำ/task family ชัดเจน** → [[Shared/Context-Packs/_Index]] (ใช้ context pack แทน assemble ใหม่)
+- **ก่อน/หลังแก้ framework** → [[Evals/second-brain-benchmarks]] (วัดว่าดีขึ้นจริงไหม)
+- **ก่อนตอบว่าเสร็จแล้วในงานไม่ trivial** → `sanook brain final --task "..." [--from-diff]` หรือ [[Templates/final]] / [[Templates/final-lite]] + [[Shared/Tech-Standards/verification-standard]]
 - **ก่อนประกอบ context เสมอ** → [[Shared/Rules/context-assembly-policy]] (head/tail + budget, กัน context-rot)
 - ingest ของนอก → [[Runbooks/ingest-quarantine]] · fact → [[Shared/Rules/frontmatter-standard]] (bi-temporal + `source::`)
 - script ทำซ้ำ → [[Shared/Rules/skills-admission]] (Skills/) · consolidate → [[Runbooks/sleep-time-consolidation]]

package/second-brain/Shared/Context-Packs/_Index.md

@@ -25,6 +25,14 @@ pack รวม context พร้อมโหลด
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Context Packs
+
+- [[Shared/Context-Packs/second-brain-maintenance]] — แก้ vault structure, routing, memory policy, indexes, runbooks, agent adapters
+- [[Shared/Context-Packs/coding-release]] — แก้ code/tests/build/release/CLI scripts
+- [[Shared/Context-Packs/research-to-framework]] — research/experiment → framework update
+
+## Use Rule
+
+โหลด pack เมื่อ task ตรงกับ pack ชัดเจน; ถ้าไม่ตรงให้ใช้ [[Shared/AI-Context-Index]] + JIT rules ปกติ
 
 up:: [[Shared/_Index]]

package/second-brain/Shared/Context-Packs/coding-release.md

@@ -0,0 +1,51 @@
+---
+tags: [context-pack, coding, release, verification]
+note_type: context-pack
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/Context-Packs/_Index]]"
+---
+
+# Context Pack: Coding & Release Work
+
+> Use when changing source code, tests, build/release behavior, CLI commands, or scripts that affect runtime behavior.
+
+## Load Order
+
+1. [[Shared/AI-Context-Index]]
+2. [[Runbooks/ai-second-brain-operating-sequence]]
+3. [[Shared/Tech-Standards/verification-standard]]
+4. Relevant project/source files
+5. Relevant tests
+6. [[Evals/second-brain-benchmarks]] only if the change affects AI/vault framework
+
+## Required Role
+
+- Primary: Operator
+- Secondary: Scientist
+
+## Verification Menu
+
+Pick the narrowest set that proves the change:
+
+- targeted test
+- full test suite
+- typecheck
+- build
+- smoke command
+- diff/scan gate
+
+## Output Artifacts
+
+- Code/test/docs changes
+- Short owner-facing summary with verification
+- Session log if the work is non-trivial or changes durable framework behavior
+
+## Done Criteria
+
+- Source read before editing
+- Tests or explicit unable-to-run note
+- No destructive command without owner approval
+- Residual risk stated if verification is partial
+
+up:: [[Shared/Context-Packs/_Index]]

package/second-brain/Shared/Context-Packs/research-to-framework.md

@@ -0,0 +1,51 @@
+---
+tags: [context-pack, research, framework, ai]
+note_type: context-pack
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/Context-Packs/_Index]]"
+---
+
+# Context Pack: Research To Framework
+
+> Use when the owner asks for best method, comparison, experiment, or turning research into framework changes.
+
+## Load Order
+
+1. [[Shared/AI-Context-Index]]
+2. [[Runbooks/ai-second-brain-operating-sequence]]
+3. [[Shared/Rules/context-assembly-policy]]
+4. [[Evals/second-brain-benchmarks]]
+5. Relevant prior research notes
+6. Target framework files or destination `_Index.md`
+
+## Required Role
+
+- Primary: Scientist
+- Secondary: Librarian
+
+## Method
+
+1. State hypothesis.
+2. Define candidates.
+3. Define metrics before judging.
+4. Run a small reproducible check when possible.
+5. Record result in `Research/` if it is evidence-bearing.
+6. Promote the winner into `Runbooks/`, `Rules/`, `Context-Packs/`, or `Playbooks/` only after evidence.
+7. Wire the result into indexes/hot path.
+
+## Output Artifacts
+
+- Research note with method/results
+- Framework/runbook/rule update
+- Quality-ledger entry for non-trivial changes
+- Session log when files are changed
+
+## Done Criteria
+
+- Recommendation is evidence-backed
+- Tradeoffs are explicit
+- Framework is actually changed, not only summarized
+- Owner-facing final answer names files and verification
+
+up:: [[Shared/Context-Packs/_Index]]

package/second-brain/Shared/Context-Packs/second-brain-maintenance.md

@@ -0,0 +1,41 @@
+---
+tags: [context-pack, second-brain, maintenance]
+note_type: context-pack
+created: 2026-06-17
+updated: 2026-06-17
+parent: "[[Shared/Context-Packs/_Index]]"
+---
+
+# Context Pack: Second-Brain Maintenance
+
+> Use when editing vault structure, routing rules, memory policy, indexes, runbooks, or agent adapters.
+
+## Load Order
+
+1. [[Shared/AI-Context-Index]]
+2. [[Runbooks/ai-second-brain-operating-sequence]]
+3. [[Vault Structure Map]]
+4. [[Shared/Rules/context-assembly-policy]]
+5. Destination `_Index.md`
+6. [[Shared/Rules/memory-write-protocol]] if changing memory/facts
+7. [[Evals/second-brain-benchmarks]] before and after framework edits
+
+## Required Role
+
+- Primary: Librarian
+- Secondary: Scientist
+
+## Output Artifacts
+
+- Updated target note/index
+- Quality/evidence note when non-trivial: [[Evals/quality-ledger]] or [[Sessions/_Index]]
+- No new root folder unless [[Vault Structure Map]] is updated and drift tests are considered
+
+## Done Criteria
+
+- New/changed notes have `parent` and `up::`
+- Index links make the artifact discoverable
+- Benchmark or explicit verification is recorded
+- Context bloat is checked; do not preload every rule
+
+up:: [[Shared/Context-Packs/_Index]]

package/second-brain/Shared/Operating-State/current-state.md

@@ -13,11 +13,24 @@ ai_surface: starter
 
 ## Now
 
-_(งาน/โฟกัสหลักตอนนี้ — ยังว่าง)_
+- 2026-06-17: ปรับ second-brain ให้ใช้ [[Runbooks/ai-second-brain-operating-sequence]] เป็น default AI operating sequence หลังทดลองเทียบ methods แล้ว
+- 2026-06-17: เพิ่ม [[Evals/second-brain-benchmarks]], [[Shared/User-Memory/response-examples]], และ context packs ใน [[Shared/Context-Packs/_Index]]
+- 2026-06-18: dogfood context packs กับงานจริง 3 task-family แล้ว: coding-release, second-brain-maintenance, research-to-framework
+- 2026-06-18: ตรวจ cli-args serve port UX change แล้ว; targeted/full tests, typecheck, build, diff check ผ่าน
+- 2026-06-18: วิจัย Hermes CLI second-brain expansion ไว้เป็น reference; เจ้าของ clarify ว่าเป้าจริงคือทำใน Sanook CLI
+- 2026-06-18: Sanook-native P0 implemented: `sanook brain doctor`, `sanook brain context`, `sanook brain eval`
+- 2026-06-18: เพิ่ม `sanook brain review` เป็น curator review แบบ read-only สำหรับ inbox/context-packs/sessions/evals/note hygiene
+- 2026-06-18: เพิ่ม [[Templates/final]] เป็น final gate / evidence matrix ก่อนปิดงาน non-trivial
+- 2026-06-18: เพิ่ม `sanook brain final`, [[Templates/final-lite]], final-gate validator ใน `brain review`, และ `SB-FINAL` ใน `brain eval` แล้ว
+- 2026-06-18: MCP P0 implemented ใน Sanook CLI แล้ว: registry-backed `mcp search/info/install/preset/test/doctor/list --tools`; verification ผ่าน และพบว่า GitLab remote ต้อง auth header ก่อน probe ผ่าน
+- 2026-06-18: เพิ่ม [[Research/2026-06-18-ai-token-reduction-frameworks]], default query-aware selective context compression, adaptive stale-tool budgets, และ optional Headroom framework mode ใน Sanook CLI
 
 ## Active Bets
 
-_(สิ่งที่กำลังลงแรง/ลงทุน)_
+- Scientific Loop Sequence: single retrieval path + JIT task rules + explicit write routing + eval/consolidation loop
+- AI จะเก่งขึ้นแบบวัดได้เมื่อมี benchmark + taste examples + reusable context packs
+- Final gate ที่มี evidence และ CLI scaffold จะลดการ claim done เกินจริงตอนปิดงาน
+- Token/cost จะลดได้อย่างปลอดภัยที่สุดจาก stale tool-output compression ก่อน ไม่ใช่บีบ user intent หรือ recent evidence
 
 ## Blockers
 
@@ -25,6 +38,12 @@ _(ติดอะไรอยู่)_
 
 ## Next Actions
 
-- [ ] _(เริ่มจดงานแรกที่นี่)_
+- [ ] Review remaining worktree diff before commit/release
+- [ ] Dogfood `sanook brain final --task "..." --from-diff` ในงาน implementation ถัดไป
+- [x] ทำ MCP P0: `sanook mcp search`, `sanook mcp info`, `sanook mcp install`, `sanook mcp test`
+- [ ] MCP follow-up: auth hints for hosted remotes that return `401`, risk labels, and richer install preview/cache
+- [ ] Token compression follow-up: benchmark real multi-step traces and smoke test Headroom mode with a real proxy/cloud setup
+- [ ] ถ้าจะต่อ second-brain CLI รอบถัดไป: ทำ `sanook brain pack list|show`, `sanook brain new <type>`, หรือ `sanook brain repair`
+- [ ] เพิ่ม good/bad examples ใหม่ใน [[Shared/User-Memory/response-examples]] เมื่อมี feedback จริงรอบถัดไป
 
 up:: [[Shared/Operating-State/_Index]]

package/second-brain/Shared/Scripts/_Index.md

@@ -25,6 +25,8 @@ one-off ที่ retired (→Scripts-Archive)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Scripts
+
+- `Shared/Scripts/ai-second-brain-method-eval.mjs` — reproducible eval เปรียบเทียบ AI second-brain operating methods; ใช้เป็น evidence ของ [[Research/2026-06-17-ai-second-brain-method-experiment]]
 
 up:: [[Shared/_Index]]

package/second-brain/Shared/Scripts/ai-second-brain-method-eval.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const vault = process.argv[2] ?? 'second-brain';
+
+const files = {
+  aiIndex: 'Shared/AI-Context-Index.md',
+  user: 'USER.md',
+  currentState: 'Shared/Operating-State/current-state.md',
+  preferences: 'Shared/User-Memory/user-preferences.md',
+  decisions: 'Shared/Decision-Memory/decision-log.md',
+  structureMap: 'Vault Structure Map.md',
+  contextPolicy: 'Shared/Rules/context-assembly-policy.md',
+  noteRule: 'Shared/Rules/contextual-note-rule.md',
+  formatting: 'Shared/Rules/rules-formatting.md',
+  memoryWrite: 'Shared/Rules/memory-write-protocol.md',
+  frontmatter: 'Shared/Rules/frontmatter-standard.md',
+  ingest: 'Runbooks/ingest-quarantine.md',
+  sleep: 'Runbooks/sleep-time-consolidation.md',
+  evalLoop: 'Runbooks/eval-loop.md',
+  retrievalEval: 'Evals/retrieval-eval.md',
+  qualityLedger: 'Evals/quality-ledger.md',
+  verification: 'Shared/Tech-Standards/verification-standard.md',
+  coordinationNow: 'Shared/Coordination/NOW.md',
+  taskBoard: 'Shared/Coordination/task-board.md',
+  agentRegistry: 'Shared/Coordination/agent-registry.md',
+  sessionsIndex: 'Sessions/_Index.md',
+  runbooksIndex: 'Runbooks/_Index.md',
+  scriptsIndex: 'Shared/Scripts/_Index.md',
+};
+
+function fileTokens(path) {
+  const full = join(vault, path);
+  if (!existsSync(full)) return { exists: false, tokens: 0 };
+  return { exists: true, tokens: Math.ceil(readFileSync(full, 'utf8').length / 4) };
+}
+
+const scenarios = [
+  {
+    id: 'start-session',
+    label: 'เริ่มงานกับ AI โดยไม่หลุด source of truth',
+    required: [files.aiIndex, files.user, files.currentState, files.preferences, files.decisions],
+    capabilities: ['retrieval', 'state', 'preference'],
+  },
+  {
+    id: 'write-durable-note',
+    label: 'สร้าง/แก้ durable note ให้ถูกที่และค้นเจอภายหลัง',
+    required: [files.aiIndex, files.structureMap, files.contextPolicy, files.noteRule, files.formatting],
+    capabilities: ['retrieval', 'routing', 'write-contract', 'graph-linking'],
+  },
+  {
+    id: 'write-memory',
+    label: 'บันทึก preference/decision/fact โดยไม่ append ซ้ำ',
+    required: [files.aiIndex, files.memoryWrite, files.frontmatter, files.preferences, files.decisions],
+    capabilities: ['memory-op', 'dedupe', 'verification'],
+  },
+  {
+    id: 'ingest-source',
+    label: 'นำข้อมูลภายนอกเข้า vault แบบปลอด prompt injection',
+    required: [files.aiIndex, files.ingest, files.frontmatter, files.structureMap],
+    capabilities: ['ingest-safety', 'provenance', 'routing'],
+  },
+  {
+    id: 'consolidate',
+    label: 'ทำ sleep-time consolidation และปิด loop ความจำ',
+    required: [files.aiIndex, files.sleep, files.memoryWrite, files.retrievalEval, files.qualityLedger],
+    capabilities: ['consolidation', 'memory-op', 'eval'],
+  },
+  {
+    id: 'multi-agent',
+    label: 'กันหลาย agent ชนกันและส่งต่องานได้',
+    required: [files.aiIndex, files.coordinationNow, files.taskBoard, files.agentRegistry, files.sessionsIndex],
+    capabilities: ['coordination', 'handoff', 'session-log'],
+  },
+  {
+    id: 'technical-work',
+    label: 'งานเทคนิคที่ต้อง verify ก่อนสรุป',
+    required: [files.aiIndex, files.verification, files.evalLoop, files.sessionsIndex],
+    capabilities: ['verification', 'eval', 'session-log'],
+  },
+];
+
+const methods = [
+  {
+    id: 'session-log-only',
+    label: 'Session-log only',
+    filesFor: () => [files.sessionsIndex],
+    capabilities: ['session-log'],
+  },
+  {
+    id: 'folder-map-only',
+    label: 'Folder map + destination indexes',
+    filesFor: (scenario) => [files.structureMap, files.sessionsIndex, ...scenario.required.filter((p) => p.endsWith('_Index.md'))],
+    capabilities: ['routing', 'session-log'],
+  },
+  {
+    id: 'single-context-index',
+    label: 'Single retrieval index',
+    filesFor: () => [files.aiIndex, files.user, files.currentState, files.preferences, files.decisions],
+    capabilities: ['retrieval', 'state', 'preference'],
+  },
+  {
+    id: 'jit-context-policy',
+    label: 'Index + JIT context policy',
+    filesFor: (scenario) => [files.aiIndex, files.contextPolicy, ...scenario.required.slice(0, 3)],
+    capabilities: ['retrieval', 'state', 'preference', 'routing', 'write-contract', 'graph-linking', 'verification'],
+  },
+  {
+    id: 'scientific-loop-sequence',
+    label: 'Scientific loop sequence',
+    filesFor: (scenario) => [files.aiIndex, files.contextPolicy, ...scenario.required],
+    capabilities: [
+      'retrieval',
+      'state',
+      'preference',
+      'routing',
+      'write-contract',
+      'graph-linking',
+      'memory-op',
+      'dedupe',
+      'verification',
+      'ingest-safety',
+      'provenance',
+      'consolidation',
+      'eval',
+      'coordination',
+      'handoff',
+      'session-log',
+    ],
+  },
+];
+
+function uniq(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+function scoreScenario(method, scenario) {
+  const contextFiles = uniq(method.filesFor(scenario));
+  const fileStats = contextFiles.map((path) => ({ path, ...fileTokens(path) }));
+  const tokens = fileStats.reduce((sum, stat) => sum + stat.tokens, 0);
+  const requiredHits = scenario.required.filter((path) => contextFiles.includes(path) && fileTokens(path).exists).length;
+  const existingRequired = scenario.required.filter((path) => fileTokens(path).exists).length;
+  const fileCoverage = existingRequired ? requiredHits / existingRequired : 1;
+  const capabilityHits = scenario.capabilities.filter((cap) => method.capabilities.includes(cap)).length;
+  const capabilityCoverage = scenario.capabilities.length ? capabilityHits / scenario.capabilities.length : 1;
+  const economy = tokens <= 2200 ? 1 : Math.max(0, 1 - (tokens - 2200) / 2200);
+  const score = Math.round((fileCoverage * 70 + capabilityCoverage * 20 + economy * 10) * 10) / 10;
+  return { score, fileCoverage, capabilityCoverage, economy, tokens, contextFiles };
+}
+
+const rows = methods.map((method) => {
+  const perScenario = scenarios.map((scenario) => scoreScenario(method, scenario));
+  const avgScore = perScenario.reduce((sum, s) => sum + s.score, 0) / perScenario.length;
+  const avgTokens = perScenario.reduce((sum, s) => sum + s.tokens, 0) / perScenario.length;
+  const avgFileCoverage = perScenario.reduce((sum, s) => sum + s.fileCoverage, 0) / perScenario.length;
+  const avgCapabilityCoverage = perScenario.reduce((sum, s) => sum + s.capabilityCoverage, 0) / perScenario.length;
+  return {
+    method,
+    avgScore: Math.round(avgScore * 10) / 10,
+    avgTokens: Math.round(avgTokens),
+    avgFileCoverage: Math.round(avgFileCoverage * 100),
+    avgCapabilityCoverage: Math.round(avgCapabilityCoverage * 100),
+    perScenario,
+  };
+});
+
+rows.sort((a, b) => b.avgScore - a.avgScore);
+
+console.log('# AI Second-Brain Method Eval');
+console.log('');
+console.log(`vault: ${vault}`);
+console.log(`scenarios: ${scenarios.length}`);
+console.log('');
+console.log('| rank | method | score | file coverage | capability coverage | avg tokens |');
+console.log('|---:|---|---:|---:|---:|---:|');
+rows.forEach((row, idx) => {
+  console.log(
+    `| ${idx + 1} | ${row.method.label} | ${row.avgScore} | ${row.avgFileCoverage}% | ${row.avgCapabilityCoverage}% | ~${row.avgTokens} |`,
+  );
+});
+console.log('');
+console.log('## Scenario Detail');
+console.log('');
+for (const row of rows) {
+  console.log(`### ${row.method.label}`);
+  console.log('| scenario | score | tokens |');
+  console.log('|---|---:|---:|');
+  row.perScenario.forEach((result, idx) => {
+    console.log(`| ${scenarios[idx].label} | ${result.score} | ~${result.tokens} |`);
+  });
+  console.log('');
+}
+
+const best = rows[0];
+console.log('## Winner');
+console.log('');
+console.log(`${best.method.label} (${best.method.id})`);

package/second-brain/Shared/Tech-Standards/_Index.md

@@ -25,6 +25,9 @@ MCP/stack/DoD/verification rulebook
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Standards
+
+- [[Shared/Tech-Standards/verification-standard]] — verification ladder, evidence format, and final gate contract
+- [[Shared/Tech-Standards/mcp-integration-roadmap]] — MCP registry/install/test UX roadmap
 
 up:: [[Shared/_Index]]

package/second-brain/Shared/Tech-Standards/mcp-integration-roadmap.md

@@ -0,0 +1,86 @@
+---
+tags: [standard, mcp, integration, roadmap]
+note_type: standard-reference
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Shared/Tech-Standards/_Index]]"
+source:
+  - "[[Research/2026-06-18-sanook-mcp-ecosystem-and-ux-roadmap]]"
+---
+
+# MCP Integration Roadmap
+
+> Technical roadmap for making MCP easier and safer to use inside Sanook CLI.
+
+## Current Baseline
+
+- `src/mcp.ts` supports stdio MCP and remote Streamable HTTP.
+- `src/mcp-server.ts` exposes Sanook's brain as an MCP server.
+- `src/bin.ts` supports `mcp add/list/remove`, `mcp serve`, registry-backed `mcp search/info/install`, curated `mcp preset`, and `mcp test/doctor`.
+- `src/mcp-registry.ts` maps official registry remotes/packages into Sanook `mcp.json`.
+- Project MCP config remains behind `sanook trust`.
+
+## Target UX
+
+```text
+sanook mcp search github
+sanook mcp info com.gitlab/mcp
+sanook mcp install com.gitlab/mcp --name gitlab
+sanook mcp test gitlab
+sanook mcp doctor
+```
+
+## P0 Requirements
+
+1. Registry search - implemented
+   - Query official registry.
+   - Show latest versions only by default.
+   - Show server name, description, version, transport, package runtime, and source URL.
+2. Server info - implemented
+   - Show remotes/packages.
+   - Show required env/header inputs.
+   - Mark secret inputs.
+   - Show install command preview.
+3. Install - implemented
+   - Convert selected remote/package into Sanook `mcp.json`.
+   - Write explicit user-requested config only.
+   - Preserve `0600` permissions.
+   - Never inherit ambient provider API keys into MCP child env.
+4. Test - implemented
+   - Initialize one server.
+   - Run `tools/list`.
+   - Report tool count and tool names.
+   - Print clear failure reason and setup hints.
+
+## P1 Requirements
+
+- `sanook mcp doctor`: validate config shape, missing commands, missing env, unreachable remote, duplicate tool names.
+- `sanook mcp list --tools`: grouped tools by server.
+- `sanook mcp remove` should support exact server names and show config path.
+- Support `--project` install only if project is trusted.
+- Add auth hints when hosted remotes return `401 Unauthorized`.
+- Add registry result caching and risk labels for write-capable servers.
+
+## Safety Policy
+
+- Default to read-only where a server offers read-only or scoped modes.
+- Show risk class before enabling:
+  - read-only
+  - file-write
+  - network-write
+  - database-write
+  - infra/admin
+- Dangerous servers must remain subject to existing approval gates in ask mode.
+- Do not run package installs implicitly during `search` or `info`.
+- For package metadata with `fileSha256`, verify downloaded MCPB packages before running.
+
+## First Presets
+
+| Preset | Servers to consider | Use case |
+|---|---|---|
+| `dev` | GitHub/GitLab, Sentry, Context7/docs | coding, PRs, releases, error debugging |
+| `research` | fetch, Brave/web search, docs, Obsidian/GDrive | grounded external research |
+| `pm` | Linear/Jira, Slack/Discord, Notion | task and team workflows |
+| `ops` | Postgres read-only, Docker/Kubernetes, Sentry | operational debugging |
+
+up:: [[Shared/Tech-Standards/_Index]]