@qvac/skills 0.1.11 → 0.1.12

package/hash.js

@@ -1,2 +1,2 @@
 // Autogenerated by scripts/build.mjs from skills/. Do not edit.
-export const SKILLS_HASH = '5bc567ac3a7803c0'
+export const SKILLS_HASH = 'b97470e51b8846e3'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/skills",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Skills for the QV.AC app — the SKILL.md tree plus a content-addressed bundle of it.",
   "type": "module",
   "main": "index.js",

package/skills/excel/SKILL.md

@@ -1,127 +1,162 @@
 ---
 name: excel
-description: Create, edit, or read Excel spreadsheets (.xlsx) with openpyxl — deliver workbooks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Computes values in Python; can also write live formulas and embed images. Opens in Numbers and Google Sheets too.
+description: Create, edit, or read Excel spreadsheets (.xlsx) — deliver workbooks as chat attachments, or read an attached one to summarize it or answer questions in the chat. Writes values and live formulas and can embed images. Opens in Numbers and Google Sheets too.
 aliases: [xlsx, spreadsheet, workbook]
-tools: [exec(python)]
-platform: [darwin, linux, win32]
-# Routing tuned on Qwen3.5-4B for QVAC-24106 ("@excel embed this image into a spreadsheet" after a
-# generate_image turn). The bullet list sent 13/14 runs to edit.md, and 6/14 ended with no image in
-# a workbook, most by asking the user to attach one. As a request -> file table: 5/5 to create.md and
-# 5/5 embedded the image; "add a fourth row" to a workbook built in the chat still loads edit.md, 3/3.
-metadata:
-  {
-    "openclaw":
-      {
-        "setup":
-          {
-            "summary": "Runs openpyxl in the in-process Python runtime, from packages that ship with the app. The first use waits for the runtime to start."
-          }
-      }
-  }
+tools: [xlsx]
+platform: [darwin, linux, win32, ios, android]
 ---
 
 # Excel
 
-Build or edit an `.xlsx` workbook by running openpyxl through the `exec` tool with
-`language: "python"`. Declare the workbook in `outputs` and it comes back as a chat
-attachment the user can save. To answer *from* a workbook instead of building one,
-run a read call — no `outputs` — and reply in the chat.
+Every workbook job is one or two `xlsx` 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 workbook holds.
+
+## Pick the Call
+
+| The user wants                                                                        | The calls                                                           |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| "make a spreadsheet of …", "embed this image into a spreadsheet" — no `.xlsx` here yet | one call: `create` + `ops` + `output`                                |
+| "change B2 to 125", "add this image to my budget.xlsx" — an `.xlsx` is here           | one call: `attachmentId` + `ops` + `output`                          |
+| "add a total row", "fix the wrong prices" — the change depends on what is in it        | read (`attachmentId` alone), then one edit call                     |
+| "what is the total in this sheet?", "summarize this workbook"                         | read (`attachmentId` alone), then reply in the chat — no second call |
+| "summarize this workbook into a new file"                                             | read, then one `create` call written from what the read returned    |
+
+A workbook already in this chat is never rebuilt with `create` — that throws
+away everything the user has. Its `attachmentId` is in the tool result that
+produced it, or on the user's `[Attached file …]` line:
+
+```
+[Attached file "budget.xlsx" (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) — attachmentId: 4f9c2ab1]
+```
+
+Copy the id verbatim. Never make one up.
+
+**An image this chat generated is already attached.** A `generate_image` result
+in any earlier turn is the image "this image" means, and its `attachmentId` is
+the one to use. Never ask the user to attach an image the conversation already
+has.
+
+## A New Workbook
+
+```json
+{
+  "create": { "sheets": ["Sales"] },
+  "ops": [
+    { "op": "setCells", "sheet": "Sales", "cells": {
+      "A1": { "value": "Quarter", "bold": true },
+      "B1": { "value": "Units", "bold": true },
+      "C1": { "value": "Price", "bold": true },
+      "D1": { "value": "Revenue", "bold": true }
+    } },
+    { "op": "appendRows", "sheet": "Sales", "rows": [
+      ["Q1", 120, 9.5, "=B2*C2"],
+      ["Q2", 135, 9.5, "=B3*C3"],
+      ["Q3", 150, 10, "=B4*C4"],
+      ["Total", "=SUM(B2:B4)", null, "=SUM(D2:D4)"]
+    ] },
+    { "op": "setColumnWidth", "sheet": "Sales", "column": "A", "width": 14 }
+  ],
+  "output": "sales.xlsx"
+}
+```
+
+## Values and Formulas
+
+Text that starts with `=` is a formula. Nothing computes it here — the
+spreadsheet app does, the moment the user opens the file. So:
+
+- For a total, an average, or anything derived from other cells, write the
+  formula (`"=SUM(D2:D4)"`). It stays right when the user edits the numbers.
+- For numbers the user gave you or that you know, write the number.
+- A formula cell shows no value in the chat preview. Say so in the reply: "the
+  totals are live formulas, so they appear when you open the file."
+
+## Reading a Workbook
+
+```json
+{ "attachmentId": "4f9c2ab1" }
+```
+
+It returns every sheet — its name and used range, its rows of values, and a map
+of the formula in each formula cell. A formula's value is the result the file
+last saved, or `null` if nothing computed it yet — a `null` total is not missing
+data: compute it from the rows the formula names. Dates come back as ISO text.
+You cannot write a summary or a fix in the same call that reads, because the
+words are fixed before the workbook is opened. Read, then write from what came
+back. If the result says it was cut short, answer from what came back and say
+the answer covers the workbook up to that point.
+
+## Editing a Workbook
+
+```json
+{
+  "attachmentId": "4f9c2ab1",
+  "ops": [
+    { "op": "setCells", "sheet": "Sales", "cells": { "B3": 125, "A7": "Note", "D7": "=SUM(D3:D5)" } },
+    { "op": "appendRows", "sheet": "Sales", "rows": [["Q4", 80, 10.5, "=B8*C8"]] }
+  ],
+  "output": "budget_revised.xlsx"
+}
+```
+
+A `sheet` is its name or its index from 0. Cells are A1 references and rows
+count from 1, as in Excel.
+
+| The change                 | The op                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| Set cells                  | `{ "op": "setCells", "sheet": "Sales", "cells": { "B3": 125, "C3": "=B3*2" } }`              |
+| Clear a cell               | `{ "op": "setCells", "sheet": "Sales", "cells": { "B3": null } }`                            |
+| Format a cell              | `{ "op": "setCells", "sheet": "Sales", "cells": { "F4": { "value": 0.3, "format": "0.0%", "bold": true, "fill": "FFF2CC" } } }` |
+| A date                     | `{ "op": "setCells", "sheet": "Sales", "cells": { "G4": { "date": "2026-06-30" } } }`        |
+| Add rows at the end        | `{ "op": "appendRows", "sheet": "Sales", "rows": [["Q4", 80, 10.5]] }`                        |
+| Insert rows                | `{ "op": "insertRows", "sheet": "Sales", "at": 3, "rows": [["Q1b", 60, 9.5]] }`              |
+| Delete rows                | `{ "op": "deleteRows", "sheet": "Sales", "at": 5, "count": 2 }`                               |
+| Delete columns             | `{ "op": "deleteColumns", "sheet": "Sales", "column": "E", "count": 1 }`                      |
+| Column width               | `{ "op": "setColumnWidth", "sheet": "Sales", "column": "A", "width": 20 }`                    |
+| Add a sheet                | `{ "op": "addSheet", "name": "Notes" }`                                                       |
+| Rename a sheet             | `{ "op": "renameSheet", "sheet": "Notes", "name": "Commentary" }`                             |
+| Delete a sheet             | `{ "op": "deleteSheet", "sheet": "Scratch" }`                                                 |
+| Add a picture              | `{ "op": "addImage", "sheet": "Sales", "image": { "attachmentId": "9be07c12" }, "cell": "F2" }` |
+
+Renaming a sheet rewrites every formula that names it. `insertRows` and
+`deleteRows` are refused on a sheet with formulas, merges or tables that would
+not move with the rows — the error names which; use `setCells` and
+`appendRows` there instead.
+
+Name the output after the workbook you opened: `budget.xlsx` →
+`budget_revised.xlsx`. Never the input's own name. A macro-enabled `.xlsm` is
+saved as `.xlsx`: add `{ "op": "removeMacros" }` and tell the user the macros
+were not kept.
+
+## 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`.
 
-## 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.
-
-Pick the file by whether an `.xlsx` is already in this chat:
-
-| The request                                                                         | Load                                            |
-| ----------------------------------------------------------------------------------- | ----------------------------------------------- |
-| "make a spreadsheet of …", "embed this image into a spreadsheet" — no `.xlsx` yet    | `references/create.md`                          |
-| "add a row", "change B2", "add this image to my budget.xlsx" — an `.xlsx` is here    | `references/edit.md`                            |
-| "what is the total in this sheet?", "summarize this workbook" — the answer is a reply | `references/read.md`                            |
-| "summarize this workbook into a new file"                                           | `references/read.md` first, then create or edit |
-
-Load it with the `skill` tool: `name: "excel"` and that `file`.
-
-**An image this chat generated is already attached.** A `generate_image` result in
-any earlier turn is the image "this image" means, and its `attachmentId` stages it.
-Never ask the user to attach an image the conversation already has.
+## Rules for Every Job
 
-Never write the Python from memory. The recipes carry required patterns (the
-fill-in template, staging rules, guard asserts) that fail in non-obvious ways
-when improvised; loading the file is one cheap read-only call.
+**You build it, not the user.** The workbook exists only when an `xlsx` call
+with `ops` returns its attachment. Never answer with a markdown table instead
+of the file the user asked for, and never tell the user to run anything.
 
-## When to Use
+**Success = stop.** When the result lists the attachment, reply with one line —
+the file name and the sheets and rows it holds — and call nothing else.
 
-- The user asks for a spreadsheet, workbook, `.xlsx`, Excel, or Numbers/Sheets-openable file.
-- The user attaches a spreadsheet and wants cells changed, rows/columns/sheets added or removed, or data extracted from it.
-- The user attaches a spreadsheet and asks what it holds — a summary, a question
-  answered, or values pulled out into the chat.
-- The user wants a workbook that embeds an image — one generated in this chat or
-  one they uploaded. Both recipe files carry it.
+**Errors name the fix.** A failed call returns a message that says what exists
+— the sheet names, the used range. Correct that one op and call again. Never
+repeat an identical call.
 
 ## When NOT to Use
 
-- The user wants a table in the chat built from content already in the
-  conversation — no workbook involved — write a markdown table. Answering or
-  summarizing from an attached workbook **is** this skill: load
-  `references/read.md`.
-- The user wants a comma-separated text file only — write the `.csv` directly with Python's `csv` module (`.csv` is an allowed output), no openpyxl needed.
-
-## Values vs Formulas — decide before writing
-
-This runtime has no spreadsheet engine: openpyxl writes a formula as text and
-computes nothing. A formula cell has **no value** until the user opens the file
-in a spreadsheet app and it recalculates. So pick the mode from what the user
-wants:
+- A table in the chat built from what is already in the conversation, with no
+  workbook involved — write a markdown table.
 
-- **They want numbers** (a report, totals, statistics, cleaned data): compute in
-  Python and write **literal values**. This is the default.
-- **They want a live spreadsheet** (totals that update when they edit cells):
-  write formulas — and say so in the reply, because the formula cells look empty
-  in the chat preview: "the total is a live formula, so it shows up once you
-  open the file in Excel, Numbers, or Sheets."
-- Never write a formula and then read it back expecting a number, and never
-  "verify" a formula by reloading the file — there is nothing to verify.
-
-Writing both is fine: literal values everywhere, plus a `=SUM(...)` total row if
-the user wants it to stay live.
-
-## Rules for Every Job
+## What This Cannot Do
 
-**You build it, not the user.** Deliver the workbook, never the recipe. Do NOT
-print the python source in chat, do NOT tell the user to install openpyxl, run
-a script, or open a terminal — they have no terminal in this chat and the code
-would not run there. The workbook exists only if an `exec` call with `outputs`
-succeeds and returns the attachment.
-
-**Success = stop.** When `exitCode` is `0` and `attachments` lists the `.xlsx`,
-the workbook is done — do not call `exec` again, not to "confirm", not to
-"improve", not to reload the file to "check the formulas". Exactly one
-successful *build* call per request (a no-`outputs` read that precedes a build
-delivers nothing and is not one of them, but it belongs before the build, never
-after). Reply with a single line: file name + the sheet/row summary from stdout.
-If the result has `missingOutputs`, read stderr first: an `AssertionError` there
-means a guard stopped the save on purpose and its message names what to fix;
-only when stderr is clean 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 openpyxl or
-the runtime — keep `packages: ["openpyxl==3.1.5"]`, never wrap source in
-`python -c` or shell, never "debug" with `os.listdir` or no-op scripts.
-
-**The runtime is sealed.** No shell (`ls`, `cat` raise `SyntaxError` — the
-`command` is Python source) and no network (`requests` and `urllib` fail — a
-URL to a spreadsheet 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 via `inputs`, and a file you write but do not
-declare in `outputs` is discarded.
-
-**Never overwrite a staged input.** Edits always save under a new output name.
+Say so instead of faking it: charts in a workbook, pivot tables, editing
+conditional formatting or data validation (both are kept as they are), and
+legacy `.xls` files.

package/skills/music-generation/SKILL.md

@@ -42,6 +42,21 @@ prompt says.
 Set `duration` when the user asks for a specific length ("30 seconds", "a
 two-minute track"); otherwise leave it unset and let the model choose.
 
+## Sheet music
+
+`generate_music` can also write the finished track out as sheet music, saved as a
+score attachment, with `sheetMusic: true`. Offer it before generating whenever
+the request sounds like someone will play the result (a melody, a piano or guitar
+piece, a practice backing) or when they mention notes, chords or a score.
+
+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, so say so when the result comes back rather than quietly writing
+something sparser than they asked for. When the choice is genuinely open, a
+sparse 30 to 60 second piece gives a score a person can actually read.
+
+To write out audio that already exists, that is `transcribe_music`, not this.
+
 ## Parameters
 
 - `prompt` (required) - describe the genre, instruments, mood, and vocal

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.