@pithosai/pithosai 1.0.10 → 1.0.32

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright © 2026 lidh04@gmail.com. All rights reserved.
+Copyright © 2026 sihuic. Email: service@sihuic.com. Website: https://www.sihuic.com. All rights reserved.
 
 This software is proprietary and confidential. It is not distributed under
 an open-source license. No permission is granted to use, copy, modify, merge,

package/README.md

@@ -1,11 +1,13 @@
 # Pithosai (`@pithosai/pithosai`)
 
-**Multi-role AI CLI** for coding and product work: natural-language requests, pluggable models (DeepSeek, OpenRouter, Ollama, Cursor), 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).
 
 | | |
 |---|---|
 | **Best for** | Agent-style coding, multi-role workflows (RD / PM / QA / …), local or cloud models, repeatable prompts from a local database |
-| **Requirements** | **Node.js ≥ 18.12** and **at least one** [model provider](#model-providers) |
+| **Requirements** | **Node.js ≥ 22.19** and **at least one** [model provider](#model-providers) |
 | **License** | Proprietary — see [License](#license) |
 
 ---
@@ -16,14 +18,18 @@
 npm install -g @pithosai/pithosai
 ```
 
-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`.
+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.
+
+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`.
 
 **Highlights**
 
 - **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, and slash commands (`/model`, `/shell`, `/list`, skills, …).
-- **Virtual projects** — Switch workspaces from the REPL via `~/.pithosai/projects.json` ([details](#virtual-projects)).
+- **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.
@@ -36,7 +42,6 @@ On a global install, if `~/.pithosai/pithosai.db` does not exist, it is created
 ```bash
 export DEEPSEEK_API_KEY=sk-...   # or another provider below
 cd your-project
-pithosai init
 pithosai "Describe what you want done"
 ```
 
@@ -44,10 +49,85 @@ pithosai "Describe what you want done"
 |------------|----------|
 | `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. Prompts load from the local database (default `~/.pithosai/pithosai.db`). Optional role overrides live under `.pithosai/<role>/` in your project.
+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:
+
+| 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
+# 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
+```
+
+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).
+
+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).
+
+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
+```
+
+### 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"
+    }
+  ]
+}
+```
 
 ### Language
 
@@ -59,6 +139,60 @@ pithosai --lang zh "请解释这个错误"
 
 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.
 
+### Natural-language command fallback (bash / zsh)
+
+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`):
+
+```bash
+# zsh (~/.zshrc) or bash 4+ (~/.bashrc) — from this repo:
+source /path/to/pithosai/scripts/pithosai-nl-fallback.sh
+
+# 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"
+```
+
+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.
+
+**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.
+
+macOS system bash 3.2 has neither `command_not_found_handle` nor `bind -x`; use zsh or Homebrew bash.
+
+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.
+
+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]**.
@@ -72,11 +206,97 @@ Configure **at least one** of the following.
 | Provider | Setup |
 |----------|--------|
 | **DeepSeek** | `export DEEPSEEK_API_KEY=sk-...` |
-| **OpenRouter** | `export OPENROUTER_API_KEY=sk-or-...` |
-| **Ollama (local)** | Install Ollama, run a model, then `export OPENAI_LOCAL_API_BASE=http://localhost:11434/v1` |
+| **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 → Ollama (`OPENAI_LOCAL_API_BASE`) → OpenRouter → `CURSOR_MODEL` / `--cursor`.
+**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
+node -e "import { getPublicModelKeys } from './src/models/key-to-model.js'; getPublicModelKeys().forEach(console.log)"
+```
+
+Full provider tables, env vars, and OpenRouter key patterns: [`src/models/README.md`](src/models/README.md).
+
+### China direct APIs (1.0.12)
+
+When a direct env key is set, pi-ai catalogs are exposed under predictable CLI prefixes:
+
+| 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` |
+
+```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
+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
+npm install -g @sifxprime/krouter
+krouter -t   # tray; or `krouter` for foreground logs
+```
+
+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)
 
@@ -103,7 +323,32 @@ With **OpenRouter** only, use slugs `deepseek/deepseek-v4-flash` (default) and `
 
 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.
+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.
 
 ---
 
@@ -115,22 +360,32 @@ Use `/model` in the REPL to list and switch models interactively.
 | `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` | Initialize `~/.pithosai/pithosai.db` manually |
+| `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]` | Scaffold project, `.pithosai/sessions/`, settings |
+| `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>` | Add a role to the project |
+| `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`.
+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`.
 
 ---
 
@@ -153,35 +408,57 @@ Markdown previews: `PITHOSAI_SKIP_RESULT_BROWSER`, `PITHOSAI_RESULT_BROWSER`, `P
 
 ## Interactive session
 
-The default UI is a **full-screen TUI**: transcript above, input below. **Ctrl+S** stops the agent; **Ctrl+P** pauses. Set `PITHOSAI_NO_TUI=1` for a classic line prompt (scripts, minimal terminals).
+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 |
-| `/shell <cmd>` | Run a shell command in-process |
+| `/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 |
+| `/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) |
+| `/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**) |
-| `/exit`, `/quit` | Leave the REPL (**1.0.7**) |
+| `/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**).
 
-Tab completion covers slash commands (including `/list-project` and `/grill-me`). 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 file: **`~/.pithosai/projects.json`** (**1.0.8**).
+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, `chdir`, and start a new task id. With no arguments, registers the current directory (or shows it if already registered). |
+| `/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 and start a new task id |
+| `/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.
 
@@ -192,7 +469,7 @@ Manage multiple workspaces from the REPL without leaving the session. Registry f
 ### 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 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**).
 
 ---
 
@@ -210,21 +487,115 @@ Disable with `PITHOSAI_AUTO_UPGRADE=0` (or `false` / `no` / `off`).
 
 | Variable | Role |
 |----------|------|
-| `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY` | API providers |
-| `OPENAI_LOCAL_API_BASE` | Local Ollama (`/v1` base URL) |
+| `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` | 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.10)
+## 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
 
-Highlights for the published CLI (excluding unreleased components). Full per-version notes: [`CHANGELOG.md`](CHANGELOG.md).
+- **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
 
@@ -265,6 +636,6 @@ Highlights for the published CLI (excluding unreleased components). Full per-ver
 
 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) in the npm package. The `license` field in `package.json` is **`UNLICENSED`** (npm convention 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).

package/dist/529.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export const __rspack_esm_id="529";export const __rspack_esm_ids=["529"];export const __webpack_modules__={7136(s,t,e){e.d(t,{hashPassword:()=>r});var a=e(7598);let o=(0,e(7975).promisify)(a.pbkdf2);async function r(s){let t=(0,a.randomBytes)(16),e=await o(s,t,1e5,32,"sha256");return{salt:t.toString("hex"),hash:`100000:${e.toString("hex")}`}}}};

package/dist/813.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export const __rspack_esm_id="813";export const __rspack_esm_ids=["813"];export const __webpack_modules__={5484(t,e,i){i.a(t,async function(t,s){try{i.d(e,{showMarkdownInPiTui:()=>o});var l=i(8691),r=i(3565),n=i(2615),h=i(9989),a=t([l,r,n]);[l,r,n]=a.then?(await a)():a;let c=!1;class m{constructor(t){let{terminal:e,tui:i,markdown:s,hintText:l,documentTitle:r,onClose:n}=t;this.terminal=e,this.tui=i,this._markdown=s,this.hintText=l,this.documentTitle=r?.trim()||"",this.onClose=n,this.scrollTop=0,this._fullLines=null,this._cachedWidth=null,this._ggAwaitingSecondG=!1,this._ggTimer=null}clearGgPrefixState(){null!=this._ggTimer&&(clearTimeout(this._ggTimer),this._ggTimer=null),this._ggAwaitingSecondG=!1}invalidate(){this._markdown.invalidate(),this._fullLines=null,this._cachedWidth=null}handleInput(t){let e=this.terminal.columns,i=this.terminal.rows,s=+!!this.documentTitle,l=Math.max(1,i-s-1),r=this._getFullLines(e).length,h=Math.max(0,r-l);if((0,n.matchesKey)(t,"escape")||(0,n.matchesKey)(t,"esc")||(0,n.matchesKey)(t,"q")||(0,n.matchesKey)(t,"shift+q")||(0,n.matchesKey)(t,"ctrl+c")){this.clearGgPrefixState(),this.onClose();return}if((0,n.matchesKey)(t,"shift+g")){this.clearGgPrefixState(),this.scrollTop=h;return}if((0,n.matchesKey)(t,"g")){if(this._ggAwaitingSecondG){this.clearGgPrefixState(),this.scrollTop=0;return}this._ggAwaitingSecondG=!0,null!=this._ggTimer&&clearTimeout(this._ggTimer),this._ggTimer=setTimeout(()=>{this._ggTimer=null,this._ggAwaitingSecondG=!1},500);return}if(this.clearGgPrefixState(),(0,n.matchesKey)(t,"up")||(0,n.matchesKey)(t,"k")){this.scrollTop=Math.max(0,this.scrollTop-1);return}if((0,n.matchesKey)(t,"down")||(0,n.matchesKey)(t,"j")){this.scrollTop=Math.min(h,this.scrollTop+1);return}if((0,n.matchesKey)(t,"pageUp")||(0,n.matchesKey)(t,"ctrl+u")){this.scrollTop=Math.max(0,this.scrollTop-l);return}if((0,n.matchesKey)(t,"pageDown")||(0,n.matchesKey)(t,"ctrl+d")){this.scrollTop=Math.min(h,this.scrollTop+l);return}if((0,n.matchesKey)(t,"home")){this.scrollTop=0;return}if((0,n.matchesKey)(t,"end")){this.scrollTop=h;return}}_getFullLines(t){return this._fullLines&&this._cachedWidth===t||(this._cachedWidth=t,this._fullLines=this._markdown.render(t)),this._fullLines}render(t){let e=this.terminal.rows,i=this.documentTitle?[l.m.bold.cyan((0,n.truncateToWidth)(this.documentTitle,t))]:[],s=i.length,r=Math.max(1,e-s-1);null!=this._cachedWidth&&this._cachedWidth!==t&&this.invalidate();let h=this._getFullLines(t),a=Math.max(0,h.length-r);this.scrollTop=Math.min(this.scrollTop,a);let o=h.slice(this.scrollTop,this.scrollTop+r);for(;o.length<r;)o.push("");let c=l.m.dim((0,n.truncateToWidth)(this.hintText,t));return[...i,...o,c]}}async function o(t){let{markdown:e,t:i,documentTitle:s,tuiSession:l=null}=t;if(!e||"string"!=typeof e||!e.trim())return;if(!(process.stdout.isTTY&&process.stdin.isTTY))return void process.stdout.write(`${e}
+`);let a=l&&"function"==typeof l.suspendForReadline&&"function"==typeof l.resumeFromReadline;a&&l.suspendForReadline();try{c||((0,r.initTheme)("dark"),c=!0);let t=(0,r.getMarkdownTheme)(),l=new n.Markdown(e,1,1,t),a=i("cli.resultPreviewTerminalHint"),o=new n.ProcessTerminal,u=new n.TuiAltScreen(o);u.setClearOnShrink(!0),await new Promise(t=>{let e,i=new m({terminal:o,tui:u,markdown:l,hintText:a,documentTitle:s,onClose:()=>{e?.clearGgPrefixState(),u.stop(),(0,h.eN)(),t()}});e=i;let r=new n.Container;r.addChild(i),u.addChild(r),u.setFocus(i),u.start(),u.requestRender(!0)})}finally{a&&l.resumeFromReadline()}}s()}catch(t){s(t)}})}};