@aholbreich/agent-skills 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.7.0 - 2026-05-07
+
+Added:
+
+- New `confluence-update` skill for dry-run-first Confluence page updates, agent-owned block replacement, simple Markdown-to-storage conversion, and page creation through authenticated browser sessions.
+
+## 0.6.1 - 2026-05-07
+
+Fixed:
+
+- Browser fetchers no longer open duplicate target tabs when reusing DevTools during bulk Jira/Confluence runs.
+
 ## 0.6.0 - 2026-05-07
 
 Added:

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetchers that work well when Jira/Confluence API-token authentication is unavailable because an organization uses Microsoft/SSO.
+This repository is a pure skills package. It currently contains browser-authenticated Atlassian fetch/update tools that work well when Jira/Confluence API-token authentication is unavailable because an organization uses Microsoft/SSO.
 
 ## Skills
 
@@ -10,6 +10,7 @@ This repository is a pure skills package. It currently contains browser-authenti
 |---|---|
 | [`jira-browser-fetch`](skills/jira-browser-fetch/) | Fetch Jira issue JSON, rendered HTML/XML, linked/referenced issues, Jira Software board backlogs, JQL result sets, and attachments through an authenticated Chrome session. |
 | [`confluence-browser-fetch`](skills/confluence-browser-fetch/) | Fetch Confluence page JSON, storage/view HTML, browser HTML, descendants, CQL result sets, and attachments through an authenticated Chrome session. |
+| [`confluence-update`](skills/confluence-update/) | Dry-run-first Confluence page updates, agent-owned block replacement, Markdown-to-storage conversion, and page creation through an authenticated browser session. |
 
 ## Compatibility
 
@@ -175,6 +176,7 @@ If installed globally via npm, the package exposes:
 agent-skills
 jira-browser-fetch
 confluence-browser-fetch
+confluence-update
 ```
 
 ## Reuse one Atlassian browser login
@@ -188,6 +190,29 @@ export ATLASSIAN_CHROME_DEBUG_PORT=9223
 
 Skill-specific variables such as `JIRA_CHROME_PROFILE` or `CONFLUENCE_CHROME_PROFILE` still override the shared profile when needed.
 
+## Confluence update examples
+
+Dry-run an agent-owned block replacement from Markdown:
+
+```bash
+confluence-update replace-block 123456 \
+  --site https://example.atlassian.net \
+  --marker agent-summary \
+  --file ./summary.md \
+  --representation markdown
+```
+
+Apply only after reviewing `raw/confluence-updates/...`:
+
+```bash
+confluence-update replace-block 123456 \
+  --site https://example.atlassian.net \
+  --marker agent-summary \
+  --file ./summary.md \
+  --representation markdown \
+  --apply
+```
+
 ## Jira examples
 
 Fetch one issue:

package/SECURITY.md

@@ -2,11 +2,11 @@
 
 ## Read this before installing or running
 
-These skills are local automation tools. They can fetch potentially sensitive Jira and Confluence data into your filesystem.
+These skills are local automation tools. They can fetch potentially sensitive Jira and Confluence data into your filesystem, and `confluence-update` can write to Confluence when explicitly run with `--apply`.
 
 ## Browser authentication model
 
-The Jira and Confluence fetchers:
+The Jira and Confluence browser tools:
 
 1. launch or reuse a Chromium-compatible browser with a dedicated local profile,
 2. let you complete normal Atlassian SSO in the browser,
@@ -20,10 +20,11 @@ They do **not** require you to paste API tokens or cookies into chat.
 
 - Do not paste Atlassian cookies, API tokens, passwords, or session headers into prompts, issues, logs, or commits.
 - Treat everything under `raw/` as confidential unless you know it is public.
-- Do not commit fetched Jira/Confluence exports or attachments to a public repository.
+- Do not commit fetched Jira/Confluence exports, update audit files, or attachments to a public repository.
 - Review generated `attachments.json` manifests before sharing; they may contain private URLs and filenames.
 - Chrome remote debugging is configured for `127.0.0.1`; do not expose it to a network interface.
 - Use dedicated browser profiles for fetch automation. If reusing SSO between Jira and Confluence, share only a dedicated automation profile via `ATLASSIAN_CHROME_PROFILE`, not your everyday browser profile.
+- `confluence-update` is dry-run by default; review audit files before re-running with `--apply`.
 - The default attachment download cap is `5mb`; skipped large attachments are still referenced in `attachments.json`.
 
 ## Attachment size limits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aholbreich/agent-skills",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Handcrafted Agent Skills for browser-authenticated Jira and Confluence ingestion, LLM wiki workflows, and developer automation.",
   "license": "MIT",
   "type": "commonjs",
@@ -37,10 +37,11 @@
   "bin": {
     "agent-skills": "bin/agent-skills.js",
     "jira-browser-fetch": "skills/jira-browser-fetch/scripts/jira-browser-fetch.js",
-    "confluence-browser-fetch": "skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js"
+    "confluence-browser-fetch": "skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js",
+    "confluence-update": "skills/confluence-update/scripts/confluence-update.js"
   },
   "scripts": {
-    "check": "node --check bin/agent-skills.js && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.js && node --check skills/confluence-browser-fetch/scripts/confluence-browser-fetch.js && node --check skills/confluence-browser-fetch/scripts/lib.js",
+    "check": "node --check bin/agent-skills.js && node --check skills/jira-browser-fetch/scripts/jira-browser-fetch.js && node --check skills/jira-browser-fetch/scripts/lib.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-update/scripts/confluence-update.js && node --check skills/confluence-update/scripts/lib.js",
     "test": "node --test",
     "ci": "npm run check && npm test && npm pack --dry-run",
     "pack:dry": "npm pack --dry-run",

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

@@ -131,6 +131,18 @@ async function openDevtoolsTab(url) {
   return false;
 }
 
+async function hasDevtoolsTabForWiki(url) {
+  if (!url) return false;
+  const host = new URL(url).host;
+  const list = await endpoint('/json/list');
+  return list.some(t => t.type === 'page' && t.url && (() => {
+    try {
+      const tabUrl = new URL(t.url);
+      return tabUrl.host === host && tabUrl.pathname.startsWith('/wiki');
+    } catch { return false; }
+  })());
+}
+
 function isExecutable(file) {
   try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
 }
@@ -198,9 +210,14 @@ async function ensureBrowser(openUrl) {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
     const targetUrl = openUrl || wikiBase;
     if (targetUrl) {
-      const opened = await openDevtoolsTab(targetUrl);
-      if (opened) console.log(`Opened target URL in reused browser: ${targetUrl}`);
-      else console.warn(`Could not open target URL through DevTools; continuing with existing tabs.`);
+      const hasTab = await hasDevtoolsTabForWiki(targetUrl);
+      if (hasTab) {
+        console.log(`Found existing Confluence tab for ${new URL(targetUrl).host}; not opening another tab.`);
+      } else {
+        const opened = await openDevtoolsTab(targetUrl);
+        if (opened) console.log(`Opened target URL in reused browser: ${targetUrl}`);
+        else console.warn(`Could not open target URL through DevTools; continuing with existing tabs.`);
+      }
     }
   }
   await waitDevtools();
@@ -346,16 +363,20 @@ async function getCookieWithWait(openUrl) {
       const cookie = await getCookieHeader();
       const session = await verifyConfluenceSession(cookie);
       if (session.ok) {
-        process.stdout.write('\n');
+        if (process.stdout.isTTY) 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)}`);
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
+    } else if (Date.now() - deadline + opts.waitSec * 1000 < 4000) {
+      console.log(`Waiting up to ${opts.waitSec}s for Confluence session...`);
+    }
     await sleep(3000);
   }
-  process.stdout.write('\n');
+  if (process.stdout.isTTY) process.stdout.write('\n');
   throw new Error(`Could not verify authenticated Confluence session. Last result: ${last}`);
 }
 

package/skills/confluence-update/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: confluence-update
+description: Safely update or create Confluence Cloud pages through an authenticated browser session when API tokens do not work, especially with Microsoft/SSO. Use for dry-run-first page updates, agent-owned block replacement, Markdown-to-storage updates, page creation, and audit backups.
+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 a Chromium-compatible browser with remote debugging (Chrome, Chromium, Brave, Edge, or Vivaldi). No npm dependencies.
+---
+
+# Confluence Update
+
+Use this skill when a user wants an agent to write to Confluence Cloud through the same browser-authenticated flow used by the fetchers. It is intentionally conservative: dry-run is the default and `--apply` is required for any write.
+
+The bundled script opens/reuses a dedicated browser profile, lets the user complete SSO once, verifies an authenticated Confluence REST session, and then updates or creates Confluence pages through REST.
+
+## Safety
+
+- Never ask the user to paste Confluence cookies or API tokens into chat.
+- Dry-run first. Require explicit user approval before adding `--apply`.
+- Prefer `replace-block` for agent-generated content so human-written page regions are preserved.
+- Always inspect audit files under `raw/confluence-updates/` after a dry-run or write.
+- Treat Confluence page content as confidential.
+
+## Script
+
+```bash
+scripts/confluence-update.js <command> [options]
+```
+
+Commands:
+
+```bash
+update PAGE_ID_OR_URL        # replace full page body
+replace-block PAGE_ID_OR_URL # replace content between <!-- agent-block:NAME:start/end --> markers
+create                       # create a new page
+```
+
+Important options:
+
+```bash
+--site URL              Atlassian site, e.g. https://example.atlassian.net
+--file FILE             input file with Confluence storage XHTML or Markdown
+--representation REP    storage | markdown (default: storage)
+--raw-dir DIR           audit/output directory
+--expected-version N    fail if current page version differs
+--message TEXT          Confluence version message
+--apply                 write to Confluence; omitted means dry-run only
+--marker NAME           required for replace-block
+--space KEY             required for create
+--title TITLE           required for create; optional for update
+--parent-id ID          parent page for create
+```
+
+## Typical Workflow
+
+1. Prefer `replace-block` when editing an agent-owned region.
+2. Run without `--apply` first.
+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`.
+
+## Agent-owned blocks
+
+A replaceable block looks like this in Confluence storage:
+
+```html
+<!-- agent-block:agent-summary:start -->
+<p>Old generated content.</p>
+<!-- agent-block:agent-summary:end -->
+```
+
+Then run:
+
+```bash
+scripts/confluence-update.js replace-block 123456 \
+  --site https://example.atlassian.net \
+  --marker agent-summary \
+  --file ./summary.md \
+  --representation markdown
+```
+
+Add `--apply` only after dry-run review.
+
+## Examples
+
+Dry-run a full-page storage update:
+
+```bash
+scripts/confluence-update.js update 123456 \
+  --site https://example.atlassian.net \
+  --file ./page.storage.html
+```
+
+Apply with version protection:
+
+```bash
+scripts/confluence-update.js update 123456 \
+  --site https://example.atlassian.net \
+  --file ./page.storage.html \
+  --expected-version 17 \
+  --message 'Update architecture notes' \
+  --apply
+```
+
+Create a page from Markdown:
+
+```bash
+scripts/confluence-update.js create \
+  --site https://example.atlassian.net \
+  --space ABC \
+  --parent-id 123456 \
+  --title 'Architecture Notes' \
+  --file ./page.md \
+  --representation markdown
+```
+
+## Output Layout
+
+Each dry-run or write creates an audit directory:
+
+```text
+raw/confluence-updates/<page-or-create>-<timestamp>/
+├── before.page.json       # existing page for update/replace-block
+├── before.storage.html    # existing storage body for update/replace-block
+├── proposed.storage.html  # generated replacement body
+├── payload.json           # REST payload that would be sent
+├── after.page.json        # only after successful --apply
+└── update-run.json        # command metadata
+```
+
+## References
+
+- [Usage reference](references/usage.md)

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

@@ -0,0 +1,24 @@
+# Confluence Update Distribution
+
+This skill is distributed as part of `@aholbreich/agent-skills`.
+
+Directory layout:
+
+```text
+confluence-update/
+├── SKILL.md
+├── references/
+│   └── usage.md
+└── scripts/
+    ├── confluence-update.js
+    └── lib.js
+```
+
+Use directly by path or install a convenience symlink:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf ~/.pi/agent/skills/confluence-update/scripts/confluence-update.js ~/.local/bin/confluence-update
+```
+
+The package also exposes a `confluence-update` npm bin when installed globally.

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

@@ -0,0 +1,138 @@
+# Confluence Update Usage
+
+## Why Browser Update?
+
+Some Confluence Cloud organizations use Microsoft/SSO and make API-token auth difficult. This updater avoids pasted secrets by:
+
+1. Launching/reusing a dedicated Chromium-compatible browser profile.
+2. Letting the user complete normal Atlassian SSO in the browser.
+3. Reading Atlassian cookies through local Chrome DevTools.
+4. Verifying those cookies represent an authenticated Confluence REST session.
+5. Writing through Confluence REST only after `--apply`.
+
+## Safety Model
+
+Dry-run is the default. Without `--apply`, the script writes audit/proposal files locally but does not update Confluence.
+
+Always review:
+
+- `proposed.storage.html`
+- `payload.json`
+- `update-run.json`
+
+For existing pages, the script also stores `before.page.json` and `before.storage.html`.
+
+## Common Commands
+
+Dry-run full-page update with native Confluence storage XHTML:
+
+```bash
+scripts/confluence-update.js update 123456 \
+  --site https://example.atlassian.net \
+  --file ./page.storage.html
+```
+
+Apply after review:
+
+```bash
+scripts/confluence-update.js update 123456 \
+  --site https://example.atlassian.net \
+  --file ./page.storage.html \
+  --expected-version 17 \
+  --message 'Update architecture notes' \
+  --apply
+```
+
+Replace an agent-owned block from Markdown:
+
+```bash
+scripts/confluence-update.js replace-block 123456 \
+  --site https://example.atlassian.net \
+  --marker agent-summary \
+  --file ./summary.md \
+  --representation markdown
+```
+
+Create a page from Markdown:
+
+```bash
+scripts/confluence-update.js create \
+  --site https://example.atlassian.net \
+  --space ABC \
+  --parent-id 123456 \
+  --title 'Architecture Notes' \
+  --file ./page.md \
+  --representation markdown
+```
+
+## Agent-owned Blocks
+
+Use block replacement for LLM-generated content. It protects human-written parts of the page.
+
+Page storage must contain markers:
+
+```html
+<!-- agent-block:release-notes:start -->
+<p>Old generated content.</p>
+<!-- agent-block:release-notes:end -->
+```
+
+Then update only that region:
+
+```bash
+scripts/confluence-update.js replace-block 123456 \
+  --marker release-notes \
+  --file ./release-notes.md \
+  --representation markdown
+```
+
+If the marker is missing, the command fails. It does not insert content into an unmarked page.
+
+## Representations
+
+| Representation | Meaning |
+|---|---|
+| `storage` | Native Confluence storage XHTML. Best for exact page updates and preserving advanced Confluence structures. |
+| `markdown` | Small built-in Markdown subset converted to storage XHTML. Best for agent-owned blocks and simple new pages. |
+
+The Markdown converter is intentionally simple: headings, paragraphs, unordered/ordered lists, links, emphasis, inline code, and fenced code blocks. For complex macros/layouts, use `storage`.
+
+## Environment Variables
+
+| Variable | Meaning |
+|---|---|
+| `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_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 |
+| `CHROME` / `CHROMIUM` | Browser executable path override |
+
+## Shared Atlassian SSO Session
+
+To reuse one Atlassian browser login across Jira fetch, Confluence fetch, and Confluence update:
+
+```bash
+export ATLASSIAN_CHROME_PROFILE="$HOME/.local/share/atlassian-browser-fetch-chrome"
+export ATLASSIAN_CHROME_DEBUG_PORT=9223
+```
+
+## Troubleshooting
+
+### Dry-run did not update the page
+
+That is expected. Add `--apply` only after reviewing the audit files.
+
+### Version mismatch
+
+The page changed after the agent prepared the update. Refetch/review the page and rerun with the new version.
+
+### Marker block not found
+
+`replace-block` only edits explicitly marked regions. Add the marker block manually or use full-page `update` after review.
+
+### Authentication waits forever
+
+Complete SSO in the opened browser. Login-page cookies are not enough; the script waits until a Confluence REST probe succeeds.

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

@@ -0,0 +1,541 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const lib = require('./lib');
+const {
+  safeName,
+  extractPageId,
+  renderContent,
+  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:
+  --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)
+  --raw-dir DIR                Output/audit dir (default: CONFLUENCE_UPDATE_RAW_DIR, CONFLUENCE_RAW_DIR, or ./raw)
+  --message TEXT               Version message (default: Updated by confluence-update)
+  --minor-edit                 Mark update as minor edit (default)
+  --major-edit                 Do not mark update as minor edit
+  --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)
+
+Update options:
+  --title TITLE                Override page title while updating
+
+replace-block options:
+  --marker NAME                Required marker name, e.g. agent-summary for <!-- agent-block:agent-summary:start -->
+
+replace-text options:
+  --match TEXT                 Required exact string to find and replace
+
+replace-element options:
+  --local-id ID                Required local-id attribute value of the element to replace
+
+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
+
+Examples:
+  confluence-update update 123456 --site https://example.atlassian.net --file page.storage.html --apply
+  confluence-update replace-block 123456 --marker agent-summary --file summary.md --representation markdown --apply
+  confluence-update create --site https://example.atlassian.net --space ABC --parent-id 123456 --title 'New Page' --file page.md --representation markdown --apply
+`);
+}
+
+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)),
+  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'),
+  file: '',
+  representation: 'storage',
+  title: '',
+  message: 'Updated by confluence-update',
+  minorEdit: true,
+  expectedVersion: null,
+  apply: false,
+  marker: '',
+  matchText: '',
+  localId: '',
+  space: '',
+  parentId: '',
+  allowRoot: false,
+};
+
+const args = process.argv.slice(2);
+if (!args.length || args.includes('-h') || args.includes('--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 (opts.command !== 'create') opts.pageInput = args.shift() || '';
+
+for (let i = 0; i < args.length; i++) {
+  const a = args[i];
+  if (a === '--site') opts.site = args[++i];
+  else if (a === '--raw-dir') opts.rawDir = args[++i];
+  else if (a === '--file') opts.file = args[++i];
+  else if (a === '--representation') opts.representation = args[++i];
+  else if (a === '--title') opts.title = args[++i];
+  else if (a === '--message') opts.message = args[++i];
+  else if (a === '--minor-edit') opts.minorEdit = true;
+  else if (a === '--major-edit') opts.minorEdit = false;
+  else if (a === '--expected-version') opts.expectedVersion = args[++i] === 'auto' ? 'auto' : Number(args[i]);
+  else if (a === '--apply') opts.apply = true;
+  else if (a === '--wait') opts.waitSec = Number(args[++i]);
+  else if (a === '--port') opts.port = Number(args[++i]);
+  else if (a === '--profile-dir') opts.profileDir = args[++i];
+  else if (a === '--marker') opts.marker = args[++i];
+  else if (a === '--match') opts.matchText = args[++i];
+  else if (a === '--local-id') opts.localId = args[++i];
+  else if (a === '--space') opts.space = args[++i];
+  else if (a === '--parent-id') opts.parentId = args[++i];
+  else if (a === '--allow-root') opts.allowRoot = true;
+  else { console.error(`Unknown argument: ${a}`); process.exit(2); }
+}
+
+opts.site = opts.site.replace(/\/$/, '');
+opts.rawDir = path.resolve(opts.rawDir);
+const wikiBase = opts.site ? `${opts.site}/wiki` : '';
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+function failUsage(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+if (!opts.site) failUsage('Missing Atlassian site. Pass --site https://example.atlassian.net or set CONFLUENCE_SITE.');
+if (!opts.file) failUsage('Missing --file input.');
+if (opts.command !== 'create' && !opts.pageInput) failUsage(`Missing page id or URL for ${opts.command}.`);
+if (opts.command === 'replace-block' && !opts.marker) failUsage('replace-block requires --marker NAME.');
+if (opts.command === 'replace-text' && !opts.matchText) failUsage('replace-text requires --match TEXT.');
+if (opts.command === 'replace-element' && !opts.localId) failUsage('replace-element requires --local-id ID.');
+if (opts.command === 'create') {
+  if (!opts.space) failUsage('create requires --space KEY.');
+  if (!opts.title) failUsage('create requires --title TITLE.');
+  if (!opts.parentId && !opts.allowRoot) failUsage('create requires --parent-id ID unless --allow-root is passed.');
+}
+if (opts.expectedVersion !== null && opts.expectedVersion !== 'auto' && (!Number.isInteger(opts.expectedVersion) || opts.expectedVersion < 1)) failUsage('--expected-version must be "auto" or a positive integer.');
+
+async function endpoint(pathname) {
+  const res = await fetch(`http://127.0.0.1:${opts.port}${pathname}`);
+  if (!res.ok) throw new Error(`DevTools HTTP ${res.status} for ${pathname}`);
+  return res.json();
+}
+
+async function devtoolsReady() {
+  try { await endpoint('/json/version'); return true; } catch { return false; }
+}
+
+async function waitDevtools() {
+  for (let i = 0; i < 80; i++) {
+    if (await devtoolsReady()) return;
+    await sleep(250);
+  }
+  throw new Error('Chrome DevTools endpoint did not start');
+}
+
+async function openDevtoolsTab(url) {
+  if (!url) return false;
+  const endpointUrl = `http://127.0.0.1:${opts.port}/json/new?${encodeURIComponent(url)}`;
+  for (const init of [{ method: 'PUT' }, {}]) {
+    try {
+      const res = await fetch(endpointUrl, init);
+      if (res.ok) { await sleep(500); return true; }
+    } catch {}
+  }
+  return false;
+}
+
+async function hasDevtoolsTabForWiki(url) {
+  if (!url) return false;
+  const host = new URL(url).host;
+  const list = await endpoint('/json/list');
+  return list.some(t => t.type === 'page' && t.url && (() => {
+    try {
+      const tabUrl = new URL(t.url);
+      return tabUrl.host === host && tabUrl.pathname.startsWith('/wiki');
+    } catch { return false; }
+  })());
+}
+
+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 browser = findBrowserExecutable();
+  const args = [
+    `--remote-debugging-port=${opts.port}`,
+    '--remote-debugging-address=127.0.0.1',
+    '--remote-allow-origins=*',
+    `--user-data-dir=${opts.profileDir}`,
+    '--no-first-run',
+    '--no-default-browser-check',
+    url,
+  ];
+  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 Chromium-compatible browser with reusable profile: ${opts.profileDir}`);
+    launchChrome(openUrl || wikiBase);
+  } else {
+    console.log(`Reusing Chrome DevTools on port ${opts.port}`);
+    const targetUrl = openUrl || wikiBase;
+    const hasTab = await hasDevtoolsTabForWiki(targetUrl);
+    if (hasTab) {
+      console.log(`Found existing Confluence tab for ${new URL(targetUrl).host}; not opening another tab.`);
+    } else {
+      const opened = await openDevtoolsTab(targetUrl);
+      if (opened) console.log(`Opened target URL in reused browser: ${targetUrl}`);
+      else console.warn('Could not open target URL through DevTools; continuing with existing tabs.');
+    }
+  }
+  await waitDevtools();
+}
+
+async function getPageWsUrl() {
+  const list = await endpoint('/json/list');
+  const pages = list.filter(t => t.type === 'page' && t.webSocketDebuggerUrl);
+  const host = new URL(opts.site).host;
+  const preferred = pages.find(t => (t.url || '').includes(host)) || pages[0];
+  return preferred && preferred.webSocketDebuggerUrl;
+}
+
+function connectCdp(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+    let id = 0;
+    const pending = new Map();
+    const failTimer = setTimeout(() => reject(new Error('CDP websocket timeout')), 10000);
+
+    ws.addEventListener('open', () => {
+      clearTimeout(failTimer);
+      resolve({
+        send(method, params = {}) {
+          return new Promise((res, rej) => {
+            const msgId = ++id;
+            pending.set(msgId, { res, rej });
+            ws.send(JSON.stringify({ id: msgId, method, params }));
+          });
+        },
+        close() { try { ws.close(); } catch {} },
+      });
+    });
+
+    ws.addEventListener('message', ev => {
+      let data = ev.data;
+      if (typeof data !== 'string') data = Buffer.from(data).toString('utf8');
+      const msg = JSON.parse(data);
+      if (!msg.id || !pending.has(msg.id)) return;
+      const { res, rej } = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.error) rej(new Error(`${msg.error.message || 'CDP error'} ${JSON.stringify(msg.error)}`));
+      else res(msg.result);
+    });
+
+    ws.addEventListener('error', err => reject(err));
+  });
+}
+
+async function getCookieHeader() {
+  const wsUrl = await getPageWsUrl();
+  if (!wsUrl) return '';
+  const cdp = await connectCdp(wsUrl);
+  try {
+    await cdp.send('Network.enable');
+    const host = new URL(opts.site).host;
+    const result = await cdp.send('Network.getCookies', { urls: [`${opts.site}/`, wikiBase] });
+    const cookies = (result.cookies || [])
+      .filter(c => c.domain && (c.domain === host || c.domain.endsWith(`.${host}`)))
+      .map(c => `${c.name}=${c.value}`);
+    return cookies.join('; ');
+  } finally {
+    cdp.close();
+  }
+}
+
+async function fetchText(url, cookie, method = 'GET', body = null) {
+  const headers = {
+    Cookie: cookie,
+    Accept: 'application/json',
+    'User-Agent': 'confluence-update/1.0',
+  };
+  if (body !== null) headers['Content-Type'] = 'application/json';
+  const res = await fetch(url, { method, redirect: 'follow', headers, body });
+  return { status: res.status, contentType: res.headers.get('content-type') || '', text: await res.text() };
+}
+
+async function fetchJson(url, cookie, method = 'GET', json = null) {
+  const result = await fetchText(url, cookie, method, json === null ? null : JSON.stringify(json));
+  let parsed = null;
+  try { parsed = JSON.parse(result.text); } catch {}
+  return { ...result, json: parsed };
+}
+
+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}`);
+  const deadline = Date.now() + opts.waitSec * 1000;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const cookie = await getCookieHeader();
+      const session = await verifyConfluenceSession(cookie);
+      if (session.ok) {
+        if (process.stdout.isTTY) process.stdout.write('\n');
+        console.log(`Authenticated Confluence session verified via ${session.url}`);
+        return cookie;
+      }
+      last = session.message;
+    } catch (e) { last = e.message; }
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
+    } else if (Date.now() - deadline + opts.waitSec * 1000 < 4000) {
+      console.log(`Waiting up to ${opts.waitSec}s for Confluence session...`);
+    }
+    await sleep(3000);
+  }
+  if (process.stdout.isTTY) process.stdout.write('\n');
+  throw new Error(`Could not verify authenticated Confluence session. Last result: ${last}`);
+}
+
+function pageUrl(pageId) {
+  return `${wikiBase}/spaces/pages/${pageId}`;
+}
+
+async function getPage(pageId, cookie) {
+  const url = `${wikiBase}/rest/api/content/${pageId}?expand=body.storage,version,space,ancestors`;
+  const result = await fetchJson(url, cookie);
+  if (result.status !== 200 || !result.json || !result.json.id) {
+    throw new Error(`Could not read page ${pageId}. HTTP ${result.status}: ${(result.text || '').slice(0, 300).replace(/\s+/g, ' ')}`);
+  }
+  return result.json;
+}
+
+function currentStorage(page) {
+  return (((page || {}).body || {}).storage || {}).value || '';
+}
+
+function updatePayload(page, storage) {
+  return {
+    id: String(page.id),
+    type: page.type || 'page',
+    title: opts.title || page.title,
+    space: { key: page.space && page.space.key },
+    body: { storage: { value: storage, representation: 'storage' } },
+    version: {
+      number: Number(page.version && page.version.number || 0) + 1,
+      minorEdit: opts.minorEdit,
+      message: opts.message,
+    },
+  };
+}
+
+function createPayload(storage) {
+  const payload = {
+    type: 'page',
+    title: opts.title,
+    space: { key: opts.space },
+    body: { storage: { value: storage, representation: 'storage' } },
+  };
+  if (opts.parentId) payload.ancestors = [{ id: String(opts.parentId) }];
+  return payload;
+}
+
+async function makeRunDir(name) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = path.join(opts.rawDir, 'confluence-updates', `${safeName(name)}-${stamp}`);
+  await fsp.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+async function writeAudit(dir, manifest, files) {
+  for (const [name, content] of Object.entries(files)) await fsp.writeFile(path.join(dir, name), content);
+  await fsp.writeFile(path.join(dir, 'update-run.json'), JSON.stringify(manifest, null, 2));
+}
+
+async function runUpdate(cookie, pageId, inputStorage) {
+  const page = await getPage(pageId, cookie);
+  const version = Number(page.version && page.version.number || 0);
+  if (opts.expectedVersion !== null && opts.expectedVersion !== 'auto' && version !== opts.expectedVersion) {
+    throw new Error(`Version mismatch for ${pageId}: expected ${opts.expectedVersion}, current ${version}. Refetch before updating.`);
+  }
+  let nextStorage = inputStorage;
+  if (opts.command === 'replace-block') nextStorage = replaceMarkedBlock(currentStorage(page), opts.marker, inputStorage);
+  else if (opts.command === 'replace-text') nextStorage = lib.replaceTextMatch(currentStorage(page), opts.matchText, inputStorage);
+  else if (opts.command === 'replace-element') nextStorage = lib.replaceLocalId(currentStorage(page), opts.localId, inputStorage);
+
+  const payload = updatePayload(page, nextStorage);
+  const dir = await makeRunDir(pageId);
+  const { generateSimpleDiff } = require('./lib');
+  const manifest = {
+    command: opts.command,
+    dryRun: !opts.apply,
+    site: opts.site,
+    pageId,
+    title: payload.title,
+    currentVersion: version,
+    nextVersion: payload.version.number,
+    representation: opts.representation,
+    marker: opts.marker || undefined,
+    matchText: opts.matchText || undefined,
+    localId: opts.localId || undefined,
+    auditDir: dir,
+  };
+  await writeAudit(dir, manifest, {
+    'before.page.json': JSON.stringify(page, null, 2),
+    'before.storage.html': currentStorage(page),
+    'proposed.storage.html': nextStorage,
+    'payload.json': JSON.stringify(payload, null, 2),
+  });
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} ${opts.command} for page ${pageId}: ${page.title} v${version} -> v${payload.version.number}`);
+  console.log(`Audit files: ${dir}`);
+  
+  if (!opts.apply) {
+    console.log('\n--- Dry-run Diff Summary ---');
+    console.log(generateSimpleDiff(currentStorage(page), nextStorage));
+    console.log('----------------------------\n');
+    console.log('Dry-run only. Re-run with --apply to write to Confluence.');
+    return;
+  }
+  const result = await fetchJson(`${wikiBase}/rest/api/content/${pageId}`, cookie, 'PUT', payload);
+  if (result.status !== 200 || !result.json || !result.json.id) {
+    throw new Error(`Update failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  await fsp.writeFile(path.join(dir, 'after.page.json'), JSON.stringify(result.json, null, 2));
+  console.log(`Updated page ${pageId} to version ${result.json.version && result.json.version.number || payload.version.number}`);
+}
+
+async function runCreate(cookie, inputStorage) {
+  const payload = createPayload(inputStorage);
+  const dir = await makeRunDir(`create-${opts.space}-${opts.title}`);
+  const manifest = {
+    command: 'create',
+    dryRun: !opts.apply,
+    site: opts.site,
+    space: opts.space,
+    parentId: opts.parentId || undefined,
+    title: opts.title,
+    representation: opts.representation,
+    auditDir: dir,
+  };
+  await writeAudit(dir, manifest, {
+    'proposed.storage.html': inputStorage,
+    'payload.json': JSON.stringify(payload, null, 2),
+  });
+  console.log(`${opts.apply ? 'Applying' : 'Dry-run'} create page: ${opts.space} / ${opts.title}`);
+  console.log(`Audit files: ${dir}`);
+  if (!opts.apply) {
+    console.log('Dry-run only. Re-run with --apply to write to Confluence.');
+    return;
+  }
+  const result = await fetchJson(`${wikiBase}/rest/api/content`, cookie, 'POST', payload);
+  if ((result.status !== 200 && result.status !== 201) || !result.json || !result.json.id) {
+    throw new Error(`Create failed HTTP ${result.status}: ${(result.text || '').slice(0, 500).replace(/\s+/g, ' ')}`);
+  }
+  await fsp.writeFile(path.join(dir, 'after.page.json'), JSON.stringify(result.json, null, 2));
+  console.log(`Created page ${result.json.id}: ${result.json.title}`);
+}
+
+async function main() {
+  const rawInput = await fsp.readFile(path.resolve(opts.file), 'utf8');
+  const inputStorage = renderContent(rawInput, opts.representation);
+  const pageId = opts.command === 'create' ? '' : extractPageId(opts.pageInput);
+  if (opts.command !== 'create' && !pageId) throw new Error(`Could not extract page id from: ${opts.pageInput}`);
+  const openUrl = opts.command === 'create' ? wikiBase : pageUrl(pageId);
+  const cookie = await getCookieWithWait(openUrl);
+  if (opts.command === 'create') await runCreate(cookie, inputStorage);
+  else await runUpdate(cookie, pageId, inputStorage);
+}
+
+main().catch(err => {
+  console.error(`\nERROR: ${err.stack || err.message}`);
+  process.exit(1);
+});

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

@@ -0,0 +1,197 @@
+'use strict';
+
+function escapeHtml(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function safeName(name) {
+  return String(name || 'untitled').replace(/[\\/\0]/g, '_').replace(/^\.+$/, '_').slice(0, 120) || 'untitled';
+}
+
+function extractPageId(input) {
+  const s = String(input || '').trim();
+  if (/^\d+$/.test(s)) return s;
+  try {
+    const u = new URL(s);
+    const qp = u.searchParams.get('pageId') || u.searchParams.get('pageid') || u.searchParams.get('contentId') || u.searchParams.get('contentid');
+    if (qp && /^\d+$/.test(qp)) return qp;
+    const patterns = [
+      /\/pages\/(\d+)(?:\/|$)/,
+      /[?&]pageId=(\d+)/,
+      /[?&]contentId=(\d+)/,
+    ];
+    for (const re of patterns) {
+      const m = u.href.match(re);
+      if (m) return m[1];
+    }
+  } catch {}
+  return null;
+}
+
+function inlineMarkdown(s) {
+  let out = escapeHtml(s);
+  out = out.replace(/`([^`]+)`/g, '<code>$1</code>');
+  out = out.replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, '<a href="$2">$1</a>');
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/\*([^*]+)\*/g, '<em>$1</em>');
+  return out;
+}
+
+function markdownToStorage(markdown) {
+  const lines = String(markdown ?? '').replace(/\r\n/g, '\n').split('\n');
+  const out = [];
+  let paragraph = [];
+  let list = null;
+  let inCode = false;
+  let code = [];
+
+  function flushParagraph() {
+    if (!paragraph.length) return;
+    out.push(`<p>${inlineMarkdown(paragraph.join(' '))}</p>`);
+    paragraph = [];
+  }
+
+  function closeList() {
+    if (!list) return;
+    out.push(`<${list.type}>${list.items.map(item => `<li>${inlineMarkdown(item)}</li>`).join('')}</${list.type}>`);
+    list = null;
+  }
+
+  function flushCode() {
+    out.push(`<pre><code>${escapeHtml(code.join('\n'))}</code></pre>`);
+    code = [];
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/\s+$/, '');
+    if (/^```/.test(line)) {
+      if (inCode) {
+        inCode = false;
+        flushCode();
+      } else {
+        flushParagraph();
+        closeList();
+        inCode = true;
+        code = [];
+      }
+      continue;
+    }
+    if (inCode) {
+      code.push(rawLine);
+      continue;
+    }
+    if (!line.trim()) {
+      flushParagraph();
+      closeList();
+      continue;
+    }
+    const heading = line.match(/^(#{1,6})\s+(.+)$/);
+    if (heading) {
+      flushParagraph();
+      closeList();
+      const level = heading[1].length;
+      out.push(`<h${level}>${inlineMarkdown(heading[2].trim())}</h${level}>`);
+      continue;
+    }
+    const bullet = line.match(/^[-*]\s+(.+)$/);
+    if (bullet) {
+      flushParagraph();
+      if (!list || list.type !== 'ul') { closeList(); list = { type: 'ul', items: [] }; }
+      list.items.push(bullet[1].trim());
+      continue;
+    }
+    const ordered = line.match(/^\d+[.)]\s+(.+)$/);
+    if (ordered) {
+      flushParagraph();
+      if (!list || list.type !== 'ol') { closeList(); list = { type: 'ol', items: [] }; }
+      list.items.push(ordered[1].trim());
+      continue;
+    }
+    closeList();
+    paragraph.push(line.trim());
+  }
+
+  if (inCode) flushCode();
+  flushParagraph();
+  closeList();
+  return out.join('\n');
+}
+
+function renderContent(content, representation) {
+  const rep = String(representation || 'storage').toLowerCase();
+  if (rep === 'storage') return String(content ?? '');
+  if (rep === 'markdown' || rep === 'md') return markdownToStorage(content);
+  throw new Error(`Unsupported representation: ${representation}`);
+}
+
+function blockMarkers(marker) {
+  const name = String(marker || '').trim();
+  if (!/^[A-Za-z0-9._:-]+$/.test(name)) throw new Error('Marker must contain only letters, digits, dot, underscore, colon, or hyphen');
+  return {
+    start: `<!-- agent-block:${name}:start -->`,
+    end: `<!-- agent-block:${name}:end -->`,
+  };
+}
+
+function replaceMarkedBlock(storage, marker, replacementStorage) {
+  const { start, end } = blockMarkers(marker);
+  const re = new RegExp(`(${escapeRegExp(start)})([\\s\\S]*?)(${escapeRegExp(end)})`);
+  if (!re.test(String(storage || ''))) throw new Error(`Marker block not found: ${marker}`);
+  return String(storage).replace(re, `$1\n${String(replacementStorage || '')}\n$3`);
+}
+
+function replaceTextMatch(storage, matchText, replacementStorage) {
+  if (!matchText) throw new Error('Match text cannot be empty');
+  const index = storage.indexOf(matchText);
+  if (index === -1) throw new Error(`Match text not found: ${matchText.slice(0, 50)}...`);
+  if (storage.indexOf(matchText, index + 1) !== -1) throw new Error('Match text is not unique in the page. Please provide a more specific match string.');
+  return storage.replace(matchText, replacementStorage);
+}
+
+function replaceLocalId(storage, localId, replacementStorage) {
+  if (!localId) throw new Error('local-id cannot be empty');
+  const re = new RegExp(`(<[^>]+local-id="${escapeRegExp(localId)}"[^>]*>)([\\s\\S]*?)(</[a-zA-Z0-9]+>)`);
+  const match = storage.match(re);
+  if (!match) throw new Error(`local-id not found: ${localId}`);
+  
+  // This is a naive replacement that assumes the tag closes cleanly. It works for simple blocks (p, h1, etc.)
+  // but might be dangerous for deep nesting unless the user provides the whole replacement tag.
+  // Actually, replacing the *entire* matched block is safer and clearer for the user.
+  return storage.replace(match[0], replacementStorage);
+}
+
+function generateSimpleDiff(oldText, newText) {
+  const oldLines = String(oldText || '').split('\n');
+  const newLines = String(newText || '').split('\n');
+  const diff = [];
+  
+  // Extremely naive diff just for dry-run summaries without dependencies
+  if (oldText === newText) return '  (No changes)';
+  
+  const added = newLines.length - oldLines.length;
+  diff.push(`  Size changed: ${oldText.length} bytes -> ${newText.length} bytes`);
+  diff.push(`  Lines changed: ${oldLines.length} -> ${newLines.length} (${added > 0 ? '+' : ''}${added})`);
+  
+  return diff.join('\n');
+}
+
+module.exports = {
+  escapeHtml,
+  safeName,
+  extractPageId,
+  markdownToStorage,
+  renderContent,
+  blockMarkers,
+  replaceMarkedBlock,
+  replaceTextMatch,
+  replaceLocalId,
+  generateSimpleDiff,
+};

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

@@ -143,6 +143,15 @@ async function openDevtoolsTab(url) {
   return false;
 }
 
+async function hasDevtoolsTabForHost(url) {
+  if (!url) return false;
+  const host = new URL(url).host;
+  const list = await endpoint('/json/list');
+  return list.some(t => t.type === 'page' && t.url && (() => {
+    try { return new URL(t.url).host === host; } catch { return false; }
+  })());
+}
+
 function isExecutable(file) {
   try { fs.accessSync(file, fs.constants.X_OK); return true; } catch { return false; }
 }
@@ -322,16 +331,20 @@ async function getCookieWithWait(openUrl) {
       const cookie = await getCookieHeader();
       const session = await verifyJiraSession(cookie);
       if (session.ok) {
-        process.stdout.write('\n');
+        if (process.stdout.isTTY) 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)}`);
+    if (process.stdout.isTTY) {
+      process.stdout.write(`\r${new Date().toLocaleTimeString()} ${last.padEnd(120).slice(0, 120)}`);
+    } else if (Date.now() - deadline + opts.waitSec * 1000 < 4000) {
+      console.log(`Waiting up to ${opts.waitSec}s for Jira session...`);
+    }
     await sleep(3000);
   }
-  process.stdout.write('\n');
+  if (process.stdout.isTTY) process.stdout.write('\n');
   throw new Error(`Could not verify authenticated Jira session. Last result: ${last}`);
 }
 
@@ -375,10 +388,12 @@ async function fetchBacklogPageWithWait(url, cookie) {
       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 Jira backlog access: ${last.padEnd(120).slice(0, 120)}`);
+    if (process.stdout.isTTY) {
+      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');
+  if (process.stdout.isTTY) process.stdout.write('\n');
   throw new Error(`Could not fetch Jira backlog. Last result: ${last}`);
 }
 
@@ -520,9 +535,14 @@ async function ensureBrowser(browseUrl) {
   } else {
     console.log(`Reusing Chrome DevTools on port ${opts.port}`);
     if (browseUrl) {
-      const opened = await openDevtoolsTab(browseUrl);
-      if (opened) console.log(`Opened target URL in reused browser: ${browseUrl}`);
-      else console.warn(`Could not open target URL through DevTools; continuing with existing tabs.`);
+      const hasTab = await hasDevtoolsTabForHost(browseUrl);
+      if (hasTab) {
+        console.log(`Found existing Jira/Atlassian tab for ${new URL(browseUrl).host}; not opening another tab.`);
+      } else {
+        const opened = await openDevtoolsTab(browseUrl);
+        if (opened) console.log(`Opened target URL in reused browser: ${browseUrl}`);
+        else console.warn(`Could not open target URL through DevTools; continuing with existing tabs.`);
+      }
     }
   }
   await waitDevtools();