@botiverse/raft-sdk 0.9.0 → 0.11.0

package/dist/cjs/index.cjs

@@ -4753,6 +4753,7 @@ const AGENT_API_ROUTE_META = {
 	attachmentUploadSessionCancel: naturalDestructive,
 	attachmentUploadSessionStatus: read,
 	attachmentDownload: read,
+	attachmentDownloadUrl: read,
 	attachmentCommentsList: read,
 	pushWebhookStatus: {
 		sideEffect: "read",
@@ -5281,6 +5282,18 @@ const agentApiMessageReactionBodySchema = passthroughObject({ emoji: string().tr
 const agentApiChannelMembershipParamsSchema = passthroughObject({ channelId: string().trim().min(1).transform(asChannelId) });
 const agentApiChannelLifecycleBodySchema = passthroughObject({ target: string().trim().min(1) });
 const agentApiAttachmentDownloadParamsSchema = passthroughObject({ attachmentId: string().trim().min(1) });
+/**
+* Short-lived download URL for an attachment visible to the bound agent
+* credential (`GET /attachments/:attachmentId/url`). For runtimes that cannot
+* take binary tool results: the agent fetches the bytes itself from `url`
+* before `expiresAt`. The URL is a bearer capability; never log it.
+*/
+const agentApiAttachmentDownloadUrlResponseSchema = passthroughObject({
+	url: string().min(1),
+	expiresAt: string().datetime(),
+	filename: string(),
+	mimeType: string()
+});
 const agentApiAttachmentCommentsParamsSchema = passthroughObject({ attachmentId: string().trim().min(1) });
 const agentApiAttachmentCommentsQuerySchema = passthroughObject({ limit: optionalStringSchema });
 const agentApiAttachmentCommentAnchorSchema = passthroughObject({
@@ -7337,6 +7350,19 @@ const agentApiContract = {
 		request: { params: agentApiAttachmentDownloadParamsSchema },
 		response: { kind: "binary" }
 	}),
+	attachmentDownloadUrl: route({
+		key: "attachmentDownloadUrl",
+		method: "GET",
+		path: "/attachments/:attachmentId/url",
+		client: {
+			resource: "attachments",
+			method: "downloadUrl"
+		},
+		capability: "read",
+		description: "Mint a short-lived (5 minute) download URL for an attachment visible to the bound agent credential, with its filename and MIME type. 409 download_url_unavailable when this Server's storage cannot presign; use the binary download instead.",
+		request: { params: agentApiAttachmentDownloadParamsSchema },
+		response: { body: agentApiAttachmentDownloadUrlResponseSchema }
+	}),
 	attachmentCommentsList: route({
 		key: "attachmentCommentsList",
 		method: "GET",
@@ -9732,6 +9758,31 @@ const AGENT_API_ROUTE_MANIFEST = [
 			"body": false
 		}
 	},
+	{
+		"key": "attachmentDownloadUrl",
+		"method": "GET",
+		"path": "/attachments/:attachmentId/url",
+		"fullPath": "/internal/agent-api/attachments/:attachmentId/url",
+		"client": {
+			"resource": "attachments",
+			"method": "downloadUrl"
+		},
+		"capability": "read",
+		"description": "Mint a short-lived (5 minute) download URL for an attachment visible to the bound agent credential, with its filename and MIME type. 409 download_url_unavailable when this Server's storage cannot presign; use the binary download instead.",
+		"sideEffect": "read",
+		"idempotency": "natural",
+		"destructive": false,
+		"audience": "both",
+		"request": {
+			"params": true,
+			"query": false,
+			"body": false
+		},
+		"response": {
+			"kind": "json",
+			"body": true
+		}
+	},
 	{
 		"key": "attachmentCommentsList",
 		"method": "GET",
@@ -9859,7 +9910,7 @@ const AGENT_API_ROUTE_MANIFEST = [
 	}
 ];
 /** Content hash of AGENT_API_ROUTE_MANIFEST; see computeAgentApiManifestVersion. */
-const AGENT_API_MANIFEST_VERSION = "2a3c2201ea57a9d1";
+const AGENT_API_MANIFEST_VERSION = "c762a744e3542f89";
 //#endregion
 //#region src/routes.ts
 const ROUTE_INFO = Object.fromEntries(AGENT_API_ROUTE_MANIFEST.map((entry) => {
@@ -10454,6 +10505,277 @@ function fileReadError() {
 	return new RaftCredentialError("CREDENTIAL_STORE_READ_FAILED", "The Raft credential file is invalid or unreadable");
 }
 //#endregion
+//#region ../shared/src/agentOps/hint.ts
+/** `tasks.updateStatus` → `tasks_update_status`: the manifest's tool name for an operation name. */
+function raftToolNameFor(name) {
+	return name.replace(/\./g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+/** Tool-form wording for a CLI command that has no operation (channel / server admin writes). */
+const RAFT_NO_TOOL_WORDING = "ask a human via an action card (`actions_prepare`)";
+const ELLIPSIS = "…";
+function q(value) {
+	return `"${value}"`;
+}
+function hint(cli, op, fill) {
+	if (!op) return { cli };
+	const args = Object.fromEntries(Object.entries(op.args).filter(([, value]) => value !== void 0));
+	return fill && fill.length > 0 ? {
+		cli,
+		op: {
+			name: op.name,
+			args,
+			partial: true
+		},
+		fill
+	} : {
+		cli,
+		op: {
+			name: op.name,
+			args
+		}
+	};
+}
+function toolArgs(hint) {
+	const parts = Object.entries(hint.op?.args ?? {}).map(([key, value]) => `${key}: ${JSON.stringify(value)}`);
+	for (const key of hint.fill ?? []) parts.push(`${key}: ${ELLIPSIS}`);
+	return parts.length > 0 ? `{ ${parts.join(", ")} }` : "{}";
+}
+/** Render a hint: `raft message read --target "#ops"` (cli) or `messages_read({ target: "#ops" })` (tool). */
+function formatHint(hint, style = "cli") {
+	if (style === "cli") return ["raft", ...hint.cli].join(" ");
+	if (!hint.op) return RAFT_NO_TOOL_WORDING;
+	if (hint.codeOnly) return `raft.${hint.op.name}(${toolArgs(hint)})`;
+	return `${raftToolNameFor(hint.op.name)}(${toolArgs(hint)})`;
+}
+/** Just the command's name, for prose that lists commands: `raft channel join` (cli) or `channels_join` (tool). */
+function formatHintName(hint, style = "cli") {
+	if (style === "cli") return ["raft", ...hint.cli].join(" ");
+	if (!hint.op) return RAFT_NO_TOOL_WORDING;
+	return hint.codeOnly ? `raft.${hint.op.name}` : raftToolNameFor(hint.op.name);
+}
+/** A flag named in prose: `--limit` (cli) or `limit` (tool, the argument name). */
+function formatHintFlag(flag, arg, style = "cli") {
+	return style === "cli" ? `--${flag}` : arg;
+}
+/**
+* The hint as a next step: `command` is the rendered hint, `operation` the
+* structured call (when there is one). `args` keeps the step's own arguments.
+*/
+function hintStep(kind, hint, why, style = "cli", args) {
+	return {
+		kind,
+		command: formatHint(hint, style),
+		...args ? { args } : {},
+		...hint.op ? { operation: hint.op } : {},
+		why
+	};
+}
+/**
+* Every hint the shared formatters and operations produce. Placeholder
+* arguments (`<name>`, `"…"`) are `fill` keys: the CLI form prints the
+* placeholder, the tool form `name: …`.
+*/
+const RAFT_HINTS = {
+	messageRead: ({ target, after, before, around }) => hint([
+		"message",
+		"read",
+		"--target",
+		q(target),
+		...after === void 0 ? [] : ["--after", String(after)],
+		...before === void 0 ? [] : ["--before", String(before)],
+		...around === void 0 ? [] : ["--around", around.shown]
+	], {
+		name: "messages.read",
+		args: {
+			target,
+			after,
+			before,
+			around: around?.id
+		}
+	}),
+	/** Send into a conversation; `content` is always the caller's. Without a target the target is left too. */
+	messageSend: ({ target, attachmentId }) => hint([
+		"message",
+		"send",
+		...target === void 0 ? [] : ["--target", q(target)],
+		...attachmentId === void 0 ? [] : ["--attachment-id", attachmentId]
+	], {
+		name: "messages.send",
+		args: {
+			target,
+			attachmentIds: attachmentId === void 0 ? void 0 : [attachmentId]
+		}
+	}, target === void 0 ? ["target", "content"] : ["content"]),
+	/** The send command's name alone (prose, never a call). */
+	messageSendName: () => hint(["message", "send"], {
+		name: "messages.send",
+		args: {}
+	}, ["target", "content"]),
+	messageCheck: () => hint(["message", "check"], {
+		name: "inbox.check",
+		args: {}
+	}),
+	inboxList: ({ view, before } = {}) => hint([
+		"inbox",
+		"check",
+		...view === void 0 ? [] : ["--view", view],
+		...before === void 0 ? [] : ["--before", String(before)]
+	], {
+		name: "inbox.list",
+		args: {
+			view,
+			before
+		}
+	}),
+	/** `query: true` is the `<name>` placeholder. */
+	serverInfo: ({ view, offset, limit, query, joined } = {}) => hint([
+		"server",
+		"info",
+		...view === void 0 ? [] : [`--${view}`],
+		...offset === void 0 ? [] : ["--offset", String(offset)],
+		...limit === void 0 ? [] : ["--limit", String(limit)],
+		...query === void 0 ? [] : ["--query", query === true ? "<name>" : JSON.stringify(query)],
+		...joined ? ["--joined"] : []
+	], {
+		name: "server.info",
+		args: {
+			view,
+			offset,
+			limit,
+			query: typeof query === "string" ? query : void 0,
+			joined: joined ? true : void 0
+		}
+	}, query === true ? ["query"] : void 0),
+	/** `name` undefined is the `<name>` placeholder. */
+	userInfo: ({ name, offset, limit } = {}) => hint([
+		"user",
+		"info",
+		name === void 0 ? "<name>" : `@${name}`,
+		...offset === void 0 ? [] : ["--offset", String(offset)],
+		...limit === void 0 ? [] : ["--limit", String(limit)]
+	], {
+		name: "users.info",
+		args: {
+			name: name === void 0 ? void 0 : `@${name}`,
+			offset,
+			limit
+		}
+	}, name === void 0 ? ["name"] : void 0),
+	/** The `<name>` placeholder form. */
+	channelInfo: () => hint([
+		"channel",
+		"info",
+		"<name>"
+	], {
+		name: "channels.info",
+		args: {}
+	}, ["target"]),
+	channelMembers: (target) => hint([
+		"channel",
+		"members",
+		q(target)
+	], {
+		name: "channels.members",
+		args: { target }
+	}),
+	/** Channel attention commands by name (prose). */
+	channelJoinName: () => hint(["channel", "join"], {
+		name: "channels.join",
+		args: {}
+	}, ["target"]),
+	channelLeaveName: () => hint(["channel", "leave"], {
+		name: "channels.leave",
+		args: {}
+	}, ["target"]),
+	channelMuteName: () => hint(["channel", "mute"], {
+		name: "channels.mute",
+		args: {}
+	}, ["target"]),
+	channelUnmuteName: () => hint(["channel", "unmute"], {
+		name: "channels.unmute",
+		args: {}
+	}, ["target"]),
+	threadUnfollowName: () => hint(["thread", "unfollow"], {
+		name: "threads.unfollow",
+		args: {}
+	}, ["target"]),
+	/** Channel / server admin writes: no operation by policy (a human acts through an action card). */
+	channelCreateName: () => hint(["channel", "create"]),
+	serverUpdateName: () => hint(["server", "update"]),
+	taskClaim: ({ target, taskNumber }) => hint([
+		"task",
+		"claim",
+		"--target",
+		q(target),
+		"--number",
+		String(taskNumber)
+	], {
+		name: "tasks.claim",
+		args: {
+			target,
+			taskNumbers: [taskNumber]
+		}
+	}),
+	taskListAll: (target) => hint([
+		"task",
+		"list",
+		"--target",
+		q(target),
+		"--status",
+		"all"
+	], {
+		name: "tasks.list",
+		args: {
+			target,
+			status: "all"
+		}
+	}),
+	mentionAction: (action, resolutionId) => hint([
+		"mention",
+		action,
+		resolutionId
+	], {
+		name: action === "notify" ? "mentions.notify" : "mentions.add",
+		args: { resolutionIds: [resolutionId] }
+	}),
+	mentionPending: () => hint(["mention", "pending"], {
+		name: "mentions.pending",
+		args: {}
+	}),
+	/** `intent` and `reason` are always the caller's. */
+	manualGet: (topic) => hint([
+		"manual",
+		"get",
+		topic,
+		"--intent",
+		q(ELLIPSIS),
+		"--reason",
+		q(ELLIPSIS)
+	], {
+		name: "manual.get",
+		args: { topic }
+	}, ["intent", "reason"]),
+	/** The download pointer on message lines; the tool form mints a URL (one attachment: its id; several: left to fill). */
+	attachmentView: (attachmentId) => hint(["attachment", "view"], {
+		name: "attachments.downloadUrl",
+		args: { attachmentId }
+	}, attachmentId === void 0 ? ["attachmentId"] : void 0),
+	/** The binary download (typed method only): where an attachment whose URL cannot be minted is fetched. */
+	attachmentDownload: (attachmentId) => ({
+		...hint([
+			"attachment",
+			"view",
+			attachmentId,
+			"--output",
+			"<path>"
+		], {
+			name: "attachments.download",
+			args: { attachmentId }
+		}),
+		codeOnly: true
+	})
+};
+//#endregion
 //#region ../shared/src/agentOps/outcome.ts
 const SERVER_ERROR_CODE = /^[A-Za-z0-9_.:-]{1,64}$/;
 const DEFAULT_MESSAGES = {
@@ -10470,6 +10792,9 @@ const DEFAULT_MESSAGES = {
 	UNAVAILABLE: "The Raft Server could not serve this operation right now.",
 	MODEL_ONLY: "This operation only counts when the model sees its result, so it cannot be run from code; nothing was sent."
 };
+function notFoundNextAction(style) {
+	return `Check the target spelling with \`${formatHint(RAFT_HINTS.serverInfo({ view: "channels" }), style)}\` or resolve the message id first.`;
+}
 const DEFAULT_NEXT_ACTION = {
 	INVALID_REQUEST: "Fix the request arguments; nothing was sent.",
 	TRANSPORT_ERROR: "Check connectivity to the Raft Server and retry if the operation is safe to repeat.",
@@ -10477,7 +10802,7 @@ const DEFAULT_NEXT_ACTION = {
 	INVALID_RESPONSE: "Upgrade the SDK or report the Server version; the response shape is not the one this SDK knows.",
 	CAPABILITY_NOT_AUTHORIZED: "Ask a human who can mint credentials to include the missing capability.",
 	SCOPE_DENIED: "Ask a human with editAgents authority to extend this agent's scopes.",
-	NOT_FOUND: "Check the target spelling with `raft server info --channels` or resolve the message id first.",
+	NOT_FOUND: notFoundNextAction("cli"),
 	CONFLICT: "Read the current state before repeating this operation.",
 	IDEMPOTENCY_KEY_REUSED: "Use a new idempotency key for a different request, or resend the identical request to reconcile.",
 	UNSUPPORTED_FOR_EXTERNAL_AGENTS: "Use your own runtime for this; the Server does not provide it to External Agents.",
@@ -10569,6 +10894,31 @@ function failureOutcome(error) {
 	};
 }
 /**
+* Render the SDK's own default next action in a hint style. Only NOT_FOUND's
+* default names a command; it is set deep in the shared client-error mapping,
+* so `createRaft({ hints: "tool" })` re-renders it here instead of threading
+* the style through every failure. A Server-sent next action is left as is.
+*/
+function restyleDefaultNextAction(outcome, style) {
+	if (style === "cli" || !outcome || typeof outcome !== "object") return outcome;
+	const failure = outcome;
+	if (failure.ok !== false || !failure.error || failure.error.nextAction !== DEFAULT_NEXT_ACTION.NOT_FOUND) return outcome;
+	const error = {
+		...failure.error,
+		nextAction: notFoundNextAction(style)
+	};
+	const next = failure.next && failure.next.why === DEFAULT_NEXT_ACTION.NOT_FOUND ? {
+		...failure.next,
+		why: error.nextAction
+	} : failure.next ?? null;
+	return {
+		...failure,
+		error,
+		next,
+		text: formatOpErrorText(error)
+	};
+}
+/**
 * A failure of a keyed write (`idempotencyKey`). A retryable failure (the
 * request may not have reached the Server, or the Server was unavailable)
 * says to repeat the SAME request with the SAME key, and carries the key in
@@ -10991,9 +11341,10 @@ function formatAgentSenderHandle(m) {
 	const desc = m.sender_description ?? null;
 	return desc ? `@${name} — ${desc}` : `@${name}`;
 }
-function formatAgentAttachmentSuffix(attachments) {
+function formatAgentAttachmentSuffix(attachments, style = "cli") {
 	if (!attachments?.length) return "";
-	return ` [${attachments.length} attachment${attachments.length > 1 ? "s" : ""}: ${attachments.map((a) => `${a.filename} (id:${a.id})`).join(", ")} — use raft attachment view to download]`;
+	const download = formatHint(RAFT_HINTS.attachmentView(style === "tool" && attachments.length === 1 ? attachments[0].id : void 0), style);
+	return ` [${attachments.length} attachment${attachments.length > 1 ? "s" : ""}: ${attachments.map((a) => `${a.filename} (id:${a.id})`).join(", ")} — use ${download} to download]`;
 }
 function formatAgentTaskAssigneeSuffix(assigneeId, assigneeName) {
 	if (!assigneeId) return "";
@@ -11019,7 +11370,7 @@ function formatAgentTaskCurrentProjection(projection, taskNumber, neutralize) {
 	return `\n${lines.join("\n")}`;
 }
 /** One received-message line: header bracket + sender + content + suffixes. */
-function formatAgentMessageLine(m) {
+function formatAgentMessageLine(m, style = "cli") {
 	if (m.third_party_event) {
 		const msgId = m.message_id ? m.message_id.slice(0, 8) : m.third_party_event.id.slice(0, 8);
 		const time = m.timestamp ? formatUtcTimestamp(m.timestamp) : "-";
@@ -11035,22 +11386,22 @@ function formatAgentMessageLine(m) {
 	const time = m.timestamp ? formatUtcTimestamp(m.timestamp) : "-";
 	const senderType = ` type=${m.sender_type}`;
 	const content = indentAgentBodyContinuationLines(m.content ?? "");
-	const attachSuffix = formatAgentAttachmentSuffix(m.attachments);
+	const attachSuffix = formatAgentAttachmentSuffix(m.attachments, style);
 	const taskSuffix = m.task_status ? ` [task #${m.task_number} status=${m.task_status}${formatAgentTaskAssigneeSuffix(m.task_assignee_id, m.task_assignee_name)}]` : "";
 	return `[target=${target} msg=${msgId} time=${time}${senderType}] ${formatAgentSenderHandle(m)}: ${content}${attachSuffix}${taskSuffix}${formatAgentReplyAffordanceSuffix(m)}${formatAgentTaskCurrentProjection(m.task_current_projection)}`;
 }
 /** Batch of received-message lines (`raft message check` output). */
-function formatAgentMessages(messages) {
+function formatAgentMessages(messages, style = "cli") {
 	if (messages.length === 0) return "No new inbox messages.";
-	return messages.map(formatAgentMessageLine).join("\n");
+	return messages.map((m) => formatAgentMessageLine(m, style)).join("\n");
 }
 /**
 * `message check` hands over a bounded batch, oldest first per conversation;
 * the server reports how many conversations still have unread after it.
 */
-function formatAgentInboxHint(hint) {
+function formatAgentInboxHint(hint, style = "cli") {
 	const n = hint.unread_conversations;
-	return `Still unread: ${n} ${n === 1 ? "conversation" : "conversations"}. Run \`raft inbox check\` to list them.`;
+	return `Still unread: ${n} ${n === 1 ? "conversation" : "conversations"}. Run \`${formatHint(RAFT_HINTS.inboxList(), style)}\` to list them.`;
 }
 //#endregion
 //#region ../shared/src/agentOps/message.ts
@@ -11094,7 +11445,7 @@ function hasAgentMessageIdentity(envelope) {
 	return true;
 }
 /** Project one envelope; `null` when it has no conversation identity (skip it rather than render `#undefined`). */
-function projectRaftMessage(envelope) {
+function projectRaftMessage(envelope, style = "cli") {
 	if (!hasAgentMessageIdentity(envelope)) return null;
 	const like = toAgentMessageLike(envelope);
 	const id = nullableString(like.message_id);
@@ -11127,7 +11478,7 @@ function projectRaftMessage(envelope) {
 			id: nullableString(envelope.threadId),
 			replyCount: nullableNumber(envelope.replyCount)
 		},
-		text: formatAgentMessageLine(like),
+		text: formatAgentMessageLine(like, style),
 		raw: envelope
 	};
 }
@@ -11135,8 +11486,8 @@ function sortBySeq(messages) {
 	return [...messages].sort((a, b) => (a.seq ?? Number.MAX_SAFE_INTEGER) - (b.seq ?? Number.MAX_SAFE_INTEGER));
 }
 /** Project a list, skipping envelopes without a conversation identity. */
-function projectRaftMessages(envelopes) {
-	return envelopes.map(projectRaftMessage).filter((m) => m !== null);
+function projectRaftMessages(envelopes, style = "cli") {
+	return envelopes.map((envelope) => projectRaftMessage(envelope, style)).filter((m) => m !== null);
 }
 /** The conversation fields a target string names; `null` for a shape this cannot read. */
 function identityFromTarget(target) {
@@ -11168,12 +11519,12 @@ function identityFromTarget(target) {
 * because the request already named the target; fill them from `target`
 * instead of dropping the message.
 */
-function projectRaftMessagesInTarget(envelopes, target) {
+function projectRaftMessagesInTarget(envelopes, target, style = "cli") {
 	const identity = identityFromTarget(target);
 	return envelopes.map((envelope) => projectRaftMessage(identity && !hasAgentMessageIdentity(envelope) ? {
 		...envelope,
 		...identity
-	} : envelope)).filter((m) => m !== null);
+	} : envelope, style)).filter((m) => m !== null);
 }
 //#endregion
 //#region ../shared/src/agentOps/interrupt.ts
@@ -11185,7 +11536,7 @@ function isInterrupted(outcome) {
 function unreadMessagesInterrupt(input) {
 	const { hold, target } = input;
 	const withheld = input.withheld === true || hold.freshnessContextMode === "withheld";
-	const heldMessages = withheld ? [] : projectRaftMessagesInTarget(hold.heldMessages ?? [], target);
+	const heldMessages = withheld ? [] : projectRaftMessagesInTarget(hold.heldMessages ?? [], target, input.hints);
 	const newMessageCount = withheld ? hold.withheldMessageCount ?? hold.newMessageCount ?? 0 : hold.newMessageCount ?? heldMessages.length;
 	const omittedMessageCount = withheld ? 0 : hold.omittedMessageCount ?? 0;
 	return {
@@ -11476,18 +11827,9 @@ const inboxPullFields = {
 };
 const checkInboxRequestSchema = requestSchema()(object(inboxPullFields));
 const MAX_DRAIN_ROUNDS = 50;
-function batchNext(batch) {
-	if (batch.hasMore) return {
-		kind: "check_inbox_again",
-		command: "raft message check",
-		...batch.cursor === null ? {} : { args: { since: batch.cursor } },
-		why: "The Server trimmed this batch; more messages are pending."
-	};
-	if ((batch.stillUnreadConversations ?? 0) > 0) return {
-		kind: "list_inbox",
-		command: "raft inbox check",
-		why: "Conversations remain unread beyond this batch."
-	};
+function batchNext(batch, style) {
+	if (batch.hasMore) return hintStep("check_inbox_again", RAFT_HINTS.messageCheck(), "The Server trimmed this batch; more messages are pending.", style, batch.cursor === null ? void 0 : { since: batch.cursor });
+	if ((batch.stillUnreadConversations ?? 0) > 0) return hintStep("list_inbox", RAFT_HINTS.inboxList(), "Conversations remain unread beyond this batch.", style);
 	if (batch.messages.length > 0) return {
 		kind: "reply_or_act",
 		args: { target: batch.messages[0].target },
@@ -11495,11 +11837,11 @@ function batchNext(batch) {
 	};
 	return null;
 }
-function batchText(batch) {
-	const lines = [formatAgentMessages(batch.messages.map((m) => toAgentMessageLike(m.raw)))];
-	if (batch.hasMore) lines.push("More messages are pending. Run `raft message check` again.");
+function batchText(batch, style) {
+	const lines = [formatAgentMessages(batch.messages.map((m) => toAgentMessageLike(m.raw)), style)];
+	if (batch.hasMore) lines.push(`More messages are pending. Run \`${formatHint(RAFT_HINTS.messageCheck(), style)}\` again.`);
 	else if (batch.messages.length > 0) lines.push("No more new inbox messages.");
-	if ((batch.stillUnreadConversations ?? 0) > 0) lines.push(formatAgentInboxHint({ unread_conversations: batch.stillUnreadConversations }));
+	if ((batch.stillUnreadConversations ?? 0) > 0) lines.push(formatAgentInboxHint({ unread_conversations: batch.stillUnreadConversations }, style));
 	return lines.join("\n");
 }
 function recordExactSeen(frontier, messages) {
@@ -11512,7 +11854,8 @@ function recordExactSeen(frontier, messages) {
 	for (const [target, seqs] of byTarget) frontier.recordExact(target, seqs);
 }
 /** One bounded pull. Records exact seen seqs on `frontier` (sparse drains never advance the high-water mark). */
-async function checkInbox(client, request = {}, frontier) {
+async function checkInbox(client, request = {}, frontier, options = {}) {
+	const style = options.hints ?? "cli";
 	const invalid = validateOpRequest(checkInboxRequestSchema, request);
 	if (invalid) return invalid;
 	const ack = request.ack ?? "cursor";
@@ -11523,7 +11866,7 @@ async function checkInbox(client, request = {}, frontier) {
 	});
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
-	const messages = sortBySeq(projectRaftMessages(data.events));
+	const messages = sortBySeq(projectRaftMessages(data.events, style));
 	recordExactSeen(frontier, messages);
 	const batch = {
 		messages,
@@ -11537,8 +11880,8 @@ async function checkInbox(client, request = {}, frontier) {
 		ok: true,
 		state: messages.length > 0 ? "batch" : "empty",
 		data: batch,
-		next: batchNext(batch),
-		text: batchText(batch)
+		next: batchNext(batch, style),
+		text: batchText(batch, style)
 	};
 }
 const drainInboxRequestSchema = requestSchema()(object(inboxPullFields));
@@ -11552,7 +11895,7 @@ const drainInboxRequestSchema = requestSchema()(object(inboxPullFields));
 * return value summarises the drain; the batch that ends the iteration is
 * acknowledged only by the caller's next pull (`summary.cursor`).
 */
-async function* drainInbox(client, request = {}, frontier, onPull) {
+async function* drainInbox(client, request = {}, frontier, onPull, options = {}) {
 	const ack = request.ack ?? "cursor";
 	const invalid = validateOpRequest(drainInboxRequestSchema, request);
 	if (invalid) return {
@@ -11574,7 +11917,7 @@ async function* drainInbox(client, request = {}, frontier, onPull) {
 			...sent === null ? {} : { since: sent },
 			limit: request.limit,
 			ack
-		}, frontier);
+		}, frontier, options);
 		if (!round.ok) return {
 			cursor,
 			ackMode,
@@ -11624,25 +11967,18 @@ async function* drainInbox(client, request = {}, frontier, onPull) {
 	};
 }
 /** Fold a finished drain into one outcome; a drain that failed before its first batch is that failure. */
-function drainedInboxOutcome(batches, summary) {
+function drainedInboxOutcome(batches, summary, options = {}) {
 	if (summary.error && batches.length === 0) return summary.error;
+	const style = options.hints ?? "cli";
 	const messages = batches.flatMap((batch) => batch.messages);
-	const lines = [formatAgentMessages(messages.map((m) => toAgentMessageLike(m.raw)))];
+	const lines = [formatAgentMessages(messages.map((m) => toAgentMessageLike(m.raw)), style)];
 	if (summary.error) lines.push("The drain stopped early on an error; more messages may be pending. Check the inbox again.");
 	else if (summary.hasMore) lines.push("More messages are pending. Check the inbox again.");
 	else if (messages.length > 0) lines.push("No more new inbox messages.");
 	const stillUnread = summary.stillUnreadConversations ?? 0;
-	if (stillUnread > 0) lines.push(formatAgentInboxHint({ unread_conversations: stillUnread }));
+	if (stillUnread > 0) lines.push(formatAgentInboxHint({ unread_conversations: stillUnread }, style));
 	const first = messages[0];
-	const next = summary.hasMore ? {
-		kind: "check_inbox_again",
-		command: "raft message check",
-		why: "More messages are pending."
-	} : stillUnread > 0 ? {
-		kind: "list_inbox",
-		command: "raft inbox check",
-		why: "Conversations remain unread beyond this drain."
-	} : first ? {
+	const next = summary.hasMore ? hintStep("check_inbox_again", RAFT_HINTS.messageCheck(), "More messages are pending.", style) : stillUnread > 0 ? hintStep("list_inbox", RAFT_HINTS.inboxList(), "Conversations remain unread beyond this drain.", style) : first ? {
 		kind: "reply_or_act",
 		args: { target: first.target },
 		why: "Handle the messages above; reply where each one came from."
@@ -11664,23 +12000,21 @@ const listInboxRequestSchema = requestSchema()(object({
 	before: number$1().int().nonnegative().optional().describe("Next page: the nextBeforeSeq of the previous page."),
 	limit: number$1().int().positive().optional().describe("Conversations per page, 1..50 (Server default 20).")
 }));
-function openCommandFor(item) {
-	return `raft message read --target "${item.target}" --after ${item.lastReadSeq}`;
+function openHint(item) {
+	return RAFT_HINTS.messageRead({
+		target: item.target,
+		after: item.lastReadSeq
+	});
 }
-function listingNext(listing) {
+function listingNext(listing, style) {
 	const first = listing.conversations[0];
-	if (first) return {
-		kind: "read_target",
-		command: first.openCommand,
-		args: {
-			target: first.target,
-			after: first.lastReadSeq
-		},
-		why: "Open the newest unread conversation from your read position."
-	};
+	if (first) return hintStep("read_target", openHint(first), "Open the newest unread conversation from your read position.", style, {
+		target: first.target,
+		after: first.lastReadSeq
+	});
 	return null;
 }
-function listingText(listing) {
+function listingText(listing, style) {
 	const t = listing.totals;
 	const head = t.conversations === 0 ? "Inbox: nothing unread." : `Inbox: ${t.conversations} unread ${t.conversations === 1 ? "conversation" : "conversations"} (${t.dms} DMs, ${t.mentions} with mentions).${listing.conversations.length > 0 ? " Newest activity first." : ""}`;
 	const rows = listing.conversations.map((c) => {
@@ -11688,8 +12022,14 @@ function listingText(listing) {
 		return `${c.target} · ${c.unread} unread${flags ? ` · ${flags}` : ""}${c.latestSenderName ? ` · latest @${c.latestSenderName}` : ""}\n  open: ${c.openCommand}`;
 	});
 	const trailer = [];
-	if (listing.hasMore && listing.nextBeforeSeq !== null) trailer.push(`More: raft inbox check${listing.view === "mentions" ? " --view mentions" : ""} --before ${listing.nextBeforeSeq}`);
-	const next = listingNext(listing);
+	if (listing.hasMore && listing.nextBeforeSeq !== null) {
+		const more = RAFT_HINTS.inboxList({
+			...listing.view === "mentions" ? { view: "mentions" } : {},
+			before: listing.nextBeforeSeq
+		});
+		trailer.push(`More: ${formatHint(more, style)}`);
+	}
+	const next = listingNext(listing, style);
 	trailer.push(next?.command ? `Next: open the first conversation above: ${next.command}` : "Next: nothing to do.");
 	return [
 		head,
@@ -11698,7 +12038,8 @@ function listingText(listing) {
 	].join("\n");
 }
 /** The agent's Activity panel. Lists only; nothing is consumed. */
-async function listInbox(client, request = {}) {
+async function listInbox(client, request = {}, options = {}) {
+	const style = options.hints ?? "cli";
 	const invalid = validateOpRequest(listInboxRequestSchema, request);
 	if (invalid) return invalid;
 	const result = await client.inbox.list({
@@ -11719,7 +12060,7 @@ async function listInbox(client, request = {}) {
 			activitySeq: item.activitySeq,
 			latestSenderName: item.latestSenderName,
 			latestAt: item.latestAt,
-			openCommand: openCommandFor(item)
+			openCommand: formatHint(openHint(item), style)
 		})),
 		totals: data.totals,
 		hasMore: data.hasMore,
@@ -11729,8 +12070,8 @@ async function listInbox(client, request = {}) {
 		ok: true,
 		state: listing.conversations.length > 0 ? "listed" : "empty",
 		data: listing,
-		next: listingNext(listing),
-		text: listingText(listing)
+		next: listingNext(listing, style),
+		text: listingText(listing, style)
 	};
 }
 //#endregion
@@ -11745,38 +12086,34 @@ const readHistoryRequestSchema = requestSchema()(object({
 	limit: number$1().int().positive().optional().describe("Maximum messages in the window."),
 	consume: boolean().optional().describe("false reads without consuming: the conversation is not marked read and nothing counts as seen.")
 }));
-function historyNext(page) {
+function historyNext(page, style) {
 	const seqs = page.messages.map((m) => m.seq).filter((s) => s !== null);
 	if (page.hasNewer && seqs.length > 0) {
 		const max = Math.max(...seqs);
-		return {
-			kind: "read_newer",
-			command: `raft message read --target "${page.target}" --after ${max}`,
-			args: {
-				target: page.target,
-				after: max
-			},
-			why: "Newer messages exist beyond this window."
-		};
+		return hintStep("read_newer", RAFT_HINTS.messageRead({
+			target: page.target,
+			after: max
+		}), "Newer messages exist beyond this window.", style, {
+			target: page.target,
+			after: max
+		});
 	}
 	if (page.hasOlder && seqs.length > 0) {
 		const min = Math.min(...seqs);
-		return {
-			kind: "read_older",
-			command: `raft message read --target "${page.target}" --before ${min}`,
-			args: {
-				target: page.target,
-				before: min
-			},
-			why: "Older messages exist before this window; read them only if the task needs them."
-		};
+		return hintStep("read_older", RAFT_HINTS.messageRead({
+			target: page.target,
+			before: min
+		}), "Older messages exist before this window; read them only if the task needs them.", style, {
+			target: page.target,
+			before: min
+		});
 	}
 	return null;
 }
-function historyText(page) {
+function historyText(page, style) {
 	if (page.messages.length === 0) return `No messages in ${page.target}.`;
-	const lines = [formatAgentMessages(page.messages.map((m) => toAgentMessageLike(m.raw)))];
-	const next = historyNext(page);
+	const lines = [formatAgentMessages(page.messages.map((m) => toAgentMessageLike(m.raw)), style)];
+	const next = historyNext(page, style);
 	if (next?.command) lines.push(`${next.kind === "read_newer" ? "Newer" : "Older"} exist: ${next.command}`);
 	return lines.join("\n");
 }
@@ -11796,7 +12133,8 @@ function recordHistorySeen(frontier, requested, page, around) {
 	}
 	frontier.recordExact(page.target, seqs);
 }
-async function readHistory(client, request, frontier) {
+async function readHistory(client, request, frontier, options = {}) {
+	const style = options.hints ?? "cli";
 	const invalid = validateOpRequest(readHistoryRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target is required to read history." }));
@@ -11812,7 +12150,7 @@ async function readHistory(client, request, frontier) {
 	const data = result.data;
 	const page = {
 		target: typeof data.target === "string" && data.target ? data.target : request.target,
-		messages: sortBySeq(projectRaftMessages(data.messages)),
+		messages: sortBySeq(projectRaftMessages(data.messages, style)),
 		hasOlder: data.has_older === true,
 		hasNewer: data.has_newer === true,
 		lastReadSeq: typeof data.last_read_seq === "number" ? data.last_read_seq : null,
@@ -11823,8 +12161,8 @@ async function readHistory(client, request, frontier) {
 		ok: true,
 		state: page.messages.length > 0 ? "page" : "empty",
 		data: page,
-		next: historyNext(page),
-		text: historyText(page)
+		next: historyNext(page, style),
+		text: historyText(page, style)
 	};
 }
 /** Attempts for a keyed send whose request never reached the Server (transport failure only). */
@@ -11848,68 +12186,60 @@ const replyToRequestSchema = requestSchema()(object({
 	...sendMessageFields
 }));
 /** Today's held text (unchanged); it is the interrupt's `context` and the outcome's `text`. */
-function heldText(held, action) {
+function heldText(held, action, style) {
 	const noun = held.newMessageCount === 1 ? "message" : "messages";
 	const head = `Held — ${held.newMessageCount} unread ${noun} in ${held.target}. ${action}`;
 	if (held.withheld) return `${head}\nContext withheld (reviewer isolation).`;
 	const lines = [head];
 	if (held.formalMentionCount > 0) lines.push(`Note: ${held.formalMentionCount} of these messages formally @mention you.`);
 	if (held.omittedMessageCount > 0) lines.push(`${held.omittedMessageCount} earlier ${held.omittedMessageCount === 1 ? "message" : "messages"} not shown.`);
-	if (held.heldMessages.length > 0) lines.push(formatAgentMessages(held.heldMessages.map((m) => toAgentMessageLike(m.raw))));
+	if (held.heldMessages.length > 0) lines.push(formatAgentMessages(held.heldMessages.map((m) => toAgentMessageLike(m.raw)), style));
 	if (!held.contextComplete) lines.push("Not all of them are shown here; read the conversation before sending again.");
-	lines.push(`Full text: raft message read --target "${held.target}"`);
+	lines.push(`Full text: ${formatHint(RAFT_HINTS.messageRead({ target: held.target }), style)}`);
 	return lines.join("\n");
 }
 /**
 * A Server freshness hold as the `unread_messages` interrupt: the structured
 * details, today's held text as `context`, and the given resume / cancel.
 */
-function heldInterrupt(target, data, action, resume, cancel) {
+function heldInterrupt(target, data, action, resume, cancel, style = "cli") {
 	const interrupt = unreadMessagesInterrupt({
 		target,
 		hold: data,
 		context: "",
 		resume,
-		...cancel ? { cancel } : {}
+		...cancel ? { cancel } : {},
+		hints: style
 	});
 	return {
 		...interrupt,
-		context: heldText(interrupt, action)
+		context: heldText(interrupt, action, style)
 	};
 }
-function heldSendNext(interrupt) {
-	return {
-		kind: "resend",
-		command: `raft message read --target "${interrupt.target}"`,
-		args: { target: interrupt.target },
-		why: interrupt.withheld ? "Newer messages exist in this conversation but were withheld; read them, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : !interrupt.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : "Newer messages arrived in this conversation. Show interrupt.context to the model, call frontier.recordHeld(interrupt) to attest that, then resume the send (interrupt.resume, same idempotencyKey) or cancel it."
-	};
+function heldSendNext(interrupt, style) {
+	return hintStep("resend", RAFT_HINTS.messageRead({ target: interrupt.target }), interrupt.withheld ? "Newer messages exist in this conversation but were withheld; read them, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : !interrupt.contextComplete ? "Newer messages arrived in this conversation and not all of them are shown here; read the conversation, then resume the send (interrupt.resume, same idempotencyKey) or cancel it." : "Newer messages arrived in this conversation. Show interrupt.context to the model, call frontier.recordHeld(interrupt) to attest that, then resume the send (interrupt.resume, same idempotencyKey) or cancel it.", style, { target: interrupt.target });
 }
 function isHeldResponse(data) {
 	return Boolean(data) && typeof data === "object" && data.state === "held";
 }
-function sentOutcome(target, data) {
+function sentOutcome(target, data, style) {
 	const sent = {
 		messageId: data.messageId,
 		messageSeq: typeof data.messageSeq === "number" ? data.messageSeq : null,
 		unresolvedMentionHandles: data.unresolvedMentionHandles ?? [],
-		recentUnread: projectRaftMessages(data.recentUnread ?? [])
+		recentUnread: projectRaftMessages(data.recentUnread ?? [], style)
 	};
 	const warn = sent.unresolvedMentionHandles.length > 0 ? ` Unresolved @handles: ${sent.unresolvedMentionHandles.map((h) => `@${h}`).join(", ")}.` : "";
 	return {
 		ok: true,
 		state: "sent",
 		data: sent,
-		next: sent.recentUnread.length > 0 ? {
-			kind: "read_target",
-			command: `raft message read --target "${target}"`,
-			args: { target },
-			why: "Newer messages arrived while you were sending."
-		} : null,
+		next: sent.recentUnread.length > 0 ? hintStep("read_target", RAFT_HINTS.messageRead({ target }), "Newer messages arrived while you were sending.", style, { target }) : null,
 		text: `Message sent to ${target}. Message ID: ${sent.messageId}${warn}`
 	};
 }
-async function sendMessage(client, request, frontier) {
+async function sendMessage(client, request, frontier, options = {}) {
+	const style = options.hints ?? "cli";
 	const invalid = validateOpRequest(sendMessageRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target is required to send a message." }));
@@ -11933,16 +12263,16 @@ async function sendMessage(client, request, frontier) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey));
+		const interrupt = heldInterrupt(request.target, data, "Your message was not sent.", inProcessSendResume(idempotencyKey), void 0, style);
 		return {
 			ok: true,
 			state: "interrupted",
 			interrupt,
-			next: heldSendNext(interrupt),
+			next: heldSendNext(interrupt, style),
 			text: interrupt.context
 		};
 	}
-	if (data.state === "sent") return sentOutcome(request.target, data);
+	if (data.state === "sent") return sentOutcome(request.target, data, style);
 	return failureOutcome(opError("INVALID_RESPONSE", { message: `Unexpected send state "${data.state}".` }));
 }
 function taskTimestamps(t) {
@@ -12024,13 +12354,13 @@ function formatAgentMyTaskList(data, statusFilter) {
 	].join("\n");
 }
 /** Receipt for task create. */
-function formatAgentTasksCreated(channel, data) {
+function formatAgentTasksCreated(channel, data, style = "cli") {
 	const created = data.tasks.map((t) => {
 		const assignee = t.claimedById ? t.claimedByName ? `@${t.claimedByName}` : "<unresolved>" : "unassigned";
 		const resourceReceipt = t.requiresResourceReceipt ? " resource-receipt=pending" : "";
 		return `#${t.taskNumber} [${t.status}] assignee=${assignee} claimedAt=${t.claimedAt ?? "null"} msg=${t.messageId.slice(0, 8)}${resourceReceipt} "${t.title}"`;
 	}).join("\n");
-	const threadHints = data.tasks.map((t) => `#${t.taskNumber} → raft message send --target "${channel}:${t.messageId.slice(0, 8)}"`).join("\n");
+	const threadHints = data.tasks.map((t) => `#${t.taskNumber} → ${formatHint(RAFT_HINTS.messageSend({ target: `${channel}:${t.messageId.slice(0, 8)}` }), style)}`).join("\n");
 	const receipt = data.assignmentReceipt ? `\n\nAssignment receipt (msg=${data.assignmentReceipt.messageId.slice(0, 8)}):\n${data.assignmentReceipt.content}` : "";
 	return `Created ${data.tasks.length} task(s) in ${channel}:\n${created}${receipt}\n\nTo follow up in each task's thread:\n${threadHints}`;
 }
@@ -12053,7 +12383,7 @@ function agentTaskThreadTarget(target, messageId) {
 	return `${canonicalAgentTaskTarget(target)}:${messageId.slice(0, 8)}`;
 }
 /** Claim results incl. concurrency-lock guidance on failed claims. */
-function formatAgentClaimResults(channel, data) {
+function formatAgentClaimResults(channel, data, style = "cli") {
 	const lines = data.results.map((r) => {
 		const label = r.taskNumber ? `#${r.taskNumber}` : `msg:${r.messageId}`;
 		if (r.success) return `${label} (msg:${r.messageId ? r.messageId.slice(0, 8) : ""}): claimed`;
@@ -12065,7 +12395,7 @@ function formatAgentClaimResults(channel, data) {
 	const failed = data.results.length - succeeded;
 	let summary = `${succeeded} claimed`;
 	if (failed > 0) summary += `, ${failed} failed`;
-	const claimedMsgs = data.results.filter((r) => r.success && r.messageId).map((r) => `#${r.taskNumber} → raft message send --target "${agentTaskThreadTarget(channel, r.messageId)}"`).join("\n");
+	const claimedMsgs = data.results.filter((r) => r.success && r.messageId).map((r) => `#${r.taskNumber} → ${formatHint(RAFT_HINTS.messageSend({ target: agentTaskThreadTarget(channel, r.messageId) }), style)}`).join("\n");
 	const threadHint = claimedMsgs ? `\n\nFollow up in each task's thread:\n${claimedMsgs}` : "";
 	return `Claim results (${summary}):\n${lines.join("\n")}${threadHint}`;
 }
@@ -12082,13 +12412,13 @@ function formatAgentTaskDeleted(taskNumber) {
 	return `#${taskNumber} deleted.`;
 }
 /** Message→task conversion receipt. */
-function formatAgentTaskConverted(channel, task) {
+function formatAgentTaskConverted(channel, task, style = "cli") {
 	const target = `${canonicalAgentTaskTarget(channel)}:${task.messageId.slice(0, 8)}`;
 	return [
 		`Converted msg=${task.messageId.slice(0, 8)} to task #${task.taskNumber} [${task.status}] assignee=unassigned "${task.title}"`,
 		"",
 		`To follow up in the task's thread:`,
-		`raft message send --target "${target}"`
+		formatHint(RAFT_HINTS.messageSend({ target }), style)
 	].join("\n");
 }
 function formatAgentTaskAmended(data) {
@@ -12150,15 +12480,16 @@ const claimTasksRequestSchema = requestSchema()(object({
 * A held task call: the interrupt whose resume is the identical command, with
 * no cancel (a held task call saved nothing). `context` is today's held text.
 */
-function heldTaskInterrupt(target, data, action, after, argv) {
+function heldTaskInterrupt(target, data, action, after, argv, style) {
 	const interrupt = unreadMessagesInterrupt({
 		target,
 		hold: data,
 		context: "",
-		resume: { argv }
+		resume: { argv },
+		hints: style
 	});
 	const noun = interrupt.newMessageCount === 1 ? "message" : "messages";
-	const context = `Held — ${interrupt.newMessageCount} unread ${noun} in ${target}. ${action}\nRead them with: raft message read --target "${target}"\n${after}`;
+	const context = `Held — ${interrupt.newMessageCount} unread ${noun} in ${target}. ${action}\nRead them with: ${formatHint(RAFT_HINTS.messageRead({ target }), style)}\n${after}`;
 	return {
 		...interrupt,
 		context
@@ -12170,17 +12501,14 @@ function rowState(result) {
 	if (result.conflict?.kind === "claim_conflict") return "conflict";
 	return "refused";
 }
-function claimNext(claim) {
+function claimNext(claim, style) {
 	const first = claim.rows.find((row) => row.mayWork);
 	if (first) {
 		const thread = first.messageId ? agentTaskThreadTarget(claim.target, first.messageId) : null;
-		return {
+		const why = "The claim is yours; post progress in the task's thread.";
+		return thread ? hintStep("start_work", RAFT_HINTS.messageSend({ target: thread }), why, style, { target: thread }) : {
 			kind: "start_work",
-			...thread ? {
-				command: `raft message send --target "${thread}"`,
-				args: { thread }
-			} : {},
-			why: "The claim is yours; post progress in the task's thread."
+			why
 		};
 	}
 	return {
@@ -12188,10 +12516,11 @@ function claimNext(claim) {
 		why: "No claim authorised work. Do not retry the identical claim and do not start conflicting execution; if you own this lane, correct the routing in the original thread."
 	};
 }
-function claimText(claim) {
-	return formatAgentClaimResults(claim.target, { results: claim.rows.map((row) => row.raw) });
+function claimText(claim, style) {
+	return formatAgentClaimResults(claim.target, { results: claim.rows.map((row) => row.raw) }, style);
 }
-async function claimTasks(client, request) {
+async function claimTasks(client, request, options = {}) {
+	const style = options.hints ?? "cli";
 	const numbers = (request.taskNumbers ?? []).filter((n) => Number.isInteger(n) && n > 0);
 	const ids = (request.messageIds ?? []).map((id) => id.trim()).filter(Boolean);
 	const invalid = validateOpRequest(claimTasksRequestSchema, request);
@@ -12206,17 +12535,12 @@ async function claimTasks(client, request) {
 	if (!result.ok) return failureFromClientResult(result);
 	const data = result.data;
 	if (isHeldResponse(data)) {
-		const interrupt = heldTaskInterrupt(request.target, data, "Your task claim was not applied.", "After reviewing, rerun the claim if it is still correct.", taskClaimArgv(request.target, numbers, ids));
+		const interrupt = heldTaskInterrupt(request.target, data, "Your task claim was not applied.", "After reviewing, rerun the claim if it is still correct.", taskClaimArgv(request.target, numbers, ids), style);
 		return {
 			ok: true,
 			state: "interrupted",
 			interrupt,
-			next: {
-				kind: "retry_claim",
-				command: `raft message read --target "${request.target}"`,
-				args: { target: request.target },
-				why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume the claim (interrupt.resume) if it is still right."
-			},
+			next: hintStep("retry_claim", RAFT_HINTS.messageRead({ target: request.target }), "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume the claim (interrupt.resume) if it is still right.", style, { target: request.target }),
 			text: interrupt.context
 		};
 	}
@@ -12243,8 +12567,8 @@ async function claimTasks(client, request) {
 		ok: true,
 		state: !claim.anyAuthorised ? "refused" : rows.every((row) => row.mayWork) ? "claimed" : "partial",
 		data: claim,
-		next: claimNext(claim),
-		text: claimText(claim)
+		next: claimNext(claim, style),
+		text: claimText(claim, style)
 	};
 }
 const listTasksRequestSchema = requestSchema()(object({
@@ -12259,7 +12583,7 @@ const listTasksRequestSchema = requestSchema()(object({
 		"all"
 	]).optional().describe("Filter by status; all includes done and closed.")
 }));
-async function listTasks(client, request) {
+async function listTasks(client, request, options = {}) {
 	const invalid = validateOpRequest(listTasksRequestSchema, request);
 	if (invalid) return invalid;
 	const mine = request.mine === true;
@@ -12278,15 +12602,13 @@ async function listTasks(client, request) {
 	};
 	const text = mine ? formatAgentMyTaskList(data, request.status) : formatAgentTaskList(request.target, data, request.status);
 	const open = board.tasks.find((t) => t.status === "todo" && !t.claimedByName);
-	const next = open?.taskNumber && board.target ? {
-		kind: "claim_task",
-		command: `raft task claim --target "${board.target}" --number ${open.taskNumber}`,
-		args: {
-			target: board.target,
-			taskNumbers: [open.taskNumber]
-		},
-		why: "An unassigned todo task is open; claim it before working on it."
-	} : null;
+	const next = open?.taskNumber && board.target ? hintStep("claim_task", RAFT_HINTS.taskClaim({
+		target: board.target,
+		taskNumber: open.taskNumber
+	}), "An unassigned todo task is open; claim it before working on it.", options.hints, {
+		target: board.target,
+		taskNumbers: [open.taskNumber]
+	}) : null;
 	return {
 		ok: true,
 		state: board.tasks.length > 0 ? "board" : "empty",
@@ -12304,7 +12626,7 @@ const createTasksRequestSchema = requestSchema()(object({
 	assignee: string().optional().describe("`@handle`: yourself to start in_progress, or (owner/admin) someone else to reserve a todo."),
 	idempotencyKey: string().optional().describe("One key per logical create; generated when omitted and returned. Repeat the same request with the same key within 24 hours to retry without creating the tasks twice.")
 }));
-async function createTasks(client, request) {
+async function createTasks(client, request, options = {}) {
 	const invalid = validateOpRequest(createTasksRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim() || !request.tasks?.length) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and at least one task title are required." }));
@@ -12329,15 +12651,15 @@ async function createTasks(client, request) {
 			target: request.target,
 			idempotencyKey
 		},
-		next: first ? {
-			kind: "post_in_task_thread",
-			command: `raft message send --target "${agentTaskThreadTarget(request.target, first.messageId)}"`,
-			args: { thread: agentTaskThreadTarget(request.target, first.messageId) },
-			why: "Follow up in each task's thread."
-		} : null,
-		text: formatAgentTasksCreated(request.target, data)
+		next: first ? taskThreadStep(request.target, first.messageId, "Follow up in each task's thread.", options.hints) : null,
+		text: formatAgentTasksCreated(request.target, data, options.hints)
 	};
 }
+/** Post in a task's thread (a send: `content` is the caller's). */
+function taskThreadStep(target, messageId, why, style = "cli") {
+	const thread = agentTaskThreadTarget(target, messageId);
+	return hintStep("post_in_task_thread", RAFT_HINTS.messageSend({ target: thread }), why, style, { target: thread });
+}
 const taskRefFields = {
 	target: taskChannelSchema,
 	taskNumber: taskNumberSchema
@@ -12427,22 +12749,17 @@ const updateTaskStatusRequestSchema = requestSchema()(object({
 	status: raftTaskStatusSchema.describe("todo → in_progress → in_review → done; closed from anywhere.")
 }));
 /** A held task write: the interrupt whose resume is the identical command; nothing to cancel. */
-function heldTaskWrite(target, data, action, kind, argv) {
-	const interrupt = heldTaskInterrupt(target, data, action, "After reviewing, repeat the operation if it is still correct.", argv);
+function heldTaskWrite(target, data, action, kind, argv, style) {
+	const interrupt = heldTaskInterrupt(target, data, action, "After reviewing, repeat the operation if it is still correct.", argv, style);
 	return {
 		ok: true,
 		state: "interrupted",
 		interrupt,
-		next: {
-			kind,
-			command: `raft message read --target "${target}"`,
-			args: { target },
-			why: "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume (interrupt.resume) if it is still right."
-		},
+		next: hintStep(kind, RAFT_HINTS.messageRead({ target }), "Unread messages in this channel may change the task; read them (frontier.recordHeld(interrupt) once the model saw them), then resume (interrupt.resume) if it is still right.", style, { target }),
 		text: interrupt.context
 	};
 }
-async function updateTaskStatus(client, request) {
+async function updateTaskStatus(client, request, options = {}) {
 	const invalid = requireTaskRef(request, updateTaskStatusRequestSchema);
 	if (invalid) return invalid;
 	const result = await client.tasks.updateStatus({
@@ -12451,7 +12768,7 @@ async function updateTaskStatus(client, request) {
 		status: request.status
 	});
 	if (!result.ok) return failureFromClientResult(result);
-	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The status change was not applied.", "retry_update_status", taskUpdateArgv(request.target, request.taskNumber, request.status));
+	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The status change was not applied.", "retry_update_status", taskUpdateArgv(request.target, request.taskNumber, request.status), options.hints ?? "cli");
 	return {
 		ok: true,
 		state: "updated",
@@ -12480,7 +12797,7 @@ function taskAmendArgv(request) {
 		...request.description === void 0 ? [] : request.description === null ? ["--clear-description"] : ["--description", request.description]
 	];
 }
-async function amendTask(client, request) {
+async function amendTask(client, request, options = {}) {
 	const invalid = requireTaskRef(request, amendTaskRequestSchema);
 	if (invalid) return invalid;
 	if (request.title === void 0 && request.description === void 0) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass a new title, a new description, or description: null to clear it." }));
@@ -12491,7 +12808,7 @@ async function amendTask(client, request) {
 		...request.description === void 0 ? {} : { description: request.description }
 	});
 	if (!result.ok) return failureFromClientResult(result);
-	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The amendment was not applied.", "retry_amend", taskAmendArgv(request));
+	if (isHeldResponse(result.data)) return heldTaskWrite(request.target, result.data, "The amendment was not applied.", "retry_amend", taskAmendArgv(request), options.hints ?? "cli");
 	return {
 		ok: true,
 		state: "amended",
@@ -12528,7 +12845,7 @@ async function taskHistory(client, request) {
 * and picks the task; a miss says whether the Server asserted the list is
 * complete, exactly as the CLI does.
 */
-async function showTask(client, request) {
+async function showTask(client, request, options = {}) {
 	const invalid = requireTaskRef(request);
 	if (invalid) return invalid;
 	const { target, taskNumber } = request;
@@ -12541,7 +12858,7 @@ async function showTask(client, request) {
 	const task = tasks.find((candidate) => candidate.taskNumber === taskNumber);
 	if (!task) return failureOutcome(opError("NOT_FOUND", {
 		message: result.data.pagination?.mode === "complete" && result.data.pagination.truncated === false ? `task #${taskNumber} not found in ${target} (searched ${tasks.length} task(s), status=all; server asserts this list is complete)` : tasks.length === 0 ? `task #${taskNumber} not found in ${target}: the server returned 0 tasks and did not assert the list is complete. That can mean the channel has no tasks, or that the server failed to read them (it currently reports some read errors as an empty list), and this command cannot tell which — so this is not evidence that task #${taskNumber} does not exist` : `task #${taskNumber} not found in ${target} (searched ${tasks.length} task(s), status=all; this surface does NOT assert completeness — so this is "absent from what was returned", not "does not exist")`,
-		nextAction: `Check the number with \`raft task list --target "${target}" --status all\`.`
+		nextAction: `Check the number with \`${formatHint(RAFT_HINTS.taskListAll(target), options.hints)}\`.`
 	}));
 	return {
 		ok: true,
@@ -12558,7 +12875,7 @@ const convertMessageToTaskRequestSchema = requestSchema()(object({
 	target: taskChannelSchema,
 	messageId: string().describe("Full or short id of a top-level message in that channel.")
 }));
-async function convertMessageToTask(client, request) {
+async function convertMessageToTask(client, request, options = {}) {
 	const invalid = validateOpRequest(convertMessageToTaskRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.target?.trim() || !request.messageId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A channel target and a message id are required." }));
@@ -12575,13 +12892,8 @@ async function convertMessageToTask(client, request) {
 			target: request.target,
 			task
 		},
-		next: {
-			kind: "post_in_task_thread",
-			command: `raft message send --target "${agentTaskThreadTarget(request.target, task.messageId)}"`,
-			args: { thread: agentTaskThreadTarget(request.target, task.messageId) },
-			why: "Follow up in the task's thread; it is unassigned until someone claims it."
-		},
-		text: formatAgentTaskConverted(request.target, task)
+		next: taskThreadStep(request.target, task.messageId, "Follow up in the task's thread; it is unassigned until someone claims it.", options.hints),
+		text: formatAgentTaskConverted(request.target, task, options.hints)
 	};
 }
 async function deleteTask(client, request) {
@@ -12811,7 +13123,7 @@ function formatCurrentAgent(data) {
 	return `${lines.join("\n")}\n\n`;
 }
 /** Server overview: runtime context, channels, agents, humans. */
-function formatAgentServerInfo(data) {
+function formatAgentServerInfo(data, style = "cli") {
 	let text = "## Server\n\n";
 	const channels = data.channels ?? [];
 	const agents = data.agents ?? [];
@@ -12819,8 +13131,14 @@ function formatAgentServerInfo(data) {
 	text += formatRuntimeContext(data.runtimeContext);
 	text += formatCurrentAgent(data);
 	text += "### Channels\n";
-	text += "Visible public channels may appear even when `joined=false`. Private channels are shown only when you are a member; do not disclose private-channel names, membership, or content outside that channel. Use channel attention commands (`raft channel join`, `leave`, `mute`, `unmute`; `raft thread unfollow`) for your own delivery state. Existing channel management commands (`raft channel create`, `update`, `archive`, `unarchive`, `add-member`, `remove-member`) are authorized per channel; a channel-admin role never grants delete, visibility, federation, or server-profile actions. There is no Agent command for changing channel roles. Run any subcommand with `--help` for syntax.\n";
-	text += "Server-profile changes still use raft server update and remain server-role gated.\n";
+	text += "Visible public channels may appear even when `joined=false`. Private channels are shown only when you are a member; do not disclose private-channel names, membership, or content outside that channel. ";
+	text += style === "cli" ? `Use channel attention commands (\`${formatHintName(RAFT_HINTS.channelJoinName())}\`, \`leave\`, \`mute\`, \`unmute\`; \`${formatHintName(RAFT_HINTS.threadUnfollowName())}\`) for your own delivery state. Existing channel management commands (\`${formatHintName(RAFT_HINTS.channelCreateName())}\`, \`update\`, \`archive\`, \`unarchive\`, \`add-member\`, \`remove-member\`) are authorized per channel; a channel-admin role never grants delete, visibility, federation, or server-profile actions. There is no Agent command for changing channel roles. Run any subcommand with \`--help\` for syntax.\n` : `Use the channel attention tools (${[
+		RAFT_HINTS.channelJoinName(),
+		RAFT_HINTS.channelLeaveName(),
+		RAFT_HINTS.channelMuteName(),
+		RAFT_HINTS.channelUnmuteName()
+	].map((hint) => `\`${formatHintName(hint, style)}\``).join(", ")}; \`${formatHintName(RAFT_HINTS.threadUnfollowName(), style)}\`) for your own delivery state. Channel management (create, update, archive, unarchive, add-member, remove-member) has no tool: ${RAFT_NO_TOOL_WORDING}; a channel-admin role never grants delete, visibility, federation, or server-profile actions. There is no tool for changing channel roles.\n`;
+	text += style === "cli" ? `Server-profile changes still use ${formatHintName(RAFT_HINTS.serverUpdateName())} and remain server-role gated.\n` : `Server-profile changes have no tool and remain server-role gated: ${RAFT_NO_TOOL_WORDING}.\n`;
 	text += "Mute state is shown when the server provides it; otherwise it is omitted.\n";
 	if (channels.length > 0) for (const t of channels) {
 		const statusParts = [channelVisibility(t), t.joined ? "joined" : "not joined"];
@@ -12843,7 +13161,8 @@ function formatAgentServerInfo(data) {
 	}
 	else text += "  (none)\n";
 	text += "\n### Humans\n";
-	text += "To start a new DM: raft message send --target \"dm:@name\" <<'RAFTMSG' followed by the message body and RAFTMSG. To reply in an existing DM: reuse the target from received messages.\n";
+	const newDm = formatHint(RAFT_HINTS.messageSend({ target: "dm:@name" }), style);
+	text += style === "cli" ? `To start a new DM: ${newDm} <<'RAFTMSG' followed by the message body and RAFTMSG. To reply in an existing DM: reuse the target from received messages.\n` : `To start a new DM: ${newDm}. To reply in an existing DM: reuse the target from received messages.\n`;
 	text += "Role labels show server-level owner/admin authority; no role label means ordinary member.\n";
 	if (humans.length > 0) for (const u of humans) {
 		const role = roleLabel(u.role);
@@ -12883,7 +13202,7 @@ function formatPageFooter(page) {
 	return `${lines.join("\n")}\n`;
 }
 /** Single channel detail block. */
-function formatAgentChannelInfo(channel, memberCounts) {
+function formatAgentChannelInfo(channel, memberCounts, style = "cli") {
 	const lines = ["## Channel", ""];
 	lines.push(`Channel: ${agentChannelRef(channel.name, channel.type)}`);
 	if (channel.id) lines.push(`ID: ${channel.id}`);
@@ -12903,11 +13222,11 @@ function formatAgentChannelInfo(channel, memberCounts) {
 		lines.push(`Members: ${agents + humans} (${agents} agents, ${humans} humans)`);
 	}
 	lines.push("");
-	lines.push(`More: raft channel members "${agentChannelRef(channel.name, channel.type)}"`);
+	lines.push(`More: ${formatHint(RAFT_HINTS.channelMembers(agentChannelRef(channel.name, channel.type)), style)}`);
 	return `${lines.join("\n")}\n`;
 }
 /** Compact server summary. */
-function formatAgentServerSummary(data) {
+function formatAgentServerSummary(data, style = "cli") {
 	const channels = data.channels ?? [];
 	const agents = data.agents ?? [];
 	const humans = data.humans ?? [];
@@ -12920,13 +13239,15 @@ function formatAgentServerSummary(data) {
 		`Humans: ${humans.length}`,
 		"",
 		"Narrow queries:",
-		"- raft server info --channels",
-		"- raft server info --agents",
-		"- raft server info --humans",
-		"- raft channel info <name>",
-		"- raft user info <name>",
+		...[
+			RAFT_HINTS.serverInfo({ view: "channels" }),
+			RAFT_HINTS.serverInfo({ view: "agents" }),
+			RAFT_HINTS.serverInfo({ view: "humans" }),
+			RAFT_HINTS.channelInfo(),
+			RAFT_HINTS.userInfo()
+		].map((hint) => `- ${formatHint(hint, style)}`),
 		"",
-		"Full dump: raft server info --full"
+		`Full dump: ${formatHint(RAFT_HINTS.serverInfo({ view: "full" }), style)}`
 	].join("\n")}\n`;
 }
 /** Channel listing page. */
@@ -13207,7 +13528,7 @@ const unfollowThreadRequestSchema = requestSchema()(object({
 	reason: string().optional().describe("Short reason, kept with the unfollow.")
 }));
 const INVALID_CHANNEL_TARGET = "Target must be a regular channel in the form '#channel-name'. DMs and thread targets are not supported.";
-async function resolveRegularChannel(client, target) {
+async function resolveRegularChannel(client, target, options) {
 	const name = parseRaftRegularChannelTarget$1(target ?? "");
 	if (!name) return failureOutcome(opError("INVALID_REQUEST", { message: INVALID_CHANNEL_TARGET }));
 	const info = await client.server.info();
@@ -13215,7 +13536,7 @@ async function resolveRegularChannel(client, target) {
 	const channel = info.data.channels.find((candidate) => candidate.name === name);
 	if (!channel) return failureOutcome(opError("NOT_FOUND", {
 		message: `Channel not found: ${target}`,
-		nextAction: "List visible channels with `raft server info --channels`; private channels need a human to add you."
+		nextAction: `List visible channels with \`${formatHint(RAFT_HINTS.serverInfo({ view: "channels" }), options.hints)}\`; private channels need a human to add you.`
 	}));
 	return {
 		id: channel.id,
@@ -13223,7 +13544,7 @@ async function resolveRegularChannel(client, target) {
 		joined: channel.joined
 	};
 }
-async function joinChannel(client, request) {
+async function joinChannel(client, request, options = {}) {
 	const invalid = validateOpRequest(channelTargetRequestSchema, request);
 	if (invalid) return invalid;
 	const result = await joinRaftChannelByTarget$1(client, { target: request.target });
@@ -13249,19 +13570,14 @@ async function joinChannel(client, request) {
 			target: result.data.target,
 			channelId: result.data.channelId
 		},
-		next: {
-			kind: "read_target",
-			command: `raft message read --target "${result.data.target}"`,
-			args: { target: result.data.target },
-			why: "Read the channel before posting."
-		},
+		next: hintStep("read_target", RAFT_HINTS.messageRead({ target: result.data.target }), "Read the channel before posting.", options.hints, { target: result.data.target }),
 		text: state === "joined" ? `Joined ${result.data.target}.` : `Already a member of ${result.data.target}.`
 	};
 }
-async function leaveChannel(client, request) {
+async function leaveChannel(client, request, options = {}) {
 	const invalid = validateOpRequest(channelTargetRequestSchema, request);
 	if (invalid) return invalid;
-	const channel = await resolveRegularChannel(client, request.target);
+	const channel = await resolveRegularChannel(client, request.target, options);
 	if ("ok" in channel) return channel;
 	if (!channel.joined) return {
 		ok: true,
@@ -13292,10 +13608,10 @@ async function leaveChannel(client, request) {
 function formatSeq(value) {
 	return value == null ? "none" : String(value);
 }
-async function setChannelMute(client, request, action) {
+async function setChannelMute(client, request, action, options) {
 	const invalid = validateOpRequest(channelTargetRequestSchema, request);
 	if (invalid) return invalid;
-	const channel = await resolveRegularChannel(client, request.target);
+	const channel = await resolveRegularChannel(client, request.target, options);
 	if ("ok" in channel) return channel;
 	const result = action === "mute" ? await client.channels.mute({ channelId: channel.id }, {}) : await client.channels.unmute({ channelId: channel.id });
 	if (!result.ok) return failureFromClientResult(result);
@@ -13330,11 +13646,11 @@ async function setChannelMute(client, request, action) {
 		text: lines.join("\n")
 	};
 }
-function muteChannel(client, request) {
-	return setChannelMute(client, request, "mute");
+function muteChannel(client, request, options = {}) {
+	return setChannelMute(client, request, "mute", options);
 }
-function unmuteChannel(client, request) {
-	return setChannelMute(client, request, "unmute");
+function unmuteChannel(client, request, options = {}) {
+	return setChannelMute(client, request, "unmute", options);
 }
 async function channelMembers(client, request) {
 	const invalid = validateOpRequest(channelMembersRequestSchema, request);
@@ -13384,7 +13700,7 @@ const channelInfoRequestSchema = requestSchema()(object({ target: string().descr
 * `raft channel info <target>`: the channel's facts from `server.info`, plus
 * member counts from its roster when the Server shows it.
 */
-async function channelInfo(client, request) {
+async function channelInfo(client, request, options = {}) {
 	const invalid = validateOpRequest(channelInfoRequestSchema, request);
 	if (invalid) return invalid;
 	const trimmed = request.target.trim();
@@ -13396,7 +13712,10 @@ async function channelInfo(client, request) {
 	const channel = info.data.channels.find((candidate) => candidate.name === name);
 	if (!channel) return failureOutcome(opError("NOT_FOUND", {
 		message: `Channel not found or not visible: ${input}`,
-		nextAction: "Run `raft server info --channels --query <name>` to inspect visible channels, or ask a channel member to add you if this is private."
+		nextAction: `Run \`${formatHint(RAFT_HINTS.serverInfo({
+			view: "channels",
+			query: true
+		}), options.hints)}\` to inspect visible channels, or ask a channel member to add you if this is private.`
 	}));
 	const members = await client.channels.members({ channel: `#${name}` });
 	const memberCounts = members.ok ? {
@@ -13411,7 +13730,7 @@ async function channelInfo(client, request) {
 			memberCounts
 		},
 		next: null,
-		text: formatAgentChannelInfo(channel, memberCounts)
+		text: formatAgentChannelInfo(channel, memberCounts, options.hints)
 	};
 }
 //#endregion
@@ -13426,45 +13745,54 @@ const serverInfoRequestSchema = requestSchema()(object({
 	]).optional().describe("summary (default): counts; full: the whole overview; channels / agents / humans: one paged section."),
 	offset: number$1().optional().describe("Section paging: rows to skip."),
 	limit: number$1().optional().describe("Section paging: rows per page (default 50)."),
-	joined: boolean().optional().describe("channels view only: only channels you have joined.")
+	joined: boolean().optional().describe("channels view only: only channels you have joined."),
+	query: string().optional().describe("channels / agents / humans view only: keep rows whose name, description, or other visible text contains this (case-insensitive).")
 }));
 const showProfileRequestSchema = requestSchema()(object({ target: string().optional().describe("`@handle` of someone else; omit for your own profile.") }));
 /** The Agent API's profile body schema; at least one field is required (checked by the operation). */
 const updateProfileRequestSchema = agentApiProfileUpdateBodySchema;
-function nextCommand(section, request, offset, limit, total) {
+/** The next page of a section, or null on the last page (`--query` / `--joined` carried, in the CLI's order). */
+function nextPageArgs(section, request, offset, limit, total) {
 	const nextOffset = offset + limit;
-	if (nextOffset >= total) return void 0;
-	const parts = [
-		"raft server info",
-		`--${section}`,
-		`--offset ${nextOffset}`,
-		`--limit ${limit}`
-	];
-	if (section === "channels" && request.joined) parts.push("--joined");
-	return parts.join(" ");
+	if (nextOffset >= total) return null;
+	const query = request.query?.trim() || void 0;
+	const joined = section === "channels" && request.joined === true ? true : void 0;
+	return {
+		view: section,
+		offset: nextOffset,
+		limit,
+		...query === void 0 ? {} : { query },
+		...joined ? { joined } : {}
+	};
 }
-async function serverInfo(client, request = {}) {
+/** The CLI's `--query` match: any string field contains the needle, case-insensitively. */
+function includesQuery(row, query) {
+	const needle = query?.trim().toLowerCase();
+	if (!needle) return true;
+	return Object.values(row).some((value) => typeof value === "string" && value.toLowerCase().includes(needle));
+}
+async function serverInfo(client, request = {}, options = {}) {
 	const invalid = validateOpRequest(serverInfoRequestSchema, request);
 	if (invalid) return invalid;
+	const style = options.hints ?? "cli";
 	const result = await client.server.info();
 	if (!result.ok) return failureFromClientResult(result);
 	const server = result.data;
 	const view = request.view ?? "summary";
-	if (view === "summary") return {
-		ok: true,
-		state: "info",
-		data: {
-			view,
-			server,
-			page: null
-		},
-		next: {
-			kind: "list_channels",
-			command: "raft server info --channels",
-			why: "The summary only counts; list a section to see names."
-		},
-		text: formatAgentServerSummary(server)
-	};
+	if (view === "summary") {
+		const next = hintStep("list_channels", RAFT_HINTS.serverInfo({ view: "channels" }), "The summary only counts; list a section to see names.", style);
+		return {
+			ok: true,
+			state: "info",
+			data: {
+				view,
+				server,
+				page: null
+			},
+			next,
+			text: formatAgentServerSummary(server, style)
+		};
+	}
 	if (view === "full") return {
 		ok: true,
 		state: "info",
@@ -13474,30 +13802,23 @@ async function serverInfo(client, request = {}) {
 			page: null
 		},
 		next: null,
-		text: formatAgentServerInfo(server)
+		text: formatAgentServerInfo(server, style)
 	};
 	const limit = Math.max(1, Math.trunc(request.limit ?? 50));
 	const offset = Math.max(0, Math.trunc(request.offset ?? 0));
-	const rows = view === "channels" ? server.channels.filter((c) => !request.joined || c.joined) : view === "agents" ? server.agents : server.humans;
+	const rows = (view === "channels" ? server.channels.filter((c) => !request.joined || c.joined) : view === "agents" ? server.agents : server.humans).filter((row) => includesQuery(row, request.query));
 	const pageRows = rows.slice(offset, offset + limit);
+	const nextArgs = nextPageArgs(view, request, offset, limit, rows.length);
+	const nextHint = nextArgs ? RAFT_HINTS.serverInfo(nextArgs) : null;
 	const page = {
 		section: view,
 		total: rows.length,
 		offset,
 		limit,
-		nextCommand: nextCommand(view, request, offset, limit, rows.length)
+		nextCommand: nextHint ? formatHint(nextHint, style) : void 0
 	};
 	const text = view === "channels" ? formatAgentServerChannels(pageRows, page) : view === "agents" ? formatAgentServerAgents(pageRows, page) : formatAgentServerHumans(pageRows, page);
-	const next = page.nextCommand ? {
-		kind: "next_page",
-		command: page.nextCommand,
-		args: {
-			view,
-			offset: offset + limit,
-			limit
-		},
-		why: "More rows exist; one page is one page."
-	} : null;
+	const next = nextArgs && nextHint ? hintStep("next_page", nextHint, "More rows exist; one page is one page.", style, nextArgs) : null;
 	return {
 		ok: true,
 		state: "info",
@@ -13547,7 +13868,7 @@ const userInfoRequestSchema = requestSchema()(object({
 * their memberships among one page of the visible channels, checked one
 * channel roster at a time (a rejected roster is skipped and counted).
 */
-async function userInfo(client, request) {
+async function userInfo(client, request, options = {}) {
 	const invalid = validateOpRequest(userInfoRequestSchema, request);
 	if (invalid) return invalid;
 	const trimmed = request.name.trim();
@@ -13568,7 +13889,13 @@ async function userInfo(client, request) {
 	} : null;
 	if (!user) return failureOutcome(opError("NOT_FOUND", {
 		message: `User not found or not visible: @${name}`,
-		nextAction: "Run `raft server info --agents --query <name>` or `raft server info --humans --query <name>` to inspect visible users."
+		nextAction: `Run \`${formatHint(RAFT_HINTS.serverInfo({
+			view: "agents",
+			query: true
+		}), options.hints)}\` or \`${formatHint(RAFT_HINTS.serverInfo({
+			view: "humans",
+			query: true
+		}), options.hints)}\` to inspect visible users.`
 	}));
 	const visibleChannels = info.data.channels;
 	const memberships = [];
@@ -13587,22 +13914,22 @@ async function userInfo(client, request) {
 		});
 	}
 	const nextOffset = offset + limit;
+	const nextHint = nextOffset < visibleChannels.length ? RAFT_HINTS.userInfo({
+		name,
+		offset: nextOffset,
+		limit
+	}) : null;
 	const page = {
 		total: visibleChannels.length,
 		offset,
 		limit,
-		nextCommand: nextOffset < visibleChannels.length ? `raft user info @${name} --offset ${nextOffset} --limit ${limit}` : void 0
+		nextCommand: nextHint ? formatHint(nextHint, options.hints) : void 0
 	};
-	const next = page.nextCommand ? {
-		kind: "next_page",
-		command: page.nextCommand,
-		args: {
-			name: `@${name}`,
-			offset: nextOffset,
-			limit
-		},
-		why: "Only one page of visible channels was inspected for memberships."
-	} : null;
+	const next = nextHint ? hintStep("next_page", nextHint, "Only one page of visible channels was inspected for memberships.", options.hints, {
+		name: `@${name}`,
+		offset: nextOffset,
+		limit
+	}) : null;
 	return {
 		ok: true,
 		state: "info",
@@ -13619,8 +13946,9 @@ async function userInfo(client, request) {
 //#endregion
 //#region ../shared/src/agentText/attachments.ts
 /** Upload receipt with attachment id and send-usage hint. */
-function formatAgentAttachmentUploaded(attachment) {
-	return `File uploaded: ${attachment.filename} (${(attachment.sizeBytes / 1024).toFixed(1)}KB)\nAttachment ID: ${attachment.id}\n\nUse this ID with raft message send --attachment-id ${attachment.id} to include it in a message.\n`;
+function formatAgentAttachmentUploaded(attachment, style = "cli") {
+	const send = formatHint(RAFT_HINTS.messageSend({ attachmentId: attachment.id }), style);
+	return `File uploaded: ${attachment.filename} (${(attachment.sizeBytes / 1024).toFixed(1)}KB)\nAttachment ID: ${attachment.id}\n\nUse this ID with ${send} to include it in a message.\n`;
 }
 function anchorSummary(anchor) {
 	if (anchor.type === "md-section") {
@@ -13662,6 +13990,7 @@ const attachmentCommentsRequestSchema = requestSchema()(object({
 	attachmentId: string().describe("The attachment id."),
 	limit: number$1().int().positive().optional().describe("Maximum comments to return.")
 }));
+const downloadAttachmentUrlRequestSchema = requestSchema()(object({ attachmentId: string().describe("The attachment id, as message lines show it (`id:…`).") }));
 /** Compatibility fallback for Servers that predate the capability endpoint (the CLI's constant). */
 const AGENT_ATTACHMENT_UPLOAD_FALLBACK_MAX_BYTES = 52428800;
 const FILENAME_MIME_MAP = {
@@ -13714,7 +14043,7 @@ function inferAttachmentMimeType(filename, bytes, explicit) {
 * `POST /upload` below the Server's direct-upload threshold, an upload session
 * (create → PUT to a presigned URL → complete) at or above it.
 */
-async function uploadAttachment(client, transport, request) {
+async function uploadAttachment(client, transport, request, options = {}) {
 	if (!request.target?.trim() || !request.filename?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and a filename are required to upload." }));
 	if (!(request.bytes instanceof Uint8Array) || request.bytes.byteLength === 0) return failureOutcome(opError("INVALID_REQUEST", { message: "Refusing to upload a 0-byte attachment." }));
 	if (request.mimeType !== void 0 && !MIME_TYPE_RE.test(request.mimeType.trim())) return failureOutcome(opError("INVALID_REQUEST", { message: `mimeType must look like type/subtype, got: ${request.mimeType}` }));
@@ -13726,7 +14055,7 @@ async function uploadAttachment(client, transport, request) {
 	if (!resolved.ok) return failureFromClientResult(resolved);
 	const channelId = resolved.data.channelId;
 	const mimeType = inferAttachmentMimeType(request.filename, request.bytes, request.mimeType);
-	if (threshold !== null && request.bytes.byteLength >= threshold) return uploadThroughSession(client, transport, request, channelId, mimeType);
+	if (threshold !== null && request.bytes.byteLength >= threshold) return uploadThroughSession(client, transport, request, channelId, mimeType, options);
 	const copy = new Uint8Array(request.bytes.byteLength);
 	copy.set(request.bytes);
 	const form = new FormData();
@@ -13766,9 +14095,9 @@ async function uploadAttachment(client, transport, request) {
 	}
 	const parsed = agentApiContract.attachmentUpload.response.body.safeParse(body);
 	if (!parsed.success) return failureOutcome(opError("INVALID_RESPONSE"));
-	return uploadedOutcome(request.target, parsed.data, mimeType);
+	return uploadedOutcome(request.target, parsed.data, mimeType, options);
 }
-function uploadedOutcome(target, data, mimeType) {
+function uploadedOutcome(target, data, mimeType, options) {
 	return {
 		ok: true,
 		state: "uploaded",
@@ -13777,16 +14106,14 @@ function uploadedOutcome(target, data, mimeType) {
 			target,
 			mimeType: data.mimeType ?? mimeType
 		},
-		next: {
-			kind: "send_with_attachment",
-			command: `raft message send --target "${target}" --attachment-id ${data.id}`,
-			args: {
-				target,
-				attachmentIds: [data.id]
-			},
-			why: "The upload alone posts nothing; send a message that links the attachment id."
-		},
-		text: formatAgentAttachmentUploaded(data)
+		next: hintStep("send_with_attachment", RAFT_HINTS.messageSend({
+			target,
+			attachmentId: data.id
+		}), "The upload alone posts nothing; send a message that links the attachment id.", options.hints, {
+			target,
+			attachmentIds: [data.id]
+		}),
+		text: formatAgentAttachmentUploaded(data, options.hints)
 	};
 }
 const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -13797,7 +14124,7 @@ const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 * verifies against the object store. A PUT that definitely failed cancels the
 * session; a PUT whose outcome is unknown leaves it for completion to verify.
 */
-async function uploadThroughSession(client, transport, request, channelId, mimeType) {
+async function uploadThroughSession(client, transport, request, channelId, mimeType, options) {
 	const created = await client.attachments.createUploadSession({
 		channelId,
 		filename: request.filename,
@@ -13844,7 +14171,7 @@ async function uploadThroughSession(client, transport, request, channelId, mimeT
 		const completed = await client.attachments.completeUploadSession({ uploadId });
 		if (completed.ok) {
 			const attachment = completed.data.attachment;
-			return uploadedOutcome(request.target, attachment, mimeType);
+			return uploadedOutcome(request.target, attachment, mimeType, options);
 		}
 		const code = completed.error.kind === "http" ? completed.error.errorCode : null;
 		if (!(code === "UPLOAD_OBJECT_NOT_FOUND" || code === "UPLOAD_VERIFICATION_IN_PROGRESS") || attempt === 2) return failureFromClientResult(completed);
@@ -13868,6 +14195,46 @@ async function downloadAttachment(client, request) {
 		text: `Downloaded attachment ${request.attachmentId.slice(0, 8)} (${bytes.byteLength} bytes).`
 	};
 }
+/**
+* Mint a short-lived URL for an attachment's bytes, for runtimes whose tools
+* cannot return binary data: the runtime (not the model) fetches `url` before
+* `expiresAt`. The URL is a bearer capability; do not log it. A Server whose
+* storage cannot presign answers 409 `download_url_unavailable`; that failure's
+* `next` points at the binary download (`attachments.download`).
+*/
+async function downloadAttachmentUrl(client, request, options = {}) {
+	const invalid = validateOpRequest(downloadAttachmentUrlRequestSchema, request);
+	if (invalid) return invalid;
+	const attachmentId = request.attachmentId?.trim();
+	if (!attachmentId) return failureOutcome(opError("INVALID_REQUEST", { message: "An attachment id is required." }));
+	const result = await client.attachments.downloadUrl({ attachmentId });
+	if (!result.ok) {
+		const failure = failureFromClientResult(result);
+		if (failure.error.serverCode !== "download_url_unavailable") return failure;
+		const download = RAFT_HINTS.attachmentDownload(attachmentId);
+		const nextAction = `This Server's storage cannot mint download URLs; download the bytes instead: \`${formatHint(download, options.hints)}\`.`;
+		return {
+			...failureOutcome({
+				...failure.error,
+				nextAction
+			}),
+			next: hintStep("download_bytes", download, nextAction, options.hints, { attachmentId })
+		};
+	}
+	const { url, expiresAt, filename, mimeType } = result.data;
+	return {
+		ok: true,
+		state: "url",
+		data: {
+			url,
+			expiresAt,
+			filename,
+			mimeType
+		},
+		next: null,
+		text: `Download URL for ${filename} (${mimeType}), valid until ${expiresAt}:\n${url}`
+	};
+}
 async function attachmentComments(client, request) {
 	const invalid = validateOpRequest(attachmentCommentsRequestSchema, request);
 	if (invalid) return invalid;
@@ -14016,14 +14383,15 @@ function renderSearchPreview(content, query) {
 	].join("");
 }
 /** Search results with <match>/<omit /> preview markup. */
-function formatAgentSearchResults(query, data, offset, sort, limit) {
+function formatAgentSearchResults(query, data, offset, sort, limit, style = "cli") {
 	const trimmedQuery = query.trim();
+	const flag = (name) => formatHintFlag(name, name, style);
 	const oldestShown = data.results?.length ? data.results[data.results.length - 1]?.createdAt : void 0;
-	const nextPageHint = sort === "recent" && oldestShown ? `page with --before ${oldestShown} (pages OLDER only; NOT a complete traversal: stored times are microsecond but this key is millisecond, so rows inside the boundary millisecond can be skipped, and a full page sharing one timestamp can repeat indefinitely; copy the key verbatim)` : `page with --offset ${(offset ?? 0) + (data.results?.length ?? 0)}`;
+	const nextPageHint = sort === "recent" && oldestShown ? `page with ${flag("before")} ${oldestShown} (pages OLDER only; NOT a complete traversal: stored times are microsecond but this key is millisecond, so rows inside the boundary millisecond can be skipped, and a full page sharing one timestamp can repeat indefinitely; copy the key verbatim)` : `page with ${flag("offset")} ${(offset ?? 0) + (data.results?.length ?? 0)}`;
 	const effectiveLimit = Math.min(limit ?? 20, 50);
 	const countEqualsLimit = (data.results?.length ?? 0) === effectiveLimit;
-	const limitSource = limit === void 0 ? `the server default of ${effectiveLimit}` : limit > 50 ? `the server cap of ${effectiveLimit} (your --limit ${limit} was clamped)` : `the --limit ${effectiveLimit} that was requested`;
-	const atCapRemedy = effectiveLimit < 50 ? "re-run with a higher --limit to tell the two apart" : `this is already the server's maximum page, so completeness CANNOT be determined from this result: a higher --limit is clamped back to ${effectiveLimit} and paging will not reveal it; narrow the query (add --sender, --target, --after or --before) until fewer than ${effectiveLimit} results match`;
+	const limitSource = limit === void 0 ? `the server default of ${effectiveLimit}` : limit > 50 ? `the server cap of ${effectiveLimit} (your ${flag("limit")} ${limit} was clamped)` : `the ${flag("limit")} ${effectiveLimit} that was requested`;
+	const atCapRemedy = effectiveLimit < 50 ? `re-run with a higher ${flag("limit")} to tell the two apart` : `this is already the server's maximum page, so completeness CANNOT be determined from this result: a higher ${flag("limit")} is clamped back to ${effectiveLimit} and paging will not reveal it; narrow the query (add ${flag("sender")}, ${flag("target")}, ${flag("after")} or ${flag("before")}) until fewer than ${effectiveLimit} results match`;
 	const truncation = data.hasMore === true ? `truncated=true · more results exist, ${nextPageHint}` : data.hasMore === false ? countEqualsLimit ? `truncated=unknown · server reported hasMore=false, but this page returned exactly ${limitSource}, which is also what a capped page returns; ${atCapRemedy}` : "truncated=false" : "truncated=unknown · server did not report hasMore";
 	if (!data.results || data.results.length === 0) return `No search results. (${truncation})`;
 	const formatted = data.results.map((result) => {
@@ -14072,7 +14440,7 @@ const reactRequestSchema = requestSchema()(object({
 	messageId: string().describe("Full or short message id."),
 	emoji: string().describe("One reaction emoji.")
 }));
-async function searchMessages(client, request) {
+async function searchMessages(client, request, options = {}) {
 	const invalid = validateOpRequest(searchMessagesRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.query?.trim() && !request.target && !request.sender) return failureOutcome(opError("INVALID_REQUEST", { message: "Pass a query, or filter by target or sender." }));
@@ -14094,11 +14462,16 @@ async function searchMessages(client, request) {
 		results: data.results,
 		hasMore
 	};
+	const nextArgs = {
+		...request,
+		offset: (request.offset ?? 0) + data.results.length
+	};
 	const next = hasMore ? {
 		kind: "next_search_page",
-		args: {
-			...request,
-			offset: (request.offset ?? 0) + data.results.length
+		args: nextArgs,
+		operation: {
+			name: "messages.search",
+			args: nextArgs
 		},
 		why: "More results exist; page on, or narrow the query."
 	} : null;
@@ -14110,31 +14483,32 @@ async function searchMessages(client, request) {
 		text: formatAgentSearchResults(page.query, {
 			results: data.results,
 			...hasMore === null ? {} : { hasMore }
-		}, request.offset, request.sort, request.limit)
+		}, request.offset, request.sort, request.limit, options.hints)
 	};
 }
-async function resolveMessage(client, request) {
+async function resolveMessage(client, request, options = {}) {
 	const invalid = validateOpRequest(resolveMessageRequestSchema, request);
 	if (invalid) return invalid;
 	if (!request.messageId?.trim()) return failureOutcome(opError("INVALID_REQUEST", { message: "A message id is required." }));
 	const result = await client.messages.resolve({ msgId: request.messageId });
 	if (!result.ok) return failureFromClientResult(result);
-	const message = projectRaftMessage(result.data.message);
+	const message = projectRaftMessage(result.data.message, options.hints);
 	if (!message) return failureOutcome(opError("INVALID_RESPONSE", { message: "The resolved message carries no conversation identity." }));
 	return {
 		ok: true,
 		state: "message",
 		data: message,
-		next: {
-			kind: "read_target",
-			command: `raft message read --target "${message.target}" --around ${message.shortId ?? request.messageId}`,
-			args: {
-				target: message.target,
-				around: message.id ?? request.messageId
-			},
-			why: "Read the surrounding context before acting on one message."
-		},
-		text: formatAgentMessages([toAgentMessageLike(message.raw)])
+		next: hintStep("read_target", RAFT_HINTS.messageRead({
+			target: message.target,
+			around: {
+				shown: message.shortId ?? request.messageId,
+				id: message.id ?? request.messageId
+			}
+		}), "Read the surrounding context before acting on one message.", options.hints, {
+			target: message.target,
+			around: message.id ?? request.messageId
+		}),
+		text: formatAgentMessages([toAgentMessageLike(message.raw)], options.hints)
 	};
 }
 async function reactToMessage(client, request, action = "add") {
@@ -14164,17 +14538,20 @@ function normalizeAgentMentionAction(action) {
 	if (action === "add" || action === "invite") return "add";
 	return null;
 }
-function formatActionCommands(action) {
+function actionVerbs(action) {
 	const verbs = action.availableActions.map(normalizeAgentMentionAction).filter((verb) => verb !== null);
-	return Array.from(new Set(verbs)).map((verb) => `  ${verb}: raft mention ${verb} ${action.resolutionId}`);
+	return Array.from(new Set(verbs));
+}
+function formatActionCommands(action, style) {
+	return actionVerbs(action).map((verb) => `  ${verb}: ${formatHint(RAFT_HINTS.mentionAction(verb, action.resolutionId), style)}`);
 }
 function formatAuthoredMentionToken(targetHandle) {
 	return targetHandle.startsWith("@") ? targetHandle : `@${targetHandle}`;
 }
 const PENDING_MENTION_ACTION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Per-token mention recovery command line; null when the id is not a UUID (fail closed). */
-function formatAgentMentionNotifyRecoveryCommand(resolutionId) {
-	return PENDING_MENTION_ACTION_ID_RE.test(resolutionId) ? `raft mention notify ${resolutionId}` : null;
+function formatAgentMentionNotifyRecoveryCommand(resolutionId, style = "cli") {
+	return PENDING_MENTION_ACTION_ID_RE.test(resolutionId) ? formatHint(RAFT_HINTS.mentionAction("notify", resolutionId), style) : null;
 }
 function toAgentSenderPendingMentionAction(action) {
 	return {
@@ -14231,22 +14608,24 @@ function normalizeAgentMentionActionResults(data) {
 	})).filter((item) => item.resolutionId.length > 0);
 }
 const PENDING_DEFAULT_LIMIT = 50;
-function pendingPageVerdict(hasMore, limit, shown) {
-	const asked = limit === void 0 ? "server default 50" : `--limit ${limit}`;
-	if (hasMore === true) return (limit ?? PENDING_DEFAULT_LIMIT) >= 100 ? `shown ${shown}, ${asked} — truncated=true · more pending actions exist AND this is the server's maximum page (100); this route has no offset or cursor, so the rest cannot be reached from here — resolve what you can and re-run; rows with no available actions are not actionable here and will remain until they expire` : `shown ${shown}, ${asked} — truncated=true · more pending actions exist; raise --limit (server caps at 100) or resolve these first and re-run`;
+function pendingPageVerdict(hasMore, limit, shown, style) {
+	const limitFlag = formatHintFlag("limit", "limit", style);
+	const asked = limit === void 0 ? "server default 50" : `${limitFlag} ${limit}`;
+	if (hasMore === true) return (limit ?? PENDING_DEFAULT_LIMIT) >= 100 ? `shown ${shown}, ${asked} — truncated=true · more pending actions exist AND this is the server's maximum page (100); this route has no offset or cursor, so the rest cannot be reached from here — resolve what you can and re-run; rows with no available actions are not actionable here and will remain until they expire` : `shown ${shown}, ${asked} — truncated=true · more pending actions exist; raise ${limitFlag} (server caps at 100) or resolve these first and re-run`;
 	if (hasMore === false) return `shown ${shown}, ${asked} — truncated=false · this is the complete list`;
 	return `shown ${shown}, ${asked} — truncated=unknown · server did not report has_more, so completeness is NOT asserted`;
 }
 /** Undelivered-mentions partial result (send) or the pending list. */
 function formatAgentPendingMentionActions(actions, opts = {}) {
+	const style = opts.hints ?? "cli";
 	const unresolvedMentionHandles = opts.source === "send" ? Array.from(new Set(opts.unresolvedMentionHandles ?? [])) : [];
-	const pageNote = opts.source === "pending" ? pendingPageVerdict(opts.hasMore, opts.limit, actions.length) : "";
+	const pageNote = opts.source === "pending" ? pendingPageVerdict(opts.hasMore, opts.limit, actions.length, style) : "";
 	if (actions.length === 0 && unresolvedMentionHandles.length === 0) return opts.source === "pending" ? `Pending mention actions\n\nNo pending mention actions. (${pageNote})\n` : "";
 	if (opts.source === "send") {
 		const lines = [
 			"Undelivered mentions — partial result",
 			"Message effect: status=queued. Queue acceptance is the only message proof.",
-			"Do not rerun `raft message send`; the message is already queued and a retry could duplicate it.",
+			`Do not rerun \`${formatHintName(RAFT_HINTS.messageSendName(), style)}\`; the message is already queued and a retry could duplicate it.`,
 			"Each row below is bound to the literal @token from your message.",
 			"For a literal name rather than a recipient, wrap the @handle in inline or fenced code.",
 			""
@@ -14260,10 +14639,10 @@ function formatAgentPendingMentionActions(actions, opts = {}) {
 			if (action.messageId) lines.push(`  message: ${action.messageId}`);
 			lines.push(`  expires: ${action.expiresAt ?? "unknown"}`);
 			if (action.recoveryCommand) {
-				lines.push(`  recovery: ${action.recoveryCommand}`);
+				lines.push(`  recovery: ${style === "cli" ? action.recoveryCommand : formatAgentMentionNotifyRecoveryCommand(action.resolutionId, style)}`);
 				lines.push("  note: the handle resolved, but the target was not in this conversation at send time. This does not prove the person left the server.");
 				lines.push("  note: notify exits nonzero unless the target queue accepts the delivery.");
-			} else lines.push("  recovery: unavailable because the pending action id is invalid; inspect `raft mention pending` without resending the message.");
+			} else lines.push(`  recovery: unavailable because the pending action id is invalid; inspect \`${formatHint(RAFT_HINTS.mentionPending(), style)}\` without resending the message.`);
 		}
 		for (const rawHandle of unresolvedMentionHandles) {
 			const warning = toAgentSenderUnresolvedMentionWarning(rawHandle);
@@ -14287,11 +14666,11 @@ function formatAgentPendingMentionActions(actions, opts = {}) {
 		if (action.messageId) lines.push(`  message: ${action.messageId}`);
 		lines.push(`  reason: ${formatPendingReason(action.reason)}`);
 		if (action.expiresAt) lines.push(`  expires: ${action.expiresAt}`);
-		const commands = formatActionCommands(action);
+		const commands = formatActionCommands(action, style);
 		if (commands.length > 0) {
 			lines.push("  recovery commands:");
 			lines.push(...commands);
-			if (commands.some((command) => command.includes(" mention notify "))) lines.push("  note: notify exits nonzero unless the target queue accepts the delivery.");
+			if (actionVerbs(action).includes("notify")) lines.push("  note: notify exits nonzero unless the target queue accepts the delivery.");
 		}
 	}
 	return `${lines.join("\n")}\n`;
@@ -14342,12 +14721,14 @@ function formatAgentSenderMentionDeliveries(messageId, deliveries) {
 //#endregion
 //#region ../shared/src/agentOps/mentions.ts
 const pendingMentionActionsRequestSchema = requestSchema()(object({ limit: number$1().int().positive().optional().describe("Maximum pending mentions to list.") }));
+const mentionResolutionIdsRequestSchema = requestSchema()(object({ resolutionIds: array(string()).describe("resolutionId values from mentions.pending.") }));
+/** @deprecated The request of the deprecated `mentions.execute`; use `mentionResolutionIdsRequestSchema` (`mentions.notify` / `mentions.add`). */
 const executeMentionActionRequestSchema = requestSchema()(object({
 	action: _enum(["notify", "add"]).describe("notify: tell the mentioned target about the message; add: add them to the conversation."),
 	resolutionIds: array(string()).describe("resolutionId values from mentions.pending.")
 }));
 const senderMentionDeliveriesRequestSchema = requestSchema()(object({ messageId: string().describe("Id of a message you sent.") }));
-async function pendingMentionActions(client, request = {}) {
+async function pendingMentionActions(client, request = {}, options = {}) {
 	const invalid = validateOpRequest(pendingMentionActionsRequestSchema, request);
 	if (invalid) return invalid;
 	const result = await client.mentions.pendingActions(request.limit === void 0 ? {} : { limit: String(request.limit) });
@@ -14355,15 +14736,10 @@ async function pendingMentionActions(client, request = {}) {
 	const actions = normalizeAgentPendingMentionActions(result.data);
 	const hasMore = typeof result.data.has_more === "boolean" ? result.data.has_more : null;
 	const first = actions.find((a) => a.availableActions.length > 0);
-	const next = first ? {
-		kind: "resolve_mention",
-		command: `raft mention notify ${first.resolutionId}`,
-		args: {
-			action: "notify",
-			resolutionIds: [first.resolutionId]
-		},
-		why: "This @mention reached nobody at send time; notify the target (or add them) so the message is seen."
-	} : null;
+	const next = first ? hintStep("resolve_mention", RAFT_HINTS.mentionAction("notify", first.resolutionId), "This @mention reached nobody at send time; notify the target (or add them) so the message is seen.", options.hints, {
+		action: "notify",
+		resolutionIds: [first.resolutionId]
+	}) : null;
 	return {
 		ok: true,
 		state: actions.length > 0 ? "pending" : "empty",
@@ -14376,17 +14752,36 @@ async function pendingMentionActions(client, request = {}) {
 		text: formatAgentPendingMentionActions(actions, {
 			source: "pending",
 			...hasMore === null ? {} : { hasMore },
-			limit: request.limit
+			limit: request.limit,
+			hints: options.hints
 		})
 	};
 }
+/** Tell the targets of unreached @mentions about the message (`raft mention notify`). */
+async function notifyMentions(client, request) {
+	const invalid = validateOpRequest(mentionResolutionIdsRequestSchema, request);
+	if (invalid) return invalid;
+	return runMentionAction(client, "notify", request.resolutionIds);
+}
+/** Add the targets of unreached @mentions to the conversation (`raft mention add`). */
+async function addMentions(client, request) {
+	const invalid = validateOpRequest(mentionResolutionIdsRequestSchema, request);
+	if (invalid) return invalid;
+	return runMentionAction(client, "add", request.resolutionIds);
+}
+/** @deprecated Backs the deprecated `mentions.execute`; use `notifyMentions` / `addMentions`. */
 async function executeMentionAction(client, request) {
 	const invalid = validateOpRequest(executeMentionActionRequestSchema, request);
 	if (invalid) return invalid;
-	const ids = (request.resolutionIds ?? []).map((id) => id.trim()).filter(Boolean);
-	if (ids.length === 0 || request.action !== "notify" && request.action !== "add") return failureOutcome(opError("INVALID_REQUEST", { message: "Pass an action (notify | add) and at least one resolution id." }));
+	const missing = "Pass an action (notify | add) and at least one resolution id.";
+	if (request.action !== "notify" && request.action !== "add") return failureOutcome(opError("INVALID_REQUEST", { message: missing }));
+	return runMentionAction(client, request.action, request.resolutionIds, missing);
+}
+async function runMentionAction(client, action, resolutionIds, missingIdsMessage = "Pass at least one resolution id.") {
+	const ids = (resolutionIds ?? []).map((id) => id.trim()).filter(Boolean);
+	if (ids.length === 0) return failureOutcome(opError("INVALID_REQUEST", { message: missingIdsMessage }));
 	const result = await client.mentions.executeAction({
-		action: request.action,
+		action,
 		resolutionIds: ids
 	});
 	if (!result.ok) return failureFromClientResult(result);
@@ -14395,11 +14790,11 @@ async function executeMentionAction(client, request) {
 		ok: true,
 		state: "executed",
 		data: {
-			action: request.action,
+			action,
 			results
 		},
 		next: null,
-		text: formatAgentMentionActionResults(request.action, results)
+		text: formatAgentMentionActionResults(action, results)
 	};
 }
 async function senderMentionDeliveries(client, request) {
@@ -14474,7 +14869,7 @@ async function getManualTopic(client, request) {
 		text: formatAgentKnowledgeStdout(result.data.content)
 	};
 }
-async function searchManual(client, request) {
+async function searchManual(client, request, options = {}) {
 	const malformed = validateOpRequest(searchManualRequestSchema, request);
 	if (malformed) return malformed;
 	const invalid = requireContext(request);
@@ -14490,12 +14885,7 @@ async function searchManual(client, request) {
 	const data = result.data;
 	const results = data.results;
 	const first = results[0];
-	const next = first ? {
-		kind: "read_manual_topic",
-		command: `raft manual get ${first.slug} --intent "…" --reason "…"`,
-		args: { topic: first.slug },
-		why: "Open the best-matching topic."
-	} : null;
+	const next = first ? hintStep("read_manual_topic", RAFT_HINTS.manualGet(first.slug), "Open the best-matching topic.", options.hints, { topic: first.slug }) : null;
 	return {
 		ok: true,
 		state: results.length > 0 ? "results" : "empty",
@@ -14696,29 +15086,26 @@ function formatAgentActionCardPosted(target, messageId) {
 * the preparer in the card's own thread; a card posted inside a thread has no
 * thread of its own, so the reply lands in that same thread.
 */
-function awaitConfirmationNext(target, messageId) {
+function awaitConfirmationNext(target, messageId, style) {
 	const short = messageId.slice(0, 8);
-	if (getParentTargetForThread(target) !== null) return {
-		kind: "await_confirmation",
-		command: `raft message read --target "${target}" --around ${short}`,
-		args: {
-			target,
-			messageId
-		},
-		why: "A human must click the card to commit it. When it is executed (or fails), the outcome arrives as a reply in this thread that @mentions you; you do not need to poll."
-	};
+	if (getParentTargetForThread(target) !== null) return hintStep("await_confirmation", RAFT_HINTS.messageRead({
+		target,
+		around: {
+			shown: short,
+			id: messageId
+		}
+	}), "A human must click the card to commit it. When it is executed (or fails), the outcome arrives as a reply in this thread that @mentions you; you do not need to poll.", style, {
+		target,
+		around: messageId,
+		messageId
+	});
 	const thread = agentTaskThreadTarget(target, messageId);
-	return {
-		kind: "await_confirmation",
-		command: `raft message read --target "${thread}"`,
-		args: {
-			target: thread,
-			messageId
-		},
-		why: "A human must click the card to commit it. When it is executed (or fails), the outcome arrives as a reply in the card's thread that @mentions you; you do not need to poll."
-	};
+	return hintStep("await_confirmation", RAFT_HINTS.messageRead({ target: thread }), "A human must click the card to commit it. When it is executed (or fails), the outcome arrives as a reply in the card's thread that @mentions you; you do not need to poll.", style, {
+		target: thread,
+		messageId
+	});
 }
-async function prepareActionCard(client, request) {
+async function prepareActionCard(client, request, options = {}) {
 	if (typeof request?.target !== "string" || !request.target.trim() || !request.action) return failureOutcome(opError("INVALID_REQUEST", { message: "A target and an action are required to prepare a card." }));
 	const invalid = validateOpRequest(prepareActionCardRequestSchema, request);
 	if (invalid) return invalid;
@@ -14737,7 +15124,7 @@ async function prepareActionCard(client, request) {
 		ok: true,
 		state: "prepared",
 		data: card,
-		next: awaitConfirmationNext(request.target, card.messageId),
+		next: awaitConfirmationNext(request.target, card.messageId, options.hints ?? "cli"),
 		text: formatAgentActionCardPosted(request.target, card.messageId)
 	};
 }
@@ -15148,6 +15535,14 @@ const OPERATION_DEFS = [
 		consumes: nothing,
 		output: small
 	},
+	{
+		name: "attachments.downloadUrl",
+		description: "Get a short-lived (5 minute) URL for an attachment's bytes, with its filename and MIME type, for runtimes that fetch files themselves. The URL grants access to the file: do not post it in messages.",
+		schema: downloadAttachmentUrlRequestSchema,
+		routes: ["attachmentDownloadUrl"],
+		consumes: nothing,
+		output: small
+	},
 	{
 		name: "attachments.comments",
 		description: "List the comments on an attachment.",
@@ -15171,21 +15566,47 @@ const OPERATION_DEFS = [
 		}
 	},
 	{
-		name: "mentions.execute",
-		description: "Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.",
-		schema: executeMentionActionRequestSchema,
+		name: "mentions.notify",
+		description: "Deliver unreached @mentions by notifying each mentioned target about the message, without adding them to the conversation. Takes resolutionId values from mentions.pending.",
+		schema: mentionResolutionIdsRequestSchema,
 		routes: ["mentionActionsExecute"],
 		consumes: nothing,
 		output: small
 	},
 	{
-		name: "mentions.deliveries",
+		name: "mentions.add",
+		description: "Deliver unreached @mentions by adding each mentioned target to the conversation, so they see the message and what follows. Takes resolutionId values from mentions.pending.",
+		schema: mentionResolutionIdsRequestSchema,
+		routes: ["mentionActionsExecute"],
+		consumes: nothing,
+		output: small
+	},
+	{
+		name: "mentions.delivery",
 		description: "Whether each @mention in a message you sent reached its target.",
 		schema: senderMentionDeliveriesRequestSchema,
 		routes: ["senderMentionDeliveries"],
 		consumes: nothing,
 		output: small
 	},
+	{
+		name: "mentions.execute",
+		description: "Deprecated: use mentions.notify / mentions.add. Removed in the next minor release. Deliver unreached @mentions: notify the mentioned target, or add them to the conversation.",
+		schema: executeMentionActionRequestSchema,
+		routes: ["mentionActionsExecute"],
+		consumes: nothing,
+		output: small,
+		deprecated: true
+	},
+	{
+		name: "mentions.deliveries",
+		description: "Deprecated: use mentions.delivery. Removed in the next minor release. Whether each @mention in a message you sent reached its target.",
+		schema: senderMentionDeliveriesRequestSchema,
+		routes: ["senderMentionDeliveries"],
+		consumes: nothing,
+		output: small,
+		deprecated: true
+	},
 	{
 		name: "actions.prepare",
 		description: "Post an action card (create a channel, add members, create an agent, or an integration step) for a human to confirm; the human who clicks it carries it out as themselves. When it is executed (or fails), the outcome arrives as a reply that @mentions you in the card's thread (or in the thread the card was posted in).",
@@ -15449,10 +15870,6 @@ const OPERATION_DEFS = [
 		output: small
 	}
 ];
-/** `tasks.updateStatus` → `tasks_update_status`. */
-function raftToolNameFor(name) {
-	return name.replace(/\./g, "_").replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
-}
 const IDEMPOTENCY_STRENGTH = {
 	natural: 0,
 	key: 1,
@@ -15524,11 +15941,17 @@ function createRaft(options) {
 	const serverUrl = requireServerUrl(options.serverUrl);
 	const authorization = `Bearer ${requireAgentCredential(options.credential)}`;
 	const frontier = SeenFrontier.fromSnapshot(options.frontier);
+	if (options.hints !== void 0 && options.hints !== "cli" && options.hints !== "tool") throw new TypeError("createRaft: hints must be \"cli\" or \"tool\".");
+	const hints = options.hints ?? "cli";
+	/** How every operation renders its hints. */
+	const style = { hints };
+	/** The SDK's default NOT_FOUND next action names a command; render it in the configured style. */
+	const styled = (outcome) => restyleDefaultNextAction(outcome, hints);
 	const session = new RaftStateSession(options.state, frontier, options.onStateSaveError);
 	/** Load before, run, then save if the operation succeeded and changed the state. */
 	const withState = async (run) => {
 		await session.ensureLoaded();
-		const outcome = await run();
+		const outcome = styled(await run());
 		if (outcome.ok) await session.save();
 		return outcome;
 	};
@@ -15564,7 +15987,7 @@ function createRaft(options) {
 		const outcome = await sendMessage(api, pending ? {
 			...request,
 			idempotencyKey: pending.idempotencyKey
-		} : request, seen);
+		} : request, seen, style);
 		if (outcome.ok && outcome.state === "interrupted" && outcome.interrupt.resume.idempotencyKey) session.rememberContinuation({
 			target: request.target,
 			idempotencyKey: outcome.interrupt.resume.idempotencyKey,
@@ -15579,7 +16002,7 @@ function createRaft(options) {
 		const outcome = await checkInbox(inboxApi, {
 			...request,
 			...since === void 0 ? {} : { since }
-		}, seen);
+		}, seen, style);
 		if (outcome.ok) {
 			session.markDirty();
 			if (since !== void 0 && (request.ack ?? "cursor") === "cursor") session.commit(since);
@@ -15598,7 +16021,7 @@ function createRaft(options) {
 			if (batch.ackMode === "cursor" && batch.messages.length > 0) session.setPending(batch.cursor);
 			session.markDirty();
 			await session.save();
-		});
+		}, style);
 	})();
 	const commitInbox = async (target) => {
 		await session.ensureLoaded();
@@ -15610,7 +16033,7 @@ function createRaft(options) {
 	};
 	/** `seen` undefined: read without recording anything (a code read). */
 	const readWithState = (request, seen) => withState(async () => {
-		const outcome = await readHistory(api, request, seen);
+		const outcome = await readHistory(api, request, seen, style);
 		if (outcome.ok && seen) session.markDirty();
 		return outcome;
 	});
@@ -15619,16 +16042,16 @@ function createRaft(options) {
 		wake: {
 			verifyNotice: (input) => verifyInboxNotice(input),
 			webhook: {
-				status: () => webhookStatus(api),
-				register: (request) => registerWebhook(api, request),
-				unregister: () => unregisterWebhook(api)
+				status: () => webhookStatus(api).then(styled),
+				register: (request) => registerWebhook(api, request).then(styled),
+				unregister: () => unregisterWebhook(api).then(styled)
 			}
 		},
 		inbox: {
 			check: (request = {}) => checkWithState(request, frontier),
 			commit: (target) => commitInbox(target),
 			drain: (request = {}) => drainWithState(request, frontier),
-			list: (request) => listInbox(api, request)
+			list: (request) => listInbox(api, request, style).then(styled)
 		},
 		messages: {
 			read: (request) => readWithState(request, frontier),
@@ -15637,10 +16060,10 @@ function createRaft(options) {
 				...request,
 				target: message.target
 			}, frontier),
-			search: (request) => searchMessages(api, request),
-			resolve: (request) => resolveMessage(api, request),
-			react: (request) => reactToMessage(api, request, "add"),
-			unreact: (request) => reactToMessage(api, request, "remove")
+			search: (request) => searchMessages(api, request, style).then(styled),
+			resolve: (request) => resolveMessage(api, request, style).then(styled),
+			react: (request) => reactToMessage(api, request, "add").then(styled),
+			unreact: (request) => reactToMessage(api, request, "remove").then(styled)
 		},
 		attachments: {
 			upload: (request) => uploadAttachment(api, {
@@ -15648,51 +16071,55 @@ function createRaft(options) {
 				fetch: options.fetch ?? fetch,
 				headers: Object.fromEntries(new Headers(options.headers)),
 				authorization
-			}, request),
-			download: (request) => downloadAttachment(api, request),
-			comments: (request) => attachmentComments(api, request)
+			}, request, style).then(styled),
+			download: (request) => downloadAttachment(api, request).then(styled),
+			downloadUrl: (request) => downloadAttachmentUrl(api, request, style).then(styled),
+			comments: (request) => attachmentComments(api, request).then(styled)
 		},
 		mentions: {
-			pending: (request) => pendingMentionActions(api, request),
-			execute: (request) => executeMentionAction(api, request),
-			deliveries: (request) => senderMentionDeliveries(api, request)
-		},
-		actions: { prepare: (request) => prepareActionCard(api, request) },
+			pending: (request) => pendingMentionActions(api, request, style).then(styled),
+			notify: (request) => notifyMentions(api, request).then(styled),
+			add: (request) => addMentions(api, request).then(styled),
+			delivery: (request) => senderMentionDeliveries(api, request).then(styled),
+			execute: (request) => executeMentionAction(api, request).then(styled),
+			deliveries: (request) => senderMentionDeliveries(api, request).then(styled)
+		},
+		actions: { prepare: (request) => prepareActionCard(api, request, style).then(styled) },
 		manual: {
-			get: (request) => getManualTopic(api, request),
-			search: (request) => searchManual(api, request)
+			get: (request) => getManualTopic(api, request).then(styled),
+			search: (request) => searchManual(api, request, style).then(styled)
 		},
 		tasks: {
-			claim: (request) => claimTasks(api, request),
-			list: (request) => listTasks(api, request),
-			create: (request) => createTasks(api, request),
-			unclaim: (request) => unclaimTask(api, request),
-			assign: (request) => assignTask(api, request),
-			unassign: (request) => unassignTask(api, request),
-			updateStatus: (request) => updateTaskStatus(api, request),
-			amend: (request) => amendTask(api, request),
-			history: (request) => taskHistory(api, request),
-			show: (request) => showTask(api, request),
-			convert: (request) => convertMessageToTask(api, request),
-			delete: (request) => deleteTask(api, request)
+			claim: (request) => claimTasks(api, request, style).then(styled),
+			list: (request) => listTasks(api, request, style).then(styled),
+			create: (request) => createTasks(api, request, style).then(styled),
+			unclaim: (request) => unclaimTask(api, request).then(styled),
+			assign: (request) => assignTask(api, request).then(styled),
+			unassign: (request) => unassignTask(api, request).then(styled),
+			updateStatus: (request) => updateTaskStatus(api, request, style).then(styled),
+			amend: (request) => amendTask(api, request, style).then(styled),
+			history: (request) => taskHistory(api, request).then(styled),
+			show: (request) => showTask(api, request, style).then(styled),
+			convert: (request) => convertMessageToTask(api, request, style).then(styled),
+			delete: (request) => deleteTask(api, request).then(styled)
 		},
 		channels: {
-			join: (request) => joinChannel(api, request),
-			leave: (request) => leaveChannel(api, request),
-			mute: (request) => muteChannel(api, request),
-			unmute: (request) => unmuteChannel(api, request),
-			members: (request) => channelMembers(api, request),
-			info: (request) => channelInfo(api, request)
+			join: (request) => joinChannel(api, request, style).then(styled),
+			leave: (request) => leaveChannel(api, request, style).then(styled),
+			mute: (request) => muteChannel(api, request, style).then(styled),
+			unmute: (request) => unmuteChannel(api, request, style).then(styled),
+			members: (request) => channelMembers(api, request).then(styled),
+			info: (request) => channelInfo(api, request, style).then(styled)
 		},
 		threads: {
-			list: () => listThreads(api),
-			unfollow: (request) => unfollowThread(api, request)
+			list: () => listThreads(api).then(styled),
+			unfollow: (request) => unfollowThread(api, request).then(styled)
 		},
-		server: { info: (request) => serverInfo(api, request) },
-		users: { info: (request) => userInfo(api, request) },
+		server: { info: (request) => serverInfo(api, request, style).then(styled) },
+		users: { info: (request) => userInfo(api, request, style).then(styled) },
 		profile: {
-			show: (request) => showProfile(api, request),
-			update: (request) => updateProfile(api, request)
+			show: (request) => showProfile(api, request).then(styled),
+			update: (request) => updateProfile(api, request).then(styled)
 		},
 		frontier,
 		state: {
@@ -15713,7 +16140,7 @@ function createRaft(options) {
 			const drain = drainWithState(args, call.seen);
 			const batches = [];
 			for (let step = await drain.next();; step = await drain.next()) {
-				if (step.done) return drainedInboxOutcome(batches, step.value);
+				if (step.done) return styled(drainedInboxOutcome(batches, step.value, style));
 				batches.push(step.value);
 			}
 		},
@@ -15741,8 +16168,12 @@ function createRaft(options) {
 		"messages.resolve": (args) => raft.messages.resolve(args),
 		"messages.react": (args) => raft.messages.react(args),
 		"messages.unreact": (args) => raft.messages.unreact(args),
+		"attachments.downloadUrl": (args) => raft.attachments.downloadUrl(args),
 		"attachments.comments": (args) => raft.attachments.comments(args),
 		"mentions.pending": (args) => raft.mentions.pending(args),
+		"mentions.notify": (args) => raft.mentions.notify(args),
+		"mentions.add": (args) => raft.mentions.add(args),
+		"mentions.delivery": (args) => raft.mentions.delivery(args),
 		"mentions.execute": (args) => raft.mentions.execute(args),
 		"mentions.deliveries": (args) => raft.mentions.deliveries(args),
 		"actions.prepare": (args) => raft.actions.prepare(args),
@@ -15844,6 +16275,7 @@ exports.createRaftClientFromStore = createRaftClientFromStore;
 exports.createRaftRoutes = createRaftRoutes;
 exports.createTasksRequestSchema = createTasksRequestSchema;
 exports.describeRaftRoute = describeRaftRoute;
+exports.downloadAttachmentUrlRequestSchema = downloadAttachmentUrlRequestSchema;
 exports.drainInboxRequestSchema = drainInboxRequestSchema;
 exports.executeMentionActionRequestSchema = executeMentionActionRequestSchema;
 exports.getManualTopicRequestSchema = getManualTopicRequestSchema;
@@ -15856,6 +16288,7 @@ exports.listInboxRequestSchema = listInboxRequestSchema;
 exports.listRaftRoutes = listRaftRoutes;
 exports.listTasksRequestSchema = listTasksRequestSchema;
 exports.listThreadsRequestSchema = listThreadsRequestSchema;
+exports.mentionResolutionIdsRequestSchema = mentionResolutionIdsRequestSchema;
 exports.parseRaftRegularChannelTarget = parseRaftRegularChannelTarget;
 exports.parseRaftState = parseRaftState;
 exports.pendingMentionActionsRequestSchema = pendingMentionActionsRequestSchema;