opencode-skills-collection 4.1.14 → 4.1.16

package/bundled-skills/slideops/references/automation.md

@@ -0,0 +1,185 @@
+# Keeping a deck in sync
+
+A deck is generated from code once. Keeping it true after that is the part every
+documentation effort loses, and it is the part this skill automates.
+
+Two costs, and they are nothing alike:
+
+| | What it costs | How often to run it |
+|---|---|---|
+| **Detect** (`scripts/check.py`) | standard library only, no model, no network, no tokens. Milliseconds. | As often as you like |
+| **Repair** (an agent rewrites slides) | tokens, and a review | Only when detect says so, and only for evergreen docs |
+
+That asymmetry is the whole design. Detection is free, so it can be everywhere. Repair is
+not, so it is a decision someone makes on purpose, scoped by `check` to the slides that
+actually drifted rather than a re-read of the whole deck.
+
+## The loop
+
+```
+build once  ->  check whenever (free)  ->  refresh on purpose (scoped)
+```
+
+## Level 1: on demand
+
+The default, and for most decks the only level you need:
+
+```bash
+python3 scripts/check.py docs/slides/ --repo .            # sweep every deck in the folder
+python3 scripts/check.py docs/slides/ --repo . --quiet    # silent unless something drifted
+python3 scripts/check.py docs/slides/ --repo . --suggest  # + diff, commits, corrected citation
+```
+
+A directory sweeps recursively and skips HTML that carries no citations, so pointing it at
+`docs/` is safe. Exit code is 1 when anything is stale, 0 when clean.
+
+In a session, "are the decks still true?" is enough: the agent runs the sweep and reads
+the result.
+
+## Level 2: on a pull request
+
+The right gate for a deck people rely on. Not every commit: a docs check that blocks the
+fast path teaches everyone to pass `--no-verify`, and drift is a review-time concern, not
+a keystroke-time one.
+
+`check.py` is one dependency-free file, so a repo that owns decks should vendor it rather
+than depend on every contributor having the skill installed:
+
+```bash
+curl -o tools/slideops-check.py \
+  https://raw.githubusercontent.com/glukicov/slideops/main/skills/slideops/scripts/check.py
+```
+
+(Or copy it out of your own checkout: `cp skills/slideops/scripts/check.py tools/`. Where
+the installed copy lives depends on how the skill was installed, so the URL is the portable
+instruction.)
+
+```yaml
+# .github/workflows/deck-freshness.yml
+name: Deck freshness
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Are the decks still true?
+        run: |
+          python3 tools/slideops-check.py docs/slides/ --repo . --suggest --exit-zero \
+            | tee -a "$GITHUB_STEP_SUMMARY"
+```
+
+`--exit-zero` makes this **report-only**: the drift and its fix land in the PR summary,
+and nobody is blocked. Start here. Drop `--exit-zero` later, for the one or two decks the
+team actually relies on, once the reports have been quiet for a while.
+
+## Level 3: delegated refresh
+
+This is where the tokens go, and the reason detection is worth wiring up at all.
+
+`--json` is a complete repair brief. For every stale citation it carries the status, the
+unified diff, **the commits that caused it**, the corrected `data-src` and `data-sha256`,
+and the current source. Current citations stay one line each, so the payload stays small:
+
+```bash
+python3 scripts/check.py docs/slides/ --repo . --json > /tmp/drift.json
+```
+
+The commit subjects are the part a diff cannot give you. "rename helper for clarity" and
+"drop the retry branch" produce similar diffs and need completely different slide edits:
+one is a re-quote, the other may invalidate the claim the slide is making.
+
+Hand that to the agent (headless, in CI, or in a session):
+
+```bash
+claude -p "Refresh the stale slides in docs/slides/.
+$(cat /tmp/drift.json)
+
+For each stale citation: read the diff and the commit subjects, decide whether the slide's
+CLAIM is still true, then either re-quote (MOVED: attributes only, leave the prose alone)
+or rewrite the slide (CHANGED: the claim may be dead). Update data-src and data-sha256 from
+suggested_src/suggested_sha256, re-stamp the build meta with scripts/cite.py --stamp, then
+re-run check.py until clean and re-screenshot only the slides you touched." \
+  --allowedTools "Read,Edit,Bash"
+```
+
+Then open it as a pull request rather than a push, because a refresh is a content change
+that deserves the same review as the code that caused it. Monthly on a schedule works well
+for an onboarding deck:
+
+```yaml
+on:
+  schedule:
+    - cron: "0 9 1 * *"     # 09:00 on the 1st
+  workflow_dispatch:
+```
+
+Guard the token spend with the free half first, so a quiet month costs nothing:
+
+```bash
+python3 tools/slideops-check.py docs/slides/ --repo . --quiet || refresh_decks
+```
+
+## Level 4: agent hooks, advisory only
+
+If you want the agent itself to notice, keep it to a notification. A hook that blocks is a
+hook that gets disabled.
+
+`SessionStart` is the low-noise option: one line, once, at the point where acting on it is
+cheap. With `--quiet`, a clean repo prints nothing at all.
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 tools/slideops-check.py docs/slides/ --repo . --quiet --exit-zero"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+A git `pre-commit` hook is the same idea, and the same rule applies: warn, exit 0, never
+block.
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit: advisory, never blocking
+python3 tools/slideops-check.py docs/slides/ --repo . --quiet --exit-zero
+exit 0
+```
+
+## What to automate, and what to let rot
+
+Not every deck deserves any of this. Automating a snapshot is pure waste:
+
+| Deck | Automate? |
+|---|---|
+| Onboarding, architecture, anything linked from the README | Yes: PR check, and a scheduled refresh |
+| A subsystem deep dive the team keeps returning to | PR check, report-only |
+| Sprint update, "what shipped in March" | No. It is a record of a moment and is *supposed* to freeze |
+| A conference talk you gave once | No |
+
+A deck that describes a point in time should keep describing that point in time. Freshness
+checking is for documents that claim to describe *now*.
+
+## What a clean check does not prove
+
+`check` verifies that quoted source still matches the code. It cannot see that the prose
+around a snippet has become wrong, that a slide is missing a subsystem added last quarter,
+or that the architecture diagram is now a lie. It tells you what has **definitely** drifted,
+which is the part humans reliably miss, and it makes the rest a smaller problem.

package/bundled-skills/slideops/references/diagrams.md

@@ -0,0 +1,92 @@
+# Diagrams: built-in flow boxes vs pre-rendered Mermaid
+
+Two ways to draw architecture on a slide. Both must depict the **real, verified** call
+path (SKILL.md Step 1); the choice is only about rendering.
+
+| Situation | Use |
+|---|---|
+| Linear pipeline, ≤6 boxes, one or two rows | Template's `.flow`/`.flow-box` pattern (no tooling, styles itself with the theme) |
+| Sequence diagram (request/response between components) | Mermaid `sequenceDiagram` |
+| Branching graph, fan-in/fan-out, back-edges | Mermaid `flowchart` |
+| ER / schema relationships | Mermaid `erDiagram` |
+| Git branching story | Mermaid `gitGraph` |
+
+Never load mermaid.js at runtime: the deck must stay a single self-contained file with no
+network access. Instead **pre-render to SVG at build time and inline the SVG** into the
+slide.
+
+This is the one step that downloads code. It fetches a pinned `@mermaid-js/mermaid-cli`
+unless the binary is already installed, so treat it as an opt-in the user agreed to in the
+intake: if the environment has no network, or the user did not opt in, use the flow-box
+pattern instead and say why. Diagram sources you write are your own text, but the labels
+in them land in a shipped artifact, so the confidentiality rule applies to them too.
+
+## Render recipe
+
+1. Write the diagram source to `$STAGE/<name>.mmd`.
+2. Write a theme config deriving from the deck's current `:root` tokens (open the deck and
+   copy the literal values; mermaid can't read CSS variables):
+
+```json
+// $STAGE/mermaid-config.json: values from the DECK'S CURRENT THEME, not hardcoded olive
+{
+  "theme": "base",
+  "themeVariables": {
+    "background": "transparent",
+    "primaryColor": "<--card>",
+    "primaryTextColor": "<--fg>",
+    "primaryBorderColor": "<--accent>",
+    "lineColor": "<--muted>",
+    "secondaryColor": "<--bg2>",
+    "tertiaryColor": "<--bg>",
+    "fontFamily": "-apple-system, Segoe UI, Roboto, sans-serif",
+    "fontSize": "16px"
+  }
+}
+```
+
+3. Point puppeteer at the same Chrome that verification.md's `find_chrome` found (no
+   second browser download):
+
+```bash
+printf '{ "executablePath": "%s" }\n' "$CHROME" > "$STAGE/puppeteer-config.json"
+# Pinned: an unpinned `npx --yes` runs whatever the registry serves today, unreviewed.
+# If mmdc is already installed, use it and skip the download entirely.
+MMDC=$(command -v mmdc || echo "npx --yes @mermaid-js/mermaid-cli@11.4.2")
+$MMDC \
+  -i "$STAGE/<name>.mmd" -o "$STAGE/<name>.svg" \
+  -c "$STAGE/mermaid-config.json" -p "$STAGE/puppeteer-config.json" \
+  -b transparent -I "mmd-<name>"
+```
+
+4. Inline the SVG into the slide inside `.img-wrap` (the template constrains inline SVG to
+   the slide body):
+
+```html
+<section class="slide">
+  <div class="kicker">[Section name]</div>
+  <h2>[Slide title]</h2>
+  <div class="img-wrap"><!-- paste the full <svg …>…</svg> here --></div>
+  <p class="caption">[What the diagram shows; verified against the real call path.]</p>
+</section>
+```
+
+## Rules that matter
+
+- **`-I "mmd-<name>"` (unique per diagram) is mandatory.** The SVG's internal `<style>` is
+  scoped to its root id; two inlined diagrams with the default `my-svg` id restyle each
+  other.
+- **Theme by config, verify by screenshot.** Some mermaid internals (e.g. sequence-diagram
+  activation bars) ignore `themeVariables` and keep light-grey fills; that's usually fine
+  on dark themes, but check the slide screenshot for unreadable text or glaring fills and
+  simplify the diagram (or switch diagram type) if theming fights you.
+- **A rethemed deck does not retheme inlined SVGs.** Their colors are baked at render
+  time; re-run this recipe for every Mermaid slide after a theme swap.
+- **Size**: mermaid emits `width="100%"` with a `viewBox`; the slide's `.img-wrap` caps it
+  to the available body. If a diagram renders too small to read at 1280×720, it has too
+  many nodes for one slide: split it, don't shrink the font.
+- **Keep the `.mmd` sources** in `$STAGE` until the deck ships, then delete with the rest
+  of staging; the inlined SVG is the artifact. If the user wants editable sources kept,
+  put them next to the deck as `<deck>-diagrams/<name>.mmd`.
+- Escape rules still apply to `.mmd` content on slides only if you *show* the source in a
+  `<pre>`; the inlined SVG itself is already valid markup: never HTML-escape it.

package/bundled-skills/slideops/references/verification.md

@@ -0,0 +1,124 @@
+# Verification & PDF export
+
+## Setup: headless Chrome + a staging directory
+
+Headless Chrome is the workhorse for this whole skill: it's how you look at a slide before
+telling the user it's done, and it's how you produce a PDF at the end.
+
+**Chrome discovery is platform-dependent.** The Playwright browser cache lives at
+`~/Library/Caches/ms-playwright` on macOS and `~/.cache/ms-playwright` on Linux, and the
+binary path inside a `chromium-*` bundle differs per platform, so discover it by searching
+for the binary itself rather than hardcoding a subpath:
+
+```bash
+find_chrome() {
+  local base c
+  for base in "$HOME/Library/Caches/ms-playwright" "$HOME/.cache/ms-playwright"; do
+    [ -d "$base" ] || continue
+    c=$(find "$base" -maxdepth 6 -type f \
+          \( -name chrome -o -name Chromium -o -name "Google Chrome for Testing" \) \
+          2>/dev/null | grep -v headless_shell | sort -V | tail -1)
+    [ -n "$c" ] && { printf '%s\n' "$c"; return; }
+  done
+  # System installs as a last resort
+  for c in "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+           "$(command -v google-chrome || true)" "$(command -v chromium || true)"; do
+    [ -x "$c" ] && { printf '%s\n' "$c"; return; }
+  done
+}
+CHROME=$(find_chrome)
+[ -x "$CHROME" ] || { npx --yes playwright install chromium; CHROME=$(find_chrome); }
+"$CHROME" --version   # sanity-check before the loop
+```
+
+(Windows is untested; adapt the cache path, `%LOCALAPPDATA%\ms-playwright`, and binary
+name if you're there.) Quote `"$CHROME"` everywhere: the macOS binary path contains spaces.
+
+**Keep the Chrome sandbox on.** The commands below deliberately omit `--no-sandbox`. You
+are rendering a page built from repository content, so the sandbox is the layer that
+contains a malicious payload if one ever reaches a slide. Add `--no-sandbox` only if
+Chrome refuses to start as root inside a container that cannot grant user namespaces, and
+say so when you do; the better fix is to run as a non-root user.
+
+**Staging directory: always fresh, always per-deck.** Never use fixed shared paths like
+`/tmp/slide-01.png`: parallel deck builds (or a second deck in the same session) collide
+on them. If your environment provides a session scratchpad directory, create a
+subdirectory of it per deck; otherwise:
+
+```bash
+STAGE=$(mktemp -d -t slides)
+DECK="deck.html"   # your deck's actual filename; the loops below use it
+```
+
+All commands below write into `$STAGE`. Delete the whole directory when the deck ships.
+
+## Visual verification (do this for every slide, every edit: see SKILL.md Step 4)
+
+Screenshot a single slide (fast, for spot-checking one edit; the URL hash is 1-indexed,
+`#7` is display slide 7, i.e. the section with comment `<!-- 6: ... -->`):
+
+```bash
+"$CHROME" --headless=new --disable-gpu --hide-scrollbars \
+  --window-size=1280,720 --screenshot="$STAGE/slide.png" "file://$(pwd)/$DECK#7"
+```
+
+Screenshot every slide (do this at least once before calling a deck "done", and again after
+any batch of structural edits: insertions/deletions/reflows, not just wording tweaks).
+Each cold Chrome launch takes ~2-3 s; batching a few in parallel keeps a 25-slide deck
+under ~30 s:
+
+```bash
+N=$(grep -c '<section class="slide' "$DECK")
+for i in $(seq 1 $N); do
+  "$CHROME" --headless=new --disable-gpu --hide-scrollbars \
+    --window-size=1280,720 --screenshot="$STAGE/slide-$(printf "%02d" $i).png" \
+    "file://$(pwd)/$DECK#${i}" &
+  [ $((i % 4)) -eq 0 ] && wait
+done; wait
+```
+
+Then actually view each PNG. Things this catches in practice, every time it's run:
+
+- Text or an image overlapping the bottom nav pill (fix: tighten vertical spacing, reduce a
+  `margin-top`, or shorten the offending copy).
+- A grid of cards stretching to fill leftover vertical space. The template's `.cols-2` /
+  `.cols-3` default to content height; if you added the `fill` class (or a `flex:1`
+  inline style) and the content doesn't need the room, remove it, or pin the stretching
+  children with `flex:0 0 auto`.
+- A relative image path (`../img/foo.png`) that resolves fine when the deck lives in its
+  original folder but breaks the moment you copy the HTML somewhere else to screenshot it
+  (see "PDF export" below: this is the single most common failure mode when generating a
+  PDF export copy).
+- Stale slide-number comments after an insertion/deletion: re-derive with
+  `grep -n '<!-- [0-9]*:' "$DECK"` and renumber whenever the count changes.
+
+## Redaction scan (before you hand anything over)
+
+Run this on the finished artifacts, not on the source, and read every hit:
+
+```bash
+grep -nEi "api[_-]?key|secret|token|password|passwd|BEGIN [A-Z ]*PRIVATE KEY|\bAKIA[0-9A-Z]{16}\b|xox[baprs]-|ghp_[A-Za-z0-9]{20,}|[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|\b(10|127|172|192)\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\b" "$DECK"
+```
+
+The regex is a net, not a verdict: a hit inside the word "tokenized" is fine, a hit on a
+real key is a stop-everything. Also check by eye, because these do not grep:
+
+- **Every embedded image**, including ones you generated. Look at window titles, file
+  trees, branch names, ticket ids, notification banners, and neighbouring tabs.
+- **Speaker notes** (`<aside class="notes">`): they ship inside the HTML even though they
+  are hidden, so anyone who opens the file can read them.
+- **HTML comments**, including the slide-index comments, for anything pasted while drafting.
+- **The PDF**, separately from the HTML: it is a different artifact, and text you cropped
+  out of a slide can still sit in the page it was rendered from.
+
+If the deck is going outside the organisation, have the user confirm the artifact before
+it is sent. You cannot un-share a deck.
+
+## PDF export
+
+PDF export lives in the companion **slides-to-pdf** skill (self-contained; distributed
+alongside this one). In short: build an export copy with absolute image paths and hidden
+nav chrome, screenshot every slide at 2x, print a page-per-slide wrapper to PDF, and
+verify by rendering the PDF back to images with pypdfium2, since headless Chrome cannot
+rasterize a local PDF and image pages can be silently blank. Use that skill's recipe as
+written; do not improvise a shortcut here.