@brightbeamai/chap-coordinator-mcp 0.2.12 → 0.3.0

package/dist/schemas.js

@@ -11,17 +11,37 @@ var TASK_ID = {
   type: "string",
   description: "Task identifier returned by chap.task.create."
 };
+var decimalStringNote = (example) => `Written as a decimal string, e.g. "${example}". CHAP canonicalisation accepts integers only, so a JSON number with a fractional part is refused with -32602.`;
 var ROUTING_HINTS = {
   type: "object",
-  description: "Optional signals for the routing/1.0 profile.",
+  description: "Signals recorded on the task and read by the routing/1.0 methods: task.route, review.depth and escalate.auto. Recording a hint has no effect on its own; it is consulted only when one of those methods is called.",
   properties: {
-    criticality: { type: "string", enum: ["low", "medium", "high", "critical"] },
-    deadline: { type: "string", description: "ISO 8601 timestamp." },
-    risk_tier: { type: "string" },
-    max_cost_usd: { type: "number" }
+    criticality: {
+      type: "string",
+      enum: ["low", "medium", "high", "critical"],
+      description: "How costly a wrong answer would be. The default review-depth policy reads it: 'critical' gives a full review, and 'high' with confidence below 0.7 does the same. The default assignee policy does not read it."
+    },
+    deadline: { type: "string", description: "When the work is needed by, as an ISO 8601 timestamp. Recorded on the task; the coordinator does not act on it." },
+    risk_tier: { type: "string", description: "Operator-defined risk band, e.g. 'regulated' or 'internal'. No built-in policy reads it; it is available to an operator-supplied routing policy." },
+    max_cost_usd: { type: "string", description: `Budget ceiling for this task in US dollars. ${decimalStringNote("12.50")} No built-in policy reads it.` }
   },
   additionalProperties: true
 };
+var COMMENT = {
+  type: "string",
+  description: "The reviewer's note on this decision. Recorded in the audit entry for the decision."
+};
+var TAGS = {
+  type: "array",
+  items: { type: "string" },
+  description: "Workspace-defined labels for this decision, e.g. ['tone', 'unsupported-claim']. Recorded in the audit entry. chap.audit.read does not filter on tags, so grouping by tag is done by the reader."
+};
+var ARTEFACT_DIGEST = {
+  type: "string",
+  pattern: "^sha256:[0-9a-f]{64}$",
+  description: "Optional. SHA-256 over the JCS canonicalisation of the artefact under review, in the form `sha256:<hex>`. When present it binds the decision to the exact content reviewed, and a mismatch is refused with -32074."
+};
+var STRUCTURED_PAYLOAD_NOTE = "Pass a JSON object or array. A JSON-encoded string is parsed back to the structured value before dispatch, so patches in chap.decide.override apply against a real object.";
 var SCHEMAS = {
   "chap.workspace.create": {
     type: "object",
@@ -30,10 +50,20 @@ var SCHEMAS = {
       profiles: {
         type: "array",
         items: { type: "string" },
-        description: "Profile identifiers to enable, e.g. ['core/1.0', 'review/1.0']."
+        description: "Profile identifiers to enable, e.g. ['core/1.0', 'review/1.0']. Recorded on the workspace. Two profiles change behaviour by being present: modes/1.0, under which a trial-mode task requires review, and audit-scitt/1.0, which turns on the hash-linked chain."
+      },
+      mode: {
+        type: "string",
+        enum: ["shadow", "trial", "production"],
+        default: "trial",
+        description: "Default mode for tasks created here. Under modes/1.0 a trial-mode task has review_required set to true whatever the caller passes. 'shadow' and 'production' are recorded on the task and carry no further behaviour in this implementation."
       },
-      mode: { type: "string", enum: ["shadow", "trial", "production"], default: "trial" },
-      mode_ceiling: { type: "string", enum: ["shadow", "trial", "production"], default: "production" }
+      mode_ceiling: {
+        type: "string",
+        enum: ["shadow", "trial", "production"],
+        default: "production",
+        description: "Highest mode a task in this workspace may request. A task.create above the ceiling is refused with -32040. The ceiling can be changed afterwards with chap.control.set_mode_ceiling."
+      }
     },
     additionalProperties: false
   },
@@ -46,7 +76,11 @@ var SCHEMAS = {
     type: "object",
     properties: {
       workspace: WORKSPACE_ID,
-      profiles: { type: "array", items: { type: "string" } }
+      profiles: {
+        type: "array",
+        items: { type: "string" },
+        description: "The complete profile set to enable, replacing the current one. Adding audit-scitt/1.0 to a workspace that already has entries leaves those entries unchained and outside chain verification."
+      }
     },
     required: ["workspace", "profiles"]
   },
@@ -55,9 +89,13 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      type: { type: "string", enum: ["human", "agent", "service", "group", "workspace"] },
-      role: { type: "string", description: "Operator-defined role, e.g. 'reviewer' or 'drafter'." },
-      display_name: { type: "string" }
+      type: {
+        type: "string",
+        enum: ["human", "agent", "service", "group", "workspace"],
+        description: "The kind of participant. Only members of type 'human' are eligible for the review that chap.task.complete opens on a task marked review_required, and a completion with no eligible human is refused with -32011."
+      },
+      role: { type: "string", description: "Operator-defined role, e.g. 'reviewer' or 'drafter'. One value is read by the coordinator: 'admin' permits revoking another member's key." },
+      display_name: { type: "string", description: "Human-readable name for interfaces. Not used in authorisation." }
     },
     required: ["workspace", "from", "type"]
   },
@@ -70,12 +108,25 @@ var SCHEMAS = {
     type: "object",
     properties: {
       workspace: WORKSPACE_ID,
-      from: { ...PARTICIPANT_URI, description: "Delegator URI." },
-      kind: { type: "string", description: "Task kind, e.g. 'draft_response' or 'review'." },
-      assignee: { ...PARTICIPANT_URI, description: "Who the task is assigned to. Must be a workspace member." },
+      from: { ...PARTICIPANT_URI, description: "The delegator. Must be a workspace member." },
+      kind: { type: "string", description: "Task kind, e.g. 'draft_response' or 'review'. Free text; the coordinator records it without interpreting it." },
+      assignee: { ...PARTICIPANT_URI, description: "Who the task is assigned to. Must be a workspace member, and must not be paused: assigning to a paused member is refused with -32063." },
       input: { type: "object", description: "Task-specific input payload.", additionalProperties: true },
       routing_hints: ROUTING_HINTS,
-      mode: { type: "string", enum: ["shadow", "trial", "production"] }
+      mode: {
+        type: "string",
+        enum: ["shadow", "trial", "production"],
+        description: "Mode for this task, defaulting to the workspace mode. A mode above the workspace ceiling is refused with -32040."
+      },
+      review_required: {
+        type: "boolean",
+        description: "When true, chap.task.complete opens a review instead of completing: the output becomes the artefact under review, and the task reaches 'completed' only on a reviewer decision. chap.task.update cannot complete such a task. Under modes/1.0 a trial-mode task has this set to true whatever is passed here."
+      },
+      deadline: { type: "string", description: "When the task is due, as an ISO 8601 timestamp. Recorded on the task; the coordinator does not act on it." },
+      idempotency_key: {
+        type: "string",
+        description: "Caller-chosen key for safe retries. A second create carrying a key already seen in this workspace returns the original task and records nothing further. The workspace retains the 10,000 most recent keys."
+      }
     },
     required: ["workspace", "from", "kind", "assignee", "input"]
   },
@@ -85,8 +136,12 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      state: { type: "string", enum: ["in_progress", "review_requested", "declined", "paused", "cancelled", "completed"] },
-      progress_note: { type: "string" }
+      state: {
+        type: "string",
+        enum: ["in_progress", "declined", "cancelled", "completed"],
+        description: "The state to move the task to. Only the transitions in SPECIFICATION.md 8.1 are legal from the task's current state; others are refused with -32602. A review opens with chap.review.request, or with chap.task.complete on a task that requires one, so 'review_requested' is not a target here. A task marked review_required cannot be moved to 'completed' here: submit the output with chap.task.complete, which opens the review."
+      },
+      progress_note: { type: "string", description: "Short note on what changed, kept in the task's history." }
     },
     required: ["workspace", "from", "task_id", "state"]
   },
@@ -96,8 +151,8 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      output: { description: "The task's output artefact. Pass as a JSON object or array, not a JSON-encoded string." },
-      confidence: { type: "number", description: "Self-reported confidence (0-1), where supported." },
+      output: { description: `The task's output artefact. ${STRUCTURED_PAYLOAD_NOTE}` },
+      confidence: { type: "string", description: `Self-reported confidence in the output, between 0 and 1. ${decimalStringNote("0.86")}` },
       routing_hints: ROUTING_HINTS
     },
     required: ["workspace", "from", "task_id"]
@@ -108,17 +163,24 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       range: {
         type: "object",
+        description: "Sequence window to return. Omit for the whole log.",
         properties: {
-          from_seq: { type: "integer", description: "Start sequence number (inclusive)." },
-          to_seq: { type: "integer", description: "End sequence number (exclusive)." }
+          from_seq: { type: "integer", description: "Start sequence number, inclusive." },
+          to_seq: { type: "integer", description: "End sequence number, exclusive." }
         }
       },
       filter: {
         type: "object",
+        description: "Narrows the entries returned. Conditions combine with AND, and are applied within the sequence window rather than before it.",
         properties: {
-          method: { type: "string" },
-          from: { type: "string" },
-          task_id: { type: "string" }
+          method: { type: "string", description: "Return only entries for this CHAP method, e.g. 'decide.override'. Matched in full, without the 'chap.' tool-name prefix." },
+          from: { type: "string", description: "Return only entries whose actor is this participant URI." },
+          task_id: { type: "string", description: "Return only entries about this task." },
+          outcome: {
+            type: "string",
+            enum: ["accepted", "refused"],
+            description: "Return only accepted calls, or only the refused attempts the coordinator recorded. Omit for both."
+          }
         }
       }
     },
@@ -135,15 +197,16 @@ var SCHEMAS = {
       task_id: TASK_ID,
       to: {
         oneOf: [PARTICIPANT_URI, { type: "array", items: PARTICIPANT_URI }],
-        description: "One or more reviewers. A single URI string, or a JSON array of URI strings (not a JSON-encoded string)."
+        description: "One or more reviewers, as a single URI string or an array of URI strings. Only a workspace member can go on to decide, so a review addressed elsewhere cannot be closed by its recipient."
       },
       rule: {
         type: "string",
         enum: ["any_one_approves", "all_approve", "quorum:2", "quorum:3"],
-        default: "any_one_approves"
+        default: "any_one_approves",
+        description: "How many of the addressed reviewers must approve before the task completes. quorum:N is accepted for any N of 1 or more. The rule is fixed once the review is open: a later request naming a different one is refused with -32014. Omitting it on a later request leaves the rule alone, which is how reviewers are added to an open review."
       },
-      artefact: { description: "The draft being submitted for review. Pass as a JSON object or array, not a JSON-encoded string." },
-      deadline: { type: "string" }
+      artefact: { description: `The draft being submitted for review. ${STRUCTURED_PAYLOAD_NOTE} Re-requesting with the same artefact widens the reviewer set; a different artefact on an open review is refused with -32014.` },
+      deadline: { type: "string", description: "When the review is needed by, as an ISO 8601 timestamp. Recorded on the review; the coordinator does not act on it." }
     },
     required: ["workspace", "from", "task_id", "to", "artefact"]
   },
@@ -153,13 +216,9 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      approved_artefact_digest: {
-        type: "string",
-        pattern: "^sha256:[0-9a-f]{64}$",
-        description: "Optional. SHA-256 over the JCS canonicalisation of the artefact under review, as `sha256:<hex>`. Binds the decision to the exact content reviewed; refused with -32074 on mismatch."
-      },
-      comment: { type: "string" },
-      tags: { type: "array", items: { type: "string" } }
+      approved_artefact_digest: ARTEFACT_DIGEST,
+      comment: COMMENT,
+      tags: TAGS
     },
     required: ["workspace", "from", "task_id"]
   },
@@ -169,47 +228,49 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      approved_artefact_digest: {
-        type: "string",
-        pattern: "^sha256:[0-9a-f]{64}$",
-        description: "Optional. SHA-256 over the JCS canonicalisation of the artefact under review, as `sha256:<hex>`. Binds the decision to the exact content reviewed; refused with -32074 on mismatch."
-      },
-      comment: { type: "string" },
-      tags: { type: "array", items: { type: "string" } },
-      request_revision: { type: "boolean", description: "If true, task returns to in_progress instead of declined." }
+      approved_artefact_digest: ARTEFACT_DIGEST,
+      comment: COMMENT,
+      tags: TAGS,
+      request_revision: { type: "boolean", description: "When true the task returns to 'in_progress' rather than 'declined', so the assignee can revise and resubmit." }
     },
     required: ["workspace", "from", "task_id"]
   },
   "chap.decide.override": {
     type: "object",
     properties: {
-      approved_artefact_digest: {
-        type: "string",
-        pattern: "^sha256:[0-9a-f]{64}$",
-        description: "Optional. SHA-256 over the JCS canonicalisation of the artefact under review, as `sha256:<hex>`. Binds the decision to the exact content reviewed; refused with -32074 on mismatch."
-      },
+      approved_artefact_digest: ARTEFACT_DIGEST,
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
       diff: {
         type: "array",
-        description: "RFC 6902 JSON Patch operations applied to the artefact under review.",
+        description: "RFC 6902 JSON Patch operations applied to the artefact under review. The patched artefact becomes the task output; a patch that does not apply is refused with -32012.",
         items: {
           type: "object",
           properties: {
-            op: { type: "string", enum: ["add", "replace", "remove", "copy", "move", "test"] },
-            path: { type: "string" },
-            value: {},
-            from: { type: "string" }
+            op: { type: "string", enum: ["add", "replace", "remove", "copy", "move", "test"], description: "The patch operation to apply." },
+            path: { type: "string", description: "JSON Pointer into the artefact, e.g. '/body' or '/items/0/severity'." },
+            value: { description: "The new value, for add, replace and test." },
+            from: { type: "string", description: "Source JSON Pointer, for copy and move." }
           },
           required: ["op", "path"]
         }
       },
-      rationale: { type: "string", description: "Why the override was applied. Required for the structured-override audit trail." },
-      tags: { type: "array", items: { type: "string" } },
-      policy_refs: { type: "array", items: { type: "string" } },
-      logical_id: { type: "string" },
-      intent_preserved: { type: "boolean" }
+      rationale: { type: "string", description: "Why the correction was made. Required on every override and recorded in the audit entry, since the diff shows what changed but not why." },
+      tags: TAGS,
+      policy_refs: {
+        type: "array",
+        items: { type: "string" },
+        description: "Identifiers of the policies or guidelines this correction applies, e.g. ['policy:no-delivery-promises']. Recorded in the audit entry."
+      },
+      logical_id: {
+        type: "string",
+        description: "Caller-chosen identifier for the item being decided, stable across revisions and overrides of the same underlying content. Recorded in the audit entry."
+      },
+      intent_preserved: {
+        type: "boolean",
+        description: "True when the edit refines the decision the draft was making, false when it substitutes a different one. Recorded in the audit entry."
+      }
     },
     required: ["workspace", "from", "task_id", "diff", "rationale"]
   },
@@ -219,8 +280,12 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      reason: { type: "string" },
-      category: { type: "string", enum: ["conflict_of_interest", "insufficient_context", "out_of_scope", "other"] }
+      reason: { type: "string", description: "Why this reviewer is standing aside. Recorded in the audit entry." },
+      category: {
+        type: "string",
+        enum: ["conflict_of_interest", "insufficient_context", "out_of_scope", "other"],
+        description: "The kind of abstention. Recorded in the audit entry."
+      }
     },
     required: ["workspace", "from", "task_id", "reason"]
   },
@@ -229,13 +294,15 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      original_task_id: TASK_ID,
+      original_task_id: { ...TASK_ID, description: "The task being escalated. It moves to 'escalated' and is linked to the successor. A completed, cancelled or superseded task cannot be escalated." },
       new_task: {
         type: "object",
+        description: "The successor task to open for the escalation target.",
         properties: {
-          kind: { type: "string" },
-          assignee: PARTICIPANT_URI,
-          input: { type: "object", additionalProperties: true }
+          kind: { type: "string", description: "Task kind for the successor. Defaults to the original's kind." },
+          assignee: { ...PARTICIPANT_URI, description: "Who the escalation goes to. Must be a workspace member who is not paused: a paused assignee is refused with -32063." },
+          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. It defaults to an empty object rather than the original's input, so anything the new assignee needs has to be restated here." },
+          mode: { type: "string", enum: ["shadow", "trial", "production"], description: "Mode for the successor, defaulting to the original's. A mode above the workspace's current ceiling is refused with -32040, so after the ceiling is lowered a task is escalated by naming a mode within it." }
         },
         required: ["assignee"]
       }
@@ -252,15 +319,27 @@ var SCHEMAS = {
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
       to: { type: "array", items: PARTICIPANT_URI, description: "Who is being asked." },
-      question: { type: "string" },
+      question: { type: "string", description: "The question being put. A whisper is answered on its own, without the recipient opening the task." },
       options: {
         type: "array",
-        items: { type: "object", properties: { id: { type: "string" }, label: { type: "string" } }, required: ["id"] },
-        description: "Optional multiple-choice options. If present, answer_option must be one of these ids."
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "Stable identifier that an answer refers to." },
+            label: { type: "string", description: "What the option says to the person answering." }
+          },
+          required: ["id"]
+        },
+        description: "Multiple-choice options. When present, an answer must name one of these ids in answer_option; any other id is refused with -32022."
       },
-      deadline_ms: { type: "integer", description: "Time-to-live in milliseconds from now." },
-      default_if_lapsed: { description: "Value applied if the whisper lapses without an answer." },
-      urgency: { type: "string", enum: ["low", "medium", "high"], default: "low" }
+      deadline_ms: { type: "integer", description: "How long the whisper stays open, in milliseconds from now. Once it passes, the whisper lapses and default_if_lapsed is applied." },
+      default_if_lapsed: { description: "The value applied if the deadline passes with no answer. Required, so that a lapsed whisper still has a defined outcome." },
+      urgency: {
+        type: "string",
+        enum: ["low", "medium", "high"],
+        default: "low",
+        description: "How urgent the question is. Recorded and passed on to the client; it does not change the deadline or the lapse behaviour."
+      }
     },
     required: ["workspace", "from", "task_id", "to", "question", "deadline_ms", "default_if_lapsed"]
   },
@@ -269,10 +348,10 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      whisper_id: { type: "string" },
-      answer_option: { type: "string", description: "Option id (required when the whisper has options)." },
-      answer: { type: "string", description: "Free-text answer (when no options)." },
-      comment: { type: "string" }
+      whisper_id: { type: "string", description: "Identifier returned by chap.whisper.ask. A whisper that has already been answered is refused with -32020, and one past its deadline with -32021." },
+      answer_option: { type: "string", description: "The id of the chosen option. Required when the whisper carried options." },
+      answer: { type: "string", description: "Free-text answer, for a whisper with no options." },
+      comment: { type: "string", description: "Anything else the answerer wants recorded alongside the answer." }
     },
     required: ["workspace", "from", "whisper_id"]
   },
@@ -284,16 +363,16 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      to: { type: "array", items: PARTICIPANT_URI, description: "Deliberation participants." },
+      to: { type: "array", items: PARTICIPANT_URI, description: "The participants entitled to vote. A vote from anyone else is refused with -32030." },
       task_id: TASK_ID,
       rule: {
         type: "string",
-        description: "Voting rule. Examples: any_one_approves, all_approve, quorum:N, weighted_vote:T, weighted_vote_with_veto:T."
+        description: "How the outcome is decided when the deliberation closes: any_one_approves, all_approve, quorum:N, weighted_vote:T or weighted_vote_with_veto:T. An unrecognised rule is refused at open with -32033."
       },
-      question: { type: "string" },
-      weights: { type: "object", additionalProperties: { type: "number" }, description: "Voter -> weight map (for weighted rules)." },
-      veto: { type: "object", additionalProperties: { type: "boolean" }, description: "Voter -> can-veto map." },
-      deadline: { type: "string" }
+      question: { type: "string", description: "What the group is deciding. State it so that a yea or a nay is unambiguous." },
+      weights: { type: "object", additionalProperties: { type: "integer" }, description: "Voter to weight map, read by the weighted rules. A voter with no entry counts as 1. Weights must be integers: a JSON number with a fractional part is refused with -32602." },
+      veto: { type: "object", additionalProperties: { type: "boolean" }, description: "Voter to can-veto map. A veto is honoured only under weighted_vote_with_veto, and only from a voter listed true here." },
+      deadline: { type: "string", description: "When voting is intended to close, as an ISO 8601 timestamp. Recorded on the deliberation; closing is done by chap.deliberate.close and the coordinator does not close on the deadline." }
     },
     required: ["workspace", "from", "to", "rule"]
   },
@@ -302,8 +381,8 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      deliberation_id: { type: "string" },
-      comment: { type: "string" }
+      deliberation_id: { type: "string", description: "Identifier returned by chap.deliberate.open. A closed deliberation is refused with -32032." },
+      comment: { type: "string", description: "The contribution to record. Comments are kept with the deliberation and in the audit log, so the reasoning survives the vote." }
     },
     required: ["workspace", "from", "deliberation_id", "comment"]
   },
@@ -312,11 +391,11 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      deliberation_id: { type: "string" },
-      vote: { type: "string", enum: ["yea", "nay", "abstain"] },
-      weight: { type: "number" },
-      comment: { type: "string" },
-      veto_invoked: { type: "boolean" }
+      deliberation_id: { type: "string", description: "Identifier returned by chap.deliberate.open. A closed deliberation is refused with -32032, and a second vote from the same voter with -32031." },
+      vote: { type: "string", enum: ["yea", "nay", "abstain"], description: "This voter's position. An abstention is recorded but counts as neither a yea nor a nay, so under all_approve or quorum:N it withholds the approval those rules need." },
+      weight: { type: "integer", description: "Recorded with the vote. The tally uses the weights map given at chap.deliberate.open, not this value." },
+      comment: { type: "string", description: "Why the vote went this way. Recorded with it." },
+      veto_invoked: { type: "boolean", description: "Blocks the outcome regardless of the tally. Honoured only under weighted_vote_with_veto, and only when the voter is listed true in the veto map given at open." }
     },
     required: ["workspace", "from", "deliberation_id", "vote"]
   },
@@ -325,7 +404,7 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      deliberation_id: { type: "string" }
+      deliberation_id: { type: "string", description: "Identifier returned by chap.deliberate.open. Closing computes the outcome from the votes cast; closing an already closed deliberation returns the outcome unchanged." }
     },
     required: ["workspace", "from", "deliberation_id"]
   },
@@ -337,23 +416,24 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      to: { type: "string", description: "Recipient (URI or 'group:...')." },
+      to: { type: "string", description: "Recipient, as a participant URI or a group URI such as 'group:support-team'. A recipient who is not a workspace member is refused with -32052." },
       tasks: {
         type: "array",
+        description: "The work being handed over, one entry per task. Every task must currently be assigned to the proposer; otherwise the proposal is refused with -32050.",
         items: {
           type: "object",
           properties: {
             task_id: TASK_ID,
-            title: { type: "string" },
-            status_summary: { type: "string" },
-            next_action: { type: "string" },
-            blockers: { type: "array", items: { type: "string" } }
+            title: { type: "string", description: "Short label for the task." },
+            status_summary: { type: "string", description: "Where the work has reached, and what has already been tried." },
+            next_action: { type: "string", description: "What the recipient should do first." },
+            blockers: { type: "array", items: { type: "string" }, description: "What is preventing progress, if anything." }
           },
           required: ["task_id"]
         }
       },
-      summary: { type: "string" },
-      context_links: { type: "array", items: { type: "string" } }
+      summary: { type: "string", description: "Covering note for the handover as a whole, above the per-task detail." },
+      context_links: { type: "array", items: { type: "string" }, description: "URLs to threads, tickets or documents the recipient will need." }
     },
     required: ["workspace", "from", "to", "tasks"]
   },
@@ -362,9 +442,9 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      handoff_id: { type: "string" },
-      accepted_task_ids: { type: "array", items: TASK_ID, description: "If omitted, all proposed tasks are accepted." },
-      comment: { type: "string" }
+      handoff_id: { type: "string", description: "Identifier returned by chap.handoff.propose. A handoff already accepted or declined is refused with -32051." },
+      accepted_task_ids: { type: "array", items: TASK_ID, description: "Which of the proposed tasks are being accepted. If omitted, all of them are." },
+      comment: { type: "string", description: "Anything the recipient wants recorded when taking the work on." }
     },
     required: ["workspace", "from", "handoff_id"]
   },
@@ -373,9 +453,9 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      handoff_id: { type: "string" },
-      reason: { type: "string" },
-      suggested_target: PARTICIPANT_URI
+      handoff_id: { type: "string", description: "Identifier returned by chap.handoff.propose. A handoff already accepted or declined is refused with -32051." },
+      reason: { type: "string", description: "Why the handover is refused. Recorded so the proposer can route it elsewhere." },
+      suggested_target: { ...PARTICIPANT_URI, description: "Who should take it instead, if the decliner knows." }
     },
     required: ["workspace", "from", "handoff_id"]
   },
@@ -387,11 +467,20 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      scope: { type: "string", enum: ["task", "participant", "workspace"], default: "task" },
+      scope: {
+        type: "string",
+        enum: ["task", "participant", "workspace"],
+        default: "task",
+        description: "What the pause applies to. 'task' moves one task to 'paused'; a task that is completed, declined, cancelled or superseded is refused with -32061. 'participant' stops new tasks being assigned to that member and leaves their existing work running. 'workspace' refuses every method except workspace.create, workspace.describe, control.resume, audit.read, participant.join and participant.leave."
+      },
       task_id: TASK_ID,
-      participant_uri: PARTICIPANT_URI,
-      in_flight_policy: { type: "string", enum: ["allow_to_complete", "interrupt"] },
-      reason: { type: "string" }
+      participant_uri: { ...PARTICIPANT_URI, description: "Whose work to pause, when scope is 'participant'. Must be a workspace member." },
+      in_flight_policy: {
+        type: "string",
+        enum: ["allow_to_complete", "interrupt"],
+        description: "Recorded with the request, and echoed back when scope is 'participant'. The coordinator does not act on it: under either value, work already under way is left alone."
+      },
+      reason: { type: "string", description: "Why the pause was applied. Recorded in the audit entry." }
     },
     required: ["workspace", "from"]
   },
@@ -400,9 +489,14 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      scope: { type: "string", enum: ["task", "participant", "workspace"], default: "task" },
+      scope: {
+        type: "string",
+        enum: ["task", "participant", "workspace"],
+        default: "task",
+        description: "What the resume applies to. 'task' returns a paused task to the state it held at the pause; a task that is not paused is refused with -32061. 'participant' allows that member to be assigned tasks again. 'workspace' returns the workspace to active."
+      },
       task_id: TASK_ID,
-      participant_uri: PARTICIPANT_URI
+      participant_uri: { ...PARTICIPANT_URI, description: "Whose work to resume, when scope is 'participant'. Must be a workspace member." }
     },
     required: ["workspace", "from"]
   },
@@ -411,8 +505,8 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      task_id: TASK_ID,
-      reason: { type: "string" }
+      task_id: { ...TASK_ID, description: "The task to cancel. A task that is completed, declined, cancelled or superseded is refused with -32061." },
+      reason: { type: "string", description: "Why the task was cancelled. Recorded in the audit entry." }
     },
     required: ["workspace", "from", "task_id"]
   },
@@ -421,8 +515,8 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      label: { type: "string" },
-      include: { type: "array", items: { type: "string" }, description: "Aspects to snapshot, e.g. ['members', 'open_tasks', 'mode_ceiling']." }
+      label: { type: "string", description: "Name for this snapshot, recorded on the artefact. chap.control.rollback identifies a snapshot by its artefact id, not by label." },
+      include: { type: "array", items: { type: "string" }, description: "Which aspects of the workspace to capture. Recognised values are 'members', 'open_tasks', 'mode_ceiling', 'policy' and 'audit'. Defaults to members, open_tasks and mode_ceiling." }
     },
     required: ["workspace", "from"]
   },
@@ -431,9 +525,9 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      to_snapshot_artefact_id: { type: "string" },
-      what_to_restore: { type: "array", items: { type: "string" } },
-      reason: { type: "string" }
+      to_snapshot_artefact_id: { type: "string", description: "Artefact id returned by chap.control.snapshot. An id with no matching snapshot is refused with -32062." },
+      what_to_restore: { type: "array", items: { type: "string" }, description: "Which captured aspects to apply. Only 'mode_ceiling' and 'members' are restored; the others are held in the snapshot and not reapplied. Restoring members resets role and scopes on members still present, and does not re-add members who have left. Defaults to the snapshot's include list." },
+      reason: { type: "string", description: "Why the rollback was performed. The rollback is itself an audit entry; earlier entries are not rewritten." }
     },
     required: ["workspace", "from", "to_snapshot_artefact_id"]
   },
@@ -442,17 +536,20 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      task_id: TASK_ID,
+      task_id: { ...TASK_ID, description: "The task being replaced. It moves to 'superseded' and is linked to the successor rather than deleted." },
       successor_task: {
         type: "object",
+        description: "The replacement task.",
         properties: {
-          kind: { type: "string" },
-          assignee: PARTICIPANT_URI,
-          input: { type: "object", additionalProperties: true }
+          kind: { type: "string", description: "Task kind for the successor. Required." },
+          assignee: { ...PARTICIPANT_URI, description: "Who takes the replacement on. Defaults to the superseded task's assignee, and must be a workspace member who is not paused." },
+          input: { type: "object", additionalProperties: true, description: "Input payload for the successor. Defaults to an empty object." },
+          mode: { type: "string", enum: ["shadow", "trial", "production"], description: "Mode for the successor, defaulting to the superseded task's. A mode above the workspace's current ceiling is refused with -32040." },
+          review_required: { type: "boolean", description: "Whether completing the successor needs a reviewer decision. A successor of a task that requires review requires it whatever is passed here, and under modes/1.0 so does a trial-mode successor." }
         },
         required: ["kind"]
       },
-      reason: { type: "string" }
+      reason: { type: "string", description: "Why the original is being replaced. Recorded in the audit entry." }
     },
     required: ["workspace", "from", "task_id", "successor_task"]
   },
@@ -461,8 +558,12 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      new_ceiling: { type: "string", enum: ["shadow", "trial", "production"] },
-      reason: { type: "string" }
+      new_ceiling: {
+        type: "string",
+        enum: ["shadow", "trial", "production"],
+        description: "The highest mode tasks in this workspace may request from now on. Existing tasks keep the mode they were created with. Where the coordinator is configured to enforce step-up authentication this method is one of the privileged ones and a call without step-up is refused with -32402."
+      },
+      reason: { type: "string", description: "Why the ceiling is being changed. Recorded in the audit entry." }
     },
     required: ["workspace", "from", "new_ceiling"]
   },
@@ -475,7 +576,7 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      candidates: { type: "array", items: PARTICIPANT_URI, description: "Candidate assignees." }
+      candidates: { type: "array", items: PARTICIPANT_URI, description: "Candidate assignees. An empty list is refused with -32513. The default policy takes the first candidate that is a workspace member and is not paused, and refuses the call with -32510 when there is none. An operator-supplied routing policy may select on any basis; a choice that is not a member is refused with -32510, and one who is paused with -32063." }
     },
     required: ["workspace", "from", "task_id", "candidates"]
   },
@@ -487,7 +588,7 @@ var SCHEMAS = {
       task_id: TASK_ID,
       artefact_routing_hints: {
         type: "object",
-        description: "Per-artefact signals like confidence, model_id, cost_consumed_usd.",
+        description: `Per-artefact signals such as confidence, model_id and cost_consumed_usd, merged over the task's routing_hints for this call. The default policy reads criticality and confidence. If the merged set is empty the call is refused with -32514. Fractional values are written as decimal strings, e.g. "confidence": "0.86".`,
         additionalProperties: true
       }
     },
@@ -499,7 +600,7 @@ var SCHEMAS = {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
       task_id: TASK_ID,
-      default_escalation_target: PARTICIPANT_URI
+      default_escalation_target: { ...PARTICIPANT_URI, description: "Who to escalate to when the policy decides to escalate and names no target of its own. It must be a workspace member or a group URI; if the policy escalates with no usable target the call is refused with -32516." }
     },
     required: ["workspace", "from", "task_id"]
   },
@@ -511,8 +612,8 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      old_kid: { type: "string" },
-      new_jwk: { type: "object", additionalProperties: true }
+      old_kid: { type: "string", description: "Key id being retired. It is given a valid_until timestamp and stays in the member's key history, so signatures made before the rotation still verify. A key id that is unknown is refused with -32071, and one already revoked with -32072." },
+      new_jwk: { type: "object", additionalProperties: true, description: "The replacement public key as a JWK. It must carry a 'kid'. Whether the request itself has to be signed with the old key is decided at dispatch, and only where the coordinator is configured to require signatures." }
     },
     required: ["workspace", "from", "old_kid", "new_jwk"]
   },
@@ -521,9 +622,9 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      target_uri: PARTICIPANT_URI,
-      kid: { type: "string" },
-      reason: { type: "string" }
+      target_uri: { ...PARTICIPANT_URI, description: "Whose key is being revoked. Revoking another member's key requires the caller to hold the role 'admin'; otherwise the call is refused with -32011." },
+      kid: { type: "string", description: "Key id to revoke. It is marked revoked with a timestamp and a reason, and signatures presented with it are refused from then on. A key id that is unknown is refused with -32071." },
+      reason: { type: "string", description: "Why the key was revoked, e.g. 'laptop lost'. Recorded on the key and in the audit entry." }
     },
     required: ["workspace", "from", "target_uri", "kid"]
   },
@@ -537,12 +638,13 @@ var SCHEMAS = {
       from: PARTICIPANT_URI,
       range: {
         type: "object",
+        description: "Sequence window to anchor. Omit to submit the whole chain.",
         properties: {
-          from_seq: { type: "integer" },
-          to_seq: { type: "integer" }
+          from_seq: { type: "integer", description: "Start sequence number, inclusive." },
+          to_seq: { type: "integer", description: "End sequence number, exclusive." }
         }
       },
-      issuer: { type: "string" }
+      issuer: { type: "string", description: "Issuer identifier placed on each SCITT signed statement, naming who vouches for the chain. Defaults to 'service:coordinator'. Where no submitter is configured the statements are returned unsigned for the deployment to submit out of band." }
     },
     required: ["workspace"]
   },
@@ -551,7 +653,7 @@ var SCHEMAS = {
     properties: {
       workspace: WORKSPACE_ID,
       from: PARTICIPANT_URI,
-      receipt: { type: "object", additionalProperties: true }
+      receipt: { type: "object", additionalProperties: true, description: "The SCITT receipt to check, as returned by the transparency service. Verification is delegated to a hook supplied by the deployment, and fails closed with -32082 where no hook is configured." }
     },
     required: ["workspace", "receipt"]
   },