ticketlens 0.21.9 → 0.21.10

package/README.md

@@ -260,8 +260,8 @@ Runs the same compliance check as `ticketlens CNV1-2 --compliance` but as a dedi
 ### Compliance Ledger
 
 ```bash
-ticketlens ledger                             # View the local compliance audit ledger [Pro]
-ticketlens ledger --plain                     # Plain markdown output
+ticketlens ledger                             # View the local compliance audit ledger, JSON + signature [Pro]
+ticketlens ledger --format=csv                # Flat CSV export, no signature [Pro]
 ```
 
 Displays the append-only local ledger of all compliance checks run on this machine. Useful for SOC 2 / HIPAA audit trails. Requires a Pro license.
@@ -365,9 +365,11 @@ Cache locations:
 ticketlens schedule               # Interactive wizard — set digest time, timezone, profile [Pro]
 ticketlens schedule --stop        # Cancel the scheduled digest
 ticketlens schedule --status      # Show current schedule
-ticketlens schedule --local       # Local-only cron (no Console auth) — saves triage to file [Pro]
+ticketlens schedule --local --time=07:00 --save=./triage.txt   # Local-only cron/LaunchAgent, no Console auth [Pro]
 ```
 
+Not logged in? `ticketlens schedule` falls back to local-only mode automatically — same as passing `--local` explicitly.
+
 Stores the schedule as a cron entry. Delivers your triage digest at the configured time without an open terminal. Requires a Pro license.
 
 ---
@@ -595,6 +597,7 @@ ticketlens CNV1-2 --template=quick              # Apply quick template (meta + 2
 ticketlens CNV1-2 --template=code-review        # Apply code-review template (meta + desc + linked + code refs)
 ticketlens CNV1-2 --template=full               # Apply full template (all sections, default)
 ticketlens CNV1-2 --template=my-team-template   # Apply a custom team template [Team]
+ticketlens CNV1-2 --budget=8000                 # Trim brief to fit a token budget [Pro]
 ticketlens CNV1-2 --depth=2 --profile=acme --plain   # Combine flags freely
 
 # Pipe plain output to clipboard, LLM, or file
@@ -675,7 +678,7 @@ ticketlens cache clear --older-than=30d --yes            # Skip confirmation (CI
 ticketlens schedule                           # Interactive wizard — set time, timezone, profile [Pro]
 ticketlens schedule --stop                    # Cancel the scheduled digest [Pro]
 ticketlens schedule --status                  # Show current schedule [Pro]
-ticketlens schedule --local                   # Local-only cron/LaunchAgent — no Console auth needed [Pro]
+ticketlens schedule --local --time=07:00 --save=./triage.txt  # Local-only cron/LaunchAgent, no Console auth [Pro]
 
 # ── History ───────────────────────────────────────────────────────────────────
 ticketlens history <TICKET-KEY>               # Show urgency timeline for a ticket [Pro]

package/bin/ticketlens.mjs

@@ -24,6 +24,7 @@ import {
   printProfilesHelp, printScheduleHelp,
   printInitHelp, printSwitchHelp, printConfigHelp,
   printReviewHelp, printStandupHelp, printUpdateSkillHelp,
+  printComplianceHelp, printLedgerHelp, printPrHelp, printInstallHooksHelp,
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp,
@@ -394,10 +395,28 @@ switch (command) {
       break;
     }
 
-    const { runScheduleWizard } = await import('../skills/jtb/scripts/lib/schedule-wizard.mjs');
+    const cliTokenForSchedule = readCliToken();
+    const { shouldUseLocalSchedule, parseLocalScheduleFlags, runScheduleLocal, runScheduleWizard } = await import('../skills/jtb/scripts/lib/schedule-wizard.mjs');
+
+    if (shouldUseLocalSchedule({ cmdArgs, cliToken: cliTokenForSchedule })) {
+      const { time, outputFile } = parseLocalScheduleFlags(cmdArgs);
+      if (!time || !outputFile) {
+        process.stderr.write(`  Local scheduling requires --time and --save.\n`);
+        process.stderr.write(`  Usage: ticketlens schedule --local --time=HH:MM --save=FILE\n`);
+        if (!cliTokenForSchedule) {
+          process.stderr.write(`  Or run \`ticketlens login\` first to use the Console-backed wizard.\n`);
+        }
+        process.exitCode = 1;
+        break;
+      }
+      const localResult = await runScheduleLocal({ answers: { time, outputFile } });
+      if (!localResult.ok) { process.exitCode = 1; }
+      break;
+    }
+
     const { promptScheduleAnswers } = await import('../skills/jtb/scripts/lib/prompt-helpers.mjs');
     const answers = await promptScheduleAnswers(cmdArgs);
-    const result = await runScheduleWizard({ answers, cliToken: readCliToken() });
+    const result = await runScheduleWizard({ answers, cliToken: cliTokenForSchedule });
     if (!result.ok) { process.exitCode = 1; break; }
 
     const s = createStyler({ isTTY: process.stdout.isTTY });
@@ -410,6 +429,7 @@ switch (command) {
   }
 
   case 'install-hooks':
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printInstallHooksHelp(); break; }
     runFetch(['install-hooks', ...cmdArgs]).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;
@@ -417,6 +437,7 @@ switch (command) {
     break;
 
   case 'pr':
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printPrHelp(); break; }
     runFetch(['pr', ...cmdArgs]).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;
@@ -440,6 +461,7 @@ switch (command) {
     break;
 
   case 'ledger':
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printLedgerHelp(); break; }
     runFetch(['ledger', ...cmdArgs]).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;
@@ -447,6 +469,7 @@ switch (command) {
     break;
 
   case 'compliance':
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printComplianceHelp(); break; }
     runFetch(['compliance', ...cmdArgs]).catch(err => {
       process.stderr.write(`Error: ${err.message}\n`);
       process.exitCode = 1;

package/package.json

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

package/skills/jtb/SKILL.md

@@ -44,6 +44,10 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb stats --format=json               # JSON output for scripting
 /jtb collisions                        # show branch collisions with teammates (Team)
 /jtb collisions --json                 # machine-readable output
+/jtb review                            # code-review context brief from current branch
+/jtb review --branch=main              # compare against a specific branch
+/jtb standup                           # standup summary from git log (last 24h)
+/jtb standup --format=pr               # PR body instead of standup bullets
 /jtb cloud-keys list                   # list configured AI provider keys (Pro)
 /jtb cloud-keys add groq gsk_xxxx      # add Groq key (free tier — console.groq.com)
 /jtb cloud-keys add anthropic sk-ant-x # add Anthropic key
@@ -52,7 +56,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb cloud-keys remove groq            # remove a provider
 /jtb cloud-keys priority groq 1        # set provider priority (lower = tried first)
 /jtb cloud-keys timeout anthropic 15   # set per-request timeout in seconds
-/jtb note "gotcha text" --ticket=PROD-1234    # save a Recall note (Pro)
+/jtb note add --title="gotcha text" --ticket=PROD-1234    # save a Recall note (Pro, body from stdin)
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
 /jtb recall sync                       # retry any notes stuck in the local queue (Pro)
 /jtb recall settings                   # show effective retry-queue settings, fetched live (Pro)

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

@@ -493,6 +493,22 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   // Early dispatch for non-ticket subcommands
   if (args[0] === 'install-hooks') {
+    if (args.includes('--uninstall')) {
+      const { uninstallHook } = await import('./lib/hook-installer.mjs');
+      try {
+        const result = await uninstallHook({ cwd: process.cwd() });
+        if (result.skipped) {
+          process.stderr.write(`  Hook uninstall skipped: ${result.reason}\n`);
+        } else {
+          process.stdout.write(`  Hook removed: ${result.path}\n`);
+        }
+      } catch (err) {
+        process.stderr.write(`  Error removing hook: ${err.message}\n`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+
     const { installHook } = await import('./lib/hook-installer.mjs');
     try {
       const result = await installHook({ cwd: process.cwd() });

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

@@ -43,23 +43,30 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} review ${s.dim('[--branch=BRANCH]')}   Code-review context brief from current branch`,
     `    ${s.brand('ticketlens')} standup ${s.dim('[--since=N]')}        Standup summary from git log  ${s.dim('(last 24h by default)')}`,
     `    ${s.brand('ticketlens')} compliance ${s.dim('<TICKET-KEY>')}    Check requirements coverage  ${s.dim('[Pro/Free 3/mo]')}`,
+    `    ${s.brand('ticketlens')} install-hooks ${s.dim('[--uninstall]')}  Git pre-push compliance gate`,
+    `    ${s.brand('ticketlens')} pr ${s.dim('<TICKET-KEY>')}             Assemble a PR description from ticket context`,
+    `    ${s.brand('ticketlens')} ledger ${s.dim('[--format=json|csv]')}  Export your signed usage ledger  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} history ${s.dim('<TICKET-KEY>')}       Urgency timeline for a ticket  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} stats ${s.dim('[options]')}            Personal response-time metrics from local history`,
     `    ${s.brand('ticketlens')} note add ${s.dim('--title=... [--ticket=KEY]')}  Save a Recall note  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} note delete ${s.dim('--id=... [--ticket=KEY]')}  Remove a note from your local vault  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} recall ${s.dim('<query|TICKET-KEY>')}   Search your saved Recall notes  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} recall sync                 Retry any notes stuck in the local queue  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} recall settings             Show effective retry-queue settings, fetched live  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
     `    ${s.brand('ticketlens')} license                     Show license status`,
     `    ${s.brand('ticketlens')} cache ${s.dim('[size|clear]')}          Manage attachment cache  ${s.dim('(try cache --help)')}`,
-    `    ${s.brand('ticketlens')} schedule ${s.dim('[--stop|--status]')}  Manage digest schedule  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} schedule ${s.dim('[--stop|--status|--local]')}  Manage digest schedule  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} cloud-keys ${s.dim('[add|remove|list|test]')}  Manage your encrypted AI provider keys  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} update-skill ${s.dim('[--dry-run]')}    Update /jtb skill in Claude Code and other AI assistants`,
     '',
     `  ${s.bold('GLOBAL OPTIONS')}`,
     '',
     `    ${s.brand('--no-input')}          Force non-interactive behavior even in a terminal`,
+    `    ${s.brand('-v')}, ${s.brand('--version')}       Show version and exit ${s.dim('(same as ticketlens version)')}`,
+    `    ${s.brand('clear')}               Alias for ${s.brand('cache clear')}`,
     '',
     `  ${s.bold('FETCH OPTIONS')}`,
     '',
@@ -78,6 +85,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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.brand('--template')}=${s.dim('SLUG')}    Apply a brief template ${s.dim('(full|quick|code-review, or custom [Team])')}`,
+    `    ${s.brand('--budget')}=${s.dim('N')}         Trim brief to fit a token budget  ${s.dim('[Pro]')}`,
     '',
     `  ${s.bold('TRIAGE OPTIONS')}`,
     '',
@@ -100,6 +108,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${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)')}`,
+    `    ${s.brand('--styled')}           Force ANSI-styled table output`,
     '',
     `  ${s.bold('EXAMPLES')}`,
     '',
@@ -444,15 +453,23 @@ export function printScheduleHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [
     '',
-    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('schedule')} ${s.dim('[--stop|--status]')}  ${s.dim('[Pro]')}`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('schedule')} ${s.dim('[--stop|--status|--local]')}  ${s.dim('[Pro]')}`,
     '',
     `  Set up a recurring digest email with your triage results. ${s.dim('[Pro]')}`,
     `  Runs an interactive wizard to configure day, time, and timezone.`,
+    `  Without Console login, falls back to local-only scheduling automatically —`,
+    `  no interactive wizard, no digest email, just a cron/LaunchAgent entry that`,
+    `  writes triage output to a file.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--stop')}        Cancel the active digest schedule`,
     `    ${s.brand('--status')}      Show current schedule configuration`,
+    `    ${s.brand('--time')}=${s.dim('HH:MM')}  Pre-fill delivery/run time ${s.dim('(skips the interactive prompt)')}`,
+    `    ${s.brand('--email')}=${s.dim('ADDR')}  Pre-fill delivery email ${s.dim('(Console-backed wizard only)')}`,
+    `    ${s.brand('--timezone')}=${s.dim('TZ')}  Pre-fill timezone ${s.dim('(Console-backed wizard only)')}`,
+    `    ${s.brand('--local')}       Local-only cron/LaunchAgent, no Console auth ${s.dim('(auto-detected when logged out)')}`,
+    `    ${s.brand('--save')}=${s.dim('FILE')}   Output file for local mode ${s.dim('(required with --local)')}`,
     `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
@@ -460,6 +477,7 @@ export function printScheduleHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens schedule`,
     `    ${s.dim('$')} ticketlens schedule --status`,
     `    ${s.dim('$')} ticketlens schedule --stop`,
+    `    ${s.dim('$')} ticketlens schedule --local --time=07:00 --save=./triage.txt`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');
@@ -710,6 +728,108 @@ export function printReviewHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printComplianceHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('compliance')} ${s.dim('<TICKET-KEY> [--profile=NAME]')}  ${s.dim('[Pro/Free 3/mo]')}`,
+    '',
+    `  Check your current branch's diff against the ticket's requirements.`,
+    `  Extracts candidate requirements from the ticket description and diffs`,
+    `  them against what the local git diff actually covers, reporting a`,
+    `  coverage percentage and a list of uncovered items.`,
+    '',
+    `  Used internally by the pre-push hook installed via ${s.brand('ticketlens install-hooks')}`,
+    `  (reads the threshold from ${s.dim('.ticketlens-hooks.json')}, default 80%).`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--profile')}=${s.dim('NAME')}  Use a specific Jira profile`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens compliance PROJ-123`,
+    `    ${s.dim('$')} ticketlens compliance PROJ-123 --profile=myteam`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printLedgerHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('ledger')} ${s.dim('[--format=json|csv]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Export your local usage ledger — a signed, tamper-evident record of`,
+    `  billable actions (AI calls, exports, etc). Verifiable offline via an`,
+    `  HMAC-SHA256 signature over {records, exportedAt}, keyed at ledger-key.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--format')}=${s.dim('json')}   Full record export with signature ${s.dim('(default)')}`,
+    `    ${s.brand('--format')}=${s.dim('csv')}    Flat CSV, no signature`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens ledger`,
+    `    ${s.dim('$')} ticketlens ledger --format=csv`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printPrHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('pr')} ${s.dim('<TICKET-KEY> [--profile=NAME]')}`,
+    '',
+    `  Assemble a pull-request description from a ticket's context —`,
+    `  summary, acceptance criteria, and linked issues, formatted as a`,
+    `  ready-to-paste PR body.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--profile')}=${s.dim('NAME')}  Use a specific Jira profile`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens pr PROJ-123`,
+    `    ${s.dim('$')} ticketlens pr PROJ-123 --profile=myteam`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
+export function printInstallHooksHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('install-hooks')} ${s.dim('[--uninstall]')}`,
+    '',
+    `  Installs a git pre-push hook that blocks a push when this branch's`,
+    `  compliance coverage (see ${s.brand('ticketlens compliance')}) is below 80%.`,
+    `  Appends to an existing pre-push hook rather than overwriting it;`,
+    `  calling it again is a no-op if already installed.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('--uninstall')}   Remove the hook, restoring any pre-existing pre-push content`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}     Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens install-hooks`,
+    `    ${s.dim('$')} ticketlens install-hooks --uninstall`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printUpdateSkillHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/hook-installer.mjs

@@ -79,3 +79,51 @@ export function installHook({ cwd = process.cwd(), threshold = 80, fsModule = fs
 
   return { installed: true, path: hookPath };
 }
+
+/**
+ * Removes a previously-installed compliance gate, leaving any pre-existing
+ * (non-ticketlens) pre-push hook content untouched. installHook() always
+ * appends its block last, prefixed with its own `#!/bin/sh` line — this
+ * strips from that shebang line (and one preceding blank line from the
+ * append's leading '\n', if present) through end of file. If nothing
+ * precedes that point, the file is deleted rather than left empty.
+ *
+ * @param {{ cwd?: string, fsModule?: typeof import('node:fs') }} [opts]
+ * @returns {{ uninstalled: true, path: string } | { skipped: true, reason: string }}
+ */
+export function uninstallHook({ cwd = process.cwd(), fsModule = fs } = {}) {
+  const hookPath = join(cwd, '.git', 'hooks', 'pre-push');
+
+  let existing;
+  try {
+    existing = fsModule.readFileSync(hookPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return { skipped: true, reason: 'No pre-push hook installed.' };
+    throw err;
+  }
+
+  if (!existing.includes(GUARD)) {
+    return { skipped: true, reason: 'No ticketlens compliance gate found in the pre-push hook.' };
+  }
+
+  const guardIdx = existing.indexOf(GUARD);
+  const shebangIdx = existing.lastIndexOf('#!/bin/sh\n', guardIdx);
+  let cutStart = shebangIdx;
+  if (cutStart > 0 && existing[cutStart - 1] === '\n') cutStart -= 1;
+
+  const remaining = existing.slice(0, cutStart);
+  if (remaining.trim() === '') {
+    fsModule.unlinkSync(hookPath);
+  } else {
+    fsModule.writeFileSync(hookPath, remaining, 'utf8');
+  }
+
+  const configPath = join(cwd, '.ticketlens-hooks.json');
+  try {
+    fsModule.unlinkSync(configPath);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  return { uninstalled: true, path: hookPath };
+}

package/skills/jtb/scripts/lib/schedule-wizard.mjs

@@ -252,6 +252,33 @@ export function buildLocalCronLine({ hour, minute, ticketlensBin, outputFile })
   return `${minute} ${hour} * * * ${ticketlensBin} triage '--save=${outputFile}' >> '${outputFile}.err' 2>&1`;
 }
 
+/**
+ * Decides whether `ticketlens schedule` should use the local-only path
+ * (runScheduleLocal) instead of the Console-backed wizard (runScheduleWizard)
+ * — explicit `--local`, or auto-detected whenever there's no cliToken at all,
+ * so a logged-out user gets a working local schedule instead of a hard
+ * "log in first" error.
+ *
+ * @param {{ cmdArgs?: string[], cliToken?: string|null }} opts
+ * @returns {boolean}
+ */
+export function shouldUseLocalSchedule({ cmdArgs = [], cliToken } = {}) {
+  return cmdArgs.includes('--local') || !cliToken;
+}
+
+/**
+ * Extracts the --time= and --save= flags local scheduling needs. Both are
+ * required by runScheduleLocal itself; this just does the string parsing.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {{ time?: string, outputFile?: string }}
+ */
+export function parseLocalScheduleFlags(cmdArgs = []) {
+  const time = cmdArgs.find(a => a.startsWith('--time='))?.split('=')[1];
+  const outputFile = cmdArgs.find(a => a.startsWith('--save='))?.split('=')[1];
+  return { time, outputFile };
+}
+
 /**
  * Set up a local-only scheduled triage (no Console auth, no cloud push).
  * Writes a cron/LaunchAgent entry that runs `ticketlens triage --save=FILE`.