@floh-solutions/pharos-cli 0.17.1 → 0.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "Azure DevOps from a headless shell, for an agent: the whole context of a task in one call, and the wiki/comment verbs Microsoft's MCP server does not ship.",
   "license": "UNLICENSED",
   "author": "FLOH Solutions",
@@ -24,8 +24,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@floh-solutions/plan-to-board": "0.1.1",
-    "@floh-solutions/ado-core": "0.8.0"
+    "@floh-solutions/ado-core": "0.8.0",
+    "@floh-solutions/plan-to-board": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/skill/SKILL.md

@@ -251,24 +251,83 @@ Two ways this fails **silently**, both measured on a real work item:
   deck and looks like it worked. For a slide deck, or a scanned PDF, the payload
   is usually the images — extract them and actually look at them.
 
-**Known-good on a Claude Code machine provisioned by us, measured 2026-08-08.**
-Conditional on purpose: this skill also runs under other agents on machines
-nobody here set up, so read a missing command as "find your own", not as a bug.
+### First ask whether you read PDFs natively. If you do, this is one command.
+
+Many agents — Claude Code among them — read a PDF **visually**, page by page,
+the way a person looks at it. That covers a scan with no text in it at all, with
+no OCR step. If that is you, the whole problem collapses to one conversion:
+
+```bash
+soffice --headless --convert-to pdf f.docx --outdir ./out    # .pptx, .xlsx too
+# then read ./out/f.pdf with your own file-reading tool
+```
+
+**This is the route that keeps the pictures**, which is the whole failure this
+section is about. Measured on the deck described above — the one whose seven
+text fragments lost the specification: converted to PDF and read, it gives up
+the flow diagram, the screenshot of the configuration UI with its actual
+threshold values, and every row and column of the target output table. One
+command, one read, nothing dropped. The same is true of a `.docx` whose content
+is in a chart or a screenshot.
+
+Prefer it whenever layout or images might carry meaning — a deck always, a
+report usually, a spreadsheet when the shape matters more than the numbers.
+
+### If you only read text, extract it per format
 
 | file | how |
 |---|---|
-| `.pdf` | `pdftotext -layout f.pdf -` — poppler; keeps the table layout |
+| `.pdf` | `pdftotext -layout f.pdf -` — poppler; keeps the table layout. **Empty output means a scan**, not an empty document |
 | scanned `.pdf` | `pdftoppm -png -r 150 f.pdf page`, then look at the PNGs it wrote |
-| `.docx` | `soffice --headless --convert-to "txt:Text (encoded):UTF8" f.docx --outdir ./out` — LibreOffice; tables come out tab-separated |
-| `.xlsx` | `soffice --headless --convert-to csv f.xlsx --outdir ./out` — **first sheet only**, so check whether the workbook has more |
-| `.pptx` | `~/.claude/skills/pptx/.venv/bin/python -m markitdown deck.pptx` — slide text, and it NAMES the embedded images without extracting them |
-| images in a `.pptx` | `unzip -o -q deck.pptx 'ppt/media/*' -d ./out` → `out/ppt/media/*.png` |
+| `.docx` | `soffice --headless --convert-to "txt:Text (encoded):UTF8" f.docx --outdir ./out` — tables come out tab-separated |
+| `.xlsx` | `soffice --headless --convert-to csv f.xlsx --outdir ./out` — **first sheet only**. Count them first: `unzip -p f.xlsx xl/workbook.xml \| grep -o '<sheet [^>]*name="[^"]*"'` |
+| `.pptx` | `~/.claude/skills/pptx/.venv/bin/python -m markitdown deck.pptx` — slide text. Its `![](Graphic5.jpg)` lines are SHAPE names, not files: see below |
+| images inside any of them | `unzip -o -q f.pptx 'ppt/media/*' -d ./out` — also `word/media/` in a `.docx`, `xl/media/` in an `.xlsx` |
+
+Two traps in that table, both measured:
+
+- **Do not predict what `pdftoppm` names its output.** The page number is padded
+  to the width of the page COUNT, so a one-page scan — what an attachment
+  usually is — gives `page-1.png` while a forty-page one gives `page-01.png`.
+  List the directory. A guessed name that is not there reads as "the render
+  failed" when it worked.
+- **`--convert-to pdf` paginates a spreadsheet twice over, and only one of them
+  is obvious.** Long splits by ROW, which is ordinary. **Wide splits by
+  COLUMN** — a 40-column sheet became four pages, each carrying a different
+  slice of the columns for the same rows. So a page count above one does not
+  tell you which kind you have: read every page, and if a row looks like it is
+  missing fields, look for them on the next one. For pure numbers `csv` is the
+  better half of the pair.
+
+**Count the parts before you trust a conversion.** Every one of these formats is
+a ZIP, so the file itself will tell you what it holds — and each of these has
+been the thing that was quietly missing:
+
+```bash
+unzip -p f.xlsx xl/workbook.xml | grep -o '<sheet [^>]*name="[^"]*"'   # sheets
+unzip -l f.pptx | grep -c 'ppt/slides/slide[0-9]*\.xml'                # slides
+unzip -l f.docx | grep 'word/media/'                                   # images
+```
 
-**Do not predict what `pdftoppm` names its output.** The page number is padded
-to the width of the page COUNT, so a one-page scan — which is what an attachment
-usually is — gives `page-1.png` while a forty-page one gives `page-01.png`. List
-the directory rather than guessing the name; a guessed name that is not there
-reads as "the render failed" when it worked.
+If the images list is empty, text extraction loses nothing and the cheap route
+is safe. If it is not, that is your warning that the payload may not be text.
+
+**`markitdown`'s image lines name SHAPES, not files.** A deck that emits
+`![](Graphic5.jpg)`, `![](Graphic8.jpg)` and `![](Graphic9.jpg)` for one slide
+turned out to contain exactly two media files in the whole archive — named
+`image1.png` and `image2.svg`, matching none of them. Those are PowerPoint's
+shape names. Do not go looking for a file by one, and do not read three of them
+as three pictures. To map media to the slide that uses it, read the
+relationships: `unzip -p f.pptx ppt/slides/_rels/slide6.xml.rels`.
+
+**Text extraction tells you WHICH strings are on a slide and never WHERE.** That
+is not a nuance — measured on a real deck, one slide carried both `IDENTITEIT`
+and a leftover `Wat is ChatGPT?` from a different presentation, in the same
+place, printing on top of each other. Extracted, they are two tidy lines and
+read as a title with a subtitle. Rendered, the slide is visibly broken. So a
+duplicated, stale or overlapping shape is invisible to every text route by
+construction — if you are reviewing a deck rather than mining it for facts, look
+at it.
 
 `pandoc` is **not** installed here, whatever another skill's instructions say.
 `markitdown` in that venv does `.pptx` and nothing else: it went in without the
@@ -276,6 +335,10 @@ reads as "the render failed" when it worked.
 for all three. That is why LibreOffice, not markitdown, is the line above for
 everything except a deck.
 
+**Known-good on a Claude Code machine provisioned by us, measured 2026-08-08.**
+Conditional on purpose: this skill also runs under other agents on machines
+nobody here set up, so read a missing command as "find your own", not as a bug.
+
 ## Mentioning somebody
 
 **A mention is `@<guid>` and nothing else notifies.** `@Ada Lovelace` written