cc-session-tools 3.3.2__tar.gz → 3.5.2__tar.gz

{cc_session_tools-3.3.2/src/cc_session_tools.egg-info → cc_session_tools-3.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.3.2
+Version: 3.5.2
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License
@@ -569,7 +569,7 @@ Translates a natural-language cadence request ("run my Tesco shop every other Su
 
 ### `update-command-cache`
 
-Curates the SHA-256 command cache the `bash-security-review` hook reads (`CCCS_USE_COMMAND_CACHE=1`). Triggers on "update the command cache", "sweep the fires log for cacheable commands", "promote my recent claude-CLI safe fires". Reads recent `safe`-verdict fires from `telemetry.db`, identifies commands not yet cached, presents them for approval, and records approved ones. Also supports manual `--remove`/`--flip` on existing entries.
+Curates the SHA-256 command cache the `bash-security-review` hook reads (`CCST_USE_COMMAND_CACHE=1`). Triggers on "update the command cache", "sweep the fires log for cacheable commands", "promote my recent claude-CLI safe fires". Reads recent `safe`-verdict fires from `telemetry.db`, identifies commands not yet cached, presents them for approval, and records approved ones. Also supports manual `--remove`/`--flip` on existing entries.
 
 ### `clean-hook-sessions`
 
@@ -679,7 +679,7 @@ Both hooks are included in the standard bundle and installed by
 `ccst hooks install --apply`. Surfacing is per-session (per-session cursor), so
 each session sees each completed run exactly once. Failures never block the
 session; every action is recorded to the shared `telemetry.db` (SQLite, under
-`~/.local/share/claude/`, overridable via `CCCS_HOOKS_DIR`) telemetry ledger —
+`~/.local/share/claude/`, overridable via `CCST_HOOKS_DIR`) telemetry ledger —
 query it with `ccst telemetry query`.
 
 ### `manage-recurring-cc-jobs-using-ccsched` skill
@@ -840,7 +840,7 @@ real risk, which is why this hook blocks rather than just warning like
 - **Only fires if a WORKLOG.md already exists** - it never forces you to
   create one, and never blocks automatic (non-`/compact`) compaction, which
   can happen mid-task in an unattended session with nobody present to react.
-- **Escape hatch:** set `CCCS_ALLOW_STALE_WORKLOG=1` to bypass the block for
+- **Escape hatch:** set `CCST_ALLOW_STALE_WORKLOG=1` to bypass the block for
   one `/compact`.
 
 ### Running modules directly (debugging only)

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/README.md

@@ -512,7 +512,7 @@ Translates a natural-language cadence request ("run my Tesco shop every other Su
 
 ### `update-command-cache`
 
-Curates the SHA-256 command cache the `bash-security-review` hook reads (`CCCS_USE_COMMAND_CACHE=1`). Triggers on "update the command cache", "sweep the fires log for cacheable commands", "promote my recent claude-CLI safe fires". Reads recent `safe`-verdict fires from `telemetry.db`, identifies commands not yet cached, presents them for approval, and records approved ones. Also supports manual `--remove`/`--flip` on existing entries.
+Curates the SHA-256 command cache the `bash-security-review` hook reads (`CCST_USE_COMMAND_CACHE=1`). Triggers on "update the command cache", "sweep the fires log for cacheable commands", "promote my recent claude-CLI safe fires". Reads recent `safe`-verdict fires from `telemetry.db`, identifies commands not yet cached, presents them for approval, and records approved ones. Also supports manual `--remove`/`--flip` on existing entries.
 
 ### `clean-hook-sessions`
 
@@ -622,7 +622,7 @@ Both hooks are included in the standard bundle and installed by
 `ccst hooks install --apply`. Surfacing is per-session (per-session cursor), so
 each session sees each completed run exactly once. Failures never block the
 session; every action is recorded to the shared `telemetry.db` (SQLite, under
-`~/.local/share/claude/`, overridable via `CCCS_HOOKS_DIR`) telemetry ledger —
+`~/.local/share/claude/`, overridable via `CCST_HOOKS_DIR`) telemetry ledger —
 query it with `ccst telemetry query`.
 
 ### `manage-recurring-cc-jobs-using-ccsched` skill
@@ -783,7 +783,7 @@ real risk, which is why this hook blocks rather than just warning like
 - **Only fires if a WORKLOG.md already exists** - it never forces you to
   create one, and never blocks automatic (non-`/compact`) compaction, which
   can happen mid-task in an unattended session with nobody present to react.
-- **Escape hatch:** set `CCCS_ALLOW_STALE_WORKLOG=1` to bypass the block for
+- **Escape hatch:** set `CCST_ALLOW_STALE_WORKLOG=1` to bypass the block for
   one `/compact`.
 
 ### Running modules directly (debugging only)

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.3.2"
+version = "3.5.2"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -72,7 +72,7 @@ cc_session_tools = ["skills/**/*", "config/*", "prompts/**/*"]
 cc_session_tools = ["**/tests/*", "**/__pycache__/*"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests", "tests/scheduler", "src/cc_session_tools/skills/move-session/tests", "src/cc_session_tools/skills/list-empty-sessions/tests", "src/cc_session_tools/skills/delete-sessions/tests", "src/cc_session_tools/skills/generate-8digit-code/tests", "src/cc_session_tools/skills/reduce-persistent-context/tests", "src/cc_session_tools/skills/update-command-cache/tests"]
+testpaths = ["tests", "tests/scheduler", "src/cc_session_tools/skills/move-session/tests", "src/cc_session_tools/skills/list-empty-sessions/tests", "src/cc_session_tools/skills/delete-sessions/tests", "src/cc_session_tools/skills/generate-8digit-code/tests", "src/cc_session_tools/skills/reduce-persistent-context/tests", "src/cc_session_tools/skills/update-command-cache/tests", "src/cc_session_tools/skills/extract-pptx/tests", "src/cc_session_tools/skills/extract-to-text/tests"]
 addopts = "-q"
 pythonpath = ["src"]
 
@@ -82,8 +82,17 @@ dev = [
     "pytest>=7",
     "pytest-mock>=3.12",
     "types-PyYAML>=6.0",
+    "python-pptx>=1.0",
+    "extract-msg>=0.45",
+    "pillow>=10.0",
+    "pytesseract>=0.3",
+    "types-openpyxl>=3.1",
 ]
 
 [[tool.mypy.overrides]]
 module = "tiktoken_tools.*"
 ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "pytesseract.*"
+ignore_missing_imports = true

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/src/cc_session_tools/cli/ccst.py

@@ -96,6 +96,7 @@ import importlib
 import json
 import os
 import sys
+from dataclasses import dataclass
 from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, TextIO, cast
@@ -239,6 +240,37 @@ def _decide_action(skill_src: Path, target_dir: Path) -> tuple[SkillAction, Path
     return SkillAction.NON_SYMLINK_EXISTS, dest
 
 
+@dataclass(frozen=True)
+class StaleSkillSymlink:
+    dest: Path
+    target: Path
+
+
+def _find_stale_skill_symlinks(source_dir: Path, target_dir: Path) -> list[StaleSkillSymlink]:
+    """Return every symlink under target_dir left behind by a rename or removal from
+    source_dir: dangling (its target no longer exists) AND created by a previous install from
+    source_dir (its stored target's parent resolves to source_dir). `ccst skills install` only
+    ever creates symlinks for skills currently in source_dir, so a name it no longer bundles is
+    never revisited by the create/repoint loop above — this is the matching subtractive pass.
+
+    A dangling symlink pointing somewhere other than source_dir is not ours to remove (e.g. a
+    user's own broken symlink), and neither is a non-symlink entry — both are left untouched.
+    """
+    if not target_dir.is_dir():
+        return []
+    resolved_source = source_dir.resolve()
+    stale: list[StaleSkillSymlink] = []
+    for entry in sorted(target_dir.iterdir()):
+        if not entry.is_symlink() or entry.exists():
+            continue
+        raw_target = Path(os.readlink(entry))
+        target = raw_target if raw_target.is_absolute() else (entry.parent / raw_target)
+        if target.parent.resolve() != resolved_source:
+            continue
+        stale.append(StaleSkillSymlink(dest=entry, target=target))
+    return stale
+
+
 def _cmd_skills_install(args: argparse.Namespace) -> int:
     # Resolve source
     if args.source:
@@ -273,8 +305,16 @@ def _cmd_skills_install(args: argparse.Namespace) -> int:
     for action, skill_src, dest in decisions:
         print(f"{skill_src.name:<{col_w}}  {action.value}")
 
+    stale = _find_stale_skill_symlinks(source_dir, target_dir)
+    if stale:
+        print("\nStale symlink(s) (skill no longer bundled):")
+        for entry in stale:
+            print(f"  {entry.dest.name} -> {entry.target}")
+
     if not args.apply:
         print(f"\nDry run — re-run with --apply to create symlinks in {target_dir}")
+        if stale:
+            print(f"({len(stale)} stale symlink(s) above would also be removed)")
         return 0
 
     # Perform writes
@@ -315,12 +355,20 @@ def _cmd_skills_install(args: argparse.Namespace) -> int:
         linked.append(dest)
         print(f"  linked: {dest} -> {skill_src}")
 
+    pruned: list[Path] = []
+    for entry in stale:
+        entry.dest.unlink()
+        pruned.append(entry.dest)
+        print(f"  removed stale: {entry.dest}")
+
     print()
     if linked:
         print(f"Linked {len(linked)} skill(s) in {target_dir}")
     if skipped:
         print(f"Skipped {len(skipped)} (already correct)")
-    if not linked and not skipped and not failed:
+    if pruned:
+        print(f"Removed {len(pruned)} stale symlink(s) no longer bundled")
+    if not linked and not skipped and not pruned and not failed:
         print(f"Nothing to do in {target_dir}")
 
     if failed:
@@ -2757,7 +2805,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "--hooks-dir",
         default=None,
         metavar="DIR",
-        help="telemetry.db directory (default: CCCS_HOOKS_DIR or ~/.local/share/claude/)",
+        help="telemetry.db directory (default: CCST_HOOKS_DIR or ~/.local/share/claude/)",
     )
 
     telemetry_query_parser = telemetry_sub.add_parser(
@@ -2784,7 +2832,7 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     telemetry_query_parser.add_argument(
         "--hooks-dir", default=None, metavar="DIR",
-        help="telemetry.db directory (default: CCCS_HOOKS_DIR or ~/.local/share/claude/)",
+        help="telemetry.db directory (default: CCST_HOOKS_DIR or ~/.local/share/claude/)",
     )
 
     # ---- gc ----

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/src/cc_session_tools/lib/doctor.py

@@ -14,6 +14,7 @@ import os
 import shutil
 import sqlite3
 import subprocess
+import textwrap
 import time
 from dataclasses import dataclass
 from enum import Enum
@@ -1148,6 +1149,21 @@ def _extract_bundle_hook_names(bundle_path: Path) -> list[str]:
     return names
 
 
+def _wrap_reason(reason: str, *, indent: str = "    ") -> str:
+    """Word-wrap a check's reason to the detected terminal width.
+
+    Reasons are long free-text sentences (often 100-250+ characters, with
+    embedded paths and remediation commands); printed on a single line they
+    hard-wrap at the terminal edge with no continuation indent, making a
+    wrapped reason indistinguishable from a new, unrelated result. Wrapping
+    to the real terminal width — falling back to 80 columns for non-tty
+    output (piped, redirected, or the scheduled drift-monitor job whose
+    stdout is forwarded to Telegram) — and indenting every line fixes that.
+    """
+    width = shutil.get_terminal_size(fallback=(80, 24)).columns
+    return textwrap.fill(reason, width=width, initial_indent=indent, subsequent_indent=indent)
+
+
 def format_results(results: list[CheckResult], *, show_all: bool = False) -> str:
     """Return a human-readable table of check results.
 
@@ -1156,15 +1172,27 @@ def format_results(results: list[CheckResult], *, show_all: bool = False) -> str
     otherwise dozens of [OK] lines a user has to scroll past to find the one
     thing that needs attention. show_all=True reproduces the full table this
     function always printed before this parameter existed.
+
+    A non-OK result renders as a two-line record — `[STATUS] name` on its own
+    line, then the reason wrapped and indented below it — since its reason is
+    the long free-text kind `_wrap_reason` exists for. OK rows (only ever
+    shown via show_all) stay a single fixed-width `[OK]   name  reason` line;
+    their reasons are short and there's nothing to disambiguate from a
+    neighbouring result.
     """
     if not results:
         return "(no checks ran)"
     shown = results if show_all else [r for r in results if r.status is not Status.OK]
     lines = []
     if shown:
-        name_w = max(len(r.name) for r in shown)
+        ok_shown = [r for r in shown if r.status is Status.OK]
+        name_w = max((len(r.name) for r in ok_shown), default=0)
         for r in shown:
-            lines.append(f"[{r.status.value:<4}] {r.name:<{name_w}}  {r.reason}")
+            if r.status is Status.OK:
+                lines.append(f"[{r.status.value:<4}] {r.name:<{name_w}}  {r.reason}")
+            else:
+                lines.append(f"[{r.status.value:<4}] {r.name}")
+                lines.append(_wrap_reason(r.reason))
     elif not show_all:
         lines.append(f"All {len(results)} checks OK.")
     has_issues = any(r.status in (Status.WARN, Status.FAIL) for r in results)
@@ -1201,10 +1229,10 @@ def format_drift_report(unmuted: list[CheckResult], *, muted_count: int) -> str:
     """
     if not unmuted:
         return ""
-    name_w = max(len(r.name) for r in unmuted)
     lines = ["ccst doctor: un-muted drift detected —"]
     for r in unmuted:
-        lines.append(f"  [{r.status.value:<4}] {r.name:<{name_w}}  {r.reason}")
+        lines.append(f"  [{r.status.value:<4}] {r.name}")
+        lines.append(_wrap_reason(r.reason))
     lines.append("")
     lines.append(
         "Acknowledge an item with:  ccst doctor --mute <name>"

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/src/cc_session_tools/lib/pdata/resolve.py

@@ -7,7 +7,7 @@ overwrite (that is rehydrate.py's job for the clean fast-forward case; this modu
 `ccst pdata resolve` reaches for once vector_clock.compare() has already reported a genuine FORK).
 
 Never auto-merges, never silently keeps one side and discards the other — every record surfaced
-here needs an explicit choice from the caller (ultimately Chris, via the CLI/skill), matching the
+here needs an explicit choice from the caller (ultimately the user, via the CLI/skill), matching the
 existing `pm-pdata-resolve-conflicts` skill's single-file-conflict framing exactly. Every
 record: `apply_resolution` is all-or-nothing over the whole diff, for the reasons in its own
 docstring.

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/src/cc_session_tools/lib/scheduler/ledger.py

@@ -50,7 +50,7 @@ class LedgerEntry:
 
 
 def _hooks_dir() -> Path:
-    """The telemetry.db directory: the CCCS_HOOKS_DIR override when set,
+    """The telemetry.db directory: the CCST_HOOKS_DIR override when set,
     else telemetry_store's default. Kept as a thin wrapper so catchup.py's
     existing ``ledger._hooks_dir()`` call keeps working unchanged."""
     return telemetry_store.hooks_dir()

{cc_session_tools-3.3.2 → cc_session_tools-3.5.2}/src/cc_session_tools/lib/telemetry_store.py

@@ -1,4 +1,4 @@
-"""Shared schema, CCCS_HOOKS_DIR resolution, and connection helper for
+"""Shared schema, CCST_HOOKS_DIR resolution, and connection helper for
 telemetry.db. Single source of truth so hooks.telemetry (writer),
 hooks.telemetry_trim, hooks.telemetry_query, and
 lib.scheduler.ledger (catch-up reader/writer) can never point at different
@@ -35,7 +35,7 @@ from pathlib import Path
 
 from cc_session_tools.lib import db, paths
 
-HOOKS_DIR_ENV = "CCCS_HOOKS_DIR"
+HOOKS_DIR_ENV = "CCST_HOOKS_DIR"
 DB_FILENAME = "telemetry.db"
 
 # Marker name recorded in the migrations table by cli.migrate_telemetry once
@@ -80,14 +80,14 @@ CREATE INDEX IF NOT EXISTS idx_catchup_events_job_id ON catchup_events(job_id);
 
 # Computed once at import time; tests override it with
 # monkeypatch.setattr(telemetry_store, "_DEFAULT_HOOKS_DIR", tmp_path) to
-# exercise the "CCCS_HOOKS_DIR unset" production-default path, matching the
+# exercise the "CCST_HOOKS_DIR unset" production-default path, matching the
 # existing repo-wide convention for a module-level default.
 _DEFAULT_HOOKS_DIR = paths.data_home()
 
 
 def hooks_dir(explicit: Path | None = None) -> Path:
     """Resolve the telemetry.db directory: explicit override, else
-    CCCS_HOOKS_DIR, else the module default."""
+    CCST_HOOKS_DIR, else the module default."""
     if explicit is not None:
         return explicit
     raw = os.environ.get(HOOKS_DIR_ENV)

cc_session_tools-3.5.2/src/cc_session_tools/skills/extract-pptx/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: extract-pptx
+description: Use when text needs to be extracted from a .pptx PowerPoint file - slide text, tables, speaker notes, text baked into images (OCR), or embedded file objects (embedded workbooks/documents). Also use when a .pptx needs a sibling print-to-PDF. Triggers on "extract this pptx", "read this powerpoint", "pptx won't extract", "pandoc can't read pptx", empty/failed pptx mirrors in a text-extraction pipeline, or any pptx-to-markdown/pptx-to-pdf task. Do NOT use pandoc for pptx input - pandoc has a markdown writer but no pptx reader.
+---
+
+# Extract PPTX
+
+## Why this exists
+
+Pandoc has a markdown *writer* but no `.pptx` *input reader*. Any pipeline that
+routes Office formats through `pandoc -t markdown` (a correct, common pattern
+for preserving Word/RTF tables) silently or loudly fails on every `.pptx` file.
+There is no pandoc flag that fixes this - it needs a different extractor
+entirely. This skill wraps a `python-pptx`-based one. The sibling `extract-to-text`
+skill delegates its own `.pptx`/`.pptm` handling to this script rather than
+re-implementing pptx extraction.
+
+## When to use
+
+- A `.pptx` file needs its text extracted and pandoc has failed, returned empty
+  output, or isn't an option.
+- A text-extraction pipeline's `--check`/audit step shows `.pptx` mirrors as
+  empty, missing, or `FAILED`.
+- Text is baked into an image on a slide (a chart export, a scanned page
+  pasted as a picture) and needs OCR to be readable.
+- A slide has an embedded object (an embedded Excel sheet, a Word doc) whose
+  content needs to be pulled out, not just referenced.
+- A clean, paginated PDF render of a `.pptx` is needed alongside the text
+  extraction (evidence packs, archival records).
+
+**Do NOT use** `pandoc -t markdown <file>.pptx` - it will fail or silently
+produce nothing useful. Do not hand-roll a second one-off pptx extractor
+either; use or extend this one so behaviour stays consistent across projects.
+
+## How it works
+
+`scripts/extract_pptx.py` opens the file with `python-pptx` and, per slide,
+in order:
+
+1. Walks every shape (text frames, tables, and groups recursively) and
+   collects text in slide order. Table cells are extracted cell-by-cell, not
+   just shape text - this matters the same way it matters for docx tables
+   (see the sibling `extract-to-text` skill's docx-table-loss motivation).
+2. If OCR is enabled (default), runs Tesseract over every picture shape's
+   image bytes and appends the result labelled as OCR text, distinct from
+   slide body text.
+3. Extracts speaker notes if present, labelled distinctly from slide body
+   text.
+4. Extracts embedded OLE/package objects (embedded workbooks, documents)
+   referenced by the slide's relationships, if `--embeds-dir` is given.
+5. Optionally renders a sibling PDF via headless LibreOffice (`soffice`), if
+   `--pdf-out` is given.
+
+## Procedure
+
+```bash
+python3 ~/.claude/skills/extract-pptx/scripts/extract_pptx.py <source.pptx> \
+    --out-md <output.md> \
+    [--embeds-dir <dir-for-embedded-files>] \
+    [--pdf-out <output.pdf>] \
+    [--no-ocr]
+```
+
+- `--out-md` is required; the other three are opt-in.
+- OCR is **on by default** and fails loudly (non-zero exit, clear message) if
+  `pytesseract`/Pillow or the `tesseract` binary is missing - it does not
+  silently skip OCR and produce an incomplete-looking-complete file. Pass
+  `--no-ocr` explicitly if OCR isn't wanted for this run.
+- `--embeds-dir` is only written to if the slide actually has embedded
+  objects; it's never created empty.
+- `--pdf-out` requires `soffice` (LibreOffice) on `PATH`. If it's missing the
+  script exits non-zero with a clear message rather than skipping the PDF
+  silently - report that to the user rather than treating the run as
+  complete.
+
+Verify the output: open `--out-md` and confirm slide count and non-trivial
+content; a `.pptx` with no extractable text on any slide is possible
+(image-only decks) but should be rare - treat an entirely-empty result the
+same way a hand-rolled pipeline treats `empty-output-CHECK-THIS`, not as a
+quiet success.
+
+## Refusing fallbacks
+
+Do not silently drop OCR, embeds, or the PDF render when a dependency is
+missing and substitute a partial result without saying so. The script is
+built to fail loudly for exactly this reason - surface the failure to the
+user rather than working around it.
+
+## Reusing this in a project-local extractor
+
+If a project has its own canonical text-extraction script (e.g. one that
+mirrors an archive into markdown files with status metadata), do not import
+this script into it directly across a network/OneDrive boundary - a
+project's canonical script needs to run standalone on every machine it syncs
+to, independent of whether this bundled skill happens to be installed there.
+Port the relevant logic (shape/table/notes walking at minimum) into the
+project's own script instead, matching that script's existing conventions for
+status/output. Treat OCR, embeds, and PDF rendering as separate, explicitly
+opted-into capabilities when porting - they add real dependencies and runtime
+cost that a project's canonical extractor may not want by default.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `pandoc failed` / empty pandoc output on a `.pptx` | pandoc has no pptx reader | Don't use pandoc for pptx; use this skill instead |
+| `ModuleNotFoundError: pytesseract` | OCR deps not installed | `pip install --user pytesseract pillow` (add `--break-system-packages` if the environment is externally-managed) |
+| `tesseract binary is not on PATH` | Tesseract OCR engine not installed | Install `tesseract-ocr` (apt/brew/winget) |
+| `no soffice/libreoffice binary found` | LibreOffice not installed | Install LibreOffice, or run in a container that has it |
+| OCR text is garbled/partial | Low-res or stylised image text | Expected - Tesseract accuracy depends on image quality; note it as approximate in any evidence use |
+| Embeds dir stays empty | Slide genuinely has no embedded OLE/package objects | Not a bug - only shapes with an actual embed relationship produce output |

cc_session_tools-3.5.2/src/cc_session_tools/skills/extract-pptx/scripts/extract_pptx.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+
+"""Extract a .pptx file's full content: slide text, tables, speaker notes, OCR of
+embedded images, embedded file objects, and (optionally) a sibling print-to-PDF.
+
+Used by the `extract-pptx` skill. Exists because pandoc has a markdown *writer*
+but no `.pptx` *reader* - there is no pandoc input format for PowerPoint, so any
+pipeline that routes Office formats through `pandoc -t markdown` (a common,
+otherwise-correct pattern for preserving Word/RTF tables) silently or loudly
+fails on every .pptx file. This script is a standalone python-pptx-based
+replacement for the .pptx case specifically.
+
+Dependencies:
+  python-pptx   pip install python-pptx
+  Pillow        pip install pillow          (only needed for --ocr)
+  pytesseract   pip install pytesseract     (only needed for --ocr)
+  tesseract-ocr binary on PATH               (only needed for --ocr; apt/brew/winget package)
+  soffice (LibreOffice) on PATH              (only needed for --pdf-out)
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+EMBED_RELTYPE_MARKERS = ("package", "oleObject")
+
+
+def shape_text(shape) -> list[str]:
+    """Return this shape's own text content as a list of lines. Recurses into
+    groups; handles plain text frames and tables. Does not touch images."""
+    lines: list[str] = []
+
+    if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+        for sub in shape.shapes:
+            lines.extend(shape_text(sub))
+        return lines
+
+    if getattr(shape, "has_table", False) and shape.has_table:
+        table = shape.table
+        for row in table.rows:
+            cells = [cell.text.strip() for cell in row.cells]
+            if any(cells):
+                lines.append(" | ".join(cells))
+        return lines
+
+    if getattr(shape, "has_text_frame", False) and shape.has_text_frame:
+        text = shape.text_frame.text
+        if text.strip():
+            lines.extend(text.split("\n"))
+        return lines
+
+    return lines
+
+
+def extract_slide_images(slide) -> list[tuple[str, bytes, str]]:
+    """Return (shape_name, image_bytes, image_ext) for every picture shape on
+    this slide, recursing into groups."""
+    found: list[tuple[str, bytes, str]] = []
+
+    def walk(shapes):
+        for shape in shapes:
+            if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+                walk(shape.shapes)
+            elif shape.shape_type == MSO_SHAPE_TYPE.PICTURE:
+                image = shape.image
+                found.append((shape.name, image.blob, image.ext))
+
+    walk(slide.shapes)
+    return found
+
+
+def extract_slide_embeds(slide) -> list[tuple[str, bytes]]:
+    """Return (filename, bytes) for every embedded OLE/package object
+    (embedded workbooks, documents, etc.) referenced by this slide."""
+    found: list[tuple[str, bytes]] = []
+    for rel in slide.part.rels.values():
+        if rel.is_external:
+            continue
+        if not any(marker in rel.reltype for marker in EMBED_RELTYPE_MARKERS):
+            continue
+        target = rel.target_part
+        fname = Path(str(target.partname)).name
+        found.append((fname, target.blob))
+    return found
+
+
+def ocr_image(image_bytes: bytes) -> str:
+    import io
+
+    from PIL import Image
+    import pytesseract
+
+    img = Image.open(io.BytesIO(image_bytes))
+    return pytesseract.image_to_string(img).strip()
+
+
+def render_pdf(src: Path, pdf_out: Path, timeout: int) -> None:
+    soffice = shutil.which("soffice") or shutil.which("libreoffice")
+    if not soffice:
+        sys.exit(
+            "ERROR: --pdf-out requested but no `soffice` / `libreoffice` binary found on PATH. "
+            "Install LibreOffice, or run this script inside a container that has it. "
+            "Refusing to silently skip the PDF - report this to the user."
+        )
+    with tempfile.TemporaryDirectory() as tmp:
+        result = subprocess.run(
+            [soffice, "--headless", "--convert-to", "pdf", "--outdir", tmp, str(src)],
+            capture_output=True, text=True, timeout=timeout,
+        )
+        produced = Path(tmp) / (src.stem + ".pdf")
+        if result.returncode != 0 or not produced.exists():
+            sys.exit(
+                f"ERROR: soffice failed to render PDF.\nstdout: {result.stdout}\nstderr: {result.stderr}"
+            )
+        pdf_out.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(produced), str(pdf_out))
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Extract text, tables, notes, OCR, embeds, and (optionally) a sibling PDF from a .pptx file.")
+    p.add_argument("pptx", type=Path, help="Path to the source .pptx file.")
+    p.add_argument("--out-md", type=Path, required=True, help="Output markdown path.")
+    p.add_argument("--pdf-out", type=Path, default=None, help="Also render a sibling PDF at this path (requires soffice/LibreOffice).")
+    p.add_argument("--embeds-dir", type=Path, default=None, help="Directory to extract embedded OLE/package objects into. Skipped if none are found.")
+    p.add_argument("--no-ocr", action="store_true", help="Skip OCR of embedded images (default: OCR is attempted; missing tesseract is a hard error, not a silent skip).")
+    p.add_argument("--timeout", type=int, default=180, help="Subprocess timeout in seconds for the PDF render step (default 180).")
+    args = p.parse_args()
+
+    if not args.pptx.exists():
+        sys.exit(f"ERROR: source file does not exist: {args.pptx}")
+
+    if not args.no_ocr:
+        try:
+            import pytesseract  # noqa: F401
+            from PIL import Image  # noqa: F401
+        except ImportError as e:
+            sys.exit(f"ERROR: OCR requested (default) but a dependency is missing ({e}). "
+                      "Install pillow + pytesseract, or pass --no-ocr to skip OCR explicitly.")
+        if not shutil.which("tesseract"):
+            sys.exit("ERROR: OCR requested (default) but the `tesseract` binary is not on PATH. "
+                      "Install tesseract-ocr, or pass --no-ocr to skip OCR explicitly.")
+
+    prs = Presentation(str(args.pptx))
+
+    out_lines: list[str] = [f"# {args.pptx.name}", ""]
+    total_embeds: list[tuple[int, str, Path]] = []
+
+    for idx, slide in enumerate(prs.slides, start=1):
+        out_lines.append(f"## Slide {idx}")
+        out_lines.append("")
+
+        body_lines = shape_text_all(slide)
+        if body_lines:
+            out_lines.extend(body_lines)
+        else:
+            out_lines.append("*(no extractable text on this slide)*")
+        out_lines.append("")
+
+        if not args.no_ocr:
+            images = extract_slide_images(slide)
+            for shape_name, blob, ext in images:
+                text = ocr_image(blob)
+                if text:
+                    out_lines.append(f"**OCR text from image `{shape_name}` (slide {idx}):**")
+                    out_lines.append("")
+                    out_lines.append(text)
+                    out_lines.append("")
+
+        if slide.has_notes_slide:
+            notes = slide.notes_slide.notes_text_frame.text.strip()
+            if notes:
+                out_lines.append(f"**Speaker notes (slide {idx}):**")
+                out_lines.append("")
+                out_lines.append(notes)
+                out_lines.append("")
+
+        embeds = extract_slide_embeds(slide)
+        for fname, blob in embeds:
+            if args.embeds_dir:
+                dest = args.embeds_dir / f"slide{idx:03d}-{fname}"
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_bytes(blob)
+                total_embeds.append((idx, fname, dest))
+
+    if total_embeds:
+        out_lines.append("## Embedded file objects")
+        out_lines.append("")
+        for idx, fname, dest in total_embeds:
+            out_lines.append(f"- Slide {idx}: `{fname}` -> `{dest}`")
+        out_lines.append("")
+
+    args.out_md.parent.mkdir(parents=True, exist_ok=True)
+    args.out_md.write_text("\n".join(out_lines), encoding="utf-8")
+    print(f"OK: wrote {args.out_md} ({len(prs.slides)} slides, {len(total_embeds)} embed(s))")
+
+    if args.pdf_out:
+        render_pdf(args.pptx, args.pdf_out, args.timeout)
+        print(f"OK: wrote {args.pdf_out}")
+
+    return 0
+
+
+def shape_text_all(slide) -> list[str]:
+    lines: list[str] = []
+    for shape in slide.shapes:
+        lines.extend(shape_text(shape))
+    return lines
+
+
+if __name__ == "__main__":
+    sys.exit(main())