@skillrecordings/cli 0.8.0 → 0.10.0

package/dist/index.js

@@ -91720,7 +91720,85 @@ 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);
@@ -92059,7 +92137,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
@@ -92128,7 +92246,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
@@ -92415,7 +92584,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
@@ -92538,8 +92767,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
@@ -92748,7 +93056,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 {
@@ -92903,7 +93304,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
@@ -92971,7 +93438,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
@@ -93176,7 +93698,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
@@ -93297,10 +93876,10 @@ async function searchConversations(query, options) {
   }
 }
 function registerSearchCommand(frontCommand) {
-  frontCommand.command("search").description(
+  const searchCmd = frontCommand.command("search").description(
     "Search conversations (text, subject, filters). See https://dev.frontapp.com/docs/search-1"
   ).argument(
-    "<query>",
+    "[query]",
     'Search query (text, "exact phrase", or filter syntax)'
   ).option("--inbox <id>", "Filter by inbox ID (inb_xxx)").option("--tag <id>", "Filter by tag ID (tag_xxx)").option("--assignee <id>", "Filter by assignee (tea_xxx)").option(
     "--status <status>",
@@ -93308,31 +93887,90 @@ function registerSearchCommand(frontCommand) {
   ).option("--from <email>", "Filter by sender email").option("--after <timestamp>", "Filter after Unix timestamp").option("--before <timestamp>", "Filter before Unix timestamp").option("--limit <n>", "Max results (default 25)", "25").option("--json", "Output as JSON").addHelpText(
     "after",
     `
-Front Search Query Syntax:
-  Text search:    "exact phrase" or word1 word2 (AND logic)
-  inbox:inb_xxx   Filter by inbox
-  tag:tag_xxx     Filter by tag
-  from:email      Filter by sender
-  to:email        Filter by recipient
-  recipient:email Filter by email/handle
-  assignee:tea_x  Filter by assigned teammate
-  participant:t   Filter by participating teammate
-  is:open         Status: open, archived, assigned, unassigned,
-                  unreplied, snoozed, resolved, waiting
-  before:<ts>     Before Unix timestamp
-  after:<ts>      After Unix timestamp
-  during:<ts>     During day of Unix timestamp
-  custom_field:"Name=value"
-
-  Multiple filters = AND. Multiple from/to/cc/bcc = OR. Max 15 filters.
-
-Examples:
-  skill front search "payment failed" --inbox inb_4bj7r
-  skill front search "upgrade" --status unassigned --from user@example.com
-  skill front search "from:dale@a.com tag:tag_14nmdp" --limit 50
-  skill front search "is:unreplied" --inbox inb_4bj7r --after 1706745600
+\u2501\u2501\u2501 Front Search Query Syntax \u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
+
+  The <query> argument accepts free text and/or inline Front filters.
+  CLI flags (--inbox, --status, etc.) are appended as filters automatically.
+  You can mix both: skill front search "refund" --inbox inb_4bj7r --status open
+
+TEXT SEARCH
+  word1 word2             AND \u2014 both words must appear in subject or body
+  "exact phrase"          Phrase match (quote the phrase)
+
+FILTERS (use inline in query OR via CLI flags)
+  Filter              CLI flag              What it matches
+  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  inbox:inb_xxx       --inbox <id>          Conversations in inbox
+  tag:tag_xxx         --tag <id>            Conversations with tag
+  from:email          --from <email>        Sender address
+  to:email            (inline only)         Recipient address
+  cc:email            (inline only)         CC'd address
+  bcc:email           (inline only)         BCC'd address
+  recipient:email     (inline only)         Any role (from/to/cc/bcc)
+  contact:crd_xxx     (inline only)         Contact ID in any role
+  assignee:tea_xxx    --assignee <id>       Assigned teammate
+  author:tea_xxx      (inline only)         Message author (teammate)
+  participant:tea_xxx (inline only)         Any teammate involvement
+  mention:tea_xxx     (inline only)         Mentioned teammate
+  commenter:tea_xxx   (inline only)         Commenting teammate
+  link:top_xxx        (inline only)         Linked topic
+  is:<status>         --status <status>     Conversation status (see below)
+  before:<unix_ts>    --before <timestamp>  Messages before timestamp
+  after:<unix_ts>     --after <timestamp>   Messages after timestamp
+  during:<unix_ts>    (inline only)         Messages on same day as timestamp
+  custom_field:"K=V"  (inline only)         Custom field value
+
+STATUS VALUES (is: filter / --status flag)
+  open         In the Open tab (not archived, not trashed, not snoozed)
+  archived     In the Archived tab
+  assigned     Has an assignee (can combine: is:open is:assigned)
+  unassigned   No assignee
+  unreplied    Last message was inbound (no teammate reply yet)
+  snoozed      Snoozed (will reopen later; API status shows "archived")
+  trashed      In Trash
+  waiting      Waiting for response
+
+  Status combos:  is:open + is:unassigned = open & unassigned
+                  is:archived + is:assigned = archived & assigned
+  Conflicts:      open vs archived vs trashed vs snoozed are mutually exclusive
+                  assigned vs unassigned are mutually exclusive
+
+FILTER LOGIC
+  All filters combine with AND (results must match every filter).
+  Exception: multiple from/to/cc/bcc use OR within the same filter type.
+    from:a@x.com from:b@x.com   \u2192  from A OR from B
+    from:a@x.com to:b@x.com     \u2192  from A AND to B
+  Max 15 filters per query.
+
+EXAMPLES
+  # Find unresolved payment issues in AI Hero inbox
+  skill front search "payment failed" --inbox inb_4bj7r --status unassigned
+
+  # Unreplied conversations from a specific sender
+  skill front search "upgrade" --from user@example.com --status unreplied
+
+  # Complex inline query (filters in the query string itself)
+  skill front search "from:dale@a.com from:laura@a.com tag:tag_14nmdp before:1650364200"
+
+  # All snoozed conversations assigned to a teammate
+  skill front search "is:snoozed assignee:tea_2thf" --inbox inb_4bj7r
+
+  # Search by custom field
+  skill front search 'custom_field:"External ID=12345"'
+
+  # Pipe JSON to jq for IDs only
+  skill front search "is:unassigned" --inbox inb_4bj7r --json | jq '.data.conversations[].id'
+
+  Full docs: https://dev.frontapp.com/docs/search-1
 `
-  ).action(searchConversations);
+  ).action((query, options) => {
+    const hasFilters = options.inbox || options.tag || options.assignee || options.status || options.from || options.after || options.before;
+    if (!query && !hasFilters) {
+      searchCmd.help();
+      return;
+    }
+    return searchConversations(query || "", options);
+  });
 }
 
 // src/commands/front/tags.ts
@@ -93881,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
@@ -94110,7 +94881,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
@@ -94384,10 +95220,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);