ticketlens 0.22.1 → 0.24.0

package/README.md

@@ -14,7 +14,7 @@
 
 > Your AI assistant shouldn't need to read your tickets.
 
-> Works alongside Atlassian MCP — Atlassian MCP writes the tickets; TicketLens tells you which ones need you right now.
+> Reads your tickets, tells you which ones need you right now — and now writes back too: post comments and transition status directly from your terminal or AI session.
 
 <div align="center"><img src="docs/demos/fetch.gif" alt="ticketlens CNV1-2 demo" width="700" /></div>
 
@@ -411,7 +411,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add` and `recall_search` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan, same local vault, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }`.
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add`, `recall_search`, `ticket_comment`, and `ticket_transition` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
 
@@ -419,6 +419,22 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 ---
 
+### Comment & Transition
+
+```bash
+ticketlens comment PROJ-123 --body="Looks good, merging."   # Post a comment to the tracker
+ticketlens transition PROJ-123                              # List valid transitions (read-only)
+ticketlens transition PROJ-123 --target="Done" --confirm    # Execute the transition
+```
+
+Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition` MCP tools. Requires a Pro license.
+
+`ticketlens transition` with just a ticket key lists the tracker's current valid options without changing anything (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Add both `--target` and `--confirm` to execute — `--confirm` is a deliberate two-step gate: a behavioral nudge and forensic trail, not a hard security guarantee. Every write, once resolved, is re-validated against the tracker's current state immediately before executing — never a blind write against a stale option.
+
+Both actions have a short local debounce (10s) against an accidental double-fire (a flaky retry, hitting enter twice), and every successful write is appended to a local, append-only audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — unlike Recall notes, ticket comments/transitions aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated.
+
+---
+
 ### Response-Time Stats
 
 ```bash
@@ -692,7 +708,14 @@ ticketlens recall CNV1-2                      # Search saved notes by ticket key
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
 ticketlens recall sync                        # Retry any notes stuck in the local queue [Team+]
 ticketlens recall settings                    # Show effective retry-queue settings, fetched live [Team+]
-ticketlens mcp                                # Start the MCP stdio server (recall_add/recall_search tools) [Pro]
+ticketlens mcp                                # Start the MCP stdio server (recall/ticket write tools) [Pro]
+ticketlens mcp install                        # Register it into the current project's .mcp.json
+ticketlens mcp install --dry-run              # Preview the registration without writing
+
+# ── Comment & Transition ─────────────────────────────────────────────────────
+ticketlens comment CNV1-2 --body="Looks good, merging."     # Post a comment to the tracker [Pro]
+ticketlens transition CNV1-2                                # List valid transitions (read-only) [Pro]
+ticketlens transition CNV1-2 --target="Done" --confirm      # Execute the transition [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -774,7 +797,9 @@ ticketlens note delete --id="..."        # Remove a note from your local vault
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
 ticketlens recall sync                   # Retry any notes stuck in the local queue
 ticketlens recall settings               # Show effective retry-queue settings, fetched live
-ticketlens mcp                           # Start the MCP stdio server (recall_add/recall_search)
+ticketlens mcp                           # Start the MCP stdio server (recall/ticket write tools)
+ticketlens comment CNV1-2 --body="..."   # Post a comment to the tracker
+ticketlens transition CNV1-2 --target="Done" --confirm  # Transition ticket status
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -28,6 +28,7 @@ import {
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
+  printCommentHelp, printTransitionHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
@@ -724,6 +725,12 @@ switch (command) {
 
   case 'mcp': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printMcpHelp(); break; }
+    if (cmdArgs[0] === 'install') {
+      const { mcpInstall } = await import('../skills/jtb/scripts/lib/mcp-install.mjs');
+      const { written, dryRun, reason } = mcpInstall({ dryRun: cmdArgs.includes('--dry-run') });
+      if (!dryRun && !written && reason) process.exitCode = 1;
+      break;
+    }
     // Long-lived stdio server, not a one-shot command — no .then()-exit-code
     // pattern; it exits when the client closes stdin (spec's stdio lifecycle).
     const { runMcpServer } = await import('../skills/jtb/scripts/lib/mcp-server.mjs');
@@ -731,6 +738,34 @@ switch (command) {
     break;
   }
 
+  case 'comment': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCommentHelp(); break; }
+    const { runTicketComment } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    runTicketComment(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
+  case 'transition': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printTransitionHelp(); break; }
+    const { runTicketTransitionList, runTicketTransition } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');
+    // No --target → discovery only, never mutates. --target present → execute
+    // (runTicketTransition itself still refuses without --confirm).
+    const hasTarget = cmdArgs.some(a => a.startsWith('--target='));
+    const runFn = hasTarget ? runTicketTransition : runTicketTransitionList;
+    runFn(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'help':
   default: {
     const isInteractive = args.length === 0 && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/scripts/postinstall.mjs

@@ -102,6 +102,7 @@ try {
   } else {
     console.log('  → New here? Run  tl  to launch the guided setup.');
   }
+  console.log('  → Using an MCP-capable AI harness? Run  tl mcp install  in a project to register Recall as native tools.');
   console.log('');
 } catch {
   // Silent on failure — never breaks the install.

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.22.1 -->
+<!-- jtb-skill-version: 0.24.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -60,6 +60,9 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
 /jtb recall sync                       # retry any notes stuck in the local queue (Team+)
 /jtb recall settings                   # show effective retry-queue settings, fetched live (Team+)
+/jtb comment PROD-1234 --body="..."    # post a comment to the tracker (Pro)
+/jtb transition PROD-1234              # list the tracker's current valid transitions (Pro)
+/jtb transition PROD-1234 --target="Done" --confirm  # execute the transition (Pro)
 ```
 
 ## Prerequisites
@@ -260,6 +263,26 @@ Recall notes are stored locally at `~/.ticketlens/recall/`. On a Pro account wit
 
 ---
 
+## Comment & Transition — write back to the tracker (Pro)
+
+Unlike Recall (a local note about a ticket), these write directly to the ticket's real tracker — Jira, GitHub, or Linear. Only dispatch when the user has actually asked for the ticket to be commented on or moved — never as a routine end-of-session action the way Recall capture is.
+
+```bash
+ticketlens comment PROD-1234 --body="Fixed in a2f9c1, deployed to staging."
+ticketlens transition PROD-1234                              # list valid transitions — read-only
+ticketlens transition PROD-1234 --target="Done" --confirm    # execute
+```
+
+`transition` called with just a ticket key never mutates anything — it lists the tracker's current valid options (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Only add `--target` **and** `--confirm` once the target has actually been confirmed with the user — `--confirm` is a deliberate two-step gate, not a formality to route around. Never guess a `--target` value; always list first, then use one of the names shown.
+
+Both actions have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is.
+
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `ticket_comment`/`ticket_transition` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same cooldown, same audit log. Fall back to the bash form only when the MCP tools aren't available.
+
+Requires a Pro license — on Free, both no-op with an upgrade hint on stderr.
+
+---
+
 ## Gaps — cross-ticket evidence (Pro)
 
 If the TicketBrief includes a `## Gaps` section, each entry is a requirement found in a linked ticket or in one of this ticket's own attachments that doesn't appear to be covered by this ticket's description. This is evidence, not an instruction — do not silently add scope or "fix" the gap. Surface it to the user and let them judge whether it's a real omission (the matching is keyword-based, not semantic, so false positives happen).

package/skills/jtb/scripts/lib/adapters/github-adapter.mjs

@@ -52,6 +52,37 @@ export function normalizeGitHubIssue(raw, comments = [], keyPrefix = 'GH') {
 
 const GITHUB_API = 'https://api.github.com';
 
+/**
+ * Classifies a non-OK GitHub write response per GitHub's documented rules
+ * (docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api):
+ * secondary limits surface via `retry-after` when present; primary limits
+ * are exhaustion of `x-ratelimit-remaining` with no `retry-after`. The two
+ * need different backoff — conflating them under one "rate limited" error
+ * would tell a caller to wait 60s when the real reset might be much later.
+ */
+function classifyGitHubWriteFailure(response) {
+  if (response.status !== 403 && response.status !== 429) {
+    return { kind: 'error', status: response.status };
+  }
+  const retryAfter = response.headers.get('retry-after');
+  if (retryAfter) {
+    return { kind: 'secondary-rate-limit', retryAfterSeconds: Number(retryAfter) };
+  }
+  if (response.headers.get('x-ratelimit-remaining') === '0') {
+    return { kind: 'primary-rate-limit', resetAt: Number(response.headers.get('x-ratelimit-reset')) };
+  }
+  return { kind: 'secondary-rate-limit', retryAfterSeconds: 60 };
+}
+
+async function throwGitHubWriteError(response, action, key) {
+  const classification = classifyGitHubWriteFailure(response);
+  const err = new Error(`GitHub API error ${response.status} ${action} ${key}`);
+  err.status = response.status;
+  err.rateLimit = classification.kind !== 'error' ? classification : undefined;
+  try { err.details = await response.json(); } catch { /* body not JSON */ }
+  throw err;
+}
+
 /**
  * Returns a tracker adapter backed by the GitHub Issues REST API.
  * Profile baseUrl must be https://github.com/OWNER/REPO.
@@ -108,5 +139,53 @@ export function createGitHubAdapter(conn, { fetcher = globalThis.fetch } = {}) {
     async fetchStatuses() {
       return ['open', 'closed'];
     },
+
+    async addComment(key, body, opts = {}) {
+      const number = parseInt(key.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}/comments`, {
+        method: 'POST',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ body }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'commenting on', key);
+      const raw = await res.json();
+      return { id: String(raw.id), url: raw.html_url ?? null };
+    },
+
+    /**
+     * GitHub issues have exactly one valid opposite state — not a
+     * discoverable workflow like Jira. Reports it in the same
+     * {id, name, to} shape as Jira's getTransitions for a uniform
+     * cross-tracker adapter contract.
+     */
+    async getTransitions(key, opts = {}) {
+      const ticket = await this.fetchTicket(key, opts);
+      return ticket.status === 'open'
+        ? [{ id: 'closed', name: 'Close issue', to: 'closed' }]
+        : [{ id: 'open', name: 'Reopen issue', to: 'open' }];
+    },
+
+    async transition(key, target, opts = {}) {
+      const ticket = await this.fetchTicket(key, opts);
+      const t = String(target).toLowerCase();
+      if (t === ticket.status) {
+        return { executed: false, reason: 'already-in-target-state', options: await this.getTransitions(key, opts) };
+      }
+      const options = await this.getTransitions(key, opts);
+      const match = options.find(o => o.id === t || o.name.toLowerCase() === t || o.to === t);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      const number = parseInt(key.split('-').pop(), 10);
+      const res = await fetcher(`${GITHUB_API}/repos/${owner}/${repo}/issues/${number}`, {
+        method: 'PATCH',
+        headers: { ...headers, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ state: match.to }),
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000),
+      });
+      if (!res.ok) await throwGitHubWriteError(res, 'transitioning', key);
+      return { executed: true, to: match.to };
+    },
   };
 }

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -1,6 +1,17 @@
-import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses } from '../jira-client.mjs';
+import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, postComment, getTransitions, postTransition } from '../jira-client.mjs';
 import { buildJiraEnv } from '../config.mjs';
 
+/**
+ * Finds the option in a fresh transitions list matching a caller-given
+ * target — by id (exact) or by name/to-name (case-insensitive). Never
+ * trusts a caller-supplied id without confirming it's still a real,
+ * currently-valid option for this exact issue right now.
+ */
+function resolveTransitionTarget(options, target) {
+  const t = String(target).toLowerCase();
+  return options.find(o => o.id === String(target) || o.name.toLowerCase() === t || (o.to ?? '').toLowerCase() === t);
+}
+
 /**
  * Returns a tracker adapter backed by the Jira REST API.
  * Binds connection credentials so callers never touch jira-client directly.
@@ -8,12 +19,29 @@ import { buildJiraEnv } from '../config.mjs';
 export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
   const env = buildJiraEnv(conn);
   const apiVersion = conn.auth === 'cloud' ? 3 : 2;
+  const base = { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp };
 
   return {
     type: 'jira',
-    fetchTicket: (key, opts = {}) => fetchTicket(key, { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    fetchCurrentUser: (opts = {}) => fetchCurrentUser({ env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    searchTickets: (query, opts = {}) => searchTickets(query, { env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
-    fetchStatuses: (opts = {}) => fetchStatuses({ env, fetcher, apiVersion, allowPrivateIp: conn.allowPrivateIp, ...opts }),
+    fetchTicket: (key, opts = {}) => fetchTicket(key, { ...base, ...opts }),
+    fetchCurrentUser: (opts = {}) => fetchCurrentUser({ ...base, ...opts }),
+    searchTickets: (query, opts = {}) => searchTickets(query, { ...base, ...opts }),
+    fetchStatuses: (opts = {}) => fetchStatuses({ ...base, ...opts }),
+    addComment: (key, body, opts = {}) => postComment(key, body, { ...base, ...opts }),
+    getTransitions: (key, opts = {}) => getTransitions(key, { ...base, ...opts }),
+    /**
+     * Always re-fetches transitions fresh and resolves `target` against
+     * them before executing — a caller can never blind-POST a stale or
+     * guessed transition id, even if they try.
+     */
+    async transition(key, target, opts = {}) {
+      const options = await getTransitions(key, { ...base, ...opts });
+      const match = resolveTransitionTarget(options, target);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      await postTransition(key, match.id, { ...base, ...opts });
+      return { executed: true, to: match.to ?? match.name };
+    },
   };
 }

package/skills/jtb/scripts/lib/adapters/linear-adapter.mjs

@@ -65,6 +65,39 @@ async function gql(query, variables, { token, fetcher, signal }) {
   return data;
 }
 
+/**
+ * Resolves a human identifier (e.g. "ENG-123") to the issue's internal id
+ * plus its current state and team — mutations require the UUID id, never
+ * the identifier string (confirmed against Linear's own SDK docs).
+ */
+async function fetchIssueStateInfo(key, { token, fetcher, signal }) {
+  const data = await gql(
+    `query ($id: String!) {
+      issues(filter: { identifier: { eq: $id } }, first: 1) {
+        nodes { id state { id name } team { id } }
+      }
+    }`,
+    { id: key },
+    { token, fetcher, signal },
+  );
+  const node = data.issues?.nodes?.[0];
+  if (!node) throw new Error(`Linear issue not found: ${key}`);
+  return node;
+}
+
+async function fetchTeamWorkflowStates(teamId, { token, fetcher, signal }) {
+  const data = await gql(
+    `query ($teamId: ID!) {
+      workflowStates(filter: { team: { id: { eq: $teamId } } }, first: 50) {
+        nodes { id name }
+      }
+    }`,
+    { teamId },
+    { token, fetcher, signal },
+  );
+  return data.workflowStates?.nodes ?? [];
+}
+
 /**
  * Returns a tracker adapter backed by the Linear GraphQL API.
  * Profile baseUrl must contain linear.app. Auth token stored as apiToken in credentials.json.
@@ -130,5 +163,73 @@ export function createLinearAdapter(conn, { fetcher = globalThis.fetch } = {}) {
       );
       return (data.workflowStates?.nodes ?? []).map(s => s.name);
     },
+
+    async addComment(key, body, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const { id: issueId } = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const data = await gql(
+        `mutation ($issueId: String!, $body: String!) {
+          commentCreate(input: { issueId: $issueId, body: $body }) {
+            success
+            comment { id url }
+          }
+        }`,
+        { issueId, body },
+        { token, fetcher, signal },
+      );
+      if (!data.commentCreate?.success) {
+        throw new Error(`Linear commentCreate reported success:false for ${key}`);
+      }
+      return { id: data.commentCreate.comment.id, url: data.commentCreate.comment.url ?? null };
+    },
+
+    /**
+     * Scoped to the issue's own team — Linear's workflow states are
+     * per-team, so an unscoped list would offer states from teams this
+     * issue can never actually move into.
+     */
+    async getTransitions(key, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const states = await fetchTeamWorkflowStates(info.team.id, { token, fetcher, signal });
+      return states
+        .filter(s => s.id !== info.state?.id)
+        .map(s => ({ id: s.id, name: s.name, to: s.name }));
+    },
+
+    /**
+     * Always re-resolves the issue's current state and team-scoped
+     * options fresh before executing — a caller can never blind-mutate
+     * with a stale stateId. Explicitly checks `success` on the mutation
+     * payload: Linear can return HTTP 200 with no top-level GraphQL
+     * `errors` and still report success:false (e.g. permission denial),
+     * so absence of `errors` alone does not mean the mutation applied.
+     */
+    async transition(key, target, opts = {}) {
+      const signal = AbortSignal.timeout(opts.timeoutMs ?? 10_000);
+      const info = await fetchIssueStateInfo(key, { token, fetcher, signal });
+      const states = await fetchTeamWorkflowStates(info.team.id, { token, fetcher, signal });
+      const t = String(target).toLowerCase();
+      const options = states
+        .filter(s => s.id !== info.state?.id)
+        .map(s => ({ id: s.id, name: s.name, to: s.name }));
+      const match = options.find(o => o.id === String(target) || o.name.toLowerCase() === t);
+      if (!match) {
+        return { executed: false, reason: 'not-found', options };
+      }
+      const data = await gql(
+        `mutation ($id: String!, $stateId: String!) {
+          issueUpdate(id: $id, input: { stateId: $stateId }) {
+            success
+          }
+        }`,
+        { id: info.id, stateId: match.id },
+        { token, fetcher, signal },
+      );
+      if (!data.issueUpdate?.success) {
+        return { executed: false, reason: 'mutation-rejected', options };
+      }
+      return { executed: true, to: match.to };
+    },
   };
 }

package/skills/jtb/scripts/lib/adf-converter.mjs

@@ -4,6 +4,25 @@
  * comment bodies are ADF objects instead of plain text strings.
  */
 
+/**
+ * Converts plain text to a minimal ADF document — one paragraph node per
+ * blank-line-separated block, one text node per paragraph. Jira Cloud (API
+ * v3) rejects a plain string comment body outright; Server/DC (v2) accepts
+ * one directly. No rich-text/markdown conversion — deliberately minimal,
+ * matching the narrow-schema scope of ticket_comment (no formatting inputs
+ * accepted, so none need representing here).
+ */
+export function textToAdf(text) {
+  const paragraphs = (text || '').split('\n\n').filter(Boolean);
+  return {
+    version: 1,
+    type: 'doc',
+    content: paragraphs.length > 0
+      ? paragraphs.map(p => ({ type: 'paragraph', content: [{ type: 'text', text: p }] }))
+      : [{ type: 'paragraph', content: [] }],
+  };
+}
+
 export function adfToText(value) {
   if (value == null) return '';
   if (typeof value === 'string') return value;

package/skills/jtb/scripts/lib/cli.mjs

@@ -130,6 +130,14 @@ export function parseCommand(args) {
     return { command: 'mcp', args: args.slice(1) };
   }
 
+  if (first === 'comment') {
+    return { command: 'comment', args: args.slice(1) };
+  }
+
+  if (first === 'transition') {
+    return { command: 'transition', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

package/skills/jtb/scripts/lib/help.mjs

@@ -54,6 +54,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} recall sync                 Retry any notes stuck in the local queue  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} recall settings             Show effective retry-queue settings, fetched live  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} mcp                         Start the MCP stdio server for Recall  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} comment ${s.dim('<TICKET-KEY> --body=...')}  Post a comment to the tracker  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} transition ${s.dim('<TICKET-KEY> [--target=... --confirm]')}  Move ticket status  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -592,16 +594,25 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}  ${s.dim('[Pro]')}`,
     '',
-    `  Start an MCP (Model Context Protocol) stdio server exposing Recall as`,
-    `  native tools — ${s.cyan('recall_add')} and ${s.cyan('recall_search')} — for any MCP-compatible AI`,
-    `  harness, not just Claude Code. Thin adapter over the same code as`,
-    `  ${s.cyan('note add')}/${s.cyan('recall')} above: same Pro gate, same secret scan, same local`,
-    `  vault, same team sync. Long-running — exits when the client closes stdin.`,
+    `  Start an MCP (Model Context Protocol) stdio server exposing Recall and`,
+    `  ticket writes as native tools — ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')},`,
+    `  ${s.cyan('ticket_transition')} — for any MCP-compatible AI harness, not just Claude Code.`,
+    `  Thin adapter over the same code as ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}`,
+    `  above: same Pro gate, same local vault/tracker writes, same team sync.`,
+    `  ${s.cyan('ticket_transition')} is destructive when called with \`target\`+\`confirm: true\`.`,
+    `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
     '',
+    `  ${s.bold('COMMANDS')}`,
+    '',
+    `    ${s.brand('install')}       Register "ticketlens mcp" into the current project's .mcp.json`,
+    '',
+    `  ${s.dim('install is ungated — writes the registration for anyone; the tools it')}`,
+    `  ${s.dim('points at still require Pro at call time, same as note add/recall.')}`,
+    '',
     `  ${s.bold('HARNESS CONFIG')}`,
     '',
     `    ${s.dim('{ "command": "ticketlens", "args": ["mcp"] }')}`,
@@ -609,6 +620,57 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens mcp`,
+    `    ${s.dim('$')} ticketlens mcp install`,
+    `    ${s.dim('$')} ticketlens mcp install --dry-run`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printCommentHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('comment')} ${s.dim('TICKET-KEY --body="..."')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Post a comment directly to the ticket in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Writes to the real tracker — this is not a local Recall note.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--body')}=${s.dim('TEXT')}    Comment body ${s.dim('(required)')}`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens comment PROD-123 --body="Looks good, merging."`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printTransitionHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('transition')} ${s.dim('TICKET-KEY [--target="..." --confirm]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Move a ticket to a new status in its tracker (Jira/GitHub/Linear). ${s.dim('[Pro]')}`,
+    `  Called with just a ticket key, lists the tracker's current valid options`,
+    `  without changing anything. Add ${s.brand('--target')} and ${s.brand('--confirm')} together to execute.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--target')}=${s.dim('NAME')}  Target status/transition name ${s.dim('(from the list, case-insensitive)')}`,
+    `    ${s.brand('--confirm')}     Required alongside --target to actually execute`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')} Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens transition PROD-123`,
+    `    ${s.dim('$')} ticketlens transition PROD-123 --target="Done" --confirm`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');