docs: rebalance prose cleanup and add trimming skill

packages/web/tool-web/src/fetch.ts

@@ -1,8 +1,8 @@
 /**
- * The model-facing `web_fetch` tool: retrieve the content of a specific URL. Execution goes
- * through `ctx.web` — this module owns the model-facing schema, argument validation, and
- * PRESENTATION (HTML→markdown, truncation formatting), while the fetch provider owns safe
- * retrieval (transport, redirects, caps).
+ * The model-facing `web_fetch` tool. This module owns its schema, validation, and presentation;
+ * `ctx.web` owns retrieval. Timeout is deployment policy, not a model argument: config becomes
+ * `ToolDefinition.timeoutMs`, timeout policy enforces it, and this tool forwards the resulting
+ * signal. A provider timeout remains a backstop for direct seam callers.
  */
 
 import type { Context } from 'cordis'

packages/web/tool-web/src/html.ts

@@ -1,5 +1,8 @@
 /**
- * Minimal, dependency-free HTML→markdown-ish text conversion for `web_fetch` presentation.
+ * Minimal dependency-free HTML-to-readable-text conversion for `web_fetch`, not a full parser. It
+ * removes non-content elements and tags, decodes common entities, collapses whitespace, and keeps
+ * basic headings, lists, and links. A richer converter can replace it without changing the seam or
+ * tool schema.
  * @module @deepseek-ai/dsh-tool-web/html
  */
 

packages/web/tool-web/src/index.ts

@@ -1,7 +1,8 @@
 /**
- * The model-facing web tool suite (`web_search`, `web_fetch`) over the `ctx.web` seam. This
- * root plugin registers the tools the product has ENABLED, composing the per-tool registration
- * helpers (`applyWebSearchTool`, `applyWebFetchTool`).
+ * Model-facing `web_search` and `web_fetch` tools over `ctx.web`. This package owns schemas,
+ * validation, prompt guidance, limits, and presentation, never concrete providers. Enablement
+ * controls tool registration; an enabled tool remains visible when its provider is unavailable
+ * and fails with a structured error at execution time.
  * @module @deepseek-ai/dsh-tool-web
  */
 

packages/web/tool-web/tests/integration.spec.ts

@@ -2,7 +2,8 @@
  * Integration: the real fetch backend (`dsh-web-fetch-local`) + a real search provider
  * (`dsh-web-search-exa`) + the real seam (`dsh-web`) + the model tool (`dsh-tool-web`) + the
  * tool-call timeout policy (`dsh-timeout-policy`), exercised through `ctx.tools.execute()` —
- * nothing bypasses the tool registry.
+ * nothing bypasses the tool registry. Fetch verifies world effects against loopback HTTP; search
+ * uses the real Exa provider with only its network boundary stubbed.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -157,7 +158,8 @@ describe('tool-call timeout returns TOOL_TIMEOUT (deadline wins over a slow fetc
 
   it('the provider backstop still protects a DIRECT ctx.web.fetch() call (no tool-call policy in that path)', async () => {
     // A direct seam caller does not go through tools/execute, so the tool-call policy never
-    // applies; the provider's own timeout is the only budget.
+    // applies; the provider's own timeout is the only budget. A short request hint must therefore
+    // produce provider-owned `WEB_FETCH_TIMEOUT`, never `TOOL_TIMEOUT`.
     const err = await tctx.web.fetch({ url: slowBase, timeoutMs: 50 }).then(
       () => undefined,
       (e: unknown) => e as { code?: string },

packages/web/tool-web/tests/load-path.spec.ts

@@ -1,4 +1,9 @@
-/** Real Loader-path coverage for the namespace plugin's export shape. */
+/**
+ * Real Loader-path guard for an injected namespace plugin. A default export would make
+ * `unwrapExports` collapse the namespace and drop `inject`, causing access to `ctx.web` to fail.
+ * Hand-built mounting bypasses that path, so this test unwraps through the real Loader first; see
+ * postmortem 0001.
+ */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
@@ -28,6 +33,7 @@ describe('dsh-tool-web real-load-path guard', () => {
 
     const loader = Object.create(Loader.prototype) as Loader
     const unwrapped = loader.unwrapExports(toolWeb) as Parameters<Context['plugin']>[0]
+    // Mounting the collapsed shape would throw for missing injection here.
     const fiber = await ctx.plugin(unwrapped)
     expect(ctx.tools.schemas().map(s => s.name)).toEqual(expect.arrayContaining(['web_search', 'web_fetch']))
     await fiber.dispose()