@pithosai/pithosai 1.0.7 → 1.0.32

package/README.md

@@ -1,198 +1,485 @@
 # Pithosai (`@pithosai/pithosai`)
 
-**Multi-role AI CLI** for coding and product work: natural-language requests, pluggable models (Cursor, DeepSeek, OpenRouter), and role-based prompts stored in SQLite.
+**Multi-role AI CLI** for coding and product work: natural-language requests, pluggable models (DeepSeek, China direct APIs, OpenRouter, Ollama, Krouter/Kiro, Cursor), and role-based prompts stored in SQLite.
 
----
+**Current release: 1.0.32** — see [What's new](#whats-new-v107--v1032) and [`CHANGELOG.md`](CHANGELOG.md#1032---2026-09-22).
 
-## What's new in v1.0.7
+| | |
+|---|---|
+| **Best for** | Agent-style coding, multi-role workflows (RD / PM / QA / …), local or cloud models, repeatable prompts from a local database |
+| **Requirements** | **Node.js ≥ 22.19** and **at least one** [model provider](#model-providers) |
+| **License** | Proprietary — see [License](#license) |
 
-**Models and cost**
+---
 
-- **Cost-first default:** with **`DEEPSEEK_API_KEY`**, regular runs use **`deepseek-v4-flash`**; **`--pro`** uses **`deepseek-v4-pro`**; **`--reasoner`** uses the pro model with reasoning enabled; **`--chat`** explicitly selects flash.
-- **Interactive `/model`** lists and switches available model keys.
-- **Aliases:** `deepSeekPro` → `deepSeekCoder`, `deepSeekFlash` → `deepSeekChat` (older keys still work).
-- **Native DeepSeek chat/coder:** requests send **`thinking: { type: "disabled" }`** so the provider’s default [thinking mode](https://api-docs.deepseek.com/guides/thinking_mode) does not force **`reasoning_content`** replay on tool-heavy turns (avoids **400** API errors). **`deepSeekReasoner`** is unchanged (thinking stays on).
+## Installation
 
-**CLI and install**
+```bash
+npm install -g @pithosai/pithosai
+```
 
-- **Optional startup auto-upgrade:** checks npm for a newer **`@pithosai/pithosai`** (at most **once per 24 hours**, state in **`~/.pithosai/auto-upgrade-check.json`**), can install **`@latest`** globally, uses the **same resolved CLI language** as help and prompts, and reminds you the **current process is still the old build** until you run `pithosai` again. In a **TTY** when the full-screen agent TUI will start, it **waits for Enter** so upgrade lines are not lost. Set **`PITHOSAI_AUTO_UPGRADE=0`** (or `false` / `no` / `off`) to disable checks entirely.
-- **`render-markdown`:** the built **`dist/render-markdown.mjs`** entry is fixed so direct execution prints output correctly.
+On a global install, if `~/.pithosai/pithosai.db` does not exist, it is created from the bundled schema. Override the path with `PITHOSAI_DB_PATH`. The first CLI start seeds built-in role templates when `pithosai_role_prompts` is empty (**1.0.31**), so `pithosai init` is not required.
 
-**Interactive REPL**
+Encrypted storage uses `@journeyapps/sqlcipher@5.3.1` (prebuilds for Windows, macOS including Apple Silicon, and Linux). If the native module fails to load, storage falls back to plaintext `better-sqlite3`.
 
-- Exit with **`/exit`** or **`/quit`** only; plain `exit` / `quit` are sent to the agent as normal messages.
+**Highlights**
 
-**Earlier in v1.0.5:** Encrypted global DB migration, device-bound SQLCipher keys, safer default logging — see **CHANGELOG** `[1.0.5]` and the upgrade subsection below.
+- **DeepSeek V4** — Cost-first `deepseek-v4-flash` by default; `--pro` and `--reasoner` for harder work ([details](#deepseek-api-v4)).
+- **China-mainland models (1.0.12)** — Kimi Code, Moonshot, MiniMax, Z.ai, Xiaomi via direct API keys; Qwen, Baidu, StepFun, and more via OpenRouter when no direct key is set.
+- **Global OpenRouter models (1.0.15)** — Anthropic, OpenAI, Google, Meta, Mistral, and more from the OpenRouter catalog, all via `OPENROUTER_API_KEY`. Reasoning models (Claude Sonnet 4, Claude Opus 4, o3, o4-mini, …) get proper thinking format and developer-role compat automatically ([details](#model-providers), [`src/models/README.md`](src/models/README.md)).
+- **Role shortcuts** — `rdsai`, `pmsai`, `qasai`, `cosai`, `mktai`, `wrsai` preset role and model defaults.
+- **Full-screen TUI** — Transcript, tool output, slash commands (`/model`, `/shell`, `/list`, skills, `/image`, …), and `@` file/path completion. **Enter** submits; **Shift+Enter** (or **Ctrl+J**) inserts a newline in the input box. Long first-line input wraps inside the frame instead of disappearing under the right border (**1.0.29**). After submit, the transcript shows `You:` once; cwd lives on the footer line, not as a second `cwd …` / `request: …` echo (**1.0.18**).
+- **Virtual projects** — Switch workspaces from the REPL via `pithosai_virtual_project` in `pithosai.db` ([details](#virtual-projects)).
+- **Plan alignment** — `/grill-me` stress-tests a design one question at a time ([details](#plan-alignment-grill-me)).
+- **Run modes** — `agent` (full tools), `dialog` (read-only), `plan` (writes `<slug>-plan.md`).
+- **Local persistence** — Tasks and prompts in SQLCipher-backed SQLite; optional `pithosai migrate-db` from legacy plaintext DBs.
+- **Skills & email** — ClawHub-style skills in-session; `heartbeat` / `email-monitor` for IMAP-driven tasks.
 
 ---
 
-## Install
+## Quick start
+
+```bash
+export DEEPSEEK_API_KEY=sk-...   # or another provider below
+cd your-project
+pithosai "Describe what you want done"
+```
+
+| Invocation | Behavior |
+|------------|----------|
+| `pithosai -i` | Interactive session with no initial prompt |
+| `pithosai --no-interactive "…"` | Single run, then exit |
+| `pithosai --report-json ./last-run.json "…"` | Interactive or one-shot; report file written on `/exit` (interactive) or after run (`--no-interactive`) |
+| `pithosai --no-interactive --json "…"` | Single run + JSON report on stdout (script mode) |
+| `pithosai -C ./other-dir "…"` | Use a different project directory |
+| `/exit` or `/quit` | Leave the REPL (plain `exit` is sent to the agent) |
+
+Each run prints a short ASCII banner with the CLI version under it. Role prompts (IDENTITY, ABILITIES, AGENTS) load from the local database (`pithosai_role_prompts` in `~/.pithosai/pithosai.db`). An empty table is filled from the Role Market on startup, so you do not run `pithosai init` first. Per-project `.pithosai/<role>/` holds optional `memory.md` and sessions — not runtime role prompts. `pithosai init [dir]` remains an optional project scaffold.
+
+### Shell scripts (one-shot runs)
+
+Use `--no-interactive` for automation. One-shot runs stream assistant text without a stderr `Running…` spinner. The process exit code tells you whether the run succeeded:
 
-**Node.js ≥ 18.12** required.
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | Success |
+| `1` | Agent run failed (API error, timeout, etc.) |
+| `2` | Run stopped by user (Ctrl+S) |
+
+Optional machine-readable report:
 
 ```bash
-npm install -g @pithosai/pithosai
+# Write report to a file (success/failure, error, changed files)
+node pithosai.js -r PM -l zh --no-interactive \
+  --report-json ./last-run.json \
+  "Create the product spec"
+
+# Or print JSON to stdout (banner is skipped when --json is set; agent output is suppressed)
+report=$(node pithosai.js -r PM -l zh --no-interactive --json "Create spec")
+echo "$report" | jq -e '.[0].success' >/dev/null
 ```
 
-On a **global** install, the package runs a one-time step: if `~/.pithosai/pithosai.db` does not exist, it is created from the bundled schema. Override the path anytime with `PITHOSAI_DB_PATH`.
+Reports are always a **JSON array** — one element per agent run. One-shot mode writes `[{ ... }]`. Interactive mode with `--report-json` appends one object per turn (including after role switches) and writes the full array on `/exit` or `/quit`.
 
----
+Each run object includes `files.created`, `files.modified`, and `files.deleted` (hybrid git snapshot + write/edit tool tracking).
 
-## What you get
+In **interactive** sessions, `--report-json` is also supported: the report file is written once when you exit with `/exit` or `/quit`, and again when you switch roles with `/role <name>` (current runs are saved first, then the role changes).
 
-| You run | Purpose |
-|--------|---------|
-| `pithosai` | Main CLI: `init`, `migrate-db`, interactive agent, `task`, `heartbeat`, `skills`, `memorize`, and more. |
-| `rdsai`, `pmsai`, `qasai`, `cosai`, `mktai`, `wrsai` | Same CLI with a **default role** (e.g. RD, PM, QA). See [Role entrypoints and models](#role-entrypoints-and-models) below. |
-| `email-monitor` | Heartbeat / email-driven task loop (`heartbeat` bundle). |
-| `render-markdown` | Render Markdown files in the terminal. |
-| `init` | Manually initialize `~/.pithosai/pithosai.db` if needed (usually automatic after global install). |
+Example retry loop (one-shot script mode):
 
----
+```bash
+REPORT=$(mktemp)
+trap 'rm -f "$REPORT"' EXIT
+for attempt in 1 2 3; do
+  if node pithosai.js -r PM -l zh --no-interactive --report-json "$REPORT" "Create spec"; then
+    jq -r '.[0].files.created[]' "$REPORT"
+    break
+  fi
+  echo "retry $attempt: $(jq -r '.[0].error // .[0].status' "$REPORT")"
+done
+```
 
-## Choose a model provider
+### Git AI checkpoints
+
+If [`git-ai`](https://usegitai.com/docs/agents/add-your-agent) is installed and on `PATH`, pithosai checkpoints **`write`** / **`edit`** / **`read`** through JSON command hooks — not hardcoded in the agent wrapper. Git AI is an **external CLI** (`scripts/pithosai-git-ai-adapter.js`, published as the `pithosai-git-ai-adapter` bin), not an in-process core adapter. The bundled default is `src/agent/hooks/configs/git-ai.json`; override it with `~/.pithosai/hooks/git-ai.json` or `<project>/.pithosai/hooks/git-ai.json`. `{pithosaiCli:pithosai-git-ai-adapter}` expands to the shipped CLI (source `scripts/` or release `dist/`). `hookType` uses pithos names (`beforeToolExecute`, `afterToolExecute`; `postToolExecute` is an alias of `afterToolExecute`). Enabled by default; set `PITHOSAI_GIT_AI=0` (or `false` / `no` / `off`) to skip the adapter. Checkpoint failures are logged and never block the tool. `beforeToolExecute` commands that exit `2` do block the tool.
+
+Full hook types, JSON schema, CLI, and env vars: [`docs/hooks-usage.md`](docs/hooks-usage.md).
+
+```json
+{
+  "version": "v1",
+  "hooks": [
+    {
+      "name": "git-ai-before-tool",
+      "enabled": true,
+      "matcher": "^(write|edit|read)$",
+      "timeout": 30,
+      "hookType": "beforeToolExecute",
+      "command": "{pithosaiCli:pithosai-git-ai-adapter} checkpoint pre"
+    },
+    {
+      "name": "git-ai-after-tool",
+      "enabled": true,
+      "matcher": "^(write|edit|read)$",
+      "timeout": 30,
+      "hookType": "afterToolExecute",
+      "command": "{pithosaiCli:pithosai-git-ai-adapter} checkpoint post"
+    }
+  ]
+}
+```
 
-Configure **at least one** of:
+### Language
 
-1. **DeepSeek** — `export DEEPSEEK_API_KEY=sk-...`
+Default locale is **English**. Set per run with `--lang`, or rely on the shell `LANG`.
 
-2. **OpenRouter** — `export OPENROUTER_API_KEY=sk-or-...`
+```bash
+pithosai --lang zh "请解释这个错误"
+```
 
-3. **Ollama (local models)** — install Ollama on your machine, run a model, and set:
-   ```bash
-   export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1
-   ```
-   Example local setup:
-   ```bash
-   ollama run qwen2.5-coder:14b
-   export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1
-   ```
+Supported codes include `en`, `ar`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pt`, `zh`, and `zh-hant` (Traditional Chinese, fixed in **1.0.7**). Run `pithosai --help` for the full list.
 
-4. **Cursor CLI** (last resort)  
-   ```bash
-   curl https://cursor.com/install -fsS | bash
-   cursor-agent login
-   export CURSOR_MODEL=auto
-   ```
-   Use **`pithosai "your request" --cursor`** or set `CURSOR_MODEL`.
+### Natural-language command fallback (bash / zsh)
 
-**Precedence:** DeepSeek → Ollama (`OPENAI_LOCAL_API_BASE`) → OpenRouter → `CURSOR_MODEL` / `--cursor`.
+Source [`scripts/pithosai-nl-fallback.sh`](scripts/pithosai-nl-fallback.sh) so unknown shell commands that look like natural language (English, Chinese, …) run pithosai instead of dying as "command not found". The hook registers `command_not_found` (plus a pre-parse intercept in interactive zsh, and a `Ctrl-J` intercept in bash 4+); classification runs in Node (`lookpath` + `tinyld`, a 0–100 shell-command score, and when the score is below 50 an LLM that may answer only `shell` or `natural`):
 
-### DeepSeek API (V4)
+```bash
+# zsh (~/.zshrc) or bash 4+ (~/.bashrc) — from this repo:
+source /path/to/pithosai/scripts/pithosai-nl-fallback.sh
 
-When using **`DEEPSEEK_API_KEY`** (native `https://api.deepseek.com`), the CLI maps runs to **DeepSeek-V4** model ids:
+# After `npm run install:global` or `npm install -g` (script is copied into dist/):
+source "$(npm root -g)/@pithosai/pithosai/dist/pithosai-nl-fallback.sh"
+```
 
-| Your choice | API model id | Typical use |
-|-------------|----------------|-------------|
-| Default (e.g. `pithosai`, `rdsai`, no `--pro` / `--reasoner`) | **`deepseek-v4-flash`** | Lower-cost daily coding and regular tasks |
-| **`--pro`** | **`deepseek-v4-pro`** | Higher quality coding output for harder tasks |
-| **`--chat`** | **`deepseek-v4-flash`** | Explicit chat-style low-cost path |
-| **`--reasoner`** | **`deepseek-v4-pro`** with reasoning / thinking enabled | Longer chains-of-thought style replies |
+Then in the same terminal:
+
+```bash
+add tests for this file
+给这个文件添加测试
+```
+
+Those become:
+
+```bash
+pithosai --no-interactive --model krouter-rd "$input"
+```
+
+**Skipped** (normal `command not found`): first token is a real command on `PATH`, a path (`foo/bar`), a flag-like line (`foo --help`), a valid `for`/`if` one-liner, or a single-token typo (`gti`). Hyphens inside words or paths (`api-cettire-orders`) still go to pithosai. On this `command not found` path the typed line is never rewritten to `pithosai --no-interactive …` (only the interactive zsh Enter intercept and the bash `Ctrl-J` intercept rewrite it, and only in place).
+
+In **interactive zsh**, Enter is intercepted *before* parse so lines like `for these files: …` / `for thest files: …` go to pithosai instead of a keyword parse error. Real `PATH` commands (`git status`) still execute normally.
 
-Legacy ids **`deepseek-chat`** and **`deepseek-reasoner`** are being retired by the provider; see [DeepSeek API docs](https://api-docs.deepseek.com/) for current parameters (including thinking mode). For extended chain-of-thought on native DeepSeek, use **`--reasoner`** / **`deepSeekReasoner`**; the default flash/coder paths disable API thinking so agent tool loops stay reliable.
+**bash 4+**: plain Enter **cannot** be intercepted — bash consumes `\C-m` as the built-in `accept-line` before any `bind -x` macro runs, so the NL path is reached by pressing **`Ctrl-J`** at the end of an NL line instead of Enter. Lines that bash fails to *parse* (`for these files: show size`) also never reach `command_not_found`, so they cannot be recovered on plain Enter — use `Ctrl-J` for those. Lines that parse but name an unknown command (`list the files here`) still reach the NL fallback through `command_not_found` on plain Enter. Skipping a line through the `Ctrl-J` intercept also leaves real `PATH` commands and valid `for`/`if` one-liners to execute unchanged.
 
-With **`OPENROUTER_API_KEY`** only, the same logical paths use OpenRouter slugs **`deepseek/deepseek-v4-flash`** (default) and **`deepseek/deepseek-v4-pro`** (`--pro` / `--reasoner`).
+macOS system bash 3.2 has neither `command_not_found_handle` nor `bind -x`; use zsh or Homebrew bash.
 
-### Role entrypoints and models
+The intercept rewrites the pending readline line into the pithosai invocation and submits it on the same Ctrl‑J keypress via a two‑key readline macro: the shell handler (bound to `\C-x\C-p`) rewrites `READLINE_LINE`, then `\C-m` (`accept-line`) executes it; the handler never evaluates a command or spawns a terminal‑reading child, so `TAB` completion keeps working after an NL line.
 
-- **`rdsai`** — default role **RD**, default model path (**`deepseek-v4-flash`** unless you pass `--pro` / `--reasoner`).
-- **`pmsai`**, **`qasai`**, **`cosai`**, **`mktai`** — set role **PM** / **QA** / **CO** / **MKT** and pass **`--chat`**, so the **chat (flash)** model above is used for those binaries without extra flags.
-- **`wrsai`** — runs the **`task`** command with role **WR** and default language **zh** (model follows normal `task` / env resolution for that run).
+Classification needs **Node.js** on `PATH` (or `PITHOSAI_NODE`) and `nl-fallback-classify` next to the sourced script (`dist/nl-fallback-classify.mjs` after a build/global install, or `src/cli/shared/nl-fallback/nl-fallback-classify.js` when sourcing from this repo). When the heuristic shell-command score is below 50 but still uncertain (`foo bar baz`), the classifier asks the LLM (`RD` via Krouter by default, **1.0.32**) for exactly `shell` or `natural`. Clear natural-language lines (starters, reserved-keyword prose, questions, CJK, tinyld, or longer than **300 characters** / **200 words**) go to pithosai with no LLM call so Enter does not wait on the network. Overlong lines that still look like shell (path, flags, or a PATH command) keep normal shell handling. Requires bash **4+** (`command_not_found_handle`) or zsh (`command_not_found_handler`).
+
+| Variable | Role |
+|----------|------|
+| `PITHOSAI_NL_FALLBACK` | Disable all NL interception: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_ZLE` | Disable the zsh Enter / bash `Ctrl-J` intercept only: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_MODEL` | Agent model for matches (default `krouter-rd`) |
+| `PITHOSAI_NL_CLASSIFY_LLM` | Skip the classify LLM when shell-score is below 50: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_CLASSIFY_TIMEOUT_MS` | Classify LLM timeout in ms (default `4000`) |
+| `PITHOSAI_NL_CLASSIFY_MODEL` | Classify LLM id (default `RD`; if unset, uses `PITHOSAI_NL_MODEL`, and `krouter-rd` maps to `RD`) |
+| `PITHOSAI_NL_CLASSIFY_API_BASE` | Classify LLM base URL (default Krouter; also `KROUTER_API_BASE` / `KIRO_API_BASE`) |
+| `PITHOSAI_NL_CLASSIFY_API_KEY` | Classify LLM API key (optional; also `KROUTER_API_KEY` / `KIRO_API_KEY`) |
+| `PITHOSAI_NL_DEBUG_LOG` | Print classify/LLM/hook debug on stderr: `1` / `true` / `yes` / `on` |
+| `PITHOSAI_BIN` | pithosai binary (default `pithosai`) |
+| `PITHOSAI_LANG` | Override locale for hook messages and `--lang` |
+| `PITHOSAI_NODE` | Node binary for the classifier (default `node`) |
+
+Sourcing the hook in zsh sets `NO_NOMATCH` so punctuation like `?` in `hello, who are you?` is not treated as a glob (otherwise zsh prints `no matches found` and never calls the handler). Quote the line if a glob would match real files (`*`, `?`).
+
+### Upgrading from v1.0.4 (plaintext database)
+
+From **1.0.5** onward, plaintext databases migrate automatically when encryption is available, or you can run `pithosai migrate-db`. See [`CHANGELOG.md`](CHANGELOG.md) section **[1.0.5]**.
 
 ---
 
-## Quick start
+## Model providers
+
+Configure **at least one** of the following.
+
+| Provider | Setup |
+|----------|--------|
+| **DeepSeek** | `export DEEPSEEK_API_KEY=sk-...` |
+| **Kimi Code** | `export KIMI_API_KEY=sk-...` (pi-ai `kimi-coding`; e.g. `kimi-for-coding`) |
+| **Moonshot / Kimi platform** | `export MOONSHOT_API_KEY=sk-...` (pi-ai `moonshotai` / `moonshotai-cn`) |
+| **MiniMax** | `export MINIMAX_API_KEY=sk-...` and/or `export MINIMAX_CN_API_KEY=sk-...` |
+| **Z.ai (GLM)** | `export ZAI_API_KEY=sk-...` |
+| **Xiaomi MiMo** | `export XIAOMI_API_KEY=sk-...` |
+| **OpenRouter** | `export OPENROUTER_API_KEY=sk-or-...` (qwen, baidu, stepfun, tencent, … when no direct key) |
+| **Ollama (local)** | Install Ollama, run a model, then `export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1` and `export OPENAI_LOCAL_API_KEY=ollama` |
+| **Krouter (Kiro provider)** | On by default (`http://localhost:20128/v1`). Start the gateway: `npm install -g @sifxprime/krouter@0.5.118 && krouter -t --skip-update`. Override the URL with `KROUTER_API_BASE`. Opt out with `KROUTER_DISABLED=1`. Install steps: [`docs/KROUTER.md`](docs/KROUTER.md). Legacy `KIRO_*` still works. API key optional. |
+| **Cursor CLI** | Install the Cursor agent, sign in, set e.g. `export CURSOR_MODEL=auto`, and pass `--cursor` when needed |
+
+**Precedence:** DeepSeek → China pi-ai direct keys (`KIMI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_*`, `ZAI_API_KEY`, `XIAOMI_API_KEY`) → Ollama → Krouter → OpenRouter → `CURSOR_MODEL` / `--cursor`. Direct keys use pi-ai model catalogs; OpenRouter skips overlapping providers (e.g. `moonshotai` when `MOONSHOT_API_KEY` is set). When `--model` is omitted, the CLI applies this walk and selects the first available model (`provider/id`). An explicit `--model` requires that provider's env API key or exits with code 2 (`{{envVar}} is not set.`).
+
+**Explicit model keys** — Use `--model <key>` or `/model <key>` where `<key>` comes from `KEY_TO_MODEL` (kebab-case, e.g. `kimi-for-coding`, `qwen-qwen-plus`, `ollama-qwen25-coder`). Hand-crafted lists are loaded from `~/.pithosai/models.json5` (seeded from `src/models/catalog.json` on first run). An unknown `--model` key prints an error on stderr and exits with code 2. List keys in your current environment:
 
 ```bash
-cd your-project
-pithosai init
-pithosai "Describe what you want done"
+node -e "import { getPublicModelKeys } from './src/models/key-to-model.js'; getPublicModelKeys().forEach(console.log)"
 ```
 
-- **`pithosai -i`** — interactive session with no initial prompt.  
-- In that interactive loop, type **`/exit`** or **`/quit`** to leave the CLI (plain `exit` is treated as a normal message to the agent).  
-- **`pithosai --no-interactive "…"`** — one shot, then exit.  
-- **`pithosai -C ./other-dir "…"`** — use another project directory.
-- Every CLI invocation prints a cyan ASCII `pithosai` slogan banner first.
-- On startup, `pithosai` may check npm for the latest `@pithosai/pithosai` version (at most **once per 24 hours**, tracked in `~/.pithosai/auto-upgrade-check.json`) and auto-runs `npm install -g @pithosai/pithosai@latest` when a newer release is found. Upgrade notices use the **same resolved CLI language** as help and prompts (project settings, `--lang`, or terminal locale). After an upgrade, **this process still runs the old build** until you run `pithosai` again. In a **TTY** session (same conditions as the full-screen agent TUI), it asks you to **press Enter** so those lines are not lost when the TUI starts. Set **`PITHOSAI_AUTO_UPGRADE=0`** (or `false` / `no` / `off`) to skip checks entirely.
+Full provider tables, env vars, and OpenRouter key patterns: [`src/models/README.md`](src/models/README.md).
 
-Prompts load from a local database (default `~/.pithosai/pithosai.db`). Optional role overrides live under `.pithosai/<role>/` in your project.
+### China direct APIs (1.0.12)
 
-### Language selection
+When a direct env key is set, pi-ai catalogs are exposed under predictable CLI prefixes:
 
-- Default language is **English (`en`)**.
-- Set language per command with `--lang`.
-- Or export `LANG` in your shell to set terminal locale preference.
+| Env | Example `--model` key |
+|-----|------------------------|
+| `KIMI_API_KEY` | `kimi-for-coding` |
+| `MOONSHOT_API_KEY` | `moonshotai-kimi-k2-6`, `moonshotai-cn-kimi-k2-6` |
+| `MINIMAX_API_KEY` / `MINIMAX_CN_API_KEY` | `minimax-*`, `minimax-cn-*` |
+| `ZAI_API_KEY` | `z-ai-glm-4-7` |
+| `XIAOMI_API_KEY` | `xiaomi-mimo-v2-5` |
 
-Examples:
+```bash
+export KIMI_API_KEY=sk-...
+pithosai --no-interactive --model kimi-for-coding "Refactor this module"
+```
+
+### OpenRouter (China + Global slugs)
+
+Use OpenRouter for any model from the OpenRouter catalog (China: Qwen, Baidu, StepFun, …; Global: Anthropic, OpenAI, Google, Meta, Mistral, …). Unset higher-priority keys if you want traffic to stay on OpenRouter.
 
 ```bash
-pithosai --lang zh "请解释这个错误"
+export OPENROUTER_API_KEY=sk-or-v1-...
+pithosai --no-interactive --model qwen-qwen-plus "Explain this function"
+pithosai --no-interactive --model anthropic-claude-sonnet-4 "Review this code"
+pithosai --no-interactive --model openai-o4-mini "Find the edge cases"
+```
+
+**Thinking models** — Any OpenRouter model with `reasoning: true` (Claude Sonnet 4/Opus 4, o3/o4-mini, Qwen thinking variants, …) automatically gets proper thinking format and developer-role compat. After `/model` to a thinking key, use `/new` or restart so the agent bootstraps fresh.
+
+### Ollama (local)
+
+| CLI key | Ollama tag | Agent tools (1.0.12) |
+|---------|------------|----------------------|
+| `ollama-qwen25` | `qwen2.5:14b` | Yes |
+| `ollama-qwen25-coder` | `qwen2.5-coder:14b` | Yes |
+| `ollama-deepseek-r1` | `deepseek-r1:14b` | No (chat-only) |
+| `ollama-qwythos-9b-q8` | `qwythos-9b-q8` | Yes |
+
+```bash
+export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1
+export OPENAI_LOCAL_API_KEY=ollama
+pithosai --no-interactive --model ollama-qwen25-coder "Add tests for this file"
 ```
 
+### Krouter (Kiro provider gateway)
+
+Install and run the local gateway first ([full install manual](docs/KROUTER.md)):
+
 ```bash
-export LANG=ja_JP.UTF-8
-pithosai "今日のタスクを要約してください"
+npm install -g @sifxprime/krouter
+krouter -t   # tray; or `krouter` for foreground logs
 ```
 
-Supported language codes:
-- `en` (English)
-- `ar` (Arabic)
-- `de` (German)
-- `es` (Spanish)
-- `fr` (French)
-- `it` (Italian)
-- `ja` (Japanese)
-- `ko` (Korean)
-- `nl` (Dutch)
-- `pt` (Portuguese)
-- `zh` (Simplified Chinese)
-- `zh-hant` (Traditional Chinese)
+Open [http://localhost:20128/dashboard](http://localhost:20128/dashboard), configure providers and combos, then point pithosai at `http://localhost:20128/v1`. Listed CLI shortcuts are dashboard combos (`RD` / `ARCH` / `PM` / `QA`). Other gateway ids use `--model krouter/<id>`. No API key is required unless kRouter enables auth (`KROUTER_API_KEY`).
+
+| CLI key | Krouter model id |
+|---------|------------------|
+| `krouter-rd` | `RD` (dashboard combo) |
+| `krouter-arch` | `ARCH` (dashboard combo) |
+| `krouter-pm` | `PM` (dashboard combo) |
+| `krouter-qa` | `QA` (dashboard combo) |
+| `krouter/<id>` | any id from `GET /v1/models` |
+
+```bash
+# optional: override the default http://localhost:20128/v1
+export KROUTER_API_BASE=http://localhost:20128/v1
+# opt out: export KROUTER_DISABLED=1
+pithosai --no-interactive --model krouter-rd "Add tests for this file"
+pithosai --no-interactive --model krouter/cu/default "Summarize this module"
+```
+
+### DeepSeek API (V4)
+
+With a native **`DEEPSEEK_API_KEY`**, flags map to:
+
+| Your choice | API model id | Typical use |
+|-------------|----------------|-------------|
+| Default (no `--pro` / `--reasoner`) | `deepseek-v4-flash` | Cost-efficient daily work |
+| `--pro` | `deepseek-v4-pro` | Harder tasks |
+| `--chat` | `deepseek-v4-flash` | Explicit chat path |
+| `--reasoner` | `deepseek-v4-pro` + reasoning | Longer chain-of-thought |
+
+Legacy ids `deepseek-chat` and `deepseek-reasoner` are retired upstream; see [DeepSeek API docs](https://api-docs.deepseek.com/). Flash paths disable API “thinking” by default so tool-heavy turns stay stable; `--reasoner` keeps extended reasoning enabled.
+
+With **OpenRouter** only, use slugs `deepseek/deepseek-v4-flash` (default) and `deepseek/deepseek-v4-pro` (`--pro` / `--reasoner`). An OpenRouter regression was fixed in **1.0.8**.
 
-### Upgrading from v1.0.4 (plaintext `pithosai.db`)
+### Role entrypoints
 
-- **Automatic:** After upgrading to **1.0.5+**, plaintext databases are migrated in place to encrypted storage on first open when encryption support is available.
-- **Manual (optional):** You can run `pithosai migrate-db` if you want to trigger migration directly.
+| Command | Role | Default model |
+|---------|------|----------------|
+| `rdsai` | RD | `deepseek-v4-flash` (unless `--pro` / `--reasoner`) |
+| `pmsai`, `qasai`, `cosai`, `mktai` | PM / QA / CO / MKT | flash (`--chat`) |
+| `wrsai` | WR (`task` mode) | flash; default language **zh** |
+
+These ship as POSIX shell wrappers next to `pithosai.mjs` that invoke the same binary with preset flags (**1.0.9** / **1.0.10**).
+
+Use `/model` in the REPL to list and switch models interactively. Autocomplete includes tool-capable keys only (Ollama Qwen yes; `ollama-deepseek-r1` excluded). The interactive session reuses one agent instance until `/new` or until the resolved model changes (**1.0.12** session cache).
+
+### Agent orchestration (`src/agent-orch/`)
+
+The `agent-orch/` layer chains multiple roles sequentially for complex, multi-step tasks.
+Each role receives the previous role's report JSON as context.
+
+```bash
+./src/agent-orch/run.sh --roles MKT,ARCH,PM,RD \
+  --request "Analyze the market for an AI platform" \
+  --lang zh
+```
+
+**Available roles:** `MKT`, `ARCH`, `RD`, `PM`, `QA`, `CO`, `WR`, `SRE`.
+
+The final report JSON path is printed to stdout.
+
+For embedding in other shell scripts, source `base.sh` and call `dispatch_roles`:
+
+```bash
+source "src/agent-orch/base.sh"
+task_id="$(uuidgen)"
+dispatch_roles "$task_id" "My Title" "My request" "zh" MKT ARCH PM RD
+```
+
+See [`src/agent-orch/READEM.md`](src/agent-orch/READEM.md) for details.
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `pithosai` | Main CLI: `init`, `migrate-db`, interactive agent, `task`, `heartbeat`, `skills`, `memorize`, … |
+| `rdsai`, `pmsai`, `qasai`, `cosai`, `mktai`, `wrsai` | Same CLI with a default role |
+| `email-monitor` | Heartbeat / email-driven task loop |
+| `render-markdown` | Render Markdown in the terminal |
+| `init` | Optional manual create of `~/.pithosai/pithosai.db` (the global install and first CLI start already do this) |
+
+### Project maintenance
+
+| Command | What it does |
+|---------|----------------|
+| `pithosai init [dir]` | Optional project scaffold (`.pithosai/sessions/`, settings). Not required to start the CLI |
+| `pithosai migrate-db` | Legacy plaintext DB → SQLCipher |
+| `pithosai add-role <role>` | Append role to `supportedRoles` in `.settings.json` |
+| `pithosai role-template init` | Seed built-in Role Market templates (RD, PM, QA, WR, CO, MKT, SRE × en/zh) into an empty `pithosai.db`; prints download progress while fetching. The CLI also auto-runs this seed on startup when `pithosai_role_prompts` is empty |
+| `pithosai models` | List models as JSON (default) or `--table`; public KEY_TO_MODEL + discovered krouter composites; optional JS regex filters match key/provider/modelId (AND) |
+| `pithosai role-template list` | List role prompt templates stored in `pithosai.db` |
+| `pithosai role-template show <role>` | Show decrypted role template content (`--lang`, `--name`) |
+| `pithosai role-template create <role>` | Create role template in DB from bundled `templates/<role>/` or `--from-dir` |
+| `pithosai role-template update <role>` | Update role template prompts (`--content`, `--file`, `--from-dir`, or `--from-remote`) |
+| `pithosai task --file <md>` | Watch a task file and run tasks |
+| `pithosai task summarize --task-id <id>` | Refresh LLM rolling summary for one persisted task |
+| `pithosai task summarize --all-stale` | Summarize tasks with new messages since last cursor |
+| `pithosai task summarize-daemon [--once]` | Background loop for stale task summaries (cron-friendly) |
+| `pithosai cron-daemon [--once]` | Load `pithosai_cron_task` schedules and run recurring agent jobs (requires daemon for schedules to fire) |
+| `pithosai memorize --start … --end … -r <role>` | Build `.pithosai/<role>/memory.md` |
+| `pithosai heartbeat` / `heartbeat --once` | Email pipeline (IMAP/SMTP in settings) |
+| `pithosai skills …` | Install / list / remove skills |
+| `pithosai shell "cmd"` | Run a shell command via the CLI |
+
+Use `pithosai --help` and `pithosai <command> --help` for flags such as `--timeout`, `--lang`, `--role`, and `--log-path`. By default, logs are written to a per-project file under the OS temp directory (`$TMPDIR/pithosai/<project-hash>/pithosai.log`); override with `--log-path` or `PITHOSAI_LOG_FILEPATH`.
 
 ---
 
-## Run modes (`--mode`)
+## Run modes
 
 | Mode | Use case |
 |------|----------|
-| **`agent`** (default) | Full tools: edit files, run commands, etc. |
-| **`dialog`** | Answers and read-only tools (no shell tool). |
-| **`plan`** | Writes a plan file (`<slug>-plan.md`) in the project root; read-only tools. |
+| `agent` (default) | Full tools: edit files, run commands, … |
+| `dialog` | Answers and read-only tools (no shell tool) |
+| `plan` | Writes `<slug>-plan.md`; read-only tools |
 
 ```bash
 pithosai --mode dialog "Explain this error"
 pithosai --mode plan "Outline the next sprint"
 ```
 
-Result previews (terminal or optional Chrome via Playwright) can be tuned with `PITHOSAI_SKIP_RESULT_BROWSER`, `PITHOSAI_RESULT_BROWSER`, and `PITHOSAI_PLAYWRIGHT_CHANNEL`.
+Markdown previews: `PITHOSAI_SKIP_RESULT_BROWSER`, `PITHOSAI_RESULT_BROWSER`, `PITHOSAI_PLAYWRIGHT_CHANNEL`.
 
 ---
 
-## Common commands
+## Interactive session
 
-| Command | What it does |
-|---------|----------------|
-| `pithosai init [dir]` | Scaffold project, `.pithosai/sessions/`, settings. |
-| `pithosai migrate-db` | Convert a legacy plaintext global DB to SQLCipher (optional; usually automatic on first open). |
-| `pithosai add-role <role>` | Add a role to the project. |
-| `pithosai task --file <md>` | Watch a task file and run tasks sequentially. |
-| `pithosai memorize --start … --end … -r <role>` | Build `.pithosai/<role>/memory.md` from stored tasks. |
-| `pithosai heartbeat` / `heartbeat --once` | Email-driven task pipeline (needs IMAP/SMTP in settings). |
-| `pithosai skills …` | Install / list / remove skills. |
-| `pithosai shell "cmd"` | Run a shell command via the CLI. |
+The default UI is a **full-screen TUI**: transcript above, input below. Your turn is shown once as **`You:`** plus the text you typed, with a blank line before it so it is separated from the previous output; the run does **not** reprint `request: …` or `cwd …` in the transcript (cwd/git is the footer line). In the input box, **Enter** submits; **Shift+Enter** inserts a newline (on macOS this works even when the terminal sends the same CR as Enter, e.g. Cursor / VS Code). **Ctrl+J** also inserts a newline; **`\` then Enter** is the same fallback. A line that fills the box wraps onto the next row (aligned under the typed text) instead of hiding characters under the right border (**1.0.29**). While the agent runs you can still type in the input box: **submit** queues a **follow-up** message for the current run (shown on a fixed row below the running indicator); **`/note <text>`** steers the run after the current assistant turn. **Ctrl+S** stops the agent; **Ctrl+P** pauses; **Ctrl+Z** (or **`/bg`**) suspends the TUI so your parent shell can run commands — type **`fg`** to bring the TUI back (the agent freezes while suspended). After pause, edit the request if needed, then type **`/continue`** to resume or **`/exit`** to stop (plain `continue`, `c`, `exit`, or `e` are treated as request text). The bottom chrome shows **task/model/role** above the framed input, and a dim **`\<cwd\> - git \<branch\>`** line under the input (path ≤50% width, branch ≤40%, both truncate with a leading `...`; no repo → path only). That cwd/git row refreshes on session start, project/`/shell cd` cwd changes, after `/shell` commands, before/after each agent turn, and periodically during a run so same-directory branch switches show up without restarting. Set `PITHOSAI_NO_TUI=1` for a classic line prompt (scripts, minimal terminals).
+
+### Core slash commands
+
+| Command | Description |
+|---------|-------------|
+| `/model` | List and switch models |
+| `/mode` | Show or switch run mode (`agent`, `dialog`, `plan`) |
+| `/bg` | Suspend the TUI (same as Ctrl+Z); return with `fg` from the parent shell |
+| `/shell <cmd>` | Run a shell command. Full-screen tools (`tig`, `vim`, `hx`, `less`, …) attach to the terminal until they exit; `/shell -i <cmd>` forces that. Extra names: `PITHOSAI_TTY_COMMANDS` |
+| `/shell cd <dir>` | Change working directory (`~` supported); syncs session `projectPath` (**1.0.8**) |
+| `/list` | Show persisted tasks for the current session project (includes `projectPath` column) |
+| `/list <text>` | Filter tasks by title, description, or path |
+| `/select`, `/show`, `/show-task`, `/show-prompt` | Work with persisted tasks. `/show-task` includes tool requests and tool results in the answer preview (**1.0.28**). `/show-prompt` fences the skills XML for readable preview (tools stay as a markdown list). |
+| `/new` | Start a new task id (no prior messages loaded) |
+| `/list-skill`, `/install-skill`, `/remove-skill` | Same as `pithosai skills` (ClawHub). Install/remove refresh the live agent session skills in place (no restart/`/new` needed). |
+| `/skill-<name> […]` | Activate an installed catalog skill for the current agent session (agent mode). Embeddable like `/image`; multiple tokens add to the session set. Follow-ups keep a `<forced_skills>` block until `/skill-done`, a `[PITHOS_SKILL_COMPLETE:<name>]` marker, or the session ends (`/new`, `/select`, …). (**1.0.30**) |
+| `/skill-done [name]` | Clear all active skills, or one name; does not run the agent. (**1.0.30**) |
+| `/grill-me [topic]` | Stress-test a plan with one question at a time (**1.0.8**) |
+| `/image <path>` | Embed a local image in a request. Multiple `/image` directives can appear anywhere in the request body (start, middle, end). Each is attached to the AI and removed from the prompt text. Failed paths are reported; a mix of successes and failures is supported. (**1.1.4**) |
+| `/exit`, `/quit` | Leave the REPL (**1.0.7**). Restores the parent shell screen without wiping scrollback (**1.0.28**). |
+
+Tab completion covers slash commands (including `/list-project`, `/grill-me`, and `/skill-<name>` from the current skill catalog). For embeddable `/skill-<name>`, **Enter** in the autocomplete list applies the token like **Tab** (keeps editing); `/skill-done` and other whole-line slash commands still submit on Enter. Directory navigation via `/shell cd` and `ls` is tracked for recall (**1.0.8**).
+
+### `@` file and directory completion (**1.0.14**)
+
+Type `@` in the TUI or readline prompt to autocomplete files and folders under the current project directory (`runOpts.cwd` / virtual project root). Suggestions include all project files (`.git`, `node_modules`, `dist`, and `.pithosai` are skipped). Tab or continue typing to filter; select a directory to keep completing with a trailing `/`.
+
+Shared logic lives in `src/completion/` (`at-mention-utils.js` for token parsing; `at-path-suggestions.js` for filesystem listing).
+
+If you need full persisted task history on resume (instead of phi LUM trimming), set `PHI_MESSAGES_DISABLED=true`. By default, phi restores the **first user turn** plus the **latest 2 user turns** (each with assistant and tool messages).
+
+### Virtual projects
+
+Manage multiple workspaces from the REPL without leaving the session. Registry table: **`pithosai_virtual_project`** in **`~/.pithosai/pithosai.db`** (legacy **`~/.pithosai/projects.json`** is imported once on first load when the table is empty).
+
+| Column | Notes |
+|--------|--------|
+| `id` | Primary key (UUID) — use as `projectId` in API calls |
+| `account_id` | Virtual account id (default **`admin`**, indexed) |
+| `path` | Unique absolute project directory |
+| `name`, `lang`, `description` | Project metadata shown by `/list-project` and `/show-project` |
+
+| Command | Description |
+|---------|-------------|
+| `/create-project [name path lang description]` | Register a project, create its directory if needed, initialize git when the path is not yet versionized (via `isomorphic-git`), `chdir`, and start a new task id. With no arguments, registers the current directory (or shows it if already registered). |
+| `/list-project [filter]` | List registered projects (index, name, path). Optional filter matches name, path, language, or description. |
+| `/show-project` | Show cwd and registry metadata when cwd matches a saved path |
+| `/switch-project <index>` | `chdir` to a listed project, initialize git when needed, and start a new task id |
+
+Agents also have git function-call tools (`git_status`, `git_init`, `git_add`, `git_commit`, `git_log`, `git_rollback`) under `src/agent/tools/git/`. Status, branch, add, commit, log, and rollback prefer the system `git` CLI so repositories using **reftable** ref storage work; they fall back to `isomorphic-git` when `git` is not installed. New project init still uses `isomorphic-git`. `git_rollback` undoes local commits (`soft` default keeps changes staged; `mixed` / `hard` optional) and refuses to remove the root commit. After generating docs or code, agents should call `code_review` (deepseek-v4-pro, read-only review of uncommitted changes; optional `path` / `filepaths`); apply all findings, then `git_commit` with a concise AI-generated message.
+
+`/list` is scoped to the active session project path and does not collide with `/list-project` or `/list-skill` by prefix.
+
+### Plan alignment (`/grill-me`)
 
-Use **`pithosai --help`** and **`pithosai <command> --help`** for flags (`--timeout`, `--lang`, `--role`, `--log-path`, etc.).
+`/grill-me` runs a Matt Pocock–style alignment prompt (one question per turn) to sharpen plans before implementation. Optional text after the command sets the focus topic. Prompt language follows `--lang` / settings (`en`, `zh`, `zh-hant`, …). A matching Cursor skill lives at `.cursor/skills/grill-me/SKILL.md`.
+
+### Reliability
+
+- **Connection-loss retry (1.0.8):** Transient API drops (`network connection lost`) are retried like timeouts.
+- **Tool result display:** Orphaned error tool results are filtered so the transcript stays consistent; ANSI styling in tool output was corrected in **1.0.8**. Tool results still preview the first three non-empty lines; `task` and `code_review` also print the full summary (`result` / `findings`) so it is not hidden behind the JSON wrapper (**1.0.24**).
 
 ---
 
-## Interactive session (short)
+## Startup version check
+
+On launch, the CLI **may** check npm for a newer `@pithosai/pithosai` (at most once per 24 hours; state in `~/.pithosai/auto-upgrade-check.json`) and run `npm install -g @pithosai/pithosai@latest` (**1.0.7**).
 
-In a normal terminal, the default UI uses a **full-screen TUI** (bottom input, scrolling transcript). **`Ctrl+S`** stops a run; **`Ctrl+P`** pauses. Slash commands include `/model`, `/shell`, `/list`, `/show-task`, `/show-prompt`, and skill helpers. Set **`PITHOSAI_NO_TUI=1`** for a classic line-based prompt (e.g. scripts or minimal terminals).
+Notices use the same resolved CLI language as help. **The running process remains the old build** until you start `pithosai` again. When stdin and stdout are TTYs and the full-screen TUI would start, the CLI **waits for Enter** so upgrade messages are visible.
+
+Disable with `PITHOSAI_AUTO_UPGRADE=0` (or `false` / `no` / `off`).
 
 ---
 
@@ -200,28 +487,155 @@ In a normal terminal, the default UI uses a **full-screen TUI** (bottom input, s
 
 | Variable | Role |
 |----------|------|
-| `CURSOR_MODEL`, `CURSOR_AGENT_BIN` | Cursor CLI integration |
-| `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY` | API providers |
-| `OPENAI_LOCAL_API_BASE` | Local Ollama endpoint (requires local Ollama install) |
-| `PITHOSAI_DB_PATH` | SQLite DB path (default `~/.pithosai/pithosai.db`) |
-| `PITHOSAI_AUTO_UPGRADE` | Set to `0` / `false` / `no` / `off` to disable startup version check and global auto-install |
+| `DEEPSEEK_API_KEY`, `KIMI_API_KEY`, `MOONSHOT_API_KEY`, `MINIMAX_API_KEY`, `MINIMAX_CN_API_KEY`, `ZAI_API_KEY`, `XIAOMI_API_KEY`, `OPENROUTER_API_KEY` | API providers |
+| `OPENAI_LOCAL_API_BASE`, `OPENAI_LOCAL_API_KEY` | Local Ollama (`/v1` base URL + key; both required for `ollama-*` keys in `/model`) |
+| `KROUTER_API_BASE`, `KROUTER_DISABLED`, `KROUTER_API_KEY` | Local kRouter (`@sifxprime/krouter`, on by default at `http://localhost:20128/v1`; set `KROUTER_DISABLED=1` to opt out; key optional). See [`docs/KROUTER.md`](docs/KROUTER.md) |
+| `KIRO_API_BASE`, `KIRO_DISABLED`, `KIRO_API_KEY` | Legacy aliases for the Krouter env vars above |
+| `CURSOR_MODEL`, `CURSOR_AGENT_BIN` | Cursor CLI |
+| `TIPS_MODEL` | Model key for `pithosai shell-tips` (default `ollama/qwen2.5-coder:14b`) |
+| `PITHOSAI_DB_PATH` | SQLite DB (default `~/.pithosai/pithosai.db`) |
+| `PITHOSAI_AUTO_UPGRADE` | Disable startup check: `0` / `false` / `no` / `off` |
 | `PITHOSAI_SKIP_RESULT_BROWSER` | Skip markdown preview (e.g. CI) |
-| `PITHOSAI_RESULT_BROWSER` | `chrome` for Playwright browser preview |
-| `PITHOSAI_TIMEOUT_MS` / `--timeout` | Run time limits |
-| `SCRAPERAPI_API_KEY` | Used by skills / some tools |
+| `PITHOSAI_RESULT_BROWSER` | e.g. `chrome` for Playwright |
+| `PITHOSAI_TIMEOUT_MS` / `--timeout` | Run limits |
+| `PITHOSAI_TTY_COMMANDS` | Extra `/shell` TUI basenames (comma/space-separated) that inherit the terminal, e.g. `hx,k9s,mytui` |
+| `PITHOSAI_NL_FALLBACK` | Disable NL shell fallback: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_ZLE` | Disable NL Enter intercept only: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_MODEL` | NL fallback agent model (default `krouter-rd`) |
+| `PITHOSAI_NL_CLASSIFY_LLM` | Skip NL classify LLM: `0` / `false` / `no` / `off` |
+| `PITHOSAI_NL_CLASSIFY_TIMEOUT_MS` | NL classify LLM timeout (default `4000` ms) |
+| `PITHOSAI_NL_CLASSIFY_MODEL` | NL classify LLM id (default `RD`) |
+| `PITHOSAI_NL_CLASSIFY_API_BASE` | NL classify LLM base URL (Krouter by default) |
+| `PITHOSAI_NL_CLASSIFY_API_KEY` | NL classify LLM API key (optional) |
+| `PITHOSAI_NL_DEBUG_LOG` | NL fallback debug on stderr: `1` / `true` / `yes` / `on` |
+| `PITHOSAI_BIN` | pithosai binary for NL fallback (default `pithosai`) |
+| `PITHOSAI_LANG` | Override locale for NL fallback messages and `--lang` |
+| `PITHOSAI_NODE` | Node binary for NL classify (default `node`) |
+| `PHI_MESSAGES_DISABLED` | Set to `true` to disable phi turn trimming when restoring task messages |
+| `PITHOSAI_GIT_AI` | Git AI adapter (on by default). Disable: `0` / `false` / `no` / `off`. JSON hooks still load. |
+| `PITHOSAI_DEBUG_HOOKS` | Debug hook handlers when no `.settings.json` `hooks.active` preset: `1` / `true` |
+| `PITHOSAI_DEBUG_HOOKS_DATA` | Log full hook payloads with debug hooks: `1` |
+| `PITHOSAI_SECURITY_HOOKS` | Security hook handlers when no `hooks.active` preset: `1` / `true` |
+| `PITHOSAI_BLOCKED_TOOLS` | Comma-separated tool names blocked by security hooks |
+| `PITHOSAI_MAX_PROMPT_LENGTH` | Security-hook system-prompt length warning (default `10000`) |
+| `SCRAPERAPI_API_KEY` | Some skills / tools |
+
+When `PHI_MESSAGES_DISABLED=true`, persisted task messages are restored in full chronological order instead of LUM selection (first user turn + latest 2 user turns).
+
+---
+
+## What's new (v1.0.7 – v1.0.32)
+
+Highlights for the published CLI. Full per-version notes: [`CHANGELOG.md`](CHANGELOG.md).
+
+### v1.0.32 — Krouter combos, `pithosai models`
+
+- **Krouter catalog** — Curated family keys (`kr/glm-5*`, `kr/minimax-*`, `kr/deepseek-*`) are gone. Shortcuts are dashboard combos `krouter-rd`, `krouter-arch`, `krouter-pm`, and `krouter-qa`. Other gateway ids use `krouter/<id>` (alias `kiro/<id>`). See [Krouter](#krouter-kiro-provider-gateway).
+- **`pithosai models`** — Lists public `KEY_TO_MODEL` keys plus discovered krouter composites. JSON on stdout by default; `--table` prints aligned columns.
+- **NL defaults** — Shell fallback `PITHOSAI_NL_MODEL` is `krouter-rd`. The classify LLM defaults to the `RD` combo.
+
+### v1.0.31 — Role Market seed, bash NL fallback
+
+- **Role templates** — `pithosai role-template init` seeds RD, PM, QA, WR, CO, MKT, and SRE (`en` and `zh`) into an empty `pithosai_role_prompts` table. The CLI does the same seed on startup, so `pithosai init` is not required. `role-template update <role> --from-remote` refreshes one installed role from the Role Market.
+- **Krouter default** — Env-walk default is the `RD` combo (`krouter-rd`). `--reasoner` / `--pro` no longer switch that default.
+- **bash NL fallback** — The intercept is **Ctrl-J** (bash reserves Enter for `accept-line`). It rewrites `READLINE_LINE` and leaves TAB completion working.
+
+### v1.0.30 — `/skill-<name>` session activation
+
+- **`/skill-<name>`** — Embeddable tokens activate installed catalog skills on the current agent session (agent mode). Several tokens add to the set. Follow-ups keep a `<forced_skills>` block until `/skill-done`, a `[PITHOS_SKILL_COMPLETE:<name>]` marker, or the session ends (`/new`, `/select`, …).
+- **`/skill-done [name]`** — Clears all active skills, or one name, without running the agent.
+- **Completer** — Tab offers `/skill-<name>` from the current skill catalog.
+
+### v1.0.29 — Git AI checkpoints, TUI input wrap
+
+- **JSON command hooks** — Load `~/.pithosai/hooks/*.json` and `<cwd>/.pithosai/hooks/*.json` (project wins by filename). `hookType` is a pithos HookType (`beforeToolExecute`, `afterToolExecute`, …). In-process adapters stay on `CORE_COMMAND_HOOK_ADAPTERS`; Git AI is a bundled JSON config plus shipped CLI. See [Git AI checkpoints](#git-ai-checkpoints) and [Add a pithosai core agent hook](docs/hooks-usage.md#add-a-pithosai-core-agent-hook).
+- **Built-in hook plugins** — Bundled hooks (system prompt rebuild, JSON command hooks) register through `registerBuiltinHookPlugins()`, with a per-run agent context so plugins can read task id, model, and messages. `pithosai hooks list` / `status` load the same plugins and print to stdout (they do not use deprecated `.settings.json` `hooks.active`).
+- **TUI input wrap** — A nearly-full first line in the framed editor wraps onto the next row instead of clipping under the right border. Wrapped rows stay aligned under the typed text.
+- **TUI trackpad scroll** — Two-finger wheel bursts on macOS no longer freeze a long transcript; ticks coalesce and wrap results are cached.
+
+### v1.0.28 — pi 0.85.1, `/show-task` tools, TUI exit restore
+
+- **pi libs 0.85.1** — `@earendil-works/pi-ai`, `pi-agent-core`, `pi-coding-agent`, and `pi-tui` upgraded from 0.78; Node **≥ 22.19** required. Agent TUI uses `TuiAltScreen`.
+- **`/show-task` tool runs** — Preview includes tool requests and tool results (truncated) in the answer body, with localized labels.
+- **TUI exit restore** — Leaving the full-screen TUI no longer clears the restored main buffer (no nested alt-screen enter / no post-stop clear). Shell prompt and scrollback stay intact.
+- **Test hygiene** — Vitest terminal teardown avoids leftover escape codes; skills tests mock `fetch`.
+- **Mouse-wheel transcript scroll** — Wheel again scrolls the agent TUI transcript after the pi-tui 0.85.1 upgrade. All-motion mouse tracking is disabled so a macOS trackpad cannot flood stdin and freeze the CLI.
+
+### v1.0.26 — System prompt rebuild hook, TUI job control
+
+- **TUI job control** — **Ctrl+Z** or **`/bg`** suspends the full-screen TUI to the parent shell; **`fg`** brings it back. The agent freezes while suspended (same as `vim`/`less`). Unsupported on Windows.
+- **System prompt rebuild hook** — New hook type `BEFORE_CACHED_AGENT_REUSE` triggers before reusing a cached agent, rebuilding the system prompt and initial messages from DB to ensure fresh task context, skills, and role prompts.
+
+### v1.0.19 — NL fallback classifier, Enter intercept
+
+- **Natural-language command fallback** — Node classifies unknown commands (`lookpath` + `tinyld`, 0–100 shell score). Uncertain lines ask an LLM for `shell` or `natural`; clear NL (starters, reserved-keyword prose, CJK, overlong) skips that call. Interactive zsh and bash 4+ intercept Enter so `for these files: …` reaches pithosai instead of a keyword parse error. Env: `PITHOSAI_NL_FALLBACK`, `PITHOSAI_NL_ZLE`, `PITHOSAI_NL_MODEL`, `PITHOSAI_NL_CLASSIFY_LLM`, `PITHOSAI_NL_DEBUG_LOG`, `PITHOSAI_BIN`, `PITHOSAI_LANG`, `PITHOSAI_NODE`. See [Natural-language command fallback](#natural-language-command-fallback-bash--zsh).
+
+### v1.0.18 — Quieter TUI transcript
+
+- **TUI transcript** — Submitting a turn no longer reprints `request: …` or `cwd …` in the scrollback (`You:` and the footer cwd/git line already show that). Queuing a follow-up no longer leaves a second `Running…` spinner.
+- **`--no-interactive`** — One-shot runs no longer draw the stderr loading spinner over streamed output.
+- **Natural-language command fallback (initial)** — Source `scripts/pithosai-nl-fallback.sh` from zsh or bash 4+ so unknown English/Chinese commands run pithosai.
+
+### v1.0.15 — Global OpenRouter models, Anthropic reasoning compat
+
+- **Global OpenRouter models** — `anthropic-*`, `openai-*`, `google-*`, `meta-*`, `mistral-*`, `cohere-*`, … all available via `OPENROUTER_API_KEY`. See [`src/models/README.md`](src/models/README.md) for the full slug list.
+- **Anthropic reasoning** — Claude Sonnet 4, Claude Opus 4, and other Anthropic reasoning models get automatic thinking-level compat (OpenRouter requires `reasoning` format even when effort is optional).
+- **Developer-role compat** — Both China OpenRouter slugs and Anthropic reasoning models now disable the `developer` role to avoid API 400 errors. Refactored `enhanceOpenRouterModel()` handles all OpenRouter models uniformly; old `enhanceOpenRouterChinaModel()` alias preserved.
+
+### v1.0.12 — China-mainland models, OpenRouter compat, Ollama tools
+
+- **China-mainland providers** — `KEY_TO_MODEL` merges pi-ai direct catalogs (Kimi, Moonshot, MiniMax, Z.ai, Xiaomi) with OpenRouter China slugs (Qwen, Baidu, StepFun, Tencent, …). Shared env detection via `provider-env.js`; see [`src/models/README.md`](src/models/README.md).
+- **OpenRouter fixes** — Mandatory-thinking models (`*-thinking`) no longer send disabled reasoning; China slugs use `system` instead of `developer` for the system prompt (Qwen-compatible).
+- **Agent session cache** — Model switches and env-only provider changes invalidate the cached CLI agent (`resolved:provider:id` cache keys).
+- **Ollama Qwen** — `ollama-qwen25` and `ollama-qwen25-coder` enable full agent tool calling locally.
+- **`PHI_MESSAGES_DISABLED`** — When `true`, restores full task message history instead of phi turn trimming on resume.
+
+### v1.0.11 — Runtime steer, follow-up, skills tools
+
+- **Runtime input while agent runs** — Submit plain text to **queue a follow-up** in the current run; `/note <text>` to **steer** after the current turn. Queued messages show on a dimmed TUI footer row. Ctrl+S stops, Ctrl+P pauses.
+- **TUI text wrapping** — Startup hints now wrap to terminal width instead of overflowing.
+- **Skills: read skill tools** — Installed skills can expose available tool definitions for their system prompts.
+- **Sub Agent** — add subagent module to support subagent functions
+
+### v1.0.10 — Packaging and distribution
+
+- Simplified npm publish layout (`.npmignore`, narrowed `files` field).
+- Role binaries (`rdsai`, `pmsai`, …) ship as POSIX wrappers under `scripts/bin-shims/` with corrected paths to `pithosai.mjs`.
+- Dependencies use published `@mariozechner/*` packages on npm instead of vendored `lib/pi-mono` copies.
+
+### v1.0.9 — Install reliability
+
+- Improved `npm install -g` resolution for bundled agent dependencies.
+- Role commands consolidated as thin shell wrappers invoking `pithosai.mjs`.
+
+### v1.0.8 — Session productivity
+
+- **Virtual projects** — `/create-project`, `/list-project`, `/show-project`, `/switch-project` with `~/.pithosai/projects.json`.
+- **`/grill-me`** — Interactive plan alignment (localized prompts).
+- **`/shell cd`** — In-process directory changes with `~` expansion and directory history.
+- **Task list** — `/list` shows `projectPath`, supports `/list <text>` filter, scopes to the session project.
+- **Resilience** — Automatic retry on connection loss; OpenRouter regression fix; `taskRef.projectPath` kept in sync after `cd` and project switches.
+
+### v1.0.7 — Models and startup
+
+- **DeepSeek V4** — Default `deepseek-v4-flash`; `--pro` / `--reasoner` select `deepseek-v4-pro` with optional reasoning.
+- **Startup auto-upgrade** — Optional global update check (24 h throttle, TTY-aware prompt).
+- **REPL exit** — `/exit` and `/quit` (plain `exit` goes to the agent).
+- **Locales** — `zh-hant` resolution fix; `render-markdown` dist entry fix.
 
 ---
 
-## Help and support
+## Help
 
-Use `pithosai --help` for top-level options, and `pithosai <command> --help` for command-specific details.
+- `pithosai --help`
+- `pithosai <command> --help`
 
 ---
 
 ## License
 
-Pithosai is **proprietary** software — it is **not** published under an open-source or ISC license.
+Pithosai is **proprietary** software; it is **not** published under an open-source license.
 
-Copyright © 2026 [lidh04@gmail.com](mailto:lidh04@gmail.com). All rights reserved.
+Copyright © 2026 [sihuic](https://www.sihuic.com) ([service@sihuic.com](mailto:service@sihuic.com)). All rights reserved.
 
-See [`LICENSE`](LICENSE) for the copyright notice (included in the npm package). The `license` field in `package.json` is `UNLICENSED`, which npm uses when no public license is granted.
+See [`LICENSE`](LICENSE), [`CHANGELOG.md`](CHANGELOG.md), and the other markdown files this README links to (`docs/hooks-usage.md`, `docs/KROUTER.md`, `src/models/README.md`, `src/models/krouter.README.md`, `src/agent-orch/READEM.md`) in the npm package. The `license` field in `package.json` is **`UNLICENSED`** (npm convention when no public license is granted).