ticketlens 0.1.24 → 0.2.0

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
@@ -375,6 +376,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
 
@@ -447,7 +449,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 +467,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 +517,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 +529,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';
@@ -314,6 +314,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.24",
+  "version": "0.2.0",
   "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.0 -->
+---
+name: jtb
+description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
+---
+
+# 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,15 +342,16 @@ 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 pushFn = opts.pushFn ?? pushTriageSnapshot;
@@ -365,6 +367,22 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       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',
+      baseUrl: conn.baseUrl,
+      licenseKey,
+      fetcher,
+      print: printFn,
+    });
+  }
 }
 
 // Run if invoked directly

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

@@ -19,6 +19,7 @@ import { classifyError } from './lib/error-classifier.mjs';
 import { promptProfileSelect, promptProfileMismatch, promptSwitchProfile, promptMultipleMatches } from './lib/profile-picker.mjs';
 import { promptSelect } from './lib/select-prompt.mjs';
 import { printFetchHelp } from './lib/help.mjs';
+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';
@@ -104,11 +105,22 @@ function resolveAiProvider(args, credentials) {
   return credentials?.aiProvider ?? undefined;
 }
 
+/**
+ * Append text-readable attachment content to a brief for AI consumption only.
+ * The returned string is only sent to the AI — the displayed brief is unchanged.
+ */
+function augmentBriefForAi(brief, localAttachments) {
+  const textFiles = readTextAttachments(localAttachments);
+  if (textFiles.length === 0) return brief;
+  const sections = textFiles.map(({ filename, content }) => `=== Attachment: ${filename} ===\n${content}`);
+  return brief + `\n\n--- Attached Documents (${textFiles.length} text-readable) ---\n\n${sections.join('\n\n')}`;
+}
+
 /**
  * Apply --summarize to a brief string.
  * Returns the modified brief, or null if the caller should exit (license gate / consent refused).
  */
-async function applySummarize(brief, args, opts, configDir, conn, licensedFn, upgradeFn) {
+async function applySummarize(brief, args, opts, configDir, conn, licensedFn, upgradeFn, ticket) {
   if (!licensedFn('pro', configDir)) {
     upgradeFn('pro', '--summarize');
     process.exitCode = 1;
@@ -142,7 +154,8 @@ async function applySummarize(brief, args, opts, configDir, conn, licensedFn, up
     const credentials = opts.credentials ?? loadCredentials(configDir);
     const licenseKey = readLicense(configDir)?.key;
     const provider = opts.provider ?? resolveAiProvider(args, credentials);
-    const summary = await summarizerFn({ brief, mode, credentials, licenseKey, provider });
+    const aiInput = augmentBriefForAi(brief, ticket?.localAttachments);
+    const summary = await summarizerFn({ brief: aiInput, mode, credentials, licenseKey, provider });
     const divider = '─'.repeat(60);
     return brief + `\n\n${divider}\n─── AI Summary ${'─'.repeat(45)}\n${summary}\n${divider}\n`;
   } catch (err) {
@@ -955,7 +968,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
       if (args.includes('--check')) brief = applyCheck(brief, opts);
 
       if (args.includes('--summarize')) {
-        brief = await applySummarize(brief, args, opts, configDir, conn, licensedFn, upgradeFn);
+        brief = await applySummarize(brief, args, opts, configDir, conn, licensedFn, upgradeFn, cached.ticket);
         if (brief === null) return;
       }
 
@@ -1141,7 +1154,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
   if (args.includes('--check')) output = applyCheck(output, opts);
 
   if (args.includes('--summarize')) {
-    output = await applySummarize(output, args, opts, configDir, conn, licensedFn, upgradeFn);
+    output = await applySummarize(output, args, opts, configDir, conn, licensedFn, upgradeFn, ticket);
     if (output === null) return;
   }
 

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/handoff-assembler.mjs

@@ -1,13 +1,17 @@
-export const HANDOFF_PROMPT = `Build a structured handoff brief from this Jira ticket's comment thread.
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
+
+export const HANDOFF_PROMPT = `Build a structured handoff brief from this Jira ticket.
 The developer receiving this ticket has never seen it before — they need to get up to speed immediately.
+Use the description, comments, attached documents, and linked Confluence pages as context.
 
 Respond in exactly this format (use the exact headings):
 
 ### What was attempted
-[2–5 bullet points of concrete work already done, based on the comments. Be specific — mention code paths, methods, or files if the comments reference them.]
+[2–5 bullet points of concrete work already done. Be specific — mention code paths, methods, or files if referenced.]
 
 ### Current blockers
-[Bullet points of unresolved issues, errors, or dependencies blocking progress. Write "None identified" if the comments suggest the path is clear.]
+[Bullet points of unresolved issues, errors, or dependencies blocking progress. Write "None identified" if the path is clear.]
 
 ### Open questions
 [Bullet points of unanswered questions or decisions not yet made. Write "None identified" if everything is resolved.]
@@ -16,16 +20,46 @@ Respond in exactly this format (use the exact headings):
 [1–2 sentences on the best starting point for the incoming developer.]
 
 Rules:
-- Be specific and factual. Reference actual details from the comments.
-- Do not invent anything not present in the comments.
+- Be specific and factual. Reference actual details from the ticket content.
+- Do not invent anything not present in the provided context.
 - Keep each bullet under 20 words.
-- If there are no comments, state that clearly in each section.
+- If there are no comments, base your analysis on the description and attached documents.
 
 `;
 
+const TEXT_EXTENSIONS = new Set(['.txt', '.md', '.markdown', '.log', '.csv', '.json', '.xml', '.html', '.htm', '.rst', '.yaml', '.yml']);
+const MAX_CHARS_PER_FILE = 4000;
+const MAX_TOTAL_CHARS = 12000;
+
+/**
+ * Read text content from downloaded local attachments.
+ * Skips binary files (images, PDFs, Office docs). Caps content per file and in total.
+ * @param {Array} localAttachments - from ticket.localAttachments
+ * @returns {Array<{filename: string, content: string}>}
+ */
+export function readTextAttachments(localAttachments = []) {
+  let totalChars = 0;
+  const result = [];
+  for (const att of localAttachments) {
+    if (!att.localPath || att.skipReason === 'error') continue;
+    if (!TEXT_EXTENSIONS.has(extname(att.filename).toLowerCase())) continue;
+    try {
+      const raw = readFileSync(att.localPath, 'utf8');
+      const trimmed = raw.trim();
+      if (!trimmed) continue;
+      const remaining = MAX_TOTAL_CHARS - totalChars;
+      if (remaining <= 0) break;
+      const content = trimmed.slice(0, Math.min(MAX_CHARS_PER_FILE, remaining));
+      totalChars += content.length;
+      result.push({ filename: att.filename, content });
+    } catch { /* unreadable — skip */ }
+  }
+  return result;
+}
+
 /**
  * Build the text input sent to the AI for handoff analysis.
- * Contains the ticket header and full comment thread.
+ * Includes description, Confluence pages, text-readable attachments, and comment thread.
  *
  * @param {object} ticket - Normalized ticket object from jira-client.normalizeTicket
  * @returns {string}
@@ -40,6 +74,33 @@ export function buildHandoffInput(ticket) {
   if (ticket.reporter) lines.push(`Reporter: ${ticket.reporter}`);
   lines.push('');
 
+  if (ticket.description) {
+    lines.push('--- Description ---');
+    lines.push(ticket.description.replace(/\r/g, ''));
+    lines.push('');
+  }
+
+  if (ticket.confluencePages?.length > 0) {
+    lines.push(`--- Confluence Pages (${ticket.confluencePages.length}) ---`);
+    for (const p of ticket.confluencePages) {
+      lines.push('');
+      lines.push(`### ${p.title ?? p.url}`);
+      if (p.text) lines.push(p.text);
+    }
+    lines.push('');
+  }
+
+  const textAttachments = readTextAttachments(ticket.localAttachments);
+  if (textAttachments.length > 0) {
+    lines.push(`--- Attached Documents (${textAttachments.length} text-readable) ---`);
+    for (const { filename, content } of textAttachments) {
+      lines.push('');
+      lines.push(`=== ${filename} ===`);
+      lines.push(content);
+    }
+    lines.push('');
+  }
+
   const comments = ticket.comments ?? [];
   lines.push(`--- Comments (${comments.length} total) ---`);
 

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/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.`);
+    }
+  }
+}