@qvac/skills 0.1.11 → 0.1.13

package/skills/pdf/SKILL.md

@@ -1,110 +1,160 @@
 ---
 name: pdf
-description: Create PDF documents with fpdf2 or transform existing ones with pypdf — merge, split, rotate, watermark, encrypt, decrypt, fill forms, extract text — and deliver them as chat attachments.
-tools: [exec(python)]
-platform: [darwin, linux, win32]
-metadata:
-  {
-    "openclaw":
-      {
-        "setup":
-          {
-            "summary": "Runs pypdf and fpdf2 in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
-          }
-      }
-  }
+description: Read, answer questions about, create, merge, split, rotate, watermark, password-protect, unlock, fill in, or pull the text out of PDF files, including any attached .pdf — always this skill, never Python, for a PDF — and deliver the result as a chat attachment.
+tools: [pdf]
+platform: [darwin, linux, win32, ios, android]
 ---
 
 # PDF
 
-Build or transform `.pdf` files by running Python through the `exec` tool with
-`language: "python"`. Declare every produced file in `outputs` and it comes back
-as a chat attachment the user can save.
-
-Two libraries, split by job — pick by whether a PDF already exists:
-
-- **fpdf2** — create a new PDF from scratch: reports, letters, invoices, cheat
-  sheets, anything laid out page by page.
-- **pypdf** — transform a PDF that already exists: merge, split, reorder or
-  rotate pages, watermark, encrypt or decrypt, fill form fields, extract text.
-
-## Load the Recipe File First
-
-This file contains no Python. The working recipes live in two reference files —
-load the one for the job with the `skill` tool BEFORE writing any Python, then
-copy its recipe and change the content:
-
-Each load is a real `skill` tool call — printing the call as JSON or text in
-your reply loads nothing.
-
-- **Creating a new PDF** (no existing PDF involved): call the `skill` tool with
-  `name: "pdf"` and `file: "references/create.md"`.
-- **Anything with an existing PDF** (merge, split, rotate, watermark, encrypt,
-  decrypt, fill forms, extract text): call the `skill` tool with
-  `name: "pdf"` and `file: "references/transform.md"`.
-- **Adding or changing words in an existing PDF** (add a paragraph or section,
-  reword, restyle): pypdf cannot edit page content — do not try. The job is a
-  REBUILD: load `references/create.md` and write the whole document again with
-  fpdf2 — every original section, unchanged, plus the requested change. When
-  the original text is not already in this chat, load
-  `references/transform.md` too and extract it first.
-- **Both in one flow** (build a page with fpdf2, then stamp it onto an existing
-  PDF): load both files.
-
-Never write the Python from memory. The recipes carry required arguments
-(`new_x`/`new_y`, exact version pins, attachment staging rules) that fail in
-non-obvious ways when improvised; loading the file is one cheap read-only call.
-
-## When to Use
-
-- The user asks for a new `.pdf` document.
-- The user attached one or more PDFs and wants them merged, split, rotated,
-  watermarked, password-protected, unlocked, filled in, or their text pulled out.
-- A flow needs both: build a page with fpdf2, then stamp it onto an existing
-  PDF with pypdf — one `exec` call can use both libraries.
+Every PDF job is one or two `pdf` tool calls. A call with an `action` saves a
+new file named `output` and attaches it to the chat; a call without `action`
+changes nothing and returns what the PDF holds.
+
+## Pick the Call
+
+| The user wants                                   | The `pdf` call                                                                                                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| A new PDF — "write a report", "make a cheat sheet" | `{ "action": "create", "markdown": "# Cat Facts\n\n...", "output": "cat_facts.pdf" }`                                                                |
+| New or changed words in an existing PDF          | read first, then one `create` call with the whole document                                                                                            |
+| "Merge these PDFs", "combine them into one"      | `{ "action": "merge", "attachmentIds": ["4f9c2ab1", "9be07c12"], "output": "merged.pdf" }`                                                             |
+| "Keep pages 1-3", "split out page 5"             | `{ "action": "split", "attachmentId": "4f9c2ab1", "pages": [1, 2, 3], "output": "report_pages_1-3.pdf" }`                                              |
+| "Delete page 3", "remove the last page"          | `split` with every page to keep: a 4-page PDF without page 3 is `{ "action": "split", "attachmentId": "4f9c2ab1", "pages": [1, 2, 4], "output": "report_without_page_3.pdf" }` |
+| "Rotate it", "turn page 2 sideways"              | `{ "action": "rotate", "attachmentId": "4f9c2ab1", "degrees": 90, "pages": [2], "output": "report_rotated.pdf" }`                                      |
+| "Stamp DRAFT on every page", "add a watermark"   | `{ "action": "watermark", "attachmentId": "4f9c2ab1", "text": "DRAFT", "output": "report_draft.pdf" }`                                                 |
+| "Fill in this form"                              | read first, then `{ "action": "fill", "attachmentId": "4f9c2ab1", "values": { "name": "Ada Lovelace", "agree": true }, "output": "form_filled.pdf" }` |
+| "Put a password on it", "lock it"                | `{ "action": "encrypt", "attachmentId": "4f9c2ab1", "password": "s3cret", "output": "report_locked.pdf" }`                                             |
+| "Remove the password", "unlock it"               | `{ "action": "decrypt", "attachmentId": "4f9c2ab1", "password": "s3cret", "output": "report_unlocked.pdf" }`                                           |
+| "Give me the text as a file"                     | `{ "action": "text", "attachmentId": "4f9c2ab1", "output": "report.txt" }`                                                                             |
+| What is in it — its pages, text, or form fields  | `{ "attachmentId": "4f9c2ab1" }`                                                                                                                       |
+
+- `pages` counts the way the user does: `1` is the first page. Leave `pages`
+  out and `rotate` and `watermark` apply to every page.
+- `merge` joins the files in the order of `attachmentIds`.
+- `degrees` is `90`, `180` or `270`, clockwise.
+- `watermark` also takes `"opacity": 0.2` (0 to 1) and `"position": "under"`
+  to put the mark behind the content.
+- `encrypt` locks the file with AES-256. Add `"ownerPassword": "admin"` and
+  `"permissions": { "print": false, "copy": false }` to restrict what a viewer
+  allows.
+- A locked PDF needs its password on every action, not only `decrypt`:
+  `{ "action": "rotate", "attachmentId": "4f9c2ab1", "password": "s3cret", "degrees": 90, "output": "report_rotated.pdf" }`.
+  The password always comes from the user — never guess one.
+
+## A New PDF
+
+```json
+{
+  "action": "create",
+  "markdown": "# Cat Facts\n\n## Senses\n\n- A cat's hearing reaches **64 kHz**.\n- Cats have about 200 million scent receptors.\n\n## Sleep\n\nCats sleep 12 to 16 hours a day, most of it in short naps.\n\n| Breed | Weight (kg) |\n| --- | --- |\n| Siamese | 4 |\n| Maine Coon | 8 |\n",
+  "output": "cat_facts.pdf"
+}
+```
+
+- `markdown` is the whole document: `#` headings, paragraphs, `-` and `1.`
+  lists, `**bold**`, `*italic*`, `>` quotes, fenced code, tables, `---` rules
+  and `\pagebreak`. The tool lays it out, wraps it and adds pages itself.
+- **Write the whole document, not a cover page.** "A small PDF about X" still
+  means a title, then several short sections, each a heading plus a paragraph
+  or bullets. The content belongs inside the PDF, not in your chat reply.
+- `create` also takes `"pageSize": "Letter"` (the default is `A4`; `A5` and
+  `Legal` work too), `"landscape": true` and `"pageNumbers": true`.
+- Lock a new PDF only when the user asks for a password, and use the one the
+  user gave: add `"password"` with it. Otherwise leave `password` out.
+- Western European text only: accents, curly quotes, dashes and `€` are fine.
+  A character outside it (Chinese, Cyrillic, emoji) fails the call and the
+  error names it — leave it out, or tell the user it cannot be drawn.
+- A picture goes on its own line as `![caption](attachmentId)`:
+  `![Sales by month](9be07c12)` for an image this chat generated, or
+  `![Our logo](logo.png)` — the file name — for an image the user uploaded.
+  Only PNG and JPEG images work, and an image behind a URL cannot be
+  downloaded.
+
+## Changing the Words in an Existing PDF
+
+A PDF's pages cannot be edited in place. Adding a paragraph, rewording, or
+restyling is a REBUILD: read the PDF when its text is not already in this chat,
+then one `create` call with every original section, unchanged, plus the
+requested change. A rebuild that condenses, summarizes, or drops original
+sections is a failed turn. Name it after the original: `report.pdf` →
+`report_revised.pdf`.
+
+**Keep the original pages.** Write each page's text from the read and put
+`\pagebreak` between the pages, so the rebuild has the original page count. A
+page the user asks to add goes where they asked, after its own `\pagebreak`.
+A 3-page report with a line fixed on page 2:
+
+```json
+{
+  "action": "create",
+  "markdown": "# Annual Report\n\nPage 1 text, unchanged.\n\n\\pagebreak\n\n## Costs\n\nPage 2 text, with the fixed line.\n\n\\pagebreak\n\n## Outlook\n\nPage 3 text, unchanged.\n",
+  "output": "report_revised.pdf"
+}
+```
+
+A picture cannot be added to an existing PDF's pages. Tell the user, or offer
+a rebuild with the picture at the top, which keeps the words but not the
+original layout.
+
+## Attachment Ids
+
+The id comes from the tool result that produced the PDF, or from the user's
+`[Attached file …]` line:
+
+```
+[Attached file "contract.pdf" (application/pdf) — attachmentId: 4f9c2ab1]
+```
+
+Copy the id verbatim. Never make one up. If no id for the PDF is in the chat,
+ask the user to attach it again.
+
+## Reading a PDF
+
+```json
+{ "attachmentId": "4f9c2ab1" }
+```
+
+It returns the page count, each page's text, and the form fields — each with
+its `name`, `type`, current `value`, and the `options` a choice field accepts.
+You cannot fill a form or write a summary in the same call that reads, because
+the values are fixed before the PDF is opened. Read, then act on what came
+back.
+
+- **Filling a form** — `values` keys are the exact field `name`s from the
+  read. A checkbox takes `true` or `false`; a radio group or dropdown takes one
+  of its `options`. A PDF with no fields has no form layer: say so instead of
+  guessing where the text goes.
+- **A page with empty text is a scanned image.** There is no OCR here — tell
+  the user those pages are images rather than calling again.
+- **A question about an attached PDF** ("summarize this", "what does it say
+  about X") — answer from the document text already in the chat. Read only
+  when that text is missing.
 
 ## When NOT to Use
 
-- A `create_pdf` tool is available in this chat and the user only wants prose
-  you are writing turned into a downloadable document — call `create_pdf` with
-  the markdown instead; it is cheaper and handles layout itself. Reach for this
-  skill when that tool is absent on this device, when an existing PDF is
-  involved, or when the layout must be controlled page by page.
-- The user asks about an attached PDF — answer from the document text or
-  knowledge excerpts already in the chat. Run text extraction only when the
-  user wants the text itself delivered as a file.
 - The user wants a slide deck — use the presentations skill; a spreadsheet or
-  Word file — this skill cannot read or write Office formats.
+  Word file — the excel or word skill.
 - The user wants a single image — call `generate_image` alone.
 
 ## Rules for Every Job
 
-**You build it, not the user.** Deliver the file, never the recipe. Do NOT
-print the Python source in chat, do NOT tell the user to install pypdf, run a
-script, or open a terminal — they have no terminal in this chat and the code
-would not run there. The PDF exists only if an `exec` call with `outputs`
-succeeds and returns the attachment.
-
-**Success = stop.** When `exitCode` is `0` and the result's `attachments` lists
-the `.pdf`, the job is done. Do not call `exec` again for the same request —
-not to "confirm", not to "improve". Reply with a single line: file name + the
-page count from stdout. If the result has `missingOutputs` instead, the file
-was never written: check the save name matches the declared output and rerun
-once.
-
-**Failures are fixed in the code, not around it.** If a run fails, fix the
-Python against the loaded reference file's recipes and Errors table and call
-`exec` again. If two consecutive calls fail with the same error, re-read the
-traceback line-by-line before a third. An error is never a fault in pypdf,
-fpdf2, or the runtime — do not switch package versions, do not wrap source in
-`python -c` or shell, and do not "debug" with `os.listdir` or no-op scripts
-while `outputs` still lists the PDF.
-
-**The runtime is sealed.** There is no shell (`ls`, `cat` raise
-`SyntaxError` — the `command` is Python source) and no network — `requests`,
-`urllib`, and `socket` all fail, so a PDF behind a URL cannot be downloaded;
-ask the user to attach the file. The working directory starts empty on every
-call: a file from an earlier call is gone unless staged again, and a file you
-write but do not declare in `outputs` is discarded.
-
-**Never overwrite a staged input.** Transforms always write a new output name.
+**You build it, not the user.** The PDF exists only when a call returns its
+attachment. Never write it as chat text instead, and never tell the user to
+run anything.
+
+**Success = stop.** When the result lists the attachment, your whole answer is
+the result's `reply` line — the file name and the page count — and you call
+nothing else.
+
+**Never overwrite the input.** Name the output after the file you opened:
+`report.pdf` → `report_rotated.pdf`. Never the input's own name.
+
+**Errors name the fix.** A failed call says what is wrong — a page out of
+range and how many pages there are, a field name and the fields that exist, a
+value and the options it takes, a wrong or missing password, a character the
+font cannot draw. Correct that one argument and call again. Never repeat an
+identical call, and never switch to exec, Python or the shell for a PDF job:
+the `pdf` tool is the only way this skill works.
+
+**No network.** A PDF behind a URL cannot be downloaded — ask the user to
+attach the file.

package/skills/presentations/SKILL.md

@@ -1,118 +1,142 @@
 ---
 name: presentations
-description: Create, edit, or read PowerPoint (.pptx) decks with python-pptx — deliver decks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images the user attached to the chat as well as images generated in it.
-tools: [exec(python)]
-platform: [darwin, linux, win32]
-metadata:
-  {
-    "openclaw":
-      {
-        "setup":
-          {
-            "summary": "Runs python-pptx in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
-          }
-      }
-  }
+description: Create, edit, or read PowerPoint (.pptx) decks — deliver decks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Can embed images the user attached to the chat as well as images generated in it.
+tools: [pptx]
+platform: [darwin, linux, win32, ios, android]
 ---
 
 # Presentations
 
-Build, edit, or read `.pptx` decks by running python-pptx through the `exec`
-tool with `language: "python"`. Declare a produced deck in `outputs` and it
-comes back as a chat attachment the user can save — exactly like a
-`generate_image` result, the `exec` result carries
-`attachments: [{ attachmentId, fileName, byteLength }]`. To answer *from* a
-deck instead of building one, run a read call alone — no `outputs` — and reply
-in the chat.
-
-## Load the Recipe File First
-
-This file contains no Python. The working recipes live in three reference
-files — load the one for the job with the `skill` tool BEFORE writing any
-Python, then copy its recipe and change the content:
-
-Each load is a real `skill` tool call — printing the call as JSON or text in
-your reply loads nothing.
-
-- **Building a new deck** (no existing deck involved; includes embedding
-  images generated or uploaded in this chat): call the `skill` tool with
-  `name: "presentations"` and `file: "references/create.md"`.
-- **Editing a deck already in this chat** (retitle, recolor, add or revise
-  slides on a deck the user attached or a prior call built): call the `skill`
-  tool with `name: "presentations"` and `file: "references/edit.md"`.
-- **Answering from an attached deck** (a summary, a question answered,
-  content pulled into the chat — no file produced): call the `skill` tool
-  with `name: "presentations"` and `file: "references/read.md"`.
-- **A summary delivered as a new file** is a read followed by a build: load
-  both `references/read.md` and `references/create.md`.
-
-Never write the Python from memory. The recipes carry required rules (typed
-`Inches`/`Pt` lengths, layout reuse, the read-before-edit flow, exact version
-pins, attachment staging) that fail in non-obvious ways when improvised;
-loading the file is one cheap read-only call.
-
-## When to Use
-
-- The user asks for a presentation, deck, slides, `.pptx`, PowerPoint, or Keynote-openable file.
-- The user attaches a `.pptx` and asks what it says — a summary, a question
-  answered, or content pulled out into the chat.
-- The user wants a slide deck that embeds images generated in this chat.
-- The user attaches an image — a photo, a logo, a screenshot — and wants it on a
-  slide. You can see the image, and you can also stage the file it came from:
-  load `references/create.md` (new deck) or `references/edit.md` (existing
-  deck). Generating a lookalike instead is a failed turn.
-
-## When NOT to Use
-
-- The user wants markdown or a document in the chat and no deck is involved —
-  just write it. Summarizing or answering from an attached `.pptx` **is** this
-  skill: load `references/read.md`.
-- The user wants a single image — call `generate_image` alone.
+Every deck job is one or two `pptx` tool calls. A call with `ops` saves a new
+file named `output` and attaches it to the chat; a call without `ops` changes
+nothing and returns what the deck holds.
+
+## Pick the Call
+
+| The user wants                                                           | The calls                                                                  |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| A new deck — "make slides about …", "a deck with this image"             | one call: `create` + `ops` + `output`                                       |
+| A mechanical edit — "make the title red", "retitle slide 1 to …"          | one call: `attachmentId` + `ops` + `output`                                 |
+| An edit whose words depend on the deck — "add a summary slide", "fix typos" | read (`attachmentId` alone), then one edit call                            |
+| An answer in the chat — "summarize this deck", "what does slide 3 say?"   | read (`attachmentId` alone), then reply in the chat — no second call        |
+| A summary of the deck as a new file                                      | read, then one `create` call written from what the read returned           |
+
+A deck already in this chat is never rebuilt with `create` — that throws away
+every slide the user has. Its `attachmentId` is in the tool result that
+produced it, or on the user's `[Attached file …]` line:
+
+```
+[Attached file "quarterly.pptx" (application/vnd.openxmlformats-officedocument.presentationml.presentation) — attachmentId: 4f9c2ab1]
+```
+
+Copy the id verbatim. Never make one up.
+
+## A New Deck
+
+```json
+{
+  "create": { "size": "16:9" },
+  "ops": [
+    { "op": "addSlide", "layout": "Title Slide", "title": "Why the Sky Is Blue", "body": "Rayleigh scattering, in four points" },
+    { "op": "addSlide", "title": "What Happens", "body": [
+      "Sunlight carries every visible wavelength",
+      "Air scatters short wavelengths hardest",
+      { "text": "Blue scatters far more than red", "level": 1 },
+      "So the sky reads blue in every direction"
+    ] },
+    { "op": "addSlide", "layout": "Title Only", "title": "By Wavelength" },
+    { "op": "addChart", "slide": 2, "type": "column", "title": "Scattered light",
+      "categories": ["Blue", "Green", "Red"], "series": [{ "name": "Relative", "values": [5.5, 3.1, 1] }] }
+  ],
+  "output": "sky.pptx"
+}
+```
+
+Layouts in a new deck: `Title Slide`, `Title and Content` (the default),
+`Section Header`, `Two Content`, `Title Only`, `Blank`. Each bullet is its own
+item in `body` — never type `-`, `•` or `1.` in front of it; the slide draws
+the bullet. Five bullets per slide at most; a sixth is a new slide titled
+`… (cont.)`.
+
+## Reading a Deck
+
+```json
+{ "attachmentId": "4f9c2ab1" }
+```
+
+It returns every slide with its index, layout and shapes — each shape's `id`,
+`name`, and its paragraphs or table rows — plus speaker notes. You cannot write
+a summary or a closing slide in the same call that reads, because the words
+are fixed before the deck is opened. Read, then write from what came back.
+
+## Editing a Deck
+
+```json
+{
+  "attachmentId": "4f9c2ab1",
+  "ops": [
+    { "op": "setText", "slide": 0, "shape": "title", "text": "Why the Sky Is Blue — Revised" },
+    { "op": "setStyle", "slide": 0, "shape": "title", "style": { "color": "C0392B", "bold": true } },
+    { "op": "addSlide", "title": "What Changed", "body": ["Retitled the cover", "Recoloured the title"] }
+  ],
+  "output": "quarterly-v2.pptx"
+}
+```
+
+Slides count from 0. A `shape` is `"title"`, `"subtitle"`, `"body"`, or the
+`id` a read returned.
+
+| The change                   | The op                                                                                     |
+| ---------------------------- | ------------------------------------------------------------------------------------------ |
+| Replace a shape's text       | `{ "op": "setText", "slide": 1, "shape": "body", "text": ["First", "Second"] }`             |
+| Replace one table cell       | `{ "op": "setCellText", "slide": 2, "shape": 4, "row": 1, "column": 1, "text": "450 nm" }` |
+| Size, colour, font, bold     | `{ "op": "setStyle", "slide": 0, "shape": "title", "style": { "size": 40, "font": "Georgia" } }` |
+| Add a slide like its neighbours | `{ "op": "addSlide", "title": "Next Steps", "body": ["Ship it"] }`                      |
+| Add a slide at a position    | `{ "op": "addSlide", "at": 1, "title": "Agenda", "body": ["Why", "How"] }`                 |
+| Delete a slide               | `{ "op": "deleteSlide", "slide": 3 }`                                                       |
+| Move a slide                 | `{ "op": "moveSlide", "from": 4, "to": 1 }`                                                 |
+| Add a picture                | `{ "op": "addPicture", "slide": 2, "image": { "attachmentId": "9be07c12" }, "width": 6 }`  |
+| Add a free text box          | `{ "op": "addTextBox", "slide": 5, "text": "Thanks", "style": { "size": 54, "align": "center" } }` |
+| Add a table                  | `{ "op": "addTable", "slide": 3, "rows": [["Band", "nm"], ["Blue", 450]], "header": true }` |
+| Change a chart's numbers     | `{ "op": "setChartData", "slide": 2, "shape": 4, "categories": ["Q1", "Q2"], "series": [{ "name": "2026", "values": [11, 13] }] }` |
+| Retitle a chart              | `{ "op": "setChartTitle", "slide": 2, "shape": 4, "title": "Revenue by quarter" }`          |
+| Solid background             | `{ "op": "setBackground", "slide": 5, "color": "101820" }`                                  |
+
+`addSlide` without `layout` copies the layout of the deck's last content slide,
+so the new slide matches its neighbours. Never pick `Blank` for an ordinary
+title-and-bullets slide on a deck the user gave you. Positions and sizes (`x`,
+`y`, `width`, `height`) are inches; give one of `width`/`height` and the
+picture keeps its shape. Colours are six hex digits, no `#`.
+
+Name the output after the deck you opened and bump a version: `quarterly.pptx`
+→ `quarterly-v2.pptx`, and an edit of that → `quarterly-v3.pptx`. Never the
+input's own name.
+
+## Images
+
+- An image this chat generated: `"image": { "attachmentId": "<id from the generate_image result>" }`.
+- An image the user attached to their latest message: `"image": {}` — an
+  uploaded image shows no id, and the empty form picks it up.
+- An image behind a URL cannot be downloaded. Say so, and ask the user to attach
+  it or offer `generate_image`.
 
 ## Rules for Every Job
 
-**You build it, not the user.** Deliver the deck, never the recipe. Do NOT
-print the python source in chat, do NOT tell the user to install python-pptx,
-run a script, or open a terminal — they have no terminal in this chat and the
-code would not run there. The deck exists only if an `exec` call with
-`outputs` succeeds and returns the attachment. Falling back to "here is the
-script, run it yourself" is a failed turn, and so is writing slides as
-markdown/chat text instead of the `.pptx` the user asked for — answering a
-*read* request as chat text is the read flow's finish, not this failure.
-
-**Success = stop.** When `exitCode` is `0` and `attachments` lists the
-`.pptx`, the deck is done. Do not call `exec` again for the same request —
-not to "confirm", not to "improve", not a second identical build; a second
-deck attach is rejected. Exactly one successful **build** `exec` per deck
-request — a no-`outputs` read delivers nothing and is not one of them: it
-belongs before the build on an edit, never after it, and on a read request it
-stands alone. Reply with a single line: file name + slide count from stdout.
-If the result has `missingOutputs` instead, the file was never written: check
-the `save()` name matches the declared output and rerun once.
-
-**Failures are fixed in the code, not around it.** If a run fails, fix the
-Python against the loaded reference file's recipes and errors table and call
-`exec` again. If two consecutive calls fail with the same error, the fix from
-the first attempt did not land — re-read the traceback line-by-line before a
-third call; retrying the identical `command`, or a version with only cosmetic
-changes, is a loop, not a fix. An error in your code is never a fault in
-python-pptx or in the runtime: do not switch package pins or hunt a "more
-compatible" version — keep `packages: ["python-pptx==1.0.2"]` — do not wrap
-source in `python -c "…"`, `python3`, `pip`, or shell, and do not "debug" with
-`os.listdir`, `print`, or a non-deck script while `outputs` still lists the
-deck. Never search the web about an error; the answer is always in the result
-you already have.
-
-**The runtime is sealed.** There is no shell — `ls`, `cat` and `file` raise
-`SyntaxError`, because the `command` is Python source — and no filesystem to
-check outside the `exec` result. There is no network: `requests`, `urllib`,
-and `socket` all fail, and `http_request` returns truncated text, never image
-bytes — an image behind a URL cannot be downloaded; ask the user to attach it
-or offer `generate_image`. The working directory starts empty on every call:
-a file from an earlier call is gone unless staged again by its attachment id,
-and a file you write but do not declare in `outputs` is discarded.
-
-**Never overwrite a staged input.** An edit always saves under a new,
-version-bumped name — `deck.pptx` → `deck-v2.pptx` — and a corrected rebuild
-after a broken delivery goes out under the next version, never the name
-already attached this turn.
+**You build it, not the user.** The deck exists only when a `pptx` call with
+`ops` returns its attachment. Never write the slides as chat text instead, and
+never tell the user to run anything.
+
+**Success = stop.** When the result lists the attachment, reply with one line —
+the file name and the slide count — and call nothing else. Check `slides` in
+the result against the request first: one slide added to a 2-slide deck is
+`3`; `4` means an op ran twice, so fix the ops and send them again under the
+next version name.
+
+**Errors name the fix.** A failed call returns a message that says what exists
+— `slide 7 does not exist; the deck has 3 slides (0 to 2)`, or the shapes on
+the slide. Correct that one op and call again. Never repeat an identical call.
+
+## What This Cannot Do
+
+Say so instead of faking it: writing speaker notes, editing scatter, bubble or
+stock charts, SmartArt, and legacy `.ppt` files.

package/skills/sheet-music/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sheet-music
+description: Turn audio into sheet music. Transcribe a recording or a generated track into a score you can read, print, or open in any notation app.
+tools: [transcribe_music]
+platform: [darwin, linux, win32]
+---
+
+# Sheet music
+
+Call `transcribe_music` when the user wants notation for audio that already
+exists: sheet music, a score, the chords, the notes, the melody, "write this
+out". It reads an audio attachment from the chat and saves a `.musicxml` score,
+which the app shows as readable sheet music in the conversation with a PDF
+download; it also opens in MuseScore, Sibelius or Dorico.
+
+```json
+{ "title": "kitchen demo" }
+```
+
+**Do not invent an `attachmentId`.** An attached audio file never appears in the
+conversation with an id, so there is nothing to copy: leaving the field out is
+how you say "the track the user just attached".
+
+## When to Use
+
+- The user attached audio and wants it written out as notation.
+- A track was generated earlier in this chat and the user now asks for its sheet
+  music, chords, or notes.
+- The user asks what notes or chords are in a recording.
+
+## When NOT to Use
+
+- The user is asking for a *new* song — that is `generate_music`. If they want the
+  track and its sheet music together, call `generate_music` with
+  `sheetMusic: true` instead of making two calls.
+- The user wants spoken words written down — that is speech transcription, not
+  this.
+
+**If `transcribe_music` returns an error, report it and stop.** Never fall back to
+`generate_music`: that writes a brand new piece, and presenting it as the user's
+transcription is a lie about their own audio. The error text says what to change,
+usually to omit `attachmentId`, so read it and retry the same tool.
+
+## Parameters
+
+- `attachmentId` — **omit it** to transcribe the most recent audio in the chat,
+  which is what an attached track means. Pass one only to reach back to an older
+  track whose id a previous `generate_music` actually returned.
+- `title` — a short title, 2 to 5 words; it names the saved files.
+- `bpm` — pass it whenever the tempo is known. **If you generated the track in
+  this chat with a `bpm`, pass that same value here.** Tempo estimated from audio
+  is right about the beat but can land an octave off (60 where the track is 120),
+  and a known tempo removes that guess entirely.
+- `keyscale` — same idea for the key, e.g. `C minor`. Estimated when omitted.
+
+## What comes back
+
+The result names the score attachment and reports what was transcribed: `notes`,
+`bars`, `bpm`, `key`, how many artifacts were filtered out, and two flags worth
+reading before you reply:
+
+- `tempoFromRequest` — false means the tempo was estimated. Worth a word to the
+  user if the rhythm looks doubled or halved.
+- `melodyMissing` — nothing was found above middle C. Say so plainly: on a dense
+  mix the transcription captures the bass and the loudest lines, and the melody
+  is buried. Do not present that score as a full transcription.
+
+## Honesty about quality
+
+This is automatic transcription, not a human copyist, and the result depends
+almost entirely on how dense the audio is.
+
+- **A solo instrument or a small ensemble transcribes well.** Piano, guitar,
+  a single voice, a duo.
+- **A full band mix does not.** Distortion and cymbals mask everything in the
+  middle, so what survives is the bass line and whichever line is loudest.
+- Percussion is not pitched and is not transcribed.
+- Sustained notes are approximate: the score reads the right pitches with
+  quantized rhythm, not a performance-accurate transcription.
+
+Tell the user which of these they are getting rather than letting them discover
+it.
+
+## A track and its score together
+
+Sheet music never changes the track. Generate what the user asked for: their
+duration, their instrumentation, their genre.
+
+Dense or long material makes a crowded score, and that is worth saying. Before
+generating, when they have left the choice open, offer it: a sparse 30-60 second
+piece gives a score a person can actually read. After generating, say plainly
+what they got when the result comes back with `melodyMissing` or sixty-odd bars.
+Never quietly substitute something shorter or sparser than they asked for.