@qvac/skills 0.1.11 → 0.1.12

package/skills/excel/references/edit.md

@@ -1,357 +0,0 @@
-# Editing an Attached Workbook (openpyxl)
-
-Edit a workbook that is already in this chat by running Python through the
-`exec` tool: change cells, add or insert rows, add columns or sheets, delete
-rows, columns, or sheets. Stage the workbook as an input, modify it, and save
-under a **new** output name such as `revised.xlsx` — never overwrite the staged
-input.
-
-**No `.xlsx` in this chat means this is not an edit.** "Put this image in a
-spreadsheet" with no workbook to open is a CREATE: load `references/create.md` and
-build a new one. Never ask the user to attach a workbook they did not mention.
-
-Macro-enabled files (`.xlsm`) can be staged as inputs and read, but this
-runtime cannot deliver `.xlsm` back — macros never survive. Save the edit as
-`.xlsx` and tell the user the macros were not preserved.
-
-## Staging the Workbook
-
-**A workbook you built earlier in this chat is edited exactly like any other
-attachment — through its id.** The `exec` result that produced it carried
-`attachments: [{ attachmentId, fileName, byteLength }]`; scroll back, copy that
-`attachmentId` character for character, and stage it. The working directory is
-wiped between calls, so a file you saved last turn is not on disk — without a
-staged input `load_workbook("report.xlsx")` raises
-`FileNotFoundError: [Errno 44] No such file or directory`.
-
-```json
-{
-  "language": "python",
-  "packages": ["openpyxl==3.1.5"],
-  "inputs": [{ "attachmentId": "<the id from the earlier exec result>", "path": "existing.xlsx" }],
-  "outputs": ["revised.xlsx"],
-  "command": "..."
-}
-```
-
-**A workbook the user uploaded is staged the same way — by its id.** The
-`[Attached file …]` line on their message names it:
-
-```
-[Attached file "budget.xlsx" (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) — attachmentId: 4f9c2ab1]
-```
-
-Copy that id verbatim into `attachmentId`, exactly as for a workbook a tool
-produced. This holds for **`.csv` and `.xlsm` uploads too**, not just `.xlsx`: an
-id-less entry resolves to an uploaded *image*, so any `inputs` entry whose `path`
-names a data or document file is rejected outright. Only an uploaded **image** is
-staged with `path` alone and no `attachmentId` key.
-
-Staged files land in the working directory under the bare `path` names —
-reference `load_workbook("existing.xlsx")` by that name only.
-`attachment … not found in this chat` means you invented an id or the file is not
-attached. Re-copy the exact id from the `exec` result or the `[Attached file …]`
-line that names the workbook; if no id appears anywhere in the chat, ask the
-user to attach the file again.
-
-`wb.save("revised.xlsx")` must match the declared output name. Keep the
-`command` source multi-line with real newlines — never collapse it with `;`.
-
-## Adding an Image to an Existing Workbook
-
-Stage two files: the workbook by its `attachmentId`, and the picture. Add `"pillow"`
-to `packages` — **deliberately unpinned**, since the runtime owns its version and a
-pin sends openpyxl to PyPI with it.
-
-```json
-{
-  "language": "python",
-  "packages": ["openpyxl==3.1.5", "pillow"],
-  "inputs": [
-    { "attachmentId": "<id of the workbook>", "path": "existing.xlsx" },
-    { "attachmentId": "<id from the generate_image result>", "path": "photo.png" }
-  ],
-  "outputs": ["revised.xlsx"],
-  "command": "..."
-}
-```
-
-`path` is a name you choose; it has nothing to do with the attachment id, and a
-`fileName` seen in a tool result is not a file on disk. A `generate_image` result
-anywhere in the conversation is the image the request points at — stage that id
-rather than asking the user to attach it again.
-
-```python
-from openpyxl.drawing.image import Image as XLImage
-
-img = XLImage("photo.png")           # the path from inputs, nothing else
-img.width, img.height = 320, 320     # pixels
-ws.add_image(img, "A1")              # a worksheet method; A1 is the top-left corner
-```
-
-One `add_image` per workbook — inside a loop over sheets it embeds a copy per sheet.
-Never wrap the import or the call in a `try`/`except` that saves anyway.
-
-## The Golden Rule of Edits
-
-**The staged sheet already has its header and all its data.** Editing never
-re-creates them: no `HEADERS`, no `ROWS`, no copy of the create template. Append
-only what is genuinely new, and change only the cells you were asked to change.
-Re-appending the header and the rows writes the whole table a second time and the
-user opens a file where every row appears twice — the create template belongs to
-the create path (`references/create.md`) and nowhere else.
-
-Adding one row is the whole program:
-
-```python
-from openpyxl import load_workbook
-
-wb = load_workbook("existing.xlsx")
-ws = wb.active                       # wb["Sheet Name"] to pick another
-
-before = ws.max_row                  # the sheet is already this long
-ws.append([2026, 82500, 135000, 107500])
-
-wb.save("revised.xlsx")              # NEW name, matching the declared output
-print(f"{before} rows in, {ws.max_row} rows out")
-```
-
-That print is the check: one added row means the count goes up by exactly one. If
-it roughly doubles, the run re-appended the existing data — fix it and rerun
-rather than delivering a workbook with the table in it twice.
-
-## Putting the Row Where It Belongs
-
-Appending is right when the table has no order, and wrong when it has one: a sheet
-running 2016…2026 with 2015 stuck on the end reads as broken. When the new row
-belongs inside an existing order, insert it at that position instead.
-
-You already know the position — 2015 sorts above 2016, and the data starts at row 2
-— so write the index as a number. Do not scan, sort, or compare anything to work it
-out:
-
-```python
-from openpyxl import load_workbook
-
-wb = load_workbook("existing.xlsx")
-ws = wb.active
-
-ROW = [2015, 278, 930, 45.5]
-AT = 2                               # 2015 goes above 2016 — row 1 is the header
-
-assert not any(m.max_row >= AT for m in ws.merged_cells.ranges) and not any(
-    isinstance(c.value, str) and c.value.startswith("=") for r in ws.iter_rows() for c in r
-), "a merged range at or below AT, or a formula — append instead, their ranges do not move"
-
-before = ws.max_row
-ws.insert_rows(AT)
-for column, value in enumerate(ROW, start=1):
-    cell = ws.cell(row=AT, column=column, value=value)
-    cell.number_format = ws.cell(row=AT + 1, column=column).number_format
-
-wb.save("revised.xlsx")
-print(f"{before} rows in, {ws.max_row} rows out")
-```
-
-`AT` is never `1` — that would push the header down into the data.
-
-The two lines that look optional are the ones that matter. An inserted cell starts
-with no number format, so without the copy the new row shows a bare `278` in a
-column of `278.00`s; taking the format from `AT + 1` uses the row that used to sit
-there. And `insert_rows` moves cells but neither formula ranges nor merged ranges,
-so a `=SUM(B2:B11)` total would go on summing the old span and quietly leave the
-new row out, while a `Total` merged across `A8:B8` would stay pinned to row 8 as
-its row slid to 9 — the assert stops both before anything is saved.
-
-The two halves are scoped differently on purpose. A merged range is disturbed only
-if it sits at or below `AT`, which is why the check is `m.max_row >= AT` rather than
-"any merged cell": a title merged across `A1:C1` is untouched by an insert further
-down, and failing on it would push you to append out of order for no reason. A
-formula gives no such signal — one in `D1` can reference `B2:B11` — so any formula
-at all is enough to stop the insert.
-
-When the assert fires, do not delete it. Append the row at the end with the
-previous template and tell the user the table kept its file order so their totals
-stay correct.
-
-## Other Edits — Touch Only What Changes
-
-```python
-from openpyxl import load_workbook
-from openpyxl.styles import Font
-
-wb = load_workbook("existing.xlsx")
-ws = wb["Q1 Sales"]                  # or wb.active; wb.sheetnames lists them
-
-ws.cell(row=1, column=5, value="Margin %").font = Font(bold=True)
-for row, margin in [(2, 0.31), (3, 0.42), (4, 0.18)]:
-    cell = ws.cell(row=row, column=5, value=margin)
-    cell.number_format = '0.0%'
-
-ws["B2"] = 150                       # update a cell in place
-
-notes = wb.create_sheet("Notes")
-notes["A1"] = "Updated unit counts for North"
-
-wb.save("revised.xlsx")              # NEW name, matching the declared output
-print(f"{len(wb.sheetnames)} sheets: {wb.sheetnames}")
-```
-
-`wb["Sheet Name"]` raises `KeyError` when the name does not exist — when unsure,
-print `wb.sheetnames` in the same run that edits, pick from it, and never guess.
-
-## Deleting Rows, Columns and Sheets
-
-openpyxl deletes for real, so none of this needs XML work. `ws.delete_rows(index)`
-and `ws.delete_cols(index)` take a **1-based** index and an optional count, so
-`ws.delete_rows(5, 3)` drops rows 5, 6 and 7 together; a sheet goes with
-`del wb["Notes"]`. Row 1 is the header — `delete_rows(1)` throws it away, and data
-rows start at 2, exactly as for an insert.
-
-**Delete from the bottom up.** Each delete shifts everything below it, so a loop
-over ascending indices removes the wrong rows after the first: dropping rows 3 and
-5 top-down deletes row 3, then deletes what used to be row 6. Collect the row
-numbers first and walk them in reverse — the same rule applies right-to-left for
-`delete_cols`:
-
-```python
-from openpyxl import load_workbook
-
-wb = load_workbook("existing.xlsx")
-ws = wb.active
-
-DROP = (2021, 2023)                  # the column-A values whose rows go
-
-before = ws.max_row
-targets = [r for r in range(2, ws.max_row + 1) if ws.cell(row=r, column=1).value in DROP]
-assert targets, f"no row matched {DROP} — check the values are numbers, not strings"
-
-assert not any(m.max_row >= min(targets) for m in ws.merged_cells.ranges) and not any(
-    isinstance(c.value, str) and c.value.startswith("=") for r in ws.iter_rows() for c in r
-), "a merged range at or below the first deleted row, or a formula — their ranges do not move"
-
-for row in reversed(targets):        # bottom-up; ascending order deletes the wrong rows
-    ws.delete_rows(row)
-
-wb.save("revised.xlsx")              # NEW name, matching the declared output
-print(f"{before} rows in, {ws.max_row} rows out")
-```
-
-The `assert targets` line is what stops a no-op being delivered, and it belongs
-before the loop rather than after it. Without it, values that match nothing leave
-the sheet untouched and the workbook still saves at `exitCode 0` with an
-attachment indistinguishable from a real delete. With it the run raises, nothing
-is written, and the result carries `missingOutputs` instead. The usual cause is a
-type mismatch — the string `"2021"` is not the number `2021` — or a wrong column
-index. **An assert that fires is a failed turn to diagnose, not a workbook to
-deliver**: fix the match and rerun, and never delete the assert to get a file out.
-The printed `rows in / rows out` line is then the reply line, not the check, and it
-still costs no extra call — both live in the run that does the deleting.
-
-The second assert is the `insert_rows` hazard in reverse, and it covers the same two
-things with the same scoping. `delete_rows` moves cells but leaves formula text
-alone, so a `=SUM(B2:B11)` total goes on summing eleven rows of a table that now
-holds nine, pulling in blanks or the wrong cells. It leaves merged ranges alone too:
-a `Total` merged at `A8:B8` keeps covering row 8 after a row above it is deleted, and
-a title merged across `A1:C1` still claims three columns after a `delete_cols`. Both
-are silent — no error, and the damage only shows when the user opens the file.
-
-Merges are again checked from the first deleted row down (`m.max_row >= min(targets)`),
-so a banner above every deletion does not block the edit, while any formula anywhere
-does. When it fires, do not delete it: say which rows you would have removed and ask
-whether to drop the merges and formulas too, or tell the user the deletion has to
-happen in Excel, where the ranges follow. Note the column case is not covered by that
-row check — if you are calling `delete_cols` on a sheet with horizontal merges, treat
-any merged range as a stop.
-
-## Reading Cell Values During an Edit
-
-`load_workbook` has two modes, and neither gives both formulas and values:
-
-- `load_workbook("f.xlsx")` — formula cells hold the formula **string**
-  (`"=SUM(D2:D4)"`).
-- `load_workbook("f.xlsx", data_only=True)` — formula cells hold the value the
-  last spreadsheet app **cached** when it saved. A file that openpyxl itself wrote
-  has no cache, so these cells read `None`.
-
-Plain data cells read the same either way. When a formula cell reads `None` under
-`data_only=True`, the file was never recalculated by a spreadsheet app — compute
-the number in Python from the data cells instead of hunting for it.
-
-**Never `save()` a workbook opened with `data_only=True`.** That mode loads values
-in place of formulas, so saving writes the values back and every formula the user
-had is gone — silently, at `exitCode 0`, with an attachment that looks fine. A
-workbook you intend to save is always opened plainly:
-
-```python
-from openpyxl import load_workbook
-
-values = load_workbook("existing.xlsx", data_only=True)   # read numbers here
-wb = load_workbook("existing.xlsx")                       # edit and save this one
-```
-
-Read from `values`, write to `wb`, and save `wb`. One open, one job.
-
-That is reading in service of an edit. Reading for the *user* — a summary or an
-answer delivered as chat text — is its own flow with its own call shape: load
-`references/read.md`.
-
-## Errors
-
-- Never print the workbook's bytes or base64 — stdout is capped and the file
-  travels through `outputs`. A build call prints only a short summary line.
-  Never pass an absolute path to `save()`.
-- `attachment … not found in this chat` — `inputs` listed an id that is not in
-  this chat (often a copied placeholder). Only stage real ids from prior tool
-  results or `[Attached file …]` lines.
-- `an id-less input stages an uploaded image, and this path names a document` —
-  an `.xlsx` was staged with no `attachmentId`. Spreadsheets are always staged
-  by id.
-- `no uploaded image in this chat — attach an image or pass an attachmentId` —
-  an id-less input was sent when the user uploaded no image at all.
-- `FileNotFoundError: [Errno 44] No such file or directory` on a workbook you
-  saved in an earlier call means it was never staged: the working directory is
-  fresh every call. Add the file to `inputs` with its `attachmentId`.
-- A delivered workbook whose formulas have turned into blanks means it was opened
-  with `data_only=True` and then saved. Open a second, plain workbook to edit.
-- A delivered workbook whose table appears twice means the edit re-appended the
-  header and rows onto the staged sheet. An edit adds only what is new.
-- `AssertionError: a merged range at or below AT, or a formula — append instead …`
-  means a merged range sits at or below the insertion row, or the sheet has a formula
-  whose range `insert_rows` would not move. Append the row at the end instead and say
-  why in the reply.
-- `AssertionError: a merged range at or below the first deleted row, or a formula …`
-  is the same hazard on a delete, and has no safe fallback: say which rows you would
-  remove and ask the user how to handle the merges and formulas.
-- `AssertionError: no row matched …` means the delete found nothing, usually because
-  the compared values are strings on one side and numbers on the other. Diagnose the
-  match and rerun; do not remove the assert, because the workbook it would deliver
-  is the staged one unchanged.
-- Rows that disappeared from the wrong places mean the delete loop ran over
-  ascending indices. Collect the targets first and delete in reverse.
-- A row that renders unlike the rest of its column — `278` among `278.00`s — was
-  inserted without copying `number_format` from the row below it.
-- `'MergedCell' object attribute 'value' is read-only` means the write hit a merged
-  non-anchor cell — write the range's top-left cell instead.
-- `".xlsm" is not an allowed output type` means the run tried to deliver a
-  macro-enabled file — save as `.xlsx` and tell the user macros were not preserved.
-- `KeyError` on `wb["Sheet Name"]` — the sheet name does not exist; print
-  `wb.sheetnames` in the run that edits and pick from it.
-- `ModuleNotFoundError: No module named 'openpyxl'` — add
-  `["openpyxl==3.1.5"]` to `packages` and rerun. Never try to install it.
-- `ImportError: You must install Pillow to fetch image objects` means an image was
-  embedded without `"pillow"` in `packages` — openpyxl does not install it.
-- `FileNotFoundError` on a 32-character hex name means an attachment id was opened as
-  a path. The id belongs in `attachmentId`; open the `path` you chose.
-- On an `AttributeError` from openpyxl the API name is wrong, and on a `TypeError`
-  about missing positional arguments a required argument was left out — fix either
-  against this file's examples. Do not retry the same call, and do not switch to a
-  shell.
-
-## Finish
-
-When `exitCode` is `0` and `attachments` lists the `.xlsx`, stop tool use and
-answer with one line: file name + the `rows in / rows out` (or sheets) summary
-from stdout. Exactly one successful `exec` per request. 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.

package/skills/excel/references/read.md

@@ -1,99 +0,0 @@
-# Reading a Workbook to Answer in Chat (openpyxl)
-
-When the user asks what an attached workbook *holds* — a summary, a question
-answered, specific values pulled out — the deliverable is your reply in the
-chat, not a file. This is a **read request**: exactly one `exec` call, staging
-the workbook in `inputs` and declaring **no `outputs`**, whose whole job is to
-print the sheets so you can read them in the result.
-
-## The exec call
-
-```json
-{
-  "language": "python",
-  "packages": ["openpyxl==3.1.5"],
-  "inputs": [{ "attachmentId": "<id from the [Attached file …] line>", "path": "existing.xlsx" }],
-  "maxOutputChars": 24000,
-  "command": "..."
-}
-```
-
-The id rules: copy it verbatim from the `[Attached file …]` line on the user's
-message or from the earlier `exec` result that produced the file, never invent
-one, never stage a workbook id-less (an id-less entry resolves to an uploaded
-*image*). If no id appears anywhere in the chat, ask the user to attach the
-file again. `maxOutputChars` raises the stdout cap so a full workbook comes
-back in one result; keep the sample's 24000. Declare no `outputs` — a read
-builds nothing.
-
-## The Read Program
-
-Prints every sheet under a `[Sheet]` marker, then its rows — one printed line
-per row:
-
-```python
-from openpyxl import load_workbook
-
-wb = load_workbook("existing.xlsx", data_only=True)
-for name in wb.sheetnames:
-    ws = wb[name]
-    print(f"[Sheet] {name} ({ws.max_row} rows)")
-    for row in ws.iter_rows(values_only=True):
-        print(" | ".join("" if v is None else str(v).replace("\n", " ") for v in row))
-```
-
-The `replace` is load-bearing: a multi-line cell (Alt+Enter in Excel) embeds
-`"\n"` in its value, and an embedded newline would split one row across two
-printed lines. Flattened, every printed line is exactly one sheet row.
-
-`data_only=True` is the right mode here: a formula cell prints the value the
-last spreadsheet app cached, or an empty field when the file was never
-recalculated (`None` prints as nothing). An empty field under a `Total` header
-is that, not missing data — say so, and when the answer needs the number, work
-it out from the data rows that did print.
-
-**You cannot summarize in the call that reads.** The words in `command` are
-fixed before the program runs, so one call cannot inform itself: any summary
-written into it was written blind — recalled or invented, not read. Python only
-*transports* the values; the summarizing happens in your reply, after the
-result comes back.
-
-## A Successful Read Ends Tool Use
-
-When the result prints the sheets, reply with the summary or the answer as chat
-text — when the user asked for the table in the chat, that reply is a markdown
-table built from the rows you read, never from memory. **Scale the reply to the
-workbook**: a summary is much shorter than what it summarizes — a small sheet
-earns a few sentences, and only a many-sheet workbook earns sections. Restating
-every row is not a summary. Do **not**:
-
-- call `exec` again to "re-check", "read more", or read the same workbook a
-  second time;
-- build a summary `.xlsx` the user never asked for — an unrequested file is a
-  failed turn, not a bonus.
-
-If stdout ends with `… [truncated]`, the workbook is longer than the cap:
-answer from what came back and say the answer covers the sheets up to that
-point. Do not rerun the read — it prints the same beginning again.
-
-If the user asks for the summary **as a file**, that is a read followed by a
-build: the read call above first, then one build call that writes the new
-workbook from the values you actually read (load `references/create.md` for the
-build). The read still declares no `outputs`.
-
-## Errors
-
-- `attachment … not found in this chat` — the id was invented or the file is
-  not attached. Re-copy the exact id; if none exists, ask the user to attach
-  the file again instead of retrying.
-- `an id-less input stages an uploaded image, and this path names a document` —
-  the workbook was staged with no `attachmentId`. Spreadsheets (`.xlsx`,
-  `.csv`, `.xlsm`) are always staged by id.
-- `FileNotFoundError: [Errno 44] No such file or directory` — the file was
-  never staged; the working directory is fresh every call. Add it to `inputs`
-  with its `attachmentId`.
-- `ModuleNotFoundError: No module named 'openpyxl'` — add
-  `["openpyxl==3.1.5"]` to `packages` and rerun. Never try to install it.
-- A formula cell that prints nothing is not a bug — the file was never
-  recalculated by a spreadsheet app. Compute the number from the data rows
-  instead of rerunning.

package/skills/pdf/references/create.md

@@ -1,169 +0,0 @@
-# Creating a PDF (fpdf2)
-
-Create a new `.pdf` from scratch by running Python through the `exec` tool.
-A new PDF needs **no** `inputs` — do not invent attachment ids. **Exactly one**
-`exec` call per user request when that call succeeds.
-
-This file is also the recipe for **changing the content of an existing PDF**
-(add a paragraph, reword, restyle): pypdf cannot edit page content, so the job
-is writing the whole document again with fpdf2 — every original section,
-reproduced unchanged, plus the requested change. A rebuild that condenses,
-summarizes, or drops original sections is a failed turn; the user must get
-their document back with only the asked-for difference. Save the rebuild under
-a **new** output name (`updated.pdf`, never the original file's name), and
-stop after the one successful build.
-
-## The exec call
-
-```json
-{
-  "language": "python",
-  "packages": ["fpdf2==2.8.8"],
-  "outputs": ["report.pdf"],
-  "command": "..."
-}
-```
-
-- `packages` — pin exactly `fpdf2==2.8.8` (imported as `fpdf`). This version
-  ships with the app and installs with no network; any other version has to be
-  downloaded, which fails on a device that is offline. Never install `fpdf`
-  (no `2`) — that is an abandoned, incompatible library.
-- `outputs` — the file to deliver. `pdf.output("report.pdf")` must match the
-  declared output name exactly.
-- `command` — the multi-line Python source, with real newline characters.
-  Never collapse it to one line joined by `;` — a `for`/`if`/`with` after a
-  semicolon is a `SyntaxError`.
-
-## The Recipe
-
-Start from this. It is a complete, working document — title, body paragraphs,
-a bulleted section, a table, automatic page breaks, saved under the declared
-output name. Copy it and change the content; do not assemble a PDF from memory.
-
-```python
-from fpdf import FPDF
-
-pdf = FPDF(format="A4")
-pdf.set_auto_page_break(auto=True, margin=15)
-pdf.add_page()
-
-pdf.set_font("helvetica", style="B", size=24)
-pdf.multi_cell(0, 12, "Quarterly Report", new_x="LMARGIN", new_y="NEXT")
-
-pdf.set_font("helvetica", size=12)
-pdf.ln(4)
-pdf.multi_cell(0, 6, "Revenue grew 20% quarter over quarter, driven by APAC. "
-                     "EMEA held flat while new logos offset churn.",
-               new_x="LMARGIN", new_y="NEXT")
-pdf.ln(2)
-
-pdf.set_font("helvetica", style="B", size=14)
-pdf.multi_cell(0, 10, "Highlights", new_x="LMARGIN", new_y="NEXT")
-pdf.set_font("helvetica", size=12)
-for point in [
-    "APAC bookings grew 34% and drove most of the quarter",
-    "EMEA held flat; new logos offset churn",
-    "Gross margin improved 2 points on infra savings",
-]:
-    pdf.multi_cell(0, 6, "- " + point, new_x="LMARGIN", new_y="NEXT")
-pdf.ln(2)
-
-with pdf.table() as table:
-    for row_data in [("Region", "Revenue"), ("APAC", "$1.2M"), ("EMEA", "$0.9M")]:
-        row = table.row()
-        for cell_text in row_data:
-            row.cell(cell_text)
-
-pdf.output("report.pdf")               # must match the declared output exactly
-print(f"{pdf.pages_count} pages")
-```
-
-## The Rules That Keep It Working
-
-- **Sizes are positional — there is no `width=` or `height=` keyword.** The
-  first two arguments of `cell` and `multi_cell` are `w` and `h`; passing
-  `width=` raises `TypeError`. The fix is renaming the arguments as in the
-  sample — never deleting the `new_x`/`new_y` keywords, which "fixes" the
-  error and prints every later line on top of the previous one.
-- **Every line of text goes through
-  `pdf.multi_cell(0, h, text, new_x="LMARGIN", new_y="NEXT")` — headings,
-  paragraphs, and bullets alike. Do not use `pdf.cell` at all.** `cell` does
-  not wrap, so a long heading is silently clipped at the right margin, and
-  without `new_x`/`new_y` it leaves the cursor at the END of the line so the
-  next write starts at the right margin — raising
-  `FPDFException: Not enough horizontal space` or printing on top of earlier
-  text. `multi_cell` wraps everything. Keep `new_x="LMARGIN", new_y="NEXT"`
-  on every call, exactly as in the sample. A bullet is one
-  `multi_cell(0, 6, "- " + point, …)` per point — never several bullets
-  packed into one string. `pdf.text(x, y, s)` is not a third option: it
-  paints at a fixed point with no wrapping and exists only for the watermark
-  stamp in `references/transform.md`.
-- **Write the whole document, not a cover page.** "A small PDF about X"
-  still means real content: a title, then several short sections, each a
-  heading plus a paragraph or bullets, as in the sample. A PDF containing
-  only a title and a subtitle is a failed turn — the explanation the user
-  asked for belongs inside the PDF, not in your chat reply.
-- **`set_font` before every block, not once.** A heading's bold 14-24 pt
-  style stays active until changed — reset to `pdf.set_font("helvetica",
-  size=12)` after each heading or the whole body renders huge and bold.
-  Core fonts: `helvetica`, `times`, `courier`; body text 10-12 pt.
-- **ASCII punctuation only.** The core fonts cover latin-1 and nothing else,
-  and one character outside it fails the whole cell with
-  `FPDFUnicodeEncodingException`. Curly quotes, em dashes, arrows, the •
-  bullet, CJK, and emoji are all outside. Write straight quotes `"` `'` and
-  hyphens `-` in every string — a bullet is `"- "`, never the `•` character.
-  Accented latin (`café`, `naïve`) is fine. When user content may carry smart
-  punctuation, normalize it first:
-
-  ```python
-  def latin1(text):
-      for bad, good in [("‘", "'"), ("’", "'"), ("“", '"'),
-                        ("”", '"'), ("–", "-"), ("—", "-"),
-                        ("…", "..."), ("→", "->"), ("•", "-")]:
-          text = text.replace(bad, good)
-      return text
-  ```
-
-  Text that genuinely needs CJK or emoji cannot be rendered — there are no
-  font files in this runtime and `add_font` has nothing to load, so never call
-  it. Say so and offer a latin transliteration instead of shipping `?`.
-- **Units are millimetres**, page format defaults to A4. `FPDF(format="letter")`
-  for US letter. An A4 page is 210 x 297 mm with 10 mm margins; a width of
-  `0` extends to the right margin.
-- **No markdown syntax in strings.** fpdf2 prints text literally — `##`,
-  `**bold**`, and `*italics*` come out as those exact characters. Headings
-  and emphasis are made with `set_font(..., style="B", size=…)`, as in the
-  sample.
-- **`pdf.output("name.pdf")` writes the deliverable.** Calling `output()`
-  with no argument returns the bytes instead — useful only for in-memory
-  intermediates; the file the user receives must be written under its
-  declared `outputs` name.
-- Never print the PDF's bytes or base64 — stdout is capped and the file
-  travels through `outputs`. Print only the page-count line.
-
-## Errors
-
-- `ModuleNotFoundError: No module named 'fpdf'` — `packages` was missing or
-  wrong; the pin is `fpdf2==2.8.8` (imported as `fpdf`). Never try to install
-  inside the script.
-- `TypeError: FPDF.cell() (or multi_cell) got an unexpected keyword argument
-  'width'` (or `'height'`) — the size parameters are the positional `w` and
-  `h`. Rewrite the call as in the sample —
-  `multi_cell(0, 6, text, new_x="LMARGIN", new_y="NEXT")`. Renaming is the
-  whole fix; deleting the keywords instead produces overlapping text.
-- `FPDFException: Not enough horizontal space to render a single character` —
-  an earlier `cell`/`multi_cell` left the cursor at the right margin. Add
-  `new_x="LMARGIN", new_y="NEXT"` to every `cell` and `multi_cell` call.
-- `FPDFUnicodeEncodingException: Character "…" is outside the range …` — a
-  non-latin-1 character reached a core font. Normalize the string (see the
-  `latin1` helper) and rerun; for CJK or emoji, tell the user it cannot be
-  rendered.
-- On an `AttributeError` or `TypeError` from fpdf2 the API name or arguments
-  are wrong — fix against this file's recipe. Do not retry the same call and
-  do not switch to a shell.
-
-## Finish
-
-When `exitCode` is `0` and `attachments` lists the `.pdf`, stop tool use and
-answer with one line: file name + the page count from stdout. Exactly one
-successful `exec` per request.