@skillrecordings/cli 0.9.0 → 0.10.1

package/dist/index.js

@@ -91673,6 +91673,51 @@ init_esm_shims();
 
 // src/commands/front/api.ts
 init_esm_shims();
+
+// src/commands/front/json-output.ts
+init_esm_shims();
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync8 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { join as join12 } from "path";
+var STDOUT_LIMIT = 64 * 1024;
+function writeJsonOutput(data2) {
+  const json = JSON.stringify(data2, null, 2);
+  if (json.length <= STDOUT_LIMIT) {
+    console.log(json);
+    return;
+  }
+  const dir = join12(tmpdir2(), "skill-front");
+  mkdirSync5(dir, { recursive: true });
+  const filepath = join12(dir, `${Date.now()}.json`);
+  writeFileSync8(filepath, json);
+  const envelope = {
+    _type: data2?._type ?? "result",
+    _file: filepath,
+    _size: `${(json.length / 1024).toFixed(1)}KB`,
+    _hint: `cat ${filepath} | jq`
+  };
+  const d = data2;
+  if (d.data && typeof d.data === "object") {
+    const inner = d.data;
+    if (inner.total !== void 0) envelope.total = inner.total;
+    if (inner.query !== void 0) envelope.query = inner.query;
+    if (Array.isArray(inner.conversations)) {
+      envelope.conversations = inner.conversations.map(
+        (c) => ({
+          id: c.id,
+          subject: c.subject,
+          status: c.status
+        })
+      );
+    }
+  }
+  if (Array.isArray(d._actions) && d._actions.length > 0) {
+    envelope._actions = d._actions;
+  }
+  console.log(JSON.stringify(envelope, null, 2));
+}
+
+// src/commands/front/api.ts
 function getFrontClient() {
   const apiToken = process.env.FRONT_API_TOKEN;
   if (!apiToken) {
@@ -91714,13 +91759,91 @@ async function apiPassthrough(method, endpoint, options) {
         `Unsupported method: ${method}. Use GET, POST, PATCH, PUT, or DELETE.`
       );
   }
-  console.log(JSON.stringify(result, null, 2));
+  writeJsonOutput(result);
 }
 function registerApiCommand(frontCommand) {
   frontCommand.command("api").description("Raw Front API request (escape hatch)").argument("<method>", "HTTP method (GET, POST, PATCH, PUT, DELETE)").argument(
     "<endpoint>",
     "API endpoint path (e.g., /me, /conversations/cnv_xxx)"
-  ).option("--data <json>", "Request body as JSON string").action(
+  ).option("--data <json>", "Request body as JSON string").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Raw Front API Passthrough \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Escape hatch for making arbitrary Front API calls. Use this when no
+  typed CLI command exists for what you need.
+
+ARGUMENTS
+  <method>      HTTP method: GET, POST, PATCH, PUT, DELETE
+  <endpoint>    API path (leading / is optional \u2014 both work)
+
+OPTIONS
+  --data <json>   Request body as a valid JSON string (for POST, PATCH, PUT)
+
+COMMON ENDPOINTS
+  Endpoint                          What it returns
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  /me                               Authenticated identity
+  /inboxes                          All inboxes
+  /conversations/cnv_xxx            Conversation details
+  /conversations/cnv_xxx/messages   Messages in a conversation
+  /tags                             All tags
+  /teammates                        All teammates
+  /contacts                         All contacts
+  /accounts                         All accounts
+  /channels                         All channels
+  /rules                            All rules
+
+ENDPOINT NORMALIZATION
+  Leading slash is optional. These are equivalent:
+    skill front api GET /me
+    skill front api GET me
+
+OUTPUT
+  Always JSON. Pipe to jq for filtering.
+
+EXAMPLES
+  # Check authenticated identity
+  skill front api GET /me
+
+  # List all inboxes
+  skill front api GET /inboxes
+
+  # Get a specific conversation
+  skill front api GET /conversations/cnv_abc123
+
+  # Archive a conversation
+  skill front api PATCH /conversations/cnv_abc123 --data '{"status":"archived"}'
+
+  # Apply a tag to a conversation
+  skill front api POST /conversations/cnv_abc123/tags --data '{"tag_ids":["tag_xxx"]}'
+
+  # Create a new tag
+  skill front api POST /tags --data '{"name":"my-new-tag","highlight":"blue"}'
+
+  # Delete a tag
+  skill front api DELETE /tags/tag_xxx
+
+  # List teammates and extract emails
+  skill front api GET /teammates | jq '._results[].email'
+
+  # Get conversation + pipe to jq for specific fields
+  skill front api GET /conversations/cnv_abc123 | jq '{subject, status, assignee: .assignee.email}'
+
+WHEN TO USE THIS vs TYPED COMMANDS
+  Prefer typed commands when available \u2014 they have better error handling,
+  pagination, and output formatting:
+    skill front search        (not: skill front api GET /conversations/search/...)
+    skill front inbox         (not: skill front api GET /inboxes)
+    skill front tags list     (not: skill front api GET /tags)
+    skill front conversation  (not: skill front api GET /conversations/cnv_xxx)
+
+  Use "skill front api" for endpoints without a dedicated command, or when
+  you need the raw response shape.
+
+  Full API docs: https://dev.frontapp.com/reference
+`
+  ).action(
     async (method, endpoint, options) => {
       try {
         await apiPassthrough(method, endpoint, options);
@@ -92000,16 +92123,12 @@ async function archiveConversations(convId, additionalIds, options) {
           };
         })
       );
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "archive-result",
-            command: `skill front archive ${allIds.map(normalizeId).join(" ")} --json`,
-            data: results2
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "archive-result",
+          command: `skill front archive ${allIds.map(normalizeId).join(" ")} --json`,
+          data: results2
+        })
       );
       return;
     }
@@ -92059,7 +92178,47 @@ async function archiveConversations(convId, additionalIds, options) {
   }
 }
 function registerArchiveCommand(frontCommand) {
-  frontCommand.command("archive").description("Archive one or more conversations by ID").argument("<id>", "Conversation ID (e.g., cnv_xxx)").argument("[ids...]", "Additional conversation IDs to archive").option("--json", "Output as JSON").action(archiveConversations);
+  frontCommand.command("archive").description("Archive one or more conversations by ID").argument("<id>", "Conversation ID (e.g., cnv_xxx)").argument("[ids...]", "Additional conversation IDs to archive").option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Archive Conversations \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Sets the status of one or more conversations to 'archived' in Front.
+  Accepts conversation IDs (cnv_xxx) or full Front API URLs.
+
+SINGLE CONVERSATION
+  skill front archive cnv_abc123
+
+MULTIPLE CONVERSATIONS
+  skill front archive cnv_abc123 cnv_def456 cnv_ghi789
+
+  All IDs are archived concurrently. The summary shows success/failure counts.
+
+JSON OUTPUT (for scripting)
+  skill front archive cnv_abc123 --json
+  skill front archive cnv_abc123 cnv_def456 --json
+
+  JSON envelope includes per-conversation success/error status.
+
+BATCH PIPELINE (search \u2192 archive)
+  # Archive all snoozed conversations in an inbox
+  skill front search "is:snoozed" --inbox inb_4bj7r --json \\
+    | jq -r '.data.conversations[].id' \\
+    | xargs -I{} skill front archive {}
+
+  # Archive unassigned conversations older than 30 days
+  skill front search "is:unassigned" --inbox inb_4bj7r --json \\
+    | jq -r '.data.conversations[].id' \\
+    | xargs -I{} skill front archive {}
+
+  For filter-based bulk archiving with built-in safety, use bulk-archive instead.
+
+RELATED COMMANDS
+  skill front bulk-archive   Filter-based bulk archive (--dry-run, rate limiting)
+  skill front conversation    View conversation details before archiving
+  skill front search          Find conversations by query / filters
+`
+  ).action(archiveConversations);
 }
 
 // src/commands/front/assign.ts
@@ -92089,20 +92248,16 @@ async function assignConversation(conversationId, teammateId, options) {
     const assigneeId = options.unassign ? "" : normalizeId2(teammateId);
     await front.conversations.updateAssignee(convId, assigneeId);
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "assign-result",
-            command: options.unassign ? `skill front assign ${convId} --unassign --json` : `skill front assign ${convId} ${assigneeId} --json`,
-            data: {
-              id: convId,
-              assignee: options.unassign ? null : assigneeId,
-              success: true
-            }
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "assign-result",
+          command: options.unassign ? `skill front assign ${convId} --unassign --json` : `skill front assign ${convId} ${assigneeId} --json`,
+          data: {
+            id: convId,
+            assignee: options.unassign ? null : assigneeId,
+            success: true
+          }
+        })
       );
     } else {
       if (options.unassign) {
@@ -92128,7 +92283,58 @@ async function assignConversation(conversationId, teammateId, options) {
   }
 }
 function registerAssignCommand(frontCommand) {
-  frontCommand.command("assign").description("Assign a conversation to a teammate").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("[teammate-id]", "Teammate ID (tea_xxx) - omit with --unassign").option("--unassign", "Remove assignee").option("--json", "Output as JSON").action(assignConversation);
+  frontCommand.command("assign").description("Assign a conversation to a teammate").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("[teammate-id]", "Teammate ID (tea_xxx) - omit with --unassign").option("--unassign", "Remove assignee").option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Assign / Unassign Conversations \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Assign a conversation to a teammate, or remove the current assignee.
+  Accepts conversation IDs (cnv_xxx) and teammate IDs (tea_xxx).
+
+ASSIGN
+  skill front assign <conversation-id> <teammate-id>
+
+  The teammate must exist in your Front workspace.
+
+UNASSIGN
+  skill front assign <conversation-id> --unassign
+
+  Removes the current assignee. Cannot be combined with a teammate ID.
+
+FINDING IDs
+  Teammate IDs:
+    skill front teammates                                 # Human-readable list
+    skill front teammates --json | jq '.[].id'            # Just the IDs
+
+  Conversation IDs:
+    skill front search --inbox inb_xxx --json | jq '.data.conversations[].id'
+    skill front conversation <cnv_xxx>                    # Verify a conversation
+
+JSON OUTPUT (--json)
+  Returns a HATEOAS-wrapped object:
+    { type: "assign-result", data: { id, assignee, success } }
+
+EXAMPLES
+  # Assign a conversation to a teammate
+  skill front assign cnv_abc123 tea_def456
+
+  # Unassign (remove assignee)
+  skill front assign cnv_abc123 --unassign
+
+  # Assign and get JSON output
+  skill front assign cnv_abc123 tea_def456 --json
+
+  # Pipeline: assign all unassigned convos in an inbox to a teammate
+  skill front search --inbox inb_4bj7r --status unassigned --json \\
+    | jq -r '.data.conversations[].id' \\
+    | xargs -I{} skill front assign {} tea_def456
+
+RELATED COMMANDS
+  skill front teammates              List teammates and their IDs
+  skill front conversation <id>      View conversation details + current assignee
+  skill front search                 Find conversations by filters
+`
+  ).action(assignConversation);
 }
 
 // src/commands/front/bulk-archive.ts
@@ -92293,16 +92499,12 @@ Found ${result.matches.length} matching conversations`);
     }
     if (dryRun) {
       if (json) {
-        console.log(
-          JSON.stringify(
-            hateoasWrap({
-              type: "bulk-archive-result",
-              command: `skill front bulk-archive --inbox ${inbox} --dry-run --json`,
-              data: result
-            }),
-            null,
-            2
-          )
+        writeJsonOutput(
+          hateoasWrap({
+            type: "bulk-archive-result",
+            command: `skill front bulk-archive --inbox ${inbox} --dry-run --json`,
+            data: result
+          })
         );
       } else {
         console.log("\nMatching conversations:");
@@ -92322,16 +92524,12 @@ Run without --dry-run to archive ${result.matches.length} conversation(s)`
       if (!json) {
         console.log("\nNo conversations to archive.");
       } else {
-        console.log(
-          JSON.stringify(
-            hateoasWrap({
-              type: "bulk-archive-result",
-              command: `skill front bulk-archive --inbox ${inbox} --json`,
-              data: result
-            }),
-            null,
-            2
-          )
+        writeJsonOutput(
+          hateoasWrap({
+            type: "bulk-archive-result",
+            command: `skill front bulk-archive --inbox ${inbox} --json`,
+            data: result
+          })
         );
       }
       return;
@@ -92361,16 +92559,12 @@ Run without --dry-run to archive ${result.matches.length} conversation(s)`
       await new Promise((r) => setTimeout(r, 150));
     }
     if (json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "bulk-archive-result",
-            command: `skill front bulk-archive --inbox ${inbox} --json`,
-            data: result
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "bulk-archive-result",
+          command: `skill front bulk-archive --inbox ${inbox} --json`,
+          data: result
+        })
       );
     } else {
       console.log("\n\nBulk Archive Results:");
@@ -92415,7 +92609,67 @@ function registerBulkArchiveCommand(parent2) {
   ).option("--tag <name>", "Filter by tag name (contains)").option(
     "--older-than <duration>",
     "Filter by age (e.g., 30d, 7d, 24h, 60m)"
-  ).option("--dry-run", "Preview without archiving").option("--json", "JSON output").action(bulkArchiveConversations);
+  ).option("--dry-run", "Preview without archiving").option("--json", "JSON output").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Bulk Archive Conversations \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Archive conversations matching filter criteria from a specific inbox.
+  Requires --inbox and at least one filter. Filters are AND-combined.
+  Rate limiting is built in (100-150ms between API calls).
+
+  \u26A0\uFE0F  ALWAYS use --dry-run first to preview what would be archived.
+
+FILTER OPTIONS
+  --sender <email>        Sender email (substring match, case-insensitive)
+  --subject <text>        Subject line (substring match, case-insensitive)
+  --status <status>       Conversation status (unassigned, assigned, archived)
+  --tag <name>            Tag name (substring match, case-insensitive)
+  --older-than <duration> Age filter \u2014 duration format: 30d, 7d, 24h, 60m
+
+  Filters combine with AND: --status unassigned --older-than 30d means
+  conversations that are BOTH unassigned AND older than 30 days.
+
+DRY RUN (preview first!)
+  skill front bulk-archive --inbox inb_4bj7r --sender "mailer-daemon" --dry-run
+
+  Shows matching count + each conversation ID/subject/reason. No changes made.
+
+EXECUTE (after verifying dry run)
+  skill front bulk-archive --inbox inb_4bj7r --sender "mailer-daemon"
+
+PRACTICAL EXAMPLES
+  # Archive all noise from mailer-daemon
+  skill front bulk-archive --inbox inb_4bj7r --sender "mailer-daemon" --dry-run
+  skill front bulk-archive --inbox inb_4bj7r --sender "mailer-daemon"
+
+  # Archive unassigned conversations older than 30 days
+  skill front bulk-archive --inbox inb_4bj7r --status unassigned --older-than 30d --dry-run
+
+  # Archive everything tagged "spam"
+  skill front bulk-archive --inbox inb_4bj7r --tag "spam" --dry-run
+
+  # Archive old daily report emails
+  skill front bulk-archive --inbox inb_4bj7r --subject "Daily Report" --older-than 7d --dry-run
+
+  # List available inboxes (omit --inbox)
+  skill front bulk-archive
+
+JSON OUTPUT (for scripting)
+  skill front bulk-archive --inbox inb_4bj7r --status unassigned --dry-run --json
+
+  # Count matches
+  skill front bulk-archive ... --dry-run --json | jq '.data.matches | length'
+
+  # Extract matched IDs
+  skill front bulk-archive ... --dry-run --json | jq -r '.data.matches[].id'
+
+RELATED COMMANDS
+  skill front triage          Categorize conversations before archiving
+  skill front archive         Archive specific conversations by ID
+  skill front search          Find conversations by query / filters
+`
+  ).action(bulkArchiveConversations);
 }
 
 // src/commands/front/conversation-tag.ts
@@ -92454,21 +92708,17 @@ async function tagConversation(convId, tagNameOrId, options) {
     const tag = await resolveTag(front, tagNameOrId);
     await front.conversations.addTag(normalizedConvId, tag.id);
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "tag-result",
-            command: `skill front tag ${normalizedConvId} ${tagNameOrId} --json`,
-            data: {
-              conversationId: normalizedConvId,
-              tagId: tag.id,
-              tagName: tag.name,
-              action: "added"
-            }
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "tag-result",
+          command: `skill front tag ${normalizedConvId} ${tagNameOrId} --json`,
+          data: {
+            conversationId: normalizedConvId,
+            tagId: tag.id,
+            tagName: tag.name,
+            action: "added"
+          }
+        })
       );
       return;
     }
@@ -92500,21 +92750,17 @@ async function untagConversation(convId, tagNameOrId, options) {
     const tag = await resolveTag(front, tagNameOrId);
     await front.conversations.removeTag(normalizedConvId, tag.id);
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "untag-result",
-            command: `skill front untag ${normalizedConvId} ${tagNameOrId} --json`,
-            data: {
-              conversationId: normalizedConvId,
-              tagId: tag.id,
-              tagName: tag.name,
-              action: "removed"
-            }
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "untag-result",
+          command: `skill front untag ${normalizedConvId} ${tagNameOrId} --json`,
+          data: {
+            conversationId: normalizedConvId,
+            tagId: tag.id,
+            tagName: tag.name,
+            action: "removed"
+          }
+        })
       );
       return;
     }
@@ -92538,8 +92784,87 @@ async function untagConversation(convId, tagNameOrId, options) {
   }
 }
 function registerConversationTagCommands(frontCommand) {
-  frontCommand.command("tag").description("Add a tag to a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("<tag-name-or-id>", "Tag name or ID (tag_xxx)").option("--json", "Output as JSON").action(tagConversation);
-  frontCommand.command("untag").description("Remove a tag from a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("<tag-name-or-id>", "Tag name or ID (tag_xxx)").option("--json", "Output as JSON").action(untagConversation);
+  frontCommand.command("tag").description("Add a tag to a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("<tag-name-or-id>", "Tag name or ID (tag_xxx)").option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag a Conversation \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Add a tag to a conversation. Accepts a tag name OR a tag ID (tag_xxx).
+  Name lookup is case-insensitive \u2014 "Billing", "billing", and "BILLING" all work.
+
+USAGE
+  skill front tag <conversation-id> <tag-name-or-id>
+
+TAG RESOLUTION
+  By name:   skill front tag cnv_abc123 "billing"         # case-insensitive
+  By ID:     skill front tag cnv_abc123 tag_14nmdp        # exact ID
+
+  If the name doesn't match any existing tag, the command errors with a hint
+  to run \`skill front tags list\` to see available tags.
+
+FINDING TAGS
+  skill front tags list                                    # Human-readable list
+  skill front tags list --json | jq '.[].id'               # Just the IDs
+  skill front tags list --json | jq '.[] | {id, name}'     # IDs + names
+
+JSON OUTPUT (--json)
+  Returns a HATEOAS-wrapped object:
+    { type: "tag-result", data: { conversationId, tagId, tagName, action: "added" } }
+
+EXAMPLES
+  # Tag by name
+  skill front tag cnv_abc123 "needs-review"
+
+  # Tag by ID
+  skill front tag cnv_abc123 tag_14nmdp
+
+  # Tag and get JSON output
+  skill front tag cnv_abc123 "billing" --json
+
+RELATED COMMANDS
+  skill front untag <id> <tag>        Remove a tag from a conversation
+  skill front tags list               List all available tags
+  skill front conversation <id>       View conversation details + current tags
+`
+  ).action(tagConversation);
+  frontCommand.command("untag").description("Remove a tag from a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").argument("<tag-name-or-id>", "Tag name or ID (tag_xxx)").option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Untag a Conversation \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Remove a tag from a conversation. Accepts a tag name OR a tag ID (tag_xxx).
+  Name lookup is case-insensitive \u2014 "Billing", "billing", and "BILLING" all work.
+
+USAGE
+  skill front untag <conversation-id> <tag-name-or-id>
+
+TAG RESOLUTION
+  By name:   skill front untag cnv_abc123 "billing"       # case-insensitive
+  By ID:     skill front untag cnv_abc123 tag_14nmdp      # exact ID
+
+  If the name doesn't match any existing tag, the command errors with a hint
+  to run \`skill front tags list\` to see available tags.
+
+JSON OUTPUT (--json)
+  Returns a HATEOAS-wrapped object:
+    { type: "untag-result", data: { conversationId, tagId, tagName, action: "removed" } }
+
+EXAMPLES
+  # Untag by name
+  skill front untag cnv_abc123 "needs-review"
+
+  # Untag by ID
+  skill front untag cnv_abc123 tag_14nmdp
+
+  # Untag and get JSON output
+  skill front untag cnv_abc123 "billing" --json
+
+RELATED COMMANDS
+  skill front tag <id> <tag>          Add a tag to a conversation
+  skill front tags list               List all available tags
+  skill front conversation <id>       View conversation details + current tags
+`
+  ).action(untagConversation);
 }
 
 // src/commands/front/inbox.ts
@@ -92585,19 +92910,15 @@ async function listInboxes(options) {
     const inboxList = await front.inboxes.list();
     const inboxes = inboxList._results ?? [];
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "inbox-list",
-            command: "skill front inbox --json",
-            data: inboxes,
-            links: inboxListLinks(
-              inboxes.map((i) => ({ id: i.id, name: i.name }))
-            )
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "inbox-list",
+          command: "skill front inbox --json",
+          data: inboxes,
+          links: inboxListLinks(
+            inboxes.map((i) => ({ id: i.id, name: i.name }))
+          )
+        })
       );
       return;
     }
@@ -92676,24 +92997,20 @@ async function listConversations(inboxNameOrId, options) {
 `);
     }
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "conversation-list",
-            command: `skill front inbox ${inbox.id} --json`,
-            data: {
-              total: conversations.length,
-              conversations
-            },
-            links: conversationListLinks(
-              conversations.map((c) => ({ id: c.id, subject: c.subject })),
-              inbox.id
-            ),
-            actions: conversationListActions(inbox.id)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "conversation-list",
+          command: `skill front inbox ${inbox.id} --json`,
+          data: {
+            total: conversations.length,
+            conversations
+          },
+          links: conversationListLinks(
+            conversations.map((c) => ({ id: c.id, subject: c.subject })),
+            inbox.id
+          ),
+          actions: conversationListActions(inbox.id)
+        })
       );
       return;
     }
@@ -92748,7 +93065,100 @@ function registerInboxCommand(front) {
   ).option("--json", "Output as JSON").option(
     "--status <status>",
     "Filter by status (unassigned, assigned, archived)"
-  ).option("--tag <tag>", "Filter by tag name").option("--limit <n>", "Limit number of results", "50").action(async (inboxNameOrId, options) => {
+  ).option("--tag <tag>", "Filter by tag name").option("--limit <n>", "Limit number of results", "50").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Front Inbox Command \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Two modes: list all inboxes, or list conversations in a specific inbox.
+
+MODE 1: LIST ALL INBOXES (no argument)
+  skill front inbox                     Show all inboxes (ID, name, privacy)
+  skill front inbox --json              JSON output with HATEOAS links
+
+MODE 2: LIST CONVERSATIONS IN AN INBOX (with argument)
+  skill front inbox <inbox-name-or-id>  List conversations in an inbox
+  skill front inbox inb_4bj7r           By inbox ID
+  skill front inbox "AI Hero"           By name (case-insensitive exact match)
+
+INBOX NAME LOOKUP
+  Pass a human-readable name instead of inb_xxx. The command fetches all
+  inboxes and matches case-insensitively against the full name.
+  Example: "ai hero" matches "AI Hero", "Total TypeScript" matches exactly.
+  If no match is found, an error is thrown with the name you provided.
+
+OPTIONS
+  Flag                    Default   Description
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  --status <status>       (none)    Filter conversations by status
+  --tag <tag>             (none)    Filter by tag name or tag_xxx ID
+  --limit <n>             50        Max conversations to return (pages auto)
+  --json                  false     Output as JSON (HATEOAS envelope)
+
+STATUS VALUES (--status flag)
+  open          In the Open tab (not archived, trashed, or snoozed)
+  archived      In the Archived tab
+  assigned      Has an assignee
+  unassigned    No assignee
+  unreplied     Last message was inbound (no teammate reply yet)
+  snoozed       Snoozed (will reopen later)
+  trashed       In Trash
+  waiting       Waiting for response
+
+TAG FILTER (--tag flag)
+  Filter by tag name (human-readable) or tag ID (tag_xxx).
+  The tag value is passed as a Front query filter: tag:"<value>"
+  Examples:
+    --tag "500 Error"       Filter by tag name
+    --tag tag_14nmdp        Filter by tag ID
+
+PAGINATION
+  Page size is always 50. If --limit is higher than 50, the command
+  automatically paginates through results until the limit is reached.
+  Progress is shown in the terminal (e.g., "Fetched 150 conversations...").
+
+JSON + jq PATTERNS
+  # List all inbox IDs
+  skill front inbox --json | jq '.data[].id'
+
+  # Get inbox names and IDs as a table
+  skill front inbox --json | jq '.data[] | {id, name}'
+
+  # Get conversation IDs from an inbox
+  skill front inbox inb_4bj7r --json | jq '.data.conversations[].id'
+
+  # Get conversation summaries
+  skill front inbox inb_4bj7r --json | jq '.data.conversations[] | {id, subject, status}'
+
+  # Count conversations by status
+  skill front inbox inb_4bj7r --json | jq '[.data.conversations[].status] | group_by(.) | map({status: .[0], count: length})'
+
+EXAMPLES
+  # Step 1: Find inbox IDs
+  skill front inbox
+
+  # Step 2: Look up inbox by name
+  skill front inbox "Total TypeScript"
+
+  # Step 3: Filter unassigned conversations
+  skill front inbox inb_4bj7r --status unassigned
+
+  # Step 4: Filter by tag
+  skill front inbox inb_4bj7r --tag "500 Error"
+
+  # Step 5: Pipe to jq for conversation IDs
+  skill front inbox inb_4bj7r --status open --json | jq '.data.conversations[].id'
+
+  # Limit results to 10
+  skill front inbox inb_4bj7r --limit 10
+
+RELATED COMMANDS
+  skill front conversation <id>    View full conversation with messages
+  skill front search <query>       Search across all inboxes with filters
+  skill front report               Generate support metrics report
+  skill front triage               Triage unassigned conversations
+`
+  ).action(async (inboxNameOrId, options) => {
     if (!inboxNameOrId) {
       await listInboxes(options || {});
     } else {
@@ -92759,7 +93169,7 @@ function registerInboxCommand(front) {
 
 // src/commands/front/pull-conversations.ts
 init_esm_shims();
-import { writeFileSync as writeFileSync8 } from "fs";
+import { writeFileSync as writeFileSync9 } from "fs";
 async function pullConversations(options) {
   const { inbox, limit: limit2 = 50, output, filter: filter4, json = false } = options;
   const frontToken = process.env.FRONT_API_TOKEN;
@@ -92878,20 +93288,16 @@ Built ${samples.length} eval samples`);
       console.log(`  ${cat}: ${count}`);
     }
     if (output) {
-      writeFileSync8(output, JSON.stringify(samples, null, 2));
+      writeFileSync9(output, JSON.stringify(samples, null, 2));
       console.log(`
 Saved to ${output}`);
     } else if (json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "eval-dataset",
-            command: `skill front pull --inbox ${inbox} --json`,
-            data: samples
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "eval-dataset",
+          command: `skill front pull --inbox ${inbox} --json`,
+          data: samples
+        })
       );
     }
   } catch (error) {
@@ -92903,7 +93309,73 @@ Saved to ${output}`);
   }
 }
 function registerPullCommand(parent2) {
-  parent2.command("pull").description("Export conversations to JSON for eval datasets").option("-i, --inbox <id>", "Inbox ID to pull from").option("-l, --limit <n>", "Max conversations to pull", parseInt).option("-o, --output <file>", "Output file path").option("-f, --filter <term>", "Filter by subject/tag containing term").option("--json", "JSON output").action(pullConversations);
+  parent2.command("pull").description("Export conversations to JSON for eval datasets").option("-i, --inbox <id>", "Inbox ID to pull from").option("-l, --limit <n>", "Max conversations to pull", parseInt).option("-o, --output <file>", "Output file path").option("-f, --filter <term>", "Filter by subject/tag containing term").option("--json", "JSON output").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Pull Conversations (Eval Dataset Export) \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Export conversations from a Front inbox as structured EvalSample objects.
+  Designed for building eval datasets for routing, classification, and
+  canned-response testing.
+
+OPTIONS
+  -i, --inbox <id>      Inbox ID to pull from (inb_xxx). Omit to list
+                         available inboxes and their IDs.
+  -l, --limit <n>       Max conversations to export (default: 50)
+  -o, --output <file>   Write output to a file instead of stdout
+  -f, --filter <term>   Only include conversations whose subject or tags
+                         contain this text (case-insensitive)
+  --json                Output as JSON (HATEOAS-wrapped)
+
+OUTPUT FORMAT (EvalSample)
+  Each sample includes:
+  - id / conversationId    Front conversation ID
+  - subject                Conversation subject
+  - customerEmail          Sender email address
+  - status                 Conversation status
+  - tags                   Array of tag names
+  - triggerMessage         Most recent inbound message (id, subject, body, timestamp)
+  - conversationHistory    Full message thread (direction, body, timestamp, author)
+  - category               Inferred category (see below)
+
+CATEGORY INFERENCE
+  Category      Rule
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  refund        Tag or subject contains "refund"
+  access        Tag contains "access" or subject contains "login"/"access"
+  technical     Tag contains "technical" or subject contains "error"/"bug"
+  feedback      Subject contains "feedback" or "suggestion"
+  business      Subject contains "partnership" or "collaborate"
+  general       Everything else (default)
+
+RATE LIMITING
+  Built-in 100ms delay between conversation message fetches to respect
+  Front API limits. Large exports will take time proportional to --limit.
+
+EXAMPLES
+  # List available inboxes (no --inbox flag)
+  skill front pull
+
+  # Pull 50 conversations (default limit)
+  skill front pull --inbox inb_4bj7r
+
+  # Pull 200 conversations and save to file
+  skill front pull --inbox inb_4bj7r --limit 200 --output data/eval-dataset.json
+
+  # Pull only refund-related conversations
+  skill front pull --inbox inb_4bj7r --filter refund --output data/refund-samples.json
+
+  # Pipe JSON for analysis
+  skill front pull --inbox inb_4bj7r --json | jq '[.data[] | {id, category, subject}]'
+
+  # Category breakdown
+  skill front pull --inbox inb_4bj7r --json | jq '[.data[].category] | group_by(.) | map({(.[0]): length}) | add'
+
+RELATED COMMANDS
+  skill eval routing <file>    Run routing eval against a dataset
+  skill front inbox             List inboxes
+`
+  ).action(pullConversations);
 }
 
 // src/commands/front/reply.ts
@@ -92930,16 +93402,12 @@ async function replyToConversation(conversationId, options) {
       }
     );
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "draft-reply",
-            command: `skill front reply ${normalizedId} --body ${JSON.stringify(options.body)}${options.author ? ` --author ${options.author}` : ""} --json`,
-            data: draft
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "draft-reply",
+          command: `skill front reply ${normalizedId} --body ${JSON.stringify(options.body)}${options.author ? ` --author ${options.author}` : ""} --json`,
+          data: draft
+        })
       );
       return;
     }
@@ -92971,7 +93439,62 @@ async function replyToConversation(conversationId, options) {
   }
 }
 function registerReplyCommand(frontCommand) {
-  frontCommand.command("reply").description("Create a draft reply on a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").requiredOption("--body <text>", "Reply body text").option("--author <teammate-id>", "Author teammate ID").option("--json", "Output as JSON").action(replyToConversation);
+  frontCommand.command("reply").description("Create a draft reply on a conversation").argument("<conversation-id>", "Conversation ID (cnv_xxx)").requiredOption("--body <text>", "Reply body text").option("--author <teammate-id>", "Author teammate ID").option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Draft Reply (HITL \u2014 Human-in-the-Loop) \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  \u26A0\uFE0F  SAFETY: This command creates a DRAFT only. It NEVER auto-sends.
+  The draft appears in Front for a human to review, edit, and send manually.
+  This is by design \u2014 the HITL principle ensures no message goes out without
+  human approval.
+
+USAGE
+  skill front reply <conversation-id> --body "Your reply text here"
+
+OPTIONS
+  --body <text>              Required. The reply body text.
+                             Accepts plain text or HTML.
+  --author <teammate-id>     Optional. Teammate ID (tea_xxx) to set as sender.
+                             Defaults to the API token owner.
+  --json                     Output as JSON.
+
+BODY FORMAT
+  Plain text:   --body "Thanks for reaching out. We'll look into this."
+  HTML:         --body "<p>Hi there,</p><p>Your refund has been processed.</p>"
+
+  For multi-line plain text, the body will render as-is in the Front draft.
+
+JSON OUTPUT (--json)
+  Returns a HATEOAS-wrapped object:
+    { type: "draft-reply", data: { id, ... } }
+
+WORKFLOW
+  1. Read the conversation first:
+       skill front conversation cnv_abc123 -m
+  2. Draft a reply:
+       skill front reply cnv_abc123 --body "We've processed your request."
+  3. Open Front \u2192 review the draft \u2192 edit if needed \u2192 click Send.
+
+EXAMPLES
+  # Simple draft reply
+  skill front reply cnv_abc123 --body "Thanks, we're looking into this now."
+
+  # HTML reply with specific author
+  skill front reply cnv_abc123 \\
+    --body "<p>Hi! Your license has been transferred.</p>" \\
+    --author tea_def456
+
+  # Draft reply and capture the draft ID
+  skill front reply cnv_abc123 --body "Processing your refund." --json \\
+    | jq '.data.id'
+
+RELATED COMMANDS
+  skill front conversation <id> -m    View conversation + message history
+  skill front message <id>            View a specific message body
+  skill front search                  Find conversations to reply to
+`
+  ).action(replyToConversation);
 }
 
 // src/commands/front/report.ts
@@ -93074,18 +93597,14 @@ async function generateReport(options) {
     );
     if (json) {
       const unresolvedIds = report.unresolvedIssues.map((i) => i.id);
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "report",
-            command: `skill front report --inbox ${inbox} --json`,
-            data: report,
-            links: reportLinks(inbox, unresolvedIds),
-            actions: reportActions(inbox)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "report",
+          command: `skill front report --inbox ${inbox} --json`,
+          data: report,
+          links: reportLinks(inbox, unresolvedIds),
+          actions: reportActions(inbox)
+        })
       );
     } else {
       printReport(report);
@@ -93176,7 +93695,64 @@ function registerReportCommand(front) {
     "Number of days to include in report",
     parseInt,
     30
-  ).option("--json", "Output as JSON").action(generateReport);
+  ).option("--json", "Output as JSON").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Inbox Forensics Report \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Generates a comprehensive report for a Front inbox covering the last N days.
+  --inbox is required. --days defaults to 30.
+
+WHAT THE REPORT INCLUDES
+  - Overview: total conversations, status breakdown with percentages
+  - Volume by week: bar chart of conversation volume per ISO week
+  - Tag breakdown: top 15 tags by frequency
+  - Top senders: top 10 sender email addresses
+  - Unresolved issues: unassigned conversations (newest first, up to 10 shown)
+
+BASIC USAGE
+  skill front report --inbox inb_4bj7r
+  skill front report --inbox inb_4bj7r --days 60
+  skill front report --inbox inb_4bj7r --days 7
+
+JSON OUTPUT (for scripting)
+  skill front report --inbox inb_4bj7r --json
+
+  # Extract unresolved issues
+  skill front report --inbox inb_4bj7r --json | jq '.data.unresolvedIssues'
+
+  # Top senders
+  skill front report --inbox inb_4bj7r --json | jq '.data.topSenders'
+
+  # Volume by week
+  skill front report --inbox inb_4bj7r --json | jq '.data.volumeByWeek'
+
+  # Status breakdown
+  skill front report --inbox inb_4bj7r --json | jq '.data.overview.byStatus'
+
+  # Count of unassigned conversations
+  skill front report --inbox inb_4bj7r --json | jq '.data.unresolvedIssues | length'
+
+  # Senders with more than 5 conversations
+  skill front report --inbox inb_4bj7r --json \\
+    | jq '[.data.topSenders[] | select(.count > 5)]'
+
+WORKFLOW: REPORT \u2192 TRIAGE \u2192 ARCHIVE
+  # 1. Run report to understand inbox state
+  skill front report --inbox inb_4bj7r
+
+  # 2. Triage to categorize conversations
+  skill front triage --inbox inb_4bj7r
+
+  # 3. Bulk archive the noise
+  skill front bulk-archive --inbox inb_4bj7r --sender "noreply@" --dry-run
+
+RELATED COMMANDS
+  skill front triage          Categorize conversations by intent
+  skill front inbox           List and inspect inboxes
+  skill front bulk-archive    Archive conversations matching filters
+`
+  ).action(generateReport);
 }
 
 // src/commands/front/search.ts
@@ -93235,24 +93811,20 @@ async function searchConversations(query, options) {
       console.log("");
     }
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "search-results",
-            command: `skill front search ${JSON.stringify(fullQuery)} --json`,
-            data: {
-              query: fullQuery,
-              total: conversations.length,
-              conversations
-            },
-            links: conversationListLinks(
-              conversations.map((c) => ({ id: c.id, subject: c.subject }))
-            ),
-            actions: options.inbox ? conversationListActions(options.inbox) : []
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "search-results",
+          command: `skill front search ${JSON.stringify(fullQuery)} --json`,
+          data: {
+            query: fullQuery,
+            total: conversations.length,
+            conversations
+          },
+          links: conversationListLinks(
+            conversations.map((c) => ({ id: c.id, subject: c.subject }))
+          ),
+          actions: options.inbox ? conversationListActions(options.inbox) : []
+        })
       );
       return;
     }
@@ -93382,6 +93954,17 @@ EXAMPLES
   # Pipe JSON to jq for IDs only
   skill front search "is:unassigned" --inbox inb_4bj7r --json | jq '.data.conversations[].id'
 
+LARGE RESULTS
+  When --json output exceeds 64KB (common with 25+ conversations), results are
+  automatically written to a temp file. Stdout gets a summary with the file path:
+    { "_file": "/tmp/skill-front/1738692000.json", "total": 50, ... }
+
+  To always get the full file:
+    skill front search "..." --json > results.json
+
+  To process the spilled file:
+    cat /tmp/skill-front/*.json | jq '.data.conversations[].id'
+
   Full docs: https://dev.frontapp.com/docs/search-1
 `
   ).action((query, options) => {
@@ -93521,20 +94104,16 @@ async function listTags(options) {
     );
     const filteredTags = options.unused ? tagsWithCounts.filter((t2) => t2.conversation_count === 0) : tagsWithCounts;
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "tag-list",
-            command: `skill front tags list${options.unused ? " --unused" : ""} --json`,
-            data: filteredTags,
-            links: tagListLinks(
-              filteredTags.map((t2) => ({ id: t2.id, name: t2.name }))
-            ),
-            actions: tagListActions()
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "tag-list",
+          command: `skill front tags list${options.unused ? " --unused" : ""} --json`,
+          data: filteredTags,
+          links: tagListLinks(
+            filteredTags.map((t2) => ({ id: t2.id, name: t2.name }))
+          ),
+          actions: tagListActions()
+        })
       );
       return;
     }
@@ -93940,13 +94519,146 @@ async function cleanupTags(options) {
   }
 }
 function registerTagCommands(frontCommand) {
-  const tags = frontCommand.command("tags").description("List, rename, delete, and clean up Front tags");
-  tags.command("list").description("List all tags with conversation counts").option("--json", "Output as JSON").option("--unused", "Show only tags with 0 conversations").action(listTags);
-  tags.command("delete").description("Delete a tag by ID").argument("<id>", "Tag ID (e.g., tag_xxx)").option("-f, --force", "Skip confirmation prompt").action(deleteTag);
-  tags.command("rename").description("Rename a tag").argument("<id>", "Tag ID (e.g., tag_xxx)").argument("<name>", "New tag name").action(renameTag);
+  const tags = frontCommand.command("tags").description("List, rename, delete, and clean up Front tags").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag Management \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Manage Front tags: list with usage counts, delete unused, rename,
+  and bulk-clean duplicates / case variants / obsolete tags.
+
+SUBCOMMANDS
+  list      List all tags with conversation counts (--unused, --json)
+  delete    Delete a tag by ID (tag_xxx)
+  rename    Rename a tag (tag_xxx \u2192 new name)
+  cleanup   Find and fix duplicate, case-variant, and obsolete tags
+
+EXAMPLES
+  skill front tags list
+  skill front tags list --unused --json
+  skill front tags delete tag_abc123 --force
+  skill front tags rename tag_abc123 "billing-issue"
+  skill front tags cleanup
+  skill front tags cleanup --execute
+
+RELATED COMMANDS
+  skill front tag <cnv_xxx> <tag_xxx>       Apply a tag to a conversation
+  skill front untag <cnv_xxx> <tag_xxx>     Remove a tag from a conversation
+`
+  );
+  tags.command("list").description("List all tags with conversation counts").option("--json", "Output as JSON").option("--unused", "Show only tags with 0 conversations").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag List \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Lists every tag in the Front workspace with its conversation count.
+  Conversation counts are fetched per-tag (rate-limited, ~5 concurrent).
+
+OPTIONS
+  --unused    Show only tags with 0 conversations (candidates for deletion)
+  --json      Output as JSON (HATEOAS-wrapped with links and actions)
+
+OUTPUT COLUMNS (table mode)
+  ID          Tag ID (tag_xxx)
+  Name        Tag display name
+  Color       Highlight color
+  Convos      Number of conversations using this tag (0 shows warning)
+
+JSON + jq PATTERNS
+  # All unused tags
+  skill front tags list --json | jq '.data[] | select(.conversation_count == 0)'
+
+  # Tag names only
+  skill front tags list --json | jq '.data[].name'
+
+  # Tags sorted by usage (most \u2192 least)
+  skill front tags list --json | jq '.data | sort_by(-.conversation_count)'
+
+  # Count of unused tags
+  skill front tags list --json | jq '[.data[] | select(.conversation_count == 0)] | length'
+
+NOTE
+  Fetching counts for many tags can take a while due to Front API rate limits.
+  The command batches requests (5 at a time, 100ms between batches).
+`
+  ).action(listTags);
+  tags.command("delete").description("Delete a tag by ID").argument("<id>", "Tag ID (e.g., tag_xxx)").option("-f, --force", "Skip confirmation prompt").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag Delete \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Delete a single tag by its Front ID.
+
+ARGUMENTS
+  <id>    Tag ID in tag_xxx format (find IDs via: skill front tags list --json)
+
+OPTIONS
+  -f, --force    Skip the confirmation prompt (use in scripts)
+
+BEHAVIOR
+  - Shows tag name, ID, and conversation count before prompting
+  - Warns if the tag is still applied to conversations
+  - Deleting a tag removes it from all conversations that use it
+  - This action is irreversible
+
+EXAMPLES
+  skill front tags delete tag_abc123
+  skill front tags delete tag_abc123 --force
+`
+  ).action(deleteTag);
+  tags.command("rename").description("Rename a tag").argument("<id>", "Tag ID (e.g., tag_xxx)").argument("<name>", "New tag name").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag Rename \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Rename a tag. The tag keeps its ID and stays applied to all conversations.
+
+ARGUMENTS
+  <id>      Tag ID in tag_xxx format
+  <name>    New display name for the tag
+
+EXAMPLES
+  skill front tags rename tag_abc123 "billing-issue"
+  skill front tags rename tag_abc123 "refund-request"
+
+NOTE
+  If a tag with the new name already exists, the API will return an error.
+  Use "skill front tags cleanup" to merge duplicates and case variants.
+`
+  ).action(renameTag);
   tags.command("cleanup").description(
     "Clean up tags: delete duplicates, merge case variants, remove obsolete, create missing standard tags"
-  ).option("--execute", "Actually apply changes (default is dry-run)", false).action(cleanupTags);
+  ).option("--execute", "Actually apply changes (default is dry-run)", false).addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Tag Cleanup \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Analyze all tags for issues and optionally fix them. Default is dry-run.
+
+WHAT IT FINDS
+  - Exact duplicates (same name, multiple tag IDs)
+  - Case variants ("Refund" vs "refund" vs "REFUND")
+  - Obsolete tags (date-based like "jan-2022", Gmail imports like "INBOX")
+  - Missing standard tags from the category registry
+
+WHAT IT DOES (with --execute)
+  - Deletes duplicate tags (keeps the one with most conversations)
+  - Renames case variants to canonical lowercase-hyphenated form
+  - Deletes obsolete/imported tags
+  - Creates missing standard category tags
+
+OPTIONS
+  --execute    Apply the cleanup plan. Without this flag, only a dry-run
+               report is printed (safe to run anytime).
+
+EXAMPLES
+  # See what would be changed (safe, read-only)
+  skill front tags cleanup
+
+  # Actually apply changes (prompts for confirmation)
+  skill front tags cleanup --execute
+`
+  ).action(cleanupTags);
 }
 
 // src/commands/front/triage.ts
@@ -94045,21 +94757,17 @@ Fetching ${status} conversations from inbox ${inbox}...`);
       });
     }
     if (json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "triage-result",
-            command: `skill front triage --inbox ${inbox} --json`,
-            data: {
-              total: allConversations.length,
-              stats: stats4,
-              results
-            },
-            actions: triageActions(inbox)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "triage-result",
+          command: `skill front triage --inbox ${inbox} --json`,
+          data: {
+            total: allConversations.length,
+            stats: stats4,
+            results
+          },
+          actions: triageActions(inbox)
+        })
       );
       return;
     }
@@ -94169,7 +94877,72 @@ function registerTriageCommand(front) {
     "-s, --status <status>",
     "Conversation status filter (unassigned, assigned, archived)",
     "unassigned"
-  ).option("--auto-archive", "Automatically archive noise and spam").option("--json", "JSON output").action(triageConversations);
+  ).option("--auto-archive", "Automatically archive noise and spam").option("--json", "JSON output").addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 AI-Powered Triage \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Categorize inbox conversations into actionable, noise, or spam using
+  heuristic rules. Optionally auto-archive the junk.
+
+OPTIONS
+  -i, --inbox <id>       (required) Inbox ID to triage (inb_xxx)
+  -s, --status <status>  Conversation status to filter (default: unassigned)
+                         Values: unassigned, assigned, archived
+  --auto-archive         Archive all noise + spam conversations automatically
+  --json                 Output as JSON (HATEOAS-wrapped)
+
+CATEGORIZATION RULES
+  Category      Signals
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  Noise         mailer-daemon, noreply, no-reply, postmaster, newsletter
+                delivery failures, auto-replies, out-of-office,
+                automated reports (daily/weekly/monthly), cert notifications
+  Spam          partnership/sponsorship pitches, guest post / link exchange,
+                backlink requests, marketing opportunities
+  Actionable    Everything else (real support issues)
+
+WORKFLOW
+  1. Triage to see the breakdown:
+     skill front triage --inbox inb_4bj7r
+
+  2. Review categories in the output (actionable / noise / spam)
+
+  3. If satisfied, auto-archive the junk:
+     skill front triage --inbox inb_4bj7r --auto-archive
+
+JSON + jq PATTERNS
+  # Just the stats
+  skill front triage --inbox inb_4bj7r --json | jq '.data.stats'
+
+  # All noise conversation IDs
+  skill front triage --inbox inb_4bj7r --json | jq '[.data.results[] | select(.category == "noise") | .id]'
+
+  # Spam sender emails
+  skill front triage --inbox inb_4bj7r --json | jq '[.data.results[] | select(.category == "spam") | .senderEmail]'
+
+  # Actionable count
+  skill front triage --inbox inb_4bj7r --json | jq '.data.stats.actionable'
+
+EXAMPLES
+  # Triage unassigned conversations (default)
+  skill front triage --inbox inb_4bj7r
+
+  # Triage assigned conversations
+  skill front triage --inbox inb_4bj7r --status assigned
+
+  # Triage and auto-archive noise + spam
+  skill front triage --inbox inb_4bj7r --auto-archive
+
+  # Pipe JSON for downstream processing
+  skill front triage --inbox inb_4bj7r --json | jq '.data.results[] | select(.category == "actionable")'
+
+RELATED COMMANDS
+  skill front bulk-archive    Bulk-archive conversations by query
+  skill front report          Inbox activity report
+  skill front search          Search conversations with filters
+`
+  ).action(triageConversations);
 }
 
 // src/commands/front/index.ts
@@ -94207,17 +94980,13 @@ async function getMessage(id, options) {
     const front = getFrontClient9();
     const message = await front.messages.get(normalizeId6(id));
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "message",
-            command: `skill front message ${normalizeId6(id)} --json`,
-            data: message,
-            links: messageLinks(message.id)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "message",
+          command: `skill front message ${normalizeId6(id)} --json`,
+          data: message,
+          links: messageLinks(message.id)
+        })
       );
       return;
     }
@@ -94276,18 +95045,14 @@ async function getConversation2(id, options) {
     }
     if (options.json) {
       const convId = normalizeId6(id);
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "conversation",
-            command: `skill front conversation ${convId} --json`,
-            data: { conversation, messages },
-            links: conversationLinks(conversation.id),
-            actions: conversationActions(conversation.id)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "conversation",
+          command: `skill front conversation ${convId} --json`,
+          data: { conversation, messages },
+          links: conversationLinks(conversation.id),
+          actions: conversationActions(conversation.id)
+        })
       );
       return;
     }
@@ -94345,19 +95110,15 @@ async function listTeammates(options) {
     const front = getFrontSdkClient2();
     const result = await front.teammates.list();
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "teammate-list",
-            command: "skill front teammates --json",
-            data: result._results,
-            links: teammateListLinks(
-              result._results.map((t2) => ({ id: t2.id, email: t2.email }))
-            )
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "teammate-list",
+          command: "skill front teammates --json",
+          data: result._results,
+          links: teammateListLinks(
+            result._results.map((t2) => ({ id: t2.id, email: t2.email }))
+          )
+        })
       );
       return;
     }
@@ -94398,17 +95159,13 @@ async function getTeammate(id, options) {
     const front = getFrontSdkClient2();
     const teammate = await front.teammates.get(id);
     if (options.json) {
-      console.log(
-        JSON.stringify(
-          hateoasWrap({
-            type: "teammate",
-            command: `skill front teammate ${id} --json`,
-            data: teammate,
-            links: teammateLinks(teammate.id)
-          }),
-          null,
-          2
-        )
+      writeJsonOutput(
+        hateoasWrap({
+          type: "teammate",
+          command: `skill front teammate ${id} --json`,
+          data: teammate,
+          links: teammateLinks(teammate.id)
+        })
       );
       return;
     }
@@ -94443,10 +95200,245 @@ async function getTeammate(id, options) {
 }
 function registerFrontCommands(program3) {
   const front = program3.command("front").description("Front conversations, inboxes, tags, archival, and reporting");
-  front.command("message").description("Get a message by ID (body, author, recipients, attachments)").argument("<id>", "Message ID (e.g., msg_xxx)").option("--json", "Output as JSON").action(getMessage);
-  front.command("conversation").description("Get a conversation by ID (status, tags, assignee, messages)").argument("<id>", "Conversation ID (e.g., cnv_xxx)").option("--json", "Output as JSON").option("-m, --messages", "Include message history").action(getConversation2);
-  front.command("teammates").description("List all teammates in the workspace").option("--json", "Output as JSON").action(listTeammates);
-  front.command("teammate").description("Get teammate details by ID").argument("<id>", "Teammate ID (e.g., tea_xxx or username)").option("--json", "Output as JSON").action(getTeammate);
+  const messageCmd = front.command("message").description("Get a message by ID (body, author, recipients, attachments)").argument("<id>", "Message ID (e.g., msg_xxx)").option("--json", "Output as JSON").action(getMessage);
+  messageCmd.addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Message Details \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Fetches a single message from Front by its ID. Returns the full message
+  including HTML body, plaintext body, author, recipients, attachments,
+  and metadata.
+
+ID FORMAT
+  msg_xxx     Front message ID (prefixed with msg_)
+              You can find message IDs from conversation message lists.
+
+WHAT'S RETURNED
+  Field        Description
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  id           Message ID (msg_xxx)
+  type         Message type (email, sms, custom, etc.)
+  subject      Message subject line
+  body         Full HTML body
+  text         Plaintext body (stripped HTML)
+  author       Author object (email, id) \u2014 teammate or contact
+  recipients   Array of {role, handle} \u2014 from/to/cc/bcc
+  attachments  Array of {filename, content_type, size, url}
+  created_at   Unix timestamp of message creation
+  metadata     Headers, external references
+
+JSON + jq PATTERNS
+  # Get the HTML body
+  skill front message msg_xxx --json | jq '.data.body'
+
+  # Get the plaintext body
+  skill front message msg_xxx --json | jq '.data.text'
+
+  # Get the author email
+  skill front message msg_xxx --json | jq '.data.author.email'
+
+  # List all recipients
+  skill front message msg_xxx --json | jq '.data.recipients[] | {role, handle}'
+
+  # List attachment filenames
+  skill front message msg_xxx --json | jq '.data.attachments[].filename'
+
+RELATED COMMANDS
+  skill front conversation <id> -m   Find message IDs from a conversation
+  skill front search <query>         Search conversations to find threads
+
+EXAMPLES
+  # Get full message details (human-readable)
+  skill front message msg_1a2b3c
+
+  # Get message as JSON for piping
+  skill front message msg_1a2b3c --json
+
+  # Extract just the body text
+  skill front message msg_1a2b3c --json | jq -r '.data.text'
+
+  # Check who sent a message
+  skill front message msg_1a2b3c --json | jq '{author: .data.author.email, recipients: [.data.recipients[].handle]}'
+`
+  );
+  const conversationCmd = front.command("conversation").description("Get a conversation by ID (status, tags, assignee, messages)").argument("<id>", "Conversation ID (e.g., cnv_xxx)").option("--json", "Output as JSON").option("-m, --messages", "Include message history").action(getConversation2);
+  conversationCmd.addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Conversation Details \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Fetches a conversation from Front by its ID. Returns metadata, tags,
+  assignee, recipient, and optionally the full message history.
+
+ID FORMAT
+  cnv_xxx     Front conversation ID (prefixed with cnv_)
+              Find conversation IDs via search or inbox listing.
+
+FLAGS
+  -m, --messages    Include full message history in the response.
+                    Without this flag, only conversation metadata is returned.
+
+WHAT'S RETURNED
+  Field        Description
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  id           Conversation ID (cnv_xxx)
+  subject      Conversation subject line
+  status       Current status (see below)
+  created_at   Unix timestamp
+  recipient    Primary recipient {handle, role}
+  assignee     Assigned teammate {id, email} or null
+  tags         Array of {id, name} tags on this conversation
+  messages     (with -m) Array of full message objects
+
+STATUS VALUES
+  archived     Conversation is archived
+  unassigned   Open, no assignee
+  assigned     Open, has an assignee
+  deleted      In trash
+  waiting      Waiting for response
+
+JSON + jq PATTERNS
+  # Get conversation metadata
+  skill front conversation cnv_xxx --json | jq '.data.conversation'
+
+  # Get all messages (requires -m flag)
+  skill front conversation cnv_xxx -m --json | jq '.data.messages[]'
+
+  # Get just message bodies as plaintext
+  skill front conversation cnv_xxx -m --json | jq -r '.data.messages[].text'
+
+  # Extract tag names
+  skill front conversation cnv_xxx --json | jq '[.data.conversation.tags[].name]'
+
+  # Get assignee email
+  skill front conversation cnv_xxx --json | jq '.data.conversation.assignee.email'
+
+  # Get message count
+  skill front conversation cnv_xxx -m --json | jq '.data.messages | length'
+
+  # Get inbound messages only
+  skill front conversation cnv_xxx -m --json | jq '[.data.messages[] | select(.is_inbound)]'
+
+RELATED COMMANDS
+  skill front message <id>           Get full details for a specific message
+  skill front assign <cnv> <tea>     Assign conversation to a teammate
+  skill front tag <cnv> <tag>        Add a tag to a conversation
+  skill front reply <cnv>            Send a reply to a conversation
+  skill front search <query>         Search for conversations
+
+EXAMPLES
+  # Get conversation overview
+  skill front conversation cnv_abc123
+
+  # Get conversation with full message history
+  skill front conversation cnv_abc123 -m
+
+  # Pipe to jq to extract tags and assignee
+  skill front conversation cnv_abc123 --json | jq '{tags: [.data.conversation.tags[].name], assignee: .data.conversation.assignee.email}'
+
+  # Get the latest message text from a conversation
+  skill front conversation cnv_abc123 -m --json | jq -r '.data.messages[-1].text'
+`
+  );
+  const teammatesCmd = front.command("teammates").description("List all teammates in the workspace").option("--json", "Output as JSON").action(listTeammates);
+  teammatesCmd.addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 List Teammates \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Lists all teammates in the Front workspace. Returns each teammate's ID,
+  email, name, username, and availability status.
+
+WHAT'S RETURNED (per teammate)
+  Field          Description
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  id             Teammate ID (tea_xxx)
+  email          Teammate email address
+  first_name     First name
+  last_name      Last name
+  username       Front username
+  is_available   Whether teammate is currently available (true/false)
+
+JSON + jq PATTERNS
+  # Get all teammate IDs
+  skill front teammates --json | jq '[.data[].id]'
+
+  # Get ID + email pairs
+  skill front teammates --json | jq '.data[] | {id, email}'
+
+  # Find a teammate by email
+  skill front teammates --json | jq '.data[] | select(.email == "joel@example.com")'
+
+  # List only available teammates
+  skill front teammates --json | jq '[.data[] | select(.is_available)]'
+
+  # Get a count of teammates
+  skill front teammates --json | jq '.data | length'
+
+RELATED COMMANDS
+  skill front teammate <id>          Get details for a specific teammate
+  skill front assign <cnv> <tea>     Assign a conversation to a teammate
+
+EXAMPLES
+  # List all teammates (human-readable table)
+  skill front teammates
+
+  # List as JSON for scripting
+  skill front teammates --json
+
+  # Find teammate ID by email for use in assign
+  skill front teammates --json | jq -r '.data[] | select(.email | contains("joel")) | .id'
+`
+  );
+  const teammateCmd = front.command("teammate").description("Get teammate details by ID").argument("<id>", "Teammate ID (e.g., tea_xxx or username)").option("--json", "Output as JSON").action(getTeammate);
+  teammateCmd.addHelpText(
+    "after",
+    `
+\u2501\u2501\u2501 Teammate Details \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  Fetches details for a single teammate by their ID. Returns email, name,
+  username, and current availability.
+
+ID FORMAT
+  tea_xxx     Front teammate ID (prefixed with tea_)
+              Find teammate IDs via: skill front teammates
+
+WHAT'S RETURNED
+  Field          Description
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  id             Teammate ID (tea_xxx)
+  email          Teammate email address
+  first_name     First name
+  last_name      Last name
+  username       Front username
+  is_available   Whether teammate is currently available (true/false)
+
+JSON + jq PATTERNS
+  # Get teammate email
+  skill front teammate tea_xxx --json | jq '.data.email'
+
+  # Get full name
+  skill front teammate tea_xxx --json | jq '(.data.first_name + " " + .data.last_name)'
+
+  # Check availability
+  skill front teammate tea_xxx --json | jq '.data.is_available'
+
+RELATED COMMANDS
+  skill front teammates              List all teammates (to find IDs)
+  skill front assign <cnv> <tea>     Assign a conversation to this teammate
+
+EXAMPLES
+  # Get teammate details (human-readable)
+  skill front teammate tea_1a2b3c
+
+  # Get as JSON
+  skill front teammate tea_1a2b3c --json
+
+  # Quick check if teammate is available
+  skill front teammate tea_1a2b3c --json | jq -r 'if .data.is_available then "available" else "away" end'
+`
+  );
   registerInboxCommand(front);
   registerArchiveCommand(front);
   registerBulkArchiveCommand(front);
@@ -112631,7 +113623,7 @@ Total: ${result.totalDurationMs}ms`);
 
 // src/commands/responses.ts
 init_esm_shims();
-import { writeFileSync as writeFileSync9 } from "fs";
+import { writeFileSync as writeFileSync10 } from "fs";
 function formatDate3(date) {
   return date.toLocaleString("en-US", {
     month: "short",
@@ -113132,7 +114124,7 @@ async function exportResponses(options) {
     }
     const outputJson = JSON.stringify(exportData, null, 2);
     if (options.output) {
-      writeFileSync9(options.output, outputJson, "utf-8");
+      writeFileSync10(options.output, outputJson, "utf-8");
       console.log(
         `Exported ${exportData.length} responses to ${options.output}`
       );