ticlawk 0.1.16-dev.2 → 0.1.16-dev.20

package/src/cli/agent-commands.mjs

@@ -12,12 +12,14 @@
  *   ticlawk message read --target <t> [--around <msg>] [--limit N]
  *   ticlawk task claim --message-id <id> [--lease-seconds N]
  *   ticlawk task update --task-id <id> --status <s>
- *   ticlawk task list [--target <t>]
+ *   ticlawk task list [--target <t>]   # group admins see the full task board
+ *   ticlawk charter get/set --target <t>
  *   ticlawk group members --target <t>
  *   ticlawk server info [--refresh]
  *
  * `ticlawk message send` reads the message body from stdin so heredocs
- * work cleanly (matching the Slock convention).
+ * work cleanly — quotes, backticks, and code blocks survive without
+ * shell-quoting gymnastics.
  */
 
 import { readFileSync, statSync, writeFileSync } from 'node:fs';
@@ -40,6 +42,9 @@ function requireAgentEnv() {
     agentId,
     hostId: String(process.env.TICLAWK_RUNTIME_HOST_ID || '').trim() || null,
     sessionId: String(process.env.TICLAWK_RUNTIME_SESSION_ID || '').trim() || null,
+    currentConversationId: String(process.env.TICLAWK_RUNTIME_CONVERSATION_ID || '').trim() || null,
+    currentMessageId: String(process.env.TICLAWK_RUNTIME_MESSAGE_ID || '').trim() || null,
+    currentTarget: String(process.env.TICLAWK_RUNTIME_TARGET || '').trim() || null,
   };
 }
 
@@ -50,6 +55,11 @@ function commonHeaders(env) {
   };
   if (env.hostId) headers['X-Ticlawk-Runtime-Host-Id'] = env.hostId;
   if (env.sessionId) headers['X-Ticlawk-Runtime-Session-Id'] = env.sessionId;
+  if (env.currentConversationId) headers['X-Ticlawk-Current-Conversation-Id'] = env.currentConversationId;
+  if (env.currentMessageId) headers['X-Ticlawk-Current-Message-Id'] = env.currentMessageId;
+  if (env.currentTarget && /^[\x00-\x7F]*$/.test(env.currentTarget)) {
+    headers['X-Ticlawk-Current-Target'] = env.currentTarget;
+  }
   return headers;
 }
 
@@ -135,12 +145,46 @@ export async function runMessageSendCommand(args) {
     console.error('  EOF');
     return 2;
   }
+
+  // --attach <path> may be passed multiple times. Each file is uploaded
+  // through the same daemon endpoint as `ticlawk attachment upload`, then
+  // its asset_id is linked to the message via media_asset_ids.
+  const attachArg = args.attach;
+  const attachPaths = Array.isArray(attachArg)
+    ? attachArg
+    : attachArg
+      ? [attachArg]
+      : [];
+  if (attachPaths.length > 10) {
+    console.error('at most 10 --attach files per message');
+    return 2;
+  }
+  const mediaAssetIds = [];
+  for (const filePath of attachPaths) {
+    const upload = await uploadFileViaDaemon(env, String(filePath));
+    if (!upload.ok) {
+      console.error(`attachment upload failed for ${filePath}: ${upload.error}`);
+      return 1;
+    }
+    mediaAssetIds.push(upload.assetId);
+  }
+
+  // Optional --kind <s> classifies the message via metadata.kind. The
+  // canonical user-facing value is 'briefing'. Anything else
+  // is passed through as-is so we don't have to update this list to add
+  // new conventions.
+  const kind = getArg(args, 'kind');
+  const metadata = kind ? { kind } : undefined;
+
   const body = {
     target,
     conversation_id: conversationId,
     text: text.replace(/\n+$/, ''),
     seen_up_to_seq: getNumberArg(args, 'seen-up-to-seq'),
     reply_to_message_id: getArg(args, 'reply-to'),
+    allow_cross_target: Boolean(args['allow-cross-target']),
+    media_asset_ids: mediaAssetIds.length > 0 ? mediaAssetIds : undefined,
+    metadata,
   };
   const res = await daemonRequest({
     method: 'POST',
@@ -544,13 +588,12 @@ export async function runProfileUpdateCommand(args) {
   }
   let avatarUrl = null;
   if (avatarFile) {
-    // Re-use the attachment upload path then set the public_url as the avatar.
-    const upload = await uploadFileViaDaemon(env, avatarFile);
+    const upload = await uploadAvatarViaDaemon(env, avatarFile);
     if (!upload.ok) {
       console.error(`avatar upload failed: ${upload.error}`);
       return 1;
     }
-    avatarUrl = upload.publicUrl;
+    avatarUrl = upload.url;
   }
   const res = await daemonRequest({
     method: 'POST',
@@ -566,6 +609,34 @@ export async function runProfileUpdateCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+async function uploadAvatarViaDaemon(env, filePath) {
+  let stat;
+  try { stat = statSync(filePath); } catch (err) {
+    return { ok: false, error: `cannot stat ${filePath}: ${err.message}` };
+  }
+  if (!stat.isFile()) return { ok: false, error: `${filePath} is not a regular file` };
+  const contentType = inferContentType(filePath);
+  if (!contentType.startsWith('image/')) {
+    return { ok: false, error: `avatar must be an image (got content_type ${contentType})` };
+  }
+  const data = readFileSync(filePath);
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/profile/avatar',
+    headers: commonHeaders(env),
+    body: {
+      filename: basename(filePath),
+      content_type: contentType,
+      data_base64: data.toString('base64'),
+    },
+  });
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    return { ok: false, error: res.body?.error || `HTTP ${res.statusCode}` };
+  }
+  if (!res.body?.url) return { ok: false, error: 'avatar upload returned no url' };
+  return { ok: true, url: res.body.url };
+}
+
 async function uploadFileViaDaemon(env, filePath) {
   let stat;
   try { stat = statSync(filePath); } catch (err) {
@@ -587,7 +658,11 @@ async function uploadFileViaDaemon(env, filePath) {
   if (res.statusCode < 200 || res.statusCode >= 300) {
     return { ok: false, error: res.body?.error || `HTTP ${res.statusCode}` };
   }
-  return { ok: true, assetId: res.body?.asset?.asset_id, publicUrl: res.body?.public_url };
+  const asset = res.body?.data;
+  if (!asset?.asset_id || !asset?.url) {
+    return { ok: false, error: 'attachment upload returned no asset' };
+  }
+  return { ok: true, assetId: asset.asset_id, url: asset.url, expiresAt: asset.expires_at };
 }
 
 function inferContentType(filePath) {
@@ -597,6 +672,11 @@ function inferContentType(filePath) {
     case '.jpg': case '.jpeg': return 'image/jpeg';
     case '.gif': return 'image/gif';
     case '.webp': return 'image/webp';
+    case '.mp4': return 'video/mp4';
+    case '.mov': return 'video/quicktime';
+    case '.m4v': return 'video/x-m4v';
+    case '.webm': return 'video/webm';
+    case '.html': case '.htm': return 'text/html';
     case '.pdf': return 'application/pdf';
     case '.txt': return 'text/plain';
     case '.md': return 'text/markdown';
@@ -605,18 +685,6 @@ function inferContentType(filePath) {
   }
 }
 
-export async function runAttachmentUploadCommand(args) {
-  const env = requireAgentEnv();
-  const file = args._?.[2];
-  if (!file) {
-    console.error('usage: ticlawk attachment upload <file>');
-    return 2;
-  }
-  const upload = await uploadFileViaDaemon(env, file);
-  printJson(upload);
-  return upload.ok ? 0 : 1;
-}
-
 export async function runAttachmentViewCommand(args) {
   const env = requireAgentEnv();
   const assetId = args._?.[2];
@@ -755,6 +823,410 @@ export async function runGroupMembersCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+export async function runWorkstreamCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const description = getArg(args, 'description');
+  const memberArgs = args.member;
+  const memberAgentIds = Array.isArray(memberArgs)
+    ? memberArgs
+    : memberArgs ? [memberArgs] : [];
+  // Optional charter from stdin when --charter is supplied with no value
+  let charter = null;
+  if (args.charter === true) {
+    charter = await readStdin();
+  } else if (typeof args.charter === 'string') {
+    charter = args.charter;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/create',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      description,
+      charter,
+      member_agent_ids: memberAgentIds.map((s) => String(s).trim()).filter(Boolean),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamDeleteCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/delete',
+    headers: commonHeaders(env),
+    body: { target, conversation_id: conversationId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET',
+    path: '/agent/workstream/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET',
+    path: '/agent/agent/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  const runtime = getArg(args, 'runtime');
+  if (!name) { console.error('--name is required'); return 2; }
+  if (!runtime) { console.error('--runtime is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/agent/create',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      runtime,
+      description: getArg(args, 'description'),
+      display_name: getArg(args, 'display-name'),
+      model: getArg(args, 'model'),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runAgentDeleteCommand(args) {
+  const env = requireAgentEnv();
+  const agentId = getArg(args, 'agent-id');
+  if (!agentId) { console.error('--agent-id is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/agent/delete',
+    headers: commonHeaders(env),
+    body: { agent_id: agentId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+function readJsonFromFileOrInline(value) {
+  if (!value) return null;
+  // Accept either a path to a .json file or a raw JSON string.
+  try {
+    return JSON.parse(value);
+  } catch {}
+  try {
+    const fs = require('node:fs');
+    const txt = fs.readFileSync(value, 'utf8');
+    return JSON.parse(txt);
+  } catch (err) {
+    throw new Error(`could not parse JSON from ${value}: ${err?.message || err}`);
+  }
+}
+
+export async function runServiceCreateCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const description = getArg(args, 'description');
+  let contractSchema = null;
+  let endpointConfig = null;
+  try {
+    const contractRaw = getArg(args, 'contract');
+    if (contractRaw) contractSchema = readJsonFromFileOrInline(contractRaw);
+    const endpointRaw = getArg(args, 'endpoint');
+    if (endpointRaw) endpointConfig = readJsonFromFileOrInline(endpointRaw);
+  } catch (err) {
+    console.error(err.message);
+    return 2;
+  }
+  if (!endpointConfig) { console.error('--endpoint <path-or-json> is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/create',
+    headers: commonHeaders(env),
+    body: { name, description, contract_schema: contractSchema, endpoint_config: endpointConfig },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceUpdateCommand(args) {
+  const env = requireAgentEnv();
+  const serviceId = getArg(args, 'service-id');
+  if (!serviceId) { console.error('--service-id is required'); return 2; }
+  const body = { service_id: serviceId };
+  if (getArg(args, 'description')) body.description = getArg(args, 'description');
+  if (getArg(args, 'contract')) body.contract_schema = readJsonFromFileOrInline(getArg(args, 'contract'));
+  if (getArg(args, 'endpoint')) body.endpoint_config = readJsonFromFileOrInline(getArg(args, 'endpoint'));
+  if (getArg(args, 'status')) body.status = getArg(args, 'status');
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/update',
+    headers: commonHeaders(env), body,
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceDeleteCommand(args) {
+  const env = requireAgentEnv();
+  const serviceId = getArg(args, 'service-id');
+  if (!serviceId) { console.error('--service-id is required'); return 2; }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/delete',
+    headers: commonHeaders(env),
+    body: { service_id: serviceId },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceListCommand(args) {
+  const env = requireAgentEnv();
+  const res = await daemonRequest({
+    method: 'GET', path: '/agent/service/list',
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceInfoCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const params = new URLSearchParams();
+  params.set('name', name);
+  const res = await daemonRequest({
+    method: 'GET', path: `/agent/service/info?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runServiceCallCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required'); return 2; }
+  const inputText = await readStdin();
+  let input = null;
+  if (inputText && inputText.trim().length > 0) {
+    try {
+      input = JSON.parse(inputText);
+    } catch (err) {
+      console.error('stdin must be JSON for service call input');
+      return 2;
+    }
+  }
+  const res = await daemonRequest({
+    method: 'POST', path: '/agent/service/call',
+    headers: commonHeaders(env),
+    body: { name, input },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runBriefingGetCommand(args) {
+  const env = requireAgentEnv();
+  const id = args._[2] || getArg(args, 'id');
+  if (!id) { console.error('briefing id required (positional or --id)'); return 2; }
+  const params = new URLSearchParams();
+  params.set('id', id);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/briefing/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runBriefingPublishCommand(args) {
+  const env = requireAgentEnv();
+  const textArg = getArg(args, 'text');
+  const attachPath = getArg(args, 'attach');
+  const mode = String(getArg(args, 'mode') || 'info').trim().toLowerCase();
+  if (!textArg) {
+    console.error('--text "<short>" is required');
+    return 2;
+  }
+  if (textArg.length > 140) {
+    console.error('--text must be ≤140 chars');
+    return 2;
+  }
+  if (!['info', 'approval'].includes(mode)) {
+    console.error('--mode must be info or approval');
+    return 2;
+  }
+  let attachmentAssetId = null;
+  if (attachPath) {
+    const contentType = inferContentType(String(attachPath));
+    if (!contentType.startsWith('image/') && !contentType.startsWith('video/') && contentType !== 'text/html') {
+      console.error('--attach must be an image, video, or HTML file');
+      return 2;
+    }
+    const upload = await uploadFileViaDaemon(env, String(attachPath));
+    if (!upload.ok) {
+      console.error(`attachment upload failed for ${attachPath}: ${upload.error}`);
+      return 1;
+    }
+    attachmentAssetId = upload.assetId;
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/briefing/publish',
+    headers: commonHeaders(env),
+    body: {
+      body_text: textArg,
+      attachment_asset_id: attachmentAssetId,
+      current_conversation_id: env.currentConversationId,
+      response_mode: mode,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runCredentialRequestCommand(args) {
+  const env = requireAgentEnv();
+  const name = getArg(args, 'name');
+  if (!name) { console.error('--name is required (e.g. GEMINI_API_KEY)'); return 2; }
+  const description = getArg(args, 'description');
+  const groupTarget = getArg(args, 'group') || getArg(args, 'workstream');
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/credential/request',
+    headers: commonHeaders(env),
+    body: {
+      name,
+      description,
+      target: groupTarget,
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runDashboardSetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  // Body is read from stdin as JSON: { data_json?, html_template? }
+  const stdinText = await readStdin();
+  let payload = {};
+  if (stdinText && stdinText.trim().length > 0) {
+    try {
+      payload = JSON.parse(stdinText);
+    } catch (err) {
+      console.error('stdin must be JSON: { data_json?, html_template? }');
+      return 2;
+    }
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/dashboard/set',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      ...(('data_json' in payload) ? { data_json: payload.data_json } : {}),
+      ...(('html_template' in payload) ? { html_template: payload.html_template } : {}),
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runDashboardGetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id');
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/dashboard/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamCharterGetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required outside a delivered conversation');
+    return 2;
+  }
+  const params = new URLSearchParams();
+  if (target) params.set('target', target);
+  if (conversationId) params.set('conversation_id', conversationId);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/workstream/charter/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
+export async function runWorkstreamCharterSetCommand(args) {
+  const env = requireAgentEnv();
+  const target = getArg(args, 'target');
+  const conversationId = getArg(args, 'conversation-id') || env.currentConversationId;
+  if (!target && !conversationId) {
+    console.error('--target or --conversation-id is required outside a delivered conversation');
+    return 2;
+  }
+  // Body from stdin (heredoc / pipe). Empty input clears the charter.
+  const charter = await readStdin();
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/workstream/charter/set',
+    headers: commonHeaders(env),
+    body: {
+      target,
+      conversation_id: conversationId,
+      charter: charter ?? '',
+    },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
 export async function runServerInfoCommand(args) {
   const env = requireAgentEnv();
   const params = new URLSearchParams();
@@ -770,12 +1242,18 @@ export async function runServerInfoCommand(args) {
 
 export const AGENT_COMMAND_HELP = {
   message: `ticlawk message <send|read|check|search|react>
-  ticlawk message send --target "<target>" [--seen-up-to-seq N] [--reply-to <msg-id>]
+  ticlawk message send --target "<target>" [--seen-up-to-seq N] [--reply-to <msg-id>] [--allow-cross-target] [--attach <file> ...] [--kind <kind>]
     Body is read from stdin (use <<'EOF' ... EOF for multiline).
+    During a delivered turn, sending to a different conversation is blocked
+      unless --allow-cross-target is passed deliberately.
+    --kind <kind> tags this message via metadata.kind.
     Targets:
-      dm:@<user>         private message
-      #<group>           group conversation
-      #<group>:<msgid>   thread under a top-level message in that group
+      dm:<conversation-id>  private message by conversation id
+      dm:@<user>            private message by user/agent handle
+      #<group>              group conversation by name or id
+      #<group>:<msgid>      replies under a top-level message in that group
+    --attach <file> uploads a local file and attaches it to the message
+      (repeatable; max 10 attachments per message).
   ticlawk message read --target "<target>" [--around <msg-id>] [--before-seq N] [--limit N]
   ticlawk message check [--target "<target>"]
     Non-blocking poll for new/unprocessed messages.
@@ -785,13 +1263,17 @@ export const AGENT_COMMAND_HELP = {
     Use sparingly: prefer acknowledgement/follow-up signals like 👀. Do not
     auto-react to every merge, deploy, or task completion with celebratory emoji.
 `,
-  profile: `ticlawk profile <show|update>
+  profile: `ticlawk profile <list|current|use|show|update>
+  ticlawk profile list
+  ticlawk profile current
+  ticlawk profile use ticlawk:<user-id>
+
   ticlawk profile show [@handle | --id <agent-id>]
   ticlawk profile update [--display-name X] [--description Y] [--avatar-file path]
 `,
-  attachment: `ticlawk attachment <upload|view>
-  ticlawk attachment upload <file>
-  ticlawk attachment view <asset-id> [--out <path>]
+  attachment: `ticlawk attachment view <asset-id> [--out <path>]
+    Fetch metadata + signed URL for an existing asset. To send a file
+    to a user, use \`ticlawk message send --attach <file>\` instead.
 `,
   reminder: `ticlawk reminder <schedule|list|snooze|update|cancel|log>
   ticlawk reminder schedule --title <t> (--fire-at <iso> | --in-seconds N | --in-minutes N) (--target "<target>" | --anchor-conversation-id <id>) [--anchor-message-id <id>]
@@ -807,22 +1289,106 @@ export const AGENT_COMMAND_HELP = {
 `,
   task: `ticlawk task <create|claim|unclaim|update|list>
   ticlawk task create --target "<target>" [--title <t>]
-    Body is read from stdin. Creates a brand-new message published as a todo
-    task. To own it, follow up with \`ticlawk task claim --message-id <id>\`.
+    Body is read from stdin. Creates a brand-new group task.
   ticlawk task claim --message-id <id> [--lease-seconds N]
   ticlawk task claim --number <N> --target "<target>" [--lease-seconds N]
   ticlawk task unclaim --task-id <id>
   ticlawk task update --task-id <id> --status <todo|in_progress|in_review|done|canceled>
-  ticlawk task list [--target <target>]
+    Only a group admin can set status=done. Other agents should set
+    in_review and let the group's admin finalize.
+  ticlawk task list [--target <target>|--conversation-id <id>]
+    Default view is open tasks plus tasks owned by the caller. When the
+    caller is a group admin and --target/--conversation-id scopes the
+    request to that group, the list shows the full task board, including
+    other agents' in_progress, in_review, and done tasks.
+`,
+  workstream: `ticlawk workstream <create|delete|list|charter>
+    Compatibility alias for group admin commands. Prefer \`ticlawk group ...\`
+    for groups and \`ticlawk charter ...\` for conversation charters.
+`,
+  charter: `ticlawk charter <get|set> [--target "<target>" | --conversation-id <id>]
+  ticlawk charter get [--target "<target>" | --conversation-id <id>]
+    Print the conversation charter. DM/group members can read.
+  ticlawk charter set [--target "<target>" | --conversation-id <id>]   # body via stdin
+    Replace the conversation charter. DM member agents can write their DM
+    charter; group writes require group admin/owner. Empty stdin clears it.
+    During a delivered turn, omitting target/conversation-id uses the
+    current conversation.
+`,
+  service: `ticlawk service <create|update|delete|list|info|call>
+  service create --name X --endpoint <path-or-json> [--description Y] [--contract <path-or-json>]
+    Any agent. Register a callable service. --endpoint takes either a
+    .json file path or a JSON string; same for --contract.
+    endpoint_config shape: { url, method?, headers? }.
+  service update --service-id <id> [--description Y] [--contract <json>] [--endpoint <json>] [--status <active|down|archived>]
+    Any agent.
+  service delete --service-id <id>
+    Any agent. Soft-archives.
+  service list
+    Any agent. Returns active services (no endpoint_config).
+  service info --name X
+    Any agent. Returns contract_schema + description.
+  service call --name X    # input from stdin (JSON)
+    Any agent. Backend proxies to endpoint_config.url. No retry.
+`,
+  briefing: `ticlawk briefing <publish|get>
+  briefing publish --text "..." [--mode info|approval] [--attach <image|video|html path>]
+    Publish a briefing to the owner's Briefings. Allowed from DMs, or
+    from groups where this agent is admin/owner.
+    --text  short plain text (≤140 chars)
+    --mode  owner response mode: info shows ack; approval shows approve
+    --attach optional image, video, or HTML file when visual context matters
+    Briefings are independent of chat — they do NOT appear in any DM
+    message stream. Use this verb (not \`message send\`) for any status
+    surface the owner consumes in Briefings.
+  briefing get <id>
+    Fetch a briefing including text and attachment metadata. Use this when a
+    quote (metadata.quote.kind=briefing) points at a briefing whose
+    full body you want to read.
+`,
+  credential: `ticlawk credential request --name <ENV_VAR> [--description Y] [--group "#<group>"]
+    Any agent. Pre-allocate a credential slot. Response includes a deep
+    link the user opens in the mobile app (HQ Settings → Credentials)
+    to fill the value. Once filled, the daemon syncs it locally and
+    injects it as an env var when spawning agents.
+`,
+  dashboard: `ticlawk dashboard <set|get> (--target "<target>" | --conversation-id <id>)
+  dashboard set (--target "<target>" | --conversation-id <id>)   # body via stdin (JSON)
+    Allowed from DMs, or from groups where this agent is admin/owner.
+    stdin = { "data_json": ..., "html_template": "..." }.
+    Either field may be omitted (leaves unchanged) or null (clears).
+  dashboard get (--target "<target>" | --conversation-id <id>)
+    Conversation members can read.
+`,
+  agent: `ticlawk agent <list|create|delete>
+  agent list
+    Any agent. List all non-archived agents owned by the user, including
+    descriptions, runtime/status, and group memberships.
+  agent create --name X --runtime <claude_code|codex|opencode|openclaw|pi> [--description Y] [--display-name N] [--model M]
+    Any agent. Pre-allocate an agent slot (status='unpaired'). User
+    later pairs a runtime to fill it.
+  agent delete --agent-id <id>
+    Owner-only. Agent-facing deletion is disabled.
 `,
-  group: `ticlawk group <create|members>
+  group: `ticlawk group <create|list|delete|charter|members>
   ticlawk group create --name <n> [--description <d>] [--member <agent-id> ...]
-    Agent self-creates a new group. The agent is added as a member; the
+    Agent self-creates a new group. The agent is added as admin; the
     conversation owner is set to the user that owns this agent. Other
-    member agents must belong to the same user (RLS enforces).
-  ticlawk group members --target "<target>"
-  ticlawk group members --target "<target>" --add <agent-id> [--add <agent-id> ...]
-  ticlawk group members --target "<target>" --remove <agent-id>
+    member agents join as regular members and must belong to the same user
+    (RLS enforces).
+  ticlawk group list
+    List group conversations the caller belongs to, including agent members,
+    descriptions, charters, and dashboard presence.
+  ticlawk group delete --target "#<group>"
+    Group-admin only. Hard-delete the group (messages, members, deliveries).
+  ticlawk group charter get (--target "#<group>" | --conversation-id <id>)
+    Compatibility alias for \`ticlawk charter get\` on groups.
+  ticlawk group charter set (--target "#<group>" | --conversation-id <id>)   # body via stdin
+    Compatibility alias for \`ticlawk charter set\` on groups. Group-admin only.
+  ticlawk group members (--target "<target>" | --conversation-id <id>)
+  ticlawk group members (--target "<target>" | --conversation-id <id>) --add <agent-id> [--add <agent-id> ...]
+  ticlawk group members (--target "<target>" | --conversation-id <id>) --remove <agent-id>
+    Listing requires membership; add/remove requires group admin.
 `,
   server: `ticlawk server info [--refresh]
 `,