sanook-cli 0.4.0 → 0.5.0

package/.env.example

@@ -21,3 +21,22 @@ ZHIPU_API_KEY=xxx                         # z.ai / open.bigmodel.cn (GLM — GLM
 
 # default model (alias หรือ provider:model) — เช่น sonnet | opus | gpt | grok | groq:fast
 SANOOK_MODEL=sonnet
+
+# ── Token / cost tuning (optional) ──
+# SANOOK_CACHE_TTL=1h                 # Anthropic prompt cache: 5m (default) หรือ 1h
+# SANOOK_COMPACTION=summarize         # summarize context แทน truncate เมื่อบทสนทนายาว
+# SANOOK_SUMMARY_MODEL=haiku          # model สำหรับ summarize-compaction (default = fast sibling)
+# SANOOK_SUBAGENT_MODEL=haiku         # ให้ sub-agent ใช้ model ถูกกว่า main agent
+# SANOOK_THINKING=4000                # เปิด Anthropic extended thinking พร้อม budgetTokens cap
+# SANOOK_EMBEDDING_MODEL=openai:text-embedding-3-small  # semantic/hybrid search
+# SANOOK_PRICING='{"openai:gpt-5.5":{"input":1.25,"output":10}}'  # override price table
+
+# ── Safety / privacy opt-ins ──
+# SANOOK_ALLOW_OUTSIDE_WORKSPACE=1    # ให้ file tools แตะ path นอก cwd/second-brain
+# SANOOK_NO_SANDBOX=1                 # ปิด OS sandbox ของ run_bash (Seatbelt/bubblewrap)
+# SANOOK_GATEWAY_ALLOW_WRITE=1        # ให้ sanook serve รัน write/bash แบบ unattended
+# SANOOK_HOOKS_INHERIT_ENV=1          # ส่ง env เต็มให้ hooks (default ส่งเฉพาะ safe env)
+# SANOOK_DISABLE_UPDATE_CHECK=1       # ปิด prompt เช็กอัปเดตใน TUI
+# SANOOK_DISABLE_PERSISTENCE=1        # ไม่บันทึก sessions/memory
+# SANOOK_DISABLE_WORKLOG=1            # ไม่เขียน worklog เข้า second-brain
+# SANOOK_TRUST_PROJECT=1              # trust project .sanook mcp/hooks/skills/commands ชั่วคราว

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## Unreleased
+
+### Install UX — `sanook doctor` + post-install guidance (the "`sanook` is not recognized" fix)
+
+The #1 first-run snag is `npm i sanook-cli` **without `-g`** → a local install that never lands on PATH, so typing `sanook` fails. Two root-cause fixes:
+
+- **`sanook doctor`** — a new diagnose-and-fix command. Checks Node version, the npm global-bin dir, whether the `sanook` shim is installed there, whether that dir is on PATH, and whether a local install exists in the cwd — then prints the **exact, OS-safe remedy**. On Windows it emits the *safe* user-PATH PowerShell one-liner (`[Environment]::SetEnvironmentVariable(... 'User')`), deliberately **not** `setx %PATH%` (which truncates PATH at 1024 chars and duplicates the system PATH — a known corruption footgun). Runnable as `npx sanook doctor` even before a global install.
+- **post-install hint** — right after `npm i`, the installer now prints the working command: local install → `npx sanook` or `npm i -g sanook-cli`; global install → "ready, type `sanook`". Never fails the install (always exits 0); stays quiet during repo-dev self-installs and CI.
+
+### Cross-platform hardening — Windows / macOS / Linux
+
+Audited the whole codebase (process spawning, paths, external deps, terminal) and fixed the real Windows breakers:
+
+- **Child-process spawning on Windows**: `npx`/`npm`/`codex` are `.cmd` shims, so `spawn('npx', …)` failed with ENOENT — breaking **MCP servers** (incl. the second-brain filesystem MCP), **`sanook update`**, and the **Codex provider**. Now spawned with `shell` on `win32`. (`hooks` already used a shell; git/LSP already resolve correctly.)
+- **`grep` works without ripgrep**: if `rg` isn't installed (common on a fresh Windows box) the grep tool now falls back to a pure-Node search (recursive walk, default-ignore set, binary/large-file skip, CRLF-aware) instead of a cryptic `spawn rg ENOENT`. Verified end-to-end with `rg` removed from PATH.
+- **The agent knows its OS**: the system prompt now states the platform + shell, so on Windows it generates `dir`/`type`/`findstr` (or prefers the cross-platform read/list/glob/grep tools) instead of `ls`/`cat`/`grep` into cmd.exe.
+- **CRLF-safe vault indexing**: the markdown chunker normalizes `\r\n` so frontmatter/sections parse identically on Windows.
+- **Terminal**: respects `NO_COLOR` and auto-disables ANSI when output is piped/redirected (no `[2m` garbage on legacy cmd); `FORCE_COLOR` overrides.
+- **Clear "not installed" errors** for `git` (and ripgrep) instead of raw `spawn … ENOENT`.
+- (Prior turn) Node-version guard (≥ 22) with a clear message; install docs clarified for `-g` / `npx` / Windows `setx`.
+
+### Skills — 16 more real-work skills, author+verify reviewed (130 → 146)
+
+A second, larger batch filling concrete gaps in distributed-systems correctness, testing rigor, frontend, security, and AI — each one **independently verified** (a separate reviewer agent read the written file and judged frontmatter validity, structure, cross-reference resolution, technical accuracy, and *actionability* — would an agent actually be able to follow it; all 16 passed):
+
+- **Backend/distributed**: `design-api-pagination` (cursor/keyset, stable ordering, Relay connections), `distributed-locks-leases` (Redlock caveats + fencing tokens, leader election), `design-state-machine` (explicit FSM/statecharts vs boolean-flag soup), `schema-evolution-compatibility` (backward/forward compat, reserve-don't-reuse, expand-then-contract).
+- **Testing**: `debug-flaky-tests` (taxonomy + root-cause fixes, not retry-masking), `test-data-factories` (factories over fixtures, faker, deterministic seeds), `property-based-testing` (invariants + shrinking), `contract-testing` (consumer-driven Pact + can-i-deploy), `visual-regression-testing` (deterministic screenshots).
+- **Frontend**: `build-data-table` (virtualized sortable/filterable grids), `optimize-react-rerenders` (profiler-driven memoization).
+- **Security**: `configure-security-headers-csp` (strict CSP with nonces, HSTS, CORS done right), `encrypt-sensitive-data` (KMS envelope encryption, AEAD, key rotation).
+- **AI/LLM**: `build-vector-search` (ANN indexes, hybrid + RRF, eval), `structured-output-llm` (json_schema/tool-calling + validate-and-repair).
+- **DevEx**: `debug-ci-pipeline-failure` (reproduce locally, classify, fix root cause).
+
+All load cleanly (catalog now 146), cross-reference only real sibling skills, and follow the When-to-Use + NOT-this-skill + dense Steps structure.
+
+### Skills — 7 high-value additions, closing reliability/integration gaps (123 → 130)
+
+New bundled skills filling conspicuous holes in the catalog, authored to the existing dense, cross-referenced bar:
+
+- **resilience-timeouts-retries** — timeouts on everything, deadline propagation, retry-only-if-idempotent, exponential backoff + full jitter, circuit breakers, bulkheads, load-shedding (the general reliability primitive the catalog was missing alongside `rate-limiting`).
+- **idempotency-keys** — make writes safe to repeat: idempotency by design (PUT/upsert/conditional) vs by key (the `Idempotency-Key` header pattern, dedup table, 409/422, outbox), consumer-side dedup, "effectively-once".
+- **integrate-oauth-oidc** — "Log in with Google/GitHub/…": Authorization Code + PKCE, state/nonce, server-side token exchange, full ID-token validation, safe `email_verified` account linking, refresh rotation, native system-browser-only. Complements `auth-jwt-session` (which owns *your* session).
+- **send-transactional-email** — the deliverability half: SPF/DKIM/DMARC alignment, provider-not-cold-MTA, transactional/marketing stream isolation, bounce/complaint → suppression, idempotent sends, sandbox testing.
+- **design-multi-tenancy** — tenant isolation models (shared+RLS / schema / DB-per-tenant), the #1 cross-tenant-leak bug + defense-in-depth (app scoping + Postgres RLS), tenant context propagation, per-tenant migrations/export/delete.
+- **build-cli-tool** — argument parsing, exit codes, stdout=data/stderr=logs, TTY/NO_COLOR, config precedence (flags>env>file), no-secrets-in-flags, dry-run — the CLI/UX design counterpart to `shell-script-robust`.
+- **deliver-webhooks** — the *producer* side: HMAC signing + rotation, replay tolerance, at-least-once retries + dead-letter + replay, stable event ids for consumer dedup, SSRF defenses — complements `ingest-webhook-secure` (the receiver).
+
+Each loads cleanly (frontmatter `name`/`description`/`when_to_use`), cross-references only real sibling skills, and follows the When-to-Use + NOT-this-skill + Steps structure.
+
+### Onboarding & ease-of-use — no more dead-ends, clearer guidance
+
+The first-run / no-key experience now guides instead of dumping a raw error, and the REPL surfaces more of what's available:
+
+- **Headless with no key no longer dead-ends**: `sanook "task"` before any key is set now prints an actionable hint — run `sanook` for the wizard, or `export <ENV>=…` with the **provider console URL** to get a key — and, if a *different* provider's key is already in the environment, it suggests `sanook -m <that-provider> "…"`.
+- **Smart first-run**: if an API key is already in the environment (e.g. you `export ANTHROPIC_API_KEY=…` before installing), sanook skips the setup wizard, picks that provider, and confirms `✅ ready` instead of asking you to re-enter everything.
+- **Setup wizard** now shows the **console URL** for the chosen provider at the key step, and the run ends with a clear `✅ ตั้งค่าเสร็จ — พิมพ์งานได้เลย`.
+- **Actionable key errors**: a missing key names the provider + console URL + how to set it; a wrong-format key shows a readable example (`sk-ant-…`, `AIza…`) instead of a raw regex (and the example is kept short so redaction doesn't mangle it).
+- **Discoverability**: `/tools` now lists the orchestration tools (`task_parallel`/`task_spawn`/`task_collect`/`task_cancel`/`task_status`) and `diagnostics`; `/help` points to the shell-side commands (`search`/`index`/`brain`/`serve`/`mcp serve`/`config set`); the REPL empty-state hints `/help` and `/tools`.
+
+### Token/cost tuning knobs — 1h cache, summarize-compaction, sub-agent routing, thinking budget
+
+New `config.json` fields (and `SANOOK_*` env overrides) that trade tokens/cost without hurting quality — read once per turn via `agentTuning()`:
+
+- **`cacheTtl: "5m" | "1h"`** (env `SANOOK_CACHE_TTL`): the Anthropic prompt-cache lifetime. `"1h"` keeps the cached preamble alive across pauses (lunch, a meeting) so resuming doesn't re-pay full price for it. Default `"5m"` (unchanged).
+- **`compaction: "truncate" | "summarize"`** (env `SANOOK_COMPACTION`): when the conversation gets long, `"summarize"` condenses the dropped middle with a **cheap model** (the fast sibling of your main model, same key — `fastSibling()`) instead of truncating it — better recall at the same token budget. Used by `/compact` and proactively before very long turns; falls back to truncation if the summarizer fails (never blocks a turn). Default `"truncate"` (zero-LLM, unchanged). `src/compaction.ts` `summarizeCompact()` is pure (injected summarizer) and unit-tested with no network.
+- **`SANOOK_SUBAGENT_MODEL`**: route all sub-agent work to a cheaper model (e.g. `haiku`) while the main agent keeps the strong one — big savings for exploration-heavy runs. Default: inherit the parent model.
+- **`thinking: true | <budget>`** (env `SANOOK_THINKING`): opt-in Anthropic extended thinking on the **main** agent only (never sub-agents), with a hard `budgetTokens` cap so reasoning can't run away. Default off (no change).
+
+### Token efficiency — line-range reads + targeted edits
+
+Two quality-neutral cuts to per-turn token cost (the model asks for exactly what it needs):
+
+- **`read_file` line ranges**: `read_file({ path, offset?, limit? })` returns just lines `offset..offset+limit` (with a `[lines A–B of N]` header) instead of the whole file. Paired with `grep` (which already returns line numbers), the model reads a small window around a symbol rather than an entire large file — large input-token savings, identical result. Default (no offset/limit) is unchanged. The system prompt now nudges grep→read-range over whole-file reads.
+- **`edit_file` `replace_all`**: rename/repeated edits use a short `old_string` with `replace_all: true` instead of padding it with surrounding context for uniqueness (which the model otherwise sends twice, old + new). The ambiguous-match error now suggests `replace_all` rather than "add more context".
+- **Terser replies**: the system prompt tells the agent not to paste back file contents / large code blocks it just read or edited (the user already sees the diff) — cuts output tokens with no loss.
+- **Sub-agent model routing** (`SANOOK_SUBAGENT_MODEL`): opt-in env that routes all sub-agent work to a cheaper model (e.g. `haiku`) while the main agent keeps the strong model — big cost savings for exploration-heavy runs, default unchanged (inherit the parent model).
+
+### LSP diagnostics — `diagnostics` tool (type errors without a full build)
+
+A Node-native, zero-dependency Language Server Protocol client (`src/lsp/`) gives the agent a tight edit→check feedback loop: after editing a file it can pull the language server's diagnostics (type errors / lint) for that one file, no project-wide compile.
+
+- **`diagnostics` tool**: `diagnostics({ path, content? })` → ranked errors/warnings as `✗ path:line:col message [code]`. Pass `content` to check an unsaved buffer. Respects worktree scoping (`agentCwd`) and the read-path guard.
+- **Real LSP client** over Content-Length framing (distinct from MCP's newline framing): initialize handshake, `didOpen`/`didChange`, diagnostics that **settle** (a quiet period after the last publish so we return the final set, not an early empty one), and it answers server→client requests so a server can't stall. Positions convert from LSP 0-based to human 1-based.
+- **Server pool**: servers are spawned once per (binary, workspace) and reused — re-checking a file becomes a `didChange`, so the slow project-load cost is paid once, not per call.
+- **Zero-config floor**: sanook bundles no language servers (like ripgrep). It maps extension → conventional server (typescript-language-server, pyright, gopls, rust-analyzer, vscode-json-language-server, bash-language-server), detects whether it's installed (node_modules/.bin or PATH), and when it isn't, returns a clear install hint instead of crashing.
+- Tests: the framing codec (split frames, multibyte, malformed-recovery), the client handshake + diagnostics-settle + server-request handling against a **fake server** (no real LSP needed), the server registry + binary detection, and the tool's graceful degradation. Verified end-to-end against a real `typescript-language-server` (caught TS2322 at the right position; pooled `didChange` cleared it after a fix).
+
+### Real-time steering — interrupt a running turn + queue follow-ups (REPL)
+
+The interactive REPL was input-locked while the agent worked, and Ctrl+C quit the whole app. Now a turn is steerable:
+
+- **Interrupt mid-turn**: the running turn gets a real `AbortController` (wired into `runAgent`'s `signal`). Press **Esc** (or Ctrl+C) to stop the stream/tool loop right away and return to the prompt — without exiting the app. Partial output is kept for reference, the turn is dropped from the model history, and any files a tool already changed are recoverable via `/rewind`.
+- **Type-ahead queue**: you can type while the agent is busy; pressing Enter **queues** the message (shown as `⏳ คิว …`) and it runs automatically as the next turn when the current one finishes. Interrupting clears the queue.
+- Covered by an Ink integration test (mocked agent) asserting the signal is passed, input queues while busy, and Esc both aborts and clears the queue.
+
+### Worktree isolation — safe parallel WRITE subagents (`task_parallel isolate:true`)
+
+Parallel subagents that edit files would clobber a shared tree. Now each write subagent can run in its own throwaway **git worktree** (`src/worktree.ts`), branched from the current HEAD, and its changes are merged back afterward:
+
+- **Per-agent working directory**: `AgentContext` gains a `cwd`, and every file tool (read/write/edit/list/glob/grep/bash) plus the write-confinement guard (`permission.allowedRoots`) now resolve through `agentCwd()`. A subagent's relative path (`src/foo.ts`) lands in ITS worktree, not the main tree — so isolation can't leak. The main agent is unchanged (no `cwd` ⇒ `process.cwd()`); the OS sandbox already confines writes to the active cwd, so a worktree is automatically sandboxed.
+- **`task_parallel isolate:true`**: creates a worktree per write subagent, runs them concurrently in isolation, captures each worktree's diff, and applies them back to the main tree **sequentially** with `git apply --3way` — conflicts are reported (with the touched files), never silently overwritten. Worktrees are always cleaned up. Requires a git repo (falls back with a clear message otherwise).
+- **`src/worktree.ts`**: `createWorktree` / `captureDiff` (incl. untracked) / `applyDiff` / `removeWorktree` / `runInWorktrees`, all over the existing `runGit` helper. The create→isolate→merge→cleanup lifecycle is unit-tested against a real throwaway git repo with an injected work callback (no agent/network), covering the round-trip, the parallel different-files case, empty diffs, non-git fallback, and conflict reporting.
+
+### Subagent orchestration — parallel fan-out + background + nested (`task_parallel` / `task_spawn` / `task_collect` / `task_cancel` / `task_status`)
+
+The single one-shot `task` subagent grows into a real orchestration layer (`src/orchestrate.ts`):
+
+- **Parallel fan-out** (`task_parallel`): run up to 16 subagents concurrently with a real concurrency cap and **per-item error isolation** (one failure never sinks the batch); results returned in order. For independent work — explore N modules, review N angles — instead of serial subagents.
+- **Background / async** (`task_spawn` → `task_collect` / `task_cancel` / `task_status`): spawn a detached subagent, get an id immediately, keep working, gather the result later in the same session, or cancel it. `task_collect` supports a timeout so the agent can poll instead of block; failures are captured as `error` state (never an unhandled rejection); `task_cancel` aborts via the subagent's `AbortSignal`.
+- **Nested**: subagents may themselves `task` / `task_parallel` (bounded by the depth cap), so the main agent can decompose, then each branch can decompose again.
+- **Parallel-safe context**: each subagent runs inside its own `AsyncLocalStorage.run()` scope, so concurrent/nested agents never bleed model/budget/depth into one another.
+- Orchestration core is pure with an **injected runner** + injectable clock/id-gen, unit-tested with a fake runner (concurrency cap, error isolation, spawn/collect/cancel/timeout) — zero model calls in CI.
+
+### Brain search — hybrid semantic search over the second brain (`sanook index` / `sanook search` / `sanook mcp serve`)
+
+A Node-native search subsystem (`src/search/`) over the second-brain vault **plus** bi-temporal memory, past sessions, and skills — one ranked surface, zero new heavy deps.
+
+- **Real BM25, zero-dependency floor**: a pure-TS inverted index (k1=1.2, b=0.75, genuine corpus-stat IDF, title field-boost) — no SQLite, no Bun, no native binary, works with no key and no network on any OS Node 22 runs on. Tokenization builds on the canonical `normalize()` and segments with `Intl.Segmenter` so **Thai** splits into real words.
+- **Incremental indexer** (`sanook index`): mtime+size+sha256 manifest diff over the existing vault via `brainPath` — O(delta), unchanged files cost one `stat()`, deleted files are evicted precisely. No `ψ/`-style directory convention required. Folds in active memory facts (with an importance prior; quarantined/inbox facts excluded), recent sessions, and skills.
+- **Optional BYOK semantic** (`--mode hybrid|semantic`): embeddings through your *existing* provider key (`@ai-sdk/{openai,mistral,google,…}` `embedMany`), stored as a compact Float32 sidecar, cosine in-process over a candidate set; fused with BM25 via **Reciprocal Rank Fusion** (scale-free, k=60). Lazy — absent without a key; a model change self-invalidates the cache. Degrades silently to BM25 on any embedding error.
+- **MCP SERVER** (`sanook mcp serve`): sanook was MCP client-only; it now also *exposes* a stdio JSON-RPC server (`sanook_search` / `sanook_recall` / `sanook_remember` / `sanook_index` / `sanook_stats`), so Claude Desktop / Cursor / any MCP host can mount sanook's brain. Same zero-dep framing as the client; stdout stays protocol-clean.
+- **`recall` upgraded**: the agent's recall tool now ranks by BM25 across all four corpora with snippets (was substring term-counting), and folds freshly-`remember`ed facts in on every call.
+- Tests: BM25 ranking/IDF/no-posting-creep, heading chunker + frontmatter + wikilinks, RRF, incremental indexer (in-memory fs), cosine/serialize (fake vectors), engine modes + degradation, MCP server dispatch + a real piped-child round-trip (≈70 new).
+
+### Competitive parity pass (table-stakes the OSS field now expects)
+
+- **Remote MCP**: connect MCP servers over Streamable-HTTP (`{ "url": "https://…", "headers": {…} }`), not just stdio — half the hosted MCP ecosystem (GitHub/Slack/Postgres/…) is HTTP-only. `sanook mcp add <name> <url>` auto-detects remote.
+- **Prompt caching**: the static system preamble (instructions + skills + brain + repo map) is sent as a cached Anthropic block, cutting cost/latency on multi-step turns; safely ignored by other providers.
+- **OS sandbox for `run_bash`**: Seatbelt (macOS) / bubblewrap (Linux) confine shell **writes** to the workspace/brain/tmp — defense-in-depth over the regex blocklist. Reads + network unchanged; `SANOOK_NO_SANDBOX=1` to disable.
+- **Checkpoint + `/rewind`**: a shadow-git snapshot before each turn; `/rewind` restores files **and** truncates the conversation (recoverable — it stashes the current state first).
+- **Input ergonomics**: multiline (trailing `\` / Alt+Enter), `↑`/`↓` persisted prompt history, readline keys (Ctrl-A/E/U/K/W), and `@file` mentions that inline file contents.
+- **Image / vision input**: `@image.png` attaches the image to vision-capable models (history keeps a lightweight placeholder, not the bytes).
+- **Custom slash commands**: `.sanook/commands/<name>.md` prompt templates invoked as `/<name>` (project commands gated by trust).
+- **Repo map**: a zero-dep, git-aware symbol map injected at session start so the agent selects files without blind grepping.
+- **Reliability**: rate-limit/overload retry with exponential backoff, kept distinct from auth/billing failures (which fail fast); per-tool execution timeouts so a runaway read/grep can't hang the loop.
+- **Minimal terminal-first TUI**: compact gradient banner, a real cursor + placeholder, and cleaner turn rendering.
+
+### Fixes
+
+- **Multi-turn history loss**: REPL/`--continue` now retain the full conversation (the user's earlier turns were being dropped — only assistant/tool messages were kept).
+- **Budget cap was silent for ~all non-Anthropic models**: added approximate list prices for the other providers, a `pricing` override (`sanook config set pricing …` / `SANOOK_PRICING`), and a warning when `-b` is set for a model (or fallback model) with no pricing. Cost now carries over when the model falls back instead of resetting.
+- MCP SSE parsing no longer aborts on a malformed earlier event; checkpoint restore pins the snapshot commit (correct even after an intervening commit) and removes files added after the snapshot.
+
+- Tests: remote-MCP, sandbox, repo map, prompt-caching/system-preservation, rate-limit classification, tool timeout, checkpoint restore, cost merge, custom commands (≈200 total).
+
 ## 0.4.0 — second brain, GLM Coding Plan, Telegram, hardening
 
 - **Second brain**: `sanook brain init` scaffolds a portable Obsidian "second-brain" workspace — full folder taxonomy (each with `_Index.md`), a central `Vault Structure Map.md`, seed memory files, and a portable AI operating constitution (`CLAUDE/GEMINI/AGENTS.md`). Research-backed rules: context-assembly (anti context-rot), intake quarantine + injection-scan, bi-temporal fact validity, provenance tracking, a verification-gated `Skills/` library, sleep-time consolidation. The agent now **loads the vault** into context, and `brain init` **auto-wires a filesystem MCP** to it. First-run wizard offers to create one (personalized).

package/README.md

@@ -2,19 +2,25 @@
 
 # Sanook CLI
 
-**A terminal AI coding agent — built from scratch in TypeScript.**
+**The open-source terminal AI coding agent that remembers across sessions.**
 
-Bring your own key, run with any of 12 model providers, and let it remember what it did across sessions.
+Bring your own key · 12 providers · MCP · a built-in **"second brain"** that gives the AI durable memory across sessions — the thing Claude Code, Codex, and Gemini CLI lose at the session boundary.
 
-[![Version](https://img.shields.io/badge/version-0.3.0-2563eb.svg)](https://github.com/Sir-chawakorn/sanook-cli/releases)
+🇹🇭 [อ่านภาษาไทย](README.th.md)
+
+[![npm](https://img.shields.io/npm/v/sanook-cli.svg?color=2563eb)](https://www.npmjs.com/package/sanook-cli)
+[![downloads](https://img.shields.io/npm/dm/sanook-cli.svg?color=2563eb)](https://www.npmjs.com/package/sanook-cli)
 [![License](https://img.shields.io/badge/license-Apache--2.0-22c55e.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A5%2022-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
-[![Tests](https://img.shields.io/badge/tests-143%20passing-22c55e.svg)](#development)
+[![Tests](https://img.shields.io/badge/tests-381%20passing-22c55e.svg)](#development)
 [![CI](https://github.com/Sir-chawakorn/sanook-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Sir-chawakorn/sanook-cli/actions/workflows/ci.yml)
 
 [Quickstart](#quickstart) · [Providers](#providers) · [Usage](#usage) · [Gateway](#gateway--scheduling) · [Skills](#skills) · [MCP](#mcp) · [Security](#security)
 
+<!-- 📹 DEMO GIF — record the close-session → reopen → "it remembered" loop (asciinema + agg), save to docs/demo.gif, then uncomment: -->
+<!-- ![sanook-cli demo](docs/demo.gif) -->
+
 </div>
 
 ---
@@ -31,12 +37,43 @@ prompt → LLM → tool call → result → loop → answer
 
 It is **BYOK (bring your own key)** by design. Every provider connects with a **direct API key from that provider's own console** — Sanook never reuses OAuth or subscription credentials, because that violates provider terms and gets accounts banned.
 
+## How it compares
+
+The agent loop, BYOK, and MCP are table stakes now. What Sanook has that the big vendor CLIs don't is **memory that survives the session** — a structured Obsidian "second brain" the agent reads at the start of every run.
+
+| | **Sanook** | Claude Code | Codex CLI | Gemini CLI |
+|---|:---:|:---:|:---:|:---:|
+| Open-source | ✅ | ❌ | ✅ | ✅ |
+| Bring your own key | ✅ | — | ✅ | ✅ |
+| Providers | **12** | 1 | 1 | 1 |
+| Local models (Ollama / LM Studio) | ✅ | ❌ | ❌ | ❌ |
+| MCP (stdio **+ remote HTTP**) | ✅ | ✅ | ✅ | ✅ |
+| OS sandbox (Seatbelt / bubblewrap) | ✅ | ✅ | ✅ | ✅ |
+| Checkpoint / rewind | ✅ | ✅ | ✅ | ✅ |
+| Image / vision input | ✅ | ✅ | ✅ | ✅ |
+| Prompt caching | ✅ | ✅ | ✅ | ✅ |
+| **Durable cross-session memory** | ✅ | ❌ | ❌ | ❌ |
+| **Local gateway + cron + Telegram** | ✅ | ❌ | ❌ | ❌ |
+
+On raw benchmark scores the frontier vendors win — Sanook's bet is **portability + persistent memory**, not beating Opus on SWE-bench. Use whatever fits; this one remembers.
+
 ## Quickstart
 
+Install **globally** — the `-g` is required (needs **Node ≥ 22**; check with `node -v`):
+
 ```bash
 npm install -g sanook-cli
+```
+
+> ⚠️ **`'sanook' is not recognized` / command not found?** You installed it locally — `npm i sanook-cli` (without `-g`) drops it into the current folder, **not on your PATH**, so the `sanook` command isn't found. Fix: reinstall with `npm install -g sanook-cli`, or just run it via **`npx sanook`** (uses the local copy you already installed).
+> Run **`npx sanook doctor`** to auto-diagnose Node version / PATH / install state and print the exact fix for your OS (incl. a safe Windows PATH one-liner).
+
+Set an API key (or run `sanook` with no task for the interactive setup wizard):
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...        # macOS / Linux
+setx ANTHROPIC_API_KEY "sk-ant-..."        # Windows (export won't work in cmd) — then open a NEW terminal
 
-export ANTHROPIC_API_KEY=sk-ant-...        # or run `sanook` and use the setup wizard
 sanook "read package.json and list the dependencies"
 ```
 
@@ -52,15 +89,20 @@ sanook --json "..."             # JSONL output for CI / scripts
 
 | Area | What you get |
 |---|---|
-| **Agent loop** | Built on the Vercel AI SDK 6 (`streamText` + `stopWhen` + `fullStream`), with streamed output, a cost meter, and a budget cap. |
-| **Tools** | `read_file` · `write_file` · `edit_file` (multi-tier matcher) · `list_dir` · `glob` · `grep` · `run_bash`, plus git tools — gated by a permission layer that denies destructive commands and protected paths. |
-| **Approval** | Interactive `ask` mode prompts `y/n` before any file write or shell command. `--yes` for auto-approve; headless defaults to safe-deny. |
-| **Memory** | The agent writes its own notes (`remember`), recalls them across past sessions (`recall`), and `--continue` resumes the last run where it left off. |
-| **Skills** | 69 built-in skills + install your own from a GitHub repo, URL, or local path. The agent can also author new skills after a repeatable task. |
+| **Agent loop** | Built on the Vercel AI SDK 6 (`streamText` + `stopWhen` + `fullStream`), with streamed output, a cost meter, a budget cap, Anthropic **prompt caching** on the static preamble, and rate-limit-aware retry/backoff (distinct from auth failures) with model fallback. |
+| **Tools** | `read_file` · `write_file` · `edit_file` (multi-tier matcher) · `list_dir` · `glob` · `grep` · `run_bash`, plus git tools — gated by a permission layer that denies destructive commands, protected paths, and paths outside the workspace/brain by default. Non-bash tools are timeout-guarded so a runaway read/grep can't hang the loop. |
+| **Sandbox** | `run_bash` is confined by an OS sandbox — **Seatbelt** on macOS, **bubblewrap** on Linux — so shell writes stay inside the workspace/brain/tmp (reads + network unaffected). Opt out with `SANOOK_NO_SANDBOX=1`. |
+| **Approval** | `ask` mode is the default and prompts `y/n` before any file write or shell command. `--yes` for auto-approve; headless ask-mode safely denies mutations when no approval UI exists. |
+| **Input** | Multiline editing, `↑`/`↓` persisted prompt history, readline keys (Ctrl-A/E/U/K/W), and `@file` mentions that inline a file's contents (or attach an **image** for vision-capable models). |
+| **Checkpoint** | A shadow-git snapshot is taken before each turn; `/rewind` restores the files **and** truncates the conversation — recoverable (it stashes the current state first). |
+| **Memory** | The agent writes its own notes (`remember`), recalls them across past sessions (`recall`), and `--continue` resumes the latest run for the current project. |
+| **Repo map** | A lightweight symbol map of the repo (zero-dep, git-aware) is injected at session start so the agent picks the right files without blind grepping. |
+| **Skills** | Built-in skills + install your own from a GitHub repo, URL, or local path. The agent can also author new skills after a repeatable task. |
+| **Custom commands** | Drop a `.sanook/commands/<name>.md` prompt template and call it as `/<name>` (project commands require trust). |
 | **Subagents** | A `task` tool spawns a fresh-context sub-agent for scoped exploration without bloating the main context — read-only by default, depth-guarded. |
 | **Gateway + cron** | `sanook serve` runs a long-lived daemon: a loopback OpenAI-compatible HTTP endpoint plus a cron scheduler. Ask it in plain language and it schedules itself. |
 | **Channels** | A Telegram adapter (long-polling, no public URL) lets you drive the agent from your phone — locked down with a required allowlist and private-chat-only policy. |
-| **MCP** | Connect any Model Context Protocol server (filesystem, GitHub, Postgres, …) via `~/.sanook/mcp.json`. |
+| **MCP** | Connect any Model Context Protocol server over **stdio or remote Streamable-HTTP** (filesystem, GitHub, Postgres, hosted servers, …) via `~/.sanook/mcp.json`. |
 | **Git** | Branch, uncommitted changes, and recent commits are injected automatically, with `git_status` / `git_diff` / `git_log` / `git_commit` tools. |
 | **Hooks** | Run your own command before/after any tool. A non-zero `PreToolUse` exit blocks the tool — enforce lint, format, or policy. |
 | **Plan mode** | `--plan` restricts the agent to read-only tools and asks it to produce a plan before touching anything. |
@@ -98,9 +140,11 @@ sanook models anthropic       # curated ids (+ live verification if a key is set
 ```
 sanook "<task>"          run one task (headless)
 sanook                   interactive REPL
-sanook -c "<task>"       resume the latest session
+sanook -c "<task>"       resume the latest session for this project
+sanook --continue-any    resume the newest session across all projects
 sanook --plan "<task>"   plan mode (read-only)
 sanook --json "<task>"   JSONL output for scripts / CI
+sanook update            update the CLI to the latest npm release
 
   -m, --model <spec>     model or provider:model-id
   -b, --budget <usd>     stop when estimated cost exceeds this
@@ -109,7 +153,20 @@ sanook --json "<task>"   JSONL output for scripts / CI
   -h, --help             show help
 ```
 
-**REPL slash commands:** `/model` · `/tools` · `/skills` · `/cost` · `/clear` · `/compact` · `/help` · `/quit`
+**REPL slash commands:** `/model` · `/tools` · `/skills` · `/cost` · `/diff` · `/undo` · `/rewind` · `/clear` · `/compact` · `/help` · `/quit` — plus your own `.sanook/commands/*.md`. Input supports `↑`/`↓` history, `@file` mentions (text or image), and multiline (trailing `\` or Alt+Enter).
+
+## Updating
+
+Use the built-in updater whenever a new CLI version is available:
+
+```bash
+sanook update
+sanook update --check   # check only
+```
+
+It checks the npm `latest` release for `sanook-cli` and, when newer than your installed version, runs `npm install -g sanook-cli@latest`.
+
+When you launch the interactive TUI with plain `sanook`, the CLI checks for updates at most once per day. If a newer version exists, it asks `Yes/No` before running the same updater. Set `SANOOK_DISABLE_UPDATE_CHECK=1` to silence the prompt.
 
 ## Gateway & scheduling
 
@@ -122,7 +179,7 @@ sanook cron list
 sanook cron rm <id>
 ```
 
-The HTTP server binds to **loopback only** and authenticates every endpoint (except `/health`) with a bearer token stored at `~/.sanook/gateway/token` (chmod 600). It speaks the OpenAI chat-completions shape, so existing clients work unchanged:
+The HTTP server binds to **loopback only** and authenticates every endpoint (except `/health`) with a bearer token stored at `~/.sanook/gateway/token` (chmod 600). It runs mutating tools in `ask` mode by default; opt into unattended writes with `sanook config set permissionMode auto` or `SANOOK_GATEWAY_ALLOW_WRITE=1`. It speaks the OpenAI chat-completions shape, so existing clients work unchanged:
 
 ```bash
 curl http://127.0.0.1:8787/v1/chat/completions \
@@ -151,7 +208,7 @@ The channel is **fail-closed**: with no allowlist it refuses to start, it accept
 
 ## Skills
 
-A skill is a `SKILL.md` file (front-matter + instructions) the agent loads on demand. Sanook ships with 69 built-in skills and can install more.
+A skill is a `SKILL.md` file (front-matter + instructions) the agent loads on demand. Sanook ships with built-in skills and can install more.
 
 ```bash
 sanook skill list                          # browse all skills
@@ -176,21 +233,55 @@ It creates a full folder taxonomy (`Projects/`, `Sessions/`, `Shared/` memory la
 
 Everything is **create-if-missing** — re-running never overwrites your notes. Point an Obsidian or filesystem MCP server at the workspace to let the agent read and write it.
 
+### Brain search
+
+Ranked search over the vault **and** the agent's memory, past sessions, and skills — one surface, no native binaries:
+
+```bash
+sanook index                       # incremental index of vault + memory + sessions + skills (O(delta))
+sanook search "vercel edge deploy" # ranked hits with snippets
+sanook search "race condition" --mode hybrid --source vault,memory --limit 5
+```
+
+- **Zero-config floor** — a pure-TypeScript BM25 inverted index (genuine corpus-stat IDF, title boost, `Intl.Segmenter` word breaks for Thai). No SQLite, no Bun, no native binary, no API key, no network.
+- **Optional semantic** — `--mode hybrid|semantic` embeds through your *existing* provider key (OpenAI / Mistral / Google / …), stores compact Float32 vectors locally, and fuses with BM25 via Reciprocal Rank Fusion. Activates only when a key resolves; degrades silently to BM25 otherwise. Configure with `sanook config set embeddingModel openai:text-embedding-3-small` (or `SANOOK_EMBEDDING_MODEL`).
+- **Incremental** — only changed files are re-read (mtime+sha manifest); deleted files are evicted. Run after editing the vault, or wire it into a hook/cron.
+
+The agent's `recall` tool uses the same engine, so remembered facts and vault notes are searchable the moment they exist.
+
 ## MCP
 
-Connect Model Context Protocol servers (stdio) with the same config shape you already use elsewhere:
+Connect Model Context Protocol servers over **stdio or remote Streamable-HTTP** with the same config shape you already use elsewhere:
 
 ```jsonc
 // ~/.sanook/mcp.json
 {
   "mcpServers": {
-    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] }
+    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] },
+    "remote":     { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer <token>" } }
   }
 }
 ```
 
+Add servers from the CLI too: `sanook mcp add fs npx -y @modelcontextprotocol/server-filesystem /path` (stdio) or `sanook mcp add remote https://example.com/mcp` (a URL is detected as remote HTTP).
+
 Their tools are merged into the agent's toolset automatically. `/tools` in the REPL lists everything currently available.
 
+sanook is also an MCP **server**: `sanook mcp serve` exposes your brain (`sanook_search` / `sanook_recall` / `sanook_remember` / `sanook_index` / `sanook_stats`) over stdio, so Claude Desktop, Cursor, or any MCP host can query it:
+
+```jsonc
+// in another host's MCP config
+{ "mcpServers": { "sanook-brain": { "command": "sanook", "args": ["mcp", "serve"] } } }
+```
+
+Project-local `.sanook/mcp.json`, `.sanook/hooks.json`, `.sanook/skills/`, and `.sanook/commands/` are ignored until the project is trusted:
+
+```bash
+sanook trust status
+sanook trust add       # allow this project's .sanook mcp/hooks/skills/commands
+sanook trust remove
+```
+
 ## Configuration
 
 Everything lives under `~/.sanook/` (with per-project `.sanook/` overrides where relevant):
@@ -198,21 +289,55 @@ Everything lives under `~/.sanook/` (with per-project `.sanook/` overrides where
 ```
 ~/.sanook/auth.json          API keys (chmod 600)
 ~/.sanook/memory/            auto-memory the agent writes
+~/.sanook/search/            brain-search index + optional embedding vectors (regenerable via `sanook index`)
 ~/.sanook/sessions/          saved conversations (for --continue)
 ~/.sanook/skills/<name>/     installed SKILL.md files
 ~/.sanook/mcp.json           MCP servers  { "mcpServers": { … } }
 ~/.sanook/hooks.json         PreToolUse / PostToolUse hooks
 ~/.sanook/gateway/           gateway token + task ledger
+~/.sanook/trusted-projects.json project roots allowed to load project .sanook extensions
 SANOOK.md                    project memory (hierarchical, like a system prompt)
 ```
 
+Untrusted project config can set ordinary project defaults, but it cannot lower `permissionMode` to `auto`; trust the project first if you want project-local config to control mutation approval.
+
+### Token / cost tuning
+
+Quality-neutral knobs in `~/.sanook/config.json` (or the matching `SANOOK_*` env var) to cut tokens/cost:
+
+| `config set …` | env | effect |
+|---|---|---|
+| `cacheTtl 1h` | `SANOOK_CACHE_TTL=1h` | keep the cached system preamble alive for 1h (default `5m`) — cheaper to resume after a pause |
+| `compaction summarize` | `SANOOK_COMPACTION=summarize` | when context gets long, condense it with a **cheap model** instead of truncating — better recall at the same budget (default `truncate`, zero-LLM) |
+| — | `SANOOK_SUBAGENT_MODEL=haiku` | run all sub-agent work (exploration/search) on a cheaper model while the main agent keeps the strong one |
+| `summaryModel <spec>` | `SANOOK_SUMMARY_MODEL=<spec>` | model used for summarize-compaction (default: the fast sibling of your main model) |
+| `thinking 4000` | `SANOOK_THINKING=4000` | opt-in Anthropic extended thinking on the main agent with a `budgetTokens` cap (default off) |
+
+Read-side savings are automatic: the agent reads file ranges (`read_file` with `offset`/`limit`) and edits with minimal `old_string` / `replace_all` rather than rewriting whole files.
+
+Useful environment flags:
+
+```bash
+SANOOK_MODEL=sonnet                 # default model alias or provider:model
+SANOOK_ALLOW_OUTSIDE_WORKSPACE=1    # allow file tools outside cwd/brain
+SANOOK_GATEWAY_ALLOW_WRITE=1        # let sanook serve run mutating tools unattended
+SANOOK_HOOKS_INHERIT_ENV=1          # pass full env to hooks instead of a minimal safe env
+SANOOK_DISABLE_PERSISTENCE=1        # do not save sessions or memory
+SANOOK_DISABLE_UPDATE_CHECK=1       # do not show interactive update prompts
+SANOOK_DISABLE_WORKLOG=1            # do not append second-brain worklogs
+SANOOK_TRUST_PROJECT=1              # temporary trust override for project .sanook extensions
+```
+
 ## Security
 
 Sanook runs shell commands and edits files, so safety is built into the core rather than bolted on:
 
 - **BYOK, direct keys only** — OAuth and subscription tokens are rejected by an explicit guard (`ya29.`, `Bearer`, `sk-ant-oat…`). This keeps you within every provider's terms of service.
-- **Permission gate** — destructive commands (`rm -rf`, `git reset --hard`, `push --force`, fork bombs, …) and writes to protected paths are denied; interactive `ask` mode confirms mutations.
-- **Secret redaction** — API keys are stripped from error messages and logs.
+- **Permission gate** — destructive commands (`rm -rf`, `git reset --hard`, `push --force`, fork bombs, …), protected paths (`.env`, `.git`, `node_modules`, credential folders), and paths outside the workspace/brain are denied unless explicitly opted in.
+- **OS sandbox** — `run_bash` runs under Seatbelt (macOS) / bubblewrap (Linux) when available, confining shell writes to the workspace/brain/tmp — defense in depth beyond the regex blocklist (`SANOOK_NO_SANDBOX=1` to disable).
+- **Project trust gate** — project `.sanook/mcp.json`, `.sanook/hooks.json`, `.sanook/skills/`, and `.sanook/commands/` can execute or steer the agent, so they are ignored until `sanook trust add`.
+- **Secret redaction** — API keys are stripped from error messages, saved sessions, memory, and worklogs.
+- **Safe fallback** — provider fallback does not retry after a mutating tool call has already happened, avoiding duplicate side effects.
 - **Gateway** — HTTP binds to `127.0.0.1` only and requires a bearer token on every non-health endpoint.
 - **Telegram** — fail-closed: a required allowlist, private-chat-only, per-chat rate-limiting, and generic error replies that never reveal internal paths.
 
@@ -223,7 +348,7 @@ Hardened across several adversarial security reviews covering command injection,
 ```bash
 npm install
 npm run build       # → dist/
-npm test            # vitest — 143 tests
+npm test            # vitest
 npm run typecheck   # tsc --noEmit (strict)
 npm run dev -- "…"  # run from source without building
 ```
@@ -234,6 +359,14 @@ CI runs the suite across macOS / Linux / Windows on Node 22 and 24. Requires **N
 
 [Apache-2.0](LICENSE)
 
+---
+
 <div align="center">
+
+**Built by [Sanook AI](https://www.facebook.com/sanookai)** — AI tools & education 🇹🇭
+
+[Facebook](https://www.facebook.com/sanookai) · [X / Twitter](https://x.com/sanook_ai)
+
 <sub>Built from scratch in TypeScript on the Vercel AI SDK — no framework, no magic.</sub>
+
 </div>

package/README.th.md

@@ -0,0 +1,136 @@
+<div align="center">
+
+# Sanook CLI
+
+**AI coding agent ใน terminal ที่ "จำงานข้ามวันได้" — open-source**
+
+ใส่ API key ของคุณเอง (BYOK) · 12 providers · MCP · มี **"สมองที่สอง" (second brain)** ที่ทำให้ AI จำ context ข้าม session ได้ — สิ่งที่ Claude Code / Codex / Gemini CLI ลืมทุกครั้งที่ปิด terminal
+
+[![npm](https://img.shields.io/npm/v/sanook-cli.svg?color=2563eb)](https://www.npmjs.com/package/sanook-cli)
+[![downloads](https://img.shields.io/npm/dm/sanook-cli.svg?color=2563eb)](https://www.npmjs.com/package/sanook-cli)
+[![License](https://img.shields.io/badge/license-Apache--2.0-22c55e.svg)](LICENSE)
+
+🇬🇧 [Read in English](README.md)
+
+</div>
+
+---
+
+## มันคืออะไร
+
+Sanook คือ **AI coding agent** ที่รันใน terminal — สั่งงานเป็นภาษาคน แล้วมันอ่านไฟล์ / แก้โค้ด / รันคำสั่ง / commit ให้ หัวใจคือ loop เดียว:
+
+```text
+prompt → LLM → เรียก tool → ผลลัพธ์ → loop → ตอบ
+```
+
+จุดต่างจากเจ้าใหญ่คือ **second brain** (โครงสร้างโน้ต Obsidian) ที่ agent อ่านก่อนทำงานทุกครั้ง จึงจำได้ว่าเคยทำอะไร ชอบอะไร และตัดสินใจอะไรไปแล้วข้าม session
+
+## เริ่มใช้
+
+ติดตั้งแบบ **global** (ต้องมี `-g`) — ต้องมี **Node ≥ 22** (เช็กด้วย `node -v`):
+
+```bash
+npm install -g sanook-cli
+```
+
+> ⚠️ **`'sanook' is not recognized` / command not found?**
+> แปลว่าลงแบบ local — `npm i sanook-cli` (ไม่มี `-g`) มันลงในโฟลเดอร์ปัจจุบัน **ไม่เข้า PATH** คำสั่ง `sanook` เลยหาไม่เจอ
+> แก้: ลงใหม่ด้วย `npm install -g sanook-cli` · หรือเรียกผ่าน **`npx sanook`** (ใช้ตัวที่ลง local ไปแล้วได้เลย)
+> หรือรัน **`npx sanook doctor`** — ตรวจ Node/PATH/สถานะการติดตั้งให้ แล้วบอกคำสั่งแก้ที่ตรงกับ OS (มีบรรทัดแก้ PATH บน Windows แบบปลอดภัยให้ก็อปด้วย)
+
+ตั้ง API key (หรือรัน `sanook` เฉย ๆ ครั้งแรกจะมี setup wizard ให้เลือก provider + วาง key):
+
+```bash
+# macOS / Linux
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Windows (Command Prompt) — export ใช้ไม่ได้ ต้อง setx แล้วเปิด terminal ใหม่
+setx ANTHROPIC_API_KEY "sk-ant-..."
+```
+
+แล้วสั่งงานได้เลย:
+
+```bash
+sanook                 # REPL (ครั้งแรก = setup wizard)
+sanook "อ่าน package.json แล้วบอกว่ามี dependencies อะไรบ้าง"
+sanook -c "ทำต่อจาก session ล่าสุดของ project นี้"
+sanook --continue-any "ทำต่อจาก session ล่าสุดข้าม project"
+```
+
+## ทำอะไรได้บ้าง
+
+- **BYOK + 12 providers** — Anthropic, Google, OpenAI, DeepSeek, xAI, Mistral, Groq, MiniMax, GLM, Ollama, LM Studio, Codex
+- **Second brain** — `sanook brain init` สร้าง workspace Obsidian ให้ AI จำงานข้ามวัน
+- **Tools** — อ่าน/เขียน/แก้ไฟล์ · รัน bash · git · grep/glob พร้อม permission gate
+- **Gateway + cron** — `sanook serve` รันเป็น service 24/7 + ตั้งงานล่วงหน้า + ต่อ Telegram
+- **MCP + Skills** — ต่อ MCP server ได้ + มี built-in skills และติดตั้งเพิ่มได้
+- **Update ง่าย** — ใช้ `sanook update` เพื่ออัปเดต CLI เป็นเวอร์ชันล่าสุดจาก npm
+
+## ใช้ provider ไหนก็ได้
+
+```bash
+sanook -m sonnet "..."         # Claude
+sanook -m gemini "..."         # Gemini
+sanook -m glm:smart "..."      # GLM (z.ai Coding Plan)
+sanook -m ollama "..."         # local ไม่ต้องมี key
+```
+
+ตั้งค่า default model ได้ด้วย:
+
+```bash
+sanook config set model sonnet
+# หรือใช้ env
+SANOOK_MODEL=sonnet sanook "..."
+```
+
+## อัปเดต CLI
+
+เวลามีเวอร์ชันใหม่ ใช้คำสั่งเดียว:
+
+```bash
+sanook update
+sanook update --check   # เช็กอย่างเดียว
+```
+
+คำสั่งนี้จะเช็ก npm `latest` ของ `sanook-cli` แล้วอัปเดตด้วย `npm install -g sanook-cli@latest` เมื่อมีเวอร์ชันใหม่กว่า
+
+ถ้าเปิด TUI ด้วย `sanook` เฉย ๆ CLI จะเช็กอัปเดตอย่างมากวันละครั้ง ถ้ามีเวอร์ชันใหม่จะถาม `Yes/No` ก่อนอัปเดต ปิด prompt ได้ด้วย `SANOOK_DISABLE_UPDATE_CHECK=1`
+
+## ความปลอดภัย
+
+Sanook ตั้งค่าเริ่มต้นให้ระวังไว้ก่อน:
+
+- `ask` mode เป็นค่าเริ่มต้น ก่อนเขียนไฟล์หรือรัน shell จะขออนุมัติ ถ้าเป็น headless แล้วไม่มี UI จะปฏิเสธ mutation
+- file tools แตะได้เฉพาะ workspace ปัจจุบันและ second brain ที่ตั้งไว้ ถ้าจะออกนอก scope ต้อง opt-in ด้วย `SANOOK_ALLOW_OUTSIDE_WORKSPACE=1`
+- path เสี่ยงอย่าง `.env`, `.git`, `node_modules`, credential folders และ `~/.sanook` ถูกบล็อก
+- project `.sanook/config.json` ที่ยังไม่ trusted ตั้งค่าทั่วไปได้ แต่ลด `permissionMode` เป็น `auto` ไม่ได้
+- project `.sanook/mcp.json`, `.sanook/hooks.json`, `.sanook/skills/`, และ `.sanook/commands/` ถูก ignore จนกว่าจะ trust project:
+
+```bash
+sanook trust status
+sanook trust add
+sanook trust remove
+```
+
+- gateway bind ที่ `127.0.0.1` และต้องใช้ bearer token ยกเว้น `/health`; mutating tools ใน `sanook serve` เป็น `ask` โดย default และ opt-in unattended write ได้ด้วย `sanook config set permissionMode auto` หรือ `SANOOK_GATEWAY_ALLOW_WRITE=1`
+- session/memory/worklog redact API keys ก่อนบันทึก และปิด persistence ได้ด้วย `SANOOK_DISABLE_PERSISTENCE=1`
+
+## พัฒนา
+
+```bash
+npm install
+npm run build
+npm test            # vitest
+npm run typecheck
+```
+
+---
+
+<div align="center">
+
+**สร้างโดย [Sanook AI](https://www.facebook.com/sanookai)** — เครื่องมือ + ความรู้ AI สำหรับคนไทย
+
+[Facebook](https://www.facebook.com/sanookai) · [X / Twitter](https://x.com/sanook_ai)
+
+</div>