@qvac/skills 0.1.3 → 0.1.5

package/hash.js

@@ -1,2 +1,2 @@
 // Autogenerated by scripts/build.mjs from skills/. Do not edit.
-export const SKILLS_HASH = 'c6c3741623f9af9c'
+export const SKILLS_HASH = '8357531791b7cdb8'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/apple-notes/create-note.applescript

@@ -1,15 +1,18 @@
 -- Create a Notes note. argv: name, htmlBody, [folder]
--- Notes writes the `name` property as the body's first line, so creating with
--- both name and body renders the title twice. Create from body, then rename.
+-- A note's title is its first line. iCloud notes carry no separate `name` and
+-- refuse `set name` (-10006) after the note already exists, which reported a
+-- created note as failed. So the title goes into the body as its heading.
 on run argv
   set noteName to item 1 of argv
   set noteBody to item 2 of argv
+  set heading to "<h1>" & noteName & "</h1>"
+  if noteBody does not start with heading then set noteBody to heading & noteBody
   tell application "Notes"
     if (count of argv) > 2 then
       set newNote to make new note at folder (item 3 of argv) with properties {body:noteBody}
     else
       set newNote to make new note with properties {body:noteBody}
     end if
-    set name of newNote to noteName
+    return id of newNote
   end tell
 end run

package/skills/apple-notes/references/write.md

@@ -29,6 +29,15 @@ level so its double quotes need no escaping. Never embed a body inside
 `osascript -e '...'`: three nested quoting layers drop the closing `"`/`}` and
 produce `syntax error: Expected "}"` and no note.
 
+On success the command prints the new note's id (`x-coredata://…`) and nothing
+else. That id IS the confirmation: the note exists, so answer the user — never
+run the command again to check or "retry". Only a non-zero exit with an
+`execution error` means no note was created.
+
+The note's title is its first line, so the script makes sure the body starts
+with `<h1>name</h1>`, adding it when the body does not already begin with it.
+Write the title once as the leading `<h1>` and the script changes nothing.
+
 Plain note in the default folder:
 
 ```bash

package/skills/spotify/SKILL.md

@@ -22,37 +22,25 @@ metadata:
 
 # Spotify
 
-Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential is attached automatically to every `api.spotify.com` request — **never include an `auth` block**. Never invent track/album/artist URIs — search first and copy `uri` from the JSON response.
+Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential is attached automatically to every `api.spotify.com` request — **never include an `auth` block**.
 
-```json
-{
-  "url": "https://api.spotify.com/v1/search",
-  "method": "GET",
-  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
-}
-```
-
-## Hard rules
+## Playing a song takes two calls. Always two.
 
-- A bare song/artist/album/playlist name is enough — search immediately, take the top match, and tell the user what you picked. Do not ask "which one?" before searching.
-- Always search before playing by name. Play carries URIs only in the JSON `body` (`"uris": ["…"]`), never as query parameters.
-- A bare `PUT /me/player/play` with no body only resumes paused playback — it never plays a requested song. For an album/artist/playlist use `{ "context_uri": "<uri>" }` instead of `uris`.
-- Do not ask about tokens or setup up front. A **401** means Spotify isn't connected (tell the user to run `/connect spotify`). A **404** from `/me/player` means no active device (tell them to open Spotify).
+"Play X" is not answered until **both** have run:
 
-## Recipe: play a song by name
+1. `GET /v1/search` — find the track.
+2. `PUT /v1/me/player/play` — start it.
 
-1. Search:
+Search alone plays nothing. If you have searched and not yet called play, you are not finished: make the play call now.
 
 ```json
 {
   "url": "https://api.spotify.com/v1/search",
   "method": "GET",
-  "query": { "q": "Radiohead Creep", "type": "track", "limit": 5 }
+  "query": { "q": "Radiohead Creep", "type": "track", "limit": 3, "market": "from_token" }
 }
 ```
 
-2. Copy `tracks.items[0].uri` into the play body:
-
 ```json
 {
   "url": "https://api.spotify.com/v1/me/player/play",
@@ -61,6 +49,20 @@ Use `http_request` against `https://api.spotify.com/v1`. The Spotify credential
 }
 ```
 
+Take `tracks.items[0].uri` from the search response and paste it into `uris`. A 204 means it started.
+
+## Hard rules
+
+- **`q` carries every word the user named — the title and the artist.** "play Creep by Radiohead" searches `q=Radiohead Creep`, never `q=Creep`. Drop the artist and the top hit is a different band's song with the same title.
+- **Before playing, check the item you picked.** Compare its `artists[0].name` with the artist the user named. If they do not match, take the first result that does. A title match under the wrong artist is the wrong song, and the user hears it immediately.
+- **Never write a URI, a JSON block, or "I'll play it now" to the user in place of calling play.** Describing the call is not making it.
+- **Every URI you send is one you copied from a search response in this turn.** Never type a `spotify:track:` id from memory or from an earlier turn. A well-formed id that is not real stops what was playing and starts nothing.
+- **A track goes in `uris`. Only `uris`.** `context_uri` takes an album, artist or playlist URI — a track URI there plays nothing. URIs go in the JSON `body`, never in query parameters.
+- **One call per intent.** A 204 means the call landed; do not send it again. Repeating a queue or play call burns the turn and changes nothing.
+- **Name what actually played, read back from the item you used** — its `name` and `artists[0].name`. A 204 says the call was accepted, not which song it was, so never report a title you did not read out of the response.
+- A bare song/artist/album/playlist name is enough — search immediately, take the top match, and tell the user what you picked. Do not ask "which one?" before searching.
+- Do not ask about tokens or setup up front. A **401** means Spotify isn't connected (tell the user to run `/connect spotify`). A **404** from `/me/player` means no active device (tell them to open Spotify).
+
 ## Other operations
 
 All paths are under `https://api.spotify.com/v1`.
@@ -69,17 +71,20 @@ All paths are under `https://api.spotify.com/v1`.
 | --------------- | ----------------------------------------------------------------------- |
 | What's playing? | `GET /me/player/currently-playing`                                      |
 | Pause           | `PUT /me/player/pause`                                                  |
-| Resume          | `PUT /me/player/play` (no body)                                         |
+| Resume          | `PUT /me/player/play` (no body — resumes only, never starts a new song) |
 | Next track      | `POST /me/player/next`                                                  |
 | Add to queue    | `POST /me/player/queue` with `query`: `{ "uri": "spotify:track:<id>" }` |
+| Play an album/artist/playlist | `PUT /me/player/play` with `body`: `{ "context_uri": "<uri>" }` |
 | My playlists    | `GET /me/playlists`                                                     |
 | Top tracks      | `GET /me/top/tracks` with `query`: `{ "time_range": "medium_term" }`    |
 | Recently played | `GET /me/player/recently-played`                                        |
 | List devices    | `GET /me/player/devices`                                                |
 
+Queueing is the same two calls as playing: search for the track, then `POST /me/player/queue` with the `uri` you just read. Queueing does not start playback.
+
 ## Notes
 
-- Keep responses small — they truncate past 8KB, and raw JSON burns tokens on small models. Keep `limit` at 5. On playlist/track endpoints request only what you need with `fields` (e.g. `query`: `{ "fields": "items(track(name,artists(name),uri))" }`). Read just the top item unless the user asked for a list.
+- Keep responses small — they truncate past 8KB, and raw JSON burns tokens on small models. Keep `limit` at 3 and **always pass `market`**: a search without it spends most of the budget on `available_markets`, and the results behind the first one are cut off before you can read them. `/search` has no `fields` param, so `market` is the only lever there. On playlist/track endpoints request only what you need with `fields` (e.g. `query`: `{ "fields": "items(track(name,artists(name),uri))" }`). Read just the top item unless the user asked for a list.
 - Present results as a short numbered list — track, artist, album, duration — and devices as `1. Name (active/idle)`. Never dump raw JSON to the user.
 - Playback commands return **204 No Content** on success (empty body). A **204** from currently-playing means nothing is playing.
 - **403** with `PREMIUM_REQUIRED` → user needs Spotify Premium. Other **403**s are usually app-scope/Development Mode limits — report and stop.

package/skills/weather/SKILL.md

@@ -1,43 +1,59 @@
 ---
 name: weather
 description: Get current weather and short forecasts for cities via wttr.in.
-tools: [http_request]
+tools: [weather_lookup]
 platform: [darwin, linux, win32, ios, android]
-allow_list: [https://wttr.in/]
-version: 3
-# Tuned on Qwen3.5-2B with an offline eval (33 prompts x mention/prose routes), QVAC-24701.
-# v2: few-shot table. 2 repeats: overall 51/132 -> 77/130, "Nassau, Bahamas" 1/4 -> 4/4, city+country 2/24 -> 18/24,
-#   ambiguous city 0/20 -> 6/20; 4B control 41/66 -> 59/66. Rules-first layouts lost on suffix slips (?3, ?1T).
+version: 4
+# Tuned on Qwen3.5-2B with an offline eval (35 prompts, mention route), QVAC-24701.
+# v2: few-shot table. 2 repeats: overall 51/132 -> 77/130, "Nassau, Bahamas" 1/4 -> 4/4, city+country 2/24 -> 18/24.
 # v3: + country row. 3 repeats: v2 110/198 -> v3 121/198 (city+country 25 -> 31/36, forecast 17 -> 23/30).
-#   Aliases, a second ambiguity row, and dropping ?T were tried and did not help (73, 74, 54 of ~130).
+#   Aliases, a second ambiguity row and dropping ?T were tried and did not help (73, 74, 54 of ~130).
+# v4: weather_lookup instead of http_request, after v3 answered a 200 for a place that does not exist.
+#   5 repeats, all variants in one sweep so they share a baseline: v3 97/171 -> v4 120/169. city+country
+#   87 -> 93%, unambiguous 57 -> 91%, unknown 57 -> 84%, forecast 68 -> 88%, casual 65 -> 80%, the ticket
+#   prompt 80 -> 100%. Context is a wash (2335 -> 2378) though the body is 387 bytes smaller: the tool owns
+#   the URL, so three rules about spelling one went away.
+#   Not fixed. "Ask which Nassau" is 3/25 on v3 and 0/25 here, and asking when no place is named is 1/10 for
+#   both: a one-argument call is easy, so the model calls rather than asks. Rules that tell the model not to
+#   act have never cleared ~17% on a 2B in four versions, and a variant that made the tool refuse an
+#   ambiguous name measured 13% against 17%, so it was dropped rather than shipped.
 ---
 
 # Weather
 
-One `http_request` to wttr.in, then answer from the body. Always call it exactly like this, with `"method": "GET"`:
+One `weather_lookup` call, then answer from the result. Always call it exactly like this:
 
 ```json
-{ "url": "https://wttr.in/Nassau,+Bahamas?format=3", "method": "GET" }
+{ "location": "Nassau, Bahamas" }
 ```
 
-Match the user's request to a row for the URL:
+Match the user's request to a row for the call:
 
 | User asks | Call |
 | --- | --- |
-| "weather in Nassau, Bahamas" | `https://wttr.in/Nassau,+Bahamas?format=3` |
-| "weather in London" / "London today" | `https://wttr.in/London?format=3` |
-| "Berlin tomorrow" / "this weekend" | `https://wttr.in/Berlin?2T` |
-| "Rome for the next 3 days" | `https://wttr.in/Rome?T` |
-| "how hot is it in Georgia, the country" | `https://wttr.in/Tbilisi,+Georgia?format=3` (a country → its capital) |
-| "weather in Nassau" (Nassau exists in the Bahamas and in New York) | no call — ask: "Which Nassau do you mean, the Bahamas or New York?" |
-| "what's the weather?" (no place) | no call — ask which city |
+| "what's the weather?" — no place named | **no call.** Ask which city |
+| "weather in Nassau, Bahamas" | `{ "location": "Nassau, Bahamas" }` |
+| "weather in London" / "London today" | `{ "location": "London" }` |
+| "Berlin tomorrow" / "this weekend" | `{ "location": "Berlin" }` |
+| "Rome for the next 3 days" | `{ "location": "Rome" }` |
+| "how hot is it in Georgia, the country" | `{ "location": "Tbilisi, Georgia" }` (a country → its capital) |
+| "weather in Nassau" | `{ "location": "Nassau" }` — the result names both, ask which |
+
+The result is the place on the first line, then the weather now, then one line per day:
+
+```
+Nassau, New Providence, Bahamas
+Now: 29°C / 84°F, Patchy rain nearby, feels like 33°C, humidity 71%, wind 21 km/h
+2026-09-16 (today): 29-29°C / 84-85°F, Partly Cloudy
+2026-09-17 (tomorrow): 28-29°C / 83-85°F, Moderate or heavy rain shower
+```
 
 ## Rules
 
-1. **The location is exactly what the user wrote, spaces as `+`.** Keep a country or state they gave (`Nassau,+Bahamas`, not `Nassau`). Never add one they did not give. A country → its capital (`Tbilisi`).
-2. **Ambiguous city names — Nassau, Springfield, Portland, Cambridge, Georgia, San Jose, Birmingham — with no country or state → do not call, ask which one.**
-3. **The URL ends in `?format=3`, `?2T` or `?T`. Nothing else.** `?format=3` is the default for now/today/current. Write it in full: `London?3`, `London?format=3&format=3` and a bare `London` are all wrong.
-4. **Status not 200, or body `location not found` → say the place could not be found and ask for a more specific name. Do not retry other cities. Never state a temperature you did not receive.**
-5. wttr.in stops at 3 days: for "next week" say so and offer `?T`.
+1. **There is no default place.** If the user named none, do not call: ask which city. Never use a place from this file.
+2. **The location is exactly what the user wrote.** Keep a country or state they gave (`Nassau, Bahamas`, not `Nassau`). Never add one they did not give. A country → its capital (`Tbilisi`).
+3. **Name the place from the first line of the result, not the words the user used.** If they ask for Rome and the first line says `Lome, Maritime, Togo`, say it is Lome in Togo.
+4. **If the result is not a weather report, say what it says, in those words.** `No such place: "Xyzzyville, Atlantis"` → tell the user that place does not exist and ask for a real one. Do not look it up again under another name, and never state a temperature you did not receive.
+5. Forecasts stop at 3 days: for "next week" say so and give the 3 days you have.
 
-A `200` body like `Nassau, Bahamas: 🌦️ +30°C` is the answer: give that temperature and condition in one plain sentence.
+Answer in one plain sentence with the temperature and the condition.

package/skills/word/SKILL.md

@@ -19,43 +19,35 @@ metadata:
 
 # Word
 
-Build, edit, or read `.docx` documents by running python-docx through the
-`exec` tool with `language: "python"`. Declare a produced document in
-`outputs` and it comes back as a chat attachment the user can save. To answer
-_from_ a document instead of building one, run a read call — no `outputs` —
-and reply in the chat.
-
-## Load the Recipe File First
-
-This file contains no Python. The working recipes live in four reference
-files — load the one for the job with the `skill` tool BEFORE writing any
-Python, then copy its recipe and change the content:
+Build, change, or read `.docx` documents. This file holds no Python and no
+recipe: it only says which reference file to load. Load exactly one with the
+`skill` tool, then do what that file says.
+
+## Which File to Load
+
+Pick the row by **what the user wants done**, then make that exact `skill`
+call. "Edit", "update", "modify", "change", "replace", "rewrite" and "fix" all
+mean the same thing here — the verb never picks the row, the change does.
+
+| The user wants                                                                                                                                   | The `skill` call                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
+| A new document — "write a report", "make a doc with 30 fun facts about cats", "draft a letter"                                                   | `{"name": "word", "file": "references/create.md"}`     |
+| Some paragraphs of an existing document changed — "replace the first 10 facts with dog facts", "change fact 3", "reword paragraph 7", "swap these bullets for those" | `{"name": "word", "file": "references/paragraphs.md"}` |
+| Anything else done to an existing document — add a section, remove or rewrite a whole section, make the text bigger, put an image in it          | `{"name": "word", "file": "references/rework.md"}`     |
+| An answer in the chat from an attached document — "summarize this", "what does it say about X"                                                 | `{"name": "word", "file": "references/read.md"}`       |
+
+- A document that already exists in this chat is never rebuilt with
+  `create.md` — that throws away everything the user has. Its `attachmentId`
+  is in the `exec` result that produced it or on the `[Attached file …]` line.
+- A summary delivered as a file is `read.md` first, then `create.md`.
+- `paragraphs.md` runs two scripts bundled with this skill and contains no
+  Python. `rework.md` and `create.md` carry the python-docx recipes to copy.
 
 Each load is a real `skill` tool call — printing the call as JSON or text in
-your reply loads nothing.
-
-- **Creating a new document** (no existing `.docx` involved; may embed
-  images): call the `skill` tool with `name: "word"` and
-  `file: "references/create.md"`.
-- **Changing some of the facts, points, bullets, items, or paragraphs** of an
-  existing `.docx` — "replace the first 10 facts", "change fact 3", "swap the
-  bullets for these", "reword paragraph 7": call the `skill` tool with
-  `name: "word"` and `file: "references/replace.md"`. This is the file even
-  when the user says edit, replace, change, update, or rewrite; it runs two
-  bundled scripts and no Python is written.
-- **Any other edit of an existing document** (extend it, trim it, rework a
-  whole section, resize the text, embed an image into it): call the `skill`
-  tool with `name: "word"` and `file: "references/edit.md"`.
-- **Reading a document to answer in chat** (a summary, a question answered,
-  content pulled out — no file delivered): call the `skill` tool with
-  `name: "word"` and `file: "references/read.md"`.
-- **A summary delivered as a file** is a read followed by a build: load both
-  `references/read.md` and `references/create.md`.
-
-Never write the Python from memory. The recipes carry rules (exact version
-pins, attachment staging, run-level formatting, in-place replacement, the only
-working removal idiom) that fail in non-obvious ways when improvised; loading
-the file is one cheap read-only call.
+your reply loads nothing. Never write the Python from memory: the recipes carry
+rules (exact version pins, attachment staging, the only working removal idiom)
+that fail in non-obvious ways when improvised, and loading the file is one
+cheap read-only call.
 
 ## When to Use
 
@@ -106,13 +98,15 @@ no-`outputs` read that precedes a build delivers nothing and is not one of
 them, but it belongs before the build, never after it. Reply with a single
 line: file name + the count line from stdout. If the result has
 `missingOutputs` instead, the file was never written: read stderr first — an
-`AssertionError` there means a guard stopped the save on purpose (see the edit
-recipe); only when stderr is clean check the `save()` name matches the
+`AssertionError` there means a guard stopped the save on purpose (see the
+rework recipe); 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.** An error in your code is
 never a fault in python-docx or in the runtime; fix the Python against the
-loaded reference file's recipes and Errors and call `exec` again. If two
+loaded reference file's recipes and Errors and call `exec` again. A bundled
+script that stops with a message is fixed by correcting its arguments and
+rerunning the same script — never by writing Python in its place. If two
 consecutive calls fail with the same error, re-read the traceback
 line-by-line before a third — retrying the identical `command`, or a version
 with only cosmetic changes, is a loop, not a fix. Do not switch package pins
@@ -130,12 +124,12 @@ and a file you write but do not declare in `outputs` is discarded. The `exec`
 result is the only account of what happened — there is no filesystem to check
 and no shell to check it with.
 
-**Never overwrite a staged input.** Edits always save a new output name,
-derived from the document edited — `report.docx` becomes `report_revised.docx`,
+**Never overwrite a staged input.** Changes always save a new output name,
+derived from the document changed — `report.docx` becomes `report_revised.docx`,
 never a fresh name taken from the new content.
 
-**An edit changes the document in place.** `add_paragraph` and `add_heading`
+**A change happens inside the document.** `add_paragraph` and `add_heading`
 append at the end and nowhere else, so replacing content that is already there
 means rewriting those paragraphs, not adding new ones. Delivering the original
-with the new version appended is a failed turn — the edit recipe carries the
-guards that catch it.
+with the new version appended, or a fresh document holding only the new
+content, is a failed turn.

package/skills/word/references/create.md

@@ -5,11 +5,12 @@ 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.** "Add a
-section", "reword this", "extend the doc" — any request that starts from an
-existing `.docx` is an EDIT: load `references/edit.md` and stage the document
-by its `attachmentId`. Building a fresh document for an edit request throws
-away everything the user already has.
+**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
 
@@ -81,9 +82,40 @@ 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. It is a complete, working document — a title, headings,
+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.
@@ -255,7 +287,7 @@ 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/edit.md` for the
+only its own styles — when editing one, load `references/rework.md` for the
 guard.)
 
 ## Headings and lists

package/skills/word/references/{replace.md → paragraphs.md}

@@ -1,11 +1,31 @@
-# Replacing Paragraphs by Position (bundled scripts)
+# Changing Some Paragraphs of a Document (bundled scripts)
 
-"Replace the first 10 facts", "reword point 3", "swap these bullets for those",
-"change paragraph 7": two `exec` calls, both running a script bundled with this
-skill. **Write no Python.** Never put source in `command` for this job — 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).
+"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`)
 
@@ -20,6 +40,10 @@ document by its `attachmentId` (from the earlier `exec` result or the
 }
 ```
 
+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:
 
@@ -27,7 +51,7 @@ Pick the indexes to replace from that list:
   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
-  that introduces them — not indexes 0–9.
+  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.
 
@@ -57,6 +81,12 @@ start + 9.
 }
 ```
 
+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
@@ -74,6 +104,10 @@ 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;
@@ -82,5 +116,10 @@ rerun the **same script** — never switch to writing Python.
   a different sentence.
 - `output … must be a new name` — the output name equals the input's; use
   `existing_revised.docx`.
-- `PackageNotFoundError` / `attachment … not found` — `inputs` is missing or
-  carries an invented id; stage the document by its real `attachmentId`.
+- `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/{edit.md → rework.md}

@@ -1,16 +1,79 @@
-# Editing an Existing Word Document (python-docx)
-
-**Stop here if the request changes some of the facts, points, bullets, items,
-or paragraphs** — "replace the first 10 facts", "change fact 3", "swap the
-bullets", "reword paragraph 7". That job is `references/replace.md`: call the
-`skill` tool with `name: "word"` and `file: "references/replace.md"` now, and
-do not use anything in this file for it. No Python is written for that job.
+# Reworking an Existing Word Document (python-docx)
 
 Change, replace, extend, trim, or rework a `.docx` that is already in this
 chat by running Python through the `exec` tool: stage it as an input, modify
 paragraphs and tables, and save a **new** output such as
 `existing_revised.docx`. Never overwrite the staged input.
 
+## Replacing Some Facts, Points, Bullets or Paragraphs: Two Script Calls
+
+"Replace the first 10 facts", "change fact 3", "swap these bullets for those",
+"reword paragraph 7" — any request that changes some of the paragraphs and
+keeps the rest — is two `exec` calls that run scripts bundled with this skill.
+**Write no Python for it.** Nothing else in this file applies to that job: no
+`command`, no `Document(...)`, no fingerprint, no loop. `references/paragraphs.md`
+is this same recipe with its error table.
+
+The document's `attachmentId` is already in the chat — in the `attachments` of
+the `exec` result that produced it, or on the user's `[Attached file …]` line.
+Copy it into `inputs`; an entry with only a `path` stages an image, not a
+document.
+
+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"]
+}
+```
+
+It prints one line per paragraph — `index`, style, text — then a count line.
+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.
+
+Step 2 — replace exactly those paragraphs (one `outputs` entry). `scriptArgs`
+is the input name, the output name, then one `index, new text` pair per
+replaced paragraph — "the first 10 facts" is 10 pairs, each a different
+complete sentence:
+
+```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): ..." }
+```
+
+`exitCode 0` plus an attachment = done: reply with the file name and the
+printed `K of N paragraphs replaced`, and do not call `exec` again. A script
+error names the fix (a heading index, an index out of range, unchanged text,
+missing pairs, a missing `outputs` for the revised name); correct the
+arguments and rerun the **same script**.
+
+Everything below is for the other edits: extending a document, trimming it,
+rewriting a whole section, resizing its text, embedding an image.
+
 ## Staging the Document
 
 Stage the document as an input **by its `attachmentId`** and open it with
@@ -163,9 +226,9 @@ formatting-loss rule below.
 The `add_heading`/`add_paragraph` pair above appends an **Appendix** because
 that is what the sample edit asks for. Copy that shape only when the user
 genuinely wants new content at the end. Substituting content that is already
-in the document — "change the first five points", "rewrite section 2" — is a
-different job with its own recipe and its own guards: see Replacing Content In
-Place.
+in the document is a different job with its own guards: some of the points —
+"change the first five points" — is the two script calls at the top of this
+file; a whole section — "rewrite section 2" — is Rewriting Whole Sections.
 
 When an edit adds substantial new content — new sections, formatted runs,
 bulleted lists, whole tables — the writing rules apply unchanged: load
@@ -193,11 +256,11 @@ bullet = "List Bullet" if "List Bullet" in names else None
 doc.add_paragraph("point one", style=bullet)   # style=None → Normal
 ```
 
-## Replacing Content In Place
+## Rewriting Whole Sections
 
-This recipe is for whole *sections* (a heading plus its body). Changing some
-of the facts, points, bullets, or paragraphs is `references/replace.md` —
-never hand-write a loop for that.
+This recipe is for whole _sections_ (a heading plus its body). Changing some
+of the facts, points, bullets, or paragraphs is the two script calls at the
+top of this file — never hand-write a loop for that.
 
 `add_paragraph`, `add_heading`, and `add_picture` **always append at the end of
 the document.** None of them takes a position. "Change the first five points",