docs: rebalance prose cleanup and add trimming skill

packages/llm/llm-deepseek/src/adapter.ts

@@ -73,9 +73,8 @@ export class DeepSeekAdapter extends LlmAdapter {
         const parsed = await response.json() as WireError
         if (parsed.error?.message) message = parsed.error.message
       } catch {
-        // Paranoid by design: `code` and the HTTP status are ALREADY captured above (and passed
-        // to LlmError below), so the only thing this `try` can add is a richer
-        // provider-supplied message.
+        // Only swallow error-body parsing: status and code are already captured,
+        // so malformed gateway JSON must not mask the actionable HTTP failure.
       }
       throw new LlmError(message, code, response.status)
     }

packages/llm/llm-deepseek/src/index.ts

@@ -1,6 +1,7 @@
 /**
- * DeepSeek LLM adapter plugin: registers a {@link DeepSeekAdapter} for the configured model
- * names on `ctx.llm`.
+ * Register a {@link DeepSeekAdapter} for configured model names on `ctx.llm`. Configuration uses
+ * Cordis schemastery; pass secrets from environment variables through `cordis.yml` with `!!js`,
+ * as shown in the package README, rather than reading ad hoc files.
  * @module @deepseek-ai/dsh-llm-deepseek
  */
 

packages/llm/llm-deepseek/src/serialize.ts

@@ -1,6 +1,8 @@
 /**
- * Serialize harness vocabulary (`GenerateOptions`, `Message[]`) into the DeepSeek
- * chat-completions request body.
+ * Serialize harness messages into DeepSeek chat completions. User text is joined; assistant text
+ * becomes `content`, tool calls become `tool_calls`, and tool results become separate tool messages.
+ * Assistant reasoning is replayed as `reasoning_content` only on tool-call turns, as required by
+ * thinking-mode passback. Unknown declaration-merged block types are skipped rather than rejected.
  * @module dsh-llm-deepseek/serialize
  */
 

packages/llm/llm-deepseek/src/sse.ts

@@ -1,4 +1,8 @@
 /**
+ * Decode an SSE byte stream into event `data` payloads. Network reads may split UTF-8 or lines;
+ * CRLF, comments, non-data fields, and multi-data events are handled per SSE rules. The literal
+ * `[DONE]` is yielded so the caller owns final flushing, and EOF before it raises {@link LlmError}.
+ *
  * Minimal SSE (text/event-stream) parser for the chat-completions stream.
  * @module dsh-llm-deepseek/sse
  */

packages/llm/llm-deepseek/src/translate.ts

@@ -1,4 +1,9 @@
 /**
+ * Translate DeepSeek SSE payloads with one stateful harness block per content, reasoning, or tool
+ * call index. An empty initial reasoning delta does not open a block. Finish reason and the latest
+ * usage are deferred until `[DONE]`, covering both finish-attached and trailing usage-only shapes
+ * while ensuring no chunk follows `finish`.
+ *
  * Translate DeepSeek wire chunks into the harness `StreamChunk` protocol.
  * @module dsh-llm-deepseek/translate
  */