@thincoder/core 0.10.13 → 0.11.1

package/tool-docs/doc_check.md

@@ -2,12 +2,20 @@ Run a built-in documentation-discipline check on a project and report its findin
 Read-only. In the default `report` mode it is non-gating: it reports, it never blocks, never sets an exit code, and its output is never a reason to refuse a task or a user instruction.
 
 What it checks — exactly two criteria, both built into the engine:
-- Anchors — every documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
+- Anchors — a documentation pointer (a `*.md` token, optionally carrying directory segments, optionally followed by a section
   indicator `§N` / `§N.M` / `§N.M.K`) must resolve: the file must exist on disk (`档缺` when it does not), and when a section
   indicator is given the target file must carry a heading numbered with it (`节缺` when it does not). Line-number coordinates
 
   (`<doc>:12`) are not section references and are not judged as such. Files inside fenced code blocks and executable lines
   (command / pattern code spans) are skipped whole.
+- **The reach is what survives extraction, not every `.md` token.** Three name families are never extracted, so they are never
+  judged: **conventional file names** used to say which files get read (`AGENTS.md`, `SKILL.md`, `project_rules.md`, `todo.md`
+  and the rest of that closed set),
+
+  **placeholder stems** (single letters plus the usual sample words — `x.md`, `file.md`, `foo.md`, `example.md`), and — on the
+  prompt face only — the seven operand names the `Operand names` block below lists.
+
+  A `.md` token outside those families is judged even when misspelled: a wrong name reports `档缺`, never a pass.
 
 ~~~text
   **Operand names.** Seven names count as operands rather than documents: the model writes them, or reads a file by that name. On
@@ -21,15 +29,41 @@ What it checks — exactly two criteria, both built into the engine:
   ```
 ~~~
 
-- Paragraph length — on a document face, adjacent non-blank body lines merge into one paragraph whose total character
+- Citation check — the same criterion, one more hit class `引缺` (a line that claims its own basis).
+
+  A claim line writes `依据 <document path>「<verbatim quotation>」`, and the quoted text must appear as a contiguous substring
+  of the file that path resolves to; when it does not, the hit is `引缺` and the report names the path plus the first 40 characters.
+
+  The path is judged for existence first: a path that does not resolve reports `档缺`, never `引缺` — the fix differs
+  (check the path ∥ check the words). Both classes count into the one `锚` total: no third criterion, no new verdict word.
+
+  Between the path token and `「` only the optional separator (`:` ∥ `：` ∥ `=`) and an optional backtick may sit. Anything else
+  (a space, a prose word, a punctuation mark) means the line is not a basis marker and nothing is judged; an empty `「」` is not a marker either.
+
+  A path whose name falls in the exempt families above is not a marker path either — the same exemption decides both faces.
+
+  Existence only: no whitespace folding, no case or width folding. A verbatim quotation taken from the wrong place still passes —
+  whether it is the *right* basis (a contract rather than a comment) belongs to review, and this tool does not claim to judge it.
+
+
+- Paragraph length — on every non-prompt face, adjacent non-blank body lines merge into one paragraph whose total character
   count (CJK counts as 1) is judged against the built-in threshold; blank lines, table rows, headings, list items,
   quote-block lines and fenced code blocks do not count into a paragraph and break it, and lines inside an exempt zone
 
-  are excluded. Breaking a paragraph into more lines changes nothing — only splitting it into more paragraphs or
-  writing it shorter passes.
+  are excluded. No face is exempt: a tool-description file (`thincoder-core/tool-docs/**`, this file included) is judged on
+  this criterion too — a long paragraph hides its later points from every reader, the model included.
+
+  Breaking a paragraph into more lines changes nothing, and clearing the length check is not the same as fixing it: splitting a
+  paragraph into more paragraphs, or writing it shorter, clears the count while the reader still faces the same packed paragraph.
+
+  What fixes it is fewer and shorter sentences, a list of named items where the paragraph holds parallel assertions, or a table
+  where it holds enumerated readings.
 - Line length — a prompt-face file (`thincoder-core/prompts/**`) is judged line by line: the model reads raw text, so
   one line is one block, and any single line over the threshold counts with no structural exemption.
 
+`report` mode also prints one extra block: an inventory of the line-number coordinates found in the documents you pass
+(`<doc>:12` shape). That block is a reading, not a criterion — `gate` never produces it, and it cannot change a verdict or a hit count.
+
 It cannot — in `report` mode — write anything, gate anything, or turn a finding into a refusal.
 
 Arguments — `target` (optional): the project root to check; defaults to the session anchor, relative paths resolve against it.
@@ -46,10 +80,11 @@ is judged; in `gate` mode such paths are listed as skipped instead. A pointer re
 
 against the pointing document's own directory — bare names are not resolved across other directories.
 
-Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**: a
-pre-existing dangling pointer or overlong paragraph / line anywhere in it counts, not only this round's edited lines. The first line is the
+Delivery gate — `mode: "gate"`, for the end of a design or development round. Every listed doc is judged **whole**:
+a pre-existing dangling pointer or overlong paragraph / line anywhere in it counts, not only this round's edited lines.
+
+The first line is the machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 
-machine-readable verdict — `DOC-CHECK GATE: PASS` / `DOC-CHECK GATE: REFUSED（命中 K 条）` / `DOC-CHECK GATE: ERROR（reason）` —
 and consumers judge by that prefix; the hits are fixed in the same round and are never booked to the ledger. The gate refuses
 
 **one delivery**, not a user instruction: an explicit user go-ahead is followed, with the hits written into the delivery.
@@ -64,7 +99,7 @@ a reader: use `doc_search` / `read` to read documents and `grep` to search them;
 Side effects and permissions — none. The tool is read-only: no writes, no approval prompt, safe to run in parallel with other calls.
 
 Parameters and scope — both criteria run on built-in constants (`DOC_CHECK_BUILTINS`: threshold 300 characters, no exempt zones,
-no exemptions), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
+no registration-based exemption list), and the judged set is the document list the caller passes — the judged set and the resolution set are the same
 
 documents, so there is no scan-dir / domain / root / exclude surface and no whole-repository scan. Changing a criterion or a
 threshold is a code change and goes through review; no project declaration changes these readings.

package/tool-docs/doc_search.md

@@ -1 +1,5 @@
-Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. Returns matching doc chunks: path, heading, line range, relevance score, content excerpt. For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.
+Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules.
+
+Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. Returns matching doc chunks: path, heading, line range, relevance score, content excerpt.
+
+For what was said in sessions (conversation/chat history — decisions, rulings), use read_history.

package/tool-docs/edit.md

@@ -1,4 +1,20 @@
-Edit a file as a patch — targeted by content or by line number. Two targeting forms (mutually exclusive — use one): ① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range; ② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region. old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming, tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes). Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept). A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after. replace_all applies to content-based edits only: literal replacement of every occurrence — the diff rules do not apply.
+Edit a file as a patch — targeted by content or by line number.
+
+Two targeting forms (mutually exclusive — use one):
+
+① line-based: `line: N` replaces that single line, `startLine: N, endLine: M` replaces the inclusive 1-based line range — no old_string needed when you know the line number; give new_string to replace, or OMIT new_string to delete the line/range;
+
+② content-based: old_string is the current content of the region to change (must match exactly once); new_string is the desired result of that region.
+
+old_string matching is tolerant: exact match first, then a unique whitespace-only variant, then fuzzy match (unique window with ≥90% of lines identical after trimming,
+
+tab→space indent and quote normalization — ASCII single, curly single/double and backtick quotes all unify to straight double quotes).
+
+Lines shared by old/new are kept; lines only in new_string take their position relative to the shared lines (LCS order); lines only in old_string are deleted — a replacement never leaves old lines behind (zero overlap → old lines are replaced by new_string, not kept).
+
+A unique single-line old_string paired with a single-line new_string replaces that exact line in place (line count unchanged). To add a new line without removing anything use insert_after.
+
+replace_all applies to content-based edits only: literal replacement of every occurrence — the diff rules do not apply.
 
 **Routing — pick the right edit tool:**
 - Delete a line/range by number → omit new_string: edit with `line: N` / `startLine: N, endLine: M`
@@ -11,9 +27,14 @@ Edit a file as a patch — targeted by content or by line number. Two targeting
 
 **Batch multiple changes into ONE call via the `edits` array** (preferred over N single edit calls) — same file or across files; atomic: any failure writes nothing. One permission ask, one undo unit, and one turn instead of N. Per-entry shape and targeting are in the schema.
 
+Line-number entries in one `edits` array apply first, in descending `startLine` order, so each is anchored on the numbers you read; their ranges must not overlap (overlap ⇒ the whole batch is refused, nothing written). Content entries then apply in array order. The receipt stays in call order.
+
 Notes:
 - Prefer this over write for targeted edits — it's safer and keeps changes targeted
 - If old_string matches zero times (even fuzzy): error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
 - Returns `Edited <path>: replaced N occurrence(s)` (delete-mode: `Deleted line N of <path>` / `Deleted lines N-M of <path>`) + git diff + syntax-check note + context block (L..-L..).
 - Never fabricate the old_string — copy it verbatim from the actual file using read first
+- **Line-number anchoring**: `line` / `startLine`+`endLine` are judged against the last write to that file: inside or below that write's affected range, or when the file was written after it without updating that anchor, the call is refused — naming the path, the drift (`L<startLine>`, `±shift`) and two ways on (re-read, or address the region without line numbers).
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tool-docs/execute.md

@@ -1,4 +1,6 @@
-Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected. File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
+Execute JavaScript — either inline `code` or a `scriptFile`. Runs in a real child `node` process — a pure node ESM environment: top-level `await` and dynamic `import()` are available, no globals are injected.
+
+File reads/writes/searches belong to the dedicated read/ls/glob/grep/write/edit tools — not to execute. If a script genuinely needs fs/path, `import` the `node:` module inside the code (one explicit import line).
 
 **Route to execute instead of bash:**
 - `node -e "…"` → execute (inline code; top-level await + import() + console all work)
@@ -11,3 +13,7 @@ Notes:
 - Output is capped at ~50KB; when a script overruns it, an explicit `[output truncated]` marker is appended — print large results in chunks, or have the script write them to a file (node:fs) and read that file back with the `read` tool.
 - Use `write`/`edit`/`apply_patch` for source edits. Still use `bash` for package-manager/CLI subprocesses (`npm test`/`npm publish`/`vsce`), servers, and interactive/TTY programs — execute covers in-process JS and `node <script>`/`node --test`/`node --check`, not arbitrary CLI or long-running programs.
 - Irreversibility: it runs with full filesystem access and no automatic undo — script side effects are permanent; checkpoint (git) before risky bulk operations.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused, and read-only scripts are judged the same way (no command-line classification).
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when `workdir` is absent — `workdir` wins when both are given. Pure declaration: it does not change the execution directory (`workdir` does).

package/tool-docs/fetch.md

@@ -1,4 +1,6 @@
-Fetch a URL and return its content. With a DeepSeek provider configured the URL is fetched through DeepSeek's servers and returned as Markdown ([deepseek] title + content); otherwise it is fetched locally and HTML is stripped to readable text. Private/metadata URLs are never sent. Use after websearch to read full documents.
+Fetch a URL and return its content. With a DeepSeek provider configured the URL is fetched through DeepSeek's servers and returned as Markdown ([deepseek] title + content); otherwise it is fetched locally and HTML is stripped to readable text.
+
+Private/metadata URLs are never sent. Use after websearch to read full documents.
 
 Parameters:
 - url (required): http/https URL

package/tool-docs/file_ops.md

@@ -14,4 +14,6 @@ Notes:
 - Paths resolve relative to cwd — no directory restriction (same boundary as bash; the approval gate is the guard).
 - `dest` is overwritten if it already exists. `copy` is recursive for directories.
 - To create a directory, use `write` (creates parent dirs) or `bash mkdir`.
-- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).
+- Returns `Moved|Copied|Renamed <source> -> <dest>` or `Error: ...` (same-path and missing-path errors).
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tool-docs/git.md

@@ -1,6 +1,8 @@
 Run a git command. Only works inside a git repository.
 
-**Route to git instead of bash** — every sub-command maps to the same-named action: status / log / diff / show / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv.
+**Route to git instead of bash** — every sub-command maps to the same-named action:
+
+status / log / diff / show / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv.
 
 - diff: unified diff since last commit (`staged` — staged only; `ref` — compare a commit/branch; `path` — scope).
 - status: working tree state — staged / unstaged / untracked / conflicts.
@@ -26,3 +28,9 @@ Run a git command. Only works inside a git repository.
 - Destructive ops (checkout -- path / restore / reset --hard / stash pop / branch|tag delete / clean / rebase) auto-snapshot first; restore a snapshot via `checkpointAction=rewind`.
 - Failures come back as errors — `git <action> failed: <reason>` — nothing is silently swallowed.
 - `filter` narrows any read-only action's output (case-insensitive regex); `config` (git -c overrides, e.g. a proxy) applies to the network actions (push / fetch / pull / ls-remote / clone). Other parameter defaults and applicability live in the schema.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it for a write action; omitted = refused.
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when neither `path` nor `workdir` is given — those win when present. Pure declaration: it does not change where git runs (`workdir` does).
+
+Read-only actions do not need it: `diff` / `status` / `log` / `show` / `ls-remote` / `blame`, and each `*Action: "list"` (`checkpoint` `list` / `cat` included).

package/tool-docs/goal.md

@@ -1,6 +1,8 @@
 Manage a long-running autonomous goal.
 action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort).
+
 action='complete': mark achieved — only after the criterion's check has actually passed.
 action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts.
 action='cancel': abandon the goal.
+
 Returns a status line — the goal set/updated/completed/blocked/cancelled confirmation, or Error: ... with the reason.

package/tool-docs/grep.md

@@ -1,4 +1,4 @@
-Search file contents with a regex. Returns matching lines as path:line: content.
+Search file contents with a regex. Returns matching lines, each preceded by its file path and line number.
 
 **Route to grep instead of bash:** `findstr /c:"pat" file` / `grep -rn pat .` → grep. Searching file contents is a read — never shell out for it.
 

package/tool-docs/hashline_edit.md

@@ -12,3 +12,5 @@ Notes:
 - Prefer this over edit when: 1) the file may have mixed whitespace/encoding, 2) you want to edit a block of lines with a single call
 - Replacement text replaces the lines identified by the hashes — content not present in new_content is deleted. For a new line after a known line, use insert_after. For a single simple string swap, use edit.
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tool-docs/insert_after.md

@@ -11,5 +11,7 @@ Notes:
 - Use this instead of edit when you're adding a new line — a checklist item, a doc heading, a line of prose, a function, an import, or a block — no need to fabricate surrounding context for exact matching.
 - The inserted content becomes its own line; it's equivalent to `lines.splice(targetLine, 0, content)`.
 - Returns a diff of the change.
-- **Read-before-insert guard**: if the file was modified by any write tool (write/edit/insert_after/hashline_edit/apply_patch/delete) since your last `read`, this tool REFUSES with an error — line numbers may be stale. Read the file again, then retry. This prevents after_line from silently landing at a drifted position.
+- **Read-before-insert guard**: `after_line` is judged against the last write to that file — a line at or above that write's write point is allowed; inside or below it, or when the file was written after it without updating that anchor, the call is refused with the path, the drift and two ways on (re-read, or address the region without line numbers).
 - use the most recent read of the file as the source of old_string / line numbers / hashes — re-read after the file changed
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it — a call that does not say which row it serves is refused.

package/tool-docs/ledger.md

@@ -1,8 +1,8 @@
 台账统一入口——action = add / update / close / query / count。query / count 只读全角色；add / update / close 写仅主 agent。
 - add：新增条目入待讨论。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）；resume_when = 复启条件句（可空；值非空——空串 / 全空白拒；句内可带锚 `@YYYY-MM-DD`（机判到期）或 `@事件件名`（机器不判））。task_book 写门（add ∥ update 同判，判本笔写入面）：结果行 在途 / 待核销 ∥ trigger = 归批 ⇒ task_book 必填（缺 / 空串 / 全空白拒）；本笔新写 task_book（非空值）∥ 本笔新写 trigger = 归批 ⇒ 该指针的文件部分（首个 `§` 前子串）须可解析且指出的档在盘，否则拒。本笔不动指针 ⇒ 零判零阻——旧指针所指档已被清理不阻 status / evidence / 其它字段更新（「档在不在盘」是读数 taskBookOnDisk，不是门）。
-- update：按六态允许表迁移：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外拒；迁移入 已核销 时结果行标题携「收尾链待跑」同拒（同笔携清标记 title 放行）。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
+- update：按六态允许表迁移（逐边枚举，表外拒）：待讨论→待设计 / 待讨论→在途 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 待核销→在途 / 任意非 已废弃 态→已废弃（已废弃 无出边）。`待讨论→在途` 是点火与建档的正路——批档一开就把覆盖行直接落到 在途，不过 待设计（待设计 = 已排设计，不是点火发生的事）；`待核销→在途` 是重开回收——批档重开 ⇒ 行回工作位，六态唯一的回退边。id ∥ batch 恰携其一。status 缺省 = 仅更新字段；executor 缺省 = 进入待设计 / 在途自动写本会话，出在途 / 撤回清空；resume_when 同 update 可空字段（缺省 = 不变）。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`——「｜」零空格；旧空直写）；`evidenceReplace: true` 与 evidence 同传 = 整段替换；旗独传（无新文）∥ 新值全空白 ⇒ 拒。
 - update --batch：批级批量迁移（batch = 批档指针，与该档 task_book 同址的行一次处理）——携 status ⇒ 逐行按迁移表重判；不携 status ⇒ 纯字段补丁（status 零写）。回执 { batch, status, applied, skipped }；被跳过的行逐行点名 { id, from, why }（why = 逐行拒因原文），其余行照落；事务级失败整批回滚。batch 值须可解析且批档在盘，否则拒。
-- close：勾销（待核销 → 已核销）；追认核销（待讨论 / 待设计 → 已核销，须有 evidence——可随本调用传入（一跳核销），判结果值：缺 / 全空白拒）；在途 → 已核销 不可跳；核销标记门：结果行标题携「收尾链待跑」⇒ 拒（收尾链未跑完，不许核销——先跑收尾全链，再由父侧清标记）；撤回（任意态 → 已废弃）不拦。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
-- close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（追认核销不入批量面，转单行 close），在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
-- query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceOversize（evidence 超软上限 300 字——读数非拒写）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
-- count：回报 { count, overdue, evidenceOversize }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceOversize = 其中 evidence 超限行数。task_book 等值过滤。
+- close：勾销（待核销 → 已核销）——**只有这一条核销边**：待讨论 / 待设计 / 在途 一律拒（拒文点名现态 + 该现态的出路句）；撤回（任意态 → 已废弃）不拦。软删除（写 closed_at，行保留）。id ∥ batch 恰携其一。evidence 传入 = 追加（旧值非空 ⇒ 拼接 `旧｜新`；旧空直写）；`evidenceReplace: true` 同传 = 整段替换；旗独传 / 新值全空白 ⇒ 拒；缺省 = 判行值。
+- close --batch：批级批量结算——只销已到 待核销 的行（勾销）；待讨论 / 待设计 逐行点名跳过（须先 update 到 在途 认领）；在途 逐行点名跳过（不可跳）；已核销 / 已废弃 行静默不计。status 可不给（缺省 = 已核销），给了只能是 已核销。
+- query：SQLite 行集，等值过滤（status / kind / board / trigger / task_book）缺省 = 全部行；行集逐行携 aged（未决四态 ∧ 行龄 > 30 天）/ evidenceTooLong（evidence 文字太长，难于阅读——读数非拒写；超 300 字即算命中）/ taskBookOnDisk（task_book 文件部分解析成立 ∧ 该档在盘 ⇒ true；缺指针 / 不可解析 / 不在盘 ⇒ false——读数非门，不拦任何写入）/ overdue（出口态字串 ∥ null：resume_due / dangling / unlabeled / aged，首中优先）。六态 = 待讨论 / 待设计 / 在途 / 待核销 / 已核销 / 已废弃。
+- count：回报 { count, overdue, evidenceTooLong }——count = 未决四态（待讨论 / 待设计 / 在途 / 待核销）行数；overdue = 其中命中出口态的行数；evidenceTooLong = 其中文字太长、难于阅读的行数。task_book 等值过滤。

package/tool-docs/lint.md

@@ -1,5 +1,6 @@
 Run the appropriate linter/checker for a file. Auto-detects based on file extension and project config.
 Without 'full', runs a fast node --check (JS/TS syntax only, catches parse errors in milliseconds).
+
 With 'full', runs the language-aware cascade: tsc –noEmit (TS); ruff (Python); cargo check (Rust); go vet (Go). JS/JSX files fall back to node --check; TS uses tsc --noEmit (requires tsconfig.json).
 Use the fast default after every write/edit; use 'full' before declaring a task complete.
 

package/tool-docs/manifest-read.md

@@ -1,4 +1,5 @@
-Read the project manifest (PROJECT-MANIFEST.json) — the project-level state file: version / phase / docRoot (the root of each document layer: requirements / specs / design / modules / batches) / codePaths / index.
+Read the project manifest (PROJECT-MANIFEST.json) — the project-level state file: version / phase / docRoot (the root of each document layer: requirements / specs / design / modules / batches, plus `standards` = the project's standards document, by file path) / codePaths / index.
+
 Read-only: the only action is `read`. Creating or editing a manifest belongs to the main agent — this subagent variant has no init / write action.
 
 read [target] — report the manifest state with a stable anchor `state=ok|missing|invalid|workspace|no-project`. The ok state prints the manifest JSON plus missingKeys / unknownKeys / errors rows (only when non-empty). Never throws — a missing manifest is reported, not refused.

package/tool-docs/manifest.md

@@ -7,7 +7,9 @@ Actions:
   The resulting manifest must pass validation (a fault is refused with the disk byte-for-byte unchanged); a missing manifest is
   refused — run init first (write never creates one).
 
-target — explicit target directory; defaults to the session anchor, relative paths resolve against it. A workspace target
+target — explicit target directory; defaults to the session anchor, relative paths resolve against it.
+
+A workspace target
 (several projects below it) is reported by `read` and refused by `init` / `write` — with the facts, the full candidate list and
 a next step: name the project root you mean and pass it as target.
 
@@ -19,11 +21,16 @@ Refusals throw `manifest <action>: refused — …` and leave the disk unchanged
 
 read is read-only (planMode passes, no approval); init / write are side effects (approval gate). Writes go through writeManifest / initManifest with writer "main" — the fail-closed subagent default is never used.
 
-Key catalog — the 12 writable nodes (3 whole keys + docRoot's 5 sub-keys + index's 4 sub-keys): what each is; when to change it; wrong ⇒ consequence.
+Key catalog — the 13 writable nodes (3 whole keys + docRoot's 6 sub-keys + index's 4 sub-keys): what each is; when to change it; wrong ⇒ consequence.
 - `version` — schema version (a number); change on file migration; wrong ⇒ validation refuses (disk unchanged).
 - `phase` — project stage, `initial-dev` / `production`; change when the stage is crossed; wrong ⇒ validation refuses.
 - `codePaths` — path segment names (replaces the default `["src"]`); change when the layout moves; wrong ⇒ no segment is classified (the fallback still runs).
 - `docRoot.requirements` · `docRoot.specs` · `docRoot.design` · `docRoot.modules` · `docRoot.batches` — each doc-layer root path (a string | a multi-root array | `null` = absent); change when a layer moves root; wrong ⇒ validation refuses, or checks / batch landing / review roots point elsewhere.
+- `docRoot.standards` — the project's standards document, by FILE path (a string | a multi-file array | `null` = undeclared); the reviewer judges methodology compliance against it; change when that document moves; wrong ⇒ the review says the declaration is unreadable and names the path (never a guessed default — there is none).
 - `index.codeExtensions` · `index.docExtensions` — extra code / doc extensions (unioned, add-only); change when a file type is missing from the index; wrong ⇒ that type stays out of the index (extras harmless; a missing entry = a miss).
 - `index.excludePaths` — project-root-relative path prefixes (for the index); change to keep a directory out of the index; wrong ⇒ that directory is still indexed, or another is wrongly excluded.
 - `index.publicRepos` — public-repo paths (resolvable from this repo root); change when wiring a public repo into the index or cross-repo refs; wrong ⇒ that repo is unreachable for retrieval (empty origin set / wrong path).
+
+- **`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`. In engineering mode the parent agent must pass it for `write`; for `init`, only when the target sits inside an existing project (a `PROJECT-MANIFEST.json` exists on its ancestor chain) — a bootstrap outside any project needs none; omitted when required = refused. `read` does not need it.
+
+**`project`** — the project this call belongs to (absolute path of the project root). Read only when `target` is absent — `target` wins when present. Pure declaration: it does not change the target directory (`target` does).

package/tool-docs/memory.md

@@ -5,7 +5,17 @@ Manage long-term memory in ONE tool — the action parameter picks the operation
 - delete — SINGLE: {id, layer} removes the entry shown in put/search/list output — layer is optional: passed, it is validated against the id prefix (a mismatch is refused — guards against deleting the wrong entry); omitted, the id prefix routes the delete (any id from put/search/list is directly deletable). BATCH (no id): {layer, type and/or keyword} removes every matching entry in that layer — layer + at least one of type/keyword required; without confirm:true it returns the count + preview instead; layer-wide wipes without filters are refused on every layer
 - clear — {layer: "personal", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing layer or a project/team layer is refused (use delete batch filters on shared layers)
 - maintain — index self-maintenance (dry-run by default in tool calls): ghost-row GC (rows whose files are gone from disk — ENOENT-only; live rows untouched; ghost-row deletions take a backup first and read back after), compaction (VACUUM past the freelist thresholds), backup rotation (keeps the newest N maintenance backups). The automatic startup pass runs the same engine and executes directly; every run reports its readings. confirm:true executes — without it you get the plan + readings only
+
 Layer = the memory tier: personal (private) / project (shared via this repo's .thincoder/memory/) / team (CLI only, git-synced); the [layer] tag, the id prefix, and the layer parameter are the same concept — pass a result row's [layer] as layer.
+
 Deleting project/team entries removes the local markdown file and its index row — team deletion is local only; a later team sync may resurrect the file while the remote still has it.
+
 Save bugs, conventions, and preferences here — they persist across sessions.
-Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history.
+Session message history (what was said in this or past sessions) is NOT in memory — search session messages with read_history.
+
+**`ledger`** — the in-flight ledger row this call serves: `"#N"` or `"N"`.
+
+In engineering mode the parent agent must pass it for any write that lands in the project layer: either `layer: "project"`, or a single delete whose id starts with `project:` while `layer` is omitted (`personal` / `team` entries live in the user data directory, so they need no number).
+
+**`project`** — the project this call belongs to (absolute path of the project root). Needed for exactly those project-layer writes: they also refuse without it. `personal` / `team` entries need neither. Pure declaration: it changes no execution directory.
+

package/tool-docs/notify_parent.md

@@ -1,7 +1,7 @@
 A one-way channel to your PARENT (the agent that spawned you) — you are a subagent, so there is no user to ask. Queue a message on the parent's side; your turn is not interrupted and nothing is consumed from it.
 
 - kind:'ask' — a question whose answer changes your next step and that you cannot answer from the materials you can read (task book / design doc / repo). The parent replies with subagent action:'send'; you receive it as an ordinary instruction at your next turn boundary. One ask at a time while a previous one still waits in the parent's queue.
-  Read the materials first and carry the evidence you already checked (`file:line` + the key text) — the parent should not have to re-read for you.
+  Read the materials first and carry the evidence you already checked (the file path + the exact words you read) — the parent should not have to re-read for you.
 - kind:'note' — an FYI that needs no answer (a premise you found broken, a conflict you resolved and want visible early).
 - Delivery markers: the message your parent receives is headed `[上抛·待裁]` (ask — awaiting the
   parent's decision) or `[上抛·知会]` (note — FYI) — added for you, so do not write these markers

package/tool-docs/plan.md

@@ -1,5 +1,7 @@
 Enter or exit plan mode.
+
 In plan mode you are restricted to READ-ONLY tools: read files, search code, run read-only shell commands.
 Use plan mode before complex multi-step tasks — explore the codebase, design the architecture, present a plan to the user.
+
 Exit plan mode to present the plan for the user's approval; implement only after they approve.
 For simple single-file edits, skip plan mode and just make the change.

package/tool-docs/question.md

@@ -14,5 +14,5 @@ Notes:
 - Keep the question text short — one or two sentences. Background, context, and analysis belong in your normal reply text, NOT in the question.
 - Routine confirmations (confirm gates) belong in your plain reply text — the user answers in their next message. Use this tool ONLY when you need the user's decision or input to proceed.
 - Ask here when no default can carry the work forward (new scope, a ruling on a criterion) — this blocks; when a reasonable default exists, ask in your ordinary reply text and keep going — a reply arriving while you work steers the work from there.
-  Read the materials first and carry the evidence you already checked (`file:line` + the key text) — the user should not have to re-read for you.
+  Read the materials first and carry the evidence you already checked (the file path + the exact words you read) — the user should not have to re-read for you.
 - After receiving an answer about a design convention, tool preference, or recurring pattern: save it with the memory tool (action: put). This prevents asking the same question in future sessions — the user shouldn't have to repeat their preferences.

package/tool-docs/read_history.md

@@ -1,7 +1,19 @@
 Query message history — THIS session by default, any session on disk with `path`. Recall what was said or done earlier: design decisions, tool-call timing, past rulings.
 
-Default (no path): this session's full record (never compacted, audit-complete). Filters combine with AND (role / keyword / tool / since-until / limit / direction — semantics per parameter; keyword with path="all" matches FTS words / phrases). Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. Messages without ts return ts:null; content is truncated — the full text is in the session file.
+Default (no path): this session's full record (never compacted, audit-complete).
 
-Cross-session (`path`, optional): a session file path deep-queries THAT session with the same filters (relative paths resolve against the project cwd) — from the derived session index when it covers that session, otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as "session too large"). "cwd:<dir>" lists that directory's session slots (slot + file path + title + count + updatedAt; copy one into path= to deep-query it). "all" searches every INDEXED session (cross-project; rows carry session.file) — sessions never indexed yet are invisible (query them with path=<file>, or index first with the CLI `thincoder session index --rebuild`).
+Filters combine with AND (role / keyword / tool / since-until / limit / direction — semantics per parameter; keyword with path="all" matches FTS words / phrases).
 
-检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。
+Returns a JSON array in chronological order: [{ts, role, name?, tool_call_id?, content (≈500 chars, truncated marker), tool_calls ([{name, arguments}] — arguments capped at 300 chars)}]. Messages without ts return ts:null; content is truncated — the full text is in the session file.
+
+Cross-session (`path`, optional): a session file path deep-queries THAT session with the same filters (relative paths resolve against the project cwd) — from the derived session index when it covers that session,
+
+otherwise from the session file itself (a file over 50,000 messages or 200,000 lines is refused as "session too large").
+
+"cwd:<dir>" lists that directory's session slots (slot + file path + title + count + updatedAt; copy one into path= to deep-query it).
+
+"all" searches every INDEXED session (cross-project; rows carry session.file) — sessions never indexed yet are invisible (query them with path=<file>, or index first with the CLI `thincoder session index --rebuild`).
+
+检索/记忆族选哪个：查**本会话**说过/裁定过 → read_history（默认）；查**别的会话/项目**旧对话 → read_history 带 path/cwd 参数；查**本 run 改过哪些文件** → recent_changes；
+
+查**跨会话已存知识/约定**（memory）→ memory search；查**项目设计文档** → doc_search；查**代码实现** → code_search；查 git 历史快照 → checkpoint cat/versions。read_history 只查会话消息——文件级改动用 recent_changes——知识与约定用 memory——互相不替代。

package/tool-docs/read_image.md

@@ -1,4 +1,6 @@
-Read an image file and return it as multimodal content visible to the model. Use this to view screenshots, UI mockups, diagrams, or any visual content. The model only sees images through this tool — it cannot "see" files directly. Supports png, jpg, gif, webp. The image is base64-encoded and included in the response. Large images (>15MB) are rejected.
+Read an image file and return it as multimodal content visible to the model. Use this to view screenshots, UI mockups, diagrams, or any visual content. The model only sees images through this tool — it cannot "see" files directly.
+
+Supports png, jpg, gif, webp. The image is base64-encoded and included in the response. Large images (>15MB) are rejected.
 
 Parameters:
 - path (required): Path to image file (relative to cwd or absolute). Supports png, jpg, gif, webp; svg is returned as text source.

package/tool-docs/recent_changes.md

@@ -1 +1,3 @@
-Show files modified in this agent run (write/edit/insert_after/delete). Use when you need to remember which files you've already touched — during long multi-file tasks, it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes. For session-level history (what was said in a session), use read_history.
+Show files modified in this agent run (write/edit/insert_after/delete). Use when you need to remember which files you've already touched — during long multi-file tasks, it's easy to lose track. This is scoped to the current run, unlike git status which shows all uncommitted changes.
+
+For session-level history (what was said in a session), use read_history.

package/tool-docs/repo_outline.md

@@ -1 +1,3 @@
-Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module. Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.
+Show the project's file dependency outline: which files import/export from which, and what symbols they export. Use when you need to understand the project structure, find where a function is defined, or see what files depend on a module.
+
+Pass a path to focus on a single file's relationships. Find code by keyword or snippet with code_search.

package/tool-docs/settings.md

@@ -1,6 +1,14 @@
 Adjust ThinCoder runtime configuration — persisted to config.json AND hot-applied to the live agent config.
 Actions: list (all keys + values, flattened) | get <key> | set <key> <value> — dot paths into config.json, any nesting.
+
 set persists to disk (only the set key is written — defaults are never baked in) and takes effect in the running session immediately (turn-boundary keys apply next turn); the value survives restarts.
-Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean); keys whose default is null against their real consumption shape — defaultModel "provider:model", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused (null clears the key: the entry is removed from config.json and the built-in default applies; string-typed keys refuse null — no "unset" state to fall back to). Unknown keys under a known section are stored as given.
+
+Known keys are type-checked: scalar keys against the built-in defaults (agent.maxTurns a number, traces.enabled a boolean);
+
+keys whose default is null against their real consumption shape — defaultModel "provider:model", agent.subagentModel / shell non-empty string, memory.team object with a repo — so a value the app would silently drop is refused
+
+(null clears the key: the entry is removed from config.json and the built-in default applies; string-typed keys refuse null — no "unset" state to fall back to). Unknown keys under a known section are stored as given.
+
 SENSITIVE keys (path segment matching apiKey/key/token/secret/password/authorization/auth/cookie/credential, or any key under a headers/env segment) are NEVER echoed in plaintext — list/get/set replies show ••••（masked）; setting a sensitive key is allowed and stored, but never echoed back.
-list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.
+
+list/get are read-only (planMode ok, no approval); set is a side effect (approval gate). The /config TUI command is the human equivalent.

package/tool-docs/skill.md

@@ -1,5 +1,7 @@
 Load a project skill from .thincoder/skills/.
+
 Skills contain reusable instructions, workflows, or reference material.
 Use this when the user references a skill by name, or when a task matches a known skill's description.
+
 Call with action='list' to see available skills; call with action='load' and name=<skill> to activate one.
 Returns the skill list ('list'), the load confirmation ('load' — instructions arrive in the next message), or Error: ... with the available skills.

package/tool-docs/ssh.md

@@ -1,26 +1,36 @@
-Open and drive a persistent interactive SSH session (remote login shell) on a host. The session survives across tool calls; password hosts get a credential window — the value never appears in tool args or results (an explicit opt-in can store it as ciphertext on this machine).
+Open and drive a persistent interactive SSH session (remote login shell) on a host, and move single files to or from that host (`put` / `get`).
+
+A session survives across tool calls. Password hosts get a credential window — the value never appears in tool args or results (an explicit opt-in can store it as ciphertext on this machine).
 
 **Route to ssh instead of bash:**
 - a one-shot non-interactive command over ssh → `bash` with `ssh host <command>` (cheaper, no session)
 - an interactive shell that must survive several calls (network device CLI, interactive prompts) → ssh
+- one file to or from a host you already have a session on → `put` / `get` (they reuse the session's host and credential chain; `bash scp` cannot reach that chain, so a password host would ask again or fail)
+- a whole directory tree, a resumable transfer or a progress bar → not this tool (single file only)
 
 Parameters:
-- action (required): connect | send | read | secret_input | close | list | credentials | forget
+- action (required): connect | send | read | secret_input | close | list | credentials | forget | put | get
 - host: connect / forget — target host (IP or name)
 - user: connect — login user (optional: your local ssh config decides, else the user recorded for this host locally)
 - port: connect / forget — TCP port (optional, default 22)
 - label: connect — short human label for this session (optional); secret_input — label for the value being sent
-- promptPattern: connect — regex that marks the shell prompt as ready (optional): send/read then settle the moment the prompt appears instead of waiting out the silence window
+- promptPattern: connect — regex that marks the shell prompt as ready (optional; the default recognises lines ending in `#` `>` `$` `%`)
 - identityFile: connect — private-key path to offer as `-i` (`~` expands); remembered for this host and reused when omitted (optional)
-- id: send / read / secret_input / close — session id from connect (`ssh#N`)
+- id: send / read / secret_input / close / put / get — session id from connect (`ssh#N`)
 - data: send — text to type into the session (a trailing newline is passed as-is; otherwise Enter is sent as `\r`)
 - settle: send — wait for the ready verdict before returning (default true); false returns right after the bytes are written
-- timeoutMs: send / read — wait budget override (default 10000; the wait then returns partial output with a readable line)
-- maxChars: read — return cap override (default 8000; the full output stays in the session log)
+- timeoutMs: send / read — wait budget override (default 60000; the wait ends as soon as the device is waiting for input — a prompt, `--More--`, a y/n or password prompt); put / get — transfer budget override (default 600000; on expiry the process tree is killed)
+- maxChars: read — return-window override (default 8000): head 60% + a note + tail 40%, and the omitted middle stays in the session for the next read
+- localPath: put / get — local file path (`~` expands; a file, never a directory)
+- remotePath: put / get — path of that file on the session host (e.g. `/flash/img.bin`)
+- overwrite: get — replace an existing local file (default false: an existing target is refused, never overwritten silently). put follows scp's own semantics: a same-named remote file is replaced
+- protocol: put / get — `scp` (classic SCP protocol, the default, what network devices speak) | `sftp` (the SFTP subsystem, for hosts that only offer that). There is no automatic fallback between them
+- ledger: the in-flight ledger row this call serves (`"#N"` or `"N"`) — required for `get` in engineering mode (the same write gate `write` goes through; `put` writes the remote host and needs no number)
 
 Output:
-- every result starts with the session status line: `[ssh (ssh#3) 10.0.0.5 — ready · idle 3s]`
-- connect returns the first screen; send returns the round's output plus the ready verdict (silence | prompt matched | timeout); read returns what arrived since the last read
+- connect / send / read / secret_input / close / list / put / get results start with the session status line: `[ssh (ssh#3) 10.0.0.5 — ready · idle 3s]`
+- connect returns the first screen; send returns the round's output plus the ready verdict (answer prompt such as `--More--` | prompt matched | timeout); read returns what arrived since the last read
+- put / get return the status line, then exactly one more line — `put <localPath> → <remotePath> · N bytes · exit 0` (and the mirrored form for get). The file's content never enters the context: the bytes travel over the disk only, never through a result, a log or a message. On failure you get an `Error:` line plus the tail of scp's stderr (≤ 600 characters), with the exit code named
 
 Notes:
 - Key-first: keys, your ssh config and ssh-agent are always tried before any saved credential — a connect succeeds without a window
@@ -30,22 +40,25 @@ Notes:
 - Credential discipline: the password is asked for in a window and reaches ssh only through its child-process environment — never in tool
   args, never echoed in a result, never stored in plaintext. Any captured output containing that value (or a value given to secret_input)
   is scrubbed from the returned text and from the session log.
-- Saving a credential is opt-in: the credential window carries a `save` checkbox (off by default). When checked and authentication succeeds,
-  the password is stored encrypted with your OS user account (Windows DPAPI) in a per-user file outside the repository; the store holds only
-  ciphertext. A saved credential is reused silently — the next connect skips the window, and only after key
-  authentication fails. The residual risk is honest: another process running as the same logged-in user can decrypt it; this protects the
-  file at rest, not a compromised account. Saving is Windows-only for now; on other platforms the checkbox does not appear and the window
-  keeps asking.
+- Saving a credential is opt-in and belongs to `connect`: that credential window carries a `save` checkbox (off by default). When checked and authentication succeeds,
+  the password is stored encrypted with your OS user account (Windows DPAPI) in a per-user file outside the repository; the store holds only ciphertext. A saved credential is reused silently — the next connect skips the window, and only after key authentication fails.
+
+  The residual risk is honest: another process running as the same logged-in user can decrypt it; this protects the file at rest, not a compromised account. Saving is Windows-only for now; on other platforms the checkbox does not appear and the window keeps asking.
 - Fail-soft: an unreadable/undecryptable entry, a damaged store or a missing backend falls back to the credential window (the connection is
   not broken; undecryptable entries are kept). If the server rejects a saved credential it is deleted and the window is shown. A failed save
   never affects the connection.
 - secret_input is for device prompts (enable password, sudo, key passphrases): it opens the same kind of window, writes the value plus Enter, and returns only the output — the value is never shown.
 - Sessions: at most 4 live at once (a connect beyond the cap is refused — close one first). A session idle for 600s with no send/read is closed automatically. `close` ends it (stdin EOF → 1.5s grace → the process tree is killed). Ctrl+I (interrupt) does not kill sessions; a user Stop does.
-- Output is capped per return (8000 chars, tail kept); the full stream is always in the session log whose path connect returns.
+- Output is a cleaned text stream: terminal escape sequences and CRLF noise are stripped, and the session log holds the same cleaned text as the result. Each return is a window (8000 chars: head + a note + tail); the omitted middle stays in the session, so another read collects it and a large configuration comes back in full.
 - Not for full-screen terminal UIs (vim/top/screen): output is read as a text stream — paged output such as `--More--` is shown as-is, not driven for you.
+- Transfers are binary safe and single-file: no recursive directory sync, no resume, no progress bar, and the parameters take files only (a directory is not a valid `localPath` / `remotePath`). That status line under the header is the whole receipt — do not expect a byte-by-byte progress.
+- `get` never overwrites silently and never creates directories: an existing local file is refused unless you pass `overwrite:true`, and the local parent directory must already exist (create it first — a mistyped `get` would otherwise land somewhere you cannot see).
+- `put` on a password host re-runs the same credential decision as connect: keys first, then the saved credential (no window), then the credential window. That transfer window only asks for user / password — it carries no save checkbox (storing a credential belongs to `connect`); a session built by typing a password into the window without saving it has no password kept, so the next transfer asks again.
+- If a transfer is killed at `timeoutMs`, a `get` removes the partial local file only when it was actually written by that transfer (an existing file scp never touched is kept — the receipt then says the target was left as it stands); after a `put` the remote host may keep a partial file — this tool does not clean it (resend the whole file with `overwrite:true`, or delete it on the host).
+- Ready means the device is waiting for you, not that output stopped: a prompt or an answer prompt (`--More--`, y/n, password) ends the wait, and a slow operation that goes quiet keeps waiting instead of returning half of its output. If a device's prompt does not look like a shell prompt, pass `promptPattern` on connect — otherwise each command waits out the full timeout.
 - Host keys follow your local ssh config — the tool never rewrites known_hosts. A changed or untrusted key stops the connect with a readable error before any credential is asked for.
-- read / list / credentials are read-only (no approval prompt); connect / send / secret_input / close / forget pass the approval gate like any side-effecting tool, and secret_input shows a masked placeholder — the value itself is never in the approval text.
+- read / list / credentials are read-only (no approval prompt); connect / send / secret_input / close / forget / put / get pass the approval gate like any side-effecting tool, and secret_input shows a masked placeholder — the value itself is never in the approval text. A transfer's approval text names both ends (`localPath` → `remotePath`) and never the file's content.
 - credentials lists saved entries (host / user / saved / last used — never a value); forget deletes the entry for a host (and optional port) and is idempotent — the next connect asks in the window again.
-- Not for file transfer or port forwarding — run `scp` / `sftp` / `ssh -L` through bash.
+- Not for port forwarding (`ssh -L` / `-R`) — run that through `bash`.
 
 Availability: where the end has no UI to collect a credential (headless / ACP), connecting to a password host fails with a readable error — use keys or an ssh-agent there.