ticketlens 0.38.34 → 0.38.36

package/README.md

@@ -44,6 +44,7 @@
   - [Recall](#recall)
   - [Comment, Transition, Assign, Duplicates, Link, Update & Create](#comment-transition-assign-duplicates-link-update--create)
   - [Response-Time Stats](#response-time-stats)
+  - [Pre-fetch Issue Types](#pre-fetch-issue-types)
   - [Doctor](#doctor)
   - [Custom Attention Rules](#custom-attention-rules)
   - [Login](#login)
@@ -453,7 +454,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 `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `history`, `collisions`, `doctor`, `recall_add`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` 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 license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; every other tool needs Pro. 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).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `issue_types`, `history`, `collisions`, `ledger`, `doctor`, `recall_add`, `recall_update`, `recall_delete`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — every CLI action now has an MCP tool, so 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 license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `issue_types` is Free and Jira-only — pre-fetches and caches a profile's real creatable projects and issue types ahead of a `ticket_create` attempt, sharing its cache with that tool's own reactive enrichment; Linear/GitHub profiles get a clear "not available" instead of an empty result; `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; `ledger` exports the local, signed compliance audit trail (zero network) and requires Pro; every other tool needs Pro. `recall_update` overwrites an existing Recall note's body — internal plumbing for the note quality loop, not typically called directly. `recall_delete` is destructive and local-vault-only — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal to prompt against), so omitting it always fails rather than silently blocking. 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. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
 
@@ -497,7 +498,7 @@ Write directly to the ticket in its real tracker — Jira, GitHub, or Linear —
 
 `--attach=path1,path2` (comma-separated local file paths) is available on `comment` and `create` only. Images render as an inline thumbnail on Jira and Linear; GitHub has no attachment upload API, so `--attach` is unsupported there.
 
-**A bad `--project`/`--type` gets a better error, automatically.** If create fails because the project or issue type doesn't exist, TicketLens fetches your tracker's real, current project list (and, for Jira, the real issue types for that project) and shows them alongside the failure — e.g. `Known creatable projects: CNV1, CNV2.` — rather than a bare tracker error. This is reactive only: it never runs on a successful create, never auto-retries the write, and is cached locally per profile for 24h so a burst of failed attempts doesn't re-fetch every time.
+**A bad `--project`/`--type` gets a better error, automatically.** If create fails because the project or issue type doesn't exist, TicketLens fetches your tracker's real, current project list (and, for Jira, the real issue types for that project) and shows them alongside the failure — e.g. `Known creatable projects: CNV1, CNV2.` — rather than a bare tracker error. This is reactive only: it never runs on a successful create, never auto-retries the write, and is cached locally per profile for 24h so a burst of failed attempts doesn't re-fetch every time. `ticketlens issue-types` (below) is the proactive counterpart — pre-fetches and caches the same data ahead of time, so a `create` right after it is a pure cache hit.
 
 All six write actions (comment/transition/assign/link/update/create) 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 writes aren't naturally idempotent, so a timed-out attempt is surfaced to you instead of silently repeated. `duplicates` has neither, since nothing is written.
 
@@ -526,6 +527,19 @@ A one-line summary footer is also appended automatically to `ticketlens triage`
 
 ---
 
+### Pre-fetch Issue Types
+
+```bash
+ticketlens issue-types                   # Pre-fetch/cache the active profile's real projects + Jira issue types
+ticketlens issue-types --profile=acme    # Target a specific profile
+ticketlens issue-types --refresh         # Force a live fetch, bypassing the cache
+ticketlens issue-types --format=json     # JSON output for scripting
+```
+
+Fetches a profile's real creatable projects and, for Jira, each project's valid issue types — the proactive counterpart to `create`'s reactive failure-message enrichment (above): a ready lookup instead of only learning them from a failed create's error. Jira only — Linear has no per-project issue-type concept and GitHub has neither, so both report a clear "not available" instead of an empty result. Free, no license gate. Shares its cache with `create`'s enrichment (`~/.ticketlens/cache/PROFILE/ticket-metadata.json`, 24h TTL), so a `create` failure right after this command is a pure cache hit, no extra network round-trip.
+
+---
+
 ### Doctor
 
 ```bash
@@ -818,6 +832,12 @@ ticketlens stats --profile=acme              # Metrics for a specific profile
 ticketlens stats --days=14                   # Extend lookback window (Pro, max 30)
 ticketlens stats --format=json               # JSON output for scripting
 
+# ── Issue Types ───────────────────────────────────────────────────────────────
+ticketlens issue-types                        # Pre-fetch/cache the active profile's projects + Jira issue types
+ticketlens issue-types --profile=acme        # Target a specific profile
+ticketlens issue-types --refresh             # Force a live fetch, bypassing the cache
+ticketlens issue-types --format=json         # JSON output for scripting
+
 # ── Doctor ────────────────────────────────────────────────────────────────────
 ticketlens doctor                             # Diagnose profile/license/connectivity/cache/MCP-registration/queue problems
 ticketlens doctor --fix                       # Attempt safe automatic fixes

package/bin/ticketlens.mjs

@@ -27,12 +27,13 @@ import {
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
   printComplianceHelp, printLedgerHelp, printPrHelp, printInstallHooksHelp,
-  printCollisionsHelp, printStatsHelp, printDoctorHelp,
+  printCollisionsHelp, printStatsHelp, printIssueTypesHelp, printDoctorHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
   printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp, printLinkHelp, printUpdateHelp, printCreateHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
+import { runIssueTypes } from '../skills/jtb/scripts/lib/run-issue-types.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
 import { readCliToken, deleteCliToken } from '../skills/jtb/scripts/lib/cli-auth.mjs';
 import { runLogin } from '../skills/jtb/scripts/lib/login-flow.mjs';
@@ -159,6 +160,15 @@ switch (command) {
     break;
   }
 
+  case 'issue-types': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printIssueTypesHelp(); break; }
+    runIssueTypes(cmdArgs).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'doctor': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printDoctorHelp(); break; }
     runDoctor(cmdArgs).then(({ ok }) => {

package/package.json

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

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.38.0 -->
+<!-- jtb-skill-version: 0.40.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.
@@ -42,6 +42,8 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb stats                             # personal response-time metrics from local history
 /jtb stats --days=14                   # extend lookback window (Pro, max 30)
 /jtb stats --format=json               # JSON output for scripting
+/jtb issue-types                       # pre-fetch/cache a profile's valid Jira issue types
+/jtb issue-types --refresh             # force a live fetch, bypassing the cache
 /jtb collisions                        # show branch collisions with teammates (Team)
 /jtb collisions --json                 # machine-readable output
 /jtb review                            # code-review context brief from current branch
@@ -66,7 +68,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb assign PROD-1234 --to=me          # assign the ticket to yourself (Pro)
 ```
 
-**Destructive commands** (`note delete`, `cloud-keys remove`, `delete <profile>`) prompt for interactive y/N confirmation and refuse outright in a non-interactive shell unless `--yes` is passed — there is no way to silently skip this. Only pass `--yes` when the user has explicitly asked for that specific deletion in this conversation (their message *is* the confirmation); never add it to route around the prompt for a deletion you decided to make on your own.
+**Destructive commands** (`note delete`, `cloud-keys remove`, `delete <profile>`) prompt for interactive y/N confirmation and refuse outright in a non-interactive shell unless `--yes` is passed — there is no way to silently skip this. Only pass `--yes` when the user has explicitly asked for that specific deletion in this conversation (their message *is* the confirmation); never add it to route around the prompt for a deletion you decided to make on your own. If this harness has TicketLens's MCP server configured, `note delete`'s equivalent is the `recall_delete` tool (`id`/`ticket`/`confirm`) — it has no interactive prompt at all (no real terminal exists under MCP to prompt against), so `confirm: true` is the only way it ever executes; the same rule applies — only pass it when the user's message is the confirmation for that specific note.
 
 ## Prerequisites
 
@@ -148,6 +150,25 @@ If this harness has TicketLens's MCP server configured (a tool named `stats` —
 
 ---
 
+### Issue-types subcommand
+
+If the first argument is `issue-types`:
+
+Run:
+```bash
+ticketlens issue-types $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--profile=acme --refresh --format=json`).
+
+Pre-fetches and caches a profile's real creatable projects and their valid Jira issue types, ahead of a `ticketlens create` attempt — a ready lookup instead of only learning them from a failed create's error message. Jira only; Linear (no per-project issue-type concept) and GitHub (neither) report a clear "not available" instead of an empty result. Free, no license gate. `--profile=NAME` (target a specific tracker profile); `--refresh` (force a live fetch even if a complete cache already exists); `--format=plain` (default, human-readable table) or `--format=json` (scripting). Shares its cache with `ticketlens create`'s own failure-message enrichment (`~/.ticketlens/cache/PROFILE/ticket-metadata.json`, 24h TTL) — a create failure right after this command is a pure cache hit.
+
+Display the script's stdout directly. No plan mode. Stop here.
+
+If this harness has TicketLens's MCP server configured (a tool named `issue_types` — often shown as `mcp__ticketlens__issue_types` — visible in your tool list), prefer it over the bash form: same Jira-only scope, same shared cache, no shell command to construct. It accepts `profile`/`refresh`/`format`.
+
+---
+
 ### History subcommand
 
 If the first argument is `history`:
@@ -370,6 +391,8 @@ When it does apply, run up to 3 rounds:
      ticketlens note patch --id="THE-ID-PRINTED-ABOVE" --ticket=TICKET-KEY --expect-mtime="THE-MTIME-FROM-STEP-1"
    ```
    `--expect-mtime` is what keeps this safe: if the file changed since step 1 (the user hand-edited it while you were drafting), the patch silently no-ops and prints "not found or already changed" — the user's own edit always wins, never gets clobbered by a stale background draft.
+
+   If this harness has TicketLens's MCP server configured (a tool named `recall_update` — often shown as `mcp__ticketlens__recall_update` — visible in your tool list), prefer it over the bash form: same license gate, same structural/secret-scan checks, same optimistic-concurrency behavior via `expectMtime` — just no shell command or stdin piping to construct. It accepts `id`/`body`/`ticket`/`expectMtime`.
 5. Repeat from step 1 (re-capture mtime/body fresh each round) up to 3 total rounds. If no round ever produces a fully-passing draft, patch in whichever round scored highest across all attempts, and let the "not found or already changed" message stand if that patch itself loses a late race — don't retry past round 3.
 
 This never calls any external API or bills any tokens beyond the session you already have open — the generator and validator are subagents inside your own Claude Code session, not a TicketLens server call.
@@ -506,6 +529,9 @@ The same tier-gated check also runs as its own command — `ticketlens complianc
 
 If this harness has TicketLens's MCP server configured (a tool named `compliance` — often shown as `mcp__ticketlens__compliance` — visible in your tool list), prefer it over the bash form: same tier gate (Free: 3 checks/month, Pro: unlimited), same report — just no shell command to construct or stdout to parse. It accepts `ticket`/`profile`, matching the standalone command's arguments above.
 
+### Ledger export
+`ticketlens ledger [--format=json|csv]` exports the same local, signed compliance ledger these checks write to — entirely local, no network call. `[Pro]`. If this harness has TicketLens's MCP server configured (a tool named `ledger` — often shown as `mcp__ticketlens__ledger` — visible in your tool list), prefer it over the bash form: same tier gate, same export, just no shell command to construct or stdout to parse. It accepts `format` (`json`/`csv`, defaults to `json`).
+
 ---
 
 ## Advanced Options

package/skills/jtb/scripts/fetch-ticket.mjs

@@ -488,10 +488,9 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   }
 
   const printFn = opts.print ?? ((chunk) => process.stdout.write(chunk));
-  // Mirrors printFn above — the bare ticket-fetch, compliance, pr, review, and standup
-  // paths all use this now (each has an MCP tool). `ledger` above still writes directly
-  // to the real process.stderr (no MCP tool yet); `install-hooks` is CLI-only and never
-  // gets one.
+  // Mirrors printFn above — the bare ticket-fetch, compliance, pr, review, standup, and
+  // ledger paths all use this now (each has an MCP tool). `install-hooks` is CLI-only
+  // and never gets one.
   const printErrFn = opts.printErr ?? ((chunk) => process.stderr.write(chunk));
   // Reused on every recursive self-call in the bare-fetch path (profile-prompt retries)
   // so an injected print/printErr survives the retry instead of silently reverting to
@@ -610,7 +609,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const { isLicensed: isLic, showUpgradePrompt: showUpgrade } = await import('./lib/license.mjs');
     const resolvedConfigDir = configDir ?? (await import('./lib/config.mjs')).DEFAULT_CONFIG_DIR;
     if (!isLic('pro', resolvedConfigDir)) {
-      showUpgrade('pro', 'ledger', { stream: process.stderr });
+      showUpgrade('pro', 'ledger', { stream: errStream });
       process.exitCode = 1;
       return;
     }
@@ -621,7 +620,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       printFn(result + '\n');
     } else {
       printFn(JSON.stringify(result, null, 2) + '\n');
-      process.stderr.write('  Verify signature: HMAC-SHA256 over {records, exportedAt} with key at ledger-key\n');
+      printErrFn('  Verify signature: HMAC-SHA256 over {records, exportedAt} with key at ledger-key\n');
     }
     return;
   }

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
+export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

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

@@ -118,6 +118,10 @@ export function parseCommand(args) {
     return { command: 'stats', args: args.slice(1) };
   }
 
+  if (first === 'issue-types') {
+    return { command: 'issue-types', args: args.slice(1) };
+  }
+
   if (first === 'doctor') {
     return { command: 'doctor', args: args.slice(1) };
   }

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

@@ -62,6 +62,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} link ${s.dim('<SOURCE> <TARGET> [--type=... --confirm]')}  Link two tickets  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} update ${s.dim('<TICKET-KEY> [--title=... --description=... --priority=... --add-labels=... --remove-labels=...]')}  Update fields  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} create ${s.dim('--project=... [--type=...] --summary=... [--description=...] [--attach=...]')}  Create a new ticket  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} issue-types ${s.dim('[--profile=NAME] [--refresh]')}   Pre-fetch valid Jira issue types  ${s.dim('[Jira only]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -646,11 +647,14 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `  Start an MCP (Model Context Protocol) stdio server exposing CLI actions as`,
     `  native tools — ${s.cyan('fetch')}, ${s.cyan('triage')}, ${s.cyan('compliance')}, ${s.cyan('review')}, ${s.cyan('standup')}, ${s.cyan('pr')}, ${s.cyan('stats')}, ${s.cyan('history')},`,
-    `  ${s.cyan('collisions')}, ${s.cyan('doctor')}, ${s.cyan('recall_add')}, ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')}, ${s.cyan('ticket_transition')},`,
-    `  ${s.cyan('ticket_assign')}, ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — for any`,
-    `  MCP-compatible AI harness, not just Claude Code. Thin adapter over the same`,
-    `  code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('review')}/${s.cyan('standup')}/${s.cyan('pr')}/${s.cyan('stats')}/${s.cyan('history')}/${s.cyan('collisions')}/`,
-    `  ${s.cyan('note add')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/${s.cyan('update')}/${s.cyan('create')} above.`,
+    `  ${s.cyan('collisions')}, ${s.cyan('ledger')}, ${s.cyan('doctor')}, ${s.cyan('issue_types')}, ${s.cyan('recall_add')}, ${s.cyan('recall_update')}, ${s.cyan('recall_delete')},`,
+    `  ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')}, ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')},`,
+    `  ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — every CLI action`,
+    `  now has an MCP tool, for any MCP-compatible AI harness, not just Claude Code.`,
+    `  Thin adapter over the same code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('review')}/`,
+    `  ${s.cyan('standup')}/${s.cyan('pr')}/${s.cyan('stats')}/${s.cyan('history')}/${s.cyan('collisions')}/${s.cyan('ledger')}/${s.cyan('issue-types')}/${s.cyan('note add')}/${s.cyan('note patch')}/`,
+    `  ${s.cyan('note delete')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/`,
+    `  ${s.cyan('update')}/${s.cyan('create')} above.`,
     `  ${s.cyan('fetch')}, ${s.cyan('doctor')}, and ${s.cyan('standup')} are Free; ${s.cyan('triage')} is Free with some Pro/Team-gated`,
     `  options (see ${s.cyan('ticketlens triage --help')}); ${s.cyan('compliance')} and ${s.cyan('pr')} are Free, sharing a`,
     `  3-checks/month cap on their requirements-coverage section, Pro unlimited;`,
@@ -658,14 +662,22 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  requires Pro as a plain license check, not a draw on that same counter;`,
     `  ${s.cyan('stats')} is Free with a 7-day lookback, Pro extends it to 30 days, same split`,
     `  as ${s.cyan('ticketlens stats --help')}; ${s.cyan('history')} is entirely local and requires Pro;`,
-    `  ${s.cyan('collisions')} requires ${s.cyan('ticketlens login')} (Console access) plus a Team license — every`,
-    `  other tool needs Pro. ${s.cyan('ticket_transition')} is destructive when called with`,
+    `  ${s.cyan('collisions')} requires ${s.cyan('ticketlens login')} (Console access) plus a Team license;`,
+    `  ${s.cyan('issue_types')} is Free and Jira-only — Linear/GitHub profiles get a clear`,
+    `  "not available" instead of an empty result — every other tool needs Pro.`,
+    `  ${s.cyan('ticket_transition')} is destructive when called with`,
     `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
     `  ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source issue as a`,
     `  duplicate — different semantics than Jira/Linear's relationship-only add;`,
     `  ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
     `  ${s.cyan('ticket_create')} has no ticket key to target — --profile/the default profile picks the`,
     `  tracker, and it fabricates a real item, the highest blast radius of this family.`,
+    `  ${s.cyan('ledger')} exports the local, signed compliance audit trail — entirely local, no`,
+    `  network call. ${s.cyan('recall_update')} overwrites an existing Recall note's body — internal`,
+    `  plumbing for the note quality loop, not typically called directly.`,
+    `  ${s.cyan('recall_delete')} is destructive and local-vault-only — requires \`confirm: true\`,`,
+    `  alongside \`id\`, to actually execute; there is no interactive y/N prompt under`,
+    `  MCP, so omitting it always fails rather than silently blocking.`,
     `  Long-running — exits when the client closes stdin.`,
     '',
     `  ${s.dim('If a tool call rejects a parameter you expect right after upgrading ticketlens,')}`,
@@ -1305,6 +1317,38 @@ export function printStatsHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printIssueTypesHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('issue-types')} ${s.dim('[--profile=NAME] [--refresh] [--format=plain|json]')}`,
+    '',
+    `  Pre-fetch and cache a profile's real creatable projects and their valid`,
+    `  Jira issue types, ahead of a ${s.brand('ticketlens create')} attempt — a ready lookup`,
+    `  instead of only learning them from a failed create's error message.`,
+    `  Jira only — Linear has no per-project issue-type concept and GitHub has`,
+    `  neither, so both report a clear "not available" instead of an empty result.`,
+    `  Shares its cache with ${s.brand('ticketlens create')}'s own failure-message enrichment`,
+    `  (${s.dim('~/.ticketlens/cache/PROFILE/ticket-metadata.json')}, 24h TTL).`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--profile')}=${s.dim('NAME')}   Use a specific tracker profile`,
+    `    ${s.brand('--refresh')}         Force a live fetch even if a complete cache exists`,
+    `    ${s.brand('--format')}=${s.dim('plain')}    Human-readable table ${s.dim('(default)')}`,
+    `    ${s.brand('--format')}=${s.dim('json')}     JSON output for scripting/piping`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}      Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens issue-types`,
+    `    ${s.dim('$')} ticketlens issue-types --profile=myteam --refresh`,
+    `    ${s.dim('$')} ticketlens issue-types --format=json | jq .`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printStandupHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -22,12 +22,13 @@
 import readline from 'node:readline';
 import { DEFAULT_CONFIG_DIR, getVersion } from './config.mjs';
 import { runDoctor } from './doctor-command.mjs';
-import { runNoteAdd } from './note-command.mjs';
+import { runNoteAdd, runNotePatch, runNoteDelete } from './note-command.mjs';
 import { runRecall } from './recall-command.mjs';
 import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign, runTicketDuplicates, runTicketLinkList, runTicketLink, runTicketUpdate, runTicketCreate } from './ticket-command.mjs';
 import { run as runFetchTicket } from '../fetch-ticket.mjs';
 import { run as runTriage } from '../fetch-my-tickets.mjs';
 import { runStats } from './run-stats.mjs';
+import { runIssueTypes } from './run-issue-types.mjs';
 import { runHistory } from './run-history.mjs';
 import { runCollisions } from './run-collisions.mjs';
 import { TOOLS } from './mcp-tool-schemas.mjs';
@@ -239,6 +240,25 @@ async function callPr(args, deps) {
   return callFetchTicketRun(buildPrArgs, args, deps, 'pr failed');
 }
 
+/**
+ * `ledger` is a subcommand of the same fetch-ticket.mjs `run()` that
+ * `callFetch`/`callCompliance`/`callPr` already wrap — reuses `runFetchTicketFn`,
+ * no new dependency. Unlike those, it has no `ticket`/`profile` argument — the
+ * ledger is local and config-dir scoped, not per-ticket. Its two direct
+ * `process.stderr` writes (the license-gate upgrade prompt and the
+ * verify-signature note printed alongside a successful json export) were
+ * threaded through opts.printErr as part of adding this tool.
+ */
+function buildLedgerArgs({ format }) {
+  const args = ['ledger'];
+  if (format) args.push(`--format=${format}`);
+  return args;
+}
+
+async function callLedger(args, deps) {
+  return callFetchTicketRun(buildLedgerArgs, args, deps, 'ledger export failed');
+}
+
 function buildDoctorArgs({ fix, profile }) {
   const args = ['--format=json'];
   if (fix === true) args.push('--fix');
@@ -289,6 +309,18 @@ async function callStats(args, { configDir, runStatsFn }) {
   return callPrintWarnRun(buildStatsArgs, args, { configDir, runFn: runStatsFn }, 'stats failed');
 }
 
+function buildIssueTypesArgs({ profile, refresh, format }) {
+  const args = [];
+  if (profile) args.push(`--profile=${profile}`);
+  if (refresh === true) args.push('--refresh');
+  if (format) args.push(`--format=${format}`);
+  return args;
+}
+
+async function callIssueTypes(args, { configDir, runIssueTypesFn }) {
+  return callPrintWarnRun(buildIssueTypesArgs, args, { configDir, runFn: runIssueTypesFn }, 'issue-types failed');
+}
+
 function buildHistoryArgs({ ticket }) {
   return [ticket];
 }
@@ -355,6 +387,68 @@ async function callRecallAdd(args, { configDir, runNoteAddFn }) {
   return written ? { content } : { isError: true, content };
 }
 
+/**
+ * Builds runNotePatch's cmdArgs array — same single-opaque-element reasoning
+ * as buildNoteAddArgs above. `expectMtime` is optimistic-concurrency: a
+ * caller that fetched a note via recall_search and wants to refine it
+ * without racing a concurrent edit passes back the mtime it observed.
+ */
+function buildNotePatchArgs({ id, ticket, expectMtime }) {
+  const args = [`--id=${id}`];
+  if (ticket) args.push(`--ticket=${ticket}`);
+  if (expectMtime !== undefined) args.push(`--expect-mtime=${expectMtime}`);
+  return args;
+}
+
+async function callRecallUpdate(args, { configDir, runNotePatchFn }) {
+  if (!args.id) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: id' }] };
+  }
+  if (!args.body) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: body' }] };
+  }
+  const capture = capturingStream();
+  const { patched } = await runNotePatchFn(buildNotePatchArgs(args), {
+    configDir,
+    stream: capture,
+    readStdin: async () => args.body,
+  });
+  const content = [{ type: 'text', text: capture.text }];
+  return patched ? { content } : { isError: true, content };
+}
+
+/**
+ * Builds runNoteDelete's cmdArgs array — same single-opaque-element reasoning
+ * as buildNoteAddArgs above. Always passes `--yes`: runNoteDelete's own
+ * confirmDestructive gate refuses outright in non-interactive mode (no real
+ * TTY exists under the MCP transport to prompt against), so without it every
+ * call would fail. The caller's `confirm: true` is enforced in callRecallDelete
+ * below instead, before runNoteDeleteFn is ever reached — same nudge-and-audit
+ * -trail spirit as ticket_transition/ticket_link, but deliberately a different
+ * code path: those two defer the refusal to the wrapped CLI function, which
+ * here would surface as that generic non-interactive error instead of a
+ * dedicated one naming `confirm`.
+ */
+function buildNoteDeleteArgs({ id, ticket }) {
+  const args = [`--id=${id}`];
+  if (ticket) args.push(`--ticket=${ticket}`);
+  args.push('--yes');
+  return args;
+}
+
+async function callRecallDelete(args, { configDir, runNoteDeleteFn }) {
+  if (!args.id) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: id' }] };
+  }
+  if (args.confirm !== true) {
+    return { isError: true, content: [{ type: 'text', text: 'Deletion requires confirm: true — this cannot be restored.' }] };
+  }
+  const capture = capturingStream();
+  const { deleted } = await runNoteDeleteFn(buildNoteDeleteArgs(args), { configDir, stream: capture });
+  const content = [{ type: 'text', text: capture.text }];
+  return deleted ? { content } : { isError: true, content };
+}
+
 async function callRecallSearch(args, { configDir, runRecallFn }) {
   const capture = capturingStream();
   const { ok } = await runRecallFn([args.query ?? ''], {
@@ -532,11 +626,15 @@ async function handleToolsCall(params, deps) {
   if (name === 'review') return callReview(args, deps);
   if (name === 'standup') return callStandup(args, deps);
   if (name === 'pr') return callPr(args, deps);
+  if (name === 'ledger') return callLedger(args, deps);
   if (name === 'doctor') return callDoctor(args, deps);
   if (name === 'stats') return callStats(args, deps);
+  if (name === 'issue_types') return callIssueTypes(args, deps);
   if (name === 'history') return callHistory(args, deps);
   if (name === 'collisions') return callCollisions(args, deps);
   if (name === 'recall_add') return callRecallAdd(args, deps);
+  if (name === 'recall_update') return callRecallUpdate(args, deps);
+  if (name === 'recall_delete') return callRecallDelete(args, deps);
   if (name === 'recall_search') return callRecallSearch(args, deps);
   if (name === 'ticket_comment') return callTicketComment(args, deps);
   if (name === 'ticket_transition') return callTicketTransition(args, deps);
@@ -548,7 +646,7 @@ async function handleToolsCall(params, deps) {
   return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
 }
 
-async function handleMessage(raw, { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn }) {
+async function handleMessage(raw, deps) {
   let msg;
   try {
     msg = JSON.parse(raw);
@@ -578,7 +676,7 @@ async function handleMessage(raw, { configDir, runFetchTicketFn, runTriageFn, ru
 
   if (method === 'tools/call') {
     try {
-      const result = await handleToolsCall(params, { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const result = await handleToolsCall(params, deps);
       return jsonRpcResult(id, result);
     } catch (err) {
       return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
@@ -603,9 +701,12 @@ export function runMcpServer({
   runTriageFn = runTriage,
   runDoctorFn = runDoctor,
   runStatsFn = runStats,
+  runIssueTypesFn = runIssueTypes,
   runHistoryFn = runHistory,
   runCollisionsFn = runCollisions,
   runNoteAddFn = runNoteAdd,
+  runNotePatchFn = runNotePatch,
+  runNoteDeleteFn = runNoteDelete,
   runRecallFn = runRecall,
   runTicketCommentFn = runTicketComment,
   runTicketTransitionListFn = runTicketTransitionList,
@@ -624,6 +725,11 @@ export function runMcpServer({
   stdin.on('error', () => {});
   stdout.on('error', () => {});
 
+  // Assembled once and passed straight through handleMessage to handleToolsCall,
+  // which is the only place the individual functions are read — so a new tool
+  // needs its dependency named here and in the parameter list above, nowhere else.
+  const deps = { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runIssueTypesFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runNotePatchFn, runNoteDeleteFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn };
+
   const rl = readline.createInterface({ input: stdin, terminal: false });
   let queue = Promise.resolve();
 
@@ -635,7 +741,7 @@ export function runMcpServer({
     // never resolving (a dropped rejection isn't a resolution) — the
     // server would hang on shutdown instead of exiting.
     queue = queue.then(async () => {
-      const response = await handleMessage(line, { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn });
+      const response = await handleMessage(line, deps);
       if (response) stdout.write(response);
     }).catch(() => {});
   });

package/skills/jtb/scripts/lib/mcp-tool-schemas.mjs

@@ -88,6 +88,16 @@ export const TOOLS = [
       required: ['ticket'],
     },
   },
+  {
+    name: 'ledger',
+    description: 'Export the local compliance ledger — a signed, tamper-evident record of every compliance check run (ticket key, commit SHA, author, timestamp, coverage %). Read-only, entirely local — no network call. Verifiable offline: the json format includes an HMAC-SHA256 signature over {records, exportedAt}, keyed at a local ledger-key file. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: { type: 'string', enum: ['json', 'csv'], description: 'Output shape: "json" (default) includes the HMAC signature; "csv" is a flat export with no signature.' },
+      },
+    },
+  },
   {
     name: 'stats',
     description: 'Show response-time and triage-cadence metrics from local triage history — average/median response time, clear rate, triage run count, current urgency breakdown. Read-only, entirely local — no network call. Free tier: 7-day lookback max; TicketLens Pro extends it to 30 days.',
@@ -100,6 +110,18 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'issue_types',
+    description: 'Pre-fetch and cache a profile\'s real creatable projects and their valid Jira issue types, ahead of a `ticket_create` attempt — a ready lookup instead of only learning them from a failed create\'s error message. Jira only; Linear/GitHub report "not available" (Linear has no per-project issue-type concept, GitHub has neither). Shares its cache with ticket_create\'s own failure-message enrichment (24h TTL) — a create failure right after this call is a pure cache hit, no extra network round-trip.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        profile: { type: 'string', description: 'Connection profile to target, overriding folder-based inference and the default profile.' },
+        refresh: { type: 'boolean', description: 'Force a live fetch even if a complete cache already exists for this profile.' },
+        format: { type: 'string', enum: ['plain', 'json'], description: 'Output shape: "plain" (default) is a human-readable table; "json" is structured for scripting.' },
+      },
+    },
+  },
   {
     name: 'history',
     description: 'Show a ticket\'s urgency timeline from local triage history — every prior triage scan that surfaced it, with the urgency level and reason computed at that point in time. Read-only, entirely local — no network call. Requires a TicketLens Pro license.',
@@ -147,6 +169,33 @@ export const TOOLS = [
       required: ['title', 'body'],
     },
   },
+  {
+    name: 'recall_update',
+    description: 'Overwrite an existing Recall note\'s body with a better draft — internal plumbing for the jtb skill\'s note quality loop, not typically called directly. The new body gets the same structural and secret-scan checks a user-typed body gets. Local vault only. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Note id to patch, as printed by recall_add or recall_search.' },
+        body: { type: 'string', description: 'The replacement note body.' },
+        ticket: { type: 'string', description: 'Ticket key the note is about, e.g. PROJ-123. Optional — narrows the search when omitted, the vault is searched across all ticket prefixes.' },
+        expectMtime: { type: 'number', description: 'The note file\'s mtime (ms) last observed by the caller. If the note changed since then, the patch is a no-op rather than an overwrite — optimistic concurrency, not a hard requirement.' },
+      },
+      required: ['id', 'body'],
+    },
+  },
+  {
+    name: 'recall_delete',
+    description: 'Delete a Recall note from the local vault. Irreversible locally, and destructive — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal exists to prompt against), so omitting confirm always fails rather than silently blocking. Local vault only — if this note 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). Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Note id to delete, as printed by recall_add or recall_search.' },
+        ticket: { type: 'string', description: 'Ticket key the note is about, e.g. PROJ-123. Optional — narrows the search when omitted, the vault is searched across all ticket prefixes.' },
+        confirm: { type: 'boolean', description: 'Must be true to actually execute the deletion — a nudge and audit trail, not just a formality. Omitted or false always fails.' },
+      },
+      required: ['id'],
+    },
+  },
   {
     name: 'recall_search',
     description: 'Search saved Recall notes by free-text query or ticket key. Requires a TicketLens Pro license.',

package/skills/jtb/scripts/lib/note-command.mjs

@@ -131,7 +131,11 @@ export async function runNoteAdd(cmdArgs, {
   }
 
   const ticketKeys = ticketKey ? [ticketKey] : [];
-  const { id } = writeNoteFn({ title, ticketKeys, tags, author, body }, { configDir });
+  // Captured once and threaded into writeNoteFn's now() override so the local
+  // vault file's `created` and the pushed payload's captured_at can never skew
+  // by the (short but real) gap between the local write and the push below.
+  const capturedAt = new Date();
+  const { id } = writeNoteFn({ title, ticketKeys, tags, author, body }, { configDir, now: () => capturedAt });
   incrementDraftKeptFn(configDir);
   const styled = !cmdArgs.includes('--plain') && stream.isTTY;
   const s = createStyler({ forceColor: styled, noColor: !styled });
@@ -144,7 +148,7 @@ export async function runNoteAdd(cmdArgs, {
     // the backend wire contract, not the local vault's internal camelCase shape.
     const profile = resolveProfileFn(ticketKey || null, { configDir, cwd: process.cwd() });
     const recallTeamId = profile ? loadProfileRecallTeamIdFn(profile.name, configDir) : null;
-    const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body };
+    const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body, captured_at: capturedAt.toISOString() };
     if (recallTeamId !== null) payload.group_id = recallTeamId;
     const result = await pushNoteFn(payload, { cliToken, configDir, warn });
     if (isRetryableFailureFn(result)) {

package/skills/jtb/scripts/lib/run-issue-types.mjs

@@ -0,0 +1,134 @@
+import { DEFAULT_CONFIG_DIR, timeAgo } from './config.mjs';
+import { resolveConnection } from './profile-resolver.mjs';
+import { resolveAdapter } from './resolve-adapter.mjs';
+import { readMetadataCache, writeMetadataCache } from './ticket-metadata-cache.mjs';
+import { createStyler } from './ansi.mjs';
+import { handleUnknownFlags } from './arg-validator.mjs';
+import { printIssueTypesHelp } from './help.mjs';
+import { formatTable } from './table-formatter.mjs';
+
+// A cache hit must cover every project it lists — a cache seeded only by
+// ticket-create-enrichment.mjs's reactive path (one project at a time, on a
+// create failure) can have projects with no recorded issue types yet. Showing
+// that as "the" answer would silently omit the rest of the profile's projects.
+function isCacheComplete(cached) {
+  if (!cached || cached.projects.length === 0) return false;
+  return cached.projects.every(p => (cached.issueTypesByProject[p.key] || []).length > 0);
+}
+
+function render({ print, format, projects, issueTypesByProject, fetchedAt, cached }) {
+  if (format === 'json') {
+    print(JSON.stringify({ projects, issueTypesByProject, fetchedAt, cached }, null, 2) + '\n');
+    return;
+  }
+
+  const s = createStyler({ isTTY: process.stdout.isTTY });
+
+  if (projects.length === 0) {
+    print(`\n  ${s.dim('No creatable projects found for this profile.')}\n\n`);
+    return;
+  }
+
+  const rows = projects.map(p => {
+    const types = issueTypesByProject[p.key] || [];
+    return [p.key, types.length ? types.map(t => t.name).join(', ') : s.dim('(none)')];
+  });
+
+  print('\n');
+  print(formatTable(['Project', 'Issue Types'], rows) + '\n');
+  print(`\n  ${s.dim(cached
+    ? `Cached ${timeAgo(fetchedAt)} — pass --refresh to force a live fetch.`
+    : 'Fetched live and cached for 24h.')}\n\n`);
+}
+
+/**
+ * `ticketlens issue-types` — proactive counterpart to
+ * ticket-create-enrichment.mjs's reactive cache-refresh: fetches every
+ * creatable project and its Jira issue types ahead of a `ticketlens create`
+ * attempt instead of only learning them from a failed create's error.
+ * Writes through the same ticket-metadata-cache.mjs file/TTL that enrichment
+ * reads, so a create failure right after this command is a pure cache hit.
+ *
+ * @param {string[]} args
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runIssueTypes(args = [], opts = {}) {
+  const print     = opts.print            ?? ((s) => process.stdout.write(s));
+  const warn      = opts.warn             ?? ((s) => process.stderr.write(s));
+  const configDir = opts.configDir        ?? DEFAULT_CONFIG_DIR;
+  const resolveConnectionFn  = opts.resolveConnectionFn  ?? resolveConnection;
+  const resolveAdapterFn     = opts.resolveAdapterFn     ?? resolveAdapter;
+  const readMetadataCacheFn  = opts.readMetadataCacheFn  ?? readMetadataCache;
+  const writeMetadataCacheFn = opts.writeMetadataCacheFn ?? writeMetadataCache;
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printIssueTypesHelp();
+    return { ok: true };
+  }
+
+  const validated = await handleUnknownFlags(
+    args,
+    ['--help', '-h', '--profile=', '--refresh', '--format='],
+    { hints: [] },
+  );
+  if (validated === null) { process.exitCode = 1; return { ok: false }; }
+
+  const profileArg = args.find(a => a.startsWith('--profile='));
+  const formatArg  = args.find(a => a.startsWith('--format='));
+  const forceRefresh = args.includes('--refresh');
+
+  const format = formatArg ? formatArg.split('=')[1] : 'plain';
+  if (format !== 'plain' && format !== 'json') {
+    warn(`Error: --format must be plain or json, got: ${format}\n`);
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  const explicitProfile = profileArg ? profileArg.split('=')[1] : undefined;
+  const cwd = opts.cwd ?? process.cwd();
+  const conn = resolveConnectionFn(null, {
+    configDir,
+    profileName: explicitProfile,
+    cwd,
+    onWarning: (msg) => warn(`  ⚠ ${msg}\n`),
+  });
+  if (!conn.baseUrl) {
+    warn('  No connection configured. Run `ticketlens init` or pass --profile=NAME.\n');
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  const adapter = resolveAdapterFn(conn);
+  if (adapter.type !== 'jira') {
+    warn(`  Issue types are not available for this tracker (${adapter.type}) — only Jira exposes per-project issue types.\n`);
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  const profileName = conn.profileName ?? 'default';
+
+  if (!forceRefresh) {
+    const cached = readMetadataCacheFn(profileName, configDir);
+    if (isCacheComplete(cached)) {
+      render({ print, format, projects: cached.projects, issueTypesByProject: cached.issueTypesByProject, fetchedAt: cached.fetchedAt, cached: true });
+      return { ok: true };
+    }
+  }
+
+  let projects, issueTypesByProject;
+  try {
+    projects = await adapter.listCreatableProjects();
+    issueTypesByProject = Object.create(null);
+    for (const p of projects) {
+      issueTypesByProject[p.key] = await adapter.listIssueTypes(p.key);
+    }
+  } catch (err) {
+    warn(`  Could not fetch issue types: ${err.message}\n`);
+    process.exitCode = 1;
+    return { ok: false };
+  }
+
+  writeMetadataCacheFn(profileName, { projects, issueTypesByProject }, configDir);
+  render({ print, format, projects, issueTypesByProject, fetchedAt: new Date().toISOString(), cached: false });
+  return { ok: true };
+}