docs: rebalance prose cleanup and add trimming skill

examples/coding-agent/code-mode.cordis.yml

@@ -1,13 +1,8 @@
-# Code Mode overlay: the live coding-agent tree (./cordis.yml) with two
-# load-time patches — the app entry's config gains `tools: { mode: code }`
-# (the registry offers exactly one wire tool, run_code, plus the generated
-# TypeScript SDK prompt section declaring bash/read/write/edit/subagent/
-# todo_write) and the worker-thread code runtime joins the tree as
-# `ctx.codeRuntime`. The dsh-stdio-agent bin boots this file for
-# `pnpm run demo:code-mode` (the acp-agent example carries the same-shaped
-# overlay for the `acp` UI). A config patch REPLACES the entry's whole
-# config, so the base entry's fields are restated verbatim; only `tools`,
-# the welcome, and the persona's second paragraph are Code Mode deltas.
+# Code Mode adds `ctx.codeRuntime` and changes the registry to one wire tool,
+# `run_code`, plus a generated SDK for bash/read/write/edit/subagent/todo_write.
+# `demo:code-mode` selects this overlay; the ACP example has the same UI-specific
+# shape. A config patch replaces the whole app config, so unchanged base fields
+# are restated; only `tools`, `welcome`, and the persona's second paragraph differ.
 - id: base
   name: '@cordisjs/plugin-include'
   config:

examples/coding-agent/cordis.yml

@@ -1,15 +1,8 @@
-# The coding-agent plugin tree: the REPL agent demo. The two swappable
-# backends — the DeepSeek adapter and the local bash executor — plus `hmr` for
-# the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio-
-# agent), which bundles the whole agent-core spine (timer, llm, sessions,
-# system-prompt, tools, agents, invariants, tool-bash, agent-loop), the console
-# logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
-#
-# `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
-# dev plugin that needs `--expose-internals` — the `demo:repl` script passes
-# it. Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
-# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env
-# first. cordis.yml reads them via the `!!js` tag.
+# REPL agent with swappable DeepSeek and local-bash backends. `dsh-stdio-agent`
+# supplies the agent-core spine, logging, JSONL persistence, readline UI, and `main` agent.
+# HMR remains a leaf because it requires Loader internals; `demo:repl` passes
+# `--expose-internals`. The app bin loads the gitignored root `.env`; this file
+# reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`.
 
 # Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
 - id: hmr
@@ -28,15 +21,13 @@
       - deepseek-v4-pro
       - deepseek-v4-flash
 
-# Local bash executor for agent-core's tool-bash schema (one of several tool
-# stacks in this tree: filesystem, subagent, and todo_write load below).
+# Local executor for the app bundle's bash tool.
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
   config:
     timeoutMs: 60000
 
-# The stdio chat app: the whole spine + front-door cluster, configured for a
-# REPL agent demo driving a pre-created `main` agent.
+# The app bundle pre-creates the REPL's `main` agent.
 - id: stdio-agent
   name: '@deepseek-ai/dsh-stdio-agent'
   config:
@@ -46,20 +37,16 @@
     resumeSessionId: !!js process.env.RESUME_SESSION_ID
     persistenceRoot: './.sessions'
     welcome: 'agent REPL ready. Give it a coding task.'
-    # The persona: identity + behavior only, nothing about transports or
-    # tooling — tool guidance lives with each tool plugin (descriptions +
-    # prompt sections). {{model}} is the prompt variable the agent loop
-    # resolves from this agent's configured model.
+    # Keep the persona to identity and behavior; tool plugins own tool guidance.
+    # The loop resolves {{model}} from this agent's configuration.
     persona: |
       You are coding-agent, a coding assistant powered by the {{model}} model.
 
       Verify your work by running the code or tests. Keep answers brief and
       factual.
 
-# Automatic context compaction: when the derived history approaches the model's
-# context window, summarize an older range into a checkpoint so a long-running
-# or tool-heavy session keeps fitting. A leaf entry (needs ctx.llm + the
-# agent-loop's `agent/pre-step` seam from the app above).
+# Summarize an older range when derived history approaches the context window.
+# This leaf consumes `ctx.llm` and the app's `agent/pre-step` seam.
 - id: compact-basic
   name: '@deepseek-ai/dsh-compact-basic'
   config:
@@ -70,13 +57,9 @@
     maxTokens: 8192
     compactionRetries: 1
 
-# The subagent seam + BOTH in-process backends + two model-facing tools, as leaf
-# entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh
-# child) and fork (a child seeded with the parent's completed-turn prefix) are
-# independent backends over the shared dsh-subagent-inprocess driver. Exposing
-# both transports is pure config: load each backend, then load dsh-tool-subagent
-# once per backend with a distinct toolName (the tool registry rejects a
-# duplicate name) — no code change.
+# Expose fresh-child `spawn` and completed-prefix `fork` through independent
+# in-process backends. Each tool instance needs a distinct `toolName`; the registry
+# rejects duplicates. These leaves follow the app because it provides `ctx.agents` and `ctx.tools`.
 - id: subagent
   name: '@deepseek-ai/dsh-subagent'
 
@@ -103,10 +86,8 @@
     toolName: subagent_fork
 
 
-# Dynamic workflows: the worker-thread engine (ctx.workflows) over the spawn
-# subagent backend above, plus the model-facing `workflow` tool. The model
-# writes a JavaScript orchestration script (meta + body); the engine runs it
-# in its own worker thread and fans agent() calls out as spawn children.
+# The worker-thread workflow engine fans a model-written JavaScript script's
+# `agent()` calls out through the spawn backend; the adjacent tool exposes it to the model.
 - id: workflow-workerthread
   name: '@deepseek-ai/dsh-workflow-workerthread'
   config:
@@ -114,14 +95,12 @@
 
 - id: tool-workflow
   name: '@deepseek-ai/dsh-tool-workflow'
-# The model-facing todo_write tool: whole-list task tracking written to the
-# session log (todo/write), rendered as a stdio checklist / ACP plan.
+# `todo_write` replaces the logged whole list and renders as a stdio checklist or ACP plan.
 - id: tool-todo
   name: '@deepseek-ai/dsh-tool-todo'
 
-# Filesystem capability stack: local provider, read-before-write/edit policy
-# gate, then the model-facing read/write/edit tools. stdio-agent is a single
-# session, so relative paths resolve from the process cwd (the workspace).
+# Policy loads before the model-facing filesystem tools so writes and edits require
+# an observed file. This single-session app resolves relative paths from the process cwd.
 - id: fs-local
   name: '@deepseek-ai/dsh-fs-local'
   config:

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.