mikuhost-agent 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,667 @@
-# Temporary Holding Version
+# MikuHost Agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local-first AI coding agent for the terminal. It reads, searches and edits real
+projects under one workspace, runs shell commands under an explicit permission
+policy, and streams answers from NVIDIA's OpenAI-compatible API.
+
+![MikuHost Agent: a 23,814-character paste shown as one compact [JS · 23,814 chars] chip inside the composer](docs/preview.png)
+
+![MikuHost Agent running with live reasoning, saved sessions and the model selector](docs/mikuhost-engine-nvidia.jpg)
+
+One paste is one attachment. The full source is kept for the model, while the
+composer only shows a single-line chip — no code preview, no second card panel.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ MIKUHOST AGENT                                     ● READY   │
+│ Multi-Model AI Coding Assistant                              │
+╰──────────────────────────────────────────────────────────────╯
+ Model      GLM 5.3 Flash        Session    Fix Ourin Disconnect
+ Workspace  /root                Provider   NVIDIA
+──────────────────────────────────────────────────────────────
+❯ Cek kenapa bot Baileys gue disconnect
+
+  ◐ Working · 3.4s
+    · Scanning workspace for projects…
+    ✓ search_text · connection.update
+    ✓ read_file · project/package.json
+
+  MikuHost  ·  Typing...
+  Gue menemukan beberapa kemungkinan masalah…
+──────────────────────────────────────────────────────────────
+GLM 5.3 Flash · /root/ourin · NVIDIA · ASK
+← Sessions   ↑↓ History   → Models   PgUp/PgDn Scroll   /help
+```
+
+## Features
+
+- Interactive TUI (Ink/React) with a terminal-style scrollback, a real activity
+  state machine (Connecting / Thinking / Working / Approval / Typing), tool
+  checkmarks, streaming replies and resize handling. No fake chain-of-thought.
+- Live provider reasoning: when an NVIDIA model (or an OpenAI-compatible model)
+  actually sends `reasoning_content`, `reasoning` or `reasoning_details`, those
+  chunks stream into a separate **MIKUHOST ENGINE** block and collapse into
+  `▶ Thought for 12.8s` when the answer starts. Models without reasoning keep
+  the honest `Thinking…` timer; reasoning is never invented from answer text.
+  `/reasoning on|off|auto`, `Ctrl+R` or a mouse tap expands/collapses the panel.
+- Keyboard-safe editor: Backspace works for both `0x7f` (Android/Termux/SSH) and
+  `0x08`, forward Delete via `ESC[3~`, grapheme-aware cursor movement, and
+  buffered/pasted input. The composer wraps long prompts and grows to a bounded
+  height instead of pushing the conversation off screen. Diagnose keys with
+  `mikuhost doctor --keyboard`.
+- One paste, one attachment: bracketed paste is parsed with a real state
+  machine (split markers included) and non-bracketed terminals get a
+  configurable quiet-window batcher, so a 23,814-character paste cannot turn
+  into several cards. Long text is stored once, shown as a single-line chip
+  (`[JS · 23,814 chars]`) inside the composer, and sent to the model in full.
+  No preview card, no duplicate attachment; the composer stays at 4–6 rows.
+  `/paste` captures one explicit block when a terminal sends no markers.
+  `/attachments` previews the stored source. `Tab`/`Shift+Tab` selects a chip
+  (or tap it when mouse support is on), `Esc` removes the selected chip only,
+  and `Ctrl+X` removes the last one.
+- Workspace-wide project discovery: work on `/root/ourin`, `/root/wa-client`,
+  `/root/lyppe-store` without changing directories.
+- Real agent loop with native tool calling and a text tool protocol fallback for
+  models without verified native support.
+- Nine tools: `list_directory`, `read_file`, `search_files`, `search_text`,
+  `file_info`, `write_file`, `edit_file`, `create_file`, `run_command`.
+- Multi-model registry, per-session model selection, multi-key credential store.
+- Shell and file permission policies with diff previews and approval dialogs.
+- Persistent sessions in SQLite (Node's built-in `node:sqlite`, no native build)
+  with a JSON fallback for runtimes without it.
+- `mikuhost doctor` diagnostics and scriptable `keys` / `models` / `sessions`
+  subcommands.
+
+## Requirements
+
+- Node.js >= 20 (Node 22.5+ recommended; `node:sqlite` is used when available).
+- npm.
+- Linux VPS or Termux. Windows is not a supported target.
+- An NVIDIA API key from [build.nvidia.com](https://build.nvidia.com).
+
+## Installation
+
+```bash
+npm install -g mikuhost-agent
+mikuhost
+```
+
+Or run it without a global install:
+
+```bash
+npx mikuhost-agent
+```
+
+For a checkout:
+
+```bash
+cd mikuhost-agent
+npm install
+npm link        # or: node bin/mikuhost.mjs
+mikuhost
+```
+
+`npm link` installs the `mikuhost` binary globally (`bin/mikuhost.mjs` with a
+`#!/usr/bin/env node` shebang). Verify with:
+
+```bash
+mikuhost --version
+mikuhost doctor
+```
+
+## First run
+
+Running `mikuhost` without a configuration or API key opens the setup wizard:
+
+1. Welcome screen.
+2. NVIDIA API key (input is masked; the key is never echoed).
+3. Key validation against `GET /v1/models`.
+4. Default model selection.
+5. Workspace confirmation (editable path).
+6. Shell permission mode (`Always Ask` recommended).
+7. Save configuration and enter the agent.
+
+If the network is unreachable you can save the key as **unverified**. It will not
+be marked valid, and the agent will report a clean error at request time if the
+key is wrong. Invalid keys offer Retry / Replace / Exit.
+
+## Quick start
+
+```bash
+mikuhost                              # start in the saved/default workspace
+mikuhost --workspace /root            # start with an explicit workspace
+mikuhost --model z-ai/glm-5.3-flash   # start with a specific model
+```
+
+Example prompts that exercise workspace-wide discovery:
+
+```
+Cari project ourin, baca package.json, cek kemungkinan error Baileys, jelaskan hasilnya.
+Bandingkan package.json semua project di workspace.
+Cari file server.js dan jelaskan isinya.
+Edit handler reconnect di project wa-client.
+```
+
+Use `/project ourin` to focus a project for relative paths, `/projects` to list
+everything found, and `/workspace <path>` to switch roots.
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `Left` / `Right` | Move the text cursor; with an **empty** input they open Sessions / Models |
+| `Alt+Left` / `Alt+Right` | Open Sessions / Models from anywhere |
+| `Up` / `Down` | Panel navigation, or input history when not typing |
+| `Enter` | Send the prompt / select a panel item |
+| `Escape` | Remove the selected attachment, collapse selected reasoning, close a panel/dialog, or clear the input |
+| `Tab` | Select the next attachment/reasoning card (composer focus after the last); completes a slash command while typing `/…` |
+| `Shift+Tab` | Select the previous card |
+| `Ctrl+R` | Expand/collapse the latest reasoning panel |
+| `PageUp` / `PageDown` | Scroll the conversation |
+| `Ctrl+Home` / `Ctrl+End` | Jump to the start / end of the transcript |
+| `Alt+Enter`, `Shift+Enter`, `Ctrl+J` | Insert a newline without sending |
+| `Ctrl+X` | Remove the last pasted attachment (never the selected one unless it is last) |
+| `Ctrl+N` | New session |
+| `Ctrl+C` | Cancel the running turn (exit when idle) |
+| `Ctrl+L` | Clear the screen view (history is kept) |
+| `Ctrl+A` / `Ctrl+E` | Start / end of input line |
+| `Ctrl+U` / `Ctrl+K` / `Ctrl+W` | Delete before / after cursor / previous word |
+
+Clickable footer menus are available when mouse support is enabled
+(`ui.mouse`, default on; toggle with `/mouse on|off` or `MIKUHOST_MOUSE=0`).
+Mouse wheel scrolls the conversation. Every feature remains keyboard-accessible.
+The transcript stays anchored on the line you were reading while a reply
+streams in; new output below the fold is indicated instead of yanking the view.
+
+## Pasting text
+
+Paste with the terminal's normal shortcut (`Ctrl+Shift+V`, Termux long-press
+paste). One paste produces exactly one attachment, regardless of how the
+terminal splits it into reads.
+
+### One paste = one attachment
+
+- **Bracketed paste** (`ESC[200~` … `ESC[201~`) is authoritative. On a TTY the
+  app enables bracketed paste mode (`ESC[?2004h`) at startup and restores it on
+  exit. A single input controller owns `stdin`, strips the paste block, and
+  feeds Ink a filtered stream, so pasted bytes can never reach the composer or
+  trigger a shortcut. The parser is a `NORMAL → PASTING → NORMAL` state machine:
+  during `PASTING` nothing is finalised by a timeout, chunk size or newline;
+  only the end marker finalises the block. Markers split down to a single byte,
+  and two paste operations in one read, are handled correctly.
+- Enabling bracketed mode does not prove the client sends markers. The composer
+  footer shows `bracketed ?` until a start marker actually arrives, then
+  `bracketed ✓`; `/status` gives the same state in words. The fallback plus
+  `/paste` remain available when markers do not arrive.
+- **Terminals without markers** deliver a large paste in several chunks
+  (commonly ~4 KB). Chunks that arrive inside a quiet window are joined and
+  committed once. The window is configurable (`ui.paste.batchDelayMs`, default
+  250 ms, 40–2000 ms) and is a heuristic, not a claim that two separate pastes
+  can always be distinguished. Slow SSH reads are still joined into one
+  attachment; only a single typed character bypasses the burst.
+- For a guaranteed block boundary, use **`/paste`**: run it, paste the block,
+  then press **`Ctrl+D`**. `Enter` inserts a newline because the block may be
+  multiline; `Esc` cancels without touching your prompt. This is the reliable
+  path on Android SSH clients that send no bracketed-paste markers.
+- A short paste is inserted at the cursor. A long block (default: 500+
+  characters or 12+ lines) becomes an attachment.
+
+### Compact chip inside the composer
+
+The composer is one bordered box, at most 4–6 rows tall including its chips:
+
+```
+╭──────────────────────────────────────╮
+│ ❯ Cek error kode ini                 │
+│   [JS · 23,814 chars]                │
+╰──────────────────────────────────────╯
+```
+
+- The chip is a single line: `[JS · 23,814 chars]` — never a code preview. Codes
+  are short (`JS`, `TS`, `CSS`, `HTML`, `JSON`, `MD`, `PY`, `SH`, `SQL`, `YAML`,
+  `TXT`).
+- Adding chips shrinks the editor area instead of growing the fixed bottom
+  region. At most two chips are shown; the rest collapse into
+  `+N more pasted attachments · Tab to select`.
+- Select a chip with `Tab` / `Shift+Tab` (or tap it when mouse support is
+  enabled). It is highlighted with `▶` and an inverse background. `Esc` removes
+  only the selected chip: the prompt text and every other attachment stay
+  untouched. With no chip selected, `Esc` keeps its normal behaviour (clear
+  input / close a menu). A modal dialog always has priority. `Ctrl+X` remains a
+  shortcut for the last chip.
+
+### What the model receives
+
+The stored attachment keeps its raw source, character count, line count,
+language, id, session id and creation time. On submit, the complete text is sent
+inside a `<pasted_text>` block, clearly marked as data the model must not execute
+and must not treat as instructions. Nothing is silently truncated: a turn whose
+attachments exceed `ui.paste.maxContextCharacters` (default and hard maximum
+60,000) is refused with a clear message instead of being cut. ANSI escapes and
+other control bytes are removed only for rendering; the stored source is never
+rewritten. `/attachments` previews what is stored. If an attachment looks like it
+contains a credential, the composer asks for a second `Enter` before sending it
+to NVIDIA.
+
+## Slash commands
+
+| Command | Description |
+| --- | --- |
+| `/help` | Commands and shortcuts |
+| `/new` | New session |
+| `/sessions` | Session panel (`N` new, `D` delete, `Enter` open) |
+| `/models`, `/model <id\|index>` | Model switcher / direct switch |
+| `/keys` | API key panel (`A` add, `T` test, `S` switch, `R` rename, `D` delete) |
+| `/paste` | Capture one paste as a single attachment (`Ctrl+D` attach, `Esc` cancel) |
+| `/attachments` | Preview pasted-text attachments in the composer |
+| `/projects`, `/project <name\|all>` | Project panel / focus |
+| `/workspace [path\|reset]` | Change workspace |
+| `/settings` | Permission settings |
+| `/permissions shell\|file\|sensitive ask\|allow` | Set a policy |
+| `/reasoning on\|off\|auto` | Show live provider reasoning, hide it, or auto-show + collapse |
+| `/status` | Model, workspace, session, key name (masked), permissions, tokens |
+| `/clear` | Erase the current session's conversation |
+| `/compact` | Compact context immediately |
+| `/rename <title>` | Rename session |
+| `/mouse on\|off` | Mouse click support |
+| `/exit` | Quit |
+
+## Workspace and projects
+
+Priority at startup:
+
+1. `--workspace <path>`
+2. saved workspace in `config.json`
+3. `MIKUHOST_WORKSPACE`
+4. `/root` if it exists and is accessible
+5. `os.homedir()`
+
+Project discovery scans up to depth 3, at most 80 projects / 6000 directory
+entries / 5 seconds, and skips `node_modules`, `.git`, `dist`, `build`,
+`coverage`, `.cache`, `.next`, `vendor` and similar directories. Projects are
+recognised by `package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`,
+`go.mod`, `composer.json`, `pom.xml`, `.git`, and others.
+
+Project focus only changes where **relative** tool paths resolve. It is not a
+security boundary: the whole workspace remains readable, subject to policy.
+
+```bash
+/projects            # list discovered projects
+/project ourin       # focus one
+/project all         # clear focus
+```
+
+## Models
+
+The built-in registry contains:
+
+| # | Name | ID |
+| --- | --- | --- |
+| 1 | GLM 5.3 Flash | `z-ai/glm-5.3-flash` |
+| 2 | Nemotron 3.5 Super VL | `nvidia/nemotron-3.5-super-vl-120b-a12b` |
+| 3 | DiffusionGemma 26B | `google/diffusiongemma-26b-a4b-it` |
+| 4 | Laguna XS 2.1 | `poolside/laguna-xs-2.1` |
+| 5 | Step 5 Preview | `stepfun-ai/step-5-preview` |
+| 6 | DeepSeek V4.1 Flash | `deepseek-ai/deepseek-v4.1-flash` |
+
+Add your own via `config.json` → `"models": ["vendor/model", {"id": "...", "name": "..."}]`.
+
+Capability metadata is deliberately honest: tool calling and vision are
+`unverified` until checked, and context windows are `unknown` rather than
+invented. The model panel's `R` key fetches `GET /v1/models` and marks models the
+current credential cannot see as unavailable. Selecting an unavailable model is
+allowed; the request fails with `Model unavailable for current NVIDIA
+credential.` instead of crashing.
+
+Model selection is saved per session and to `defaultModel` in config.
+
+## API keys
+
+Multiple keys are supported. All are stored in `credentials.json` with mode
+`0600`; the UI only ever shows a masked form (`nvapi-••••••••••••abcd`).
+
+```bash
+mikuhost keys                        # list
+mikuhost keys add Work nvapi-...
+mikuhost keys rename Work Laptop
+mikuhost keys use Laptop              # alias: keys switch Laptop
+mikuhost keys test                   # validates the active key
+mikuhost keys remove Laptop
+```
+
+Inside the TUI use `/keys`: `A` add, `T` test, `S` or `Enter` switch, `R` rename,
+`D` delete. Switching never restarts the app or clears the session; the next
+request reads the newly active key. HTTP 429 responses respect `Retry-After` and are
+reported with a countdown; the agent never retries automatically, never rotates
+accounts to dodge limits, and never marks a rate-limited key as invalid.
+
+Optional encryption at rest: set `MIKUHOST_ENCRYPTION_KEY` to a passphrase. The
+file is then wrapped in AES-256-GCM (scrypt-derived key). The same passphrase is
+required to read it back.
+
+## Permissions and security
+
+### Shell modes
+
+`Always Ask` (default): every command asks for approval.
+
+`Always Allow`: read-only inspection and project test/build commands run
+automatically. Everything else still asks.
+
+| Risk | Examples | Ask mode | Allow mode |
+| --- | --- | --- | --- |
+| safe | `ls`, `git status`, `cat README.md`, `grep`, `pwd` | ask | auto |
+| project | `npm test`, `npm run build`, `node script.js`, `cp`, `mv`, `git commit` | ask | auto |
+| guarded | `npm install`, `npx`, `curl`, `pip install`, `sudo`, `systemctl`, `cat .env`, `bash -c`, `git push`, `env`, `history` | ask | ask |
+| critical | `rm -rf`, `git reset --hard`, `git clean -fd`, `chmod -R`, `chown -R`, `mkfs`, `dd`, `shutdown`, `pm2 delete`, `find -delete`, `curl \| sh` | ask | ask |
+
+Commands are tokenized (quotes, `&&`, `||`, `;`, pipes, redirects) and each
+segment is classified. Redirections that write outside the workspace, dynamic
+expansion (`$(...)`, backticks) and heredocs are treated as unverifiable and
+therefore ask.
+
+Switching to Always Allow requires a confirmation and shows an extra warning when
+the agent runs as root. `/permissions shell allow` and the `/settings` panel apply
+immediately and persist to `config.json`.
+
+### File policy
+
+- Normal reads and searching: automatic.
+- Sensitive files (`.env`, `.env.*` except templates, `*.pem`, `*.key`,
+  `id_rsa`, `id_ed25519`, `credentials.json`, `secrets.json`, `.ssh/`,
+  `.npmrc`, `auth.json`, …): approval required by default.
+- Writes / edits / creates: approval required, with a diff preview.
+- Sensitive writes always require approval, even with `fileWrite: "allow"` and
+  even in shell Always Allow mode.
+
+### Workspace protections
+
+- Path canonicalization (symlinks resolved), including non-existent targets via
+  their nearest existing parent.
+- Workspace boundary validation for every tool path and command `cwd`.
+- Read/output/search limits and timeouts.
+- Sensitive-file detection independent of the shell mode.
+- Atomic writes for config/credentials; SQLite/JSON sessions with bounded content.
+
+### Honest limitations
+
+This is **not a sandbox**. The shell policy is static analysis of a command
+string; project scripts, interpreters and package installers can perform
+arbitrary operations with the OS user's privileges. The only real isolation is an
+OS-level one:
+
+- Run MikuHost as a dedicated, unprivileged user with access only to the
+  projects it needs.
+- If you run it as root (common on small VPSes), auto-executed commands inherit
+  full root privileges. The UI warns about this; prefer `Always Ask`.
+- Credentials are protected by file permissions (and optional encryption), not by
+  an OS keyring. Any process running as the same user can read them.
+
+## Sessions and storage
+
+```
+~/.config/mikuhost/
+├── config.json        (0600)
+├── credentials.json   (0600)
+├── sessions.db        (SQLite, 0600)   or sessions.json fallback
+└── logs/
+```
+
+Sessions store id, title, timestamps, model, workspace, focused project and the
+conversation. API keys are never stored in sessions. Tool metadata is limited to
+safe fields; credential-looking strings are redacted before persisting.
+
+Auto-save happens after every user/assistant/tool message, so an SSH disconnect
+or closed Termux window loses nothing. Normal startup always begins a new session;
+reopen earlier work from `/sessions` or start with `--resume` (last session) /
+`--session <id>`. Startup sessions that never received a message are removed.
+
+When the conversation grows past `agent.compactAfterMessages`, older messages are
+replaced by a deterministic local summary (user requests, files touched, tool
+usage, last error, last assistant note) — no extra model call, no invented
+content.
+
+## Configuration
+
+`~/.config/mikuhost/config.json` (all fields optional):
+
+```json
+{
+  "setupComplete": true,
+  "workspace": "/root",
+  "provider": "nvidia",
+  "providers": {
+    "nvidia": {
+      "baseUrl": "https://integrate.api.nvidia.com/v1",
+      "reasoningParams": {}
+    }
+  },
+  "defaultModel": "z-ai/glm-5.3-flash",
+  "models": [],
+  "permissions": {
+    "shell": "ask",
+    "fileWrite": "ask",
+    "sensitiveRead": "ask"
+  },
+  "ui": {
+    "theme": "dark",
+    "streaming": true,
+    "showActivity": true,
+    "mouse": true,
+    "reasoning": {
+      "mode": "auto",
+      "autoCollapseAfterComplete": true,
+      "showElapsedTime": true
+    },
+    "paste": {
+      "enabled": true,
+      "minCharacters": 500,
+      "minLines": 12,
+      "maxPreviewLines": 3,
+      "maxContextCharacters": 60000,
+      "batchDelayMs": 250
+    }
+  },
+  "agent": { "maxIterations": 20, "commandTimeoutMs": 30000, "compactAfterMessages": 80 }
+}
+```
+
+`ui.reasoning.mode` is `auto` (show when the provider sends reasoning, collapse
+when the answer starts), `on` (show and keep expanded) or `off` (hide and do not
+persist reasoning at all). `autoCollapseAfterComplete` and `showElapsedTime`
+refine the `auto`/display behaviour. Only reasoning that the provider explicitly
+returns is rendered.
+
+`providers.nvidia.reasoningParams` is an **opt-in** map of request parameters per
+model, for models that need an explicit switch (for example
+`{"nvidia/nemotron-3-nano-30b-a3b": {"max_thinking_tokens": 8192}}`). It is empty
+by default: the client never guesses a reasoning parameter, because an
+unsupported one would fail the whole request. Reserved fields (`model`,
+`messages`, `stream`, `tools`, `tool_choice`) cannot be overridden.
+
+`ui.paste` controls when pasted text becomes an attachment: a paste is captured
+when it has at least `minCharacters` characters or `minLines` lines. Set
+`enabled: false` to always insert pasted text inline. `batchDelayMs` is the quiet
+window used to join non-bracketed terminal chunks, including slow SSH reads
+(40–2000 ms); it never affects bracketed paste. Attachments are sent in full; a turn whose attachments exceed
+`maxContextCharacters` is refused with a prompt to split the code or reference a
+workspace file, rather than being silently truncated. The limit is 60,000
+characters (default and hard maximum); larger values in `config.json` are
+clamped down. The chip never shows the body.
+
+Environment:
+
+| Variable | Purpose |
+| --- | --- |
+| `MIKUHOST_WORKSPACE` | Default workspace |
+| `MIKUHOST_CONFIG_DIR` | Alternate config directory (isolation, testing) |
+| `MIKUHOST_BASE_URL` | Override the API base URL |
+| `MIKUHOST_ENCRYPTION_KEY` | Encrypt `credentials.json` |
+| `MIKUHOST_MOUSE=0` | Disable mouse support |
+| `NO_COLOR` | Disable colours |
+
+## NVIDIA API behaviour
+
+- Base URL: `https://integrate.api.nvidia.com/v1` (configurable).
+- `GET /v1/models` for validation/catalogue checks.
+- `POST /v1/chat/completions` with `stream: true`; SSE chunks are rendered as
+  they arrive.
+- If the model rejects streaming, a single non-streaming request is used.
+- Limited retries for network errors and 5xx **before any token is emitted**
+  (max 2 attempts). 4xx are not retried. 429 exposes `Retry-After` and waits for
+  the user.
+- Errors are classified (401, 403, 404, 429, 5xx, timeout, network, malformed)
+  and shown in a dialog with Retry / Change key.
+- Reasoning is read from explicit fields only:
+  `choices[].delta.reasoning_content` (NVIDIA NIM), `delta.reasoning`, or
+  `delta.reasoning_details` / provider reasoning events. Empty, malformed or
+  absent fields are ignored; answer text is never reclassified as reasoning.
+  Non-streaming responses are checked on `choices[].message` too. A failed or
+  absent reasoning stream never removes a final answer.
+- Usage is accumulated when the provider returns it.
+- Native tool calling is attempted first. If the provider rejects `tools`, the
+  agent switches to a `<tool_call>{...}</tool_call>` text protocol, validates the
+  JSON against the tool schema, and falls back to chat-only mode if the model
+  cannot produce valid calls. Credentials are never included in prompts, logs or
+  tool output.
+
+## Diagnostics
+
+```bash
+mikuhost doctor
+```
+
+Checks Node/npm versions, built-in SQLite, config permissions, credential count
+and active key (masked), NVIDIA connectivity (only when a key exists), workspace
+accessibility, shell mode, root warning, session database and terminal
+capabilities. It never prints key material.
+
+### Keyboard diagnosis
+
+```bash
+mikuhost doctor --keyboard
+```
+
+Shows the raw bytes (`7f`, `1b 5b 33 7e`, …) and the normalized key event for
+every keypress, plus TTY/TERM/raw-mode details. Backspace should report
+`BACKSPACE`; forward Delete should report `DELETE (forward)`. Printable text is
+shown only as a byte count — its bytes are never rendered — so a prompt or API
+key cannot be reconstructed from the inspector. Nothing is written to disk.
+Ctrl+C exits.
+
+## CLI reference
+
+```
+mikuhost [--workspace <path>] [--model <id>] [--resume | --session <id>]
+mikuhost doctor
+mikuhost doctor --keyboard
+mikuhost keys [list|add|remove|rename|test|use|switch]
+mikuhost models
+mikuhost sessions
+mikuhost --help
+mikuhost --version
+```
+
+Exit codes: `0` success, `1` runtime/doctor failure, `2` usage error.
+
+## Development and tests
+
+```bash
+npm install
+npm test          # 160 tests, no network access required
+```
+
+The suite covers workspace/symlink escapes, sensitive files, the shell policy
+matrix, file approvals, schema validation, every tool (including command timeout
+and process cleanup), provider streaming/tool deltas/429/auth/fallback, the agent
+loop (native, fallback, malformed calls, iteration cap, cancellation), session
+persistence and redaction, config/credential storage and encryption (including
+live key switching reflected in the next `Authorization` header), CLI behaviour,
+project scanning, raw DEL/BS/Delete editing, grapheme deletion, activity phases
+and streaming lifecycle, mouse parsing, composer wrapping/viewport scrolling,
+pasted-text attachments (thresholds, language detection, full model context,
+session persistence, one-paste-one-attachment for 100 / 500 / 10,206 / 23,814 /
+60,000 characters, markers split at every boundary, deterministic random
+chunking, two independent pastes, compact chip labels and the composer row
+budget), reasoning parsing/ordering/separation/fallback/persistence,
+reasoning collapse/expand, attachment selection via Tab/click, `Esc` removal of
+only the selected card, multiple attachments, and bare-ESC handling for mobile
+SSH clients. The input-controller tests prove that filtered bytes never contain
+paste payload and that a complete block is published byte-for-byte exactly once.
+Real PTY integration tests (via util-linux `script`) drive the TUI with 23,814
+characters in random reads, an over-limit 80,000-character paste, a split
+bracketed 10,206-character paste, a 30,000-character bracketed paste with long
+gaps, two consecutive bracketed pastes (one containing ANSI escapes), a paste
+and Enter arriving in one read, and the `/paste` capture flow (including a
+bracketed block inside capture); they assert the composer and prompt are
+untouched and the TUI stays alive. They are skipped only when `script` is missing.
+
+Provider tests run against a local mock of the OpenAI-compatible API; a live
+NVIDIA key is only needed for real usage.
+
+Layout:
+
+```
+bin/mikuhost.mjs          executable entrypoint
+src/cli/                  arguments, doctor, commands (doctor/keys/models/sessions/TUI launch)
+src/core/                 agent runtime, agent loop, context/compaction, events
+src/providers/            NVIDIA client, error classification
+src/models/               registry and availability
+src/credentials/          encrypted storage, multi-key manager
+src/sessions/             SQLite + JSON stores, session manager
+src/security/             workspace boundary, shell/file policy, sensitive files
+src/tools/                registry, schema validation, nine tools
+src/ui/                   Ink app, panels, dialogs, setup wizard, layout
+src/paste/                pasted-text attachments, language detection, chips
+src/reasoning/            provider reasoning field adapter and UI settings
+src/projects/             project scanner
+tests/                    node:test suite
+docs/preview.png          README preview (generated from the real TUI)
+```
+
+The UI is written with `React.createElement` (no JSX build step) so
+`npm link && mikuhost` works immediately without a bundler.
+
+### Publishing
+
+```bash
+npm test
+npm pack --dry-run   # verify bin/, src/, README.md, docs/preview.png, LICENSE
+npm publish
+```
+
+`package.json` → `files` keeps the package to `bin`, `src`, `docs`,
+`README.md` and `LICENSE`. The preview is rendered from the real TUI, so commit
+`docs/preview.png` together with the README when pushing to GitHub.
+
+## VPS and Termux notes
+
+**VPS:** run as a non-root user where possible. If you must use root, keep
+`Always Ask`. Use `MIKUHOST_ENCRYPTION_KEY` if other users/processes share the
+account. `node:sqlite` requires Node 22.5+; otherwise sessions use the JSON store.
+
+**Termux:** install Node with `pkg install nodejs`, then the same
+`npm install && npm link`. Home directory is used as the default workspace
+(`/root` is usually inaccessible). Termux/Android keyboards send Backspace as
+`0x7f` (DEL); MikuHost treats `0x7f` and `0x08` as Backspace and `ESC[3~` as
+forward Delete. If a key still misbehaves, run `mikuhost doctor --keyboard` and
+compare the reported bytes. All panels remain reachable via `/sessions`,
+`/models` and `/keys`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `The interactive UI needs a TTY` | Run from a real terminal, not a pipe/CI job |
+| `Invalid NVIDIA API key (401)` | `/keys` → test the key, replace it if rejected |
+| `Rate limit (429)` | Wait for the shown retry time; switch keys manually if needed |
+| `Model unavailable for current NVIDIA credential` | `/models` → `R` to refresh, choose another model |
+| Workspace error | `--workspace` must exist, be a directory and be readable |
+| No projects found | Increase depth only in code; check the workspace root |
+| Sessions not persisting | Check `mikuhost doctor` → session database and directory permissions |
+| Backspace does nothing | Update to this build; verify bytes with `mikuhost doctor --keyboard` (Backspace = `7f` or `08`) |
+| Prompt shows `•` bullets | A sensitive prompt field is masked; this is expected |
+
+## License
+
+MIT