deel-local-cli 0.9.0 → 1.0.0

package/README.en.md

@@ -23,7 +23,7 @@ Zero dependencies · Node 20+ · Exactly one place your source can go
  │ This PC  337 skills · 127 commands · 42 plugins              │
  ╰──────────────────────────────────────────────────────────────╯
 
- ▏myproject ▏qwen2.5-coder:7b ▏▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏◇ medium·save ▏auto
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱▱▱ 22% 28k/128k ▏ ◎ 종합 · ◇ medium·절약 · auto
  ❯ unify the logging style
 
   ❊ Grep(console.log)
@@ -33,7 +33,7 @@ Zero dependencies · Node 20+ · Exactly one place your source can go
   ◈ Edit(src/runner.js)
     └ 1 spot
 
-  Unified log calls to the logger format. One change in runner.js.
+  ▌ Unified log calls to the logger format. One change in runner.js.
 
   ── 4.2s · 3 tools · ↑3,900 ↓180
 ```
@@ -55,6 +55,7 @@ Zero dependencies · Node 20+ · Exactly one place your source can go
 - [Reasoning effort](#reasoning-effort)
 - [Auto-compaction](#auto-compaction)
 - [Resuming a conversation](#resuming-a-conversation)
+- [Attaching tools from outside (MCP)](#attaching-tools-from-outside-mcp)
 - [Safety](#safety)
 - [Corporate review package](#corporate-review-package)
 - [Configuration](#configuration)
@@ -211,16 +212,20 @@ Names follow Claude Code / Codex conventions.
 | `/help` | Command list |
 | `/context` | What is consuming the context window |
 | `/ctx [auto\|number]` | Context **length** — re-read it off the model, or set it yourself |
+| `/out [number\|auto]` | Cap on a **single reply** — raise it when large files get cut |
 | `/compact` | Summarise and fold older turns |
 | `/clear` | Clear the conversation (keeps link and rules) |
 | `/model` | Switch connection / model |
-| `/think <level\|profile>` | `off·low·medium·high·max` or `even·save·deep` |
+| `/think <level>` | Reasoning level (`off·low·medium·high·max`) |
+| `/think 배분 <profile>` | Per-stage profile (`even·save·deep`) |
+| `/think 자세히` | Stage table — which stage runs at which level and cap |
 | `/mode <mode>` | Approval policy — how much it asks (`auto` · `confirm` · `strict`) |
 | `/work [mode]` | Work mode — what kind of work you are doing |
 | `/auto` | Hand the wheel back — it picks the mode from what you type |
 | `/code` `/plan` `/architect` `/debug` `/ask` `/orchestrator` | Switch work mode directly (pins it) |
 | `/level [level]` | How much to show (`쉬움` simple · `개발자` developer) |
 | `/undo [turns]` | Revert file changes |
+| `/diff [file]` | Files changed this session, and the changed lines |
 | `/tools` | Available tools |
 | `/skills [query\|all\|off]` | Browse, search, load skills |
 | `/plugin [install\|remove\|pack]` | Manage plugins |
@@ -228,6 +233,9 @@ Names follow Claude Code / Codex conventions.
 | `/status` | Connection status |
 | `/scan [save]` | Sweep this machine for local model servers (`save` registers them) |
 | `/sessions` | Past conversations in this folder |
+| `/recall <text>` | Search past conversations **by content** |
+| `/memory` | What persists across sessions — view, add, delete |
+| `/mcp` | Externally attached tools (MCP servers) |
 | `/init` | Create a `DEEL.md` rules file |
 | `/exit` | Quit |
 
@@ -237,6 +245,43 @@ Discovered plugin commands are invoked as `/<plugin>:<name>`, with `$ARGUMENTS`
 server or loaded a different model, `/scan save` then `/model` switches over without losing
 the conversation.
 
+### Attaching a file with `@`
+
+Write `@` followed by a path and that file is sent along with your message.
+
+```
+❯ @src/a.js why is this slow?
+  ◧ attached src/a.js
+```
+
+That removes **one round-trip** — the one where the model has to call `Read` itself. Local
+models are weak at tool calling and that round-trip often misfires: it calls the wrong path,
+or skips the call and invents the contents. You already know which file it is; there is no
+reason to make the model go looking.
+
+The hard part is not attaching. It is **not mistaking something else for a file.**
+Things starting with `@` are everywhere.
+
+| What you type | What happens |
+|---|---|
+| `@src/a.js` | Attached — only when the path actually exists |
+| `hong@example.com` | Not a mention at all. A letter before the `@` means it is an address |
+| `@media` · `@dataclass` · `@scope/pkg` | Left alone — no such path exists |
+| `@src/` (a directory) | A listing of what is inside is attached |
+| `@"draft report.txt"` | Quote names containing spaces |
+| Outside the working scope | Refused, and the refusal is printed |
+| A CP949 corporate document | Decoded by content and attached correctly |
+
+There is one rule: **attach only when the path really exists.** Otherwise the text is left
+exactly as typed, silently — it probably wasn't a mention.
+
+Attachments are capped at **25% of the context length** (20,000 tokens at most). Anything larger is attached from the
+top only, and a truncated file is **not marked as already read.** Marking it read would let the
+model edit a part it never saw. Only a fully attached file lets it skip `Read`.
+
+Every attachment is announced on screen. Text the user did not type is now in the conversation;
+not showing it would also leave them wondering where the context went.
+
 ### Interrupting
 
 Press **Ctrl+C** to stop the model mid-answer when it is heading the wrong way.
@@ -349,6 +394,52 @@ Two things matter here:
 - **Beginners do not get fewer safeguards.** Undo, workspace scope and dangerous-command
   blocking are identical. A beginner needs the undo more, not less.
 
+### Two screens
+
+Launched in a terminal, deel runs **full-screen**: conversation on the left, files changed
+this session at the top right, todos below them, with a status line and an input box pinned
+at the bottom.
+
+```
+┌ 대화 ─────────────────────────────────────────────┬ 바뀐 파일 ───────────────┐
+│   ❊ Grep(console.log)                             │ src/runner.js +3-1       │
+│     └ 3 files · 11 hits                           │ src/index.js +1-1        │
+│                                                   │ src/ui/log.js +12-0      │
+│   ◈ Edit(src/runner.js)                           ├ 할 일 ───────────────────│
+│     └ 1 spot +3-1                                 │ ☑ find log calls         │
+│     - 12 console.log('시작', 이름)                │ ☑ unify runner.js        │
+│     + 12 logger.info({ 단계: '시작', 이름 })      │ ▶ unify index.js         │
+│                                                   │ ☐ update docs            │
+│   ▌ Unified log calls to the logger format.       │                          │
+│                                                   │                          │
+│   ── 4.2s · 3 tools · ↑3,900 ↓180                 │                          │
+└───────────────────────────────────────────────────┴──────────────────────────┘
+ ▏myproject · qwen2.5-coder:7b ▏ ▰▰▱▱▱▱▱▱ 22% ▏ ◎ 종합 · ◇ medium · auto ▏ ↑3.8k ↓180
+ ╭─────────────────────────────────────────────────────────────────────────────╮
+ │ ❯                                                                           │
+ ╰─────────────────────────────────────────────────────────────────────────────╯
+```
+
+**It switches itself off where it would do harm.** Piped or redirected output, `CI` set,
+`TERM=dumb`, or a window under 60×16 all fall back to the **scrolling view** without asking —
+`deel … | tee log.txt` must not become a pile of escape codes. Passing `--tui` does not
+override a pipe.
+
+| | Full-screen | Scrolling (`--no-tui`) |
+|---|---|---|
+| When | Launched in a terminal | Pipes, CI, small windows, `--no-tui` |
+| Files changed / todos | Always visible on the right (≥96 cols) | Printed inline as they happen |
+| Earlier output | Wrapped and paged inside the frame | Your terminal's own scrollback |
+| On exit | **Replays the conversation into scrollback** | Already there |
+| For keeping a log | Not this one | This one |
+
+Full-screen uses the alternate screen buffer, like vim. Exiting would otherwise erase the whole
+conversation, so the recent lines are reprinted into the real screen on the way out. Whether it
+exits on Ctrl+C or dies on an uncaught error, **the terminal is always restored.**
+
+If the full-screen view cannot be set up — an unusual terminal, anything at all — it falls back
+to the scrolling view and says why in one line. **No program should fail to start over a screen.**
+
 ---
 
 ## Tools
@@ -359,14 +450,95 @@ Names and arguments match Claude Code, so skills written for that convention wor
 |---|---|
 | `Read` | Read a file (line numbers, `offset`/`limit`, **Excel as CSV**) |
 | `Write` | Write / overwrite a file |
+| `Append` | Append to the end of a file — **how large files get written in pieces** |
 | `Edit` | Replace an exact string (`replace_all` supported) |
 | `Glob` | Find files by name pattern |
 | `Grep` | Regex search file contents |
 | `Bash` | Run a command |
 | `Skill` | Expand a skill body (shown to the model only when skills exist) |
 | `WebFetch` | Read a web page (read-only; hidden under `--offline`) |
+| `Recall` | Search **past conversations** — the model digs up "that thing last time" itself |
+| `Remember` | One line that outlives the session — known from the start next time |
 | `TodoWrite` | Checklist — breaks long work into steps and shows progress |
 
+Only **three** tools here are not in Claude Code — `Append`, `Recall`, `Remember`. Each
+tool costs roughly 150 tokens of schema on **every request**, so a test stops you every
+time the list grows (`test/loop.test.js`).
+
+### Finding past conversations, and remembering decisions
+
+deel writes every conversation to `.deel/sessions/*.jsonl`. Until now all you could do was
+list them — **a record you cannot search is the same as no record.**
+
+```
+$ /recall 인코딩을 어떻게
+
+  2026-08-01 10:15  모델    20260801-101500
+      CP949 인코딩 문제입니다. 읽을 때 인코딩을 재서 그대로 되돌려 쓰도록…
+```
+
+Korean particles are handled: `인코딩을` also matches `인코딩`. A morphological analyser is
+out of the question (zero dependencies), so particle-looking tails are stripped and **both**
+forms are searched. No index is built — an index inevitably goes stale, and **a stale index is
+worse than none** ("not found" reads as "never happened"). Instead every search reports how
+much it read and what it could not.
+
+`Recall` is also a **tool**. Left as a human-only command, "do it the way we decided last
+time" leaves the model nothing to do but ask again.
+
+**Memory (`/memory`) is a different thing.** Recall has to be *searched*; memory is *already
+there*. Things you cannot re-explain every session go here.
+
+```
+$ /memory
+
+   1  사내 문서는 CP949 로 읽고 CP949 로 되돌려 쓴다
+   2  검증할 때 7080 포트는 쓰지 않는다
+
+  2줄 · 약 30토큰이 매 요청마다 함께 나갑니다
+  파일 .deel/memory.md — 직접 고치셔도 됩니다
+```
+
+`.deel/memory.md` is **prose a human edits**, not a database. That matters: a line the model
+got wrong ships on every request and keeps being wrong. **A wrong memory is worse than none.**
+So `/memory 지우기 2` deletes one.
+
+Because it ships on every request it is bounded: 400 chars per line, 60 lines, 6,000 chars
+total. Overflow drops the oldest and says so. `/context` shows its line count and tokens.
+
+### Repeatable procedures become skills
+
+When a multi-step job finishes and it is something that will come up again, the model writes
+the procedure to `.deel/skills/<name>/SKILL.md`. Next session it appears in the skill list;
+when it turns out to be wrong somewhere, the model edits that file.
+
+No new tool needed — the existing `Write` writes it and the existing skill sweep reads it.
+
+### Large files are written in pieces — `Append`
+
+A model with a 4k output cap still has to be able to write a 2,000-line file, eight pieces at
+a time. Stitching with `Edit` does not work in practice — HTML repeats anchors like `</div>`,
+so the match comes back as "found in several places", and a longer anchor eats the tokens that
+should have gone into the body.
+
+`Write` to create, `Append` to continue. Encoding follows `Write` (CP949 for corporate
+documents, the BOM on a `.csv` is preserved). The undo snapshot is taken **only on the first
+`Append`** — eight appends must not leave eight copies in the history, or there is no single
+point to revert to.
+
+```
+  ⏺ Write(dashboard.html)
+    └ ⚠ wrote only as far as it arrived — 632 lines
+  ↻ the reply hit the cap — retrying with 9,984 → 16,384
+  ⏺ Append(dashboard.html)
+    └ +567 lines · 1,199 total
+
+  ✓ dashboard.html · 1,199 lines · 97.7KB
+```
+
+That last line matters. If the file does not exist and the model says "created it", you would
+believe it. **The real file is measured at the end of the turn.**
+
 ### Checklists
 
 Keeps the model from losing its place on multi-step work. The list is redrawn whenever the
@@ -417,6 +589,65 @@ Measured with `npm run bench`:
 
 On failure it points at the closest line in the file.
 
+### It shows you what it changed
+
+`auto` mode edits without asking. That is the speed of this tool — but if all that reaches the
+screen is `1 spot`, you move on without knowing what happened. Undo is the safety net, and
+**you cannot decide whether to undo something you never saw.** So every `Edit` and `Write` is
+followed by the changed lines themselves.
+
+```
+  ◈ Edit(src/runner.js)
+    └ 1 spot +1 −2
+
+      11 const id = job.id;
+    -    console.log("start: " + id);
+    -    console.log("  opts " + JSON.stringify(opts));
+    + 12 logger.info('start', { id, opts });
+      13 return run(job);
+```
+
+The `+1 −2` next to the summary is how many lines were added and removed.
+
+- **Removed lines carry no line number.** They no longer exist in the file. Printing the old
+  number put it directly under a context line's new number — two different files' numbering in
+  one column. Line 8 really did appear twice on screen.
+- If only the line endings changed (CRLF/LF), it says so. Otherwise every visually identical
+  line shows as changed and the real edit is impossible to find.
+- Large files are compared after trimming the identical head and tail. If it is still too big,
+  exact matching is abandoned for "this whole block changed" — a rough answer now beats an
+  exact one later.
+
+How many lines are shown depends on the level. Forty lines at someone's first launch means none get read.
+
+| | Simple | Developer |
+|---|---|---|
+| After a tool call | 14 lines | 40 lines |
+| `/diff <file>` | 60 lines | 200 lines |
+
+### `/diff` — everything changed this session
+
+Those lines scroll away. `/diff` collects every file touched this session onto one page.
+
+```
+$ /diff
+
+── files changed this session ─────────────────────────────
+  src/runner.js                     +12     −7   3×
+  src/logger.js                     +40     −0
+  ──────────────────────────────────────────────────────────
+  2 files                            +52     −7
+
+  /diff <file> for detail, /undo to revert
+```
+
+`/diff <file>` compares **the state at the start of the session against now.** Even after
+three edits, what you want to know is "what is different from before I asked", not what the
+last edit did. That original state comes from the earliest undo snapshot.
+
+`/diff` is **in the simple level's command list.** As long as `auto` edits without asking,
+a beginner needs a way to see what changed more than anyone.
+
 ---
 
 ## Korean text and Excel
@@ -453,6 +684,12 @@ Newly created files are UTF-8.
 Command output is handled the same way. A Windows console is not UTF-8, so taking `Bash`
 output as utf8 garbles non-ASCII text. It is collected as bytes and decoded afterwards.
 
+**Undo snapshots are stored as bytes too.** They used to be stored as UTF-8 text, so undoing
+a CP949 file brought back `가나다` (bytes `b0a1 b3aa b4d9`) as six U+FFFD characters — **the
+safety net itself destroyed the original bytes.** Now every snapshot is round-tripped through
+UTF-8 first; anything that does not come back identical is stored as base64 and restored
+byte-exact.
+
 ### Excel — read as CSV
 
 An Excel file is a compressed archive, not text, so normally you get "this is a binary file"
@@ -539,15 +776,14 @@ with a licence table — ready to hand to a security reviewer.
 One answer means several model calls, and **each needs a different amount of thinking.**
 All-high is slow; all-low wanders off.
 
+The default is **one line**. What you want to know is how hard it is thinking right now,
+not a stage table.
+
 ```
 $ /think
 
-  Base medium   Profile save   Hard on the first decision, light while continuing
-
-  Stage         Effort    Cap     When
-  first call    · medium   4,096  deciding what to do
-  continuing    ↓ low      2,048  reading a tool result, picking the next step
-  stuck         ↑ high     4,096  the previous tool errored
+  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
+  더 세게 /think high   더 빠르게 /think low
 ```
 
 | Profile | Character |
@@ -556,6 +792,31 @@ $ /think
 | `save` (default) | Hard on the first decision only |
 | `deep` | Everything one notch up — for hard work |
 
+Set the profile with `/think 배분 절약`. **Level and profile are different axes, so the
+commands were split** — `/think high` and `/think save` used to set different things under
+one name, which made the screen unreadable.
+
+The stage table moved to `/think 자세히` (the default at developer level).
+
+```
+$ /think 자세히
+
+  추론 강도  medium   (첫 판단 medium · 이어가기 low · 막혔을 때 high)
+  배분      절약   첫 판단만 세게, 이어가기는 얕게 — 대개 이게 낫습니다
+
+  단계        강도      출력상한  언제
+  첫 판단     · medium      15,549  무엇을 할지 정하는 자리
+  이어가기    ↓ low         13,605  도구 결과를 읽고 다음 한 수
+  막혔을 때   ↑ high        16,384  직전 도구가 오류를 냄
+
+  출력 상한은 16,384 (모르는 값이라 기본값) 안에서 나눕니다 — /out
+  컨텍스트 40,960 · 지금 찬 양 2,087
+```
+
+That second-to-last line exists for a reason: **when all three caps are equal, it is the
+only thing that says whether that is correct.** A low known cap makes them equal, and that
+is fine. For a while all three read `16,384` always — which meant the table said nothing.
+
 ### Context length is read off the model
 
 This one number sizes the whole program: how many files fit in one read, when the
@@ -595,29 +856,99 @@ the **loaded length is what deel uses**, and the maximum is reported separately.
 | `/ctx` | Current length and remaining room |
 | `/ctx auto` | Ask the server again and match the model |
 | `/ctx 655360` | Set it yourself (`640k`, `128k`, `1m` also work) |
-| `/ctx out 32k` | Cap on a **single reply** — a different axis from context |
+| `/ctx 자세히` | Which endpoints were probed and what each returned — how to see why a lookup failed |
 | `deel --ctx 655360` | Start at this value (skips the lookup) |
 
 **`k` means 1024 here.** Context lengths are all powers of two, so that is the only base
 that lines up: 655,360 is `640k`, not `655k`; 131,072 is `128k`, not `131k`. The display and
 `/ctx` use the same unit, so typing back what you see gives you the same number.
 
+### Reply length cap — `/out`
+
+Context (how much can be held) and the **output cap** (how much can come back at once) are
+different numbers. Treating them as one makes it impossible to understand why a large file
+never gets written — the context is roomy while the reply is being cut.
+
+| Command | What it does |
+|---|---|
+| `/out` | Current cap and **where it came from** (set by you / discovered / default) |
+| `/out 32k` | Set it yourself (`k` is 1024). Saved to the profile |
+| `/out auto` | Drop your value and go back to the discovered one, or the default |
+| `deel --max-tokens 65536` | Start at this value |
+
+The old name `/ctx out 32k` still works.
+
 **Caps are not fixed numbers.** They are computed from the model's context window and how
 much of it is currently used — the profile decides what share of the remaining room a stage gets.
 
-| Model | First call | Continuing | Stuck |
-|---|---|---|---|
-| 2k local | 554 | 512 | 554 |
-| 8k local | 2,007 | 1,003 | 2,007 |
-| 40k (qwen3) | 11,688 | 5,844 | 11,688 |
-| 128k gateway | 16,384 | 16,384 | 16,384 |
-| 128k, 80% full | 7,680 | 3,840 | 7,680 |
+| Model | First call | Continuing | Stuck | Retry after truncation |
+|---|---|---|---|---|
+| 2k local | 819 | 716 | 921 | 1,638 |
+| 8k local | 3,276 | 2,867 | 3,686 | 6,553 |
+| 40k (qwen3) | 16,384 | 14,336 | 16,384 | 16,384 |
+| 128k gateway | 16,384 | 16,384 | 16,384 | 16,384 |
+| 128k, 80% full | 10,485 | 9,174 | 11,796 | 16,384 |
+| 640k with `/out 65536` | 65,536 | 65,536 | 65,536 | 65,536 |
 
 Caps shrink as the context fills. Handing a 4k model a 4,096-token cap would leave no room for input.
-Raise the ceiling with `maxTokens` in the profile if you need more.
 
-If a saved cap truncates a reply, **that step alone is retried with the cap lifted.**
-A truncated reply means a half-written tool call, which fails silently.
+The last row is the point: **a known cap overrides the 16,384 default.** For a while it did
+not — the third argument of `Math.min(cap, max ?? 16384, 16384)` clamped it right back, so a
+configured cap could only be lowered, never raised. Meanwhile the comment, the README, and the
+on-screen help all said it could be raised. A documented escape hatch that is welded shut is
+the worst kind.
+
+If a cap truncates a reply, **the call is retried with the cap lifted** — and the thinking
+level drops one notch, because reasoning tokens eat the same budget first. Without that, more
+headroom just buys more thinking. A truncated reply means a half-written tool call, which fails silently.
+
+**When the server refuses, it is read for the answer.**
+
+```
+This model's maximum context length is 8192 tokens, however you requested 41003
+```
+
+The number is extracted, applied, and the call is retried. You never see the failure.
+No spec knowledge is needed, so **this works against servers we have never seen.**
+
+### Truncated tool calls
+
+This actually happened. A user asked for a dashboard; the model tried to put an entire HTML
+document into `Write`'s arguments, hit the output token limit, and the arguments JSON arrived
+cut off mid-string.
+
+The old code quietly turned that unparseable JSON into `{_raw: "..."}` and handed it to the
+tool. The tool answered `path is empty` — **a message with nothing to do with the real cause.**
+The model had not omitted the path, so there was nothing to fix; it retried identically, and
+was truncated again.
+
+```
+  ◆ Write(dashboard.html)
+    └ path is empty          ← nine identical times
+
+  ── 71s · 13 tool calls · context filled and auto-compacted · no file produced
+```
+
+One silently swallowed value produced all of that. What happens now:
+
+| | Now |
+|---|---|
+| Unparseable arguments | **Marked as truncated**, not swallowed. Never passed to the tool |
+| The model is told | Exactly what happened, and to stop resending the whole thing — write a short skeleton first, then **build it up with `Edit`** |
+| The truncated payload | Never re-injected into the conversation — it is half a payload and it costs context |
+| Detecting truncation | Even when the gateway reports `finish_reason: "stop"`, **broken arguments are themselves proof it was cut.** No model writes half a JSON object on purpose |
+| Three identical failures | The turn stops, with a suggestion to split the request |
+
+```
+  ⊘ Stopped — it is spinning in the same place.
+    the same tool call keeps getting truncated
+    What you asked for in one go is larger than the model's output cap. Try splitting it —
+    e.g. "just the skeleton first" → "now add the table" → "now add the chart"
+```
+
+**A step limit (`maxSteps`) cannot catch this.** It cannot tell a long healthy task from a
+spinning one. What is counted here is not steps but **how many times the same tool failed for
+the same reason.**
 
 ---
 
@@ -670,6 +1001,43 @@ covers `.deel/` so it never reaches a repository.
 
 ---
 
+## Attaching tools from outside (MCP)
+
+A corporate wiki search, an issue tracker, a DB query tool — if a team publishes one as an MCP
+server, deel uses it as a tool **without a code change**.
+
+Configure in `.deel/mcp.json`. A Claude Code config can be copied over verbatim:
+
+```json
+{ "mcpServers": { "wiki": { "command": "node", "args": ["wiki-mcp.js"] } } }
+```
+
+The model sees it as `mcp__wiki__search`. `/mcp` shows what is attached.
+
+**Dependencies stay at zero.** The stdio transport is nothing but newline-delimited JSON-RPC
+2.0 over a child process's stdin/stdout, so `child_process` and `JSON` cover it. No SDK.
+
+### But this is somebody else's program
+
+This project exists because unapproved software is blocked. Turning on MCP carelessly would
+tear down that line with our own hands. So:
+
+| | |
+|---|---|
+| **Off by default** | Nothing runs unless it is in `.deel/mcp.json` |
+| **Never under `--offline`** | We cannot police where a child process connects. **We do not claim to block what we cannot block** |
+| **Outside the working scope** | MCP servers do not honour our fence. The `/mcp` screen says so |
+| **Audited** | What was launched and what was called, in `.deel/audit.jsonl` |
+| **No key passthrough** | Our environment is not forwarded wholesale — a `DEEL_*` gateway key in someone else's process goes somewhere we cannot see |
+| **Not in read-only modes** | A tool named "search" can still write files. Handing an unknown to plan/architect mode would make that promise meaningless |
+| **24 tools per server** | Schemas ship on every request. Past that they are dropped, and **the drop is reported** |
+
+One server crashing, hanging, or talking nonsense does not affect the others. Failures are not
+swallowed — the reason appears in the header, because a silent drop leaves "why is that tool
+missing?" unanswerable.
+
+---
+
 ## Safety
 
 Instead of approval prompts, the design makes things **reversible**. The default `auto` mode
@@ -678,10 +1046,13 @@ does not ask.
 | Mechanism | Detail |
 |---|---|
 | **Undo** | Snapshot before every write. `/undo` restores per turn |
+| **Change display** | The changed lines are shown on every edit; `/diff` for the whole session |
 | **Scope** | Outside the starting folder is refused, even if the model insists |
 | **Blocked commands** | Only irreversible ones (disk format, recursive delete, `--force` push) |
 | **No re-run** | A mutating command is never retried after failure |
 | **Interrupt** | Ctrl+C stops mid-answer and leaves the conversation valid |
+| **Spin guard** | Three identical failures stop the turn, with the reason |
+| **Not read** | Other tools' private stores, and deel's own logs and config (the key), are refused |
 | **Audit log** | Everything recorded in `.deel/audit.jsonl` |
 
 | Mode | Asks when |
@@ -694,6 +1065,43 @@ Undo history stores whole file contents, so repeated edits to large files add up
 it keeps the **most recent 50 turns** and drops the rest. What you just did is always
 undoable; `/status` shows how large the history currently is.
 
+### What it will not read
+
+Walking a folder turns up things that are not project files: the private stores other coding
+tools keep — past conversations, command history, caches, and keys. They have nothing to do
+with the task, but once they appear in a listing the model reads them first.
+
+```
+  ◧ Read(~/.deel/audit.jsonl)      77 lines
+  ◧ Read(~/.claude/history.jsonl)  35 lines
+```
+
+The audit log is **this program's own record of what it just did.** Reading it back into the
+conversation makes the model chase its own shadow. It has nothing to do with what was asked,
+and it fills the context.
+
+The config file is worse. `.deel/config.json` holds the gateway **API key.** Reading it puts
+that key into the conversation, sends it to the model, and writes it into the on-disk session
+log. It hands the key to the very service the key is for.
+
+| Refused | Why |
+|---|---|
+| `.deel/config.json` | Contains the gateway key |
+| `.deel/audit.jsonl` · `.deel/sessions` · `.deel/history` | deel's own records — chasing its own shadow |
+| `.claude` `.codex` `.cursor` `.gemini` `.aider` `.continue` `.cline` `.roo` `.kilocode` `.windsurf` `.opencode` `.zed` `.trae` `.augment` `.qodo` `.tabnine` `.cody` `.sourcegraph` `.copilot` `.amazonq` `.junie` `.codeium` `.goose` `.crush` `.gptme` `.openhands` `.devin` | Other tools' private stores |
+| File-style leftovers like `.aider.chat.history.md` | Same reason |
+
+Writing is blocked too, not just reading. Blocking only reads would still let the agent
+overwrite another tool's settings, and overwriting `.deel/config.json` destroys the connection.
+
+**It blocks, it does not hide** — the refusal says exactly why. New tools keep appearing;
+when a name is missing from the list, **adding it is one line.**
+
+That list lives in **exactly one place in the source.** The directory walker (`SKIP_DIRS`) and
+the read guard look at the same set. They used to be two copies, and two copies means the day
+comes when only one of them learns a new name — a folder that is skipped while walking but
+readable if you name it directly, which is very hard to explain.
+
 ---
 
 ## Corporate review package
@@ -780,11 +1188,14 @@ deel --root <folder>     Working scope. Defaults to the current folder
 deel --mode <mode>       auto (default) / confirm / strict
 deel --work <mode>       auto (default) / code / plan / architect / debug / ask / orchestrator
 deel --level <level>     쉬움 (simple) / 개발자 (developer)
+deel --ctx <length>      Set the context length yourself (655360 · 640k · 128k)
+deel --max-tokens <len>  Cap on a single reply (32k) — same value as /out
 deel --think <level>     off / low / medium (default) / high / max
 deel --effort <profile>  even / save (default) / deep
 deel --offline           Nothing leaves this machine
 deel --continue          Resume the most recent conversation
 deel --resume <id>       Resume a specific one
+deel --no-tui            Turn the full-screen view off; use the scrolling view (see below)
 ```
 
 ### Project rules
@@ -805,7 +1216,9 @@ If the working folder has `DEEL.md`, `CLAUDE.md` or `AGENTS.md`, it is loaded as
 | 401 / 403 | Wrong key or auth header style (four are tried automatically) |
 | `address not permitted` | The lock did its job — pick a connection with `/model` |
 | Tool calls don't work | Run `deel diagnose`. Small models (1B–3B) often can't |
-| Empty replies | A heavy-reasoning model — try `/think low` |
+| Empty replies | The server ignores streaming. deel retries once, then turns streaming off for the session |
+| Large files cut off mid-write | Check `/out` and raise it — the cap may be sitting at the 16,384 default because it could not be discovered |
+| Only `HTTP 400` shows | The server's own message is shown verbatim. If it is a length problem the number is read and applied automatically |
 | `deel scan` finds nothing | Server is off or on another port — use `--ports` |
 
 ---
@@ -813,11 +1226,12 @@ If the working folder has `DEEL.md`, `CLAUDE.md` or `AGENTS.md`, it is loaded as
 ## Development
 
 ```bash
-npm test        Full suite (254 checks)
-npm run verify  Import + network checks only
-npm run bench   Edit success rate
-npm run demo    See what the UI actually looks like
-npm run check   Syntax check every file
+npm test          Full suite (1,745 checks)
+npm run coverage  Which lines the tests actually execute
+npm run verify    Import + network checks only
+npm run bench     Edit success rate
+npm run demo      See what the UI actually looks like
+npm run check     Syntax check every file
 ```
 
 Tests run against a **fake gateway**, so the loop, streaming, tool execution, undo and compaction
@@ -834,17 +1248,46 @@ so one run tells you everything.
 |---|---|---|
 | `smoke` | 20 | Tools, scope, undo, audit log |
 | `loop` | 16 | Agent loop, streaming, tool calls |
+| `guard` | 24 | **What it refuses to do** — denied edits, unknown tools, repeated mutations, out-of-scope writes |
 | `network` | 30 | Nothing escapes the configured address |
 | `web` | 25 | Web reads stay read-only |
 | `abort` | 16 | Ctrl+C leaves the conversation valid |
 | `parallel` | 23 | Read-only tools run together; checklists |
+| `cli` | 75 | **Spawns the real `deel`** and drives it to completion |
+| `setup` | 42 | First-run wizard, driven through a fake TTY |
+| `detect` | 66 | Identifying shape and auth from one address |
+| `modes` · `route` | 89 · 33 | Work modes; auto-switching from Auto |
+| `ctxsize` | 43 | Reading context length off the model |
+| `commands` · `commands-more` | 128 · 62 | Every slash command |
+| `ui` · `ui2` | 60 · 40 | Password masking, CJK width, status line, session list, Excel→text |
+| `encoding` · `xlsx` | 68 · 72 | Legacy-encoding detection; Excel reading |
 | `compact` | 21 | Summary folding, pairing intact, graceful fallback |
 | `store` | 34 | Session persistence, resume, crash recovery |
-| `scan` | 19 | Distinguishing multiple runtimes |
+| `scan` | 29 | Distinguishing multiple runtimes |
 | `plugins` | 38 | Plugin fetch/pack, ZIP/TAR |
 | `no-bundle` | 12 | Nothing foreign in the published package; test-file hygiene |
 | `edit-bench` | 20 cases | Edit success rate |
 
+### Coverage
+
+```bash
+npm run coverage                           Summary
+node test/coverage.mjs --file src/repl.js  One file in detail
+node test/coverage.mjs --json              Machine-readable
+```
+
+Zero dependencies rules out c8 and nyc, so this reads Node's own
+`NODE_V8_COVERAGE` instead — nothing new to get through an import review. It picks up
+child processes too, so the `cli` suite that spawns `deel` counts like everything else.
+
+Currently **92% overall** (6,960 of 7,570 lines). Three files are deliberately left short.
+
+| File | Now | Why it stops there |
+|---|---|---|
+| `tools/excel.js` | 67% | The password path needs Excel installed and a genuinely encrypted file. Faking it would produce a test that only *looks* like it passes |
+| `repl.js` | 77% | The keypress paths — Shift+Tab, Ctrl+C, password entry, paste. Reaching them needs a pty, and a pty is a dependency. What the screen *prints* is measured instead, as a value (`ui` and `tui` suites) |
+| `plugins/manage.js` | 79% | The GitHub download path. **Tests not reaching the network** matters more. Folder installs are covered |
+
 ---
 
 ## Licence