@qvac/skills 0.1.11 → 0.1.12

package/skills/word/references/create.md

@@ -1,400 +0,0 @@
-# Creating a Word Document (python-docx)
-
-Create a new `.docx` from scratch by running Python through the `exec` tool.
-A new document needs **no** `inputs` — do not invent attachment ids — unless
-it embeds an image (see Embedding Images). **Exactly one** `exec` call per
-user request when that call succeeds.
-
-**A document that already exists in this chat is never rebuilt here.** "Replace
-the first 10 facts", "reword this", "add a section" — any request that starts
-from an existing `.docx` is a change to that document: some of its paragraphs
-is `references/paragraphs.md`, anything else is `references/rework.md`, and
-either one stages the document by its `attachmentId`. Building a fresh
-document for such a request throws away everything the user already has.
-
-## The exec call
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "outputs": ["report.docx"],
-  "command": "..."
-}
-```
-
-- `language` — always `"python"`.
-- `packages` — `["python-docx==1.2.0"]` on every call. The PyPI package is
-  `python-docx` but the import is `docx`; never list `docx` as the package —
-  that resolves a different, abandoned library. Pin the version; an unpinned
-  install resolves a potentially different library version. This exact 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.
-- `outputs` — `["report.docx"]`. `save("report.docx")` must match the declared
-  output name. A file you write but do not declare here is discarded. A `.doc`
-  output name is rejected — name it `.docx`.
-- `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`. Its first line is the first line of Python
-  that runs: there is no shell and no interpreter to invoke, and no
-  installer — packages are declared in `packages`.
-
-## Embedding Images
-
-Two kinds of image input, told apart by where the file came from:
-
-**Tool-produced images** (`generate_image` output): stage them with the exact
-`attachmentId` from the tool result — never placeholders like `att_image` or
-any id you made up.
-
-**Images the user uploaded** ("use this photo"): there is no id to copy — an
-uploaded image never shows one. Stage it with `path` only and **no
-`attachmentId` key**; the first id-less entry is the first image of the user's
-latest message, the second is its second image, and so on. Id-less entries
-resolve _images only_.
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "path": "photo.png" }],
-  "outputs": ["report.docx"],
-  "command": "..."
-}
-```
-
-Staged files land in the working directory under the bare `path` names —
-reference `doc.add_picture("photo.png", …)` by that name only. Paths must be
-unique bare filenames. `attachment … not found in this chat` means you
-invented an id or the file is not attached: re-copy the exact id from the tool
-result, or for a document with no image drop `inputs` entirely.
-
-If the image was staged in `inputs`, embed it in **that** single build with
-`doc.add_picture` — never deliver a document and then rebuild to add the
-image. Soft-failing (`try`/`except` around the picture) and saving without it
-is a failed turn, not a success.
-
-**Image URLs do not work — never download.** Your Python code has **no
-network access**: `requests`, `urllib`, and `socket` all fail with a network
-error, and `http_request` returns truncated text, never image bytes. When the
-user gives an image URL, do not try to fetch it from Python and do not retry
-through other tools — that is a dead end. Say the link cannot be downloaded
-and ask the user to attach the image itself, or offer `generate_image` for a
-similar visual. Then build the document with the staged attachment as above.
-
-## Which Shape
-
-| The user asks for                                                                        | Shape                                                                                                                                                 |
-| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "30 fun facts about cats", "10 tips for …", "a list of …", any number of items or points | **List** — a title, then exactly N `List Bullet` paragraphs and nothing else: no intro sentence, no section headings, no numbers typed into the text |
-| a report, memo, letter, plan — anything with sections                                    | **Report** — the recipe under The Recipe below                                                                                                        |
-
-### The list shape
-
-```python
-from docx import Document
-
-doc = Document()
-doc.add_heading("30 Fun Facts About Cats", level=0)
-facts = [
-    "Cats sleep for about 70 percent of their lives.",
-    "A group of cats is called a clowder.",
-    "A cat's nose print is unique, like a fingerprint.",
-]                                       # one plain string per item — write all N here
-for fact in facts:
-    doc.add_paragraph(fact, style="List Bullet")
-doc.save("cat_facts.docx")             # must match the declared output exactly
-print(f"{len(facts)} items, {len(doc.paragraphs)} paragraphs, {len(doc.tables)} table(s)")
-```
-
-One string per item, as many as the user asked for. No headings between
-groups of items and no introductory sentence: each of those is a paragraph the
-user did not ask for, and a later "change the first 10 items" then lands on the
-wrong lines. The count line it prints is the reply — a delivered list is done,
-whatever the count says; never rebuild it to fix the number.
-
-## The Recipe
-
-Start from this for a report. It is a complete, working document — a title, headings,
-paragraphs with bold and italic runs, a bulleted list, and a table — saved
-under the declared output name. Copy it and change the content; do not
-assemble a document from memory.
-
-**Keep the source multi-line.** A `for`/`if`/`with` after a semicolon is a
-`SyntaxError` — paste the block with real newlines, not `stmt; for x in y: …`.
-
-**Hold content in plain lists of strings, and walk them.** Every list of bullets
-is a flat `["…", "…"]`, and every table is a list of row lists. Do not reach for
-a dict, a tuple of mixed widths, or a nested comprehension to hold document
-content — those are where a `SyntaxError` or a
-`ValueError: too many values to unpack` comes from, and they buy nothing here.
-
-**Keep every underscore in API names.** `add_heading`, `add_paragraph`,
-`add_run`, `add_table`, `add_row`, `add_picture`, `add_page_break` — stripping
-them to `addheading` / `addparagraph` fails. Copy identifiers exactly as written
-below:
-
-```python
-from docx import Document
-from docx.shared import Inches, Pt, RGBColor   # one import line covers sizes, widths, colors
-
-doc = Document()
-
-doc.add_heading("Quarterly Report", level=0)
-doc.add_paragraph("Prepared by the finance team.")
-
-doc.add_heading("Summary", level=1)
-p = doc.add_paragraph("Revenue grew ")
-strong = p.add_run("18 percent")
-strong.bold = True
-p.add_run(" against a ")
-emphasis = p.add_run("flat")
-emphasis.italic = True
-p.add_run(" cost base.")
-
-doc.add_heading("Highlights", level=1)
-for point in [
-    "New retail partners in two regions",
-    "Churn down for the third quarter",
-    "Support backlog cleared",
-]:
-    doc.add_paragraph(point, style="List Bullet")
-
-doc.add_heading("Key Figures", level=1)
-figures = [
-    ["Metric", "Q3", "Q4"],              # first list is the header row
-    ["Revenue", "$1.2M", "$1.4M"],
-    ["Costs", "$0.9M", "$0.9M"],
-]
-table = doc.add_table(rows=1, cols=len(figures[0]))
-table.style = "Table Grid"
-for index, cells in enumerate(figures):
-    row = table.rows[0].cells if index == 0 else table.add_row().cells
-    for column, value in enumerate(cells):
-        row[column].text = value
-
-doc.save("report.docx")               # must match the declared output exactly
-print(f"{len(doc.paragraphs)} paragraphs, {len(doc.tables)} table(s)")
-```
-
-## Write a document, not markdown
-
-A `.docx` carries real styles, so the structure is the style — never the
-punctuation. Markdown written into text stays there verbatim and reads as a
-typo in the finished document:
-
-- **No markdown characters in any string.** `#`, `##`, `-`, `*`, `1.`, `**bold**`
-  and backticks all render literally. `add_heading("Security", level=2)` — never
-  `add_heading("- Security", level=2)` or `"## Security"`. A numbered list is
-  `style="List Number"`, which numbers itself; a typed `"1. "` prefix double-numbers.
-- **No typed rules or line breaks.** A row of dashes or underscores as a section
-  divider is just those characters on the page, and a leading `"\n"` is a blank
-  line inside the paragraph. Headings already separate sections.
-- **Every section title is a heading.** A first section called "Introduction" or
-  "Overview" goes through `add_heading(..., level=1)` like every other one; as a
-  plain `add_paragraph` it renders as body text and the document looks unstructured.
-- **No blank paragraphs for spacing.** `add_paragraph("")` leaves a visible gap —
-  the heading and body styles already carry their own space before and after.
-- **Bold is for a few words, not a sentence.** A fully bold paragraph reads as a
-  formatting mistake; bold the term, then continue in a normal run.
-
-## One paragraph, one string
-
-`add_paragraph` takes a single text string, optionally with `style=` — nothing
-else. Several sentences passed positionally raise
-`TypeError: Document.add_paragraph() takes from 1 to 3 positional arguments but 4
-were given`. Join them into one string, or open the paragraph with the first
-piece and add the rest as runs:
-
-```python
-p = doc.add_paragraph("As of 2026, Bitcoin is widely held. ")
-p.add_run("Adoption keeps growing.")
-```
-
-**The text you pass to `add_paragraph` is already the paragraph's first run.** A
-run added afterwards _appends_ — repeating any of those words writes them twice
-into the document (`"…finite supplyfinite supply"`). Each run carries the next
-words and only those, so give a mixed-format paragraph an empty start and add
-every piece as its own run:
-
-```python
-p = doc.add_paragraph()
-p.add_run("Digital scarcity ")
-tail = p.add_run("and a finite supply")
-tail.italic = True
-```
-
-## Bold and italic live on runs, never on paragraphs
-
-`paragraph.bold = True` raises no error and changes **nothing** in the file — a
-paragraph has no bold; the assignment lands on the Python object and is silently
-discarded on save. Formatting belongs to runs:
-
-```python
-p = doc.add_paragraph("normal, then ")
-strong = p.add_run("bold")
-strong.bold = True
-p.add_run(" and ")
-emphasis = p.add_run("italic")
-emphasis.italic = True
-```
-
-Two rules make that shape the only one to write:
-
-- **`add_run` takes the text and nothing else.** `p.add_run("x", bold=True)`
-  raises `TypeError: Paragraph.add_run() got an unexpected keyword argument
-'bold'` — create the run, then set the attribute.
-- **Never chain an attribute onto the `add_run(...)` call.** Name the run on one
-  line and format it on the next, as above. A run that needs no formatting is a
-  bare `p.add_run("plain text")` and the line ends there — a trailing `.` left
-  over from a half-written chain is `SyntaxError: invalid syntax`.
-- **Runs join with no gap between them.** The next run starts exactly where the
-  last one ended, so the separating space belongs inside one of the strings —
-  `"…without intermediaries. "` then `"It was invented"`, never
-  `"…intermediaries."` followed by `"It was invented"`.
-
-**`add_run` belongs to the paragraph, not to a run.** Keep the paragraph in a
-variable and call `p.add_run(...)` for every run in it — chaining a second run off
-the first raises `AttributeError: 'Run' object has no attribute 'add_run'`. A run
-owns `.text`, `.bold`, `.italic` and `.font`, and nothing else: it has no
-`add_run`, no `add_paragraph`, and no `.style`.
-
-A run is also not a string: `p.add_run(" ") * 2` raises
-`TypeError: unsupported operand type(s) for *: 'Run' and 'int'`. Put any repeated
-text inside the string itself — and reach for neither, since spacing is the
-style's job, not padding you type.
-
-Character detail goes through `run.font` — size, color:
-
-```python
-from docx.shared import Pt, RGBColor
-
-p = doc.add_paragraph()
-run = p.add_run("Key finding")
-run.font.size = Pt(14)
-run.font.color.rgb = RGBColor(0x1A, 0x73, 0xE8)   # RGB in all caps
-```
-
-`Pt`, `Inches`, and `RGBColor` all import from `docx.shared` — there is no
-`docx.util` and no `docx.dml.color`; those are python-pptx paths and fail here.
-
-## Styles must exist in the document
-
-`style="List Bullet"` names a style **inside the document**. A missing name
-raises `KeyError: "no style with name 'List Bullet'"` at `add_paragraph` time.
-
-A **new** `Document()` ships these styles — safe to use without checking:
-`Title`, `Heading 1` … `Heading 9`, `Normal`, `List Bullet` (+ ` 2`, ` 3`),
-`List Number` (+ ` 2`, ` 3`), `Intense Quote`, and the table style `Table Grid`.
-Do not invent other names for a new document. (An uploaded document carries
-only its own styles — when editing one, load `references/rework.md` for the
-guard.)
-
-## Headings and lists
-
-- `doc.add_heading(text, level=N)` — level `0` is the document title style,
-  `1`–`9` map to `Heading 1`–`Heading 9`. Any other level raises
-  `ValueError: level must be in range 0-9`.
-- Bullets: one `add_paragraph(point, style="List Bullet")` per point, over a flat
-  list of plain strings. Never pack several points into one paragraph with `\n` —
-  a `\n` is a soft line break inside the same list item, not a new bullet. A
-  bullet that needs a label and a detail is one string (`"Limited supply — 21
-million coins"`), never a dict entry or a tuple.
-- Numbered lists: `style="List Number"`. Indent a level with `List Bullet 2` /
-  `List Number 2`.
-
-## Tables
-
-Write the whole table as a list of row lists — header first — then let the code
-above derive everything from it. **Always `rows=1` and `cols=len(rows[0])`**:
-
-```python
-rows = [
-    ["Item", "Status"],                        # header
-    ["Search", "Shipped"],
-    ["Export", "In review"],
-]
-table = doc.add_table(rows=1, cols=len(rows[0]))
-table.style = "Table Grid"                     # borders; omit for invisible grid
-for index, cells in enumerate(rows):
-    row = table.rows[0].cells if index == 0 else table.add_row().cells
-    for column, value in enumerate(cells):
-        row[column].text = value
-```
-
-That shape exists because the two hand-written alternatives both fail:
-
-- **`rows=` is a count of blank rows created immediately, not a maximum.**
-  `add_table(rows=4, …)` followed by `add_row()` per entry leaves three empty
-  rows sitting between the header and the data, plainly visible in the finished
-  document. `rows=1` is the header; every other row comes from `add_row()`.
-- **Unpacking a row into fixed names breaks the moment a row is a different
-  width.** `for name, q3, q4 in data:` raises
-  `ValueError: too many values to unpack (expected 3, got 4)`, and hand-counting
-  `cols=` against the data is the same mistake one step earlier. Index the cells
-  instead, and take the column count from the header.
-
-Address cells as `table.cell(row, col)` or `table.rows[r].cells[c]` — they are
-the same cell. Rows only grow at the bottom: there is no insert-at.
-`table.rows[9]` on a 4-row table raises `IndexError`. Write text with
-`cell.text = "…"`; for formatting inside a cell go through `cell.paragraphs[0]`
-and its runs like any other paragraph.
-
-## Images and page breaks
-
-`doc.add_picture(name, width=…)` appends the image in its own paragraph. Pass
-only one of `width`/`height`; passing both distorts the picture.
-
-```python
-from docx.shared import Inches
-
-doc.add_picture("figure1.png", width=Inches(5.5))
-doc.add_page_break()
-```
-
-**Do not soft-fail images or imports.** Never wrap `add_picture` or an import in
-`try`/`except` that prints a warning and continues. A missing file must raise so
-you fix it and rerun — a document saved without the requested image is a failed
-turn, not a success.
-
-## Errors
-
-- `ModuleNotFoundError: No module named 'docx'` means `packages` was missing or
-  wrong — add `["python-docx==1.2.0"]` and rerun. Never try to install it, and
-  never "fix" it by importing `python_docx`; the import stays `docx`.
-- `TypeError: 'Table' object is not subscriptable` — a table was indexed
-  directly (`table[0]`). Cells are reached through `table.rows[r].cells[c]` or
-  `table.cell(r, c)`; a whole row of cells is `table.add_row().cells`.
-- `KeyError: "no style with name '…'"` — the style is not in this document. For
-  a new document use only the names listed under Styles.
-- `NameError: name 'RGBColor' is not defined` (or `Pt`, `Inches`) — the import
-  line is missing that name. Keep the sample's single
-  `from docx.shared import Inches, Pt, RGBColor` rather than importing one at a time.
-- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
-  collapsed — restore multi-line newlines from the sample and rerun. Underscores
-  in names (`add_paragraph`, not `addparagraph`) must stay. Do not switch to
-  `python -c` or change the package pin.
-- On an `AttributeError` from python-docx the API name is wrong; on a `TypeError`
-  about positional arguments the call passes the wrong number of them — usually
-  several strings where one is allowed. Fix either against this file's examples,
-  reading the line number in the traceback. Do not retry the same call, and do
-  not switch to a shell.
-- `attachment … not found in this chat` means `inputs` listed an id that is not
-  in this chat (often a copied placeholder like `att_doc`). For a new document,
-  omit `inputs` entirely and rerun. Only stage real ids from prior tool results.
-- Never print the document's bytes or base64 — stdout is capped and the file
-  travels through `outputs`. A build call prints exactly one line (e.g. `9
-paragraphs, 1 table(s)`).
-- Never pass an absolute path to `save()`.
-
-## Finish
-
-When `exitCode` is `0` and `attachments` lists the `.docx`, the document is
-done — the `exec` result carries
-`attachments: [{ attachmentId, fileName, byteLength }]` and the file is already
-attached to the chat for the user to open or save, exactly like a
-`generate_image` result. Stop tool use and reply with a single line: file name
-
-- the count line from stdout. Exactly one successful `exec` per request. If
-  the result has `missingOutputs` instead, the file was never written: check the
-  `save()` name matches the declared output and rerun once.

package/skills/word/references/paragraphs.md

@@ -1,125 +0,0 @@
-# Changing Some Paragraphs of a Document (bundled scripts)
-
-"Replace the first 10 facts", "change fact 3", "swap these bullets for those",
-"reword paragraph 7": two `exec` calls, both running a script bundled with this
-skill. **Write no Python.** There is no `command` in this job — a call with
-`command` is the wrong call. Pass `skill`, `script`, and `scriptArgs` exactly as
-shown, with `inputs` staging the document by its `attachmentId` (from the
-earlier `exec` result or the `[Attached file …]` line — copy it verbatim, never
-invent one).
-
-| Step                                    | The `exec` call                                                  |
-| --------------------------------------- | ---------------------------------------------------------------- |
-| 1. see the paragraphs and their indexes | `scripts/list_paragraphs.py`, `inputs` staged, no `outputs`      |
-| 2. replace exactly the chosen indexes   | `scripts/replace_paragraphs.py`, `inputs` staged, one `outputs` |
-
-## Step 0 — find the document's `attachmentId`
-
-The id is in the chat already, never invented: a document built earlier in
-this chat has it in the `attachments` of the `exec` result that produced it —
-`{"attachmentId":"922bd4e17517b90593be1c5ae4f12fbd","fileName":"cat_facts.docx"}`
-— and a document the user uploaded has it on the `[Attached file …]` line of
-their message. Copy that exact id into `inputs`. An `inputs` entry with a
-`path` and no `attachmentId` is an _image_ upload and is refused for a
-document:
-
-```json
-{ "inputs": [{ "path": "existing.docx" }] }
-```
-
-## Step 1 — list the paragraphs (no `outputs`)
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
-  "skill": "word",
-  "script": "scripts/list_paragraphs.py",
-  "scriptArgs": ["existing.docx"]
-}
-```
-
-Every key above is required — `inputs` with the document's real
-`attachmentId`, `skill`, `script`, `scriptArgs`. A call missing `skill` or
-`inputs` is refused.
-
-It prints one line per paragraph — `index`, style, text — then a count line.
-Pick the indexes to replace from that list:
-
-- Only body paragraphs (`Normal`, `List Bullet`, `List Number`) are facts,
-  points, or bullets. `Title`, `Heading N`, and an intro sentence are never
-  counted as one.
-- "The first 10 facts" = the first 10 body-paragraph indexes after the heading
-  or sentence that introduces them — not indexes 0–9.
-- Fewer facts in the document than asked for: replace the ones that exist and
-  say so in the reply.
-
-## Step 2 — replace exactly those paragraphs (one `outputs` entry)
-
-`scriptArgs` is: input name, output name, then `index, new text` pairs — one
-pair per replaced paragraph, as many pairs as facts requested. The output name
-keeps the input's stem plus `_revised`.
-
-Count the pairs before sending: "the first 10 facts" is 10 pairs — 20 strings
-after the two file names, 10 different sentences, the last index being
-start + 9.
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "attachmentId": "<real id>", "path": "existing.docx" }],
-  "outputs": ["existing_revised.docx"],
-  "skill": "word",
-  "script": "scripts/replace_paragraphs.py",
-  "scriptArgs": [
-    "existing.docx", "existing_revised.docx",
-    "3", "Dogs have about 1,700 taste buds.",
-    "4", "A dog's nose print is unique, like a fingerprint."
-  ]
-}
-```
-
-Wrong, for this job — a `command` instead of a `script`:
-
-```json
-{ "command": "from docx import Document\ndoc = Document(\"existing.docx\")\nfor i in range(1, 11): ..." }
-```
-
-Each new text is one complete plain sentence, no markdown, each different. The
-script keeps each paragraph's paragraph style, refuses a heading index,
-refuses text that already reads the same, and prints
-`K of N paragraphs replaced`.
-
-## Finish
-
-`exitCode 0` plus an attachment = done. Reply with one line: the file name and
-the printed count line. Do not call `exec` again for this request.
-
-## Errors
-
-The script stops with a message that names the fix; correct the arguments and
-rerun the **same script** — never switch to writing Python.
-
-- `usage: replace_paragraphs.py …` — the pairs are incomplete: after the two
-  file names, arguments alternate `index`, `text`.
-- `scriptArgs name "existing_revised.docx" but the working directory starts
-  empty` — the call has no `outputs`; add `"outputs": ["existing_revised.docx"]`
-  (the same name as in `scriptArgs`) and rerun the same script.
-- `script runs need the owning skill name in skill` — add `"skill": "word"`.
-- `index N is the heading '…'` — that paragraph is a heading, not a fact. Pick
-  body indexes from the Step 1 list.
-- `index N is outside the document's M paragraphs` — re-read the Step 1 list;
-  indexes run from 0 to M-1.
-- `index N already reads exactly that` — the new text equals the old one; write
-  a different sentence.
-- `output … must be a new name` — the output name equals the input's; use
-  `existing_revised.docx`.
-- `an id-less input stages an uploaded image` — the `inputs` entry has no
-  `attachmentId`; add the document's id from Step 0 and rerun the same script.
-- `usage: list_paragraphs.py <input.docx>` — `scriptArgs` was left out; pass
-  the staged path, `["existing.docx"]`.
-- `PackageNotFoundError` / `attachment … not found` / `does not exist in the
-  working directory` — `inputs` is missing or carries an invented id; stage the
-  document by its real `attachmentId`.

package/skills/word/references/read.md

@@ -1,141 +0,0 @@
-# Reading a Word Document to Answer in Chat
-
-When the user asks what an attached `.docx` _says_ — a summary, a question
-answered, specific content pulled out — the deliverable is your reply in the
-chat, not a file. This is a **read request**: exactly one `exec` call, staging
-the document in `inputs` and declaring **no `outputs`**, whose whole job is to
-print the document's text so you can read it in the result.
-
-## Staging the Document
-
-Stage the document **by its `attachmentId`**. The id comes from wherever the
-document entered the chat:
-
-- **Produced earlier in this chat** — the `attachmentId` is in that `exec` result.
-- **Uploaded by the user** — the `[Attached file …]` line on their message names
-  it, when the message carries one:
-
-  ```
-  [Attached file "report.docx" (application/vnd.openxmlformats-officedocument.wordprocessingml.document) — attachmentId: 4f9c2ab1]
-  ```
-
-Copy the id verbatim — never invent one, never stage a document id-less: an
-id-less input resolves to an uploaded _image_, so it can never reach a
-document. If no `attachmentId` for the document appears anywhere in the chat,
-say you cannot open that file and ask the user to attach it again — do not
-retry. An attachment from an earlier turn can be used when its attachment id
-is available in the conversation.
-
-## The exec call
-
-```json
-{
-  "language": "python",
-  "packages": ["python-docx==1.2.0"],
-  "inputs": [{ "attachmentId": "<id from the [Attached file …] line>", "path": "existing.docx" }],
-  "maxOutputChars": 24000,
-  "command": "..."
-}
-```
-
-- `packages` — `["python-docx==1.2.0"]` on every call. The PyPI package is
-  `python-docx` but the import is `docx`; never list `docx` as the package —
-  that resolves a different, abandoned library. This exact version ships with
-  the app and installs with no network.
-- `inputs` — the staged document lands in the working directory under the bare
-  `path` name; open `Document("existing.docx")` by that name only. The working
-  directory starts empty on every call.
-- No `outputs` — a read builds nothing.
-- `maxOutputChars` — stdout cap in characters (default 8192, max 65536). Set
-  it only on a read call, where the document text must fit in one result —
-  keep the sample's 24000. A build call prints one line and never needs it.
-- `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 Read Program
-
-The read program prints every paragraph under its style name — the style names
-are the document's structure — then every table:
-
-```python
-from docx import Document
-
-doc = Document("existing.docx")
-for p in doc.paragraphs:
-    text = p.text.replace("\n", " ").strip()
-    if text:
-        print(f"[{p.style.name}] {text}")
-for i, t in enumerate(doc.tables):
-    print(f"[Table {i + 1}]")
-    for row in t.rows:
-        print(" | ".join(c.text.replace("\n", " ") for c in row.cells))
-```
-
-The `replace` calls are load-bearing: a multi-paragraph cell and a soft line
-break both embed `"\n"` in `.text`, and an embedded newline would split one
-table row — or one paragraph — across two printed lines. Flattened, every line
-starts with its `[...]` marker and every table row is exactly one line.
-
-Tables print after the body text — python-docx does not expose their position
-between paragraphs. When that order matters to the answer, say the tables are
-listed separately. Note `p.style.name` in the sample: `paragraph.style` is a
-style object, not a string — go through `.name` to print or compare it.
-
-**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 text; the summarizing happens in your reply, after the result
-comes back.
-
-## Answering
-
-**A successful read ends tool use.** When the result prints the document, reply
-with the summary or the answer as chat text. **Scale the reply to the
-document**: a summary is much shorter than what it summarizes — a page or two
-of source earns three to five sentences, and only a long document earns
-sections. Restating the document near its full length is not a summary. Do
-**not**:
-
-- call `exec` again to "re-check", "read more", or read the same document a
-  second time;
-- build a summary `.docx` the user never asked for — an unrequested file is a
-  failed turn, not a bonus.
-
-If stdout ends with `… [truncated]`, the document is longer than the cap:
-answer from what came back and say the answer covers the document 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
-document from the text you actually read (load `references/create.md` for the
-build). The read still declares no `outputs`, delivers nothing, and does not
-count against the one successful build `exec` per document request — but it
-belongs before the build, never after it.
-
-## Errors
-
-- `PackageNotFoundError: Package not found at '…'` — the document was never
-  staged, or an id-less entry staged an image under a `.docx` path. Add
-  `inputs: [{ "attachmentId": "<id from the exec result or the [Attached file …]
-line>", "path": "existing.docx" }]` and open that exact path. If no id is
-  available, ask the user to attach the file again rather than guessing a name.
-- `attachment … not found in this chat` means `inputs` listed an id that is not
-  in this chat (often a copied placeholder like `att_doc`). Only stage real ids
-  from prior tool results or `[Attached file …]` lines; if none exists, ask the
-  user to re-attach.
-- `ModuleNotFoundError: No module named 'docx'` means `packages` was missing or
-  wrong — add `["python-docx==1.2.0"]` and rerun. Never try to install it, and
-  never "fix" it by importing `python_docx`; the import stays `docx`.
-- `SyntaxError: invalid syntax` on a one-line `for`/`if` means the source was
-  collapsed — restore multi-line newlines from the sample and rerun. Do not
-  switch to `python -c` or change the package pin.
-- A read result ending in `… [truncated]` means the document outgrew the cap:
-  answer from what came back and say the answer covers the document up to that
-  point. Do not rerun the read — it prints the same beginning again.
-
-## Finish
-
-When the read result prints the document, stop tool use and answer the user in
-the chat. Exactly one read `exec` per request; only a read call prints
-document text.