sanook-cli 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 0.5.9
+
+### Codex (ChatGPT plan) + install
+
+- **Codex models** — setup, `/model` picker, and config migration now only offer ChatGPT-plan-safe models (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`); legacy `gpt-5-codex` / `*-codex` ids auto-migrate instead of failing at runtime.
+- **Codex errors** — surface JSONL API errors from `codex exec` (not just opaque exit codes).
+- **Install** — README install section, GitHub Pages deploy script, npm publish guard (`scripts/publish-npm.sh`).
+
+## 0.5.8
+
+### Self-maintaining memory + reliability & security hardening
+
+**New: automatic memory maintenance** (default on; `sanook config set autoMaintain off` / `SANOOK_DISABLE_AUTO_MAINTAIN=1` to disable)
+
+- **Auto-consolidate** — on REPL startup (at most once a week) the second brain consolidates itself: dedup memory, archive stale notes by importance decay (reversible — never deletes), refresh the index. Background, non-blocking.
+- **Auto-distill** — on session exit (and each headless turn) durable facts from the conversation are distilled into the compounding memory store so the self-retrieving brain surfaces them next time (previously opt-in via `SANOOK_AUTO_DISTILL`).
+- Status shown in `sanook config`.
+
+**Vault data-integrity fixes** (second brain)
+
+- Worklog/transcript/index writers no longer truncate history when pasted content contains an `up::` line — the footer regex now matches only the trailing footer.
+- `$`-sequences in prompts/answers/titles/paths no longer corrupt vault notes (String.replace replacement-pattern injection) — fixed across every note/index writer.
+- Worklog writes are serialized (lost-update under back-to-back turns); chat-transcript headings use the real per-turn time (were frozen to session start, and mis-filed past midnight).
+
+**Persona** (`sanook persona`)
+
+- `sanook persona <bad-arg>` errors with an unknown-subcommand message instead of falling through to a paid LLM call.
+- Re-running with identical answers no longer claims facts were newly saved; Esc-back no longer overwrites a prior answer (including a custom "อื่นๆ" value); warns when the vault profile note can't be written.
+
+**REPL / terminal**
+
+- Detailed live activity: the busy status line shows the friendly action ("📖 อ่านไฟล์ …", "`$ npm test`") instead of the raw tool name; expanded tool-trail height is bounded so big diffs can't push the prompt off-screen; scrollback renders past turns compact.
+
+**Dashboard**
+
+- Security: fixed directory traversal in the file API (path confinement now uses a real path boundary, not a string prefix).
+- Web terminal: the agent run is cancelled when the browser disconnects; the raw-shell websocket is guarded against uncaught-error crashes.
+
+**Installer**
+
+- `install.ps1` checks the install exit code — no more false "Sanook CLI installed" banner when `npm install -g` fails.
+
 ## 0.5.7
 
 ### Local token usage ledger (ccusage-style)

package/README.md

@@ -1,41 +1,199 @@
-<div align="center">
+<p align="center">
+  <br />
+  <strong>Sanook CLI</strong>
+  <br />
+  <br />
+  <em>The terminal AI coding agent with a memory that outlives the session.</em>
+  <br />
+  <br />
+  <sub>Bring your own key · 9 providers · MCP · Obsidian second brain · gateway & cron</sub>
+  <br />
+  <br />
+  🇹🇭 <a href="README.th.md">อ่านภาษาไทย</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sanook-cli"><img src="https://img.shields.io/npm/v/sanook-cli.svg?style=flat-square&color=111827&labelColor=1f2937" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sanook-cli"><img src="https://img.shields.io/npm/dm/sanook-cli.svg?style=flat-square&color=111827&labelColor=1f2937" alt="downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-22c55e?style=flat-square&labelColor=1f2937" alt="license" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A5%2022-339933?style=flat-square&labelColor=1f2937&logo=node.js&logoColor=white" alt="node" /></a>
+  <a href="#development"><img src="https://img.shields.io/badge/tests-passing-22c55e?style=flat-square&labelColor=1f2937" alt="tests" /></a>
+  <a href="https://github.com/Sir-chawakorn/sanook-cli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Sir-chawakorn/sanook-cli/ci.yml?style=flat-square&labelColor=1f2937" alt="CI" /></a>
+</p>
 
-# Sanook CLI
+---
 
-**The open-source terminal AI coding agent that remembers across sessions.**
+<h2 align="center" id="install">Install Sanook CLI</h2>
 
-Bring your own key · 9 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.
+<p align="center">
+  <strong>Pick one command below — all roads lead to <code>sanook</code>.</strong><br/>
+  <sub>Requires <strong>Node.js ≥ 22</strong> &nbsp;·&nbsp; <code>node -v</code> to check &nbsp;·&nbsp; <code>npx sanook doctor</code> auto-fixes PATH / Node issues</sub>
+</p>
 
-🇹🇭 [อ่านภาษาไทย](README.th.md)
+<p align="center">
+  <img src="https://img.shields.io/badge/npm-✅_Ready-22c55e?style=for-the-badge&labelColor=14532d" alt="npm ready" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/curl_|_bash-✅_Ready-22c55e?style=for-the-badge&labelColor=14532d" alt="curl ready" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/Homebrew-✅_Ready-22c55e?style=for-the-badge&labelColor=14532d" alt="homebrew ready" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/GitHub_Pages-✅_Ready-22c55e?style=for-the-badge&labelColor=14532d" alt="pages ready" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/WinGet-⏳_PR_pending-f59e0b?style=for-the-badge&labelColor=78350f" alt="winget pending" />
+  &nbsp;
+  <img src="https://img.shields.io/badge/sanook.ai-⏳_DNS_pending-94a3b8?style=for-the-badge&labelColor=334155" alt="sanook.ai pending" />
+</p>
 
-[![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-passing-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)
+<br />
 
-[Quickstart](#quickstart) · [Providers](#providers) · [Usage](#usage) · [Gateway](#gateway--scheduling) · [Skills](#skills) · [MCP](#mcp) · [Security](#security)
+<table width="100%">
+<tr>
+<td width="50%" valign="top">
 
-<!-- 📹 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) -->
+### 🍎 macOS · 🐧 Linux · WSL
+
+**Recommended — npm**
+
+```bash
+npm install -g sanook-cli
+# or run once without installing:
+npx sanook-cli
+```
+
+**One-liner install script** *(checks Node, then installs via npm)*
+
+```bash
+# GitHub raw (default)
+curl -fsSL https://raw.githubusercontent.com/Sir-chawakorn/sanook-cli/main/scripts/install.sh | bash
+
+# GitHub Pages mirror
+curl -fsSL https://sir-chawakorn.github.io/sanook-cli/install.sh | bash
+
+# jsDelivr CDN
+curl -fsSL https://cdn.jsdelivr.net/gh/Sir-chawakorn/sanook-cli@main/scripts/install.sh | bash
+```
+
+**Homebrew**
+
+```bash
+brew trust Sir-chawakorn/tap    # once on newer Homebrew
+brew tap Sir-chawakorn/tap
+brew install sanook-cli
+```
+
+</td>
+<td width="50%" valign="top">
+
+### 🪟 Windows
+
+**Recommended — npm** *(PowerShell or cmd)*
+
+```powershell
+npm install -g sanook-cli
+# or:
+npx sanook-cli
+```
+
+**One-liner install script**
+
+```powershell
+# GitHub raw (default)
+irm https://raw.githubusercontent.com/Sir-chawakorn/sanook-cli/main/scripts/install.ps1 | iex
+
+# GitHub Pages mirror
+irm https://sir-chawakorn.github.io/sanook-cli/install.ps1 | iex
+```
+
+**WinGet** *(after [PR #391114](https://github.com/microsoft/winget-pkgs/pull/391114) merges)*
+
+```powershell
+winget install Sanook.SanookCLI
+```
+
+Portable zip (no WinGet yet): [sanook-cli-win-x64.zip](https://github.com/Sir-chawakorn/sanook-cli/releases/download/v0.5.7/sanook-cli-win-x64.zip)
+
+</td>
+</tr>
+</table>
 
-</div>
+<br />
+
+<details open>
+<summary><strong>📋 All install methods — status &amp; links</strong></summary>
+
+| Method | Command | Status |
+|--------|---------|--------|
+| **npm / npx** | `npm install -g sanook-cli` | ✅ [npm](https://www.npmjs.com/package/sanook-cli) · latest **0.5.7** |
+| **curl \| bash** | `curl -fsSL …/install.sh \| bash` | ✅ [raw](https://raw.githubusercontent.com/Sir-chawakorn/sanook-cli/main/scripts/install.sh) · [Pages](https://sir-chawakorn.github.io/sanook-cli/install.sh) · [jsDelivr](https://cdn.jsdelivr.net/gh/Sir-chawakorn/sanook-cli@main/scripts/install.sh) |
+| **irm \| iex** | `irm …/install.ps1 \| iex` | ✅ [raw](https://raw.githubusercontent.com/Sir-chawakorn/sanook-cli/main/scripts/install.ps1) · [Pages](https://sir-chawakorn.github.io/sanook-cli/install.ps1) |
+| **Homebrew** | `brew tap Sir-chawakorn/tap && brew install sanook-cli` | ✅ [homebrew-tap](https://github.com/Sir-chawakorn/homebrew-tap) |
+| **GitHub Pages** | `curl -fsSL https://sir-chawakorn.github.io/sanook-cli/install.sh \| bash` | ✅ Live |
+| **WinGet** | `winget install Sanook.SanookCLI` | ⏳ [PR #391114](https://github.com/microsoft/winget-pkgs/pull/391114) · CLA signed · [release zip](https://github.com/Sir-chawakorn/sanook-cli/releases/tag/v0.5.7) ready |
+| **sanook.ai** *(optional short URL)* | `curl -fsSL https://sanook.ai/install.sh \| bash` | ⏳ DNS at GoDaddy → run `bash scripts/configure-sanook-ai-dns.sh` |
+
+Full maintainer guide: **[docs/INSTALL_INFRA.md](docs/INSTALL_INFRA.md)**
+
+</details>
+
+<br />
+
+> **Troubleshooting**
+>
+> | Symptom | Fix |
+> |---------|-----|
+> | `'sanook' is not recognized` | You ran `npm i sanook-cli` without `-g` — reinstall with `npm install -g sanook-cli`, or use `npx sanook` |
+> | Node too old | Install [Node ≥ 22](https://nodejs.org) · scripts refuse older versions |
+> | Homebrew refuses tap | Run `brew trust Sir-chawakorn/tap` once, then retry |
+> | Not sure what's wrong | `npx sanook doctor` — prints OS-specific fixes (incl. Windows PATH one-liner) |
+
+<br />
+
+<p align="center">
+  <a href="#quickstart"><strong>First run → setup wizard &amp; API key</strong></a>
+</p>
 
 ---
 
+<p align="center">
+  <a href="#install"><strong>Install</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#quickstart"><strong>Quickstart</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#memory--second-brain"><strong>Memory</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#persona"><strong>Persona</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#dashboard"><strong>Dashboard</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#providers"><strong>Providers</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#usage"><strong>Usage</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#gateway--scheduling"><strong>Gateway</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#mcp"><strong>MCP</strong></a>
+  &nbsp;·&nbsp;
+  <a href="#security"><strong>Security</strong></a>
+</p>
+
+<!-- 📹 DEMO GIF — record the close-session → reopen → "it remembered" loop (asciinema + agg), save to docs/demo.gif, then uncomment: -->
+<!-- <p align="center"><img src="docs/demo.gif" alt="sanook-cli demo" width="720" /></p> -->
+
+<br />
+
 ## Overview
 
-Sanook is a small, transparent coding agent for your terminal. At its heart is a single loop —
+> **Close the terminal. Come back tomorrow. Sanook still knows what you decided.**
 
-```
+Sanook is a transparent coding agent for your terminal — one loop, no magic:
+
+```text
 prompt → LLM → tool call → result → loop → answer
 ```
 
-— wrapped with everything that makes it usable for real work: a permission gate, a memory the agent writes itself, a long-running gateway with cron and chat channels, on-demand skills, MCP servers, and first-class git awareness.
+Wrapped in the things real work needs: a permission gate, **structured memory across sessions**, a long-running gateway with cron and chat channels, on-demand skills, MCP servers, and first-class git awareness.
 
-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.
+**BYOK by design.** Every provider uses a **direct API key from that provider's console** — Sanook never reuses OAuth or subscription credentials, because that violates provider terms and gets accounts banned.
 
 ## How it compares
 
@@ -57,22 +215,155 @@ The agent loop, BYOK, and MCP are table stakes now. What Sanook has that the big
 
 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
+## Memory & second brain
+
+Sanook does **not** dump everything into one folder. Memory is layered — some lives in your Obsidian vault, some in `~/.sanook/` for speed and resume. Both are wired together at runtime.
+
+```mermaid
+flowchart LR
+  START([Start<br/>sanook / gateway / cron / resume]):::start
+  CFG["Load config<br/>~/.sanook/config.json"]:::local
+  MODE{"brainPath is set<br/>and vault is reachable?"}:::gate
+  LOCALONLY([Fallback end<br/>answer works with local session + usage only]):::warn
+
+  subgraph read["1. Read path · gather memory before the turn"]
+    direction TB
+    HIER["Hierarchical SANOOK.md<br/>global -> repo -> cwd instructions"]:::inject
+    AM["Auto-memory<br/>~/.sanook/memory/memory.json"]:::local
+    RESUME["Resume context<br/>~/.sanook/sessions/*.json"]:::local
+    HOT["Vault hot files<br/>AI-Context-Index + current-state + inbox"]:::vault
+    PROJECT["Project hot context<br/>Projects/&lt;slug&gt;/ matched from cwd"]:::vault
+    PACK["Context pack<br/>Shared/Context-Packs/*.md selected by task"]:::vault
+    SEARCH["Per-turn retrieval<br/>search/index.json over vault + memory + sessions + skills"]:::local
+  end
+
+  subgraph inject["2. Injection · build the model input"]
+    direction TB
+    STATIC["Static brain block<br/>stable context injected at session start"]:::inject
+    RECALLED["Recalled context block<br/>fresh matches for this prompt"]:::inject
+    SYS["System prompt<br/>policy + tools + memory + repo state"]:::inject
+    USER["User prompt<br/>or incoming gateway message"]:::process
+  end
+
+  subgraph loop["3. Agent loop · act, observe, answer"]
+    direction TB
+    LLM["LLM reasoning step"]:::process
+    NEED{"Need tools?"}:::gate
+    TOOLS["Tool calls<br/>files, shell, git, MCP, skills"]:::process
+    RESULT["Tool results<br/>fed back into context"]:::process
+    ANSWER["Final answer<br/>terminal or gateway reply"]:::finish
+  end
+
+  subgraph write["4. Write-back · make the next session smarter"]
+    direction TB
+    REMEMBER["remember tool<br/>redact -> merge -> rank"]:::write
+    MEMJSON["Persist auto-memory<br/>memory.json + MEMORY.md mirror"]:::write
+    INBOX["Append candidate fact<br/>Shared/Memory-Inbox/memory-inbox.md"]:::write
+    WORKLOG["Append daily worklog<br/>Sessions/YYYY-MM-DD-worklog.md"]:::write
+    CHAT["Append full transcript<br/>Sessions/*-chat.md when enabled"]:::write
+    SESSION["Save session JSON<br/>~/.sanook/sessions/*.json"]:::write
+    USAGE["Record usage<br/>~/.sanook/usage/events.jsonl"]:::write
+    INDEX["Re-index changed sources<br/>sanook index -> search/index.json"]:::write
+    END([End<br/>answer returned + memory ready for resume/retrieval]):::finish
+  end
+
+  START -->|entrypoint starts| CFG
+  CFG --> MODE
+  MODE -->|yes| HOT
+  MODE -->|no vault path| LOCALONLY
+  CFG --> AM
+  CFG --> RESUME
+  CFG --> SEARCH
+  HIER --> STATIC
+  AM --> STATIC
+  HOT --> STATIC
+  PROJECT --> STATIC
+  PACK --> RECALLED
+  RESUME --> RECALLED
+  SEARCH --> RECALLED
+  STATIC --> SYS
+  RECALLED --> SYS
+  USER --> LLM
+  SYS -->|injected every turn| LLM
+  LLM --> NEED
+  NEED -->|yes| TOOLS
+  TOOLS --> RESULT
+  RESULT --> LLM
+  NEED -->|no| ANSWER
+  LLM -->|durable fact found| REMEMBER
+  REMEMBER --> MEMJSON
+  REMEMBER --> INBOX
+  ANSWER --> WORKLOG
+  ANSWER --> CHAT
+  ANSWER --> SESSION
+  ANSWER --> USAGE
+  MEMJSON --> INDEX
+  INBOX --> INDEX
+  WORKLOG --> INDEX
+  CHAT --> INDEX
+  SESSION --> INDEX
+  ANSWER --> END
+
+  classDef start fill:#064e3b,stroke:#34d399,color:#ffffff,stroke-width:3px
+  classDef finish fill:#0f766e,stroke:#5eead4,color:#ffffff,stroke-width:3px
+  classDef gate fill:#7c2d12,stroke:#fdba74,color:#ffffff,stroke-width:2px
+  classDef local fill:#172554,stroke:#60a5fa,color:#ffffff
+  classDef vault fill:#312e81,stroke:#a78bfa,color:#ffffff
+  classDef inject fill:#164e63,stroke:#22d3ee,color:#ffffff
+  classDef process fill:#1f2937,stroke:#94a3b8,color:#ffffff
+  classDef write fill:#78350f,stroke:#fbbf24,color:#ffffff
+  classDef warn fill:#7f1d1d,stroke:#fca5a5,color:#ffffff,stroke-width:2px
+```
 
-Install **globally** — the `-g` is required (needs **Node ≥ 22**; check with `node -v`):
+**How to read the flow:** green nodes mark start/end, orange diamonds are decisions, blue nodes are local runtime state, purple nodes live inside the Obsidian-style vault, cyan nodes are injected into the system prompt, dark nodes are the active agent loop, amber nodes write memory back after/during the turn, and the red node is the safe fallback when no vault is configured.
+
+### What goes where
+
+| Data | Stored at | When | Purpose |
+|---|---|---|---|
+| **Worklog** | `{brainPath}/Sessions/YYYY-MM-DD-worklog.md` | After every agent turn (REPL + headless) | Daily trace of prompts & cost summary |
+| **Full transcript** *(opt-in)* | `{brainPath}/Sessions/YYYY-MM-DD-<id>-chat.md` | After every turn, when `brainTranscript` is on | The actual conversation — your prompt **and** the AI's reply |
+| **Session note** | `{brainPath}/Sessions/YYYY-MM-DD-<id>-session.md` | On REPL exit (`/quit` or Ctrl+C at empty prompt) | AI/heuristic summary + key facts |
+| **Memory inbox** | `{brainPath}/Shared/Memory-Inbox/memory-inbox.md` | When the agent calls `remember` | Candidate facts for vault curation |
+| **Project workspace** | `{brainPath}/Projects/<slug>/` | Setup wizard / `sanook brain init` links your repo | Project-scoped notes & hot context |
+| **Persona profile** | `{brainPath}/Shared/User-Persona/persona.md` | `sanook persona` or `/persona` in REPL | Who you are + how you want the agent to work |
+| **Auto-memory** | `~/.sanook/memory/memory.json` | When the agent calls `remember`, or `sanook persona` (protected) | Structured facts (merge, rank, inject) |
+| **Session JSON** | `~/.sanook/sessions/*.json` | Every turn | `--continue` / `--resume` transcript |
+| **Search index** | `~/.sanook/search/` | `sanook index` (incremental) | BM25 / hybrid retrieval |
+| **Usage ledger** | `~/.sanook/usage/events.jsonl` | Every turn | Token/cost tracking — **not** semantic memory |
+
+**Read at session start:** hierarchical `SANOOK.md` (global → project root → cwd), auto-memory block, vault hot files (`AI-Context-Index`, `current-state`, inbox, matched `Projects/<slug>/`), plus per-turn retrieval over vault + memory + past sessions.
+
+**Setup links your repo to the vault:** the first-run wizard (or `sanook brain init`) saves `brainPath` in `~/.sanook/config.json`, scaffolds `Projects/<slug>/` inside the vault, and creates `SANOOK.md` in your repo if missing.
 
 ```bash
-npm install -g sanook-cli
+sanook brain init                  # pick vault folder + identity
+sanook brain context               # inspect what gets injected from cwd
+sanook brain projects list         # vault projects ↔ repo paths
+sanook memory stats                # auto-memory store overview
+sanook usage daily                 # token/cost ledger (ccusage-style)
 ```
 
-> ⚠️ **`'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).
+**Want the entire conversation in your vault?** Turn on full transcripts — every prompt and reply is appended to `Sessions/*-chat.md` per session:
+
+```bash
+sanook config set brainTranscript on   # or env: SANOOK_BRAIN_TRANSCRIPT=1
+```
+
+> It is **opt-in** because verbatim transcripts of long coding sessions grow a vault fast. Worklog (always on) keeps a lighter daily trace; the full transcript is the complete record.
+
+Disable persistence: `SANOOK_DISABLE_PERSISTENCE=1` · worklog only: `SANOOK_DISABLE_WORKLOG=1` · usage ledger: `SANOOK_DISABLE_USAGE=1`
+
+## Quickstart
+
+Already installed? Jump straight to setup — see **[Install](#install)** if you haven't yet.
 
 Run the setup wizard or set an API key manually:
 
 ```bash
 sanook setup                    # provider + model wizard; offers to create a second brain
 sanook model                    # re-run provider/model setup later
+sanook persona                  # tell the agent who you are + how you like to work
 sanook auth add anthropic --api-key sk-ant-... --use
 
 export ANTHROPIC_API_KEY=sk-ant-...        # macOS / Linux
@@ -106,7 +397,7 @@ sanook dump                     # support snapshot; raw secrets are never printe
 | **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`), `--continue` resumes the latest run for the current project, `--resume <id>` resumes a specific run, and `sanook sessions` audits/exports/renames/prunes saved conversations. |
+| **Memory** | Layered memory: `remember` / `recall`, hierarchical `SANOOK.md`, Obsidian vault injection, per-turn retrieval, `--continue` / `--resume`, session notes on exit, daily worklogs, and `sanook memory` / `sanook usage` inspect commands. |
 | **Familiar CLI surfaces** | `sanook setup`, `sanook model`, `sanook auth`, `sanook chat -q`, `sanook gateway`, `sanook status`, `sanook sessions`, `sanook dump`, `sanook tools`, and `sanook send` provide familiar management entry points, all Sanook-branded. |
 | **Startup cockpit** | The interactive REPL opens with a Sanook-branded wordmark, service routes (Code, Brain, Connect, Ship), and live readiness signals for second-brain, MCP servers, installed skills, and the current git branch. |
 | **Web grounding** | `sanook web status` separates local brain search from true internet search, detects configured MCP web/search/fetch candidates, and prints Sanook's citation + prompt-injection policy for current external facts. |
@@ -124,6 +415,46 @@ sanook dump                     # support snapshot; raw secrets are never printe
 | **Prompt budget inspectability** | `sanook prompt-size [--json]` reports the offline size of Sanook's system prompt, personality overlay, auto-memory, skills index, second-brain context, project memory, repo map, git context, and built-in tool schemas. |
 | **Polyglot runtime surface** | `sanook runtimes [--json]` shows optional Python/Rust readiness. The agent gets `run_python` for data/document/ML-style helper scripts and `run_rust` for small performance/safety-critical helpers, both approval-gated and no-shell. |
 | **Second brain** | `sanook brain init` scaffolds a structured Obsidian "second-brain" workspace (folders + `_Index` + a portable AI operating constitution) for organising work and giving the agent durable, cross-session memory. |
+| **Self-improvement** | Sanook watches for repeated tasks and, past a threshold, **auto-authors a skill** for the pattern — announced in the terminal and surfaced on the Dashboard. Tune with `SANOOK_SELF_IMPROVE_THRESHOLD`; disable with `SANOOK_DISABLE_SELF_IMPROVE=1`. |
+| **Persona** | `sanook persona` runs a short questionnaire (who you are, language, tone, autonomy, stack, preferences) and stores the answers as **protected memory** plus a vault profile so every session starts in context. |
+
+## Persona
+
+Teach the agent who you are once, and it carries that context into every session — name, language, tone, autonomy, your stack, and what you like (or don't like) it to do.
+
+```bash
+sanook persona                  # short questionnaire (A/B/C/D + free-text)
+# or /persona inside the REPL — pre-fills from existing profile
+```
+
+A mix of multiple-choice and free-text questions. Answers are saved in two places, wired into the agent automatically:
+
+- **Auto-memory** (`~/.sanook/memory/memory.json`) as **protected, owner-trust facts** — injected at the start of every run, so the agent immediately knows how to address you and how you want it to work.
+- **Second brain** (`{brainPath}/Shared/User-Persona/persona.md`) as a readable profile note you can edit by hand — written only when a vault exists.
+
+Re-run any time to update; existing answers are **pre-filled** from `persona.md` and protected memory. Blanks are skipped, and the vault profile is rewritten in place. The brain wizard (`sanook brain init`) already seeds a lighter identity (name + AI name + autonomy); `sanook persona` is the deeper, standalone pass.
+
+## Dashboard
+
+A local, Hermes-style admin panel for everything the CLI knows — open it in a browser and drive Sanook without leaving the page.
+
+```bash
+sanook dashboard                # http://127.0.0.1:9119
+sanook dashboard --port 8080
+```
+
+| Page | What it shows |
+|---|---|
+| **Terminal** | A real web terminal — an **Agent console** (the Sanook REPL, streamed over SSE with live tool activity + color-coded diffs) and an optional **Raw shell** (a system PTY via `xterm.js`, enabled when the `node-pty` + `ws` optional deps are installed). |
+| **Skills** | Built-in and installed skills, including the ones Sanook auto-authored from repeated tasks. |
+| **Memory** | Your structured auto-memory facts (incl. persona) with tier/trust. |
+| **Persona** | Your saved persona profile (`sanook persona` / `/persona`) — view answers and profile path. |
+| **Usage** | Token/cost ledger, daily/weekly/monthly. |
+| **Self-improve** | The task ledger — what's repeating and which skills were created. |
+| **Install** | The multi-platform install commands (see [Quickstart](#quickstart)), with copy buttons. |
+| **Sessions · Models · Files · Logs · Cron · Channels · Config · MCP · Brain** | Inspect and manage the same surfaces as the CLI. |
+
+It binds to **loopback only** and reads the same `~/.sanook/` state as the CLI, so the Dashboard and terminal always agree.
 
 ## Providers
 
@@ -159,6 +490,8 @@ sanook chat -q "<query>" direct one-shot query
 sanook                   interactive REPL
 sanook setup [section]   setup model/gateway/tools/agent/brain
 sanook model             choose provider + model
+sanook persona           questionnaire → durable persona (memory + second brain)
+sanook dashboard [--port] local web admin UI (terminal, skills, memory, usage, install)
 sanook status            redacted install/config status
 sanook auth list         redacted provider key status
 sanook auth add openai --api-key <key> [--use]
@@ -170,6 +503,7 @@ sanook sessions stats [--all]
 sanook sessions prune --keep N [--all] [--yes]
 sanook sessions rm <id>
 sanook dump [--show-keys] support dump (keys are still redacted)
+sanook usage [daily|weekly|monthly|session] [--days N] [--json]
 sanook prompt-size [--json] inspect system/brain/skill/tool context budget
 sanook runtimes [--json]   inspect optional Python/Rust runtime surface
 sanook web status [--json] inspect true web-search/fetch readiness
@@ -424,16 +758,20 @@ sanook skill remove my-skill
 
 ## Second brain
 
-Scaffold a structured [Obsidian](https://obsidian.md) workspace for organising your work and giving the agent a durable, cross-session memory:
+Scaffold a structured [Obsidian](https://obsidian.md) workspace — the durable layer Sanook reads and writes alongside `~/.sanook/`:
 
 ```bash
 sanook brain init                  # interactive — asks where + a few identity questions
 sanook brain init ~/notes/brain    # non-interactive (with --yes)
 ```
 
-It creates a full folder taxonomy (`Projects/`, `Sessions/`, `Shared/` memory layer, `Goals/`, `Research/`, `Skills/`, …), an `_Index.md` in every folder, seed memory files, and a portable AI **operating constitution** (`CLAUDE.md` / `GEMINI.md` / `AGENTS.md` / `SANOOK.md`) so any AI agent works with the vault consistently. It ships with research-backed operating rules — context-assembly (anti context-rot), an intake quarantine + injection-scan gate, bi-temporal fact validity, provenance tracking, a verification-gated `Skills/` library, and sleep-time consolidation. The first-run setup wizard also offers to create one.
+The wizard creates a full folder taxonomy (`Projects/`, `Sessions/`, `Shared/` memory layer, `Goals/`, `Research/`, `Skills/`, …), an `_Index.md` in every folder, seed memory files, and a portable AI **operating constitution** (`CLAUDE.md` / `GEMINI.md` / `AGENTS.md` / `SANOOK.md`). It ships with research-backed operating rules — context-assembly (anti context-rot), an intake quarantine + injection-scan gate, bi-temporal fact validity, provenance tracking, a verification-gated `Skills/` library, and sleep-time consolidation.
+
+**Every folder documents its own job.** Each folder gets a generated `_Index.md` stating its role, what goes there, what doesn't, and an AI routing contract — and a top-level `Vault Structure Map.md` lists the whole taxonomy in one place. So both you and the agent always know where a note belongs. Identity lives in `Shared/User-Persona/` (see [Persona](#persona)); what the agent learns over time lives in `Shared/User-Memory/`.
 
-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.
+**Create-if-missing** — re-running never overwrites your notes. On init, Sanook also links your current repo (`Projects/<slug>/` + `SANOOK.md`) and can wire a filesystem MCP server so the agent reads and writes the vault directly.
+
+See [Memory & second brain](#memory--second-brain) for the exact routing table (worklog, session notes, inbox, auto-memory, sessions).
 
 ### Brain search
 
@@ -503,16 +841,19 @@ sanook trust remove
 Everything lives under `~/.sanook/` (with per-project `.sanook/` overrides where relevant):
 
 ```
+~/.sanook/config.json        brainPath, model, tuning knobs
 ~/.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/memory/            auto-memory store (memory.json + MEMORY.md view)
+~/.sanook/usage/             token/cost ledger (events.jsonl)
+~/.sanook/search/            brain-search index + optional embedding vectors
 ~/.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)
+~/.sanook/trusted-projects.json
+SANOOK.md                    project memory (hierarchical, cwd → project root → global)
+{brainPath}/                 your Obsidian vault — worklogs, session notes, Projects/, Shared/
 ```
 
 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.
@@ -530,6 +871,7 @@ Quality-neutral knobs in `~/.sanook/config.json` (or the matching `SANOOK_*` env
 | — | `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) |
 | `embeddingModel <spec>` | `SANOOK_EMBEDDING_MODEL=<spec>` | model used for semantic search embeddings (for example `openai:text-embedding-3-small`) |
+| `brainTranscript on` | `SANOOK_BRAIN_TRANSCRIPT=1` | append the **full conversation** (prompt + reply, every turn) to `{brainPath}/Sessions/*-chat.md` (default off) |
 | `thinking on` / `thinking 4000` | `SANOOK_THINKING=on` / `4000` | opt-in Anthropic extended thinking on the main agent; use `on`, `true`, or `yes` for the default budget, `off`, `false`, or `no` to disable, or a positive integer for `budgetTokens` |
 
 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.
@@ -544,6 +886,7 @@ SANOOK_HOOKS_INHERIT_ENV=1          # pass full env to hooks instead of a minima
 SANOOK_DISABLE_PERSISTENCE=1        # do not save sessions, memory, prompt history, or worklogs
 SANOOK_DISABLE_UPDATE_CHECK=1       # do not show interactive update prompts
 SANOOK_DISABLE_WORKLOG=1            # do not append second-brain worklogs
+SANOOK_DISABLE_USAGE=1              # do not append token/cost usage events
 SANOOK_TRUST_PROJECT=1              # temporary trust override for project .sanook extensions
 ```
 
@@ -590,12 +933,19 @@ CI runs the suite across macOS / Linux / Windows on Node 22 and 24. Requires **N
 
 ---
 
-<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>
+<p align="center">
+  <br />
+  <strong>Built by <a href="https://www.facebook.com/sanookai">Sanook AI</a></strong>
+  <br />
+  <sub>AI tools & education · 🇹🇭</sub>
+  <br />
+  <br />
+  <a href="https://www.facebook.com/sanookai">Facebook</a>
+  &nbsp;·&nbsp;
+  <a href="https://x.com/sanook_ai">X / Twitter</a>
+  <br />
+  <br />
+  <sub>TypeScript · Vercel AI SDK · no framework, no magic</sub>
+  <br />
+  <br />
+</p>