PCD (Portable Context Deck)

Previous value: -"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."New value: +"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Takes precedence over trail when both are set."

Previous value: -"Container ID — without trail or work_item, returns { projection, state } (see projection). worker_meta is not returned (platform-internal)."New value: +"Container ID — without trail or work_item, returns { projection, state } (see projection), plus warnings when an ops-trail action filter is set without trail='ops'. worker_meta is not returned (platform-internal)."

Added value: +{
+  "description": "Ops-trail filter: leave out these actions (exact names or a prefix ending in *). With include_actions, the result is include minus exclude. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
+  "items": {
+    "maxLength": 64,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 25,
+  "type": "array"
+}

Added value: +{
+  "description": "Ops-trail filter: return only these actions. Each entry is an exact action name or a prefix ending in * (e.g. 'signal_*'). Unknown names are dropped with a warning; if nothing is left, no entries are returned. Applies to trail='ops' only; elsewhere it is ignored with a warning.",
+  "items": {
+    "maxLength": 64,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 25,
+  "type": "array"
+}

Previous value: -"Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first. 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes)."New value: +"Read grain (topology 3.0). 'full' (default): the complete state row (work + scalars — work items carry state/next) plus the did tail (12) and ops tail (10) from their tables, newest-first; the ops tail leaves out the reads (knowledge_read, knowledge_describe, knowledge_validate, reground_called). 'summary': the hot multi-window handoff read — work headers with per-group counts + the did tail, no ops. Ignored when trail or work_item is set (those keep their own focused shapes)."

Previous value: -"Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?). Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable."New value: +"Trail paging (topology 3.0) — when set, returns { container_id, trail, entries, has_more, warnings? } from the did trail (the client-written narrative: ts, text, work_ref?, by?) or the ops audit (worker-only: ts, action, ref?, detail?), every action included. Newest-first; pair with before/limit to walk deeper — retention is keep-everything, so the full history is reachable. On trail='ops', include_actions / exclude_actions narrow the window."

Previous value: -"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."New value: +"Work-item paging — when set, finds the work item by `what` across all four groups (active/paused/blocked/done) and returns { container_id, work_item: { group, item } } (plus warnings when an ops-trail action filter is set without trail='ops') with the full item including state/next, all annotations, refs, and group-specific fields. Use to revive a paused thread when boot trim hid the item's full context. Returns an error if no item with the given `what` exists. Mutually exclusive with trail."

Previous value: -"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): goal/state/next are capped at 250/600/250 chars and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."New value: +"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): what/goal/state/next/blocker are capped at 120/250/600/250/600 chars (a lookup what is never capped) and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."

Previous value: -"Work item on create_work, or a field patch on update_work/transition_work. goal/state/next are capped at 250/600/250 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."New value: +"Work item on create_work, or a field patch on update_work/transition_work. what/goal/state/next/blocker are capped at 120/250/600/250/600 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."

Previous value: -"Default 'write'. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Uniqueness and deck resolution still run at write time."New value: +"Default 'write'. 'validate': pre-send check — name format/cap (48), description shape, signal_emission — WITHOUT writing; returns { valid, missing_required[], over_cap: [{field, len, cap}], not_checked? }. Uniqueness, deck resolution and the skill allowance still run at write time (not_checked names them)."

Previous value: -"Version number to compare against. Omit to compare against the latest committed version. For container, names the OLDER snapshot the latest is compared against; omit for latest vs previous."New value: +"Version number to compare against; a deck number resolves to its commit. Omit to compare against the newest saved version (for a deck, possibly a pre-update snapshot). For container, names the OLDER snapshot the latest is compared against; omit for latest vs previous."

Previous value: -"Object to restore. console_doc is restricted to platform maintainers. Restore changes working content; commit separately."New value: +"Object to restore. console_doc is restricted to platform maintainers and commits a new version; deck and skill restore working content — commit separately."

Previous value: -"Saved version number; supply exactly one of version or version_id."New value: +"Saved version number; a deck number resolves to its commit. Supply exactly one of version or version_id."

Previous value: -"Filter by category — e.g. 'decision', 'reference', 'manual', 'milestone', 'note'."New value: +"Filter by category — e.g. 'decision', 'reference', 'manual', 'milestone', 'note', 'flow'."

Previous value: -"Accept ids from a cross-container browse/search by relaxing the same-container reject; records annotate their container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error."New value: +"Accept ids from a cross-container browse/search by relaxing the same-container reject; records annotate their container_id. container_id stays required as the session anchor. Scope never leaves your account. Currently restricted to platform-maintainer accounts; others get a gate error. Not with stage."

Added value: +{
+  "description": "Only with stage: your active deck's handle. The stage's skill is read from this deck exactly as run_pcd_skill reads it.",
+  "type": "string"
+}

Previous value: -"Response grain. 'full' (default) returns complete bodies — unchanged behaviour. 'summary' returns metadata + summary only, no raw_markdown — the cheap skim when you already hold ids. 'outline' returns metadata + section_tree (section slugs, headers, per-node hashes, word/paragraph counts — no bodies): the read twin of write_knowledge action='describe'. Lean-then-fetch: outline first, then sections for the parts you need."New value: +"Response grain. 'full' (default) returns complete bodies — unchanged behaviour. 'summary' returns metadata + summary only, no raw_markdown — the cheap skim when you already hold ids. 'outline' returns metadata + section_tree (section slugs, headers, per-node hashes, word/paragraph counts — no bodies): the read twin of write_knowledge action='describe'. Lean-then-fetch: outline first, then sections for the parts you need. Not with stage."

Previous value: -"Section-addressable read — fetch only the named sections instead of the whole body. Requires exactly ONE record_id. Same addressing as the patch surface: a bare level-2 slug returns that section's subtree (intro + level-3 children); a compound 'parent/child' slug returns just that level-3 sub-section. Unknown slugs are rejected with available_sections listed (no silent partial reads). Response items carry { slug, header, level, hash, markdown } + raw_chapter_hash — hashes flow straight into write_knowledge action='patch' expected_hash. Mutually exclusive with projection."New value: +"Section-addressable read — fetch only the named sections instead of the whole body. Requires exactly ONE record_id. Same addressing as the patch surface: a bare level-2 slug returns that section's subtree (intro + level-3 children); a compound 'parent/child' slug returns just that level-3 sub-section. Unknown slugs are rejected with available_sections listed (no silent partial reads). Response items carry { slug, header, level, hash, markdown } + raw_chapter_hash — hashes flow straight into write_knowledge action='patch' expected_hash. Mutually exclusive with projection. Not with stage."

Added value: +{
+  "description": "Flow stage read: the stage's id or name. Needs exactly one record id — a flow — and handle. Returns the stage as written, its declared routes with their conditions, the flow's Gates, Resumption and Records, and the stage's skill as run_pcd_skill returns it from handle. Not with projection, sections or cross_container.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

Previous value: -"Partial content patch. Shape: intent (≤600), description (specialized-context only, ≤300 — container-context rejects it; intent is the container's single what-is-this answer), guidelines (instruction_item[]), out_of_bounds (instruction_item[]), data_refs, file_map. file_map is keyed by stable reference name; every item is { path: string, description?: string }, stays deck-local, and key-merges with existing (null deletes a key). instruction_item is { rule, priority, shared? } — per-item shared governs what flows to specialized loads (guidelines/data_refs opt-in via shared:true; out_of_bounds opt-out via shared:false). data_refs entries take optional declaration-layer knobs: read {projection: 'outline'|'summary' | sections: string[]} on medium='kb_record' (grounding grain) and routing 'pcd'|'direct'|'auto' on medium='mcp_connection' (broker vs client reach); rejected on other mediums. Most fields REPLACE on provided — prefer content_ops for single-item edits on the three arrays. session_modes retired — sending it rejects. Optional — may be omitted when only patching name/load."New value: +"Partial content patch. Shape: intent (≤600), description (specialized-context only, ≤300 — container-context rejects it; intent is the container's single what-is-this answer), guidelines (instruction_item[]), out_of_bounds (instruction_item[]), data_refs, file_map. file_map is keyed by stable reference name; every item is { path: string, description?: string }, stays deck-local, and key-merges with existing (null deletes a key). instruction_item is { rule, priority, shared? } — per-item shared governs what flows to specialized loads (guidelines/data_refs opt-in via shared:true; out_of_bounds opt-out via shared:false). data_refs entries take optional declaration-layer knobs: read {projection: 'outline'|'summary' | sections: string[]} on medium='kb_record' (grounding grain) and routing 'pcd'|'direct'|'auto' on medium='mcp_connection' (broker vs client reach); a data_ref of type 'flow' points at a flow record — medium 'kb_record', never mandatory, no read knob, at most 3 per deck; rejected on other mediums. Most fields REPLACE on provided — prefer content_ops for single-item edits on the three arrays. session_modes retired — sending it rejects. Optional — may be omitted when only patching name/load."

Previous value: -"Pre-flight, pre-send check, full write, or partial patch. 'describe' returns the category contract + per-record state — no body required. 'validate' runs the exact write-path validation (slug format, status, immutability, template sections, metadata, summary max_length) on a candidate payload WITHOUT writing — returns { valid, missing_required[], over_cap: [{field, len, cap}] }; use it before committing a long compose so an over-cap field costs one cheap check, not a rejected write. Default 'write' commits in one call. 'patch' applies targeted section/paragraph edits to an existing record via `patches[]` without sending the whole body — supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note). On immutable categories (decision, milestone) the patch reconstructs the successor and supersedes (returns action='superseded'); on mutable categories (manual, reference, note) it edits in place (action='patched'). Pre-flight with describe to fetch the current section_tree + hashes."New value: +"Pre-flight, pre-send check, full write, or partial patch. 'describe' returns the category contract + per-record state — no body required. 'validate' runs the exact write-path validation (slug format, status, immutability, template sections, metadata, summary max_length) on a candidate payload WITHOUT writing — for a flow, its stage structure too — returns { valid, missing_required[], over_cap: [{field, len, cap}] }; use it before committing a long compose so an over-cap field costs one cheap check, not a rejected write. Default 'write' commits in one call. 'patch' applies targeted section/paragraph edits to an existing record via `patches[]` without sending the whole body — supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) the patch reconstructs the successor and supersedes (returns action='superseded'); on mutable categories (manual, reference, note, flow) it edits in place (action='patched'); on a flow the stages are re-checked on the patched body first. Pre-flight with describe to fetch the current section_tree + hashes."

Previous value: -"Category — must be declared in the manifest (note, decision, reference, manual, milestone). 'knowledge' is reserved. Immutability + locking are derived from the manifest's transitions on promotion."New value: +"Category — must be declared in the manifest (note, decision, reference, manual, milestone, flow). 'knowledge' is reserved. Immutability + locking are derived from the manifest's transitions on promotion. A record never moves into or out of 'flow' — write a new record instead."

Previous value: -"Array of patch ops for action='patch'. Level-2 ops: replace_section / replace_section_intro / append_section / insert_section_after / remove_section. Level-3 ops: replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Both levels: rename_section — { section_slug, new_header, expected_hash? } renames a heading + its slug without resending the body; body and children untouched, child slugs cascade on a level-2 rename; required frame sections reject (REQUIRED_SECTION), slug collisions reject (DUPLICATE_HEADER). Section slugs are doc-local addressing, not a stable cross-doc contract — a rename that changes a slug raises a repair signal for cross-record references (warning in the response). Addressing: level-2 ops take section_slug=<bare slug> (insert_section_after takes after_section_slug). Level-3 ops take section_slug=<parent's BARE slug> PLUS the child's compound 'parent/child' slug in paragraph_slug (after_paragraph_slug for insert_paragraph_after) — never put the compound slug in section_slug (exception: rename_section on a level-3 child takes the compound slug directly in section_slug); append_paragraph / prepend_paragraph create a new child under section_slug=<parent> with the title in header. See section_tree.addressing in the describe response. Each op also carries content/header as applicable. content is BODY-ONLY: never include the section's '## …'/'### …' heading line — the heading is emitted from the slug (replace ops) or the header param (append/insert ops); a content opening with a heading line is rejected with HEADER_IN_CONTENT. Ops without a header param reject a stray header field (UNEXPECTED_HEADER) — renaming goes through rename_section, never a header on replace_section. replace_section_intro edits ONLY a level-2 section's own lead text and preserves its level-3 children — use it to fix a parent section's intro when it has subsections (replace_section refuses such a section with CHILDREN_PRESENT). replace_section / replace_section_intro / replace_paragraph / remove_paragraph / rename_section accept optional expected_hash for optimistic concurrency. Pass as JSON array; the worker also accepts a JSON-encoded string. Supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note). On immutable categories (decision, milestone) a patch reconstructs the successor and supersedes rather than editing in place."New value: +"Array of patch ops for action='patch'. Level-2 ops: replace_section / replace_section_intro / append_section / insert_section_after / remove_section. Level-3 ops: replace_paragraph / append_paragraph / insert_paragraph_after / prepend_paragraph / remove_paragraph. Both levels: rename_section — { section_slug, new_header, expected_hash? } renames a heading + its slug without resending the body; body and children untouched, child slugs cascade on a level-2 rename; required frame sections reject (REQUIRED_SECTION), slug collisions reject (DUPLICATE_HEADER). Section slugs are doc-local addressing, not a stable cross-doc contract — a rename that changes a slug raises a repair signal for cross-record references (warning in the response). Addressing: level-2 ops take section_slug=<bare slug> (insert_section_after takes after_section_slug). Level-3 ops take section_slug=<parent's BARE slug> PLUS the child's compound 'parent/child' slug in paragraph_slug (after_paragraph_slug for insert_paragraph_after) — never put the compound slug in section_slug (exception: rename_section on a level-3 child takes the compound slug directly in section_slug); append_paragraph / prepend_paragraph create a new child under section_slug=<parent> with the title in header. See section_tree.addressing in the describe response. Each op also carries content/header as applicable. content is BODY-ONLY: never include the section's '## …'/'### …' heading line — the heading is emitted from the slug (replace ops) or the header param (append/insert ops); a content opening with a heading line is rejected with HEADER_IN_CONTENT. Ops without a header param reject a stray header field (UNEXPECTED_HEADER) — renaming goes through rename_section, never a header on replace_section. replace_section_intro edits ONLY a level-2 section's own lead text and preserves its level-3 children — use it to fix a parent section's intro when it has subsections (replace_section refuses such a section with CHILDREN_PRESENT). replace_section / replace_section_intro / replace_paragraph / remove_paragraph / rename_section accept optional expected_hash for optimistic concurrency. Pass as JSON array; the worker also accepts a JSON-encoded string. Supported on any category whose template declares a section_schema (all authored categories today: manual, reference, decision, milestone, note, flow). On immutable categories (decision, milestone) a patch reconstructs the successor and supersedes rather than editing in place."

Previous value: -"Work item on create_work, or a field patch on update_work/transition_work. Provenance is server-stamped."New value: +"Work item on create_work, or a field patch on update_work/transition_work. goal/state/next are capped at 250/600/250 chars and rejected over the cap, never truncated; refs holds at most 8 typed pointers. Only the fields you send are checked. Provenance is server-stamped."

Removed value: -1000

Removed value: -1

Removed value: -1000

Removed value: -1

Removed value: -1000

Removed value: -1

Added value: +{
+  "description": "Typed pointers {kind, label?, locator}; sending refs replaces the stored array. See describe.work_item_shape.",
+  "items": {},
+  "type": "array"
+}

Removed value: -2000

Removed value: -1

Removed value: -200

Removed value: -1

Previous value: -"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source)."New value: +"Required when action='patch' or 'validate'. Ignored when action='describe'. work_patch: partial merge on an existing item by `what` across all groups — update goal/state/next/assigned_to, append refs — without resending the item (fields per topology 3.0). The primary keep-it-current op: `state` is the thread's current standing (renamed from detail), `next` its own next move — keep both current, they replace the retired session summary. work_upsert: create an item, or fully reshape one (match on `what`) in work.{active|paused|blocked|done}. Items carry goal/state/next/refs[]/annotations[] and assigned_to — advisory deck-handle label naming the owning deck. This is the reshape op the over_shape boot flag points at. work_transition: move an existing item by `what` to a different group. work_remove: remove an item by `what` from any group. work_annotate: append a typed annotation to a work item's annotations[] (renamed from note_append, topology 3.1.0). did_append: record a completion into the did trail (its own table since topology 3.0); append-only, attribution on every entry, optional work_ref to the closed item, nudges if that item is still open. Retired (topology 3.0): summary_set + session_mode_set (slots dissolved) and client op_append (audit is worker-stamped at source). Work items are pointers plus current standing, never documents (topology 3.2): goal/state/next are capped at 250/600/250 chars and refs[] at 8 typed pointers; all three write ops reject over-cap rather than truncating, and check only what you send."

Previous value: -"Required when action='patch' or 'validate' (validate takes the same candidate payload the patch would send). Ignored when action='describe'. Op-specific payload. work_patch: {what, patch: {goal?, state?, next?, assigned_to?, refs_append?: [...]}} — partial merge on the item matched by `what` (any group); provided fields update, untouched fields survive; refs_append appends to refs[] (exact duplicates skipped with a warning); empty or unknown-field patches are rejected with the patchable field list (`detail` rejects — renamed to `state`). Stamps item.updated (the freshness clock behind the boot hygiene flags). assigned_to soft-validates like work_upsert. work_upsert: {group: 'active'|'paused'|'blocked'|'done', item: {what, goal?, state?, next?, refs?, annotations?, assigned_to?, ...}} — `detail` is rejected (renamed to `state`, topology 3.0); blocked requires `blocker`; done auto-stamps `closed` if missing; item.updated stamps on every upsert. Caps: active/paused 5, blocked 3, done 5 — over-cap on active/paused/blocked is REJECTED with a make-room hint (work items are never silently evicted); done alone trims oldest-by-closed. assigned_to is an advisory deck handle: soft-validated against the container's decks, mismatch warns in the envelope, never rejects. work_transition: {what, to: 'active'|'paused'|'blocked'|'done', patch?: {...}} — transitioning to blocked requires `blocker` in patch; moving into a full active/paused/blocked group is REJECTED (make room first — the source item stays put), done trims oldest-by-closed. work_remove: {what}. work_annotate: {what, type, text: string|string[], actor?} — `what` matches the work item's `what` field (the same item key as work_patch/work_transition/work_remove); `type` is open vocabulary (gotchas, choice, observation, shipped, attempt, risk, …); `text` is the annotation content, aligned with did_append. Char caps (150 chars/bullet, 900 total) are REJECTED over-cap with a field+limit message (never truncated) — tighten and resend; the 6-bullet cap drops oldest. Per-item cap 10: an over-cap append succeeds and RETURNS the evicted annotation in evicted_annotations (annotations are memory, never silently destroyed) — graduate it to knowledge or fold it into the item if it still matters. did_append: {text, work_ref?, by?} — record a COMPLETION into the did trail (topology 3.0): `text` ≤250 chars (rejected over-cap); optional `work_ref` (a work item's `what` this completion closes) and `by` (your deck handle). Append-only, retention keep-everything; boot ships a tail of 8, read_topology pages deeper (trail='did'). A work_ref still in active/paused returns a nudge. Use for finished things — in-flight standing stays on the work item's `state` via work_patch."New value: +"Required when action='patch' or 'validate' (validate takes the same candidate payload the patch would send). Ignored when action='describe'. Op-specific payload. work_patch: {what, patch: {goal?, state?, next?, assigned_to?, refs_append?: [...]}} — partial merge on the item matched by `what` (any group); provided fields update, untouched fields survive; refs_append appends to refs[] (exact duplicates skipped with a warning); empty or unknown-field patches are rejected with the patchable field list (`detail` rejects — renamed to `state`). `state` REPLACES — write the new standing from scratch, never the old text plus a layer; goal/state/next reject over 250/600/250 chars. Each appended ref is {kind, label?, locator}: kinds are knowledge | skill | signal | connection | url | file, the locator is the one its kind needs, and nothing else is accepted; the merged refs[] caps at 8. Stamps item.updated (the freshness clock behind the boot hygiene flags). assigned_to soft-validates like work_upsert. work_upsert: {group: 'active'|'paused'|'blocked'|'done', item: {what, goal?, state?, next?, refs?: [{kind, label?, <locator>}], annotations?, assigned_to?, ...}} — `detail` is rejected (renamed to `state`, topology 3.0); blocked requires `blocker`; done auto-stamps `closed` if missing; item.updated stamps on every upsert. Caps: active/paused 5, blocked 3, done 5 — over-cap on active/paused/blocked is REJECTED with a make-room hint (work items are never silently evicted); done alone trims oldest-by-closed. assigned_to is an advisory deck handle: soft-validated against the container's decks, mismatch warns in the envelope, never rejects. The sent item is checked against the work-item caps and ref shape; knowledge/skill/signal refs must resolve in this container, and a connection ref naming nothing the container declared warns and lands. work_transition: {what, to: 'active'|'paused'|'blocked'|'done', patch?: {...}} — transitioning to blocked requires `blocker` in patch; moving into a full active/paused/blocked group is REJECTED (make room first — the source item stays put), done trims oldest-by-closed. Only the patch you send is checked against the caps and ref shape — the stored item's other fields are left alone, so a bare transition of a legacy over-shape item passes. work_remove: {what}. work_annotate: {what, type, text: string|string[], actor?} — `what` matches the work item's `what` field (the same item key as work_patch/work_transition/work_remove); `type` is open vocabulary (gotchas, choice, observation, shipped, attempt, risk, …); `text` is the annotation content, aligned with did_append. Char caps (150 chars/bullet, 900 total) are REJECTED over-cap with a field+limit message (never truncated) — tighten and resend; the 6-bullet cap drops oldest. Per-item cap 10: an over-cap append succeeds and RETURNS the evicted annotation in evicted_annotations (annotations are memory, never silently destroyed) — graduate it to knowledge or fold it into the item if it still matters. did_append: {text, work_ref?, by?} — record a COMPLETION into the did trail (topology 3.0): `text` ≤250 chars (rejected over-cap); optional `work_ref` (a work item's `what` this completion closes) and `by` (your deck handle). Append-only, retention keep-everything; boot ships a tail of 8, read_topology pages deeper (trail='did'). A work_ref still in active/paused returns a nudge. Use for finished things — in-flight standing stays on the work item's `state` via work_patch."

Previous value: -"Operation. Call describe before composing an unfamiliar contribution or work write."New value: +"Operation. Call describe before composing an unfamiliar contribution, work write, or document action; describe.document_actions is the action-specific contract."

Previous value: -"Current proposal revision required for revise_contribution and mark_ready."New value: +"Current immutable record revision required for revise_contribution, mark_ready, revise_document, and submit_document."

Previous value: -"Current transition revision required for revise_contribution and mark_ready."New value: +"Current lifecycle transition revision required by contribution and document writes; open_document_round accepts this version but not expected_revision."

Previous value: -"Maximum review requests returned; defaults to 20."New value: +"Result cap: read_reviews and list_documents default to 20 with maximum 50; search_documents defaults to 10 with maximum 20."

Previous value: -"Versioned team contribution record for reads, revision, or readiness."New value: +"Versioned Team record. Required by record- and document-specific reads and writes; inspect describe.document_actions for each document action."

Added value: +"Immutable document revision to check with check_document; defaults to the current revision. It is not an optimistic write token."