docs: rebalance prose cleanup and add trimming skill

packages/llm/llm-pi-ai/src/adapter.ts

@@ -1,6 +1,6 @@
 /**
- * `PiAiAdapter`: the `@earendil-works/pi-ai`-backed implementation of the harness LLM seam,
- * pointed at a DeepSeek (OpenAI-compatible) endpoint.
+ * Pi-ai-backed DeepSeek adapter and design twin of the hand-rolled adapter.
+ * Both implementations must fit the same provider-neutral stream vocabulary.
  * @module dsh-llm-pi-ai/adapter
  */
 
@@ -37,8 +37,8 @@ export function buildModel(modelId: string, options: PiAiAdapterOptions): Model<
     api: 'openai-completions',
     provider: 'deepseek',
     baseUrl: options.baseURL,
-    // Always true: pi-ai only emits the DeepSeek `thinking` field for reasoning-capable models,
-    // deriving enabled/disabled from whether a reasoningEffort option is passed.
+    // Keep reasoning support enabled so `off` can send DeepSeek's explicit
+    // disabled marker rather than falling back to the provider's enabled default.
     reasoning: true,
     // DeepSeek's official effort levels: high|max (xhigh maps to max).
     thinkingLevelMap: { minimal: null, low: null, medium: null, high: 'high', xhigh: 'max' },
@@ -143,8 +143,8 @@ export class PiAiAdapter extends LlmAdapter {
     // `reasoning_effort` so the provider chooses its default effort.
     const reasoning = this.options.reasoning ?? 'high'
 
-    // pi-ai's event stream has no iterator-return cancellation hook: if our consumer stops
-    // early (break / loop abort), the underlying HTTP stream would keep draining.
+    // Pi-ai has no iterator-return cancellation hook. Chain an internal signal
+    // and abort it when this generator exits so early consumers stop the HTTP stream.
     const controller = new AbortController()
     const onCallerAbort = (): void => { controller.abort(options.signal?.reason) }
     if (options.signal?.aborted) controller.abort(options.signal.reason)

packages/llm/llm-pi-ai/src/convert.ts

@@ -1,7 +1,10 @@
 /**
  * Bidirectional mapping between the harness vocabulary and pi-ai's:
- * `GenerateOptions`/`Message[]` → pi-ai `Context`, and pi-ai `AssistantMessageEvent`s →
- * harness `StreamChunk`s.
+ * Convert harness requests to pi-ai context and pi-ai assistant events to harness stream chunks.
+ * pi-ai parses tool arguments while the harness preserves raw JSON, so conversion parses inbound
+ * arguments and re-stringifies outbound values while the adapter restores provider payloads.
+ * In-stream pi-ai errors become harness error/aborted finishes, and its reasoning tokens remain
+ * folded into output usage because it reports no separate count.
  * @module dsh-llm-pi-ai/convert
  */
 
@@ -65,7 +68,8 @@ export function toPiContext(options: GenerateOptions): PiContext {
             content.push({ type: 'text', text: block.text })
             break
           case 'reasoning':
-            // thinkingSignature names the wire field pi-ai replays the CoT under.
+            // Without this wire-field name, pi-ai replays an empty `reasoning_content`, violating
+            // DeepSeek's thinking-mode passback rule on tool-call turns.
             content.push({ type: 'thinking', thinking: block.text, thinkingSignature: 'reasoning_content' })
             break
           case 'tool-call':