docs: rebalance prose cleanup and add trimming skill

packages/compact/compact/src/index.ts

@@ -59,7 +59,7 @@ export abstract class CompactService extends Service {
    * @param start - first surface seq, inclusive.
    * @param end - last surface seq, inclusive.
    * @param agent - summarizer context.
-   * @param signal - optional cancellation.
+   * @param signal - optional cancellation; model-backed implementations must forward it.
    * @throws when compaction is active or the range is invalid or unbalanced.
    * @returns the replaced range and summary.
    */

packages/compact/compact/src/render.ts

@@ -1,7 +1,6 @@
 /**
- * Plain-text transcript rendering over session events: the shared projection used wherever a
- * compaction-class consumer needs "what a model once saw" as readable text — a summarizer's
- * input, or a recall tool's output.
+ * Pure shared transcript projection for summarization and recall, so both
+ * render the same log span byte-for-byte under replay.
  * @module @deepseek-ai/dsh-compact/render
  */
 
@@ -9,7 +8,9 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 
 /**
- * Render content blocks to a single plain-text string.
+ * Render text directly, reasoning as a tagged span, and every other block as a
+ * type-tagged placeholder. Tool results recurse into nested content; empty
+ * blocks contribute nothing and rendered blocks join with newlines.
  *
  * @param blocks - the content blocks to render.
  * @returns the newline-joined plain-text rendering; empty string when nothing renders.
@@ -43,7 +44,9 @@ export function renderContentBlocks(blocks: readonly ContentBlock[]): string {
 }
 
 /**
- * Render a set of surface-node seqs as a `User:`/`Assistant:`/`Tool result:` transcript.
+ * Render message-producing events as a role-labeled transcript. `seqs` are
+ * walked in caller-supplied surface order, which may differ from numeric log
+ * order after replacement; non-surface and unknown merged events are skipped.
  *
  * @param events - the session log the seqs index into (`session.events`).
  * @param seqs - the surface-node seqs to render, in surface order.

packages/compact/compact/src/types.ts

@@ -1,5 +1,9 @@
 /**
  * Compaction vocabulary: the result type and the `compact/*` session events.
+ * Those declaration-merged events are log-only lock/provenance markers, not
+ * surface events; a separate replacement `user/message` carries the summary.
+ * Backend packages own configuration and retention policy; see
+ * `docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md`.
  * @module @deepseek-ai/dsh-compact/types
  */