skilldrop-cli 0.16.35 → 0.16.36

package/packs/converters/skills/md-to-confluence/evals/files/3/release-notes-4.2.md

@@ -0,0 +1,49 @@
+# Ledgerly 4.2 release notes
+
+Released to all workspaces. Upgrade window: Saturday 02:00 to 04:00 UTC.
+
+## What changed
+
+- **Faster month-end close.** Reconciliation runs in the background, so the close screen
+  no longer locks while it works.
+- **New export screen.** The CSV export moved from Settings to Reports.
+- ~~Bulk invoice delete~~ is postponed to 4.3.
+
+Before:
+
+![Export under Settings in 4.1](img/before/screen.png)
+
+After:
+
+![Export under Reports in 4.2](img/after/screen.png)
+
+## How reconciliation now flows
+
+```mermaid
+flowchart LR
+  Import[Bank import] --> Match[Auto-match]
+  Match --> Review[Review queue]
+  Review --> Close[Month-end close]
+```
+
+## Upgrading a self-hosted install
+
+1. Back up the database.
+
+```bash
+ledgerly-admin backup --out /backups/pre-4.2.dump
+```
+
+2. Run the migration.
+
+```bash
+ledgerly-admin migrate --to 4.2
+```
+
+3. Restart the web and worker services.
+
+## Known issues
+
+The export screen ignores the date filter for workspaces created before 2021.[^2]
+
+[^2]: Fixed in 4.2.1, due two weeks after this release.

package/packs/converters/skills/md-to-confluence/evals/files/4/docs/ingest-pipeline-design.md

@@ -0,0 +1,65 @@
+# Ingest Pipeline Design
+
+Owner: Platform Team (Riverbend Logistics)
+Status: Approved, revision 3
+
+## Context
+
+The ingest pipeline receives shipment events from depot scanners and writes them to the
+event store. This revision moves the parser from the gateway into a dedicated worker pool
+so that malformed payloads no longer stall the gateway.
+
+![Pipeline topology](img/topology.png)
+
+## Throughput limits
+
+| Stage          | Max events/sec | p99 latency | Scales on        |
+|----------------|---------------:|------------:|------------------|
+| Gateway        | 12,000         | 40 ms       | CPU              |
+| Parser workers | 8,500          | 120 ms      | Queue depth      |
+| Event store    | 6,000          | 250 ms      | Write IOPS       |
+
+The event store is the bottleneck: anything above 6,000 events/sec is buffered in the queue.
+
+## Flow
+
+```mermaid
+flowchart LR
+  Scanner --> Gateway --> Queue[(ingest-queue)]
+  Queue --> Parser --> Store[(event-store)]
+  Parser -- invalid --> DLQ[(dead-letter)]
+```
+
+## Parser configuration
+
+The parser rejects any payload where `weight_kg < 0` or the depot code is unknown.
+Raw XML from older scanners is wrapped in CDATA before it reaches the parser:
+
+```xml
+<parser-config version="3">
+  <rule id="weight" when="weight_kg &lt; 0" action="reject"/>
+  <rule id="depot" when="depot not in ALLOWED" action="dlq"/>
+  <legacy-wrapper><![CDATA[<scan depot="RB-07">payload]]></legacy-wrapper>
+  <!-- note: a literal ]]> inside payloads must be escaped by the scanner bridge -->
+</parser-config>
+```
+
+Run the replay tool against the dead-letter queue like this:
+
+```bash
+ingest-replay --queue dead-letter --since "2026-09-01" --max 500 && echo "done" > /tmp/replay.log
+```
+
+## Failover
+
+If the parser pool loses more than half its workers, the gateway switches to
+pass-through mode and events land in the queue unparsed.
+
+![Failover sequence](img/failover.png)
+
+> **Warning:** pass-through mode skips the weight check. Do not leave it on for more than 30 minutes.
+
+## Open questions
+
+- [ ] Confirm DLQ retention (currently 7 days)
+- [x] Agree parser pool minimum size (4 workers)

package/packs/converters/skills/md-to-confluence/evals/files/5/support/troubleshooting-sso.md

@@ -0,0 +1,57 @@
+# Troubleshooting: SSO login failures
+
+For Tier 1 agents at Lumen Desk. Work top to bottom; stop at the first fix that works.
+
+> [!NOTE]
+> Most SSO tickets are clock drift or a stale browser session. Check those first.
+
+## Quick checks
+
+- [ ] Ask the customer for the exact error text (screenshot if possible)
+- [ ] Confirm their workspace URL ends in `.lumendesk.example`
+- [ ] Ask them to try a private/incognito window
+
+## Common errors
+
+<details>
+<summary>"SAML response not valid yet" or "expired assertion"</summary>
+
+This is almost always clock drift on the customer's identity provider[^1].
+Ask their admin to check the IdP server time. More than 3 minutes of drift will fail.
+
+</details>
+
+<details>
+<summary>Redirect loop after login</summary>
+
+Clear cookies for the workspace domain, then retry. If it still loops, collect a HAR file:
+
+1. Open DevTools (<kbd>F12</kbd>)
+2. Network tab, tick **Preserve log**
+3. Reproduce, then right-click and **Save all as HAR**
+
+</details>
+
+<details>
+<summary>"User not provisioned"</summary>
+
+The user exists in the IdP but not in Lumen Desk. Check SCIM sync status[^2]:
+
+```bash
+lumenctl scim status --workspace acme-demo | grep -E "last_sync|errors" && echo "<check above>"
+```
+
+If `errors > 0`, escalate. See the [escalation matrix](./escalation-matrix.md).
+
+</details>
+
+## When to escalate
+
+> [!WARNING]
+> Never ask the customer to send their IdP signing certificate or private key in a ticket.
+
+Escalate to Tier 2 if the issue is not resolved after the quick checks and the matching
+section above, or if more than one user in the same workspace is affected[^3].
+
+[^1]: Lumen Desk allows up to 180 seconds of skew.
+[^2]: SCIM sync runs every 40 minutes.

package/packs/converters/skills/md-to-confluence/examples/inputs/queue-runbook.fixed.md

@@ -0,0 +1,21 @@
+# Order queue runbook
+
+The `orders-in` queue feeds the fulfilment workers. Rota: **fulfilment-oncall**.
+
+> **Warning:** Purging the queue deletes orders. Never purge without the fulfilment lead.
+
+## Check the backlog
+
+![Queue depth panel](img/queue-depth.png)
+
+1. Read the depth:
+
+   ```bash
+   qctl depth orders-in
+   ```
+
+2. If it is above 2,000 for 10 minutes, scale the workers to 6.
+
+## Scale back down
+
+Once depth is under 200, scale the workers back to 3.

package/packs/converters/skills/md-to-confluence/examples/inputs/queue-runbook.md

@@ -0,0 +1,21 @@
+# Order queue runbook
+
+The `orders-in` queue feeds the fulfilment workers. Rota: **fulfilment-oncall**.
+
+> **Warning:** Purging the queue deletes orders. Never purge without the fulfilment lead.
+
+## Check the backlog
+
+![Queue depth panel](img/queue-depth.png)
+
+1. Read the depth:
+
+```bash
+qctl depth orders-in
+```
+
+2. If it is above 2,000 for 10 minutes, scale the workers to 6.
+
+<details><summary>Scale back down</summary>
+Once depth is under 200, scale the workers back to 3.
+</details>

package/packs/converters/skills/md-to-confluence/examples/queue-runbook.md

@@ -0,0 +1,57 @@
+# Example: a short runbook onto a Confluence space
+
+**What the user said:** *"Put `queue-runbook.md` in Confluence under the Runbooks page
+(196612) in the OPS space on northwind.atlassian.net."*
+
+The input is [`inputs/queue-runbook.md`](inputs/queue-runbook.md). It has a warning callout, an
+image, a numbered list split by an unindented code block, and the scale-down step hidden in a
+`<details>` HTML block.
+
+## First conversion (real output)
+
+```text
+WARN line 17: numbered list starts at 2 but Confluence restarts it at 1; indent the code block or text that split the list under the previous item so it stays one list
+WARN line 19: raw HTML block dropped (lines 19-21); rewrite it as Markdown to keep it
+wrote queue-runbook.xhtml (1 KB storage format): title "Order queue runbook"; 2 headings, 0 tables, 1 code blocks, 1 callouts, 0 task lists, 1 images to attach, 0 remote images
+upload these files to the page as attachments, with exactly these names, or the images show as broken:
+  queue-depth.png  (from img/queue-depth.png)
+```
+
+Both warnings are fixable in the source, so neither goes to the user as a loss. The fixed copy
+is [`inputs/queue-runbook.fixed.md`](inputs/queue-runbook.fixed.md): the code block is indented
+three spaces under step 1, and the `<details>` block became a `## Scale back down` section with
+its sentence unchanged. The rerun prints no warnings.
+
+## The page body after the fix (real, abridged)
+
+```xml
+<ac:structured-macro ac:name="warning" ac:schema-version="1"><ac:rich-text-body><p>Purging the queue deletes orders. Never purge without the fulfilment lead.</p></ac:rich-text-body></ac:structured-macro>
+<h2>Check the backlog</h2><p><ac:image ac:alt="Queue depth panel"><ri:attachment ri:filename="queue-depth.png" /></ac:image></p>
+<ol><li><p>Read the depth:</p><ac:structured-macro ac:name="code" ac:schema-version="1"><ac:parameter ac:name="language">bash</ac:parameter><ac:plain-text-body><![CDATA[qctl depth orders-in]]></ac:plain-text-body></ac:structured-macro></li>
+<li><p>If it is above 2,000 for 10 minutes, scale the workers to 6.</p></li></ol>
+<h2>Scale back down</h2><p>Once depth is under 200, scale the workers back to 3.</p>
+```
+
+## The dry run (real output; no credentials were set)
+
+```text
+dry run: nothing was sent
+  POST https://northwind.atlassian.net/wiki/rest/api/content
+  space OPS, title "Order queue runbook", parent 196612
+  body: 847 bytes of storage format
+  first checks space OPS for a page with this title and stops if one exists
+  auth: none found: set CONFLUENCE_EMAIL and CONFLUENCE_API_TOKEN (Cloud) or CONFLUENCE_PAT (Data Center) in the environment
+```
+
+## The reply
+
+> The runbook is converted and ready to go up as a new page, **Order queue runbook**, under
+> page 196612 in the OPS space. Nothing has been published yet.
+>
+> - **Two fixes to the source:** the `qctl depth` command now sits inside step 1, so the steps
+>   stay numbered 1 and 2; the hidden "Scale back down" block is now its own section, so it
+>   isn't dropped.
+> - **One file to attach after publishing:** `queue-depth.png`, name unchanged, or the panel shows as a broken image.
+> - **Before I can publish:** set `CONFLUENCE_EMAIL` and `CONFLUENCE_API_TOKEN` in your terminal
+>   and restart the session. I'll then check that no OPS page already has this title, show you
+>   the result, and publish once you say yes.

package/packs/converters/skills/md-to-confluence/manifest.json

@@ -0,0 +1,52 @@
+{
+  "name": "md-to-confluence",
+  "version": "0.1.0",
+  "description": "Turn a Markdown runbook, design note or guide into a Confluence page: storage-format XHTML with real code blocks, tables, tasks, info and warning panels, images as attachments and an optional contents macro, a warning for everything dropped, and an optional publish that first shows which page it will create or overwrite and at what version, refuses stale or wrong-space overwrites, and takes credentials only from the environment. Use when the user says \"put this in Confluence\", \"publish this markdown to the wiki\", \"update the Confluence page with this\", \"convert to Confluence storage format\", or names a Confluence space for a Markdown file.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": [
+      "CONFLUENCE_EMAIL",
+      "CONFLUENCE_API_TOKEN",
+      "CONFLUENCE_PAT"
+    ]
+  },
+  "related": [
+    "md-to-docx",
+    "md-to-html",
+    "mermaid-render",
+    "runbook-generator",
+    "tracker-brief-sync"
+  ],
+  "handoff": [
+    {
+      "to": "mermaid-render",
+      "when": "the Markdown has Mermaid diagrams",
+      "purpose": "Render each diagram to PNG so it can go on the page as an attachment instead of showing as source code.",
+      "fallback": "If mermaid-render is absent, leave the diagram as a code block and tell the user it shows as text until someone adds an image or a diagram app."
+    }
+  ],
+  "tags": [
+    "confluence",
+    "markdown",
+    "convert",
+    "publish",
+    "wiki"
+  ],
+  "permissions": {
+    "network": [
+      "*.atlassian.net"
+    ],
+    "commands": [],
+    "files": "named-paths",
+    "notes": "Converting makes no network calls. Only --inspect (read-only GET) and --publish (GET, then POST or PUT) contact Confluence, at the https base URL the user passes: a Cloud site under *.atlassian.net, or for Data Center the user's own host, which they must add to the sandbox allowlist themselves. Credentials are read from CONFLUENCE_EMAIL + CONFLUENCE_API_TOKEN or CONFLUENCE_PAT only, never printed; redirects are not followed, so the Authorization header goes nowhere else. Writes only the -o path."
+  },
+  "model": {
+    "tier": "light",
+    "rationale": "Mechanical conversion to Confluence storage format done by its script, with an optional publish; the model checks what was dropped and what will be overwritten."
+  }
+}

package/packs/converters/skills/md-to-confluence/reference.md

@@ -0,0 +1,92 @@
+# md-to-confluence reference
+
+## What converts to what
+
+| Markdown | Confluence storage format |
+|---|---|
+| `#` to `######`, setext `===` / `---` | `<h1>` to `<h6>`. The first `#` heading becomes the page title and leaves the body (Confluence prints the title above the page); `--keep-h1` keeps it |
+| `**bold**`, `*italic*`, `~~strike~~`, `` `code` `` | `<strong>`, `<em>`, line-through span, `<code>` |
+| Inline, reference-style and bare links | `<a href>`. `javascript:`, `data:`, `file:` targets are dropped (text kept). `#anchor` links become plain text: Confluence names heading anchors after the page title, so a Markdown slug never matches |
+| `-` and `1.` lists, nested | `<ul>` / `<ol>`. A list that starts at 2 or later restarts at 1, with a warning |
+| A list made only of `- [ ]` / `- [x]` items | `<ac:task-list>`, one `<ac:task>` per item, complete or incomplete. Mixed with plain items: written as ☐ / ☑ text, with a warning |
+| Pipe table | `<table>`, first row as `<th>`; `:---:` / `---:` alignment kept as a paragraph style in each cell |
+| `> quote` | `<blockquote>` |
+| Callout (below) | info, tip, note or warning macro, label removed (the panel's icon says it) |
+| Fenced or indented code | `code` macro, body in CDATA. `]]>` inside the code is split as `]]]]><![CDATA[>`, so it reads back byte for byte |
+| An image with a local path, `img/x.png` | `<ac:image><ri:attachment ri:filename="x.png"/></ac:image>`, matched by file name only |
+| An image with an `https://` address | `<ac:image><ri:url/></ac:image>`, with a warning: it breaks if that site moves or needs a login |
+| `---` | `<hr />` |
+| `--toc` | `toc` macro at the top |
+| **Dropped, with a WARN line** | raw HTML blocks (whole), inline HTML tags (text kept; `<br>` kept), footnotes, `data:` images, YAML front matter (its `title:` is used as the page title) |
+
+Text is escaped once, after `&amp;`-style references are decoded, so nothing in the Markdown
+can open a macro or a tag in the page. Before writing, the script parses its own output as XML
+and stops if it is malformed.
+
+## Callout convention
+
+The label is bold, ends in a colon, and opens the quote. GitHub's `> [!NOTE]` form works too.
+
+| Write | Panel |
+|---|---|
+| `> **Note:**` or `> **Info:**` or `> [!NOTE]` | info (blue) |
+| `> **Tip:**` or `> [!TIP]` | tip (green) |
+| `> **Important:**` or `> [!IMPORTANT]` | note (yellow) |
+| `> **Warning:**`, `> **Caution:**`, `> [!WARNING]`, `> [!CAUTION]` | warning (red) |
+
+✅ `> **Warning:** Never restart all three replicas at once.` ❌ `> Warning - never restart…`
+(a plain quote: no panel).
+
+## Code languages
+
+Highlighted on Cloud and Data Center: bash, c#, cpp, css, diff, go, groovy, java, js, json,
+kotlin, perl, php, powershell, py, ruby, sass, scala, sql, text, typescript, vb, xml, yml, and a
+few older ones. Aliases map automatically (`python` → py, `sh`/`shell`/`zsh` → bash, `yaml` →
+yml, `html` → xml, `ts` → typescript). Any other language is shown without highlighting, with a
+warning. A `mermaid` fence stays a code block.
+
+## Publishing
+
+All calls go to the v1 content API at `<base>/rest/api/content`, which Cloud and Data Center
+both serve. For a Cloud host the script adds `/wiki` if the base URL lacks it.
+
+| Mode | Calls | Writes to Confluence |
+|---|---|---|
+| `--inspect --page-id N` | GET page N with version and space | no |
+| `--inspect` (no page id) | GET pages in the space with this title | no |
+| `--publish --dry-run` | none | no |
+| `--publish` (create) | GET by title, then POST | yes, a new page |
+| `--publish --page-id N` | GET page N, then PUT with version + 1 | yes, a new version |
+
+**Refusals** (exit 2, nothing written): a base URL that isn't `https`, or carries a user name
+or password; no credentials in the environment; a page in another space than `--space`; a page
+not at `--expected-version`; a create whose title already exists in the space. A redirect is
+never followed, so the credentials go to the host you named and nowhere else. HTTP errors exit 1
+with the status and Confluence's message (401 credentials, 403 permission, 404 missing or hidden,
+409 someone saved meanwhile).
+
+## Credentials
+
+Read from the environment only, never from arguments or files, and never printed.
+
+| Variable | Used for |
+|---|---|
+| `CONFLUENCE_EMAIL` + `CONFLUENCE_API_TOKEN` | Cloud: basic auth. Token from id.atlassian.com, Security, API tokens |
+| `CONFLUENCE_PAT` | Data Center: bearer token. From your profile, Personal Access Tokens |
+
+When both are set, a `*.atlassian.net` host uses the email and API token; any other host uses the PAT.
+
+```bash
+export CONFLUENCE_EMAIL="<your Atlassian account email>"
+export CONFLUENCE_API_TOKEN="<token from id.atlassian.com>"
+```
+
+Run those in your own terminal before starting the agent, or pull them from a secret manager.
+A Data Center host is not `*.atlassian.net`: add it to the sandbox's allowed hosts yourself if
+the project is contained.
+
+## Attachments
+
+The script never uploads files. After the page exists, upload each listed file to the page
+(page menu, Attachments) with its name unchanged; the `ri:filename` in the page is matched
+exactly, case included. Until then Confluence shows a broken image box.