@aholbreich/agent-skills 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,14 +1,18 @@
 # Changelog
 
-## Unreleased
+## 0.5.0 - 2026-05-07
 
 Added:
 
+- `confluence-browser-fetch` now verifies an authenticated Confluence REST session before fetching pages, avoiding false positives from Atlassian login-page cookies.
+- `jira-browser-fetch` now verifies an authenticated Jira REST session before issue, JQL, or backlog fetches, avoiding false positives from Atlassian login-page cookies.
 - `jira-browser-fetch --backlog URL|BOARD_ID` to fetch all issues from a Jira Software board backlog through the authenticated browser session.
 - Backlog manifests at `raw/jira-board-<board-id>-backlog.json` and a `backlogs` section in `raw/jira-browser-fetch-run.json`.
 - Documentation examples for natural-language user requests that should invoke the skills.
 - Recommended `npx skills add aholbreich/agent-skills -g` cross-agent install path, plus collision/update guidance for Pi and project-local overrides.
 - CI/package dry-run scripts that use `npm pack --dry-run` for compatibility with older local pnpm launchers.
+- `agent-skills install --skill NAME` and `--pick` to install only selected bundled skills from the fallback npx installer.
+- Browser fetchers now auto-detect common Chromium-compatible browsers (Chrome, Chromium, Brave, Edge, Vivaldi) instead of only trying `/usr/bin/google-chrome` unless `CHROME` is set.
 
 ## 0.1.0 - 2026-05-06
 

package/COMPATIBILITY.md

@@ -79,6 +79,14 @@ npx @aholbreich/agent-skills --target project-agents
 npx @aholbreich/agent-skills install --dir /path/to/skills
 ```
 
+Select one or more skills with `--skill`, or use the interactive picker:
+
+```bash
+npx @aholbreich/agent-skills install --skill jira-browser-fetch
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --skill confluence-browser-fetch
+npx @aholbreich/agent-skills install --pick
+```
+
 This fallback copies files. For symlinked, multi-agent installs, prefer `npx skills add aholbreich/agent-skills`.
 
 ## Collision behavior

package/README.md

@@ -29,7 +29,7 @@ See [`COMPATIBILITY.md`](COMPATIBILITY.md) for details, including collision beha
 ## Requirements
 
 - Node.js `>=22`.
-- Google Chrome or Chromium.
+- A Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Access to the Jira/Confluence site in the browser account you use.
 - Pi, or any Agent Skills-compatible harness, if you want skill discovery.
 
@@ -105,6 +105,20 @@ npx @aholbreich/agent-skills install --target codex
 npx @aholbreich/agent-skills install --target project
 ```
 
+Install only selected skills:
+
+```bash
+npx @aholbreich/agent-skills install --skill jira-browser-fetch
+npx @aholbreich/agent-skills install --skill confluence-browser-fetch
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --target project
+```
+
+Or use the dependency-free interactive picker:
+
+```bash
+npx @aholbreich/agent-skills install --pick
+```
+
 Overwrite existing installed skill directories:
 
 ```bash

package/SECURITY.md

@@ -8,10 +8,11 @@ These skills are local automation tools. They can fetch potentially sensitive Ji
 
 The Jira and Confluence fetchers:
 
-1. launch or reuse Chrome/Chromium with a dedicated local profile,
+1. launch or reuse a Chromium-compatible browser with a dedicated local profile,
 2. let you complete normal Atlassian SSO in the browser,
 3. read Atlassian cookies through the local Chrome DevTools protocol,
-4. call Atlassian REST endpoints with those cookies.
+4. verify those cookies represent an authenticated Jira/Confluence REST session,
+5. call Atlassian REST endpoints with those cookies.
 
 They do **not** require you to paste API tokens or cookies into chat.
 

package/bin/agent-skills.js

@@ -5,6 +5,7 @@ const fs = require('fs');
 const fsp = require('fs/promises');
 const os = require('os');
 const path = require('path');
+const readline = require('readline/promises');
 
 const packageRoot = path.resolve(__dirname, '..');
 const sourceSkillsDir = path.join(packageRoot, 'skills');
@@ -41,12 +42,16 @@ Commands:
 Options for install:
   --target NAME           pi | agents | claude | codex | openclaw | project | project-agents | project-claude | project-codex (default: agents)
   --dir PATH              Custom skills directory, overrides --target
+  --skill NAME            Install only selected skill(s); repeatable, comma-separated, or '*' for all
+  --pick                  Interactively choose which bundled skills to install
   --force                 Overwrite existing skill directories
   --dry-run               Show what would be copied without writing
 
 Examples:
   npx skills add aholbreich/agent-skills -g
   npx @aholbreich/agent-skills
+  npx @aholbreich/agent-skills install --skill jira-browser-fetch
+  npx @aholbreich/agent-skills install --pick
   npx @aholbreich/agent-skills install --target agents --force
   npx @aholbreich/agent-skills install --target pi --force
   npx @aholbreich/agent-skills install --target project
@@ -80,16 +85,72 @@ async function copyDir(src, dest) {
   await fsp.cp(src, dest, { recursive: true, force: true, errorOnExist: false });
 }
 
+function addSkillFilters(filters, value) {
+  if (!value) throw new Error('--skill requires a skill name');
+  for (const item of String(value).split(',')) {
+    const skill = item.trim();
+    if (skill) filters.push(skill);
+  }
+}
+
+function selectSkills(allSkills, filters) {
+  if (!filters.length || filters.includes('*')) return allSkills;
+  const known = new Set(allSkills);
+  const selected = [...new Set(filters)];
+  const unknown = selected.filter(skill => !known.has(skill));
+  if (unknown.length) {
+    throw new Error(`Unknown skill(s): ${unknown.join(', ')}. Available: ${allSkills.join(', ')}`);
+  }
+  return selected.sort();
+}
+
+function parsePickedSkills(answer, allSkills) {
+  const value = String(answer || '').trim();
+  if (!value || value === '*') return allSkills;
+  const selected = [];
+  for (const raw of value.split(',')) {
+    const token = raw.trim();
+    if (!token) continue;
+    if (/^\d+$/.test(token)) {
+      const index = Number(token) - 1;
+      if (index < 0 || index >= allSkills.length) throw new Error(`Invalid skill number: ${token}`);
+      selected.push(allSkills[index]);
+    } else {
+      selected.push(token);
+    }
+  }
+  return selectSkills(allSkills, selected);
+}
+
+async function pickSkills(allSkills) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('--pick requires an interactive terminal; use --skill NAME for non-interactive installs');
+  }
+  console.log('Bundled skills:');
+  allSkills.forEach((skill, index) => console.log(`  ${index + 1}) ${skill}`));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question('Install which skills? Enter numbers/names separated by commas, or blank for all: ');
+    return parsePickedSkills(answer, allSkills);
+  } finally {
+    rl.close();
+  }
+}
+
 async function install(args) {
   let target = 'agents';
   let customDir = '';
   let force = false;
   let dryRun = false;
+  let pick = false;
+  const skillFilters = [];
 
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--target') target = args[++i];
     else if (a === '--dir') customDir = args[++i];
+    else if (a === '--skill' || a === '-s') addSkillFilters(skillFilters, args[++i]);
+    else if (a === '--pick') pick = true;
     else if (a === '--force') force = true;
     else if (a === '--dry-run') dryRun = true;
     else if (a === '-h' || a === '--help') { usage(); return; }
@@ -99,11 +160,15 @@ async function install(args) {
   if (!customDir && !TARGETS[target]) {
     throw new Error(`Unknown target '${target}'. Valid targets: ${Object.keys(TARGETS).join(', ')}`);
   }
+  if (pick && skillFilters.length) {
+    throw new Error('Use either --pick or --skill, not both');
+  }
 
   const destRoot = path.resolve(expandHome(customDir || TARGETS[target]));
-  const skills = await listSkills();
+  const allSkills = await listSkills();
+  const skills = pick ? await pickSkills(allSkills) : selectSkills(allSkills, skillFilters);
 
-  console.log(`Installing ${skills.length} skill(s) to ${destRoot}`);
+  console.log(`Installing ${skills.length} of ${allSkills.length} skill(s) to ${destRoot}`);
   if (dryRun) console.log('Dry run: no files will be written.');
 
   if (!dryRun) await fsp.mkdir(destRoot, { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",

package/skills/confluence-browser-fetch/SKILL.md

@@ -2,14 +2,14 @@
 name: confluence-browser-fetch
 description: Fetch Confluence Cloud pages through an authenticated Chrome browser session when API tokens do not work, especially with Microsoft/SSO. Use to archive Confluence page JSON, storage/view HTML, browser HTML, attachments, CQL search results, or page descendants into a raw wiki folder.
 license: MIT
-compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and Google Chrome/Chromium with remote debugging. No npm dependencies.
+compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
 ---
 
 # Confluence Browser Fetch
 
 Use this skill when a user wants Confluence pages ingested into an LLM wiki `raw/` folder and normal Atlassian API-token auth is unavailable or inconvenient due to SSO.
 
-The script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Atlassian cookies via Chrome DevTools, and fetches Confluence REST data plus rendered page HTML and attachments.
+The script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Atlassian cookies via Chrome DevTools, verifies they represent an authenticated Confluence REST session, and fetches Confluence REST data plus rendered page HTML and attachments.
 
 ## Safety
 

package/skills/confluence-browser-fetch/references/usage.md

@@ -7,24 +7,25 @@ Confluence Cloud pages are often behind Microsoft/SSO. API-token Basic auth may
 1. Launching Chrome with a dedicated user profile.
 2. Letting the user complete normal SSO.
 3. Reading Atlassian cookies through local Chrome DevTools.
-4. Calling Confluence REST endpoints with those cookies.
+4. Verifying those cookies represent an authenticated Confluence REST session.
+5. Calling Confluence REST endpoints with those cookies.
 
 No cookie or API token needs to be pasted into chat.
 
 ## Requirements
 
 - Node.js 22+.
-- Google Chrome or Chromium.
+- A Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Access to the Confluence page with the logged-in account.
 
 Check:
 
 ```bash
 node --version
-which google-chrome || which chromium || which chromium-browser
+which google-chrome || which chromium || which chromium-browser || which brave-browser || which microsoft-edge
 ```
 
-If Chrome has a different path:
+The script auto-detects common Chromium-compatible browsers. If yours has a different path:
 
 ```bash
 CHROME=/path/to/chrome scripts/confluence-browser-fetch.js 123456
@@ -113,7 +114,7 @@ By default, pages with matching local `metadata.json` Confluence `version.number
 | `CONFLUENCE_REQUEST_TIMEOUT_SEC` | Per-request timeout, default `60` |
 | `CONFLUENCE_SKIP_UNCHANGED` | Set to `0` to disable default skip-unchanged behavior |
 | `CONFLUENCE_CHROME_PROFILE` | Dedicated Chrome profile dir |
-| `CHROME` | Chrome executable path |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
 
 ## Output Files
 
@@ -129,13 +130,17 @@ For each page:
 
 ## Troubleshooting
 
-### `no Atlassian cookies yet`
+### `no Atlassian cookies yet` / `not authenticated yet`
 
-Complete SSO in the Chrome window opened by the script.
+Complete SSO in the Chrome window opened by the script. Login-page cookies are not enough; the script waits until a Confluence REST session probe succeeds.
+
+### `Could not verify authenticated Confluence session`
+
+The browser did not reach an authenticated Confluence REST session before `--wait` expired. Complete SSO, confirm you can open the target Confluence site in that browser profile, then rerun or increase `--wait`.
 
 ### `Page failed HTTP 404`
 
-The authenticated user cannot see the page, or the page ID/site is wrong.
+After authentication is verified, this usually means the authenticated user cannot see the page, or the page ID/site is wrong.
 
 ### URL cannot be resolved
 

package/skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
+const fs = require('fs');
 const fsp = require('fs/promises');
 const os = require('os');
 const path = require('path');
@@ -115,8 +116,50 @@ async function waitDevtools() {
   throw new Error('Chrome DevTools endpoint did not start');
 }
 
+function isExecutable(file) {
+  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+function resolveBrowserCandidate(candidate) {
+  if (!candidate) return null;
+  if (candidate.includes(path.sep)) return isExecutable(candidate) ? candidate : null;
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const full = path.join(dir, candidate);
+    if (isExecutable(full)) return full;
+  }
+  return null;
+}
+
+function findBrowserExecutable() {
+  const candidates = [
+    process.env.CHROME,
+    process.env.CHROMIUM,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'brave-browser',
+    'brave',
+    'microsoft-edge',
+    'microsoft-edge-stable',
+    'vivaldi',
+    'vivaldi-stable',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolveBrowserCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error('Could not find a Chromium-compatible browser. Install Chrome/Chromium/Brave/Edge/Vivaldi or set CHROME=/path/to/browser.');
+}
+
 function launchChrome(url) {
-  const chrome = process.env.CHROME || '/usr/bin/google-chrome';
+  const browser = findBrowserExecutable();
   const args = [
     `--remote-debugging-port=${opts.port}`,
     '--remote-debugging-address=127.0.0.1',
@@ -126,13 +169,15 @@ function launchChrome(url) {
     '--no-default-browser-check',
     url,
   ];
-  const child = spawn(chrome, args, { detached: true, stdio: 'ignore' });
+  console.log(`Launching browser: ${browser}`);
+  const child = spawn(browser, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => console.error(`Failed to launch browser ${browser}: ${err.message}`));
   child.unref();
 }
 
 async function ensureBrowser(openUrl) {
   if (!(await devtoolsReady())) {
-    console.log(`Opening Chrome with reusable profile: ${opts.profileDir}`);
+    console.log(`Opening Chromium-compatible browser with reusable profile: ${opts.profileDir}`);
     launchChrome(openUrl || wikiBase);
   } else {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
@@ -246,6 +291,30 @@ async function fetchJson(url, cookie) {
   return { ...result, json };
 }
 
+async function verifyConfluenceSession(cookie) {
+  if (!cookie) return { ok: false, message: 'no Atlassian cookies yet' };
+
+  const probes = [
+    `${wikiBase}/rest/api/user/current`,
+    `${wikiBase}/rest/api/space?limit=1`,
+  ];
+
+  for (const url of probes) {
+    const result = await fetchJson(url, cookie);
+    if (result.status === 200 && result.json) return { ok: true, url };
+    if (result.status === 401 || result.status === 403) {
+      return { ok: false, message: `not authenticated yet (${result.status} from ${url})` };
+    }
+    if (result.status === 302 || result.status === 303) {
+      return { ok: false, message: `still redirected to login (${result.status} from ${url})` };
+    }
+    if (result.status === 404) continue;
+    return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
+  }
+
+  return { ok: false, message: 'could not verify Confluence session' };
+}
+
 async function getCookieWithWait(openUrl) {
   await ensureBrowser(openUrl || wikiBase);
   console.log(`If prompted in Chrome, complete SSO for: ${openUrl || wikiBase}`);
@@ -254,14 +323,19 @@ async function getCookieWithWait(openUrl) {
   while (Date.now() < deadline) {
     try {
       const cookie = await getCookieHeader();
-      if (cookie) return cookie;
-      last = 'no Atlassian cookies yet';
+      const session = await verifyConfluenceSession(cookie);
+      if (session.ok) {
+        process.stdout.write('\n');
+        console.log(`Authenticated Confluence session verified via ${session.url}`);
+        return cookie;
+      }
+      last = session.message;
     } catch (e) { last = e.message; }
     process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
-  throw new Error(`Could not get browser cookies. Last result: ${last}`);
+  throw new Error(`Could not verify authenticated Confluence session. Last result: ${last}`);
 }
 
 function cqlQuote(s) {

package/skills/jira-browser-fetch/SKILL.md

@@ -2,14 +2,14 @@
 name: jira-browser-fetch
 description: Fetch Jira issue raw data through an authenticated Chrome browser session when jira-cli/API tokens do not work, especially with Microsoft/SSO. Use to archive Jira issues, Jira Software board backlogs, JQL result sets, linked tickets, rendered HTML/XML, remote links, and attachments into a raw wiki folder.
 license: MIT
-compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and Google Chrome/Chromium with remote debugging. No npm dependencies.
+compatibility: Agent Skills standard. Tested with Pi; installable into Claude Code, Codex, OpenClaw/generic .agents skills directories. Requires Node.js 22+ with built-in fetch/WebSocket and a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
 ---
 
 # Jira Browser Fetch
 
 Use this skill when Jira API-token authentication fails or the organization uses Microsoft/SSO and the user wants Jira issues, Jira Software board backlogs, or JQL result sets archived into a local raw/wiki folder.
 
-The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, and fetches Jira REST/HTML/XML/attachments into a raw directory.
+The bundled script opens/reuses Chrome with a dedicated profile, lets the user complete SSO once, extracts Jira cookies via Chrome DevTools, verifies they represent an authenticated Jira REST session, and fetches Jira REST/HTML/XML/attachments into a raw directory.
 
 ## Safety
 

package/skills/jira-browser-fetch/references/usage.md

@@ -7,13 +7,14 @@ Some Jira Cloud organizations use Microsoft/SSO and block or break API-token Bas
 1. Launching Chrome with a dedicated user profile.
 2. Letting the user complete normal SSO in Chrome.
 3. Reading Jira cookies through the local Chrome DevTools protocol.
-4. Calling Jira REST endpoints with those cookies.
+4. Verifying those cookies represent an authenticated Jira REST session.
+5. Calling Jira REST endpoints with those cookies.
 
 No token or cookie needs to be pasted into chat.
 
 ## Requirements
 
-- Linux/macOS with Chrome or Chromium.
+- Linux/macOS with a Chromium-compatible browser: Chrome, Chromium, Brave, Edge, or Vivaldi.
 - Node.js 22+.
 - Network access to the Jira site.
 
@@ -21,10 +22,10 @@ Check:
 
 ```bash
 node --version
-which google-chrome || which chromium || which chromium-browser
+which google-chrome || which chromium || which chromium-browser || which brave-browser || which microsoft-edge
 ```
 
-If Chrome has a different path:
+The script auto-detects common Chromium-compatible browsers. If yours has a different path:
 
 ```bash
 CHROME=/path/to/chrome scripts/jira-browser-fetch.js PROJ-123
@@ -125,7 +126,7 @@ Default max attachment download size is `5mb`. Use `--max-attachment-size unlimi
 | `JIRA_MAX_SEARCH_RESULTS` | Max issues added per JQL or backlog search, default `1000` |
 | `JIRA_MAX_ATTACHMENT_SIZE` / `JIRA_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |
 | `JIRA_CHROME_PROFILE` | Dedicated Chrome profile dir |
-| `CHROME` | Chrome executable path |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
 
 ## Example user requests
 
@@ -139,17 +140,21 @@ Agents should invoke this skill for requests such as:
 
 ## Troubleshooting
 
-### `no Jira cookies yet`
+### `no Atlassian cookies yet` / `not authenticated yet`
 
-Complete SSO in the Chrome window opened by the script.
+Complete SSO in the Chrome window opened by the script. Login-page cookies are not enough; the script waits until a Jira REST session probe succeeds.
+
+### `Could not verify authenticated Jira session`
+
+The browser did not reach an authenticated Jira REST session before `--wait` expired. Complete SSO, confirm you can open the target Jira site in that browser profile, then rerun or increase `--wait`.
 
 ### `HTTP 404 Issue does not exist or you do not have permission`
 
 The session works, but the account cannot see the issue or the key is not a Jira issue.
 
-### Chrome does not open
+### Browser does not open
 
-Set the executable path:
+The script tries `CHROME`, `CHROMIUM`, then common Chrome/Chromium/Brave/Edge/Vivaldi executable names and macOS app paths. If auto-detection fails, set the executable path:
 
 ```bash
 CHROME=/usr/bin/chromium scripts/jira-browser-fetch.js PROJ-123

package/skills/jira-browser-fetch/scripts/jira-browser-fetch.js

@@ -128,8 +128,50 @@ async function waitDevtools() {
   throw new Error('Chrome DevTools endpoint did not start');
 }
 
+function isExecutable(file) {
+  try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
+}
+
+function resolveBrowserCandidate(candidate) {
+  if (!candidate) return null;
+  if (candidate.includes(path.sep)) return isExecutable(candidate) ? candidate : null;
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const full = path.join(dir, candidate);
+    if (isExecutable(full)) return full;
+  }
+  return null;
+}
+
+function findBrowserExecutable() {
+  const candidates = [
+    process.env.CHROME,
+    process.env.CHROMIUM,
+    'google-chrome',
+    'google-chrome-stable',
+    'chromium',
+    'chromium-browser',
+    'brave-browser',
+    'brave',
+    'microsoft-edge',
+    'microsoft-edge-stable',
+    'vivaldi',
+    'vivaldi-stable',
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    '/Applications/Vivaldi.app/Contents/MacOS/Vivaldi',
+  ];
+  for (const candidate of candidates) {
+    const resolved = resolveBrowserCandidate(candidate);
+    if (resolved) return resolved;
+  }
+  throw new Error('Could not find a Chromium-compatible browser. Install Chrome/Chromium/Brave/Edge/Vivaldi or set CHROME=/path/to/browser.');
+}
+
 function launchChrome(url) {
-  const chrome = process.env.CHROME || '/usr/bin/google-chrome';
+  const browser = findBrowserExecutable();
   const args = [
     `--remote-debugging-port=${opts.port}`,
     '--remote-debugging-address=127.0.0.1',
@@ -139,7 +181,9 @@ function launchChrome(url) {
     '--no-default-browser-check',
     url,
   ];
-  const child = spawn(chrome, args, { detached: true, stdio: 'ignore' });
+  console.log(`Launching browser: ${browser}`);
+  const child = spawn(browser, args, { detached: true, stdio: 'ignore' });
+  child.on('error', err => console.error(`Failed to launch browser ${browser}: ${err.message}`));
   child.unref();
 }
 
@@ -223,21 +267,57 @@ async function fetchJson(url, cookie, accept) {
   return { ...result, json };
 }
 
+async function verifyJiraSession(cookie) {
+  if (!cookie) return { ok: false, message: 'no Atlassian cookies yet' };
+
+  const probes = [
+    `${opts.server}/rest/api/3/myself`,
+    `${opts.server}/rest/api/2/myself`,
+  ];
+
+  for (const url of probes) {
+    const result = await fetchJson(url, cookie, 'application/json');
+    if (result.status === 200 && result.json && (result.json.accountId || result.json.name || result.json.key || result.json.displayName)) {
+      return { ok: true, url };
+    }
+    if (result.status === 200) {
+      const kind = result.json ? 'unexpected JSON response' : (/html/i.test(result.contentType) ? 'login page' : 'non-JSON response');
+      return { ok: false, message: `not authenticated yet (${kind} from ${url})` };
+    }
+    if (result.status === 401 || result.status === 403) {
+      return { ok: false, message: `not authenticated yet (${result.status} from ${url})` };
+    }
+    if (result.status === 302 || result.status === 303) {
+      return { ok: false, message: `still redirected to login (${result.status} from ${url})` };
+    }
+    if (result.status === 404) continue;
+    return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
+  }
+
+  return { ok: false, message: 'could not verify Jira session' };
+}
+
 async function getCookieWithWait(openUrl) {
   await ensureBrowser(openUrl || `${opts.server}/`);
+  console.log(`If prompted in Chrome, complete SSO for: ${openUrl || opts.server}`);
   const deadline = Date.now() + opts.waitSec * 1000;
   let last = '';
   while (Date.now() < deadline) {
     try {
       const cookie = await getCookieHeader();
-      if (cookie) return cookie;
-      last = 'no Jira cookies yet';
+      const session = await verifyJiraSession(cookie);
+      if (session.ok) {
+        process.stdout.write('\n');
+        console.log(`Authenticated Jira session verified via ${session.url}`);
+        return cookie;
+      }
+      last = session.message;
     } catch (e) { last = e.message; }
     process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
-  throw new Error(`Could not get Jira browser cookies. Last result: ${last}`);
+  throw new Error(`Could not verify authenticated Jira session. Last result: ${last}`);
 }
 
 async function searchJql(jql) {
@@ -271,21 +351,16 @@ async function searchJql(jql) {
   return [...new Set(found)];
 }
 
-async function fetchBacklogPageWithWait(url) {
+async function fetchBacklogPageWithWait(url, cookie) {
   const deadline = Date.now() + opts.waitSec * 1000;
   let last = '';
   while (Date.now() < deadline) {
     try {
-      const cookie = await getCookieHeader();
-      if (!cookie) {
-        last = 'no Jira cookies yet';
-      } else {
-        const result = await fetchJson(url, cookie, 'application/json');
-        if (result.status === 200 && result.json && Array.isArray(result.json.issues)) return result.json;
-        last = `HTTP ${result.status} ${(result.text || '').slice(0, 180).replace(/\s+/g, ' ')}`;
-      }
+      const result = await fetchJson(url, cookie, 'application/json');
+      if (result.status === 200 && result.json && Array.isArray(result.json.issues)) return result.json;
+      last = `HTTP ${result.status} ${(result.text || '').slice(0, 180).replace(/\s+/g, ' ')}`;
     } catch (e) { last = e.message; }
-    process.stdout.write(`\r${new Date().toLocaleTimeString()} waiting for authenticated Jira backlog session: ${last.padEnd(120).slice(0, 120)}`);
+    process.stdout.write(`\r${new Date().toLocaleTimeString()} waiting for Jira backlog access: ${last.padEnd(120).slice(0, 120)}`);
     await sleep(3000);
   }
   process.stdout.write('\n');
@@ -294,8 +369,7 @@ async function fetchBacklogPageWithWait(url) {
 
 async function searchBacklog(input) {
   const backlog = parseBacklogInput(input, opts.server);
-  await ensureBrowser(backlog.browseUrl);
-  console.log(`If prompted in Chrome, complete SSO for: ${backlog.browseUrl}`);
+  const cookie = await getCookieWithWait(backlog.browseUrl);
   console.log(`Waiting up to ${opts.waitSec}s for Jira backlog access...`);
 
   const found = [];
@@ -305,7 +379,7 @@ async function searchBacklog(input) {
   while (found.length < opts.maxSearchResults) {
     const limit = Math.min(pageSize, opts.maxSearchResults - found.length);
     const url = backlogApiUrl(opts.server, backlog.boardId, startAt, limit);
-    const page = await fetchBacklogPageWithWait(url);
+    const page = await fetchBacklogPageWithWait(url, cookie);
     const keys = issueKeysFromAgilePage(page);
     for (const key of keys) found.push(key);
     console.log(`Fetched backlog page board=${backlog.boardId} startAt=${startAt}, issues=${keys.length}${typeof page.total === 'number' ? `, total=${page.total}` : ''}`);
@@ -426,7 +500,7 @@ async function downloadAttachments(issueJson, cookie, outDir) {
 
 async function ensureBrowser(browseUrl) {
   if (!(await devtoolsReady())) {
-    console.log(`Opening Chrome with reusable profile: ${opts.profileDir}`);
+    console.log(`Opening Chromium-compatible browser with reusable profile: ${opts.profileDir}`);
     launchChrome(browseUrl);
   } else {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
@@ -443,32 +517,11 @@ async function fetchIssue(issue) {
   const remoteLinksUrl = `${opts.server}/rest/api/3/issue/${issue}/remotelink`;
   const xmlUrl = `${opts.server}/si/jira.issueviews:issue-xml/${issue}/${issue}.xml`;
 
-  await ensureBrowser(browseUrl);
-  console.log(`If prompted in Chrome, complete SSO for: ${browseUrl}`);
-  console.log(`Waiting up to ${opts.waitSec}s for Jira session...`);
-
-  const deadline = Date.now() + opts.waitSec * 1000;
-  let last = '';
-  let cookie = '';
-  let rest = null;
-
-  while (Date.now() < deadline) {
-    try {
-      cookie = await getCookieHeader();
-      if (cookie) {
-        rest = await fetchText(restUrl, cookie, 'application/json');
-        const body = rest.text || '';
-        if (rest.status === 200 && body.includes(`"key":"${issue}"`)) break;
-        last = `HTTP ${rest.status} ${body.slice(0, 110).replace(/\s+/g, ' ')}`;
-      } else last = 'no Jira cookies yet';
-    } catch (e) { last = e.message; }
-    process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
-    await sleep(3000);
-  }
-  process.stdout.write('\n');
+  const cookie = await getCookieWithWait(browseUrl);
 
-  if (!rest || rest.status !== 200 || !rest.text.includes(`"key":"${issue}"`)) {
-    throw new Error(`Could not fetch ${issue}. Last result: ${last}`);
+  const rest = await fetchJson(restUrl, cookie, 'application/json');
+  if (rest.status !== 200 || !rest.json || rest.json.key !== issue) {
+    throw new Error(`Could not fetch ${issue}. HTTP ${rest.status}: ${(rest.text || '').slice(0, 300).replace(/\s+/g, ' ')}`);
   }
 
   await fsp.writeFile(path.join(outDir, 'issue.json'), rest.text);