@aholbreich/agent-skills 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,10 +1,39 @@
 # Changelog
 
-## Unreleased
+## 1.1.0 - 2026-05-11
 
-(empty)
+Added:
+
+- `jira-browser-fetch --skip-existing` skips issues that already have a valid `raw/<KEY>/issue.json`, reading the saved `connected-keys.json` so `--connected --scan-text` traversal still resumes correctly.
+- `jira-browser-fetch` prints aggregate progress (`[N/total] pct%`) and a trailing ETA line during multi-issue runs.
+- `confluence-update` and `confluence-browser-fetch` emit a clearer error when Confluence probes return 404. After all wikiBase probes 404, the verifier does one sanity probe against the Jira API at the same site root; if that succeeds, the error specifically says "cookies are valid for ${site} but Confluence at ${wikiBase} returned 404", pointing to either a wrong `--site` or a tenant without Confluence enabled.
+- README gains a "Project status" section flagging the opinionated browser-only auth approach, Linux-Fedora-only end-to-end testing, and a feedback request.
+- Every SKILL.md's "Shared Atlassian SSO Session" section now teaches calling agents three things: (i) the script-Chrome is a separate window from the user's regular browser, cookies from the user's Chrome are not read; (ii) reuse signal — `Reusing Chrome DevTools on port 9223` / `Found existing tab for <host>` means do not re-prompt SSO; (iii) `CHROME=/path/to/launcher` env var for Flatpak/Snap/non-PATH installs. The Typical Workflow's SSO step is clarified to be first-run-or-expired-only.
+
+Changed:
+
+- The "Reuse one Atlassian browser login" section in README now reflects the unified-defaults behavior — no env vars required for the default sharing.
+- **Unified Chrome profile and DevTools port across all five Atlassian skills.** Defaults are now `~/.local/share/atlassian-browser-chrome` and port `9223` for `jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, and `bitbucket-browser-fetch`. One SSO login persists across all skills — no env vars required. Skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars still override for isolation. Each SKILL.md gains a "Shared Atlassian SSO Session" section near the top.
+- `confluence-update` and `confluence-browser-fetch` now strip a trailing `/wiki` from `--site` (or `CONFLUENCE_SITE`) with a stderr note, instead of building the unreachable `…/wiki/wiki` URL.
+- Replaced the 19-step `npm run check` chain with a `bin/check.js` script that auto-discovers `bin/`, `lib/`, and every `skills/*/scripts/` JS file. Aggregates failures (no longer stops at the first error) and prints a summary line. New skills/scripts are picked up automatically with no `package.json` edit.
+
+Migration:
+
+- Users who previously logged in via the old per-skill profiles (`~/.local/share/jira-browser-fetch-chrome`, `confluence-browser-fetch-chrome`, `bitbucket-browser-fetch-chrome`) will hit a fresh login on first run after upgrade. To preserve the existing session, move whichever profile you used: `mv ~/.local/share/jira-browser-fetch-chrome ~/.local/share/atlassian-browser-chrome` (only one — pick the one with your live cookies). Or just re-SSO once; the new shared profile then serves all five skills.
+
+## 1.0.1 - 2026-05-09
+
+Added:
+
+- `jira-update <command> --help` and `confluence-update <command> --help` now print command-specific options instead of falling back to top-level usage.
+- `jira-update transition --help` documents the `--field key=value` heuristics (`priority`/`resolution`/`status` wrap as `{name: VALUE}`; `labels`/`components`/`fixVersions` split on commas; everything else passes through as a string).
+- `jira-update` validates issue keys client-side (`PROJ-123` form). `comment`, `transition`, `update-fields`, `link <FROM>`, and `link --to <TO>` fail fast with exit 2 instead of round-tripping a bad key through SSO and the Jira REST API.
+
+Changed:
+
+- `jira-update` validation errors (missing manifest fields, unresolved transitions/link types, bad representation) now exit 2 with a clean `error: ...` message instead of dumping a Node stack trace and exiting 1. Implemented via a new `UsageError` class in `skills/jira-update/scripts/lib.js`.
 
-## 0.10.0 - 2026-05-08
+## 1.0.0 - 2026-05-08
 
 Added:
 

package/README.md

@@ -1,8 +1,24 @@
 # Agent Skills
 
-Handcrafted [Agent Skills](https://agentskills.io/) for developer and LLM-wiki workflows. The package is intentionally a pure skills package with broad compatibility across Pi, Claude Code, Codex, OpenClaw/generic `.agents` setups, and other Agent Skills-compatible harnesses.
+**Browser-authenticated Atlassian write surface for SSO-locked organizations.** Five [Agent Skills](https://agentskills.io/) covering Jira read+write, Confluence read+write, and Bitbucket read — designed for orgs where Microsoft/SSO blocks API-token use.
 
-This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetch and update tools (Jira read+write, Confluence read+write, Bitbucket read) that work well when Jira/Confluence/Bitbucket API-token authentication is unavailable because an organization uses Microsoft/SSO.
+The package is a pure Agent Skills bundle, compatible with Pi, Claude Code, Codex, OpenClaw / generic `.agents` setups, and other Agent Skills-compatible harnesses.
+
+## Why this exists
+
+Most Atlassian automation tools assume API tokens. In SSO-locked enterprises, API tokens are often disabled or restricted in ways that make scripted writes painful. These skills route through an authenticated **browser session** instead — you log in to Jira/Confluence/Bitbucket once in Chrome, and the skills replay your cookies via DevTools to make REST calls. No API token required.
+
+Beyond the SSO bypass, the skills are built around three differentiators:
+
+- **Dry-run-first writes.** Every write command (`jira-update create`, `confluence-update replace-block`, etc.) emits a full audit folder under `raw/` first. You only get a real write when you re-run with `--apply`. Each audit folder contains the proposed payload, the before-state, and a diff summary — review exactly what would happen before it does.
+- **Markdown → ADF conversion.** `jira-update` converts Markdown to Atlassian Document Format (Jira Cloud's structured rich-text representation), so agents write descriptions, comments, and transitions in a familiar format without hand-rolling ADF JSON.
+- **Shared browser session.** All Atlassian skills can reuse a single Chrome profile + DevTools port, so you log in once and every fetch/update skill rides the same SSO session.
+
+## Project status
+
+Opinionated bundle: SSO browser-session auth only, no API tokens or app passwords. The whole stack is built around extracting Chrome cookies via the DevTools Protocol — if API tokens already work for your org, you do not need this. All five Atlassian skills share one Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`) by default; log in once and the others reuse the session.
+
+**Tested on Linux (Fedora) at the moment.** macOS browser paths exist in the auto-detection logic but are not end-to-end verified; Windows is unsupported. Reports of what works on other distros or OSes are very welcome — open an issue or PR at [github.com/aholbreich/agent-skills/issues](https://github.com/aholbreich/agent-skills/issues). Feedback on SSO flavors, browser detection, profile/port collisions, and unusual Atlassian tenant shapes is especially useful.
 
 ## Skills
 
@@ -102,18 +118,22 @@ npx @aholbreich/agent-skills
 Install for a specific target:
 
 ```bash
-npx @aholbreich/agent-skills install --target agents
-npx @aholbreich/agent-skills install --target claude
-npx @aholbreich/agent-skills install --target codex
-npx @aholbreich/agent-skills install --target project
+npx @aholbreich/agent-skills install --target agents          # ~/.agents/skills (default)
+npx @aholbreich/agent-skills install --target claude          # ~/.claude/skills
+npx @aholbreich/agent-skills install --target codex           # ~/.codex/skills
+npx @aholbreich/agent-skills install --target pi              # ~/.pi/agent/skills
+npx @aholbreich/agent-skills install --target project-agents  # ./.agents/skills
+npx @aholbreich/agent-skills install --target project-pi      # ./.pi/skills
 ```
 
+The bare `--target project` is a deprecated alias for `--target project-pi`; use the explicit form. Run `npx @aholbreich/agent-skills paths` to see every target's full path.
+
 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
+npx @aholbreich/agent-skills install --skill jira-browser-fetch --target project-agents
 ```
 
 Or use the dependency-free interactive picker:
@@ -185,14 +205,16 @@ bitbucket-browser-fetch
 
 ## Reuse one Atlassian browser login
 
-To avoid separate Jira and Confluence SSO prompts, use one shared automation profile and DevTools port for both fetchers:
+All five skills share one Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`) by default. Log in once via any skill and the others ride the same SSO session — no env vars required.
+
+To relocate the shared profile or run on a different port:
 
 ```bash
-export ATLASSIAN_CHROME_PROFILE="$HOME/.local/share/atlassian-browser-fetch-chrome"
-export ATLASSIAN_CHROME_DEBUG_PORT=9223
+export ATLASSIAN_CHROME_PROFILE="$HOME/some/other/path"
+export ATLASSIAN_CHROME_DEBUG_PORT=9333
 ```
 
-Skill-specific variables such as `JIRA_CHROME_PROFILE`, `CONFLUENCE_CHROME_PROFILE`, or `BITBUCKET_CHROME_PROFILE` still override the shared profile when needed.
+Skill-specific variables (`JIRA_CHROME_PROFILE`, `CONFLUENCE_CHROME_PROFILE`, `BITBUCKET_CHROME_PROFILE`, and the matching `*_CHROME_DEBUG_PORT`) override the shared values when you intentionally want skill isolation.
 
 ## Bitbucket examples
 
@@ -375,9 +397,9 @@ Disable the limit:
 --max-attachment-size unlimited
 ```
 
-## Output and LLM wiki use
+## Example workflow: populating an LLM wiki
 
-The tools are designed to populate a wiki `raw/` folder. They do not synthesize pages themselves. A typical LLM wiki workflow is:
+One common use case for the fetch skills is feeding an LLM-curated knowledge base. The tools populate a `raw/` evidence folder; they do not synthesize pages themselves. A typical pipeline:
 
 1. fetch Jira/Confluence sources into `raw/`,
 2. treat `raw/` as immutable evidence,

package/bin/agent-skills.js

@@ -40,7 +40,10 @@ Commands:
   help                    Show this help
 
 Options for install:
-  --target NAME           pi | agents | claude | codex | openclaw | project | project-agents | project-claude | project-codex (default: agents)
+  --target NAME           Install destination (default: agents). Run "agent-skills paths" for full paths.
+                          User-scoped:    pi | agents | claude | codex | openclaw
+                          Project-scoped: project-pi | project-agents | project-claude | project-codex
+                          Deprecated:     project (alias for project-pi)
   --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
@@ -54,10 +57,10 @@ Examples:
   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
+  npx @aholbreich/agent-skills install --target project-agents
+  npx @aholbreich/agent-skills install --target project-pi
   npx @aholbreich/agent-skills install --target claude
   npx @aholbreich/agent-skills install --target codex
-  npx @aholbreich/agent-skills install --target agents
   npx @aholbreich/agent-skills install --dir ~/.pi/agent/skills
   npx @aholbreich/agent-skills list
 
@@ -160,6 +163,9 @@ async function install(args) {
   if (!customDir && !TARGETS[target]) {
     throw new Error(`Unknown target '${target}'. Valid targets: ${Object.keys(TARGETS).join(', ')}`);
   }
+  if (target === 'project' && !customDir) {
+    console.warn('warning: --target project is deprecated; it maps to ./.pi/skills. Use --target project-pi for the same path or --target project-agents for ./.agents/skills.');
+  }
   if (pick && skillFilters.length) {
     throw new Error('Use either --pick or --skill, not both');
   }
@@ -193,9 +199,9 @@ async function install(args) {
   }
 
   console.log(`Done. Installed: ${installed}. Skipped: ${skipped}.`);
-  if (target.startsWith('project') && !customDir) {
+  if ((target === 'project' || target.startsWith('project-')) && !customDir) {
     console.log('Project-local skills are available when running an Agent Skills-compatible tool inside this project.');
-  } else if (target === 'pi' && !customDir) {
+  } else if ((target === 'pi' || target === 'project-pi') && !customDir) {
     console.log('Restart Pi or start a new session to discover newly installed skills.');
   }
 }

package/bin/check.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '..');
+
+async function listJsFiles(dir) {
+  let entries;
+  try {
+    entries = await fsp.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const out = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...await listJsFiles(full));
+    else if (entry.isFile() && entry.name.endsWith('.js')) out.push(full);
+  }
+  return out;
+}
+
+async function collectTargets() {
+  const files = [];
+  for (const d of ['bin', 'lib']) files.push(...await listJsFiles(path.join(repoRoot, d)));
+  const skillsDir = path.join(repoRoot, 'skills');
+  for (const entry of await fsp.readdir(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    files.push(...await listJsFiles(path.join(skillsDir, entry.name, 'scripts')));
+  }
+  return files.sort();
+}
+
+async function main() {
+  const verbose = process.argv.includes('--verbose');
+  const skipVendor = process.argv.includes('--no-vendor');
+
+  if (!skipVendor) {
+    const vendor = spawnSync(process.execPath, [path.join(repoRoot, 'bin/vendor.js')], { stdio: 'inherit' });
+    if (vendor.status !== 0) process.exit(vendor.status || 1);
+  }
+
+  const targets = await collectTargets();
+  const failures = [];
+  const start = Date.now();
+  for (const file of targets) {
+    const rel = path.relative(repoRoot, file);
+    const result = spawnSync(process.execPath, ['--check', file], { encoding: 'utf8' });
+    if (result.status === 0) {
+      if (verbose) console.log(`ok  ${rel}`);
+    } else {
+      console.error(`FAIL ${rel}`);
+      failures.push({ rel, stderr: result.stderr });
+    }
+  }
+  const ms = Date.now() - start;
+
+  if (failures.length) {
+    console.error(`\n${failures.length} file(s) failed syntax check:`);
+    for (const f of failures) {
+      console.error(`\n--- ${f.rel} ---`);
+      console.error(f.stderr.trim());
+    }
+    process.exit(1);
+  }
+  console.log(`Syntax-checked ${targets.length} file(s) in ${ms}ms.`);
+}
+
+module.exports = { collectTargets, listJsFiles };
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(err.stack || err.message);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -44,7 +44,7 @@
   },
   "scripts": {
     "vendor": "node bin/vendor.js",
-    "check": "node --check bin/agent-skills.js && node --check bin/vendor.js && node --check lib/atlassian-browser.js && npm run vendor && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/jira-browser-fetch/scripts/atlassian-browser.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/atlassian-browser.js && node --check skills/confluence-update/scripts/confluence-update.js && node --check skills/confluence-update/scripts/lib.js && node --check skills/confluence-update/scripts/atlassian-browser.js && node --check skills/bitbucket-browser-fetch/scripts/bitbucket-browser-fetch.js && node --check skills/bitbucket-browser-fetch/scripts/lib.js && node --check skills/bitbucket-browser-fetch/scripts/atlassian-browser.js && node --check skills/jira-update/scripts/jira-update.js && node --check skills/jira-update/scripts/lib.js && node --check skills/jira-update/scripts/atlassian-browser.js",
+    "check": "node bin/check.js",
     "pretest": "npm run vendor",
     "test": "node --test",
     "ci": "npm run check && npm test && npm pack --dry-run",

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

@@ -36,6 +36,20 @@ Important options:
 --profile-dir DIR  Chrome profile dir
 ```
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+Bitbucket sits on `bitbucket.org` rather than `*.atlassian.net`, so its cookies are scoped separately, but sharing one Chrome profile/port still avoids spawning extra browser windows.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-login — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Example
 
 ```bash

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

@@ -25,8 +25,8 @@ Options:
   --raw-dir DIR             Output raw directory (default: BITBUCKET_RAW_DIR or ./raw)
   --pagelen N               Internal API page size (default: 100)
   --wait SEC                Wait time for login/session (default: 900)
-  --port PORT               Chrome DevTools port (default: BITBUCKET_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9224)
-  --profile-dir DIR         Chrome profile dir (default: BITBUCKET_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/bitbucket-browser-fetch-chrome)
+  --port PORT               Chrome DevTools port (default: BITBUCKET_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
+  --profile-dir DIR         Chrome profile dir (default: BITBUCKET_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/atlassian-browser-chrome)
   --help                    Show this help
 
 Examples:
@@ -39,9 +39,9 @@ const opts = {
   workspace: '',
   projectKey: '',
   rawDir: process.env.BITBUCKET_RAW_DIR || path.resolve(process.cwd(), 'raw'),
-  port: Number(process.env.BITBUCKET_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9224),
+  port: Number(process.env.BITBUCKET_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9223),
   waitSec: Number(process.env.BITBUCKET_FETCH_WAIT_SEC || 900),
-  profileDir: process.env.BITBUCKET_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/bitbucket-browser-fetch-chrome'),
+  profileDir: process.env.BITBUCKET_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/atlassian-browser-chrome'),
   pagelen: Number(process.env.BITBUCKET_PAGELEN || 100),
 };
 

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

@@ -43,15 +43,26 @@ Important options:
 --no-browser-html        skip rendered browser HTML
 ```
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-SSO — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Typical Workflow
 
 1. If the user gives a Confluence URL, run the script directly with that URL.
 2. If the user gives a title, ask for the space key or use `--cql`.
 3. Show the command before running it.
-4. If Chrome opens, ask the user to complete SSO in that browser window.
-5. To share one Atlassian SSO login with `jira-browser-fetch`, use `ATLASSIAN_CHROME_PROFILE` plus `ATLASSIAN_CHROME_DEBUG_PORT` (or matching `--profile-dir` and `--port`) for both tools.
-6. Verify saved files.
-7. If this is an LLM wiki ingest, process the saved `raw/confluence/...` material into `wiki/` per the project `AGENTS.md`.
+4. If Chrome opens (first run or expired session), ask the user to complete SSO in that window. On subsequent invocations the script reuses the session silently — see the Reuse signal above.
+5. Verify saved files.
+6. If this is an LLM wiki ingest, process the saved `raw/confluence/...` material into `wiki/` per the project `AGENTS.md`.
 
 Example:
 

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

@@ -6,12 +6,16 @@ This skill follows Pi / Agent Skills layout:
 confluence-browser-fetch/
 ├── SKILL.md
 ├── scripts/
-│   └── confluence-browser-fetch.js
+│   ├── atlassian-browser.js   # vendored from lib/atlassian-browser.js
+│   ├── confluence-browser-fetch.js
+│   └── lib.js
 └── references/
     ├── usage.md
     └── distribution.md
 ```
 
+`scripts/atlassian-browser.js` is vendored from `lib/atlassian-browser.js` at the repo root by `bin/vendor.js` (run via `npm run vendor`, and automatically before `npm test` and `npm pack`). The skill folder is self-contained, so copying just the `confluence-browser-fetch/` directory works once vendoring has happened. If you hand-copy from a fresh source checkout, run `npm run vendor` first or include all three files in `scripts/`.
+
 ## Install for Current User
 
 ```bash

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

@@ -106,8 +106,8 @@ By default, pages with matching local `metadata.json` Confluence `version.number
 |---|---|
 | `CONFLUENCE_SITE` | Default Atlassian site, e.g. `https://example.atlassian.net` |
 | `CONFLUENCE_RAW_DIR` | Default output raw directory |
-| `CONFLUENCE_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9224`; overrides `ATLASSIAN_CHROME_DEBUG_PORT` |
-| `ATLASSIAN_CHROME_DEBUG_PORT` | Shared Chrome DevTools port for Jira and Confluence browser fetchers. If only `ATLASSIAN_CHROME_PROFILE` is set, Confluence defaults to shared port `9223`. |
+| `CONFLUENCE_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9223`; overrides `ATLASSIAN_CHROME_DEBUG_PORT` |
+| `ATLASSIAN_CHROME_DEBUG_PORT` | Shared Chrome DevTools port for all Atlassian browser skills (Jira/Confluence/Bitbucket). Default `9223`. |
 | `CONFLUENCE_FETCH_WAIT_SEC` | Wait timeout, default `900` |
 | `CONFLUENCE_MAX_SEARCH_RESULTS` | Max CQL pages, default `200` |
 | `CONFLUENCE_MAX_ATTACHMENT_SIZE` / `CONFLUENCE_MAX_ATTACHMENT_BYTES` | Max attachment download size, default `5mb`; skipped files are listed in `attachments.json` |

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

@@ -29,8 +29,8 @@ Options:
   --retries N              HTTP retry count for transient failures (default: 3)
   --request-timeout SEC    Per-request timeout (default: 60)
   --wait SEC               Wait time for SSO/session (default: 900)
-  --port PORT              Chrome DevTools port (default: CONFLUENCE_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9224)
-  --profile-dir DIR        Chrome profile dir (default: CONFLUENCE_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/confluence-browser-fetch-chrome)
+  --port PORT              Chrome DevTools port (default: CONFLUENCE_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
+  --profile-dir DIR        Chrome profile dir (default: CONFLUENCE_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/atlassian-browser-chrome)
   --help                   Show this help
 
 Examples:
@@ -45,9 +45,9 @@ Examples:
 const opts = {
   site: process.env.CONFLUENCE_SITE || '',
   rawDir: process.env.CONFLUENCE_RAW_DIR || path.resolve(process.cwd(), 'raw'),
-  port: Number(process.env.CONFLUENCE_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || (process.env.ATLASSIAN_CHROME_PROFILE ? 9223 : 9224)),
+  port: Number(process.env.CONFLUENCE_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9223),
   waitSec: Number(process.env.CONFLUENCE_FETCH_WAIT_SEC || 900),
-  profileDir: process.env.CONFLUENCE_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/confluence-browser-fetch-chrome'),
+  profileDir: process.env.CONFLUENCE_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/atlassian-browser-chrome'),
   maxSearchResults: Number(process.env.CONFLUENCE_MAX_SEARCH_RESULTS || 200),
   retries: Number(process.env.CONFLUENCE_RETRIES || 3),
   requestTimeoutSec: Number(process.env.CONFLUENCE_REQUEST_TIMEOUT_SEC || 60),
@@ -89,6 +89,11 @@ for (let i = 2; i < process.argv.length; i++) {
 
 if (!inputs.length && !opts.titles.length && !opts.cqls.length) { usage(); process.exit(2); }
 opts.site = opts.site.replace(/\/$/, '');
+if (/\/wiki$/i.test(opts.site)) {
+  const stripped = opts.site.replace(/\/wiki$/i, '');
+  console.error(`Note: stripping trailing /wiki from --site (${opts.site} -> ${stripped}). Pass the site root, e.g. https://example.atlassian.net.`);
+  opts.site = stripped;
+}
 if (!opts.site) {
   console.error('Missing Atlassian site. Pass --site https://example.atlassian.net or set CONFLUENCE_SITE.');
   process.exit(2);
@@ -178,7 +183,14 @@ async function verifyConfluenceSession(cookie) {
     return { ok: false, message: `session probe HTTP ${result.status} from ${url}` };
   }
 
-  return { ok: false, message: 'could not verify Confluence session' };
+  try {
+    const sanity = await fetchJson(`${opts.site}/rest/api/3/myself`, cookie);
+    if (sanity.status === 200 && sanity.json && (sanity.json.accountId || sanity.json.displayName)) {
+      return { ok: false, message: `cookies are valid for ${opts.site} (Jira API responded) but Confluence at ${wikiBase} returned 404. Verify --site is the Atlassian site root (e.g. https://example.atlassian.net, without /wiki) and that Confluence is enabled on this tenant.` };
+    }
+  } catch {}
+
+  return { ok: false, message: `could not verify Confluence session at ${wikiBase}. Verify --site is the Atlassian site root (e.g. https://example.atlassian.net, without /wiki).` };
 }
 
 function getCookieWithWait(openUrl) {

package/skills/confluence-update/SKILL.md

@@ -49,6 +49,18 @@ Important options:
 --parent-id ID          parent page for create
 ```
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-SSO — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Typical Workflow
 
 1. Prefer `replace-block` when editing an agent-owned region.
@@ -56,8 +68,7 @@ Important options:
 3. Review `proposed.storage.html`, `payload.json`, and `update-run.json` under `raw/confluence-updates/`.
 4. Ask the user for approval.
 5. Re-run the same command with `--apply`.
-6. If Chrome opens, ask the user to complete SSO.
-7. To share one Atlassian SSO login with Jira/Confluence fetchers, use `ATLASSIAN_CHROME_PROFILE` plus `ATLASSIAN_CHROME_DEBUG_PORT`.
+6. If Chrome opens (first run or expired session), ask the user to complete SSO. On subsequent invocations the script reuses the session silently — see the Reuse signal above.
 
 ## Agent-owned blocks
 

package/skills/confluence-update/references/usage.md

@@ -103,8 +103,8 @@ The Markdown converter is intentionally simple: headings, paragraphs, unordered/
 |---|---|
 | `CONFLUENCE_SITE` | Default Atlassian site, e.g. `https://example.atlassian.net` |
 | `CONFLUENCE_UPDATE_RAW_DIR` / `CONFLUENCE_RAW_DIR` | Audit/output raw directory |
-| `CONFLUENCE_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9224`; overrides `ATLASSIAN_CHROME_DEBUG_PORT` |
-| `ATLASSIAN_CHROME_DEBUG_PORT` | Shared Chrome DevTools port for Jira/Confluence tools. If only `ATLASSIAN_CHROME_PROFILE` is set, Confluence update defaults to shared port `9223`. |
+| `CONFLUENCE_CHROME_DEBUG_PORT` | Chrome DevTools port, default `9223`; overrides `ATLASSIAN_CHROME_DEBUG_PORT` |
+| `ATLASSIAN_CHROME_DEBUG_PORT` | Shared Chrome DevTools port for all Atlassian browser skills (Jira/Confluence/Bitbucket). Default `9223`. |
 | `CONFLUENCE_UPDATE_WAIT_SEC` / `CONFLUENCE_FETCH_WAIT_SEC` | Wait timeout, default `900` |
 | `CONFLUENCE_CHROME_PROFILE` | Dedicated Chrome profile dir; overrides `ATLASSIAN_CHROME_PROFILE`. By default this uses the same profile as `confluence-browser-fetch`. |
 | `ATLASSIAN_CHROME_PROFILE` | Shared browser profile dir for Jira, Confluence fetch, and Confluence update tools |

package/skills/confluence-update/scripts/confluence-update.js

@@ -14,20 +14,7 @@ const {
   replaceMarkedBlock,
 } = lib;
 
-function usage() {
-  console.log(`Usage: confluence-update <command> [options]
-
-Safely update or create Confluence Cloud pages through an authenticated browser session.
-Dry-run is the default; pass --apply to write to Confluence.
-
-Commands:
-  update PAGE_ID_OR_URL        Replace an existing page body
-  replace-block PAGE_ID_OR_URL Replace only a marked agent-owned block
-  replace-text PAGE_ID_OR_URL  Replace an exact matched string in the page
-  replace-element PAGE_ID_OR_URL Replace an element by its local-id
-  create                       Create a new page
-
-Common options:
+const COMMON_OPTIONS = `Common options:
   --site URL                   Atlassian site base URL (or CONFLUENCE_SITE), e.g. https://example.atlassian.net
   --file FILE                  Input file containing storage XHTML or Markdown
   --representation REP         storage | markdown (default: storage)
@@ -40,26 +27,25 @@ Common options:
   --expected-version N|auto    Fail if current page version is not N. Use 'auto' to always overwrite (default: null)
   --apply                      Actually write. Without this, only dry-run/audit files are written
   --wait SEC                   Wait time for SSO/session (default: 900)
-  --port PORT                  Chrome DevTools port (default: CONFLUENCE_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9224)
-  --profile-dir DIR            Chrome profile dir (default: CONFLUENCE_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/confluence-browser-fetch-chrome)
+  --port PORT                  Chrome DevTools port (default: CONFLUENCE_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
+  --profile-dir DIR            Chrome profile dir (default: CONFLUENCE_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/atlassian-browser-chrome)`;
 
-Update options:
-  --title TITLE                Override page title while updating
+function usage() {
+  console.log(`Usage: confluence-update <command> [options]
 
-replace-block options:
-  --marker NAME                Required marker name, e.g. agent-summary for <!-- agent-block:agent-summary:start -->
+Safely update or create Confluence Cloud pages through an authenticated browser session.
+Dry-run is the default; pass --apply to write to Confluence.
 
-replace-text options:
-  --match TEXT                 Required exact string to find and replace
+Commands:
+  update PAGE_ID_OR_URL        Replace an existing page body
+  replace-block PAGE_ID_OR_URL Replace only a marked agent-owned block
+  replace-text PAGE_ID_OR_URL  Replace an exact matched string in the page
+  replace-element PAGE_ID_OR_URL Replace an element by its local-id
+  create                       Create a new page
 
-replace-element options:
-  --local-id ID                Required local-id attribute value of the element to replace
+Run "confluence-update <command> --help" for command-specific options.
 
-Create options:
-  --space KEY                  Required Confluence space key
-  --title TITLE                Required page title
-  --parent-id ID               Parent page id. Required unless --allow-root is passed
-  --allow-root                 Allow creating a root page without parent-id
+${COMMON_OPTIONS}
 
 Examples:
   confluence-update update 123456 --site https://example.atlassian.net --file page.storage.html --apply
@@ -68,14 +54,93 @@ Examples:
 `);
 }
 
+const COMMAND_HELP = {
+  update: `Usage: confluence-update update PAGE_ID_OR_URL [options]
+
+Replace an existing page's body with new content.
+
+Required:
+  --file FILE                  Storage XHTML or Markdown source.
+
+Optional:
+  --representation REP         storage (default) or markdown.
+  --title TITLE                Override page title while updating.
+  --expected-version N|auto    Fail if current page version is not N (default: no check).
+
+${COMMON_OPTIONS}
+`,
+  'replace-block': `Usage: confluence-update replace-block PAGE_ID_OR_URL [options]
+
+Replace only an agent-owned marked block in an existing page. Block is delimited by
+<!-- agent-block:NAME:start --> ... <!-- agent-block:NAME:end --> comments.
+
+Required:
+  --file FILE                  Replacement content (Markdown or storage).
+  --marker NAME                Marker name, e.g. agent-summary.
+
+Optional:
+  --representation REP         storage (default) or markdown.
+
+${COMMON_OPTIONS}
+`,
+  'replace-text': `Usage: confluence-update replace-text PAGE_ID_OR_URL [options]
+
+Replace an exact unique string in the page's storage XHTML.
+
+Required:
+  --file FILE                  Replacement content (Markdown or storage).
+  --match TEXT                 Exact string to find. Must be unique in the page; fails otherwise.
+
+Optional:
+  --representation REP         storage (default) or markdown.
+
+${COMMON_OPTIONS}
+`,
+  'replace-element': `Usage: confluence-update replace-element PAGE_ID_OR_URL [options]
+
+Replace an element identified by its local-id attribute. Caller must supply the
+new element's full XHTML (including the local-id) in --file.
+
+Required:
+  --file FILE                  Full replacement element (storage XHTML).
+  --local-id ID                local-id attribute value of the element to replace.
+
+${COMMON_OPTIONS}
+`,
+  create: `Usage: confluence-update create [options]
+
+Create a new Confluence page.
+
+Required:
+  --file FILE                  Page body (Markdown or storage).
+  --space KEY                  Confluence space key.
+  --title TITLE                Page title.
+  --parent-id ID               Parent page id (or --allow-root for a root page).
+
+Optional:
+  --representation REP         storage (default) or markdown.
+  --allow-root                 Permit creating a root page without --parent-id.
+
+${COMMON_OPTIONS}
+`,
+};
+
+function commandHelp(command) {
+  if (COMMAND_HELP[command]) {
+    console.log(COMMAND_HELP[command]);
+  } else {
+    usage();
+  }
+}
+
 const opts = {
   command: '',
   pageInput: '',
   site: process.env.CONFLUENCE_SITE || '',
   rawDir: process.env.CONFLUENCE_UPDATE_RAW_DIR || process.env.CONFLUENCE_RAW_DIR || path.resolve(process.cwd(), 'raw'),
-  port: Number(process.env.CONFLUENCE_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || (process.env.ATLASSIAN_CHROME_PROFILE ? 9223 : 9224)),
+  port: Number(process.env.CONFLUENCE_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9223),
   waitSec: Number(process.env.CONFLUENCE_UPDATE_WAIT_SEC || process.env.CONFLUENCE_FETCH_WAIT_SEC || 900),
-  profileDir: process.env.CONFLUENCE_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/confluence-browser-fetch-chrome'),
+  profileDir: process.env.CONFLUENCE_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/atlassian-browser-chrome'),
   file: '',
   representation: 'storage',
   title: '',
@@ -94,13 +159,17 @@ const opts = {
 };
 
 const args = process.argv.slice(2);
-if (!args.length || args.includes('-h') || args.includes('--help')) { usage(); process.exit(0); }
+if (!args.length || args[0] === '-h' || args[0] === '--help') { usage(); process.exit(0); }
 opts.command = args.shift();
 if (!['update', 'replace-block', 'replace-text', 'replace-element', 'create'].includes(opts.command)) {
   console.error(`Unknown command: ${opts.command}`);
   usage();
   process.exit(2);
 }
+if (args.includes('--help') || args.includes('-h')) {
+  commandHelp(opts.command);
+  process.exit(0);
+}
 if (opts.command !== 'create') opts.pageInput = args.shift() || '';
 
 for (let i = 0; i < args.length; i++) {
@@ -130,6 +199,11 @@ for (let i = 0; i < args.length; i++) {
 }
 
 opts.site = opts.site.replace(/\/$/, '');
+if (/\/wiki$/i.test(opts.site)) {
+  const stripped = opts.site.replace(/\/wiki$/i, '');
+  console.error(`Note: stripping trailing /wiki from --site (${opts.site} -> ${stripped}). Pass the site root, e.g. https://example.atlassian.net.`);
+  opts.site = stripped;
+}
 opts.rawDir = path.resolve(opts.rawDir);
 const wikiBase = opts.site ? `${opts.site}/wiki` : '';
 
@@ -193,7 +267,13 @@ async function verifyConfluenceSession(cookie) {
     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' };
+  try {
+    const sanity = await fetchJsonAdapter(`${opts.site}/rest/api/3/myself`, cookie);
+    if (sanity.status === 200 && sanity.json && (sanity.json.accountId || sanity.json.displayName)) {
+      return { ok: false, message: `cookies are valid for ${opts.site} (Jira API responded) but Confluence at ${wikiBase} returned 404. Verify --site is the Atlassian site root (e.g. https://example.atlassian.net, without /wiki) and that Confluence is enabled on this tenant.` };
+    }
+  } catch {}
+  return { ok: false, message: `could not verify Confluence session at ${wikiBase}. Verify --site is the Atlassian site root (e.g. https://example.atlassian.net, without /wiki).` };
 }
 
 function getCookieWithWait(openUrl) {

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

@@ -38,6 +38,7 @@ Important options:
 --max-attachment-size S  skip attachment files larger than S (default 5mb; use unlimited to disable)
 --prefix A,B,C     only follow keys with these project prefixes
 --wait SEC         SSO/session wait timeout per issue
+--skip-existing    skip issues that already have a valid raw/<KEY>/issue.json
 ```
 
 ## Example User Requests
@@ -50,13 +51,24 @@ Use this skill for user requests like:
 - "Pull my assigned Jira issues without asking me for an API token."
 - "Fetch this ticket and all linked tickets, including attachments under the default size limit."
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-SSO — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Typical Workflow
 
 1. Identify raw directory.
 2. Run the script and show the command first.
-3. If Chrome opens, ask the user to complete SSO in that browser window.
-4. To share one Atlassian SSO login with `confluence-browser-fetch`, use `ATLASSIAN_CHROME_PROFILE` plus `ATLASSIAN_CHROME_DEBUG_PORT` (or matching `--profile-dir` and `--port`) for both tools.
-5. Verify saved files.
+3. If Chrome opens (first run or expired session), ask the user to complete SSO in that window. On subsequent invocations the script reuses the session silently — see the Reuse signal above.
+4. Verify saved files.
 
 Example:
 

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

@@ -6,12 +6,16 @@ This skill follows Pi / Agent Skills layout:
 jira-browser-fetch/
 ├── SKILL.md
 ├── scripts/
-│   └── jira-browser-fetch.js
+│   ├── atlassian-browser.js   # vendored from lib/atlassian-browser.js
+│   ├── jira-browser-fetch.js
+│   └── lib.js
 └── references/
     ├── usage.md
     └── distribution.md
 ```
 
+`scripts/atlassian-browser.js` is vendored from `lib/atlassian-browser.js` at the repo root by `bin/vendor.js` (run via `npm run vendor`, and automatically before `npm test` and `npm pack`). The skill folder is self-contained, so copying just the `jira-browser-fetch/` directory works once vendoring has happened. If you hand-copy from a fresh source checkout, run `npm run vendor` first or include all three files in `scripts/`.
+
 ## Install for Current User
 
 Copy the whole directory to Pi's global skill location:

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

@@ -13,6 +13,8 @@ const {
   parseBacklogInput,
   backlogApiUrl,
   issueKeysFromAgilePage,
+  readExistingIssueJson,
+  formatEta,
 } = require('./lib');
 
 function usage() {
@@ -35,10 +37,12 @@ Options:
   --prefix A,B,C           Only fetch referenced keys with these project prefixes
   --wait SEC               Wait time for SSO/session per issue (default: 900)
   --port PORT              Chrome DevTools port (default: JIRA_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
-  --profile-dir DIR        Chrome profile dir (default: JIRA_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/jira-browser-fetch-chrome)
+  --profile-dir DIR        Chrome profile dir (default: JIRA_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/atlassian-browser-chrome)
   --no-attachments         Do not download Jira attachments
   --no-html                Do not save browser HTML
   --no-xml                 Do not save Jira XML issue view
+  --skip-existing          Skip issues that already have a valid raw/<KEY>/issue.json
+                           (still extracts connected keys for depth traversal)
   --help                   Show this help
 
 Examples:
@@ -55,7 +59,7 @@ const opts = {
   rawDir: process.env.JIRA_RAW_DIR || path.resolve(process.cwd(), 'raw'),
   port: Number(process.env.JIRA_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9223),
   waitSec: Number(process.env.JIRA_FETCH_WAIT_SEC || 900),
-  profileDir: process.env.JIRA_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/jira-browser-fetch-chrome'),
+  profileDir: process.env.JIRA_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/atlassian-browser-chrome'),
   connected: false,
   depth: undefined,
   scanText: false,
@@ -68,6 +72,7 @@ const opts = {
   attachments: true,
   html: true,
   xml: true,
+  skipExisting: false,
 };
 const issues = [];
 
@@ -91,6 +96,7 @@ for (let i = 2; i < process.argv.length; i++) {
   else if (a === '--no-attachments') opts.attachments = false;
   else if (a === '--no-html') opts.html = false;
   else if (a === '--no-xml') opts.xml = false;
+  else if (a === '--skip-existing') opts.skipExisting = true;
   else if (!a.startsWith('-')) issues.push(a.toUpperCase());
   else { console.error(`Unknown argument: ${a}`); process.exit(2); }
 }
@@ -347,6 +353,19 @@ async function downloadAttachments(issueJson, cookie, outDir) {
 
 async function fetchIssue(issue) {
   const outDir = path.join(opts.rawDir, issue);
+
+  if (opts.skipExisting) {
+    const existing = await readExistingIssueJson(outDir, issue);
+    if (existing) {
+      console.log(`Skipping ${issue} (already fetched: ${outDir})`);
+      try {
+        const saved = JSON.parse(await fsp.readFile(path.join(outDir, 'connected-keys.json'), 'utf8'));
+        if (Array.isArray(saved)) return saved;
+      } catch {}
+      return extractConnectedKeys(existing, []);
+    }
+  }
+
   await fsp.mkdir(outDir, { recursive: true });
 
   const browseUrl = `${opts.server}/browse/${issue}`;
@@ -448,11 +467,14 @@ async function main() {
     }
   }
 
+  const fetchStart = Date.now();
+  let processed = 0;
   for (let idx = 0; idx < queue.length; idx++) {
     const item = queue[idx];
     if (seen.has(item.key)) continue;
     seen.add(item.key);
-    console.log(`\n===== Fetching ${item.key}${item.from ? ` (referenced by ${item.from})` : ''} =====`);
+    const pct = ((idx + 1) / queue.length * 100).toFixed(0);
+    console.log(`\n===== [${idx + 1}/${queue.length}] ${pct}% Fetching ${item.key}${item.from ? ` (referenced by ${item.from})` : ''} =====`);
     try {
       const connected = await fetchIssue(item.key);
       if (opts.connected && item.depth < opts.depth) {
@@ -464,6 +486,13 @@ async function main() {
       failed.push({ key: item.key, error: e.message });
       console.error(`SKIPPED/FAILED ${item.key}: ${e.message}`);
     }
+    processed++;
+    const remaining = queue.length - (idx + 1);
+    if (queue.length > 1 && remaining > 0) {
+      const elapsed = (Date.now() - fetchStart) / 1000;
+      const eta = elapsed / processed * remaining;
+      console.log(`Progress: ${idx + 1}/${queue.length} done, ${remaining} remaining, elapsed ${formatEta(elapsed)}, ETA ${formatEta(eta)}`);
+    }
   }
 
   const runMeta = { fetchedAt: new Date().toISOString(), server: opts.server, rawDir: opts.rawDir, requested: issues, searches, backlogs, fetched: [...seen].filter(k => !failed.some(f => f.key === k)), failed };

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

@@ -1,5 +1,8 @@
 'use strict';
 
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
 const DEFAULT_MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024;
 
 function parseSize(value) {
@@ -80,6 +83,27 @@ function issueKeysFromAgilePage(page) {
   return issues.map(issue => issue && issue.key).filter(Boolean);
 }
 
+async function readExistingIssueJson(outDir, issueKey) {
+  try {
+    const text = await fsp.readFile(path.join(outDir, 'issue.json'), 'utf8');
+    const parsed = JSON.parse(text);
+    if (parsed && parsed.key === issueKey) return parsed;
+  } catch {}
+  return null;
+}
+
+function formatEta(seconds) {
+  if (!Number.isFinite(seconds) || seconds <= 0) return '0s';
+  const s = Math.round(seconds);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = s % 60;
+  if (m < 60) return rem ? `${m}m${rem}s` : `${m}m`;
+  const h = Math.floor(m / 60);
+  const remM = m % 60;
+  return remM ? `${h}h${remM}m` : `${h}h`;
+}
+
 module.exports = {
   DEFAULT_MAX_ATTACHMENT_BYTES,
   parseSize,
@@ -90,4 +114,6 @@ module.exports = {
   parseBacklogInput,
   backlogApiUrl,
   issueKeysFromAgilePage,
+  readExistingIssueJson,
+  formatEta,
 };

package/skills/jira-update/SKILL.md

@@ -45,7 +45,7 @@ Common options:
 --apply                   Actually write. Without this, only dry-run/audit files are written
 --message TEXT            Annotate the local audit record (not sent to Jira)
 --wait SEC                Wait time for SSO/session (default: 900)
---port PORT               Chrome DevTools port (default: 9225 or ATLASSIAN_CHROME_DEBUG_PORT)
+--port PORT               Chrome DevTools port (default: ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
 --profile-dir DIR         Chrome profile dir
 ```
 
@@ -56,13 +56,24 @@ transition: --to NAME | --to-id ID, --comment-file FILE, --field key=value (repe
 link:       --to ISSUE-KEY, --type "blocks" | "relates" | etc.
 ```
 
+## Shared Atlassian SSO Session
+
+All five Atlassian skills (`jira-browser-fetch`, `jira-update`, `confluence-browser-fetch`, `confluence-update`, `bitbucket-browser-fetch`) default to the same Chrome profile (`~/.local/share/atlassian-browser-chrome`) and DevTools port (`9223`). Log in once via any skill and the others reuse that session automatically — no env vars needed.
+
+**This is a separate Chrome window from any browser the user already has open.** The script always launches its own profile with remote-debugging enabled; cookies from the user's regular Chrome are not read. The user logs in inside the window the script opens; that session is then reused by every Atlassian skill until it expires.
+
+**Reuse signal.** When attaching to an existing session, the script prints `Reusing Chrome DevTools on port 9223` and (if the target tab is open) `Found existing tab for <host>`. When you see those lines, do not ask the user to re-SSO — the session is already valid.
+
+If Chrome/Chromium is installed via Flatpak, Snap, or another non-PATH location, set `CHROME=/path/to/launcher` (or a wrapper script) so the script can find the binary.
+
+Override with `ATLASSIAN_CHROME_PROFILE` and/or `ATLASSIAN_CHROME_DEBUG_PORT` to relocate the shared profile/port, or use skill-specific `*_CHROME_PROFILE` / `*_CHROME_DEBUG_PORT` env vars for isolation.
+
 ## Typical Workflow
 
 1. Run without `--apply` first.
 2. Review files in `raw/jira-updates/<command>-<key|new>-<timestamp>/`.
 3. Ask the user for approval.
-4. Re-run the same command with `--apply`.
-5. To share one Atlassian SSO login with the fetchers, set `ATLASSIAN_CHROME_PROFILE` and `ATLASSIAN_CHROME_DEBUG_PORT`.
+4. Re-run the same command with `--apply`. If Chrome opens (first run or expired session), ask the user to complete SSO; on subsequent runs the script reuses the session silently.
 
 ## Examples
 

package/skills/jira-update/scripts/jira-update.js

@@ -7,6 +7,15 @@ const path = require('node:path');
 const { createBrowserSession } = require('./atlassian-browser');
 const lib = require('./lib');
 
+const COMMON_OPTIONS = `Common options:
+  --server URL          Jira base URL (or JIRA_SERVER), e.g. https://example.atlassian.net
+  --raw-dir DIR         Audit directory (default: ./raw)
+  --apply               Actually write to Jira (without it, dry-run only)
+  --message TEXT        Annotate the local audit record
+  --wait SEC            Wait time for SSO/session (default: 900)
+  --port PORT           Chrome DevTools port (default: JIRA_CHROME_DEBUG_PORT, ATLASSIAN_CHROME_DEBUG_PORT, or 9223)
+  --profile-dir DIR     Chrome profile dir (default: JIRA_CHROME_PROFILE, ATLASSIAN_CHROME_PROFILE, or ~/.local/share/atlassian-browser-chrome)`;
+
 function topUsage() {
   console.log(`Usage: jira-update <command> [options]
 
@@ -20,25 +29,99 @@ Commands:
 Run "jira-update <command> --help" for command-specific options.
 Dry-run is the default; --apply is required to write.
 
-Common options:
-  --server URL          Jira base URL (or JIRA_SERVER), e.g. https://example.atlassian.net
-  --raw-dir DIR         Audit directory (default: ./raw)
-  --apply               Actually write to Jira
-  --message TEXT        Annotate the local audit record
-  --wait SEC            Wait time for SSO/session (default: 900)
-  --port PORT           Chrome DevTools port (default: 9225 or ATLASSIAN_CHROME_DEBUG_PORT)
-  --profile-dir DIR     Chrome profile dir
+${COMMON_OPTIONS}
 `);
 }
 
+const COMMAND_HELP = {
+  create: `Usage: jira-update create [options]
+
+Create a new Jira issue from a JSON manifest.
+
+Required:
+  --file FILE              Manifest JSON. Must include: project, issueType, summary.
+                           Optional: description, descriptionRepresentation (markdown|adf, default markdown),
+                           labels, assignee ("accountId:..." or bare name), priority, parent, fields (escape hatch).
+
+${COMMON_OPTIONS}
+`,
+  comment: `Usage: jira-update comment ISSUE-KEY [options]
+
+Add a comment to an existing issue.
+
+Required:
+  --file FILE              Comment body source.
+  --representation REP     markdown (default) or adf.
+
+${COMMON_OPTIONS}
+`,
+  transition: `Usage: jira-update transition ISSUE-KEY [options]
+
+Move an issue through its workflow.
+
+Required (one of):
+  --to NAME                Transition name, case-insensitive (e.g. "In Progress").
+  --to-id ID               Transition id (skips name lookup).
+
+Optional:
+  --comment-file FILE      Comment to attach to the transition.
+  --representation REP     markdown (default) or adf for the comment file.
+  --field key=value        Set a field as part of the transition. Repeatable.
+
+--field key=value heuristics:
+  priority, resolution, status   wrapped as { name: VALUE }
+  labels, components, fixVersions  split on commas; labels become a string array;
+                                   components/fixVersions become [{name},...]
+  any other key                  passed through as a plain string
+
+${COMMON_OPTIONS}
+`,
+  'update-fields': `Usage: jira-update update-fields ISSUE-KEY [options]
+
+Partial field update (PUT /issue/{key}). Does NOT detect concurrent edits;
+re-fetch with jira-browser-fetch first if drift matters.
+
+Required:
+  --file FILE              JSON manifest with a top-level "fields" object.
+                           Values are sent verbatim — caller is responsible for shape
+                           (e.g. labels: ["a","b"], priority: { name: "High" }).
+
+${COMMON_OPTIONS}
+`,
+  link: `Usage: jira-update link FROM-KEY [options]
+
+Create an issue link between two issues.
+
+Required:
+  --to ISSUE-KEY           Target issue key (validated as PROJ-123 form).
+  --type LINK-TYPE         Link type by name, inward, or outward
+                           (e.g. "blocks", "is blocked by", "relates to").
+
+${COMMON_OPTIONS}
+`,
+};
+
+function commandHelp(command) {
+  if (COMMAND_HELP[command]) {
+    console.log(COMMAND_HELP[command]);
+  } else {
+    topUsage();
+  }
+}
+
+const ISSUE_KEY_RE = /^[A-Z][A-Z0-9]+-\d+$/;
+function validIssueKey(s) {
+  return ISSUE_KEY_RE.test(String(s || ''));
+}
+
 const opts = {
   command: '',
   issueKey: '',
   server: process.env.JIRA_SERVER || '',
   rawDir: process.env.JIRA_UPDATE_RAW_DIR || process.env.JIRA_RAW_DIR || path.resolve(process.cwd(), 'raw'),
-  port: Number(process.env.JIRA_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9225),
+  port: Number(process.env.JIRA_CHROME_DEBUG_PORT || process.env.ATLASSIAN_CHROME_DEBUG_PORT || 9223),
   waitSec: Number(process.env.JIRA_UPDATE_WAIT_SEC || 900),
-  profileDir: process.env.JIRA_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/jira-browser-fetch-chrome'),
+  profileDir: process.env.JIRA_CHROME_PROFILE || process.env.ATLASSIAN_CHROME_PROFILE || path.join(os.homedir(), '.local/share/atlassian-browser-chrome'),
   file: '',
   representation: 'markdown',
   apply: false,
@@ -60,12 +143,21 @@ if (!['create', 'comment', 'transition', 'update-fields', 'link'].includes(opts.
   process.exit(2);
 }
 
+if (args.includes('--help') || args.includes('-h')) {
+  commandHelp(opts.command);
+  process.exit(0);
+}
+
 if (['comment', 'transition', 'update-fields', 'link'].includes(opts.command)) {
   if (!args.length || args[0].startsWith('-')) {
-    console.error(`${opts.command} requires an issue key as the first argument.`);
+    console.error(`error: ${opts.command} requires an issue key as the first argument (e.g. PROJ-123).`);
     process.exit(2);
   }
   opts.issueKey = args.shift();
+  if (!validIssueKey(opts.issueKey)) {
+    console.error(`error: invalid issue key "${opts.issueKey}". Expected format like PROJ-123 (uppercase letters, then "-", then digits).`);
+    process.exit(2);
+  }
 }
 
 for (let i = 0; i < args.length; i++) {
@@ -100,6 +192,11 @@ if (!opts.server) {
   process.exit(2);
 }
 
+if (opts.command === 'link' && opts.to && !validIssueKey(opts.to)) {
+  console.error(`error: invalid --to issue key "${opts.to}". Expected format like PROJ-123.`);
+  process.exit(2);
+}
+
 let session = null;
 function getSession() {
   if (session) return session;
@@ -399,6 +496,10 @@ async function main() {
 }
 
 main().catch(err => {
+  if (err && err.name === 'UsageError') {
+    console.error(`error: ${err.message}`);
+    process.exit(2);
+  }
   console.error(`\nERROR: ${err.stack || err.message}`);
   process.exit(1);
 });

package/skills/jira-update/scripts/lib.js

@@ -1,5 +1,12 @@
 'use strict';
 
+class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
 function adfDoc(content) {
   return { type: 'doc', version: 1, content: content || [] };
 }
@@ -162,11 +169,11 @@ function markdownToAdf(input) {
 function renderDescription(input, representation) {
   const rep = String(representation || 'markdown').toLowerCase();
   if (rep === 'adf') {
-    if (!input || typeof input !== 'object') throw new Error('descriptionRepresentation: adf requires an ADF object');
+    if (!input || typeof input !== 'object') throw new UsageError('descriptionRepresentation: adf requires an ADF object');
     return input;
   }
   if (rep === 'markdown' || rep === 'md') return markdownToAdf(String(input ?? ''));
-  throw new Error(`Unsupported representation: ${representation}`);
+  throw new UsageError(`Unsupported representation: ${representation}`);
 }
 
 function parseAssignee(value) {
@@ -178,10 +185,10 @@ function parseAssignee(value) {
 }
 
 function buildCreatePayload(manifest) {
-  if (!manifest || typeof manifest !== 'object') throw new Error('create manifest must be an object');
-  if (!manifest.project) throw new Error('create manifest requires project (key)');
-  if (!manifest.issueType) throw new Error('create manifest requires issueType (name)');
-  if (!manifest.summary) throw new Error('create manifest requires summary');
+  if (!manifest || typeof manifest !== 'object') throw new UsageError('create manifest must be an object');
+  if (!manifest.project) throw new UsageError('create manifest requires project (key)');
+  if (!manifest.issueType) throw new UsageError('create manifest requires issueType (name)');
+  if (!manifest.summary) throw new UsageError('create manifest requires summary');
 
   const fields = {
     project: { key: String(manifest.project) },
@@ -208,19 +215,19 @@ function buildCreatePayload(manifest) {
 
 function resolveTransition(transitionsResponse, query) {
   const list = (transitionsResponse && transitionsResponse.transitions) || [];
-  if (!list.length) throw new Error('No transitions available');
+  if (!list.length) throw new UsageError('No transitions available');
   if (query.id) {
     const match = list.find(t => String(t.id) === String(query.id));
-    if (!match) throw new Error(`Transition not found: id=${query.id}. Available: ${list.map(t => `${t.id}:${t.name}`).join(', ')}`);
+    if (!match) throw new UsageError(`Transition not found: id=${query.id}. Available: ${list.map(t => `${t.id}:${t.name}`).join(', ')}`);
     return match;
   }
   if (query.name) {
     const want = String(query.name).toLowerCase();
     const match = list.find(t => String(t.name).toLowerCase() === want);
-    if (!match) throw new Error(`Transition not found: "${query.name}". Available: ${list.map(t => t.name).join(', ')}`);
+    if (!match) throw new UsageError(`Transition not found: "${query.name}". Available: ${list.map(t => t.name).join(', ')}`);
     return match;
   }
-  throw new Error('resolveTransition requires {name} or {id}');
+  throw new UsageError('resolveTransition requires {name} or {id}');
 }
 
 function fieldValueFromCli(key, value) {
@@ -234,7 +241,7 @@ function fieldValueFromCli(key, value) {
 }
 
 function buildTransitionPayload({ transitionId, commentBody, fields }) {
-  if (!transitionId) throw new Error('buildTransitionPayload requires transitionId');
+  if (!transitionId) throw new UsageError('buildTransitionPayload requires transitionId');
   const payload = { transition: { id: String(transitionId) } };
   if (commentBody) {
     payload.update = { comment: [{ add: { body: commentBody } }] };
@@ -248,20 +255,20 @@ function buildTransitionPayload({ transitionId, commentBody, fields }) {
 
 function resolveLinkType(typesResponse, query) {
   const list = (typesResponse && typesResponse.issueLinkTypes) || [];
-  if (!list.length) throw new Error('No issue link types available');
+  if (!list.length) throw new UsageError('No issue link types available');
   const want = String(query || '').toLowerCase();
   const match = list.find(t =>
     String(t.name).toLowerCase() === want
     || String(t.inward).toLowerCase() === want
     || String(t.outward).toLowerCase() === want
   );
-  if (!match) throw new Error(`Link type not found: "${query}". Available: ${list.map(t => t.name).join(', ')}`);
+  if (!match) throw new UsageError(`Link type not found: "${query}". Available: ${list.map(t => t.name).join(', ')}`);
   return match;
 }
 
 function buildLinkPayload({ from, to, linkType }) {
-  if (!from || !to) throw new Error('buildLinkPayload requires from and to');
-  if (!linkType || !linkType.name) throw new Error('buildLinkPayload requires linkType.name');
+  if (!from || !to) throw new UsageError('buildLinkPayload requires from and to');
+  if (!linkType || !linkType.name) throw new UsageError('buildLinkPayload requires linkType.name');
   return {
     type: { name: linkType.name },
     inwardIssue: { key: to },
@@ -270,6 +277,7 @@ function buildLinkPayload({ from, to, linkType }) {
 }
 
 module.exports = {
+  UsageError,
   adfDoc,
   markdownToAdf,
   renderDescription,