docs: rebalance prose cleanup and add trimming skill

examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts

@@ -10,7 +10,8 @@ import { afterEach, describe, expect, it } from 'vitest'
  * `@deepseek-ai/dsh-stdio-agent` bin against `code-mode.cordis.yml` (the cordis Loader,
  * `unwrapExports`, the include patches over ./cordis.yml, the worker-thread code runtime, and
  * the registry in `mode: code`), then close stdin with no prompt and assert the Code Mode
- * banner + a clean exit.
+ * banner + a clean exit. A dummy key satisfies adapter boot, but no prompt means
+ * no model call; the with-key proof lives in `code-mode.e2e.ts`.
  */
 
 const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
@@ -20,7 +21,8 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
 // the repo, so point it at the repo tsconfig.
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-// The real-API workflow runs up to 14 e2e files at once.
+// Under parallel e2e load, cold tsx/Loader startup can exceed a tight deadline;
+// 30s still detects a wedged child.
 const PROCESS_TIMEOUT_MS = 30_000
 // Leave enough room for the process-owned timeout to report captured output
 // before Vitest aborts the test itself.

examples/coding-agent/tests/code-mode.e2e.ts

@@ -16,8 +16,9 @@ import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
 
 /**
- * With-key Code Mode proof: a real model composes tool calls, writes a file, and
- * returns curated output while the log records `run_code` and its sub-dispatches.
+ * With-key Code Mode proof: a real model receives only `run_code`, composes two
+ * sub-calls, writes a file, and returns curated output while the log records
+ * each `tool/code-dispatch`. The keyless Loader smoke is in the sibling test.
  */
 
 const PERSONA = 'You are coding-agent. You work by writing TypeScript programs for run_code: '

examples/coding-agent/tests/compaction.e2e.ts

@@ -6,8 +6,12 @@ import type { Context } from 'cordis'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness.ts'
 
-/** Key-gated smoke for mid-session compaction and continued agent progress. */
-// FIXME(compaction-snapshot): replay cannot serve the unlogged summarization model call.
+/**
+ * Key-gated smoke for mid-session compaction. It verifies the compact event
+ * pair, replacement of older surface nodes, and a final answer after compaction.
+ */
+// FIXME(compaction-snapshot): this is the only full compaction coverage because
+// replay cannot serve the summarizer's unlogged model call.
 
 let workdir: string | undefined
 let ctx: Context | undefined

examples/coding-agent/tests/keyless-smoke.e2e.ts

@@ -10,10 +10,11 @@ import { afterEach, describe, expect, it } from 'vitest'
  * `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` (the cordis Loader,
  * `unwrapExports`, the full plugin tree incl. the `@deepseek-ai/dsh-agent-core` bundle and the
  * app's in-package readline UI module), then close stdin with no prompt and assert the ready
- * banner + a clean exit.
+ * banner + a clean exit. A dummy key satisfies adapter boot, but no prompt means
+ * no network call; with-key suites own the product behavior.
  */
 
-// The dsh-stdio-agent bin (the demo:repl entry) and this example's cordis.yml.
+// The temp-cwd child needs absolute bin and config paths.
 const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
@@ -21,7 +22,8 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
 // the repo, so point it at the repo tsconfig (root is four levels up).
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-// The real-API workflow runs up to 14 e2e files at once.
+// Under parallel e2e load, cold tsx/Loader startup can exceed a tight deadline;
+// 30s still detects a wedged child.
 const PROCESS_TIMEOUT_MS = 30_000
 // Leave enough room for the process-owned timeout to report captured output
 // before Vitest aborts the test itself.