better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-pdf.md

@@ -0,0 +1,142 @@
+---
+title: "Pdf — PDF files: create, read, merge, fill, OCR, edit text"
+sidebar_label: "Pdf"
+description: "PDF files: create, read, merge, fill, OCR, edit text"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Pdf
+
+PDF files: create, read, merge, fill, OCR, edit text.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity\pdf` |
+| Version | `1.1.0` |
+| Author | Nous Research |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `pdf`, `documents`, `forms`, `ocr`, `text-extraction`, `reportlab`, `pypdf`, `pdfplumber`, `pymupdf`, `marker` |
+| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`powerpoint`](/docs/user-guide/skills/bundled/productivity/productivity-powerpoint) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# PDF Skill
+
+Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks):
+
+- **Scanned/image-only PDFs and OCR** (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): `references/ocr-extraction.md`
+- **Editing text inside an existing PDF via natural-language prompts** (nano-pdf CLI): `references/nano-pdf-editing.md`
+
+## When to Use
+
+- Generate a report, invoice, or multi-page document as PDF.
+- Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first.
+- Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF.
+- Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs.
+- Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments.
+- Fill or flatten AcroForm forms; encrypt or decrypt with passwords.
+- NOT for scanned/image-only PDFs (use `references/ocr-extraction.md`) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).
+
+## Prerequisites
+
+- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`:
+  `python -m pip install pypdf reportlab pdfplumber`
+- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists.
+- Each helper script checks imports lazily and prints an install hint if a dependency is missing.
+
+## How to Run
+
+All helpers live in `scripts/` and are argparse CLIs — run them with the `terminal` tool; every one supports `--help`. They read/write JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.
+
+```bash
+python scripts/pdf_create.py spec.json -o out.pdf         # build PDF from JSON spec
+python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec
+python scripts/pdf_form_layout.py formspec.json           # lint form layout BEFORE building
+python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
+python scripts/pdf_read.py doc.pdf --text                 # per-page text (JSON)
+python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # tables to JSON + CSV files
+python scripts/pdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted/scanned flags
+python scripts/pdf_read.py form.pdf --fields              # form fields: name, type, value
+python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
+python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
+python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
+python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
+python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
+python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
+python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \
+    --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
+python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
+python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
+python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
+python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
+python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/
+```
+
+## Quick Reference
+
+| Task | Tool | Command / API |
+|---|---|---|
+| Create doc (headings, tables, images) | reportlab platypus | `pdf_create.py spec.json -o out.pdf` |
+| Build fillable form | reportlab acroForm | `pdf_make_form.py formspec.json -o form.pdf` |
+| Lint form layout / overlay image | pure python + PIL | `pdf_form_layout.py formspec.json [--render-overlay o.png]` |
+| Per-page text | pdfplumber | `pdf_read.py f.pdf --text` |
+| Tables → JSON/CSV | pdfplumber | `pdf_read.py f.pdf --tables` |
+| Metadata / sizes / encrypted / scanned | pypdf + pdfplumber | `pdf_read.py f.pdf --meta` |
+| Merge (+ outline) | pypdf | `pdf_merge.py a.pdf b.pdf -o m.pdf` |
+| Split / extract / rotate | pypdf | `pdf_split.py f.pdf --pages 2-5 --rotate 90` |
+| List / fill / flatten form | pypdf | `pdf_read.py --fields`, `pdf_fill_form.py` |
+| Encrypt / decrypt (AES-256) | pypdf | `pdf_secure.py --encrypt/--decrypt` |
+| Watermark / stamp PDF page | pypdf | `pdf_watermark.py f.pdf --stamp w.pdf` |
+| Stamp text/image at coordinates | reportlab + pypdf | `pdf_stamp.py f.pdf --text "Sign here" --x 400 --y 60` |
+| Pages → PNG (review / OCR hand-off) | pypdfium2 or pdftoppm | `pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/` |
+| Set/clear metadata, attachments | pypdf | `pdf_meta.py --set-meta / --attach / --extract-attachments` |
+| Compress content streams | pypdf | `pdf_split.py f.pdf --pages 1-N --compress` |
+
+## Procedure
+
+1. **Inspect first.** Run `pdf_read.py file.pdf --meta`. Check `encrypted` (if true, decrypt first with `pdf_secure.py --decrypt`) and `likely_scanned_pages`. If pages are image-only, export them with `pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/` and hand the PNGs to the `references/ocr-extraction.md` skill — do not report empty text as "no content".
+2. **Create.** Write a JSON spec with `write_file` (elements: `heading`, `paragraph`, `table`, `image`, `pagebreak`; optional `title`/`author` metadata; page numbers are added automatically), then run `pdf_create.py`. Verify visually with `vision_analyze` on a rendered page image if layout matters.
+3. **Extract.** `--text` gives a JSON list of per-page strings; `--tables` gives row arrays per page and can also emit CSV files. Read results with `read_file`; never eyeball a binary PDF directly.
+4. **Manipulate.** `pdf_merge.py` concatenates and can add one bookmark per source file; `pdf_split.py` handles page ranges (1-based, e.g. `1-3,5,9-`), rotation in 90° steps, and `--compress`. Watermark by preparing a single-page stamp PDF (e.g. via `pdf_create.py`) and overlaying it with `pdf_watermark.py`; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use `pdf_stamp.py` with text or an image at explicit coordinates.
+5. **Build forms.** Write one form-spec JSON (fields with `label_box`/`entry_box` in PDF points — see `references/forms.md`), lint it with `pdf_form_layout.py` and fix every reported problem, optionally review the `--render-overlay` PNG with `vision_analyze`, then build with `pdf_make_form.py` and confirm with `pdf_read.py --fields`.
+6. **Fill forms.** List fields (`--fields`) to learn exact names and types, write a UTF-8 JSON of `{"FieldName": "value"}` with `write_file` (checkboxes accept `true`/`false`; radio/choice values must match the field's export options), then `pdf_fill_form.py`. Re-read with `--fields` to confirm values landed.
+7. **Metadata & attachments.** `pdf_meta.py --set-meta` writes Title/Author/Subject/Keywords (DocInfo); `--clear-meta` drops them; `--attach`/`--list-attachments`/`--extract-attachments` round-trip embedded files.
+8. **Secure.** Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, `--decrypt` writes an unencrypted copy.
+9. **Verify** (see below) before reporting success.
+
+## Pitfalls
+
+- **Scanned PDFs**: empty `extract_text()` plus page images means there is no text layer. Route to `references/ocr-extraction.md`; do not fabricate text.
+- **Flattening limits**: `pdf_fill_form.py --flatten` uses pypdf's flatten support, which converts widget appearances into page content. It is reliable for plain text fields and checkboxes but can drop or misrender exotic widgets (rich text, custom appearance streams, some radio groups). Verify the flattened output visually with `vision_analyze`; for bulletproof flattening use an external renderer (e.g. Ghostscript or `pdftoppm`+reassembly) as a fallback.
+- **NeedAppearances**: after filling, viewers only render values if appearance streams exist. The fill script sets the AcroForm `NeedAppearances` flag so conforming viewers regenerate them; some minimal viewers ignore it — flatten if display fidelity matters.
+- **Non-Latin form values**: values are stored correctly (UTF-16), but the field's default font may lack glyphs, so a viewer can show blanks even though the data round-trips. Verify with `--fields`, not just visually.
+- **Compression expectations**: `--compress` only deflates content streams. Typical savings are 0–20%; it does nothing for PDFs dominated by images or already-compressed streams. It is not a substitute for image downsampling (Ghostscript territory).
+- **Permission flags don't enforce**: owner-password permission bits (no-print, no-copy) are polite requests that viewers may honor; any library (including pypdf) can read and strip them. Only the user password actually gates content via encryption. Never present permission flags as security.
+- **Table extraction is heuristic**: pdfplumber detects tables from ruling lines/word alignment; borderless or merged-cell tables may need `table_settings` tuning or manual cleanup.
+- **Page indexing**: helper CLIs take 1-based pages; pypdf APIs are 0-based. The scripts convert — don't double-convert.
+- **Rotated stamp text extraction**: pdfplumber's line grouping scrambles rotated glyphs (a 45° "DRAFT" extracts as stray letters); verify rotated stamps with `pypdf`'s `extract_text()` or a rendered image instead.
+- **Radio groups**: reportlab needs ≥2 `radio()` widgets per group, fills need the slashed export value (`"/red"`), and flatten fidelity is worst for radios — see `references/forms.md`.
+- **Metadata scope**: `pdf_meta.py` writes the classic DocInfo dictionary only; embedded XMP metadata (if any) is left untouched and may show different values in some viewers.
+- **PDF/A is out of scope**: pypdf/reportlab cannot produce or validate conformant PDF/A. If archival conformance is required, run Ghostscript via the `terminal` tool (e.g. `gs -dPDFA=2 -dPDFACompatibilityPolicy=1 -sColorConversionStrategy=UseDeviceIndependentColor -sDEVICE=pdfwrite -o out.pdf in.pdf` with a suitable ICC profile) and validate with veraPDF — both are external installs, and the result still needs validation, not assumption.
+- Rotation must be a multiple of 90; encrypted inputs must be decrypted before any other operation.
+
+## Verification
+
+- After create/merge/split: `pdf_read.py out.pdf --meta` — confirm `page_count`, and per-page `rotation` when you rotated.
+- After extraction: check the JSON is non-empty and spot-check a known string or cell.
+- Form design loop: `pdf_form_layout.py spec.json` must exit 0; then `--render-overlay boxes.png --pdf form.pdf` and review the PNG with `vision_analyze` (red = entry boxes with field names, blue = label boxes) asking about overlaps, misalignment, and labels detached from their fields. Iterate spec → lint → overlay until clean.
+- After building a form: `pdf_read.py form.pdf --fields` lists every spec field with the right type and options.
+- After form fill: `pdf_read.py filled.pdf --fields` and compare values (exact match, including non-ASCII).
+- After stamping: re-extract text (pypdf for rotated stamps) or render the page with `pdf_page_image.py` and inspect with `vision_analyze`.
+- After metadata/attachment edits: `pdf_read.py --meta` / `pdf_meta.py --list-attachments`, and re-extract an attachment to byte-compare.
+- After encrypt: `--meta` shows `"encrypted": true` and opening without a password fails; after decrypt, text extraction matches the original.
+- For anything visual (watermarks, flattened forms), render and inspect with `vision_analyze`.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md

@@ -0,0 +1,237 @@
+---
+title: "Powerpoint — Create, read, edit .pptx decks with python-pptx"
+sidebar_label: "Powerpoint"
+description: "Create, read, edit .pptx decks with python-pptx"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Powerpoint
+
+Create, read, edit .pptx decks with python-pptx.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity\powerpoint` |
+| Version | `1.1.0` |
+| Author | Nous Research |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `pptx`, `powerpoint`, `presentations`, `slides`, `office`, `python-pptx` |
+| Related skills | [`docx`](/docs/user-guide/skills/bundled/productivity/productivity-docx), [`xlsx`](/docs/user-guide/skills/bundled/productivity/productivity-xlsx), [`pdf`](/docs/user-guide/skills/bundled/productivity/productivity-pdf) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Powerpoint Skill
+
+Create, inspect, and edit PowerPoint (.pptx) presentations using the
+python-pptx library. Five helper scripts cover deck creation from a JSON
+spec, structured read-back, in-place edits, template-driven brand decks,
+and slide rendering — all offline, no PowerPoint installation required.
+
+## When to Use
+
+- The user asks to build a slide deck, report presentation, or pitch deck.
+- You need to extract text, notes, tables, chart data, or images from a
+  .pptx someone shared.
+- You need to update an existing deck: replace text, refresh or patch
+  chart data, swap a logo, duplicate/remove/reorder slides, set
+  backgrounds, footers, hyperlinks, or speaker notes.
+- You must produce an on-brand deck from a company .pptx template.
+- Do NOT use this for .ppt (legacy binary) files — convert them first with
+  `soffice --convert-to pptx old.ppt` if LibreOffice is available.
+
+## Prerequisites
+
+- Python 3.10+ with `python-pptx` installed
+  (`pip install python-pptx`).
+- Optional: LibreOffice (`soffice`) plus poppler (`pdftoppm` or
+  `pdftocairo`) for rendering slides to PNGs and for PDF export.
+  `pptx_render.py` detects both with `shutil.which` and degrades
+  gracefully (reports `{"rendered": false, "missing": [...]}`, exit 0)
+  when absent — all create/read/edit operations work without them.
+- Check availability via `terminal`:
+  `python -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`.
+
+## How to Run
+
+All scripts live in `scripts/`, take `--help`, print JSON to stdout, and
+exit non-zero on failure. Run them with `terminal`:
+
+```bash
+python scripts/pptx_create.py deck.json out.pptx
+python scripts/pptx_read.py deck.pptx --outline      # full JSON outline
+python scripts/pptx_read.py deck.pptx --notes        # speaker notes
+python scripts/pptx_read.py deck.pptx --images ./img # export pictures
+python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp"
+python scripts/pptx_edit.py deck.pptx --chart-data update.json
+python scripts/pptx_edit.py deck.pptx --duplicate-slide 2
+python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0
+python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json
+python scripts/pptx_render.py deck.pptx --outdir ./render  # slide PNGs
+```
+
+Author JSON specs with `write_file`; inspect script output and generated
+JSON with `read_file`.
+
+## Quick Reference
+
+| Task | Command |
+|---|---|
+| New deck from spec | `pptx_create.py spec.json out.pptx` |
+| 16:9 vs 4:3 | `"slide_size": "16:9"` or `"4:3"` in the spec |
+| Outline as JSON | `pptx_read.py deck.pptx --outline` |
+| Export images | `pptx_read.py deck.pptx --images DIR` |
+| Replace text | `pptx_edit.py deck.pptx --replace-text OLD NEW` |
+| Replace chart data | `pptx_edit.py deck.pptx --chart-data spec.json` |
+| Patch one series | same flag, spec with `"ops"` (see below) |
+| Swap picture | `pptx_edit.py deck.pptx --swap-image N NAME new.png` |
+| Duplicate slide | `pptx_edit.py deck.pptx --duplicate-slide N` |
+| Remove slide | `pptx_edit.py deck.pptx --remove-slide N` |
+| Reorder slide | `pptx_edit.py deck.pptx --move-slide FROM TO` |
+| Slide background | `pptx_edit.py deck.pptx --set-background N RRGGBB` |
+| Hyperlink runs | `pptx_edit.py deck.pptx --hyperlink N TEXT URL` |
+| Slide number on | `pptx_edit.py deck.pptx --enable-slide-number N` |
+| Footer text | `pptx_edit.py deck.pptx --set-footer N TEXT` |
+| Set notes | `pptx_edit.py deck.pptx --set-notes N TEXT` |
+| Append notes | `pptx_edit.py deck.pptx --append-notes N TEXT` |
+| Fill template | `pptx_from_template.py tpl.pptx out.pptx --values v.json` |
+| Render slide PNGs | `pptx_render.py deck.pptx --outdir DIR` |
+
+## Procedure
+
+### 1. Create a deck
+
+Write a JSON spec (see `pptx_create.py --help` for the full format), then
+run `pptx_create.py`. Per slide you can set: `layout` (title,
+title_content, section, two_content, title_only, blank), `title`,
+`subtitle`, `bullets` (strings, or dicts with `level` 0-4, `size` pt,
+`bold`, `italic`, `font`, `color` hex, `link` URL for a hyperlink),
+`background` (solid hex), `footer` (text; enables the layout's footer
+placeholder), `slide_number` (true; enables the layout's slide-number
+placeholder), `images` (path + left/top/width/height in inches), `tables`
+(`rows` as list-of-lists), `shapes` (rectangle, rounded_rectangle, oval,
+diamond, right_arrow, chevron, with `fill` hex + optional `text`),
+`charts` (bar, bar_h, line, pie with `categories` + `series`), and
+`notes` (speaker notes).
+
+### 2. Read a deck
+
+`pptx_read.py deck.pptx --outline` returns slide size, layout inventory,
+and per slide: layout name, all shape texts, table cells, image inventory
+(filename/ext/bytes), chart categories/series/values, and speaker notes.
+Use `--images DIR` to dump embedded pictures to files, then
+`vision_analyze` on any exported image if you need to see its content.
+
+### 3. Edit a deck
+
+`pptx_edit.py` combines operations in one pass; use `--output` to keep the
+original. Text replacement scans slide shapes, table cells, and notes.
+Image swap retargets the picture's relationship id so position and size
+are preserved. Slide removal drops the relationship and the `<p:sldId>`
+entry; reorder moves the `<p:sldId>` element within `<p:sldIdLst>`
+(python-pptx has no public API for either — the script does the XML-level
+work). `--duplicate-slide N` appends an independent deep copy of slide N:
+shape XML plus image/media/hyperlink relationships are cloned and rIds
+remapped, so editing the copy never touches the original. Chart slides
+are refused (see Pitfalls). `--set-notes`/`--append-notes` edit speaker
+notes; `--set-background`, `--hyperlink`, `--enable-slide-number`, and
+`--set-footer` handle deck polish.
+
+Chart updates take a JSON spec via `--chart-data`. Full replace:
+`{"slide": 0, "chart": 0, "categories": [...], "series": {...}}`. For
+surgical edits, pass `"ops"` instead — a list of
+`{"op": "update_series", "name": ..., "values": [...]}`,
+`add_series`, `remove_series`, `rename_category` (`from`/`to` or
+`index`), and `set_title`. python-pptx can only swap a chart's entire
+dataset (`replace_data`), so ops are implemented as read-existing →
+modify → replace; the per-part UX is a wrapper, and any chart data not
+expressible as categories + numeric series will be normalized by the
+round-trip.
+
+### 4. Build from a template
+
+`pptx_from_template.py` opens a brand .pptx, replaces every
+`{{token}}` from a values JSON across slides/tables/notes, and can append
+new slides that use the template's own layouts (by layout name or index)
+so they inherit the master's fonts and colors. Tip: to start from a
+template with zero slides, delete existing ones afterward with
+`pptx_edit.py --remove-slide`.
+
+### 5. Visual verification
+
+`pptx_render.py deck.pptx --outdir ./render` converts the deck to PDF
+with `soffice --headless` and splits it into one PNG per slide with
+`pdftoppm` (or `pdftocairo`). Output JSON lists the PNG paths — review
+each with `vision_analyze`. When either tool is missing the script exits
+0 with `{"rendered": false, "missing": [...]}` and guidance; fall back to
+the JSON outline from `pptx_read.py`, which verifies content and
+structure, just not visuals.
+
+## Converting to PDF
+
+If LibreOffice is installed, export the finished deck to PDF directly:
+
+```bash
+soffice --headless --convert-to pdf --outdir ./out deck.pptx
+```
+
+The output lands at `./out/deck.pdf`. Fonts not installed on the host are
+substituted, so render-verify (Procedure step 5) before shipping the PDF.
+There is no offline pure-Python .pptx→PDF path; if `soffice` is absent,
+say so rather than approximating.
+
+## Pitfalls
+
+- **Run splitting**: PowerPoint fragments paragraph text into runs at
+  spell-check and edit boundaries. `--replace-text` first merges adjacent
+  runs whose formatting is identical, so matches split across such runs
+  are replaced with formatting fully preserved. Only when a match spans
+  *genuinely differently-formatted* runs is the paragraph rewritten with
+  the first run's formatting — verify those slides after replacement.
+- **Chart slides cannot be duplicated**: each chart relationship embeds a
+  separate XLSX workbook part; cloning that graph reliably is not
+  supported, so `--duplicate-slide` refuses chart slides cleanly instead
+  of corrupting the deck. Rebuild the chart on a new slide instead.
+  External-hyperlink and image/media rels are carried over; layout and
+  notes rels are recreated fresh.
+- **Chart ops are a wrapper**: python-pptx replaces the whole dataset;
+  `"ops"` round-trips existing plot data through `replace_data`, and
+  changing chart *type* is not possible.
+- **Reordering is XML-level**: python-pptx has no supported reorder API.
+  `--move-slide` manipulates `<p:sldIdLst>` directly; safe for ordinary
+  decks but re-read the deck afterward to confirm.
+- **Copying slides between decks is unsupported** — duplication works
+  only within one deck, where layouts and masters are shared.
+- Footer/slide-number enablement copies the placeholder from the slide's
+  layout; on layouts without those placeholders, `--set-footer` fails
+  with a clear message (add a textbox instead).
+- Hyperlinks apply to whole runs; `--hyperlink` links every run
+  containing the given text on that slide.
+- The default python-pptx template is 4:3; the create script sets 16:9
+  unless the spec says otherwise. Custom templates keep their own size.
+- Layout indexes vary by template. For brand templates, list layout names
+  first: `pptx_read.py template.pptx --outline` (`layouts_available`).
+- `slide.shapes.title` is None on blank layouts — the create script
+  handles this, but remember it when writing ad-hoc python-pptx code.
+- Always pass `encoding="utf-8"` when writing spec files; tokens like
+  `{{city}}` may be filled with non-ASCII values.
+
+## Verification
+
+1. After any create/edit, run `pptx_read.py OUT.pptx --outline` and check
+   slide count, texts, tables, notes, and chart values match intent.
+2. `--images DIR` then file-size check confirms pictures embedded.
+3. Render every slide with `pptx_render.py deck.pptx --outdir ./render`
+   and review each PNG with `vision_analyze` — this catches overlapping
+   shapes, truncated text, and color problems the outline cannot. If the
+   render tools are missing, the script says so; rely on the outline.
+4. The bundled test suite is the full contract:
+   `python -m pytest tests/ -q` (requires python-pptx + pytest).

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-product-price-monitor.md

@@ -0,0 +1,97 @@
+---
+title: "Product Price Monitor — Watch product, flight, or listing prices; alert on target"
+sidebar_label: "Product Price Monitor"
+description: "Watch product, flight, or listing prices; alert on target"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Product Price Monitor
+
+Watch product, flight, or listing prices; alert on target.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity\product-price-monitor` |
+| Version | `0.1.0` |
+| Author | Ben Barclay (benbarclay), Hermes Agent |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Prices`, `Availability`, `Shopping`, `Travel`, `Alerts` |
+| Related skills | [`maps`](/docs/user-guide/skills/bundled/productivity/productivity-maps) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Product Price Monitor
+
+Monitor a concrete purchasable item and alert on a normalized all-in price or availability condition. Handle variants, taxes, fees, currencies, stock, cancellation terms, and duplicate alerts explicitly. Setup runs once in the foreground; the recurring check runs as a `cronjob` tick (the `price-watch` automation blueprint scaffolds this).
+
+## When to Use
+
+- "Alert me when this laptop drops below $1,000."
+- "Watch these flights for a fare under $500."
+- "Tell me when this hotel has a refundable room."
+- "Track ticket/listing availability."
+- A cron tick fires for an existing price watch (steps 4-6).
+
+Don't use for: one-off "what does this cost right now" lookups (use `web_search`/`web_extract` directly).
+
+## Procedure — Setup (foreground, once)
+
+### 1. Define the exact item
+
+Record source URL/provider, product/listing ID where available, variant, quantity, location, dates, travelers/guests, membership/login assumptions, condition, seller, and acceptable substitutes. Done when two variants cannot be confused.
+
+### 2. Define the alert condition
+
+Specify currency, all-in vs pre-tax price, maximum price, availability/stock rule, shipping, refundability, cabin/room/ticket class, cooldown, and notification destination. Done when synthetic examples have deterministic alert decisions.
+
+### 3. Establish a live baseline, then schedule
+
+Fetch a bounded live result with `web_extract` or `browser_navigate` and record retrieval time, source price, fees/taxes, availability, and terms. Do not schedule until one foreground fetch works. Write the watch contract (item, condition, baseline observation) to a state file under `~/.hermes/price-watches/<watch-slug>.json`, then create the job:
+
+```
+cronjob(action="create",
+        schedule="every 6h",
+        prompt="Load the product-price-monitor skill and run the tick for the watch contract at ~/.hermes/price-watches/<watch-slug>.json.",
+        deliver=<user's destination>)
+```
+
+Pick a cadence that respects rate limits and site terms. Done when the baseline matches the exact item contract and the job exists.
+
+## Procedure — Tick (each scheduled run)
+
+### 4. Fetch and normalize
+
+Re-fetch the source. Convert currency only with a timestamped rate and retain the source currency. Separate base price, mandatory fees, shipping/taxes, total, and availability. Exclude volatile page metadata. A failed fetch means unknown state: report or skip, but never overwrite the last good observation with an error page. Done when the observation is comparable to the baseline or explicitly marked failed.
+
+### 5. Compare and suppress duplicates
+
+Alert on threshold entry, qualifying availability, material lower price, or recovery as requested. Store the last good observation and last alert fingerprint in the state file. Replaying the same offer must send no second alert; respect the cooldown. Done when the alert decision is deterministic against stored state.
+
+### 6. Deliver or stay silent
+
+When a condition is met, the alert includes: exact item/variant, observed all-in price and source currency, availability/terms, threshold, retrieval timestamp, source link, and important uncertainty. Never claim inventory is reserved. When nothing qualifies, stay silent — no "still watching" noise unless a periodic all-clear was requested. Done when the state file reflects this run.
+
+## Pitfalls
+
+- Comparing a base fare with an all-in threshold.
+- Alerting on the wrong size, seller, cabin, dates, or room terms.
+- Overwriting a last-known-good value with an error page.
+- Polling aggressively enough to trigger blocking or violate site terms.
+- Scheduling before a single foreground fetch has succeeded.
+
+## Verification
+
+- [ ] The watch contract pins the item so two variants cannot be confused.
+- [ ] One foreground fetch succeeded before any job was created.
+- [ ] Alert decisions replay deterministically from the state file; duplicates suppressed.
+- [ ] Failed fetches never replaced last-known-good state.
+- [ ] Alerts carry all-in price, source currency, timestamp, and source link.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/skills/bundled/productivity/productivity-session-librarian.md

@@ -0,0 +1,122 @@
+---
+title: "Session Librarian — Organize sessions by prompt: find, rename, archive, prune"
+sidebar_label: "Session Librarian"
+description: "Organize sessions by prompt: find, rename, archive, prune"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Session Librarian
+
+Organize sessions by prompt: find, rename, archive, prune.
+
+## Skill metadata
+
+| | |
+|---|---|
+| Source | Bundled (installed by default) |
+| Path | `skills/productivity/session-librarian` |
+| Version | `1.0.0` |
+| Author | Hermes Agent + Teknium |
+| License | MIT |
+| Platforms | linux, macos, windows |
+| Tags | `Sessions`, `Organization`, `Cleanup`, `Library`, `Productivity` |
+| Related skills | [`weekly-review-planning`](/docs/user-guide/skills/bundled/productivity/productivity-weekly-review-planning) |
+
+## Reference: full SKILL.md
+
+:::info
+The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
+:::
+
+# Session Librarian
+
+Manage the user's session library conversationally: find past sessions about a
+topic, summarize what they decided, rename them meaningfully, split work into
+parallel sessions, and propose stale ones for archive or deletion — all from a
+plain-language request like *"find my sessions about Q3 pricing, keep the
+useful ones, and clean up the duplicates."*
+
+Inspired by Perplexity Computer's prompt-driven session management (Aug 2026):
+the agent starts, organizes, and cleans up the user's own session library, and
+always shows the plan before touching anything.
+
+## When to Use
+
+- "What sessions do I have about X?" / "What did we decide about X?"
+- "Rename these sessions to something meaningful."
+- "Clean up my session library" / "archive the stale ones."
+- "Fork that session into a follow-up focused on Y."
+- "Split this into one session per ticket" (see Parallel workstreams below).
+
+## The Two Surfaces
+
+| Task | Surface |
+|---|---|
+| Find sessions by topic, read content, summarize decisions | `session_search` tool (FTS5 over the message store) |
+| List/filter by metadata (age, source, cost, tokens, workspace) | `hermes sessions list` / `stats` via terminal |
+| Rename | `hermes sessions rename <session_id> <title...>` |
+| Bulk soft-hide (reversible) | `hermes sessions archive <filters>` |
+| Delete (destructive) | `hermes sessions delete` / `hermes sessions prune <filters>` |
+| Export before deleting anything valuable | `hermes sessions export --session-id <id> --format md` |
+| Continue work in a new place | `/branch` (fork current session) or start a fresh session and cite the summary |
+
+## Procedure
+
+① **Discover.** Use `session_search(query=..., limit=5-10)` with topic
+keywords; vary phrasing (feature name, symptom, project name). For metadata
+sweeps ("sessions older than 60 days from telegram"), use
+`hermes sessions list --source telegram --limit 50` instead.
+
+② **Summarize per session.** The discovery result's `bookend_start` (goal),
+match window, and `bookend_end` (resolution) usually suffice — only dump a
+full session (`session_search(session_id=...)`) when the user asks for
+decisions in depth. Report each as: link (`@session:` form) — one-line goal —
+one-line outcome.
+
+③ **Plan before acting (MANDATORY for anything that mutates).** Present a
+plan table first: which sessions get renamed to what, which get archived,
+which are proposed for deletion and why (duplicate of which keeper, stale,
+empty). Wait for the user's go-ahead. Exception: a single rename the user
+explicitly dictated can be done directly.
+
+④ **Act with the safest primitive.**
+- Prefer `archive` (reversible soft-hide) over `delete`/`prune`.
+- Always run destructive commands with `--dry-run` first and show the output,
+  then re-run with `--yes` after confirmation.
+- Before deleting anything with meaningful content, offer
+  `hermes sessions export --format md` as a backup.
+
+⑤ **Report.** Renames applied, sessions archived (count + how to undo:
+archived sessions remain in the DB and are listed with `--include-archived`),
+anything exported, anything skipped and why.
+
+## Parallel Workstreams
+
+For "one session per ticket, investigate each, report back": do NOT try to
+drive other live sessions. Use `delegate_task` with one task per workstream —
+each subagent runs in its own session automatically — then synthesize their
+summaries. Mention that each delegation's transcript is itself searchable
+later via `session_search`.
+
+## Pitfalls
+
+- **Never delete without a dry-run + explicit confirmation in this
+  conversation.** A standing "clean things up" is authority to *propose*, not
+  to prune.
+- **`session_search` finds content, not metadata.** Age/cost/source filters
+  live in the CLI; combine both when the request mixes them ("old sessions
+  about pricing").
+- **Titles are identity for `/resume <title>`.** When renaming, keep titles
+  short, unique, and prefix-friendly; warn the user if a rename collides with
+  an existing title.
+- **Archived ≠ deleted.** Archive hides sessions from default listings only.
+  Say which one you did.
+- **Cross-profile session links** (`@session:<profile>/<id>`) are read-only
+  from another profile; management commands act on the current profile's DB.
+
+## Verification
+
+After a cleanup pass, re-run the discovery query and `hermes sessions list`
+to confirm the library reflects the plan (keepers present with new titles,
+archived ones gone from the default listing).