docs: rebalance prose cleanup and add trimming skill

packages/fs/tool-fs/src/read.ts

@@ -1,6 +1,6 @@
 /**
- * The model-facing `read` tool: inspect a UTF-8 text file and return line-numbered content
- * with pagination guidance.
+ * Model-facing UTF-8 read. It performs one provider stat for type, routing, and observed version,
+ * streams large or size-unknown files, renders a bounded window, then emits the observation.
  * @module @deepseek-ai/dsh-tool-fs/src/read
  */
 
@@ -90,6 +90,7 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
       const target = await ctx.fs.resolve(input.filePath, cwd !== undefined ? { cwd } : undefined)
 
       // One stat: type check + size routing + the version recorded as observed.
+      // A concurrent write can only make a later guarded mutation fail stale and require reread.
       const info = await ctx.fs.stat(target, exec.signal)
       if (!info) throw new FsError(`cannot read "${target.displayPath}": not found`, 'FS_NOT_FOUND')
       if (info.type !== 'file') throw new FsError(`cannot read "${target.displayPath}": not a regular file`, 'FS_NOT_REGULAR_FILE')
@@ -119,7 +120,8 @@ export function applyReadTool(ctx: Context, caps: ReadToolCaps): void {
     },
     // Pure display: a generic card titled by the file with the read window appended (`Read
     // foo.txt (5 - 8)`), `read` kind (icon), and a follow-along location whose line is the
-    // read's offset (defaulting to 1).
+    // read's offset (defaulting to 1). The window reflects raw args, so an omitted limit keeps
+    // the title bare instead of smuggling config into this pure presenter.
     presentCall(args): GenericCallView {
       const { offset, limit } = args
       const window = limit !== undefined && limit > 0