sanook-cli 0.5.0 → 0.5.2

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]]

package/second-brain/Research/2026-06-18-hermes-cli-second-brain-expansion-research.md

@@ -0,0 +1,160 @@
+---
+tags: [research, second-brain, hermes, ai-agent, context-engineering]
+note_type: research-note
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source::
+  - https://github.com/NousResearch/hermes-agent
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/memory
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
+  - https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
+  - https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+  - https://docs.langchain.com/oss/python/concepts/memory
+  - https://arxiv.org/abs/2304.03442
+  - https://arxiv.org/abs/2310.08560
+  - https://arxiv.org/abs/2303.11366
+  - https://arxiv.org/abs/2210.03629
+  - https://fortelabs.com/blog/para/
+related:: [[Runbooks/ai-second-brain-operating-sequence]]
+related:: [[Shared/AI-Context-Index]]
+related:: [[Evals/second-brain-benchmarks]]
+---
+
+# Hermes CLI Second-Brain Expansion Research
+
+> Research note for deciding what to add to this second-brain so Hermes CLI can use it better. Created after comparing the current vault structure with Hermes Agent docs, agent memory research, context-engineering guidance, eval patterns, and PARA-style knowledge management. This note becomes stale when Hermes context/memory/skills semantics change materially.
+
+## Bottom Line
+
+Scope correction on 2026-06-18: this note is reference material for Hermes compatibility only. If the objective is Sanook CLI itself, use [[Projects/sanook-cli/second-brain-feature-roadmap]] instead.
+
+อย่าเพิ่ม root-level folder เยอะตอนนี้. โครงสร้างปัจจุบันมี knowledge pipeline, memory, context packs, evals, coordination, and runbooks ครบกว่าค่าเฉลี่ยแล้ว.
+
+สิ่งที่ควรเพิ่มถัดไปคือชั้นที่ทำให้ Hermes ใช้ของที่มีอยู่ได้แม่นขึ้น:
+
+1. `HERMES.md` หรือ `.hermes.md` adapter สำหรับ Hermes CLI โดยเฉพาะ.
+2. `Shared/Hermes/` หรืออย่างน้อย `Shared/Agent-Adapters/hermes.md` สำหรับ config, memory sync, toolset, and curator policy.
+3. `Evals/Benchmarks/` สำหรับ benchmark cases แยกเป็นไฟล์เล็กๆ แทนการโตในไฟล์เดียว.
+4. `Acceptance/Golden-Cases/` สำหรับ input -> expected output ของ Hermes workflows.
+5. `Reviews/Vault-Health/` สำหรับ scheduled curator-style review ของ vault/context/skills.
+
+## Evidence From Hermes
+
+Hermes context files:
+
+- Hermes supports `.hermes.md` / `HERMES.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `.cursorrules`, and Cursor rule modules.
+- Priority is first-match: `.hermes.md` -> `AGENTS.md` -> `CLAUDE.md` -> `.cursorrules`; `SOUL.md` is separate global identity.
+- Hermes loads one project context type per session, then progressively discovers subdirectory context files as tools touch paths.
+- Context files are security scanned, truncated, and should stay concise with headers, examples, negative constraints, key paths, and stale-context hygiene.
+
+Implication for this vault:
+
+- Current `AGENTS.md` works as fallback, but Hermes-only usage should prefer a dedicated `HERMES.md` / `.hermes.md` so Hermes does not inherit adapter compromises meant for other agents.
+- Because Hermes progressively discovers subdirectory files, scoped context files can be more useful than one giant root instruction file.
+
+Hermes memory:
+
+- Built-in memory is deliberately tiny: `MEMORY.md` for agent notes and `USER.md` for user profile, both loaded once as a frozen snapshot at session start.
+- Hermes explicitly separates always-on memory from on-demand session search.
+- Memory writes can be gated with approval, and memory entries should be compact, specific, and non-duplicative.
+
+Implication for this vault:
+
+- Keep Hermes memory small and use the vault as the long-term source of truth.
+- Add a Hermes memory sync policy: what goes to `~/.hermes/memories/MEMORY.md`, what stays in `Shared/User-Memory`, what is retrieved on demand from vault search/session logs.
+
+Hermes skills:
+
+- Skills are on-demand knowledge documents with progressive disclosure.
+- `SKILL.md` supports references, templates, scripts, assets, platform restrictions, required environment variables, and verification sections.
+- Hermes can scan external skill directories, but writable external dirs are not a write-protection boundary.
+
+Implication for this vault:
+
+- Current `.agents/skills/` can become a shared skill source, but it needs an explicit policy for which skills are read-only, owner-authored, or agent-created.
+- Useful repeatable vault workflows should graduate into Hermes skills only after they have examples, pitfalls, and verification.
+
+Hermes curator:
+
+- The curator tracks skill usage, marks stale skills, archives long-unused skills, and can optionally run an LLM consolidation pass.
+- It has status, dry-run, backup, rollback, pin, and archive commands.
+
+Implication for this vault:
+
+- Add curator-like vault health reviews: stale context, duplicated rules, unused context packs, benchmark drift, and skills that should be archived or pinned.
+
+## Evidence From Agent Research
+
+Context engineering:
+
+- Anthropic frames context as finite and context engineering as the task of curating all tokens available to an agent across long-running loops, not just writing better prompts.
+- This supports the current Scientific Loop Sequence and argues for smaller, task-specific retrieval bundles rather than a larger global instruction file.
+
+Memory taxonomy:
+
+- LangGraph separates short-term thread-scoped memory from long-term memory across conversations, and uses semantic, episodic, and procedural memory categories.
+- Generative Agents stores experiences, synthesizes reflections, and retrieves memories dynamically for planning.
+- MemGPT argues for tiered memory and movement between fast context and slower external memory.
+- Reflexion stores reflective text in episodic memory after feedback to improve future trials.
+- ReAct shows the value of interleaving reasoning/action with external information retrieval.
+
+Implication for this vault:
+
+- Current folders already map well:
+  - semantic memory -> `Learning/`, `Distillations/`, `Entities/`, `Shared/Core-Facts/`
+  - episodic memory -> `Sessions/`, `Retrospectives/`, `Traces/`
+  - procedural memory -> `Runbooks/`, `Playbooks/`, `Skills/`, `.agents/skills/`
+  - eval/reflection memory -> `Evals/`, `Acceptance/`, `Reviews/`
+- The missing piece is not another generic "Resources" folder. It is sharper eval cases, Hermes adapter policy, and scheduled consolidation.
+
+PKM / PARA:
+
+- PARA's Projects / Areas / Resources / Archives split supports action-oriented retrieval.
+- This vault already extends PARA with AI-specific layers: Evals, Acceptance, Rules, Context-Packs, Provenance, Coordination.
+
+Implication for this vault:
+
+- Avoid adding broad folders like `Resources/`, `Notes/`, or `AI/`; they would overlap existing canonical homes.
+
+## Gap Analysis
+
+| Gap | Current coverage | Recommended addition | Priority |
+|---|---|---|---|
+| Hermes-specific project context | `AGENTS.md` only | `HERMES.md` or `.hermes.md` pointing to hot path and Hermes-only rules | P0 |
+| Hermes memory policy | `Shared/User-Memory`, `Shared/Memory-Inbox`, `USER.md` | `Shared/Hermes/memory-sync-policy.md` or `Shared/Agent-Adapters/hermes-memory.md` | P0 |
+| Hermes skill lifecycle | `.agents/skills`, `Skills/`, `Shared/Rules/skills-admission` | `Shared/Hermes/skill-lifecycle.md` plus first Hermes skill for second-brain maintenance | P1 |
+| Atomic benchmarks | `Evals/second-brain-benchmarks.md` | `Evals/Benchmarks/<case-id>.md` | P1 |
+| Golden fixtures | `Acceptance/golden-case-template.md` | `Acceptance/Golden-Cases/<workflow>.md` | P1 |
+| Scheduled vault health | `Reviews/`, `Runbooks/sleep-time-consolidation.md` | `Reviews/Vault-Health/YYYY-MM-DD.md` | P1 |
+| Prompt-injection trust boundary | `Intake/_Quarantine`, `ingest-quarantine`, Hermes scanner | `Shared/Security/trust-boundaries.md` only if rules grow beyond current files | P2 |
+| Tool inventory and MCP capabilities | `Tools/`, `Shared/mcp-servers`, `Tech-Standards` | `Shared/Hermes/toolsets.md` if Hermes profiles/toolsets become important | P2 |
+| Output artifacts per project | `Projects/<proj>/` role allows deliverables | Add `Projects/<proj>/Artifacts/` only inside active projects with many generated files | P2 |
+
+## Recommended Next Build
+
+Best next bundle:
+
+1. Add `second-brain/HERMES.md`.
+2. Add `second-brain/Shared/Hermes/_Index.md`.
+3. Add `second-brain/Shared/Hermes/memory-sync-policy.md`.
+4. Add `second-brain/Shared/Hermes/skill-lifecycle.md`.
+5. Add `second-brain/Shared/Context-Packs/hermes-cli-vault-maintenance.md`.
+6. Split 3-5 high-value cases from `Evals/second-brain-benchmarks.md` into `Evals/Benchmarks/`.
+
+Implementation caution:
+
+- If adding new folders, update [[Vault Structure Map]] and any folder scaffold source such as `src/brain.ts`.
+- If adding only files under existing folders, keep the current taxonomy stable.
+- Do not mirror Hermes `~/.hermes/` wholesale into the vault; keep local runtime state in Hermes home and store only policy, reviewed snapshots, and durable decisions here.
+
+## Do Not Add Yet
+
+- `Resources/` root folder: overlaps `Research/`, `Learning/`, and `Distillations/`.
+- `Notes/` root folder: becomes a junk drawer and weakens routing.
+- `AI/` root folder: duplicates `Shared/AI-Context-Index`, agent adapters, rules, and context packs.
+- `Archive/` root folder: `Shared/Archive/` already exists.
+- `Experiments/` root folder: use `Research/`, `Evals/`, or `Sessions/` depending on artifact type.
+
+up:: [[Research/_Index]]

package/second-brain/Research/2026-06-18-sanook-mcp-ecosystem-and-ux-roadmap.md

@@ -0,0 +1,181 @@
+---
+tags: [research, mcp, sanook-cli, integration, roadmap]
+note_type: research
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source:
+  - https://registry.modelcontextprotocol.io/openapi.json
+  - https://registry.modelcontextprotocol.io/v0/servers
+  - https://registry.modelcontextprotocol.io/v0/version
+  - https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
+  - https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+related:
+  - "[[Shared/Tech-Standards/mcp-integration-roadmap]]"
+---
+
+# 2026-06-18 - Sanook MCP Ecosystem and UX Roadmap
+
+> Research snapshot for how Sanook CLI currently handles MCP, what the official MCP registry exposes, and which integrations would make Sanook easier to use.
+
+## Current Sanook MCP State
+
+Sanook already has a strong MCP foundation:
+
+- MCP client: `src/mcp.ts`
+  - Loads global `~/.sanook/mcp.json`.
+  - Loads project `.sanook/mcp.json` only after project trust.
+  - Supports stdio via `command` + `args`.
+  - Supports remote Streamable HTTP via `url` + `headers`.
+  - Sanitizes server names.
+  - Sends minimal safe env to child MCP servers and only passes explicit `cfg.env`.
+  - Caps MCP tool output.
+  - Merges MCP tools into the main agent as `<server>__<tool>`.
+- MCP server: `src/mcp-server.ts`
+  - `sanook mcp serve` exposes `sanook_search`, `sanook_recall`, `sanook_remember`, `sanook_index`, and `sanook_stats`.
+  - Uses stdio JSON-RPC and keeps stdout protocol-clean.
+- CLI management: `src/bin.ts`
+  - `sanook mcp add <name> <command> [args...]`
+  - `sanook mcp add <name> https://host/mcp`
+  - `sanook mcp list`
+  - `sanook mcp remove <name>`
+
+Main gap: Sanook can run MCP servers, but users still need to know the exact package, args, secrets, and safe configuration shape themselves.
+
+## Registry Findings
+
+The official registry API is available and healthy:
+
+- `GET /v0/version` returned registry `1.7.9`, build time `2026-05-12T21:05:57Z`.
+- `GET /v0/health` returned `status: ok`.
+- OpenAPI exposes list/get/validate/publish/status endpoints under `/v0` and `/v0.1`.
+- Server entries include:
+  - `server.name`, `description`, `version`, `repository`, `websiteUrl`
+  - `remotes` with `type: streamable-http` or `sse`
+  - `packages` with `registryType`, `identifier`, `version`, `runtimeHint`, `transport`
+  - `environmentVariables`, `headers`, `packageArguments`, `runtimeArguments`
+  - `isRequired`, `isSecret`, `format`, `placeholder`, and default values for setup UX
+  - metadata such as `isLatest`
+
+This means Sanook can build a first-class MCP installer without hardcoding every server.
+
+## High-Value MCP Categories for Sanook
+
+| Category | Examples seen in registry | Why it matters for Sanook |
+|---|---|---|
+| Code hosting | GitLab official remote, GitHub variants | PRs/issues/releases/repo operations. |
+| Local/cloud files | Filesystem variants, remote GCS filesystem | Safer file access outside the workspace, cloud artifacts. |
+| Databases | Postgres, SQLite | Data inspection for app/debug workflows; should default read-only. |
+| Project management | Linear, Jira | Turn user tasks into issue-backed work loops. |
+| Observability | Sentry | Debug production errors from real issue/event context. |
+| Browser/web | Playwright, Browserbase, fetch, Brave/web search | JS-rendered pages, docs extraction, web research. |
+| Team/chat | Slack, Discord | Team context and delivery/notification workflows. |
+| Knowledge/workspace | Notion, Gmail, Google Drive, Obsidian | Import user knowledge into second-brain workflows. |
+| Docs/versioned knowledge | Context7-like docs servers | Better library/API grounding without broad web search. |
+| Infrastructure | Docker, Kubernetes variants | Ops/debug workflows, but needs strict approval gates. |
+
+## Recommended Sanook UX Improvements
+
+### P0: Discover / Install / Test
+
+Add registry-backed commands:
+
+```text
+sanook mcp search <query>
+sanook mcp info <server-name>
+sanook mcp install <server-name> [--name alias]
+sanook mcp test [name]
+```
+
+Expected behavior:
+
+- `search` calls the official registry, filters latest versions, and shows transport/package choices.
+- `info` shows description, repo, remotes/packages, required env/header secrets, and risk class.
+- `install` converts registry metadata to `~/.sanook/mcp.json`.
+- `test` initializes the server and lists tools without starting an agent turn.
+
+### P1: Setup Wizard from Registry Metadata
+
+Use `environmentVariables` and `headers`:
+
+- prompt for required secrets without echoing them
+- support `--env KEY=value` and `--header KEY=value`
+- store secrets explicitly only in `~/.sanook/mcp.json`, not inherited process env
+- show a redacted preview before write
+
+### P1: Safer Capability Review
+
+After install/test, print:
+
+- transport: stdio / remote HTTP
+- package runtime: `npx`, `uvx`, Docker, remote
+- number of tools
+- tool names
+- risk class:
+  - read-only
+  - file-write
+  - network-write
+  - database-write
+  - infra/admin
+
+Then let users enable dangerous servers intentionally.
+
+### P2: Preset Packs
+
+Sanook can ship curated packs:
+
+```text
+sanook mcp preset dev
+sanook mcp preset research
+sanook mcp preset pm
+sanook mcp preset ops
+```
+
+Suggested presets:
+
+- `dev`: GitHub/GitLab, filesystem, Sentry, Context7/docs
+- `research`: fetch, Brave/web search, docs, Obsidian/GDrive
+- `pm`: Linear/Jira, Slack, Notion
+- `ops`: Postgres read-only, Docker/Kubernetes, Sentry
+
+### P2: Tool Discovery in the REPL
+
+Improve `/tools`:
+
+- group MCP tools by server
+- show disabled/unreachable servers
+- show how to fix missing env/headers
+- show source config path: global vs project
+
+## Implementation Notes
+
+Good fit for Sanook's existing code:
+
+- Add a new module `src/mcp-registry.ts`.
+- Keep registry parsing pure/testable.
+- Do not install from arbitrary registry package metadata without showing command/env first.
+- Prefer remote Streamable HTTP when no local runtime is required.
+- Prefer read-only database servers by default.
+- Keep project `.sanook/mcp.json` behind trust, as today.
+- Add tests with mocked fetch and fake MCP servers.
+
+## Suggested First Integrations
+
+For this repo and owner's likely workflows:
+
+1. GitLab official remote or GitHub MCP variant: repo/issues/PRs/releases.
+2. Sentry: production debugging and release verification.
+3. Linear/Jira: task loop integration if issue tracker is used.
+4. Postgres read-only: app data inspection.
+5. Context7/docs + fetch/search: better grounded research.
+6. Slack/Discord: team/message workflows.
+7. Google Drive/Gmail/Notion/Obsidian: knowledge intake into second-brain.
+
+## Open Questions
+
+- Should Sanook store MCP secrets directly in `mcp.json`, or add a redacted secret store under `~/.sanook/secrets.json`?
+- Should `sanook mcp install` default to global only, with `--project` requiring trust?
+- Should remote OAuth flows be supported directly, or should Sanook only accept bearer tokens/headers first?
+- Should dangerous MCP tool groups be disabled until the user runs `sanook mcp enable <name> --write`?
+
+up:: [[Research/_Index]]

package/second-brain/Research/_Index.md

@@ -25,6 +25,11 @@ parent: "[[Home]]"
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Research Notes
+
+- [[Research/2026-06-17-ai-second-brain-method-experiment]] — ทดลองเปรียบเทียบวิธีใช้ second-brain ร่วมกับ AI และเลือก Scientific Loop Sequence
+- [[Research/2026-06-18-hermes-cli-second-brain-expansion-research]] — research ว่าควรเพิ่มอะไรใน second-brain เพื่อให้ Hermes CLI ใช้ vault ได้ดีขึ้น
+- [[Research/2026-06-18-sanook-mcp-ecosystem-and-ux-roadmap]] — MCP ecosystem scan + Sanook CLI registry/install/test roadmap
+- [[Research/2026-06-18-ai-token-reduction-frameworks]] — compare LLMLingua, Selective Context, and Headroom for Sanook token reduction
 
 up:: [[Home]]

package/second-brain/Reviews/2026-06-18-auto-improve-maintenance.md

@@ -0,0 +1,54 @@
+---
+tags: [review, maintenance, auto-improve]
+note_type: review
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Reviews/_Index]]"
+---
+
+# Auto Improve Maintenance - 2026-06-18
+
+> Purpose: Record the local recurring maintenance run, the small improvement chosen, and verification status for future agents.
+
+## Scope
+
+Recurring local maintenance run for `sanook-cli`.
+
+## Current State
+
+- Existing uncommitted changes already included a `serve --port` missing-value UX fix in `src/cli-args.ts`, search split-option hardening, matching tests, changelog text, and release-readiness notes.
+- Full test baseline passed before this follow-up work.
+- This run consolidated duplicated inline/split CLI option-value handling into `src/cli-option-values.ts`, shared by `parseArgs`, `parseServeArgs`, and `parseSearchArgs`.
+- Parser behavior is intended to stay unchanged by the consolidation; existing focused parser tests cover the touched surfaces.
+- This recurring follow-up added a spawned CLI regression test for `sanook gateway setup ntfy`, covering required split-option missing values and preserving single-dash secret values like `--token -tk_secret`.
+
+## Verification
+
+- `npm test` before new edits - 94 files, 810 tests passed.
+- `npm test -- src/search/cli.test.ts` - 1 file, 10 tests passed.
+- `npm run typecheck` - passed.
+- One chained full-suite attempt hit sandbox loopback `EPERM` while another listen probe was running; `npm test -- src/integration.test.ts` passed on rerun.
+- `npm test` after new edits - 94 files, 811 tests passed.
+- `npm run build` - passed.
+- Follow-up baseline `npm test` - 94 files, 811 tests passed.
+- `npm test -- src/cli-args.test.ts src/search/cli.test.ts` - 2 files, 30 tests passed.
+- Follow-up `npm run typecheck` - passed.
+- Follow-up `npm test` after consolidation - 94 files, 811 tests passed.
+- Follow-up `npm run build` - passed.
+- Recurring maintenance baseline `npm test` - 95 files, 814 tests passed.
+- `npm test -- src/gateway-setup-cli.test.ts` - 1 file, 2 tests passed.
+- `npm run typecheck` - passed.
+- Follow-up `npm test` after gateway setup CLI regression coverage - 96 files, 816 tests passed.
+- `npm run build` - passed.
+
+## Follow-up Audit
+
+- Reviewed the remaining direct next-argument readers in `src/tools/permission.ts` and `src/bin.ts`.
+- No safe behavior change was made this pass: the `permission.ts` readers intentionally model shell/git option semantics where a following token that begins with `-` can still be the consumed value, and the gateway setup helpers in `bin.ts` may receive secret/token values that begin with `-`.
+- Avoid broad conversion to the shared CLI option helper unless the target command surface has tests proving flag-like values should be rejected.
+
+## Next Candidate
+
+Consider extracting a small gateway setup option parser only if more setup command regressions appear; for now the spawned CLI regression coverage protects the known brittle edge without broad parser churn.
+
+up:: [[Reviews/_Index]]

package/second-brain/Reviews/_Index.md

@@ -25,6 +25,6 @@ reflection รายงาน (→Retrospectives)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+- [[Reviews/2026-06-18-auto-improve-maintenance]] — recurring local maintenance baseline and next candidate
 
 up:: [[Home]]

package/second-brain/Runbooks/_Index.md

@@ -25,6 +25,11 @@ runnable unit (→Skills)
 
 > รายละเอียดทุกโฟลเดอร์ + decision rules → [[Vault Structure Map]]
 
-_(ยังว่าง — โน้ตในโฟลเดอร์นี้จะถูกลิงก์ที่นี่)_
+## Runbooks
+
+- [[Runbooks/ai-second-brain-operating-sequence]] — default sequence สำหรับ AI ทำงานกับ vault จากผลทดลอง 2026-06-17
+- [[Runbooks/eval-loop]] — quality loop หลังงานไม่ trivial
+- [[Runbooks/ingest-quarantine]] — gate สำหรับข้อมูลภายนอก/untrusted content
+- [[Runbooks/sleep-time-consolidation]] — consolidate memory เป็นรอบ
 
 up:: [[Home]]