ticketlens 0.9.3 → 0.9.8

package/README.md

@@ -125,6 +125,29 @@ Confluence pages linked to the ticket via Jira Remote Links are fetched automati
 
 ---
 
+### Brief Templates
+
+Control which sections appear in a brief without changing the default output for everyone else.
+
+```bash
+ticketlens CNV1-2 --template=quick              # Meta + 2 comments only
+ticketlens CNV1-2 --template=code-review        # Meta + description + linked + code refs
+ticketlens CNV1-2 --template=full               # All sections (same as default)
+ticketlens CNV1-2 --template=my-team-template   # Custom team template [Team]
+```
+
+Three system templates ship out of the box:
+
+| Slug | Sections | Best for |
+|------|----------|---------|
+| `full` | Everything (default) | LLM context, deep planning |
+| `quick` | Meta + 2 comments | Standup, daily triage |
+| `code-review` | Meta + description + linked + code refs | PR review |
+
+**Custom templates [Team]** — create your own in the Console under **Admin → Brief Templates**. Pick which sections appear and cap comment count. The slug you set is what you pass to `--template=`.
+
+---
+
 ### Triage
 
 ```bash
@@ -483,13 +506,16 @@ ticketlens update-skill --path=~/.gemini/commands  # sync to a different AI assi
 **Usage in Claude Code:**
 
 ```
-/jtb CNV1-2                    # Fetch ticket + linked issues → plan mode
-/jtb CNV1-2 --depth=0          # Target ticket only (fast)
-/jtb CNV1-2 --depth=2          # Deep: full linked-issue graph
-/jtb CNV1-2 --profile=acme     # Force a specific profile
-/jtb CNV1-2 --no-attachments   # Skip attachment download
-/jtb CNV1-2 --no-cache         # Re-fetch from Jira
-/jtb triage                    # Scan your assigned tickets
+/jtb CNV1-2                         # Fetch ticket + linked issues → plan mode
+/jtb CNV1-2 --depth=0               # Target ticket only (fast)
+/jtb CNV1-2 --depth=2               # Deep: full linked-issue graph
+/jtb CNV1-2 --profile=acme          # Force a specific profile
+/jtb CNV1-2 --no-attachments        # Skip attachment download
+/jtb CNV1-2 --no-cache              # Re-fetch from Jira
+/jtb CNV1-2 --template=quick        # Apply quick template (meta + 2 comments)
+/jtb CNV1-2 --template=code-review  # Apply code-review template
+/jtb CNV1-2 --template=my-slug      # Apply a custom team template [Team]
+/jtb triage                         # Scan your assigned tickets
 ```
 
 Attachments are listed in the brief as absolute paths. Claude Code reads images (multimodal), PDFs, and text files before planning. Files over 10 MB are skipped.
@@ -532,6 +558,7 @@ ticketlens CNV1-2 --handoff --cloud             # AI handoff brief via TicketLen
 ticketlens CNV1-2 --template=quick              # Apply quick template (meta + 2 comments only)
 ticketlens CNV1-2 --template=code-review        # Apply code-review template (meta + desc + linked + code refs)
 ticketlens CNV1-2 --template=full               # Apply full template (all sections, default)
+ticketlens CNV1-2 --template=my-team-template   # Apply a custom team template [Team]
 ticketlens CNV1-2 --depth=2 --profile=acme --plain   # Combine flags freely
 
 # Pipe plain output to clipboard, LLM, or file
@@ -632,6 +659,18 @@ ticketlens install-hooks --uninstall          # Remove installed hooks [Pro]
 ticketlens pr <TICKET-KEY>                    # Generate PR description from ticket [Pro]
 ticketlens pr <TICKET-KEY> | pbcopy          # Copy to clipboard [Pro]
 
+# ── AI provider keys (BYOK) ───────────────────────────────────────────────────
+ticketlens cloud-keys list                            # List configured AI providers
+ticketlens cloud-keys add groq gsk_xxxx               # Add Groq key (free tier)
+ticketlens cloud-keys add anthropic sk-ant-xxxx       # Add Anthropic key
+ticketlens cloud-keys add openai sk-xxxx              # Add OpenAI key
+ticketlens cloud-keys add groq gsk_xxxx --timeout=10  # Add with custom timeout
+ticketlens cloud-keys test groq                       # Test a provider key
+ticketlens cloud-keys remove groq                     # Remove a provider
+ticketlens cloud-keys priority groq 1                 # Set provider priority
+ticketlens cloud-keys timeout anthropic 15            # Set per-request timeout
+ticketlens cloud-keys --help                          # Subcommand help
+
 # ── Login ─────────────────────────────────────────────────────────────────────
 ticketlens login                              # Browser flow — opens Console, token saved automatically
 ticketlens login --manual                     # Paste flow — for CI/headless environments
@@ -682,7 +721,7 @@ ticketlens schedule                      # Set up a scheduled daily digest
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 
-**`--summarize`** generates a 3-sentence AI summary of the ticket. The AI receives the full ticket context: description, comments, linked Confluence pages, and any text-readable attachments.
+**`--summarize`** generates a 3-sentence AI summary of the ticket. The AI receives the full ticket context: description, comments, linked Confluence pages, and any text-readable attachments. The summary is cached alongside the brief (same 4h TTL) — repeat runs return instantly from cache. Use `--no-cache` to force a fresh AI call.
 
 **`--handoff`** synthesizes the ticket into a structured one-pager for the developer picking up the work. The AI receives the same full context and returns:
 
@@ -703,20 +742,30 @@ ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 | PDFs | ❌ Binary — no parser included (zero-dependency) |
 | Office documents (`.docx`, `.xlsx`) | ❌ Binary — no parser included |
 
-Add one of the following to `~/.ticketlens/credentials.json` for BYOK, or use `--cloud` to route through the TicketLens API:
+Add your AI provider keys once via `cloud-keys` — they're stored encrypted on your account and used automatically:
+
+```bash
+ticketlens cloud-keys add groq gsk_xxxx          # Groq (Llama 3.x — free tier)
+ticketlens cloud-keys add anthropic sk-ant-xxxx  # Anthropic Claude
+ticketlens cloud-keys add openai sk-xxxx         # OpenAI GPT-4o mini
+ticketlens cloud-keys list                       # See configured providers
+ticketlens cloud-keys test groq                  # Verify a key works
+ticketlens cloud-keys remove groq                # Remove a provider
+```
 
-| Key | Provider | Cost |
+Or use `--cloud` to route through the TicketLens API without managing keys yourself.
+
+| Provider | Cost | Sign up |
 |---|---|---|
-| `anthropicApiKey` | Anthropic (Claude Haiku) | Paid |
-| `openaiApiKey` | OpenAI (GPT-4o mini) | Paid |
-| `groqApiKey` | Groq (Llama 3.1 8B) | **Free tier** — [console.groq.com](https://console.groq.com) |
+| Groq (Llama 3.x) | **Free tier** | [console.groq.com](https://console.groq.com) |
+| Anthropic (Claude) | Paid | console.anthropic.com |
+| OpenAI (GPT-4o mini) | Paid | platform.openai.com |
 
-**Selecting a provider:** By default, the first available key is used (Anthropic → OpenAI → Groq). To set a persistent default:
+**Provider priority:** Providers are tried in the order you configure them. To set a default fallback order:
 
 ```bash
-ticketlens config set aiProvider groq        # always use Groq
-ticketlens config set aiProvider openai      # always use OpenAI
-ticketlens config set aiProvider anthropic   # always use Anthropic
+ticketlens cloud-keys priority groq 1        # try Groq first
+ticketlens cloud-keys priority anthropic 2   # Anthropic second
 ```
 
 Override per-command with `--provider=`:
@@ -726,6 +775,8 @@ ticketlens CNV1-2 --summarize --provider=groq
 ticketlens CNV1-2 --handoff --provider=openai
 ```
 
+Or manage keys in **Console → Admin → AI Settings**.
+
 <div align="center">
   <img src="docs/demos/pro-triage.gif" alt="ticketlens triage --stale=3 demo" width="700" />
 </div>

package/bin/ticketlens.mjs

@@ -25,6 +25,7 @@ import {
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
   printCollisionsHelp, printStatsHelp,
+  printCloudKeysHelp,
 } 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';
@@ -33,10 +34,15 @@ import { browserLogin } from '../skills/jtb/scripts/lib/browser-login.mjs';
 import { syncProfiles, getApiBase, getConsoleBase } from '../skills/jtb/scripts/lib/sync.mjs';
 import { promptSecret, promptText } from '../skills/jtb/scripts/lib/prompt-helpers.mjs';
 import { checkForUpdate, getUpdateHint } from '../skills/jtb/scripts/lib/update-check.mjs';
+import { incrementInvocation } from '../skills/jtb/scripts/lib/activity-counter.mjs';
+import { DEFAULT_CONFIG_DIR } from '../skills/jtb/scripts/lib/config.mjs';
 
 const args = process.argv.slice(2);
 const { command, args: cmdArgs } = parseCommand(args);
 
+// Best-effort invocation counter — non-fatal
+try { incrementInvocation(DEFAULT_CONFIG_DIR); } catch { /* non-fatal */ }
+
 // Fire-and-forget: silently refresh license.json at startup if >7 days since last validation
 revalidateIfStale();
 // Fire-and-forget: refresh the cached latest npm version once per 24h
@@ -532,6 +538,122 @@ switch (command) {
     break;
   }
 
+  case 'cloud-keys': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printCloudKeysHelp(); break; }
+
+    const { listCloudKeys, addCloudKey, removeCloudKey, setPriority, setTimeout_, testCloudKey } =
+      await import('../skills/jtb/scripts/lib/cloud-keys.mjs');
+
+    const cliToken = readCliToken();
+    if (!cliToken) {
+      process.stderr.write('Not logged in. Run `ticketlens login` first.\n');
+      process.exitCode = 1;
+      break;
+    }
+
+    const apiBase = getApiBase();
+    const cfg = { cliToken, apiBase };
+    const s = createStyler({ isTTY: process.stderr.isTTY });
+    const subCmd = cmdArgs[0];
+
+    (async () => {
+      if (!subCmd || subCmd === 'list') {
+        const providers = await listCloudKeys(cfg);
+        if (providers.length === 0) {
+          process.stdout.write('No AI providers configured.\n');
+          process.stdout.write(`Add one: ticketlens cloud-keys add <provider> <key>\n`);
+          return;
+        }
+        for (const p of providers) {
+          const status = p.enabled ? s.brand('on') : s.dim('off');
+          process.stdout.write(
+            `  ${p.provider.padEnd(12)} ${p.masked_key.padEnd(28)} priority=${p.priority}  timeout=${p.timeout_seconds}s  [${status}]\n`
+          );
+        }
+        return;
+      }
+
+      if (subCmd === 'add') {
+        const provider = cmdArgs[1];
+        const apiKey   = cmdArgs[2];
+        if (!provider || !apiKey) {
+          process.stderr.write('Usage: ticketlens cloud-keys add <provider> <key> [--timeout=N]\n');
+          process.exitCode = 1;
+          return;
+        }
+        const timeoutArg = cmdArgs.find(a => a.startsWith('--timeout='));
+        const timeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 5;
+        await addCloudKey(cfg, provider, apiKey, timeout);
+        process.stdout.write(`${s.brand('✓')} ${provider} key saved.\n`);
+        return;
+      }
+
+      if (subCmd === 'remove') {
+        const provider = cmdArgs[1];
+        if (!provider) {
+          process.stderr.write('Usage: ticketlens cloud-keys remove <provider>\n');
+          process.exitCode = 1;
+          return;
+        }
+        await removeCloudKey(cfg, provider);
+        process.stdout.write(`${s.brand('✓')} ${provider} key removed.\n`);
+        return;
+      }
+
+      if (subCmd === 'test') {
+        const provider = cmdArgs[1];
+        if (!provider) {
+          process.stderr.write('Usage: ticketlens cloud-keys test <provider>\n');
+          process.exitCode = 1;
+          return;
+        }
+        process.stderr.write(`Testing ${provider}…\n`);
+        const result = await testCloudKey(cfg, provider);
+        if (result.ok) {
+          process.stdout.write(`${s.brand('✓')} ${provider} responded: ${result.response}\n`);
+        } else {
+          process.stderr.write(`${s.dim('✗')} ${provider} error: ${result.error ?? 'unknown'}\n`);
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      if (subCmd === 'priority') {
+        const provider = cmdArgs[1];
+        const priority = parseInt(cmdArgs[2], 10);
+        if (!provider || isNaN(priority)) {
+          process.stderr.write('Usage: ticketlens cloud-keys priority <provider> <N>\n');
+          process.exitCode = 1;
+          return;
+        }
+        await setPriority(cfg, provider, priority);
+        process.stdout.write(`${s.brand('✓')} ${provider} priority set to ${priority}.\n`);
+        return;
+      }
+
+      if (subCmd === 'timeout') {
+        const provider = cmdArgs[1];
+        const seconds  = parseInt(cmdArgs[2], 10);
+        if (!provider || isNaN(seconds)) {
+          process.stderr.write('Usage: ticketlens cloud-keys timeout <provider> <seconds>\n');
+          process.exitCode = 1;
+          return;
+        }
+        await setTimeout_(cfg, provider, seconds);
+        process.stdout.write(`${s.brand('✓')} ${provider} timeout set to ${seconds}s.\n`);
+        return;
+      }
+
+      process.stderr.write(`Unknown subcommand: ${subCmd}\n`);
+      printCloudKeysHelp({ stream: process.stderr });
+      process.exitCode = 1;
+    })().catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'help':
   default:
     printHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.9.3",
+  "version": "0.9.8",
   "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.9.1 -->
+<!-- jtb-skill-version: 0.9.7 -->
 ---
 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.
@@ -43,6 +43,14 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb stats --format=json               # JSON output for scripting
 /jtb collisions                        # show branch collisions with teammates (Team)
 /jtb collisions --json                 # machine-readable output
+/jtb cloud-keys list                   # list configured AI provider keys (Pro)
+/jtb cloud-keys add groq gsk_xxxx      # add Groq key (free tier — console.groq.com)
+/jtb cloud-keys add anthropic sk-ant-x # add Anthropic key
+/jtb cloud-keys add openai sk-xxxx     # add OpenAI key
+/jtb cloud-keys test groq              # verify a provider key works
+/jtb cloud-keys remove groq            # remove a provider
+/jtb cloud-keys priority groq 1        # set provider priority (lower = tried first)
+/jtb cloud-keys timeout anthropic 15   # set per-request timeout in seconds
 ```
 
 ## Prerequisites

package/skills/jtb/scripts/fetch-my-tickets.mjs

@@ -10,6 +10,7 @@ import { assembleTriageSummary } from './lib/brief-assembler.mjs';
 import { styleTriageSummary } from './lib/styled-assembler.mjs';
 import { resolveConnection, loadProfiles, saveProfile } from './lib/profile-resolver.mjs';
 import { resolveAdapter } from './lib/resolve-adapter.mjs';
+import { incrementTriageRun, readAndResetActivity } from './lib/activity-counter.mjs';
 import { writeFileSync, mkdirSync, statSync } from 'node:fs';
 import { resolve as resolvePath, dirname } from 'node:path';
 import { createSpinner } from './lib/spinner.mjs';
@@ -423,6 +424,9 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     saveTriageSnapshot(scored, { profile: profileName ?? 'default', configDir });
   } catch { /* non-fatal */ }
 
+  // Track this triage run (best-effort, non-fatal)
+  try { incrementTriageRun(configDir); } catch { /* non-fatal */ }
+
   // --digest: POST scored results to the digest backend endpoint
   if (digestFlag) {
     if (!licensedFn('pro', configDir)) {
@@ -480,6 +484,8 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     const scanFn = opts.scanFn ?? scanCurrentBranch;
     const cliToken = opts.cliToken ?? readCliToken(configDir) ?? null;
     const printFn = opts.print ?? ((s) => process.stdout.write(s));
+    let cliActivity = null;
+    try { cliActivity = readAndResetActivity(configDir); } catch { /* non-fatal */ }
     await pushFn({
       sorted,
       rawTicketMap,
@@ -487,6 +493,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       baseUrl: conn.baseUrl,
       cliToken,
       gitBranches: scanFn(),
+      cliActivity,
       fetcher,
       print: printFn,
     });

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

@@ -23,11 +23,12 @@ import { readTextAttachments } from './lib/handoff-assembler.mjs';
 import { handleUnknownFlags } from './lib/arg-validator.mjs';
 import { TICKET_KEY_PATTERN } from './lib/cli.mjs';
 import { downloadAttachments } from './lib/attachment-downloader.mjs';
-import { readBriefCache, writeBriefCache, briefCacheAge, BRIEF_TTL_MS } from './lib/brief-cache.mjs';
+import { readBriefCache, writeBriefCache, readSummaryCache, writeSummaryCache, briefCacheAge, BRIEF_TTL_MS } from './lib/brief-cache.mjs';
 import { readCliToken } from './lib/cli-auth.mjs';
 import { resolveTemplate } from './lib/template-resolver.mjs';
 import { parseAge } from './lib/cache-manager.mjs';
 import { createStyler } from './lib/ansi.mjs';
+import { apiBase } from './lib/api-utils.mjs';
 import { isLicensed, showUpgradePrompt, readLicense } from './lib/license.mjs';
 import { detectVcs } from './lib/vcs-detector.mjs';
 import { runComplianceCheck } from './lib/compliance-checker.mjs';
@@ -118,6 +119,23 @@ function augmentBriefForAi(brief, localAttachments) {
   return brief + `\n\n--- Attached Documents (${textFiles.length} text-readable) ---\n\n${sections.join('\n\n')}`;
 }
 
+const PROVIDER_LABELS = { groq: 'Groq', anthropic: 'Anthropic', openai: 'OpenAI' };
+
+async function fetchPrimaryCloudProvider(cliToken, apiUrl) {
+  try {
+    const res = await fetch(`${apiUrl}/v1/ai-providers`, {
+      headers: { 'Authorization': `Bearer ${cliToken}`, 'Accept': 'application/json' },
+      signal: AbortSignal.timeout(3_000),
+    });
+    if (!res.ok) return null;
+    const { providers = [] } = await res.json();
+    const primary = providers.filter(p => p.enabled).sort((a, b) => a.priority - b.priority)[0];
+    return primary?.provider ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Apply --summarize to a brief string.
  * Returns the modified brief, or null if the caller should exit (license gate / consent refused).
@@ -131,18 +149,48 @@ async function applySummarize(brief, args, opts, configDir, conn, licensedFn, up
 
   const mode = args.includes('--cloud') ? 'cloud' : 'byok';
   const profileName = conn.profileName ?? 'default';
+  const ticketKey = ticket?.key ?? null;
+  const noCache = args.includes('--no-cache');
+
+  // Return cached summary if available (skips consent check and AI call).
+  // Bypassed when opts.summarizer is injected (test mode) or --no-cache is set.
+  if (!noCache && !opts.summarizer && ticketKey) {
+    const cachedSummary = readSummaryCache(ticketKey, profileName, configDir);
+    if (cachedSummary) {
+      const divider = '─'.repeat(60);
+      return brief + `\n\n${divider}\n─── AI Summary ${'─'.repeat(45)}\n${cachedSummary}\n${divider}\n`;
+    }
+  }
 
   // Cloud consent check (skipped when summarizer is injected, e.g. tests)
   if (mode === 'cloud' && !opts.summarizer && !hasCloudConsent(configDir, profileName)) {
+    const cliTokenForConsent = opts.cliToken ?? readCliToken(configDir);
+    const apiUrl = apiBase();
+
     let consentGiven = !process.stdin.isTTY;
     if (!consentGiven && process.stdout.isTTY) {
-      process.stdout.write(
-        '\n  Cloud summary sends your ticket content to api.ticketlens.dev for processing.\n' +
-        '  TicketLens calls Claude and returns a summary. No data stored after the request.\n' +
-        '  Proceed? (y/N) '
-      );
+      const providerKey = cliTokenForConsent
+        ? await fetchPrimaryCloudProvider(cliTokenForConsent, apiUrl)
+        : null;
+      const providerLabel = PROVIDER_LABELS[providerKey] ?? 'your configured AI service';
+
+      const s = createStyler({ isTTY: true });
+      const sep = s.dim('  ' + '─'.repeat(55));
+      const promptText =
+        `\n${sep}\n` +
+        `  ${s.bold('Cloud Summary')}  — consent required once per profile\n` +
+        `${sep}\n` +
+        `  ${s.dim('Destination')}   ${s.cyan(apiUrl)}\n` +
+        `  ${s.dim('Processed by')}  ${s.yellow(providerLabel)}\n` +
+        `  ${s.dim('Retention')}     No data stored after this request\n` +
+        `${sep}\n\n` +
+        `  Allow cloud summarization for "${profileName}" profile? [Y/n] `;
+
       const rl = (await import('node:readline')).createInterface({ input: process.stdin, output: process.stdout });
-      consentGiven = await new Promise(resolve => rl.question('', ans => { rl.close(); resolve(ans.trim().toLowerCase() === 'y'); }));
+      consentGiven = await new Promise(resolve => rl.question(
+        promptText,
+        ans => { rl.close(); const a = ans.trim().toLowerCase(); resolve(a === '' || a === 'y'); }
+      ));
     }
     if (!consentGiven) { process.exitCode = 1; return null; }
     saveCloudConsent(configDir, profileName);
@@ -154,10 +202,11 @@ async function applySummarize(brief, args, opts, configDir, conn, licensedFn, up
       return summarize(sumOpts);
     });
     const credentials = opts.credentials ?? loadCredentials(configDir);
-    const licenseKey = readLicense(configDir)?.key;
+    const cliToken  = opts.cliToken ?? readCliToken(configDir);
     const provider = opts.provider ?? resolveAiProvider(args, credentials);
     const aiInput = augmentBriefForAi(brief, ticket?.localAttachments);
-    const summary = await summarizerFn({ brief: aiInput, mode, credentials, licenseKey, provider });
+    const summary = await summarizerFn({ brief: aiInput, mode, credentials, cliToken, provider });
+    if (ticketKey && !opts.summarizer) writeSummaryCache(ticketKey, profileName, summary, configDir);
     const divider = '─'.repeat(60);
     return brief + `\n\n${divider}\n─── AI Summary ${'─'.repeat(45)}\n${summary}\n${divider}\n`;
   } catch (err) {
@@ -187,10 +236,10 @@ async function applyHandoff(ticket, args, opts, configDir, licensedFn, upgradeFn
       return summarize(sumOpts);
     });
     const credentials = opts.credentials ?? loadCredentials(configDir);
-    const licenseKey = readLicense(configDir)?.key;
+    const cliToken  = opts.cliToken ?? readCliToken(configDir);
     const provider = opts.provider ?? resolveAiProvider(args, credentials);
     const input = buildHandoffInput(ticket);
-    const body = await summarizerFn({ brief: input, mode, credentials, licenseKey, prompt: HANDOFF_PROMPT, maxTokens: 512, provider });
+    const body = await summarizerFn({ brief: input, mode, credentials, cliToken, prompt: HANDOFF_PROMPT, maxTokens: 512, provider });
     return `## Handoff Brief — ${ticket.key}\n\n${body}\n`;
   } catch (err) {
     const onErrorFn = opts.onError ?? ((msg) => process.stderr.write(msg + '\n'));

package/skills/jtb/scripts/lib/activity-counter.mjs

@@ -0,0 +1,78 @@
+/**
+ * Best-effort CLI activity counter — tracks fetch, triage, and invocation
+ * counts between pushes. Stored in ~/.ticketlens/activity.json.
+ *
+ * Intentional limitations (acceptable for a UX metric, NOT suitable for billing):
+ *
+ * - Not transactional: if a push succeeds server-side but the network returns
+ *   an error, counters are not reset and will be included in the next push
+ *   (double-counting one session's activity is acceptable).
+ *
+ * - Not safe for concurrent processes: increment() is a read-modify-write with
+ *   no file lock. Two simultaneous CLI invocations will race and the last write
+ *   wins, silently dropping one count. This is rare in normal developer usage
+ *   and acceptable given the zero-npm-deps constraint. Do not rely on these
+ *   counters for exact accuracy.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ACTIVITY_FILE = 'activity.json';
+
+function read(configDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(configDir, ACTIVITY_FILE), 'utf8'));
+  } catch {
+    return { fetch_count: 0, triage_run_count: 0, invocations: 0 };
+  }
+}
+
+function write(configDir, data) {
+  try {
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(configDir, ACTIVITY_FILE),
+      JSON.stringify(data, null, 2),
+      'utf8',
+    );
+  } catch {
+    // Non-fatal — activity tracking is best-effort
+  }
+}
+
+function increment(configDir, field) {
+  const data = read(configDir);
+  data[field] = (data[field] ?? 0) + 1;
+  write(configDir, data);
+}
+
+export function incrementFetch(configDir) {
+  increment(configDir, 'fetch_count');
+}
+
+export function incrementTriageRun(configDir) {
+  increment(configDir, 'triage_run_count');
+}
+
+export function incrementInvocation(configDir) {
+  increment(configDir, 'invocations');
+}
+
+/**
+ * Returns the current counters and resets them to zero.
+ * Call only after a confirmed successful push.
+ *
+ * @param {string} configDir
+ * @returns {{ fetch_count: number, triage_run_count: number, invocations: number }}
+ */
+export function readAndResetActivity(configDir) {
+  const data = read(configDir);
+  const snapshot = {
+    fetch_count:      data.fetch_count      ?? 0,
+    triage_run_count: data.triage_run_count ?? 0,
+    invocations:      data.invocations      ?? 0,
+  };
+  write(configDir, { fetch_count: 0, triage_run_count: 0, invocations: 0 });
+  return snapshot;
+}

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';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,
 // with an optional port — all treated as local-only addresses.

package/skills/jtb/scripts/lib/brief-cache.mjs

@@ -72,6 +72,37 @@ export function writeBriefCache(ticketKey, profileName, depth, ticket, configDir
   }
 }
 
+/**
+ * Reads the cached AI summary from an existing brief cache file.
+ * Returns null if the brief cache is missing or contains no summary.
+ * No TTL check here — the summary is implicitly expired when the brief expires.
+ */
+export function readSummaryCache(ticketKey, profileName, configDir = DEFAULT_CONFIG_DIR) {
+  const filePath = briefCachePath(ticketKey, profileName, configDir);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return typeof data.summary === 'string' ? data.summary : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Patches an existing brief cache file with an AI summary (read-modify-write).
+ * Non-fatal — silently no-ops if the file is missing or unreadable.
+ */
+export function writeSummaryCache(ticketKey, profileName, summary, configDir = DEFAULT_CONFIG_DIR) {
+  const filePath = briefCachePath(ticketKey, profileName, configDir);
+  if (!fs.existsSync(filePath)) return;
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    fs.writeFileSync(filePath, JSON.stringify({ ...data, summary }));
+  } catch {
+    // Non-fatal
+  }
+}
+
 /**
  * Removes the brief cache file for a specific ticket + profile.
  */

package/skills/jtb/scripts/lib/cloud-keys.mjs

@@ -0,0 +1,100 @@
+/**
+ * cloud-keys.mjs — manage per-user AI provider keys stored encrypted on the backend.
+ *
+ * All operations require a CLI token (set via `ticketlens login`).
+ */
+
+const SUPPORTED_PROVIDERS = ['groq', 'anthropic', 'openai'];
+
+function apiBase(config) {
+  return (config.apiBase || 'https://api.ticketlens.io').replace(/\/$/, '');
+}
+
+async function fetchApi(config, path, method = 'GET', body = null) {
+  const cliToken = config.cliToken;
+  if (!cliToken) {
+    throw new Error('Not logged in. Run `ticketlens login` first.');
+  }
+
+  const opts = {
+    method,
+    headers: {
+      'Authorization': `Bearer ${cliToken}`,
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+    },
+  };
+  if (body !== null) opts.body = JSON.stringify(body);
+
+  const fetcher = config.fetcher ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15_000);
+  let res;
+  try {
+    res = await fetcher(`${apiBase(config)}${path}`, { ...opts, signal: controller.signal });
+  } catch (err) {
+    throw new Error(err.name === 'AbortError' ? 'Request timed out.' : err.message);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!res.ok) {
+    let msg = `HTTP ${res.status}`;
+    try { msg = (await res.json()).error ?? msg; } catch {}
+    throw new Error(msg);
+  }
+
+  return res.json();
+}
+
+export async function listCloudKeys(config) {
+  const data = await fetchApi(config, '/v1/ai-providers');
+  return data.providers ?? [];
+}
+
+async function findProvider(config, provider) {
+  const providers = await listCloudKeys(config);
+  const target = providers.find(p => p.provider === provider);
+  if (!target) throw new Error(`No "${provider}" provider configured.`);
+  return target;
+}
+
+export async function addCloudKey(config, provider, apiKey, timeout = 5) {
+  if (!SUPPORTED_PROVIDERS.includes(provider)) {
+    throw new Error(`Unknown provider "${provider}". Supported: ${SUPPORTED_PROVIDERS.join(', ')}.`);
+  }
+  if (apiKey.length < 10) {
+    throw new Error('API key too short. Check your key and try again.');
+  }
+
+  const created = await fetchApi(config, '/v1/ai-providers', 'POST', {
+    provider,
+    api_key: apiKey,
+  });
+
+  if (timeout !== 5) {
+    await fetchApi(config, `/v1/ai-providers/${created.id}`, 'PUT', { timeout_seconds: timeout });
+  }
+
+  return created;
+}
+
+export async function removeCloudKey(config, provider) {
+  const target = await findProvider(config, provider);
+  await fetchApi(config, `/v1/ai-providers/${target.id}`, 'DELETE');
+}
+
+export async function setPriority(config, provider, priority) {
+  const target = await findProvider(config, provider);
+  await fetchApi(config, `/v1/ai-providers/${target.id}`, 'PUT', { priority: Number(priority) });
+}
+
+export async function setTimeout_(config, provider, seconds) {
+  const target = await findProvider(config, provider);
+  await fetchApi(config, `/v1/ai-providers/${target.id}`, 'PUT', { timeout_seconds: Number(seconds) });
+}
+
+export async function testCloudKey(config, provider) {
+  const target = await findProvider(config, provider);
+  return fetchApi(config, `/v1/ai-providers/${target.id}/test`, 'POST');
+}

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

@@ -24,8 +24,11 @@ export function printHelp({ stream = process.stdout } = {}) {
     '',
     `  ${s.bold('USAGE')}`,
     '',
-    // visible widths — target column = 36 visible chars for the command portion
-    // Groups: Console sync ─── Setup ─── Daily use ─── Account / Maintenance
+    // Alignment targets (visible chars before description):
+    //   Groups 1–2 (auth/setup):          column 40  (command portion ≤ 24)
+    //   Group 3 (daily use):              column 42  (longest: "review [--branch=BRANCH]" = 39)
+    //   Group 4 (account/maintenance):    column 43  (longest: "schedule [--stop|--status]" = 41)
+    //   cloud-keys [add|remove|list|test] is an outlier at column 50 — kept with 2-space minimum.
     `    ${s.brand('ticketlens')} login                    Connect CLI to your TicketLens account`,
     `    ${s.brand('ticketlens')} logout                   Remove stored credentials`,
     `    ${s.brand('ticketlens')} sync                     Pull tracker profiles from the console`,
@@ -35,9 +38,9 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} config ${s.dim('[--profile=NAME]')}  Edit profile settings`,
     `    ${s.brand('ticketlens')} profiles                 List all configured profiles  ${s.dim('(alias: ls)')}`,
     '',
-    `    ${s.brand('ticketlens')} ${s.dim('<TICKET-KEY>')} ${s.dim('[options]')}   Fetch a ticket brief`,
-    `    ${s.brand('ticketlens')} get ${s.dim('<TICKET-KEY>')}         Same as above ${s.dim('(explicit alias)')}`,
-    `    ${s.brand('ticketlens')} triage ${s.dim('[options]')}         Scan your assigned tickets`,
+    `    ${s.brand('ticketlens')} ${s.dim('<TICKET-KEY>')} ${s.dim('[options]')}     Fetch a ticket brief`,
+    `    ${s.brand('ticketlens')} get ${s.dim('<TICKET-KEY>')}           Same as above ${s.dim('(explicit alias)')}`,
+    `    ${s.brand('ticketlens')} triage ${s.dim('[options]')}           Scan your assigned tickets`,
     `    ${s.brand('ticketlens')} collisions ${s.dim('[--json]')}        Show branch collisions with teammates  ${s.dim('[Team]')}`,
     `    ${s.brand('ticketlens')} review ${s.dim('[--branch=BRANCH]')}   Code-review context brief from current branch`,
     `    ${s.brand('ticketlens')} standup ${s.dim('[--since=N]')}        Standup summary from git log  ${s.dim('(last 24h by default)')}`,
@@ -45,11 +48,12 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} history ${s.dim('<TICKET-KEY>')}       Urgency timeline for a ticket  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} stats ${s.dim('[options]')}            Personal response-time metrics from local history`,
     '',
-    `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}     Remove a profile`,
-    `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}           Activate a license key`,
-    `    ${s.brand('ticketlens')} license                  Show license status`,
-    `    ${s.brand('ticketlens')} cache ${s.dim('[size|clear]')}       Manage attachment cache  ${s.dim('(try cache --help)')}`,
-    `    ${s.brand('ticketlens')} schedule ${s.dim('[--stop|--status]')} Manage digest schedule  ${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`,
+    `    ${s.brand('ticketlens')} license                     Show license status`,
+    `    ${s.brand('ticketlens')} cache ${s.dim('[size|clear]')}          Manage attachment cache  ${s.dim('(try cache --help)')}`,
+    `    ${s.brand('ticketlens')} schedule ${s.dim('[--stop|--status]')}  Manage digest schedule  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} cloud-keys ${s.dim('[add|remove|list|test]')}  Manage your encrypted AI provider keys  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} update-skill ${s.dim('[--dry-run]')}    Update /jtb skill in Claude Code and other AI assistants`,
     '',
     `  ${s.bold('FETCH OPTIONS')}`,
@@ -111,11 +115,12 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('Or use env vars:')} JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN`,
     `    ${s.dim('               ')} TICKETLENS_API_URL  ${s.dim('(override API host for local dev)')}`,
     '',
-    `    ${s.dim('BYOK AI keys')}  ${s.dim('(add to credentials.json):')}`,
-    `    ${s.dim('               ')} anthropicApiKey  ${s.dim('→ Claude (paid)')}`,
-    `    ${s.dim('               ')} openaiApiKey     ${s.dim('→ GPT-4o mini (paid)')}`,
-    `    ${s.dim('               ')} groqApiKey       ${s.dim('→ Llama 3.1 (free tier — console.groq.com)')}`,
+    `    ${s.dim('BYOK AI keys')}  ${s.dim('(stored encrypted on your account):')}`,
+    `    ${s.dim('               ')} ticketlens cloud-keys add groq ${s.dim('<key>')}`,
+    `    ${s.dim('               ')} ticketlens cloud-keys add anthropic ${s.dim('<key>')}`,
+    `    ${s.dim('               ')} ticketlens cloud-keys add openai ${s.dim('<key>')}`,
     `    ${s.dim('               ')} ${s.dim('Set default:')} ticketlens config set aiProvider ${s.dim('<anthropic|openai|groq>')}`,
+    `    ${s.dim('               ')} ${s.dim('Or manage keys at:')} ${s.dim('Console → Admin → AI Settings')}`,
     '',
     '',
   ];
@@ -752,3 +757,46 @@ export function printStandupHelp({ stream = process.stdout } = {}) {
   ];
   stream.write(lines.join('\n') + '\n');
 }
+
+export function printCloudKeysHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('cloud-keys')} ${s.dim('<subcommand> [options]')}`,
+    '',
+    `  Manage per-account AI provider keys stored encrypted on the TicketLens backend.`,
+    `  Requires ${s.bold('ticketlens login')}. Keys are scoped to your account and never shared.`,
+    '',
+    `  ${s.bold('SUBCOMMANDS')}`,
+    '',
+    `    ${s.brand('list')}                          List configured providers`,
+    `    ${s.brand('add')} ${s.dim('<provider> <key>')}         Add or replace an API key`,
+    `    ${s.brand('remove')} ${s.dim('<provider>')}            Remove a provider's key`,
+    `    ${s.brand('test')} ${s.dim('<provider>')}              Send a test request through the provider`,
+    `    ${s.brand('priority')} ${s.dim('<provider> <N>')}      Set priority (lower = tried first)`,
+    `    ${s.brand('timeout')} ${s.dim('<provider> <seconds>')} Set per-request timeout`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--timeout')}=${s.dim('N')}   Timeout in seconds when adding a key  ${s.dim('(default: 5)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}  Show this help`,
+    '',
+    `  ${s.bold('PROVIDERS')}`,
+    '',
+    `    groq        Llama 3.x — free tier at ${s.dim('console.groq.com')}`,
+    `    anthropic   Claude — ${s.dim('console.anthropic.com')}`,
+    `    openai      GPT-4o — ${s.dim('platform.openai.com')}`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens cloud-keys list`,
+    `    ${s.dim('$')} ticketlens cloud-keys add groq gsk_xxxxxxxxxxxxxxxxxxxx`,
+    `    ${s.dim('$')} ticketlens cloud-keys add groq gsk_xxx --timeout=10`,
+    `    ${s.dim('$')} ticketlens cloud-keys test groq`,
+    `    ${s.dim('$')} ticketlens cloud-keys remove groq`,
+    `    ${s.dim('$')} ticketlens cloud-keys priority groq 1`,
+    `    ${s.dim('$')} ticketlens cloud-keys timeout anthropic 15`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}

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

@@ -12,18 +12,18 @@ const DEFAULT_MAX_TOKENS = 256;
  * @param {string} opts.brief - Markdown brief text
  * @param {'byok'|'cloud'} opts.mode
  * @param {object} [opts.credentials] - { anthropicApiKey?, openaiApiKey?, groqApiKey? }
- * @param {string} [opts.licenseKey] - Required for cloud mode
+ * @param {string} [opts.cliToken] - CLI session token (required for cloud mode)
  * @param {Function} [opts.fetcher] - Injectable for tests (defaults to globalThis.fetch)
  * @param {number} [opts.timeoutMs]
  * @returns {Promise<string>} Summary text
  */
-export async function summarize({ brief, mode, credentials = null, licenseKey = null, fetcher = globalThis.fetch, timeoutMs = 30_000, prompt, maxTokens, provider }) {
+export async function summarize({ brief, mode, credentials = null, cliToken = null, fetcher = globalThis.fetch, timeoutMs = 30_000, prompt, maxTokens, provider }) {
   const effectivePrompt = prompt ?? DEFAULT_PROMPT;
   const effectiveMaxTokens = maxTokens ?? DEFAULT_MAX_TOKENS;
   if (mode === 'byok') {
     return byok({ brief, credentials, fetcher, timeoutMs, prompt: effectivePrompt, maxTokens: effectiveMaxTokens, provider });
   }
-  return cloud({ brief, licenseKey, fetcher, timeoutMs });
+  return cloud({ brief, cliToken, fetcher, timeoutMs });
 }
 
 async function byok({ brief, credentials, fetcher, timeoutMs, prompt, maxTokens, provider }) {
@@ -134,19 +134,24 @@ async function callGroq({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens }
   return data.choices[0].message.content;
 }
 
-async function cloud({ brief, licenseKey, fetcher, timeoutMs }) {
+async function cloud({ brief, cliToken, fetcher, timeoutMs }) {
+  if (!cliToken) throw new Error('Not logged in. Run `ticketlens login` first.');
   const res = await fetcher(`${apiBase()}/v1/summarize`, {
     method: 'POST',
     signal: AbortSignal.timeout(timeoutMs),
     headers: {
       'Content-Type': 'application/json',
-      'Authorization': `Bearer ${licenseKey}`,
+      'Authorization': `Bearer ${cliToken}`,
     },
     body: JSON.stringify({ brief }),
   });
 
   if (!res.ok) {
-    const err = new Error(`TicketLens API error ${res.status}`);
+    let detail = '';
+    try { detail = (await res.json()).error ?? ''; } catch {}
+    if (!detail && res.status === 503) detail = 'No AI provider configured on the backend. Run: ticketlens cloud-keys add groq <key>';
+    if (!detail && res.status === 500) detail = 'Server error (the backend may need `php artisan migrate` after a recent update)';
+    const err = new Error(detail || `TicketLens API error ${res.status}`);
     err.status = res.status;
     throw err;
   }

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

@@ -13,10 +13,9 @@ import {
   invalidateProfilesCache,
 } from './profile-resolver.mjs';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { apiBase } from './api-utils.mjs';
 
-const DEFAULT_API_BASE = 'https://api.ticketlens.app';
-
-export const getApiBase     = () => process.env.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+export const getApiBase     = () => apiBase();
 // Strip the api. subdomain to get the console base URL (e.g. api.ticketlens.app → ticketlens.app)
 export const getConsoleBase = () => getApiBase().replace('://api.', '://');
 

package/skills/jtb/scripts/lib/triage-push.mjs

@@ -34,6 +34,7 @@ export function queueUrl(base) {
  * @param {string}   [opts.cliToken]     - CLI session token for the API
  * @param {string}   [opts.capturedAt]   - ISO 8601 timestamp (defaults to now)
  * @param {Array}    [opts.gitBranches]  - Branch metadata from scanCurrentBranch (null = not in git repo)
+ * @param {object}  [opts.cliActivity]  - Activity counters since last push {fetch_count, triage_run_count, invocations}
  * @param {Function} [opts.fetcher]      - Injectable fetch (default: globalThis.fetch)
  * @param {Function} [opts.print]        - Output fn (default: process.stdout.write)
  * @returns {Promise<{ ok: boolean, status?: number }>}
@@ -46,6 +47,7 @@ export async function pushTriageSnapshot({
   cliToken,
   capturedAt,
   gitBranches,
+  cliActivity,
   fetcher = globalThis.fetch,
   print = (s) => process.stdout.write(s),
   warn = (s) => process.stderr.write(s),
@@ -87,6 +89,7 @@ export async function pushTriageSnapshot({
     captured_at: capturedAt ?? new Date().toISOString(),
     tickets,
     ...(gitBranches != null && { git_branches: gitBranches }),
+    ...(cliActivity != null && { cli_activity: cliActivity }),
   };
 
   try {