sanook-cli 0.5.1 → 0.5.5

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-hermes-tui-parity-map.md

@@ -0,0 +1,129 @@
+---
+tags: [research, cli, tui, hermes, sanook]
+note_type: research
+created: 2026-06-18
+updated: 2026-06-18
+parent: "[[Research/_Index]]"
+source:
+  - https://github.com/nousresearch/hermes-agent
+  - https://github.com/nousresearch/hermes-agent/tree/main/ui-tui/src
+  - https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/components/branding.tsx
+  - https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/components/appChrome.tsx
+  - https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/components/appOverlays.tsx
+  - https://github.com/nousresearch/hermes-agent/blob/main/ui-tui/src/components/textInput.tsx
+  - https://github.com/nousresearch/hermes-agent/blob/main/LICENSE
+  - https://clig.dev/
+  - https://github.com/google-gemini/gemini-cli
+  - https://github.com/openai/codex
+  - https://github.com/Aider-AI/aider
+---
+
+# Hermes TUI Parity Map for Sanook
+
+> Map Hermes Agent TUI features against Sanook's current UI so future port/rebrand work can be prioritized without losing source/license context.
+
+Source inspected: `nousresearch/hermes-agent` at commit `646cd1b`, then rechecked against GitHub HEAD `c37fdec` (`feat(dashboard): surface full per-MCP catalog detail; fix pip-install doc`) and latest HEAD `2fa16ec` (`Merge pull request #48529 from kshitijk4poor/salvage-48372-eap`) on 2026-06-18. License is MIT; direct code copies require preserving the Nous Research copyright/license notice.
+
+## Answer
+
+ยังไม่ได้เอา Hermes TUI มาทั้งหมด. Sanook ตอนนี้เอาแนวคิด startup banner/status launchpad, startup service routes panel, slash/path completion float box, compact/expanded transcript tool trail controls, Hermes-style `/details` สำหรับ thinking/tools sections, streaming markdown renderer แบบ stable-prefix/tail, grapheme-safe prompt cursor/backspace, Hermes-style long paste collapse, `/copy` clipboard/OSC52 bridge, และ floating overlay path สำหรับ `/help` pager, `/hotkeys`, `/tools` hub, `/model` picker, `/mcp` hub พร้อม lazy server test + per-server tool catalog browsing, `/skills` hub, กับ `/sessions` switcher ที่ inspect/resume/delete-confirm ได้มาแล้ว แต่ Hermes TUI เป็นระบบใหญ่กว่า banner มาก: มี custom Ink runtime, gateway RPC, fullscreen alternate screen, virtual transcript, overlays, model/session/skills/plugins hubs, terminal selection/copy-on-select, mouse wheel acceleration, richer collapsible reasoning/tool trail, todo panel, richer markdown/math/table rendering, voice hooks, and skin/theme live repaint.
+
+## Outside CLI Notes
+
+- CLIG.dev emphasizes human-first design, "just enough" output, discoverability, and conversational feedback. Sanook should make the first screen explain useful next actions without becoming scrollback noise.
+- Gemini CLI presents a clear screenshot-led identity and foregrounds built-in tools, MCP extensibility, terminal-first use, checkpointing, and project context files.
+- OpenAI Codex uses a strong splash image plus a direct local-agent promise and very short quickstart path.
+- Aider differentiates less through TUI chrome and more through workflow promises: repo map, git integration, lint/test loops, voice, image/web context, and copy/paste handoff.
+- Sanook's best brand gap is therefore not a bigger logo; it is a memorable terminal service map: Code, Brain, Connect, Ship.
+
+## Hermes TUI Inventory
+
+- Runtime shell: `entry.tsx`, `app.tsx`, `app/useMainApp.ts`, `gatewayClient.ts`.
+- Layout/chrome: `components/appLayout.tsx`, `components/appChrome.tsx`, `components/branding.tsx`.
+- Banner/session intro: responsive ASCII logo, compact fallback, session panel, caduceus hero, collapsible Tools/Skills/MCP/System sections.
+- Status rule: busy indicator styles, elapsed time, model, context meter, cost/duration/background task/voice/compression segments, cwd/branch truncation.
+- Transcript: virtual history, sticky scroll, transcript scrollbar, message grouping, role gutter, long system collapse.
+- Streaming: incremental markdown, reasoning/tool trail grouping, pending tools, live todo panel.
+- Composer: custom text input, grapheme-safe cursor movement, multiline navigation, paste collapse, path/image drop detection, queue editing.
+- Completions: slash completion and path completion float box.
+- Overlays: approval, confirm, clarify, sudo password, secret prompt, pager, model picker, active session switcher, skills hub, plugins hub, agents overlay, FPS/perf overlays.
+- Terminal integration: alternate screen, bracketed paste, mouse tracking, copy-on-select, OSC52 clipboard, terminal parity hints, Termux mode.
+- Domain/libs: block layout, providers, usage, viewport, emoji/math unicode/syntax/text sanitization, memory monitor, subagent tree.
+- Tests: broad UI regression suite for status rules, input cursor drift, terminal modes, overlays, markdown, virtual scroll, queue, theme, clipboard, and slash parity.
+
+## Sanook Current Parity
+
+- Done: big `SANOOK AI` wordmark and launchpad in `src/ui/banner.tsx`.
+- Done: responsive banner tiers inspired by Hermes: wide wordmark, compact panel, tiny text-only panel.
+- Done: startup service routes panel with Code, Brain, Connect, Ship, System, and Runtime lanes in `src/ui/session-panel.tsx`.
+- Done: `/hotkeys` command adapted from Hermes hotkey discovery.
+- Done: `/help` pager overlay in `src/ui/overlay.tsx`; supports line/page navigation, top/bottom jumps, and close on `Esc/q`.
+- Done: slash-command and path completion float box in `src/ui/overlay.tsx` + `src/slash-completion.ts`; supports prefix filtering, `@file`/relative/home/absolute path tokens, row navigation, and Tab/Enter-to-complete before submit.
+- Done: `/mcp` MCP Hub overlay in `src/ui/overlay.tsx` + `src/mcp-hub.ts`; maps Hermes plugins hub/dashboard catalog idea to Sanook's extension model by listing configured MCP servers, transport, target, secret summary, lazy selected-server testing with `t` for PASS/FAIL, and per-server advertised tool catalog browsing with ↑/↓ or j/k.
+- Done: floating `/hotkeys` overlay foundation in `src/ui/overlay.tsx`; closes with `Esc`, `Enter`, or `q`.
+- Done: `/tools` Tools Hub overlay in `src/ui/overlay.tsx` + `src/tool-catalog.ts`; lists built-in file/git/memory/schedule/sub-agent/diagnostics lanes and supports Enter-to-inspect details instead of dumping a long text block into scrollback.
+- Done: `/model` picker overlay in `src/ui/overlay.tsx` using Sanook provider registry; supports ↑/↓ or j/k and Enter-to-switch.
+- Done: `/skills` read-only Skills Hub overlay in `src/ui/overlay.tsx` using Sanook's bundled/global/project skill loader; supports list navigation and inspect view.
+- Done: `/sessions` Session Switcher overlay in `src/ui/overlay.tsx` using Sanook's saved session store; supports list navigation, Enter-to-resume for current-project sessions, `i` detail inspect, and two-press `d` delete confirmation.
+- Done: bounded queued-message window inspired by Hermes `QueuedMessages`, with active row selection and `Ctrl+X` deletion while busy.
+- Done: Hermes-like Sanook status rule in `src/ui/status.ts` + cached git branch lookup in `src/ui/useGitBranch.ts` + busy elapsed timer in `src/ui/useBusyElapsed.ts`; prioritizes state/model/mode/context/queue, sheds lower-priority hints on narrow terminals, shows elapsed/context-compression/cost/cwd/branch when space allows, and makes cwd/branch yield before wrapping.
+- Done: compact/expanded transcript tool trail controls in `src/ui/tool-trail.ts` + `src/ui/app.tsx`; `tool-call` events render as running rows, `tool-result` events mark rows done, errors mark the latest running tool, completed trails are snapshotted into the assistant turn, `/trail [compact|expanded]` and `Ctrl+T` rerender saved transcript trails, and assistant streaming text no longer gets polluted by raw tool-call markers.
+- Done: `/details thinking hidden|collapsed|expanded` and `/details tools hidden|collapsed|expanded` in `src/commands.ts` + `src/ui/thinking-panel.ts` + `src/ui/app.tsx`; maps Hermes section visibility to Sanook's capped reasoning panel and tool trail visibility.
+- Done: streaming/saved assistant markdown rendering in `src/ui/markdown.tsx` + `src/ui/app.tsx`; supports headings, quotes, lists, fenced code, inline code, bold, and a Hermes-inspired stable-prefix/unstable-tail split outside code fences.
+- Done: grapheme-safe prompt cursor/backspace in `src/ui/useEditor.ts`; left/right/delete move across Thai combining marks, emoji, and ZWJ emoji as whole grapheme clusters.
+- Done: Hermes-style long paste collapse in `src/ui/useEditor.ts` + `src/ui/app.tsx`; bracketed/multiline paste normalizes newlines, collapses long payloads into readable `[[ paste ... ]]` tokens, and expands those snippets before submit so the model receives full text.
+- Done: `/copy [last]` clipboard bridge in `src/clipboard.ts` + `src/ui/app.tsx`; copies the latest assistant response via native system clipboard tools and falls back to OSC52 terminal clipboard sequences.
+- Done: REPL banner only renders before conversation history exists, preserving scrollback.
+- Done: simple approval prompt, prompt history, slash commands, `@file` mention expansion, model footer.
+- Missing: fullscreen alternate screen and virtual transcript.
+- Missing: richer plugin/MCP actions such as enable/disable and install from registry inside the TUI, schema-level tool detail panes, plus remaining session actions such as rename/cross-project switch/live session state.
+- Missing: richer background-task and voice segments in the status rule.
+- Missing: remaining full custom TextInput/terminal parity: visual wrap cursor layout, image/path drop detection, mouse selection, and copy-on-select.
+- Missing: collapsible/interactive startup session sections for tools/skills/MCP/system.
+- Missing: richer grouped reasoning trail, live todo panel parity, and full markdown/math/table/media parity.
+- Missing: live theme/skin engine with user-defined banner art/colors.
+
+## Port Plan
+
+P0 completed:
+- Responsive SANOOK AI Launchpad in `src/ui/banner.tsx`.
+
+P1 next, low-risk/high-value:
+- Upgrade startup service panel into collapsible/interactive sections using Sanook's Tools Hub, skill loader, and MCP config.
+- Expand the new floating overlay foundation into richer tools/MCP/plugin actions, richer skill actions, and richer session actions.
+- Expand status with background-task/voice/compression segments.
+
+P2 completed:
+- Paged `/help` overlay using Sanook command help text.
+- Tools Hub overlay using Sanook built-in tool catalog.
+- Model picker overlay using Sanook provider registry.
+- Session switcher overlay using Sanook saved sessions.
+- Skills hub overlay using Sanook skill list/read surfaces.
+- Compact/expanded transcript tool trail controls for `tool-call`/`tool-result`/`error` agent events.
+- `/details thinking/tools hidden|collapsed|expanded` section controls with a capped thinking panel and hidden/compact/expanded tool trail.
+- Streaming markdown renderer for live assistant output and saved assistant turns.
+- Grapheme-safe prompt cursor/backspace for Thai combining marks, emoji, and ZWJ emoji.
+- Long paste collapse with snippet expansion before submit.
+- `/copy [last]` clipboard bridge with native clipboard + OSC52 fallback.
+
+P2 next:
+- Add richer skill actions once Sanook has stable install/remove/open/edit surfaces.
+- Add remaining richer session actions: rename/title edit, cross-project switch, and live-session metadata.
+- Custom command completion and richer path edge cases (quoted paths, hidden files toggle, Windows drive polish).
+
+P3 larger:
+- Virtual transcript/scrollbar/sticky prompt.
+- Full rich message rendering with markdown math/tables/media, richer grouped reasoning trail, and todo panel.
+- Finish remaining custom text input/terminal parity: visual wrap cursor layout, image/path drop detection, mouse selection, and copy-on-select.
+
+P4 only if needed:
+- Gateway-style RPC split between UI and backend. Sanook currently runs the agent in-process; copying Hermes' RPC architecture wholesale would be a larger framework change.
+
+## Rebrand Rules
+
+- Replace Hermes Agent -> SANOOK AI / Sanook.
+- Replace Hermes mythological copy -> Sanook service promise: `plan -> patch -> prove -> remember`, `readable · recoverable · remembered`.
+- Keep Sanook differentiators prominent: BYOK, local-first, second brain, MCP workflows, Thai-friendly copy.
+- Avoid copying Hermes Python backend assumptions unless Sanook has the equivalent feature.
+
+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/2026-06-19-hermes-python-architecture-for-sanook.md

@@ -0,0 +1,49 @@
+---
+tags: [research, hermes, sanook, cli, prompt-budget]
+note_type: research
+created: 2026-06-19
+updated: 2026-06-19
+parent: "[[Research/_Index]]"
+source:
+  - https://github.com/nousresearch/hermes-agent
+  - https://github.com/nousresearch/hermes-agent/blob/main/hermes_cli/prompt_size.py
+  - https://github.com/nousresearch/hermes-agent/blob/main/hermes_cli/subcommands/prompt_size.py
+  - https://github.com/nousresearch/hermes-agent/blob/main/pyproject.toml
+---
+
+# Hermes Python Architecture for Sanook
+
+> Research note for converting useful Hermes Agent backend ideas into Sanook-native TypeScript features without copying Hermes runtime assumptions wholesale.
+
+Source inspected: local clone of `nousresearch/hermes-agent` fetched on 2026-06-19, latest `origin/main` commit `0fa7d6f6609c515b6eaafda0594a1472d11d93b5` (`fix(desktop): never persist or restore a named custom provider as bare "custom" (#48547)`).
+
+## Finding
+
+Hermes' Python layer is a full backend, not a small helper. It covers agent runtime, provider and gateway adapters, CLI subcommands, tools, MCP/plugin/LSP/browser support, schedulers, memory, voice/transcription, dashboards, and tests. Sanook should not port that Python runtime directly because Sanook's core loop is already TypeScript and Vercel AI SDK based.
+
+The most useful near-term Sanook adaptation is Hermes' `prompt-size` idea: an offline diagnostic that shows fixed prompt/context/tool-schema weight before the user calls a model. This directly supports Sanook's differentiator: second-brain plus skills plus MCP, all of which can quietly grow context cost.
+
+## Sanook Adaptation
+
+- Add `sanook prompt-size [--json]`.
+- Count the same prompt blocks Sanook injects at runtime: base system, personality overlay, auto-memory, skills index, second-brain context, project memory, repo map, and git context.
+- Count built-in tool schemas separately.
+- Do not spawn MCP servers in this command. Live MCP catalogs belong in `sanook mcp list --tools`.
+- Keep counts approximate because tokenizer details vary by model.
+
+## Why This Comes Before Bigger Ports
+
+- It improves user trust: Sanook can explain what it is about to send.
+- It makes optimization concrete: big skills, repo maps, and brain context become visible.
+- It is low-risk: no Python bridge, no provider dependency, no background service architecture change.
+- It fits the existing brand promise: readable, recoverable, remembered.
+
+## Follow-Up Ideas
+
+- Add `/prompt-size` or a context-meter overlay inside the REPL.
+- Add warning thresholds in `brain doctor` when brain context grows too large.
+- Add a JSON field to support dumps so users can share context-size diagnostics without secrets.
+- Later, consider Hermes-style optional dependency profiles only if Sanook starts shipping heavyweight adapters.
+
+up:: [[Research/_Index]]
+

package/second-brain/Research/2026-06-19-terminal-ui-brand-research.md

@@ -0,0 +1,52 @@
+---
+tags: [research, cli, tui, brand, sanook]
+note_type: research
+created: 2026-06-19
+updated: 2026-06-19
+parent: "[[Research/_Index]]"
+source:
+  - https://clig.dev/
+  - https://docs.anthropic.com/en/docs/claude-code/overview
+  - https://github.com/google-gemini/gemini-cli
+  - https://github.com/openai/codex
+  - https://github.com/Aider-AI/aider
+  - https://github.com/charmbracelet/bubbletea
+  - https://github.com/charmbracelet/lipgloss
+---
+
+# Terminal UI Brand Research
+
+> Purpose: Capture outside CLI/TUI brand references and translate them into Sanook-specific startup banner and service-route decisions.
+
+## Notes
+
+- CLIG.dev: good CLIs are human-first, say just enough, and make useful next actions discoverable. For Sanook, the banner should be a launch surface, not decoration.
+- Gemini CLI: the README leads with a screenshot and immediately frames benefits around built-in tools, MCP, terminal-first use, checkpointing, and project context.
+- Codex CLI: the README uses a strong splash image and a short local-agent promise before the quickstart.
+- Aider: the brand is workflow-first: repo map, git integration, lint/test loop, voice, images/web pages, and copy/paste handoff.
+- Claude Code: the official docs position the product as an agentic terminal coding tool and emphasize project context, workflow commands, and safe collaboration inside the terminal.
+- Charmbracelet/Bubble Tea/Lip Gloss: modern terminal apps can feel branded and polished without becoming noisy if the UI has strong layout, concise states, and terminal-native styling.
+
+## Sanook Direction
+
+Sanook should own a "service routes" identity:
+
+- Code: `@file`, tools, diff, edit/run.
+- Brain: second-brain context, remember/recall, skills, compression.
+- Connect: MCP registry, gateway serve, webhooks.
+- Ship: copy handoff, cost guard, final proof, undo safety.
+
+This is more distinctive than only changing colors because it tells users what Sanook does for them in the first five seconds.
+
+## 2026-06-19 Implementation Decision
+
+Add a "startup cockpit" layer rather than only adding more ASCII art:
+
+- Show live readiness signals: second-brain ready/missing, MCP server count, loaded skill count, and git branch.
+- Keep the existing responsive tiers: wide wordmark, medium launchpad, tiny text-only fallback.
+- Preserve the service-route identity so the banner reads as a promise of work: Code, Brain, Connect, Ship.
+- Make the tagline more Sanook-specific: "งานหนักให้เบาลง · ไม่เบาความรับผิดชอบ · local-first memory".
+
+Reason: other agent CLIs already have terminal-first branding, MCP/tooling, screenshots, or git-heavy workflows. Sanook's defensible difference is that it can make durable memory and extension readiness visible immediately.
+
+up:: [[Research/_Index]]

package/second-brain/Research/_Index.md

@@ -25,6 +25,13 @@ 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-hermes-tui-parity-map]] — inventory Hermes Agent TUI ทั้งชุด + parity/port plan สำหรับ rebrand เป็น Sanook
+- [[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
+- [[Research/2026-06-19-hermes-python-architecture-for-sanook]] — Hermes Python backend scan + Sanook-native prompt budget diagnostic choice
 
 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]]