ticketlens 0.1.25 → 0.2.1

package/README.md

@@ -136,6 +136,7 @@ ticketlens triage --sprint="Sprint 12"         # Filter by sprint [Team]
 ticketlens triage --export=csv                 # Export results to CSV [Team]
 ticketlens triage --export=json                # Export results to JSON [Team]
 ticketlens triage --push                       # Push snapshot to Console queue [Team]
+ticketlens triage --share                      # Generate 24h share URL (no login for recipient) [Team]
 ticketlens triage --digest                     # POST scored results to digest endpoint [Pro]
 ticketlens triage --plain                      # Plain markdown — pipe to file or LLM
 ticketlens triage --static                     # Static table, no interactive mode
@@ -290,6 +291,25 @@ ticketlens activate <KEY>         # Activate a Pro or Team license
 
 ---
 
+### Update Skill
+
+```bash
+ticketlens update-skill                          # Sync /jtb skill to all detected AI assistants
+ticketlens update-skill --dry-run                # Preview what would be updated (no writes)
+ticketlens update-skill --path=~/.gemini/commands  # Sync to a specific assistant directory
+ticketlens update-skill --quiet                  # Suppress output (useful in scripts)
+```
+
+Copies the latest `SKILL.md` to every AI assistant command directory where `/jtb` is already installed. Runs automatically on `npm install -g ticketlens` — for most users, upgrading the CLI is enough. Use `--dry-run` to confirm what would change before writing.
+
+Supported assistants detected automatically:
+- Claude Code — `~/.claude/commands/jtb.md`
+- Claude Code (work) — `~/.claude-work/commands/jtb.md`
+- Gemini CLI — `~/.gemini/commands/jtb.md`
+- Copilot CLI — `~/.copilot-cli/commands/jtb.md`
+
+---
+
 ### /jtb — Jira TicketBrief for Claude Code
 
 `/jtb` is a Claude Code slash command that fetches full ticket context and drops a structured implementation brief directly into your session, then enters plan mode.
@@ -300,11 +320,25 @@ ticketlens activate <KEY>         # Activate a Pro or Team license
 
 ```bash
 npm install -g ticketlens && ticketlens init
-cp $(npm root -g)/ticketlens/skills/jtb/SKILL.md ~/.claude/commands/jtb.md
+ticketlens update-skill        # copies /jtb skill into ~/.claude/commands/jtb.md
 # Restart Claude Code, then:
 # /jtb CNV1-2
 ```
 
+**Keeping the skill up to date:**
+
+```bash
+npm install -g ticketlens@latest   # update the CLI
+ticketlens update-skill            # sync the /jtb skill to the new version
+```
+
+`update-skill` runs automatically on `npm install -g`, so for most users the second step is handled. If you manage Claude Code across multiple machines or accounts, run it manually after updating.
+
+```bash
+ticketlens update-skill --dry-run         # preview what would change
+ticketlens update-skill --path=~/.gemini/commands  # sync to a different AI assistant
+```
+
 **Usage in Claude Code:**
 
 ```
@@ -375,6 +409,7 @@ ticketlens triage --assignee="Jane Dev" --sprint="Sprint 12"  # Combined [Team]
 ticketlens triage --export=csv               # Export to CSV [Team]
 ticketlens triage --export=json              # Export to JSON [Team]
 ticketlens triage --push                     # Push snapshot to Console queue [Team]
+ticketlens triage --share                    # Generate 24h share URL (no login for recipient) [Team]
 ticketlens triage --digest                   # POST results to digest endpoint [Pro]
 ticketlens triage --profile=acme --stale=3 --static          # Combine flags
 
@@ -430,6 +465,11 @@ ticketlens login --manual                     # Paste flow — for CI/headless e
 ticketlens license                            # Show license tier and status
 ticketlens activate <LICENSE-KEY>             # Activate a license key
 
+# ── Skill maintenance ─────────────────────────────────────────────────────────
+ticketlens update-skill                       # Sync /jtb skill to all detected AI assistants
+ticketlens update-skill --dry-run             # Preview what would be updated
+ticketlens update-skill --path=~/.gemini/commands  # Sync to a custom assistant directory
+
 # ── Help and version ──────────────────────────────────────────────────────────
 ticketlens --help                             # Main help
 ticketlens --version                          # Show installed version
@@ -447,7 +487,7 @@ ticketlens cache clear --help                 # Cache clear help
 
 Start free, upgrade when you need it — `ticketlens activate <key>`
 
-### Pro — $8/mo
+### Pro — $9/mo
 
 <div align="center">
   <img src="docs/demos/pro-triage.gif" alt="ticketlens --summarize AI summary demo" width="700" />
@@ -465,13 +505,27 @@ ticketlens schedule                      # Set up a scheduled daily digest
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 
-**`--handoff`** synthesizes the comment thread into a structured one-pager for the developer picking up the ticket. No context-reading required — the AI reads the full comment history and returns:
+**`--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.
+
+**`--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:
 
 - **What was attempted** — concrete work already done
 - **Current blockers** — unresolved issues
 - **Open questions** — decisions not yet made
 - **Recommendation** — where to start
 
+**What the AI can read:**
+
+| Content | Included |
+|---|---|
+| Description | ✅ Always |
+| Comments | ✅ Always |
+| Linked Confluence pages | ✅ Jira only, same-origin |
+| Text files (`.txt`, `.md`, `.log`, `.csv`, `.json`, `.yaml`, etc.) | ✅ Up to 4 KB per file, 12 KB total |
+| Screenshots (`.png`, `.jpg`, `.gif`, etc.) | ❌ Binary — images require multimodal API |
+| 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:
 
 | Key | Provider | Cost |
@@ -501,7 +555,7 @@ ticketlens CNV1-2 --handoff --provider=openai
 
 Pro also unlocks configurable brief cache TTL per profile — set `cacheTtl` to `4h`, `1d`, `7d`, `30d`, or `0` (disable) via `ticketlens config`. Free tier is fixed at 4h.
 
-### Team — $15/seat/mo
+### Team — $19/seat/mo
 
 <div align="center">
   <img src="docs/demos/teams-digest.gif" alt="ticketlens triage --plain digest pipeline demo" width="700" />
@@ -513,10 +567,13 @@ ticketlens triage --sprint="Sprint 12"         # Filter by sprint name
 ticketlens triage --export=csv                 # Export triage to CSV for standups and reports
 ticketlens triage --export=json                # Machine-readable export for dashboards
 ticketlens triage --push                       # Push snapshot to the Console queue
+ticketlens triage --share                      # Generate a 24h share URL — paste into Slack, no login needed for recipients
 ```
 
 `--push` syncs the scored snapshot to the TicketLens Console after each triage run. The queue page at `/console/queue` shows the latest snapshot for every team profile — no manual refresh needed.
 
+`--share` generates a signed URL valid for 24 hours. Recipients open it in any browser — no account, no install. The asymmetry is the product: you run one command, everyone sees the same snapshot.
+
 Automate a morning digest with cron — no open terminal required:
 
 ```bash

package/bin/ticketlens.mjs

@@ -23,7 +23,7 @@ import {
   printActivateHelp, printLicenseHelp, printDeleteHelp,
   printProfilesHelp, printScheduleHelp,
   printInitHelp, printSwitchHelp, printConfigHelp,
-  printReviewHelp, printStandupHelp,
+  printReviewHelp, printStandupHelp, printUpdateSkillHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
 import { readCliToken, saveCliToken, deleteCliToken } from '../skills/jtb/scripts/lib/cli-auth.mjs';
@@ -52,6 +52,15 @@ switch (command) {
     });
     break;
 
+  case 'collisions': {
+    const { runCollisions } = await import('../skills/jtb/scripts/lib/run-collisions.mjs');
+    runCollisions(cmdArgs).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'init':
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printInitHelp(); break; }
     runInit().catch(err => {
@@ -314,6 +323,13 @@ switch (command) {
     });
     break;
 
+  case 'update-skill': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printUpdateSkillHelp(); break; }
+    const { updateSkill } = await import('../skills/jtb/scripts/lib/update-skill.mjs');
+    await updateSkill(cmdArgs);
+    break;
+  }
+
   case 'login': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printLoginHelp(); break; }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.1.25",
+  "version": "0.2.1",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {
@@ -8,12 +8,15 @@
   },
   "files": [
     "bin/",
+    "scripts/",
+    "skills/jtb/SKILL.md",
     "skills/jtb/scripts/lib/",
     "skills/jtb/scripts/fetch-ticket.mjs",
     "skills/jtb/scripts/fetch-my-tickets.mjs"
   ],
   "scripts": {
-    "test": "node --test skills/jtb/scripts/test/*.test.mjs"
+    "test": "node --test skills/jtb/scripts/test/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs"
   },
   "keywords": [
     "jira",

package/scripts/dev-license.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Dev helper — set the local TicketLens license tier for testing.
+ *
+ * Usage:
+ *   node scripts/dev-license.mjs            # show current tier
+ *   node scripts/dev-license.mjs free       # remove license (free tier)
+ *   node scripts/dev-license.mjs pro        # write Pro license
+ *   node scripts/dev-license.mjs team       # write Team license
+ */
+
+import { unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readLicense, writeLicense } from '../skills/jtb/scripts/lib/license.mjs';
+import { DEFAULT_CONFIG_DIR } from '../skills/jtb/scripts/lib/config.mjs';
+
+const TIERS = ['free', 'pro', 'team'];
+const tier = process.argv[2]?.toLowerCase();
+
+if (!tier) {
+  const current = readLicense();
+  if (!current) {
+    console.log('Current tier: free (no license file)');
+  } else {
+    console.log(`Current tier: ${current.tier}`);
+    console.log(`  key:         ${current.key}`);
+    console.log(`  email:       ${current.email}`);
+    console.log(`  validatedAt: ${current.validatedAt}`);
+    console.log(`  expiresAt:   ${current.expiresAt ?? 'none'}`);
+  }
+  process.exit(0);
+}
+
+if (!TIERS.includes(tier)) {
+  console.error(`Unknown tier: "${tier}". Valid values: ${TIERS.join(', ')}`);
+  process.exit(1);
+}
+
+if (tier === 'free') {
+  const licensePath = join(DEFAULT_CONFIG_DIR, 'license.json');
+  try {
+    unlinkSync(licensePath);
+    console.log('License removed — now running as free tier.');
+  } catch {
+    console.log('Already free tier (no license file found).');
+  }
+  process.exit(0);
+}
+
+writeLicense({
+  key: `dev-${tier}`,
+  tier,
+  email: `dev-${tier}@test.local`,
+  provider: 'dev',
+  instanceId: 'dev-local',
+  validatedAt: new Date().toISOString(),
+});
+
+console.log(`License set to: ${tier}`);
+console.log(`  key:   dev-${tier}`);
+console.log(`  email: dev-${tier}@test.local`);

package/scripts/postinstall.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Runs automatically after `npm install -g ticketlens`.
+ * Copies the latest SKILL.md into every detected AI assistant command directory.
+ * Silent on failure — never breaks the install.
+ */
+
+import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_SRC = join(__dirname, '..', 'skills', 'jtb', 'SKILL.md');
+
+if (!existsSync(SKILL_SRC)) process.exit(0);
+
+const HOME = homedir();
+
+// Known command directories per AI assistant.
+// Each entry: { label, path } — path must exist and contain jtb.md to be updated.
+const TARGETS = [
+  { label: 'Claude Code',        path: join(HOME, '.claude',      'commands', 'jtb.md') },
+  { label: 'Claude Code (work)', path: join(HOME, '.claude-work', 'commands', 'jtb.md') },
+  { label: 'Gemini CLI',         path: join(HOME, '.gemini',      'commands', 'jtb.md') },
+  { label: 'Copilot CLI',        path: join(HOME, '.copilot-cli', 'commands', 'jtb.md') },
+];
+
+function skillVersion(filePath) {
+  try {
+    const line = readFileSync(filePath, 'utf8').split('\n')[0];
+    const m = line.match(/jtb-skill-version:\s*([\d.]+)/);
+    return m ? m[1] : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+let updated = 0;
+let skipped = 0;
+
+for (const { label, path } of TARGETS) {
+  if (!existsSync(path)) { skipped++; continue; }
+  try {
+    const before = skillVersion(path);
+    copyFileSync(SKILL_SRC, path);
+    const after = skillVersion(SKILL_SRC);
+    if (before === after) {
+      console.log(`  ✔ ${label}: already at v${after}`);
+    } else {
+      console.log(`  ✔ ${label}: updated v${before} → v${after}`);
+    }
+    updated++;
+  } catch (err) {
+    console.warn(`  ⚠ ${label}: could not update — ${err.message}`);
+  }
+}
+
+if (updated === 0 && skipped === TARGETS.length) {
+  console.log('  ℹ /jtb skill not installed in any known location.');
+  console.log('    To install: ticketlens update-skill');
+}

package/skills/jtb/SKILL.md

@@ -0,0 +1,246 @@
+<!-- jtb-skill-version: 0.2.1 -->
+---
+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.
+---
+
+# Jira TicketBrief
+
+Fetches a Jira ticket and produces a structured brief with code references, then enters plan mode.
+
+## Quick Start
+
+```
+/jtb PROD-1234                          # fetch a ticket brief
+/jtb PROD-1234 --depth=0               # target ticket only (fast)
+/jtb PROD-1234 --depth=2               # include linked-of-linked tickets
+/jtb PROD-1234 --profile=acme          # force a specific connection profile
+/jtb PROD-1234 --no-cache              # re-fetch from Jira (bypass local cache)
+/jtb PROD-1234 --no-attachments        # skip attachment download
+/jtb PROD-1234 --plain                 # plain text output (no ANSI colours)
+/jtb PROD-1234 --check                 # coverage review: ACs vs local diff
+/jtb PROD-1234 --compliance            # formal compliance check (tier-gated)
+/jtb PROD-1234 --summarize             # AI summary of the brief (Pro)
+/jtb PROD-1234 --summarize --cloud     # summary via TicketLens cloud (Pro)
+/jtb PROD-1234 --handoff               # structured handoff brief from comments (Pro)
+/jtb triage                            # scan your assigned tickets for attention
+/jtb triage --stale=3                  # custom aging threshold (days)
+/jtb triage --status=CR,QA             # only check specific statuses
+/jtb triage --profile=acme             # explicit profile override
+```
+
+## Prerequisites
+
+TicketLens supports two connection methods — check in this order:
+
+**1. Profile config (recommended):** If `~/.ticketlens/profiles.json` exists, no env vars
+are needed. Profile resolution is automatic (by ticket prefix, project path, or `--profile`).
+Setup via `ticketlens init`.
+
+**2. Env var fallback:** If no profile config exists, these must be set:
+- `JIRA_BASE_URL` — e.g. `https://yourteam.atlassian.net`
+- **Cloud:** `JIRA_EMAIL` + `JIRA_API_TOKEN`
+- **Server/DC:** `JIRA_PAT`
+
+If neither profiles nor env vars are configured, tell the user:
+"No Jira connection found. Run `ticketlens init` to set up your connection,
+or set JIRA_BASE_URL + auth credentials as environment variables."
+
+## Workflow
+
+### Triage subcommand
+
+If the first argument is `triage`:
+
+Run:
+```bash
+node ~/.agents/skills/jtb/scripts/fetch-my-tickets.mjs $EXTRA_ARGS
+```
+
+Where `$EXTRA_ARGS` are any flags passed (e.g. `--stale=3 --status=QA --profile=acme`).
+
+**IMPORTANT:** Copy the script's stdout and display it directly as your response text (not inside a tool result). This ensures the markdown table renders visibly and URLs are clickable in the terminal. No VCS enrichment, no plan mode. Stop here.
+
+---
+
+### Fetch ticket workflow (default)
+
+### Step 1: Validate environment
+
+Follow the Prerequisites section above:
+- If `~/.ticketlens/profiles.json` exists → proceed to Step 2. No env vars needed.
+- If no profile exists → check `JIRA_BASE_URL` and auth vars. If missing, list them and stop.
+- If neither is configured → tell the user: "No Jira connection found. Run `ticketlens init` to set up your connection, or set `JIRA_BASE_URL` + auth credentials as environment variables."
+
+### Step 2: Fetch the ticket
+
+Run:
+```bash
+node ~/.agents/skills/jtb/scripts/fetch-ticket.mjs "$TICKET_KEY" $EXTRA_ARGS
+```
+
+Where `$TICKET_KEY` is the first argument (e.g. `PROD-1234`) and `$EXTRA_ARGS` are any flags passed (e.g. `--depth=0`).
+
+The script outputs a structured markdown TicketBrief to stdout. If it fails (exit code 1), show the stderr message to the user.
+
+### Step 2b: Read attached files
+
+Check if the TicketBrief contains an `## Attachments` section. If it does, for each line containing a backtick-quoted absolute path, call the Read tool on that path based on file type:
+
+- **Images** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`): Read it — Claude receives it as multimodal visual context.
+- **PDFs** (`.pdf`): Read it — Claude receives the extracted text content.
+- **Text files** (`.txt`, `.csv`, `.md`, `.log`): Read it — Claude receives the raw text.
+- **Other files** (`.zip`, `.docx`, `.xlsx`, etc.): Note they exist at the listed path but do not attempt to read them.
+
+Read all eligible files before proceeding. Do not describe images unprompted — hold them in context for Step 5.
+
+If there is no `## Attachments` section, skip this step.
+
+---
+
+### Step 3: Detect VCS and enrich
+
+Detect the VCS in the current working directory and run enrichment commands:
+
+**Git:**
+```bash
+git log --all --grep="$TICKET_KEY" --oneline --max-count=20
+git branch -a | grep "$TICKET_KEY"
+```
+
+**SVN:**
+```bash
+svn log --limit 50 | grep -A5 "$TICKET_KEY"
+svn ls ^/branches | grep "$TICKET_KEY"
+```
+
+**Hg:**
+```bash
+hg log -k "$TICKET_KEY" --limit 20
+hg branches | grep "$TICKET_KEY"
+```
+
+If no VCS is detected, skip this step.
+
+### Step 4: Resolve code references
+
+From the TicketBrief output, look at the **Code References** section:
+
+- For each **file path**: use Glob to check if it exists in the current repo
+- For each **class name**: use Grep to find its definition (`class ClassName`)
+- For each **branch**: note if it was found in step 3
+- For each **SHA/revision**: note if it appeared in the VCS log
+
+### Step 5: Plan the implementation
+
+Enter plan mode with all gathered context:
+- The TicketBrief markdown
+- VCS commits and branches related to the ticket
+- Which referenced files/classes exist locally
+- Linked ticket summaries and their comments
+
+Present a clear implementation plan for the user to approve.
+
+---
+
+## --check: Acceptance Criteria Coverage Review
+
+When `--check` is appended to any ticket fetch (`/jtb PROJ-123 --check`):
+
+### With VCS (git/svn/hg detected)
+1. The brief includes a `--- DIFF ---` section with the current local diff
+2. After reading the brief, evaluate coverage:
+   - Identify acceptance criteria from the ticket description and comments
+   - For each AC, check whether the diff addresses it
+   - Report: ✔ FOUND (with file:line reference) or ✗ NOT FOUND
+   - Show: `Coverage: N/M (X%) — N items outstanding`
+
+### Without VCS (no git/svn/hg in cwd)
+Use this evaluation order:
+1. **Session context** — review files you Read/Edited this session; compare against ACs
+2. **claude-mem** — if available, call `get_observations` searching for `{ticketKey}` to find prior session work
+3. **context7** — if available, validate that changed files use correct library/framework APIs
+4. **fs.stat() fallback** — read files modified in the last 4 hours in cwd; compare against ACs
+5. **Manual checklist** — if none of the above apply, list the ACs for the developer to review manually
+
+### Privacy
+`--check` never sends data anywhere. The diff stays local. Claude Code provides the intelligence using its existing session context.
+
+---
+
+## --compliance: Formal Compliance Check
+
+When `--compliance` is appended to any ticket fetch (`/jtb PROJ-123 --compliance`):
+
+**Tier gate:** Free tier allows 3 compliance checks per month. Pro tier is unlimited.
+If the user is on Free and has exhausted their quota, show the upgrade prompt returned by the script and stop.
+
+### With VCS (git/svn/hg detected)
+1. The brief includes a `--- DIFF ---` section with the current local diff
+2. After reading the brief, evaluate each requirement formally:
+   - Extract every stated requirement, acceptance criterion, and definition-of-done item from the ticket description and all comments
+   - For each requirement, assess whether the diff satisfies it:
+     - `✔ COMPLIANT` — fully addressed, cite file:line
+     - `✖ NON-COMPLIANT` — not addressed at all
+     - `~ PARTIAL` — partially addressed, describe the gap
+   - Show a compliance summary: `Compliance: N/M (X%) — N items non-compliant, N partial`
+   - List all non-compliant and partial items with actionable notes
+
+### Without VCS (no git/svn/hg in cwd)
+Use this evaluation order:
+1. **Session context** — review files you Read/Edited this session; compare against requirements
+2. **claude-mem** — if available, call `get_observations` searching for `{ticketKey}`
+3. **Manual checklist** — list each requirement for the developer to verify manually
+
+### Privacy
+`--compliance` never sends data anywhere. The diff stays local. All analysis is performed by Claude Code within your session context.
+
+---
+
+## Advanced Options
+
+These flags are available on any ticket fetch and can be combined.
+
+### --summarize (Pro)
+
+Generates an AI-powered summary of the full brief, collapsing verbose descriptions into a concise implementation overview. Useful for large tickets with many comments.
+
+```
+/jtb PROD-1234 --summarize             # BYOK — uses your own API key
+/jtb PROD-1234 --summarize --cloud     # uses TicketLens cloud summariser
+/jtb PROD-1234 --summarize --provider=openai   # use a specific AI provider
+/jtb PROD-1234 --summarize --budget=2000       # limit output to ~2000 tokens
+```
+
+- **BYOK (default):** reads your AI API key from `~/.ticketlens/credentials.json`. First use will prompt for consent.
+- **`--cloud`:** routes through TicketLens cloud API (no local key needed, requires Pro).
+- **`--provider=NAME`:** override the AI provider. Supported values depend on your credentials (e.g. `claude`, `openai`).
+- **`--budget=N`:** prune the brief to approximately N tokens before summarising. Forces plain-text output.
+
+### --handoff (Pro)
+
+Generates a structured handoff brief synthesised from the ticket's full comment thread. Designed for developer-to-developer handoffs — includes open questions, current state, and next steps.
+
+```
+/jtb PROD-1234 --handoff
+/jtb PROD-1234 --handoff --cloud
+```
+
+Output is a concise markdown document, not a full TicketBrief. No plan mode — output is displayed and the workflow stops.
+
+### --plain / --styled
+
+Control output formatting:
+
+- **`--plain`** — strip all ANSI colour codes. Useful when piping to a file or another tool.
+- **`--styled`** — force ANSI-styled output even in non-TTY contexts (e.g. when piped).
+
+Default: styled when stdout is a TTY, plain otherwise.
+
+### --no-cache
+
+Forces a fresh fetch from Jira, bypassing the local brief cache (4-hour TTL by default). Use when the ticket was recently updated and the cached brief is stale.
+
+### --no-attachments
+
+Skip downloading and reading ticket attachments. Speeds up the fetch for tickets with large or irrelevant file attachments.

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

@@ -74,7 +74,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   const validatedArgs = await handleUnknownFlags(
     args,
-    ['--help', '-h', '--static', '--plain', '--styled', '--profile=', '--stale=', '--status=', '--assignee=', '--sprint=', '--export=', '--digest', '--push'],
+    ['--help', '-h', '--static', '--plain', '--styled', '--profile=', '--stale=', '--status=', '--assignee=', '--sprint=', '--export=', '--digest', '--push', '--share'],
     { hints: ['--depth=', '--no-attachments', '--no-cache'] } // fetch-only flags — shown as hints, not applied
   );
   if (validatedArgs === null) { process.exitCode = 1; return; }
@@ -92,6 +92,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   const exportArg = args.find(a => a.startsWith('--export='))?.split('=')[1] ?? null;
   const digestFlag = args.includes('--digest');
   const pushFlag = args.includes('--push');
+  const shareFlag = args.includes('--share');
 
   if (exportArg && exportArg !== 'csv' && exportArg !== 'json') {
     process.stderr.write(`Error: --export must be csv or json, got: ${exportArg}\n`);
@@ -341,21 +342,41 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       const cleanArgs = args.filter(a => !a.startsWith('--profile=') && !a.startsWith('--project='));
       return run(cleanArgs, { ...opts, env, fetcher, configDir });
     }
-    return;
+    // Fall through to push/share if those flags were passed
+    if (!pushFlag && !shareFlag) return;
+  } else {
+    const useStyled = args.includes('--styled') || (!args.includes('--plain') && process.stdout.isTTY);
+    const summary = useStyled
+      ? styleTriageSummary(sorted, { styled: true, staleDays, baseUrl: conn.baseUrl })
+      : assembleTriageSummary(sorted, { staleDays, baseUrl: conn.baseUrl });
+    process.stdout.write(summary + '\n');
   }
 
-  const useStyled = args.includes('--styled') || (!args.includes('--plain') && process.stdout.isTTY);
-  const summary = useStyled
-    ? styleTriageSummary(sorted, { styled: true, staleDays, baseUrl: conn.baseUrl })
-    : assembleTriageSummary(sorted, { staleDays, baseUrl: conn.baseUrl });
-  process.stdout.write(summary + '\n');
-
   if (pushFlag) {
     const { pushTriageSnapshot } = await import('./lib/triage-push.mjs');
+    const { scanCurrentBranch } = await import('./lib/branch-scanner.mjs');
     const pushFn = opts.pushFn ?? pushTriageSnapshot;
+    const scanFn = opts.scanFn ?? scanCurrentBranch;
     const licenseKey = readLicense(configDir)?.key ?? null;
     const printFn = opts.print ?? ((s) => process.stdout.write(s));
     await pushFn({
+      sorted,
+      rawTicketMap,
+      profile: profileName ?? 'default',
+      baseUrl: conn.baseUrl,
+      licenseKey,
+      gitBranches: scanFn(),
+      fetcher,
+      print: printFn,
+    });
+  }
+
+  if (shareFlag) {
+    const { shareTriageSnapshot } = await import('./lib/triage-share.mjs');
+    const shareFn = opts.shareFn ?? shareTriageSnapshot;
+    const licenseKey = readLicense(configDir)?.key ?? null;
+    const printFn = opts.print ?? ((s) => process.stdout.write(s));
+    await shareFn({
       sorted,
       rawTicketMap,
       profile: profileName ?? 'default',

package/skills/jtb/scripts/lib/branch-scanner.mjs

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TICKET_KEY_RE = /([A-Z][A-Z0-9]+-\d+)/g;
+const SPAWN_OPTS = { encoding: 'utf8', timeout: 10_000 };
+const MAX_FILES = 200;
+const BASE_CANDIDATES = ['origin/main', 'origin/master', 'origin/develop', 'main', 'master'];
+
+function run(execFn, args, cwd) {
+  const result = execFn('git', args, { ...SPAWN_OPTS, cwd, stdio: 'pipe' });
+  return result.status === 0 ? (result.stdout ?? '') : null;
+}
+
+function extractTicketKeys(text) {
+  return [...new Set([...text.matchAll(TICKET_KEY_RE)].map(m => m[1]))];
+}
+
+function detectBase(execFn, cwd) {
+  for (const candidate of BASE_CANDIDATES) {
+    if (run(execFn, ['rev-parse', '--verify', candidate], cwd) !== null) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Scans the current git branch for changed files and linked ticket keys.
+ *
+ * @param {object}   [opts]
+ * @param {string}   [opts.cwd]    Working directory (default: process.cwd())
+ * @param {Function} [opts.execFn] spawnSync replacement (injectable for tests)
+ * @param {Function} [opts.fsCheck] existsSync replacement (injectable for tests)
+ * @returns {Array<{branch:string, base:string|null, tickets:string[], files:string[]}>|null}
+ *   One-element array for the current branch, or null if not in a git repo / detached HEAD.
+ */
+export function scanCurrentBranch({ cwd = process.cwd(), execFn = spawnSync, fsCheck = existsSync } = {}) {
+  if (!fsCheck(join(cwd, '.git'))) return null;
+
+  const branch = run(execFn, ['rev-parse', '--abbrev-ref', 'HEAD'], cwd)?.trim();
+  if (!branch || branch === 'HEAD') return null;
+
+  const base = detectBase(execFn, cwd);
+
+  let files = [];
+  if (base) {
+    const diffOut = run(execFn, ['diff', '--name-only', `${base}..HEAD`], cwd);
+    if (diffOut) {
+      files = diffOut.trim().split('\n').filter(Boolean).slice(0, MAX_FILES);
+    }
+  }
+
+  const recentLog = run(execFn, ['log', '--oneline', '-20'], cwd) ?? '';
+  const tickets = extractTicketKeys(`${branch} ${recentLog}`);
+
+  return [{ branch, base, tickets, files }];
+}

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

@@ -102,6 +102,10 @@ export function parseCommand(args) {
     return { command: 'sync', args: args.slice(1) };
   }
 
+  if (first === 'update-skill') {
+    return { command: 'update-skill', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

package/skills/jtb/scripts/lib/collision-reporter.mjs

@@ -0,0 +1,45 @@
+const INDENT = '        ';
+
+/**
+ * Formats a collision list from the /v1/triage/collisions API response.
+ *
+ * @param {object[]} collisions
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.plain]  Suppress ANSI (forced when not TTY)
+ * @param {boolean}  [opts.isTTY] Enable ANSI escape sequences
+ * @param {boolean}  [opts.json]  Emit raw JSON instead of text
+ * @returns {string}
+ */
+export function formatCollisions(collisions, { plain = false, isTTY = false, json = false } = {}) {
+  if (json) return JSON.stringify(collisions, null, 2) + '\n';
+
+  const useAnsi = isTTY && !plain;
+  const warn = useAnsi ? '\x1b[33m⚠\x1b[0m' : '⚠';
+  const ok   = useAnsi ? '\x1b[32m✓\x1b[0m' : '✓';
+  const bold = useAnsi ? (s) => `\x1b[1m${s}\x1b[0m` : (s) => s;
+  const dim  = useAnsi ? (s) => `\x1b[2m${s}\x1b[0m` : (s) => s;
+
+  if (collisions.length === 0) {
+    return `${ok} No branch collisions detected.\n`;
+  }
+
+  const n = collisions.length;
+  const lines = [`${warn} ${bold(`${n} collision${n === 1 ? '' : 's'} detected`)}\n`];
+
+  for (let i = 0; i < n; i++) {
+    const c = collisions[i];
+    const yourKeys  = c.your_tickets?.length  ? c.your_tickets.join(', ')  : '—';
+    const theirKeys = c.their_tickets?.length ? c.their_tickets.join(', ') : '—';
+    const count     = c.shared_files?.length ?? 0;
+
+    lines.push(
+      `  [${i + 1}] ${bold('You')} ${dim(`(${c.your_branch})`)} ↔ ${bold(c.teammate)} ${dim(`(${c.their_branch})`)}`,
+      `      Tickets: ${yourKeys} ↔ ${theirKeys}`,
+      `      Shared files (${count}):`,
+      ...(c.shared_files ?? []).map(f => `${INDENT}${f}`),
+      '',
+    );
+  }
+
+  return lines.join('\n');
+}

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

@@ -3,20 +3,24 @@
  * Single source of truth — import from here, do not redefine locally.
  */
 
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 
 /** Canonical config directory: ~/.ticketlens */
 export const DEFAULT_CONFIG_DIR = join(homedir(), '.ticketlens');
 
-/** Read package.json version once per process, memoized. */
+/** Read package.json version once per process, memoized.
+ * Uses realpathSync to resolve symlinks before navigating, so the correct
+ * package.json is found whether the module is loaded via a symlink or directly.
+ */
 let _version;
 export function getVersion() {
   if (_version) return _version;
   try {
-    const pkgPath = new URL('../../../../package.json', import.meta.url);
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const realDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+    const pkg = JSON.parse(readFileSync(join(realDir, '..', '..', '..', '..', 'package.json'), 'utf8'));
     _version = pkg.version || '0.0.0';
   } catch {
     _version = '0.0.0';

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

@@ -47,6 +47,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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')} update-skill ${s.dim('[--dry-run]')}    Update /jtb skill in Claude Code and other AI assistants`,
     '',
     `  ${s.bold('FETCH OPTIONS')}`,
     '',
@@ -63,6 +64,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
     `    ${s.brand('--handoff')}          AI handoff brief from comment thread ${s.dim('(BYOK or --cloud) [Pro]')}`,
     `    ${s.brand('--cloud')}            Route AI request through TicketLens API ${s.dim('[Pro]')}`,
+    `    ${s.brand('--provider')}=${s.dim('NAME')}     Force AI provider ${s.dim('(anthropic|openai|groq)')}`,
     '',
     `  ${s.bold('TRIAGE OPTIONS')}`,
     '',
@@ -74,6 +76,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--assignee')}=${s.dim('NAME')}    Triage another dev's tickets  ${s.dim('[Team]')}`,
     `    ${s.brand('--sprint')}=${s.dim('NAME')}      Filter by sprint name  ${s.dim('[Team]')}`,
     `    ${s.brand('--export')}=${s.dim('FORMAT')}   Export results to file  ${s.dim('(csv|json) [Team]')}`,
+    `    ${s.brand('--push')}             Push snapshot to Console queue  ${s.dim('[Team]')}`,
+    `    ${s.brand('--share')}            Generate a 24h share URL  ${s.dim('(no login required) [Team]')}`,
     `    ${s.brand('--digest')}           POST scored results to digest endpoint  ${s.dim('[Pro]')}`,
     `    ${s.brand('--static')}           Static table output ${s.dim('(skip interactive mode)')}`,
     `    ${s.brand('--plain')}            Plain markdown output ${s.dim('(for piping / LLM)')}`,
@@ -102,6 +106,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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('               ')} ${s.dim('Set default:')} ticketlens config set aiProvider ${s.dim('<anthropic|openai|groq>')}`,
     '',
     '',
   ];
@@ -541,6 +546,8 @@ export function printTriageHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--assignee')}=${s.dim('NAME')}    Triage another dev's tickets  ${s.dim('[Team]')}`,
     `    ${s.brand('--sprint')}=${s.dim('NAME')}      Filter by sprint name  ${s.dim('[Team]')}`,
     `    ${s.brand('--export')}=${s.dim('FORMAT')}    Export results to file  ${s.dim('(csv|json) [Team]')}`,
+    `    ${s.brand('--push')}             Push snapshot to Console queue  ${s.dim('[Team]')}`,
+    `    ${s.brand('--share')}            Generate a 24h share URL  ${s.dim('(no login required) [Team]')}`,
     `    ${s.brand('--digest')}           POST scored results to digest endpoint  ${s.dim('[Pro]')}`,
     `    ${s.brand('--static')}           Static table output ${s.dim('(skip interactive mode)')}`,
     `    ${s.brand('--plain')}            Plain markdown output`,
@@ -600,6 +607,42 @@ export function printReviewHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printUpdateSkillHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('update-skill')} ${s.dim('[--dry-run] [--path=DIR] [--quiet]')}`,
+    '',
+    `  Copy the latest /jtb SKILL.md into every detected AI assistant command directory.`,
+    `  Runs automatically on ${s.dim('npm install -g ticketlens')} for existing installs.`,
+    '',
+    `  ${s.bold('SUPPORTED ASSISTANTS')}`,
+    '',
+    `    Claude Code         ${s.dim('~/.claude/commands/jtb.md')}`,
+    `    Claude Code (work)  ${s.dim('~/.claude-work/commands/jtb.md')}`,
+    `    Gemini CLI          ${s.dim('~/.gemini/commands/jtb.md')}`,
+    `    Copilot CLI         ${s.dim('~/.copilot-cli/commands/jtb.md')}`,
+    '',
+    `  Only targets where ${s.dim('jtb.md')} already exists are updated. Use ${s.dim('--path')} to install`,
+    `  into a new location (the directory must exist).`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--dry-run')}          Show what would change without writing any files`,
+    `    ${s.brand('--path')}=${s.dim('DIR')}       Write to a specific commands directory instead`,
+    `    ${s.brand('--quiet')}            Suppress all output except errors`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}      Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens update-skill`,
+    `    ${s.dim('$')} ticketlens update-skill --dry-run`,
+    `    ${s.dim('$')} ticketlens update-skill --path=~/.config/my-ai/commands`,
+    '',
+  ];
+  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/run-collisions.mjs

@@ -0,0 +1,64 @@
+import { readLicense } from './license.mjs';
+import { formatCollisions } from './collision-reporter.mjs';
+
+const COLLISIONS_PATH = '/v1/triage/collisions';
+const DEFAULT_API_BASE = 'http://ticketlens.test';
+
+function apiBase() {
+  return process.env?.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+}
+
+/**
+ * Fetches cross-team branch collision data from the TicketLens API and prints results.
+ *
+ * @param {string[]} args              CLI argument array (e.g. ['--json', '--plain'])
+ * @param {object}   [opts]
+ * @param {Function} [opts.fetcher]        Injectable fetch
+ * @param {Function} [opts.print]          Output function
+ * @param {Function} [opts.readLicenseFn]  Injectable license reader
+ * @returns {Promise<{ ok: boolean, status?: number }>}
+ */
+export async function runCollisions(args = [], opts = {}) {
+  const jsonFlag  = args.includes('--json');
+  const plainFlag = args.includes('--plain');
+  const fetcher        = opts.fetcher       ?? globalThis.fetch;
+  const print          = opts.print         ?? ((s) => process.stdout.write(s));
+  const readLicenseFn  = opts.readLicenseFn ?? (() => readLicense());
+
+  const licenseKey = readLicenseFn()?.key ?? null;
+  if (!licenseKey) {
+    print('✗ collisions requires an active Team license (ticketlens activate <key>)\n');
+    return { ok: false };
+  }
+
+  try {
+    const res = await fetcher(`${apiBase()}${COLLISIONS_PATH}`, {
+      headers: { Authorization: `Bearer ${licenseKey}` },
+    });
+
+    if (!res.ok) {
+      if (res.status === 401) { print('✗ Invalid license key\n');              return { ok: false, status: 401 }; }
+      if (res.status === 403) { print('✗ collisions requires a Team license\n'); return { ok: false, status: 403 }; }
+      print(`⚠ Failed to fetch collisions (${res.status})\n`);
+      return { ok: false, status: res.status };
+    }
+
+    const { collisions = [], message } = await res.json();
+
+    if (message && collisions.length === 0) {
+      print(message + '\n');
+      return { ok: true };
+    }
+
+    print(formatCollisions(collisions, {
+      json:   jsonFlag,
+      plain:  plainFlag,
+      isTTY:  process.stdout.isTTY ?? false,
+    }));
+
+    return { ok: true };
+  } catch {
+    print('⚠ Failed to fetch collisions (network error)\n');
+    return { ok: false };
+  }
+}

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

@@ -44,6 +44,7 @@ function buildTicketPayload(scored, rawMap, baseUrl) {
  * @param {string}   [opts.baseUrl]      - Jira base URL for URL construction
  * @param {string}   [opts.licenseKey]   - Bearer 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 {Function} [opts.fetcher]      - Injectable fetch (default: globalThis.fetch)
  * @param {Function} [opts.print]        - Output fn (default: process.stdout.write)
  * @returns {Promise<{ ok: boolean, status?: number }>}
@@ -55,6 +56,7 @@ export async function pushTriageSnapshot({
   baseUrl,
   licenseKey,
   capturedAt,
+  gitBranches,
   fetcher = globalThis.fetch,
   print = (s) => process.stdout.write(s),
 } = {}) {
@@ -67,6 +69,7 @@ export async function pushTriageSnapshot({
     profile: String(profile ?? 'default').slice(0, 100),
     captured_at: capturedAt ?? new Date().toISOString(),
     tickets: sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl)),
+    ...(gitBranches != null && { git_branches: gitBranches }),
   };
 
   try {

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

@@ -0,0 +1,89 @@
+/**
+ * POST triage snapshot to /v1/triage/share and return a 24h signed URL.
+ * Errors are non-fatal — share failure must never suppress triage output.
+ */
+
+const SHARE_PATH = '/v1/triage/share';
+const DEFAULT_API_BASE = 'http://ticketlens.test';
+
+function apiBase() {
+  return process.env?.TICKETLENS_API_URL ?? DEFAULT_API_BASE;
+}
+
+function buildTicketPayload(scored, rawMap, baseUrl) {
+  const raw = rawMap?.get(scored.ticketKey);
+  return {
+    key: scored.ticketKey,
+    summary: scored.summary ?? null,
+    status: scored.status ?? null,
+    assignee: raw?.assignee ?? null,
+    attention_score: null,
+    flags: scored.urgency === 'clear' ? [] : [scored.urgency],
+    compliance_coverage: null,
+    compliance_status: 'unknown',
+    url: baseUrl ? `${baseUrl}/browse/${scored.ticketKey}` : null,
+    last_updated: raw?.updated ?? null,
+  };
+}
+
+/**
+ * @param {object}   opts
+ * @param {object[]} [opts.sorted]       - Scored tickets
+ * @param {Map}      [opts.rawTicketMap] - Map<key, normalizedTicket>
+ * @param {string}   [opts.profile]      - Resolved profile name (max 100 chars)
+ * @param {string}   [opts.baseUrl]      - Jira base URL
+ * @param {string}   [opts.licenseKey]   - Bearer token
+ * @param {string}   [opts.capturedAt]   - ISO 8601 timestamp
+ * @param {Function} [opts.fetcher]      - Injectable fetch
+ * @param {Function} [opts.print]        - Output fn
+ * @returns {Promise<{ ok: boolean, status?: number }>}
+ */
+export async function shareTriageSnapshot({
+  sorted = [],
+  rawTicketMap = new Map(),
+  profile,
+  baseUrl,
+  licenseKey,
+  capturedAt,
+  fetcher = globalThis.fetch,
+  print = (s) => process.stdout.write(s),
+} = {}) {
+  if (!licenseKey) {
+    print('✗ --share requires an active Team license (ticketlens activate <key>)\n');
+    return { ok: false };
+  }
+
+  const payload = {
+    profile: String(profile ?? 'default').slice(0, 100),
+    captured_at: capturedAt ?? new Date().toISOString(),
+    tickets: sorted.map(t => buildTicketPayload(t, rawTicketMap, baseUrl)),
+  };
+
+  try {
+    const res = await fetcher(`${apiBase()}${SHARE_PATH}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${licenseKey}`,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (res.ok) {
+      const data = await res.json();
+      print(`✓ Share link (expires in 24h):\n  ${data.url}\n`);
+      return { ok: true, status: res.status };
+    }
+
+    if (res.status === 403) {
+      print('✗ --share requires a Team license\n');
+      return { ok: false, status: res.status };
+    }
+
+    print(`⚠ Share failed (${res.status}) — triage output unaffected\n`);
+    return { ok: false, status: res.status };
+  } catch {
+    print('⚠ Share failed (network error) — triage output unaffected\n');
+    return { ok: false };
+  }
+}

package/skills/jtb/scripts/lib/update-skill.mjs

@@ -0,0 +1,116 @@
+/**
+ * update-skill — copies SKILL.md to known AI assistant command directories.
+ *
+ * Usage:
+ *   ticketlens update-skill                   # update all detected installs
+ *   ticketlens update-skill --dry-run         # show what would change, no writes
+ *   ticketlens update-skill --path=/some/dir  # write to a custom target directory
+ *   ticketlens update-skill --quiet           # suppress non-error output
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILL_SRC = join(__dirname, '..', '..', 'SKILL.md');
+
+const HOME = homedir();
+
+const DEFAULT_TARGETS = [
+  { label: 'Claude Code',        path: join(HOME, '.claude',      'commands') },
+  { label: 'Claude Code (work)', path: join(HOME, '.claude-work', 'commands') },
+  { label: 'Gemini CLI',         path: join(HOME, '.gemini',      'commands') },
+  { label: 'Copilot CLI',        path: join(HOME, '.copilot-cli', 'commands') },
+];
+
+function skillVersion(filePath) {
+  try {
+    const line = readFileSync(filePath, 'utf8').split('\n')[0];
+    const m = line.match(/jtb-skill-version:\s*([\d.]+)/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function updateSkill(args = []) {
+  const dryRun  = args.includes('--dry-run');
+  const quiet   = args.includes('--quiet');
+  const pathArg = args.find(a => a.startsWith('--path='));
+
+  const log = (...msg) => { if (!quiet) process.stdout.write(msg.join(' ') + '\n'); };
+  const err = (...msg) => process.stderr.write(msg.join(' ') + '\n');
+
+  if (!existsSync(SKILL_SRC)) {
+    err(`✖ SKILL.md not found at ${SKILL_SRC}`);
+    err('  Reinstall TicketLens: npm install -g ticketlens@latest');
+    process.exitCode = 1;
+    return;
+  }
+
+  const srcVersion = skillVersion(SKILL_SRC) ?? 'unknown';
+  if (dryRun) log(`Dry run — skill source: v${srcVersion} (${SKILL_SRC})\n`);
+
+  let targets;
+  if (pathArg) {
+    const dir = pathArg.slice('--path='.length);
+    targets = [{ label: 'Custom path', path: dir }];
+  } else {
+    targets = DEFAULT_TARGETS;
+  }
+
+  let updated = 0;
+  let skipped = 0;
+  let notFound = 0;
+
+  for (const { label, path: dir } of targets) {
+    const dest = join(dir, 'jtb.md');
+
+    if (!existsSync(dir)) { notFound++; continue; }
+    if (!existsSync(dest)) { notFound++; continue; }
+
+    const destVersion = skillVersion(dest);
+
+    if (!dryRun && destVersion === srcVersion) {
+      log(`  ✔ ${label}: already at v${srcVersion}`);
+      skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      const fromVer = destVersion ?? 'unversioned';
+      log(`  → ${label}: ${dest}`);
+      log(`    ${fromVer} → ${srcVersion} (would update)`);
+      continue;
+    }
+
+    try {
+      copyFileSync(SKILL_SRC, dest);
+      const fromVer = destVersion ?? 'unversioned';
+      log(`  ✔ ${label}: updated v${fromVer} → v${srcVersion}`);
+      updated++;
+    } catch (copyErr) {
+      err(`  ✖ ${label}: ${copyErr.message}`);
+    }
+  }
+
+  if (!dryRun) {
+    if (updated === 0 && notFound === targets.length) {
+      log('\n  /jtb is not installed in any known AI assistant.');
+      log('\n  To install for Claude Code:');
+      log('    mkdir -p ~/.claude/commands');
+      log(`    cp "${SKILL_SRC}" ~/.claude/commands/jtb.md`);
+      log('\n  Then restart your Claude Code session and use /jtb TICKET-KEY.');
+      return;
+    }
+    if (updated > 0) {
+      log(`\n  ${updated} installation(s) updated to v${srcVersion}.`);
+      log('  Restart your AI assistant session to pick up the new skill.');
+    }
+    if (skipped > 0 && !quiet) {
+      log(`  ${skipped} installation(s) already up to date.`);
+    }
+  }
+}