File Manual

File Manual

Use the action schema for routine calls; action selects one child and input belongs only to it. A JSON null optional value means absent and schema defaults apply. Call file(action="manual", input={}) once for unfamiliar or high-consequence overwrite/edit, conversion, large-read, or prompt-source work. This one-time lookup is enough: after the manual result, continue the ordinary requested action; repeating the same manual call is an error loop. Use root summarize=true only when bulky read/search output need not be exact; leave it false for write/edit receipts and manual text.

Actions

The schema owns fields and defaults: read returns numbered UTF-8 text; write creates or overwrites a whole file; edit does exact replacement and leaves a missing or ambiguous match untouched; glob finds names; grep searches UTF-8 text; settings is strict-empty SHOW; and manual does no target I/O. Keep search path/glob narrow: a partial traversal is not proof of no match.

Safety boundaries

• File is text-only and UTF-8-only: binary, image, and audio inspection is out of scope; it never detects or converts encodings silently. For known non-UTF-8 text, use an explicit codec such as Path(...).read_text(encoding='gbk', errors='replace'); replace is lossy, so review the source, then convert with iconv -f gbk -t utf-8 before durable UTF-8 storage.
• Use approved targets under the granted workdir. Relative paths stay under its canonical root; parent/symlink escapes fail. Authorization still governs every target; containment is not protection against overwriting in-root files. Keep private local paths out of human-facing/public results.
• Before an important write, read the target. For edit, make old_string identify the intended match and inspect the receipt; replace_all is only for intentionally every-match edits. Read exact receipts: write reports path / UTF-8 bytes, edit reports replacements. Neither action changes the current system prompt. For durable prompt sources, load the owning psyche domain manual; use context(action="rebuild", input={}) only for explicit activation. context(action="manual", input={}) owns reconstruction depth.

Read depth

A successful read can still be partial. If truncated=true, inspect cap_chars, returned_chars, last_returned_line, and remaining_lines_estimate, then resume with offset=next_offset. An uncapped window may still end before EOF: compare offset + lines_shown to total_lines. For a stable file, next_offset advances by physical line without overlap. line_truncated=true means one physical line was cut to a bounded prefix; next_offset skips to the next line and no later File read recovers its hidden tail. Use the nested read-manual catalog entry (installed at <workdir>/.library/intrinsic/capabilities/read-manual/SKILL.md) for cap math, metadata preflight, spill recovery, complete-content loops, and targeted bash/sed/grep escape hatches.

Settings SHOW only

settings accepts only {} and returns the complete five-field rows key, current, default, configurable, comment; there is no writer or set/reset form. The source-backed immutable rows are read defaults 2000 lines and 100 000 characters, runtime ceiling up to 200 000, glob 2000, grep 200, max file 4194304 bytes, search 20000 visited / 8.0 seconds, canonical exclusions, sidecar timeout 30.0 seconds, and utf-8. The runtime cap is observed fresh on each SHOW: min(FileIOPort.max_result_chars, 200000), or 200000 without a positive Host cap. Per-call choices do not change defaults. The two construction rows are backend.mode (default auto; explicit factory value, then LINGTAI_FILE_IO_BACKEND, then auto) and sensitive backend.sidecar (LINGTAI_FILE_IO_SIDECAR, then legacy LINGTAI_SEARCH_SIDECAR; a nonempty canonical value shadows the alias). backend.mode accepts only whitespace-trimmed, case-insensitive auto, rust, or python; invalid values fail construction. An unusable canonical sidecar still shadows the alias; packaged/dev-tree discovery and auto-mode Python fallback remain, while explicit Rust fails without a usable source. No binary is downloaded; Python ignores the sidecar. An override is an executable path/name: verify ownership and keep it private.

The first eleven rows are immutable; configurable is not permission. SHOW uses source values plus the construction snapshot and does not reread ambient environment. Sidecar current/default values are redacted. Unavailable truth or a response over 65,536 UTF-8 bytes fails the whole inventory, never returns partial rows. After an authorized construction change outside SHOW, rebuild/restart the owning service, recheck SHOW, and run a File search; no File settings action changes policy. Comments route to this single owner heading: file-manual#settings-show-only.