docs: rebalance prose cleanup and add trimming skill

packages/workflow/workflow/src/index.ts

@@ -101,7 +101,12 @@ export type WorkflowEventName =
   | 'workflow/agent-end'
   | 'workflow/end'
 
-/** Machine-routable fatal workflow failures. Child-run failures are not codes. */
+/**
+ * Machine-routable fatal workflow failures: parse/meta/argument/schema errors,
+ * resource caps, subagent infrastructure failures, unserializable boundary
+ * values, and cancellation. An ordinary child failure resolves its item to
+ * `null` and is not one of these fatal codes.
+ */
 export type WorkflowErrorCode =
   | 'SCRIPT_PARSE'
   | 'META_INVALID'

packages/workflow/workflow/src/types.ts

@@ -106,7 +106,10 @@ export interface WorkflowResult {
 }
 
 /**
- * The handle the consumer holds while a script executes.
+ * Holder-owned live workflow. `result` never rejects and settles within the
+ * engine's cancellation grace; failures resolve through `stopReason`. Consumers
+ * may cancel and must call idempotent `dispose()` on every path to await bounded
+ * script settlement and child quiescence.
  */
 export interface WorkflowRun {
   readonly id: WorkflowRunId