@qvac/skills 0.1.11 → 0.1.12

package/skills/presentations/references/create.md

@@ -1,399 +0,0 @@
-# Building a New Deck (python-pptx)
-
-Create a new `.pptx` from scratch by running Python through the `exec` tool.
-A new deck needs **no** `inputs` — do not invent attachment ids. **Exactly
-one** `exec` call per user request when that call succeeds.
-
-**A deck that already exists in this chat is never rebuilt here.** "Add a
-slide", "change a title", "revise the deck" — any request that starts from an
-existing `.pptx` is an EDIT: load `references/edit.md` and stage the deck by
-its `attachmentId`. Building a fresh deck for an edit request throws away
-every slide the user already has.
-
-## The exec call
-
-```json
-{
-  "language": "python",
-  "packages": ["python-pptx==1.0.2"],
-  "outputs": ["deck.pptx"],
-  "command": "..."
-}
-```
-
-- `language` (required) — always `"python"`.
-- `packages` (required) — `["python-pptx==1.0.2"]` on every call. 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` — `["deck.pptx"]`. `save("deck.pptx")` must match the declared
-  output name exactly. A file you write but do not declare here is discarded.
-- `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`. `command` is the program: 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`.
-- No `inputs` key at all for a new deck.
-- `maxOutputChars` (stdout cap, default 8192, max 65536) is never needed on a
-  build call — it prints one line.
-
-## Embedding images
-
-Two kinds of image input, told apart by where the image came from:
-
-**Tool-produced files** (`generate_image` output, a prior deck return): stage
-them with the exact `attachmentId` from the tool result — never placeholders
-like `att_deck`, `att_image`, or any id you made up.
-
-**Images the user uploaded** ("use this image", a photo attached to their
-message): there is no id to copy — an uploaded image shows none. Stage them
-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 — never more id-less entries than that message has images. When it has
-none, a single id-less entry resolves to the chat's most recent image instead.
-
-Seeing the image in your context is not the same as staging it: the deck is
-built by Python, which reads the working directory and never your context, so
-an uploaded image reaches a slide only through an id-less `inputs` entry. Do
-not call `generate_image` to recreate what the user attached, and do not tell
-them the image cannot be used — the id-less entry is how it is used.
-
-**Files the user uploaded that are not images** (a `.pptx` to revise, any
-document): these *do* show an id, on the `[Attached file "…" — attachmentId:
-…]` line of the message that carried them. Copy it verbatim into
-`attachmentId`, exactly as for a tool-produced file. The id-less form never
-reaches them. (Revising an existing deck is its own flow — load
-`references/edit.md`.)
-
-```json
-{
-  "language": "python",
-  "packages": ["python-pptx==1.0.2"],
-  "inputs": [
-    { "attachmentId": "<id from generate_image or prior deck>", "path": "slide1.png" },
-    { "path": "uploaded.png" }
-  ],
-  "outputs": ["deck.pptx"],
-  "command": "..."
-}
-```
-
-Staged files land in the working directory under the bare `path` names —
-reference `slide.shapes.add_picture("slide1.png", …)` by that name only.
-Paths must be unique bare filenames. The working directory is fresh on every
-call, so a file written by an earlier call is gone unless it is staged again
-as a chat attachment; an attachment from an earlier turn can be used when its
-attachment id is available in the conversation — from a tool result or an
-`[Attached file …]` line — otherwise ask the user to attach the file again.
-
-`attachment … not found in this chat` means you invented an id or the file is
-not attached. If the file you meant is an image the user uploaded, drop the
-`attachmentId` key; if it came from a tool result or an `[Attached file …]`
-line, re-copy the exact id; for a new deck drop `inputs` entirely; otherwise
-ask the user to re-attach.
-
-If an image was staged in `inputs`, embed it in **that** single build with
-`slide.shapes.add_picture` — never deliver a deck 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 deck with the staged attachment as above.
-
-Say it in the reply, every time. A deck that quietly ships without the image the
-user linked is a failed turn: they asked for that image, and silence reads as
-though it is on the slide. Name the URL you could not fetch and what you need
-instead.
-
-## Writing the Deck
-
-Start from this. It is a complete, working deck — a title slide and a bullet slide,
-16:9, every paragraph sized, saved under the declared output name. Copy it and change
-the content; do not assemble a deck 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: …`.
-
-**Every length is a typed length — `Inches(...)`, `Pt(...)` or `Emu(...)`, never
-a bare number.** This holds for every position and size anywhere in the deck:
-both pairs of `add_textbox(left, top, width, height)`, the `left`/`top` and the
-`width`/`height` of `add_picture(...)`, `prs.slide_width` and `prs.slide_height`,
-table column widths and row heights, and every margin or offset.
-
-python-pptx reads a bare number as **EMU**, and there are 914400 EMU to the inch.
-So `add_textbox(0, 0, 12, 0)` is not "12 wide" — it is a box 0.000013in wide and
-0in tall, pinned to the top-left corner. Nothing raises: `exitCode` is `0`, there
-is no traceback and no warning, and the deck is delivered looking broken. Write
-`add_textbox(Inches(0.75), Inches(0.5), Inches(11.83), Inches(1.2))` instead.
-
-Recognise the symptom, because it is the only signal you get: **text crammed
-into the top-left corner, or a box that has no size**, means a raw number reached
-an argument that required a typed length. Do not tune the numbers — wrap them.
-
-```python
-from pptx.util import Inches
-
-box = slide.shapes.add_textbox(Inches(1), Inches(1), Inches(8), Inches(1.5))
-# NOT add_textbox(1, 1, 8, 2) — that is 8 EMU wide, an invisible box
-```
-
-**Keep every underscore in API names.** `text_frame`, `add_slide`, `slide_layouts`,
-`slide_width`, `word_wrap`, `add_paragraph`, `add_picture`, `add_textbox`, `PP_ALIGN`
-— stripping them to `textframe` / `addslide` / `addpicture` fails. Copy identifiers
-exactly as written below:
-
-```python
-from pptx import Presentation
-from pptx.util import Inches, Pt
-from pptx.enum.text import PP_ALIGN
-
-prs = Presentation()
-prs.slide_width = Inches(13.333)      # 16:9 is not the default
-prs.slide_height = Inches(7.5)
-
-# Title slide — layout 0 owns a title and a subtitle
-slide = prs.slides.add_slide(prs.slide_layouts[0])
-slide.shapes.title.text = "Why the Sky Is Blue"
-slide.shapes.title.text_frame.paragraphs[0].font.size = Pt(44)
-subtitle = slide.placeholders[1].text_frame
-subtitle.text = "Rayleigh scattering, in four points"
-subtitle.paragraphs[0].font.size = Pt(24)
-
-# Content slide — layout 1 owns a title and a body
-slide = prs.slides.add_slide(prs.slide_layouts[1])
-slide.shapes.title.text = "What Happens"
-slide.shapes.title.text_frame.paragraphs[0].font.size = Pt(36)
-tf = slide.placeholders[1].text_frame
-tf.word_wrap = True
-for index, point in enumerate([
-    "Sunlight arrives carrying every visible wavelength",
-    "Air molecules scatter short wavelengths hardest",
-    "Blue scatters far more than red",
-    "So the daytime sky reads blue in every direction",
-]):
-    p = tf.paragraphs[0] if index == 0 else tf.add_paragraph()
-    p.text = point
-    p.font.size = Pt(20)
-
-prs.save("deck.pptx")               # must match the declared output exactly
-print(f"{len(prs.slides)} slides")
-```
-
-Layouts `0` and `1` own the placeholders that example writes to.
-
-**Choosing a layout has one rule, and it depends on where the deck came from:**
-
-- **Adding to a deck the user gave you** — reuse the layout its own slides
-  already use: read a comparable existing slide and pass its `.slide_layout` to
-  `add_slide`. That is the only way the new slide inherits the deck's theme.
-  That flow is `references/edit.md` — load it.
-- **Building a new deck** — index the bundled template, which commonly uses `0`
-  (title), `1` (title + content), `5` (title only), and `6` (blank). Those
-  indices belong to *that* template and mean nothing on an uploaded deck.
-
-A layout only owns the placeholders it declares, and python-pptx returns `None` for
-the rest — on the blank layout `shapes.title` is `None`, so `shapes.title.text = …`
-raises `AttributeError: 'NoneType' object has no attribute 'text'`, and
-`placeholders[1]` raises `KeyError`. So each slide is one of exactly two kinds, never
-a mix:
-
-| slide kind | layout | how you write text |
-| --- | --- | --- |
-| title / title + body | the deck's own layout, or `0`, `1`, `5` in a new deck | `shapes.title`, `placeholders[1]` |
-| hand-designed | `6` (blank) | `shapes.add_textbox(...)` for **every** box, title included |
-
-On layout `6` there is no title to reach for — the title is a text box you add.
-
-The blank layout is **not** a co-equal way to write a content slide. It is for a
-slide you are genuinely designing by hand — a full-bleed image, a diagram, a
-custom split — and it inherits no font, size, colour or position from the
-template. Using it plus `add_textbox` to hold ordinary title-and-bullets content
-on a deck the user uploaded produces a slide that visibly does not belong: wrong
-typeface, wrong sizes, wrong margins, and no bullets. Placeholders exist so you
-do not have to reproduce a theme you cannot see.
-
-Bullets — set `tf.text` for the first bullet, then `add_paragraph()` for the rest.
-Using `add_paragraph()` for the first one leaves a blank leading line.
-
-A new text frame holds exactly **one** paragraph, and `tf.paragraphs` is a tuple, so
-`tf.paragraphs[1]` raises `IndexError: tuple index out of range` until you have added
-it. Grow the frame with `p = tf.add_paragraph()`, which returns the new paragraph, and
-write through that. A paragraph owns `.text`, `.font` and `.alignment` and nothing
-else — it has no `.paragraphs` and no `.add_paragraph()`, so never reassign your frame
-variable to a paragraph.
-
-The template's body placeholder inherits 28pt, so size every paragraph you add —
-including sub-levels — or it renders far larger than intended:
-
-```python
-from pptx.util import Pt
-
-slide = prs.slides.add_slide(prs.slide_layouts[1])
-slide.shapes.title.text = "Agenda"
-tf = slide.placeholders[1].text_frame
-tf.word_wrap = True
-for index, point in enumerate(["first point", "second point"]):
-    p = tf.paragraphs[0] if index == 0 else tf.add_paragraph()
-    p.text = point
-    p.font.size = Pt(20)   # an unsized paragraph inherits 28pt
-```
-
-Every deck returned through `outputs` is fitted before it reaches the user, so text
-that would overflow its box is shrunk to fit automatically. That is a safety net, not
-a licence to overfill: shrinking below about 16pt is unreadable from a room. Budget
-each slide at no more than five bullets of about 100 characters. A sixth bullet is a
-second slide titled `... (cont.)`, never a smaller font — and prose belongs in the
-chat reply, not on a slide.
-
-Free text — the only way to add text outside a placeholder is
-`shapes.add_textbox(left, top, width, height)` — all four are required, and all
-four are typed lengths, never bare numbers — then write into its `.text_frame`.
-There is no `add_text_frame`, no `add_text`, and no `add_paragraph` on `shapes`:
-
-```python
-slide = prs.slides.add_slide(prs.slide_layouts[6])
-box = slide.shapes.add_textbox(Inches(0.75), Inches(0.5), Inches(11.83), Inches(1.2))
-tf = box.text_frame
-tf.word_wrap = True
-tf.text = "Why the sky is blue"
-tf.paragraphs[0].font.size = Pt(40)  # from pptx.util import Pt
-```
-
-Text always lives on the `.text_frame`, never on the shape: `box.paragraphs`,
-`box.add_paragraph()`, `box.word_wrap`, and `box.font` all raise AttributeError. Go
-through `tf = box.text_frame` first — `tf.text`, `tf.paragraphs[0]`,
-`tf.add_paragraph()`, `tf.word_wrap`. `shape.text` is the one shortcut that reads
-through to the frame; there is no matching `shape.font`.
-
-Formatting lives one level lower still — on a paragraph or a run, never on a shape or
-a frame. A title is sized through its paragraph:
-
-```python
-title = slide.shapes.title
-title.text = "Why the Sky is Blue"
-title.text_frame.paragraphs[0].font.size = Pt(44)      # not title.font.size
-title.text_frame.paragraphs[0].font.bold = True
-title.text_frame.paragraphs[0].alignment = PP_ALIGN.CENTER
-```
-
-Slides are added with `prs.slides.add_slide(layout)` — `prs.add_slide` does not
-exist. Alignment comes from an enum import, not an attribute path:
-
-```python
-from pptx.enum.text import PP_ALIGN
-
-tf.paragraphs[0].alignment = PP_ALIGN.CENTER
-```
-
-Bullet characters are not needed — a placeholder body renders bullets itself. Give
-each bullet its own paragraph; never pack several `\n`-joined bullets into one.
-Never type the marker into the text: `"1. "`, `"2. "`, `"- "` and `"• "` prefixes
-render *next to* the bullet the placeholder already draws, in the wrong font.
-Bullets belong in a body placeholder for exactly this reason — a bare
-`add_textbox` draws none, and typing them by hand to compensate is the wrong fix.
-Put the content in a placeholder instead.
-
-Font color — the type is `RGBColor` with **RGB in all caps**. Not `RgbColor`,
-`rgbColor`, or `rgb_color`:
-
-```python
-from pptx.dml.color import RGBColor
-
-title.text_frame.paragraphs[0].font.color.rgb = RGBColor(0x1A, 0x73, 0xE8)
-```
-
-Backgrounds and fills — `background` hangs off the slide itself, never off
-`slide.shapes` or a shape, and the fill is set in two steps: `solid()` first,
-then the color:
-
-```python
-from pptx.dml.color import RGBColor
-
-fill = slide.background.fill          # slide.shapes has no background
-fill.solid()
-fill.fore_color.rgb = RGBColor(0x0B, 0x1F, 0x3A)
-
-box.fill.solid()                      # a shape is tinted through its own .fill
-box.fill.fore_color.rgb = RGBColor(0xF2, 0xF2, 0xF2)
-```
-
-A paragraph has no `.fill` at all — coloring text goes through the font,
-`paragraph.font.color.rgb = RGBColor(...)`, as above. `fill` exists on a shape
-and on `slide.background`, nowhere else you will need.
-
-Images — go through the shapes collection: `slide.shapes.add_picture(...)`. A
-`Slide` has no picture or text-box methods of its own — `slide.add_picture`,
-`slide.addpicture`, `slide.add_textbox`, and `slide.addtextbox` all raise
-`AttributeError: 'Slide' object has no attribute '…'`. Fix: put `.shapes` between
-`slide` and the method. Pass only one of `width`/`height`; passing both distorts
-the picture. Generate image-slide visuals at 1024×512 so they fill the content box;
-a 512×512 square letterboxes with wide empty bands either side.
-
-**Do not soft-fail images or imports.** Never wrap `add_picture` or color imports in
-`try`/`except` that prints a warning and continues. A missing file or
-`cannot import name 'RgbColor'` must raise so you fix it and rerun — a deck that
-saves without the requested image is a failed turn, not a success.
-
-```python
-slide = prs.slides.add_slide(prs.slide_layouts[6])
-# correct: slide.shapes.add_picture — never slide.add_picture / slide.addpicture
-slide.shapes.add_picture("slide1.png", Inches(0.75), Inches(1.0), width=Inches(11.83))
-prs.save("deck.pptx")
-print(f"{len(prs.slides)} slides")
-```
-
-## Errors
-
-- Never print the deck's bytes or base64 — stdout is capped (8 KB by default)
-  and the file travels through `outputs`. A build call prints only the slide
-  count line (e.g. `7 slides`). No "Presentation created successfully", no
-  try/except warnings on stdout.
-- `cannot import name 'RgbColor' from 'pptx.dml.color'` means the name is wrong —
-  use `RGBColor` (all-caps RGB). Do not catch the ImportError and save anyway.
-- Never pass an absolute path to `save()`.
-- `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 (`text_frame`, not `textframe`) must stay. Do not switch to `python -c`
-  or change the package pin.
-- `outputs declare a .pptx but command does not build one` means the source never
-  calls `Presentation(...).save(...)` — paste the skill sample (edited for content),
-  not a diagnostic `os.listdir` or shell wrapper.
-- `ModuleNotFoundError: No module named 'pptx'` means `packages` was missing or
-  wrong — add `["python-pptx==1.0.2"]` and rerun. Never try to install it.
-- `attachment … not found in this chat` means `inputs` listed an id that is not in
-  this chat (often a copied placeholder like `att_deck`). For a new deck, omit
-  `inputs` entirely and rerun. Only stage real ids from prior tool results.
-- Text crammed into the top-left corner, or a shape with no visible size, means a
-  bare number reached an argument that required a typed length — python-pptx reads
-  it as EMU (914400 to the inch), so `add_textbox(0, 0, 12, 0)` is an invisible box
-  in the corner. Nothing raises and `exitCode` is `0`, so this only ever shows up in
-  the delivered deck. Wrap every position and size in `Inches(...)` / `Pt(...)` /
-  `Emu(...)` and rerun — do not tune the raw numbers.
-- On an `AttributeError` from python-pptx 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.
-- `AttributeError: 'Slide' object has no attribute 'add_picture'` (or `addpicture`,
-  `add_textbox`, `addtextbox`) means the call skipped `.shapes` — use
-  `slide.shapes.add_picture(...)` / `slide.shapes.add_textbox(...)`, never
-  `slide.add_*`.
-- `AttributeError: 'SlideShapes' object has no attribute 'background'` means the
-  background was reached through the shapes collection — it lives on the slide:
-  `slide.background.fill.solid()` then `fill.fore_color.rgb = RGBColor(...)`.
-- `AttributeError: '_Paragraph' object has no attribute 'fill'` means a fill was
-  asked of text — paragraphs have none. Color text with
-  `paragraph.font.color.rgb = RGBColor(...)`; `.fill` belongs to a shape or to
-  `slide.background`.
-
-## Finish
-
-When `exitCode` is `0` and `attachments` lists the `.pptx`, stop tool use and
-answer with one line: file name + the slide count from stdout. Exactly one
-successful build `exec` per request — re-running the same build is spam, not
-quality.