@forwardimpact/outpost 3.11.0 → 3.12.1

package/templates/.claude/skills/deck-create/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: deck-create
-description: Generate PDF slide decks from user requests using Playwright to render HTML slides to PDF. Use when the user asks to create a presentation, slide deck, or pitch deck. Pulls context from the knowledge base for company info, project details, and people.
-compatibility: Requires Node.js installed. Playwright is installed on first use.
+description: Generate PDF slide decks from user requests. Playwright renders the HTML slides to PDF. Use when the user asks to create a presentation, slide deck, or pitch deck. Pulls context from the knowledge base for company info, project details, and people.
+compatibility: Requires Node.js. The skill installs Playwright on first use.
 ---
 
 # Create Presentations
 
-Generate PDF slide decks from user requests. Uses Playwright to render HTML
-slides to PDF. Can pull context from the knowledge base for company info,
+Generate PDF slide decks from user requests. Playwright renders the HTML slides
+to PDF. This skill can pull context from the knowledge base for company info,
 project details, and people.
 
 ## Trigger
@@ -17,7 +17,7 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 ## Prerequisites
 
 - Node.js installed
-- Playwright will be installed on first use
+- The skill installs Playwright on first use
 
 ## Inputs
 
@@ -34,7 +34,7 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 
 1. Check `Knowledge/` for relevant context about the company, product, team,
    etc.
-2. Ensure Playwright is installed:
+2. Make sure Playwright is installed:
    `bun install playwright && bunx playwright install chromium`
 3. Create an HTML file at `/tmp/outpost-presentation.html` with slides
    (1280x720px each)
@@ -56,24 +56,24 @@ Defaults: input = `/tmp/outpost-presentation.html`, output =
 
 ## PDF Rendering Rules
 
-**These prevent rendering issues in PDF:**
+**These rules prevent problems when the PDF renders:**
 
-1. **No layered elements** — Style content elements directly, no separate
-   background elements
+1. **No layered elements** — Style content elements directly. Do not add
+   separate background elements
 2. **No box-shadow** — Use borders instead: `border: 1px solid #e5e7eb`
-3. **Bullets via CSS only** — Use `li::before` pseudo-elements
-4. **Content must fit** — Slides are 1280x720px with 60px padding. Safe area is
-   1160x600px. Use `overflow: hidden`
+3. **Bullets with CSS only** — Use `li::before` pseudo-elements
+4. **Content must fit** — Slides are 1280x720px with 60px padding. The safe area
+   is 1160x600px. Use `overflow: hidden`
 5. **No footers or headers** — No fixed/absolute positioned footer/header
    elements
 
 ## Interactive HTML Decks — Navigation & Event Standards
 
-When the deck is delivered as a **standalone interactive HTML file** (animated /
-navigable in the browser) rather than a static PDF, keep input handling
-deliberately minimal. Rich event handling fights with two things the user needs:
-selecting/copying text on a slide, and typing into overlay tools (e.g. the
-`slide-annotator.js` review overlay).
+You can deliver the deck as a **standalone interactive HTML file**
+(animated / navigable in the browser) instead of a static PDF. Then keep the
+input handlers deliberately minimal. Rich event handlers fight with two things
+the user needs: selection and copy of text on a slide, and text entry into
+overlay tools (e.g. the `slide-annotator.js` review overlay).
 
 **Required:**
 
@@ -83,13 +83,13 @@ selecting/copying text on a slide, and typing into overlay tools (e.g. the
    navigate (e.g. "click left/right third"). They fire on the mouse-up that ends
    a text-selection drag and jump the slide unexpectedly.
 3. **No spacebar, PageUp/PageDown, or other global key bindings.** Space
-   conflicts with typing in overlay inputs; the rest are redundant and
-   surprising.
+   conflicts when the user types into an overlay input. The rest are redundant
+   and surprising.
 4. **A progress indicator may be clickable**, but it must live in the
    footer/chrome and never overlap slide content.
 5. **Expose `window.deckGoto(index)`** (0-based) right after the slide-show
-   function, so review/overlay tools can jump to a slide without simulating
-   clicks or keys:
+   function, so review/overlay tools can jump to a slide without a simulated
+   click or key:
 
         function go(n) { /* ...show slide n... */ }
         window.deckGoto = go;
@@ -97,20 +97,20 @@ selecting/copying text on a slide, and typing into overlay tools (e.g. the
 6. **Keep the hint honest** — the on-screen nav hint should read
    `← → to navigate` (don't advertise click/space).
 7. **Use stable structural hooks.** Make each slide one element with class
-   `.slide`, and put the slide-number label (if any) in a `.slide-num` element.
+   `.slide`. Put the slide-number label (if any) in a `.slide-num` element.
    The review overlay defaults to these selectors to detect and index slides.
 
-These rules keep decks compatible with the **`deck-review`** skill, which
+These rules keep decks compatible with the **`deck-review`** skill. That skill
 installs the `slide-annotator.js` review overlay (highlight text on a slide →
-sidecar JSON of feedback that an agent acts on). After producing an interactive
-HTML deck, you can offer to run `deck-review` to make it reviewable; see that
-skill for the install steps and the sidecar JSON schema.
+sidecar JSON of feedback that an agent acts on). After you produce an
+interactive HTML deck, you can offer to run `deck-review` to make it reviewable.
+See that skill for the install steps and the sidecar JSON schema.
 
 ## Constraints
 
 - Always use the knowledge base for context when available
-- Output to `~/Desktop/presentation.pdf` unless user specifies otherwise
-- Keep slides clean and readable — max 5-6 bullet points per slide
-- Use consistent styling throughout
+- Output to `~/Desktop/presentation.pdf` unless the user specifies otherwise
+- Keep slides clean and readable (max 5-6 bullet points per slide)
+- Use the same styles throughout
 - For interactive HTML decks, follow the navigation & event standards above
-  (arrow-keys-only; no click-to-advance or spacebar)
+  (arrow-keys-only, no click-to-advance or spacebar)

package/templates/.claude/skills/deck-create/references/slide.css

@@ -1,12 +1,12 @@
-/* Required CSS for HTML slide decks rendered to PDF via Playwright.
+/* Required CSS for HTML slide decks that Playwright renders to PDF.
  *
  * Include this in the <style> block of /tmp/outpost-presentation.html.
- * See scripts/convert-to-pdf.mjs for the rendering script.
+ * See scripts/convert-to-pdf.mjs for the script that renders them.
  *
- * PDF rendering rules:
+ * Rules for PDF output:
  * - No layered elements — style content directly, no separate backgrounds
  * - No box-shadow — use borders: border: 1px solid #e5e7eb
- * - Bullets via CSS only — use li::before pseudo-elements
+ * - Bullets with CSS only — use li::before pseudo-elements
  * - Content must fit — safe area is 1160x600px (1280x720 minus 60px padding)
  * - No footers or headers — no fixed/absolute positioned elements
  */

package/templates/.claude/skills/deck-create/scripts/convert-to-pdf.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env bun
 /**
- * Convert HTML slides to PDF using Playwright.
+ * Convert HTML slides to PDF with Playwright.
  *
- * Renders an HTML file containing slide markup (1280x720px per slide) into a
- * PDF document. Each slide is sized to exactly 1280x720 pixels with background
- * colours and images preserved. Defaults to reading from /tmp and writing to
- * ~/Desktop when no arguments are given.
+ * This script renders an HTML file that contains slide markup (1280x720px per
+ * slide) into a PDF document. Each slide measures exactly 1280x720 pixels. The
+ * PDF keeps the background colours and the images. Without arguments, the
+ * script reads from /tmp and writes to ~/Desktop.
  *
  * Requires: bun install playwright && bunx playwright install chromium
  */
@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 
-const HELP = `convert-to-pdf — render HTML slides to PDF via Playwright
+const HELP = `convert-to-pdf — render HTML slides to PDF with Playwright
 
 Usage: bun scripts/convert-to-pdf.mjs [input.html] [output.pdf] [-h|--help]
 

package/templates/.claude/skills/deck-review/SKILL.md

@@ -1,34 +1,34 @@
 ---
 name: deck-review
-description: Add a lightweight text-highlight review overlay to an HTML deck. Lets you highlight text on slides and capture feedback as a sidecar JSON (with source line/column + context) that an agent can act on in small iterations. Use when the user asks to add review/annotation/highlight/comment capability to a deck, make a deck "reviewable", or wants to mark up slides for revision. Pairs with the deck-create skill.
+description: Add a lightweight text-highlight review overlay to an HTML deck. Lets you highlight text on slides and capture feedback as a sidecar JSON. The JSON carries the source line, column, and context, so an agent can act on it in small iterations. Use when the user asks to add review/annotation/highlight/comment capability to a deck, make a deck "reviewable", or wants to mark up slides for revision. Pairs with the deck-create skill.
 compatibility: Standalone HTML deck opened in a Chromium-based browser (Chrome/Edge). No build step, no server, no dependencies.
 ---
 
 # Add a Review Overlay to a Deck
 
-Install the self-contained `slide-annotator.js` overlay onto an HTML deck so the
-user can **highlight text on a slide and save the feedback as a sidecar JSON**.
-Each annotation carries a robust anchor (exact text + surrounding context +
-slide) and, once the folder is connected, the resolved
-**source line, column and context lines** — so an agent can locate and edit the
-exact text in small iterations.
+Install the self-contained `slide-annotator.js` overlay onto an HTML deck. The
+user can then **highlight text on a slide and save the feedback as a sidecar
+JSON**. Each annotation carries a robust anchor (exact text + the context around
+it + slide). After you connect the folder, the annotation also carries the
+resolved **source line, column and context lines**. An agent can then locate and
+edit the exact text in small iterations.
 
-This is the companion to **`deck-create`**: decks produced by `deck-create`
-already follow the navigation/structure standards this overlay needs, and this
-overlay is designed to drop onto them with one script tag.
+This is the companion to **`deck-create`**. Decks from `deck-create` already
+follow the navigation and structure standards this overlay needs. You drop the
+overlay onto them with one script tag.
 
 ## Trigger
 
 Run when the user asks to add review / annotation / highlight / comment / markup
-capability to a deck, "make this deck reviewable", or to set up a feedback loop
-on slides.
+capability to a deck. Run it also when the user says "make this deck
+reviewable" or asks to set up a feedback loop on slides.
 
 ## Inputs
 
 - Path to the target deck `.html` file (ask, or default to the most recently
   edited `*.html` in `Drafts/`).
-- The bundled tool at `assets/slide-annotator.js` (this skill's own copy is the
-  source of truth — edit it here, then re-install to update decks).
+- The bundled tool at `assets/slide-annotator.js`. This skill's own copy is the
+  source of truth. Edit it here, then re-install it to update decks.
 
 ## Outputs
 
@@ -40,7 +40,8 @@ on slides.
 
 ## Install steps
 
-1. **Resolve the deck path** (absolute). Confirm it is an HTML deck, not a PDF.
+1. **Resolve the deck path** (absolute). Confirm it is an HTML deck. Confirm it
+   is not a PDF.
 
 2. **Check compatibility** (see *Compatibility contract* below). The two things
    that matter:
@@ -48,18 +49,18 @@ on slides.
      (default `.slide`). If the deck uses a different class, note it for step 4.
    - **Navigation hook** — the deck exposes `window.deckGoto(index)` (0-based).
      If it has a slideshow function (e.g. `go(n)`) but no hook, add one line
-     right after it: `window.deckGoto = go;`. Without it the overlay still works
-     (the panel's *Go* button falls back to `scrollIntoView`), but it can't jump
-     to a hidden slide precisely.
-   - Optionally a slide-number label element (default `.slide-num`) for nicer
-     labels in the panel — purely cosmetic.
+     right after it: `window.deckGoto = go;`. Without it the overlay still
+     works. The panel's *Go* button falls back to `scrollIntoView`. But the
+     overlay can't jump to a hidden slide precisely.
+   - A slide-number label element (default `.slide-num`) is optional. It gives
+     nicer labels in the panel. It is purely cosmetic.
 
 3. **Install the tool**: copy this skill's `assets/slide-annotator.js` into the
-   **same directory as the deck**. Resolve `~` to `$HOME`; pass the Write/copy a
+   **same directory as the deck**. Resolve `~` to `$HOME`. Pass the Write/copy a
    full path.
 
-4. **Inject the script tag** immediately before `</body>` (idempotent — skip if
-   a `slide-annotator` script tag is already present):
+4. **Inject the script tag** immediately before `</body>`. The step is
+   idempotent. Skip it if a `slide-annotator` script tag is already present:
 
    ```html
    <!-- Review overlay: highlight text on a slide → sidecar JSON. Self-contained, optional. -->
@@ -72,8 +73,8 @@ on slides.
    differs from the defaults. If there are no slide elements at all, the tool
    treats the whole `<body>` as one container.
 
-5. **Tell the user how to use it** (see *Using the overlay*). Do **not** add any
-   other dependency or framework — the tool is plain JS and must stay that way.
+5. **Tell the user how to use it** (see *Use the overlay*). Do **not** add any
+   other dependency or framework. The tool is plain JS and must stay that way.
 
 ## Compatibility contract (must match `deck-create`)
 
@@ -82,38 +83,38 @@ follow:
 
 | Convention | Default | Why the overlay needs it |
 |---|---|---|
-| One element per slide with a stable class | `.slide` | locate which slide a highlight is on; index slides |
+| One element per slide with a stable class | `.slide` | locate which slide a highlight is on, and index the slides |
 | Slide-number label element (optional) | `.slide-num` | human-friendly panel labels |
 | Navigation hook | `window.deckGoto(index)` (0-based) | panel "Go" jumps to the right slide |
-| Arrow-keys-only navigation, **no** click-to-advance / spacebar | — | text selection + typing in the overlay must not move slides |
+| Arrow-keys-only navigation, **no** click-to-advance / spacebar | — | text selection and typed input in the overlay must not move slides |
 
-If a deck violates the last row (has click-to-advance), the overlay's click
-guard only suppresses the click that ends a text-selection drag, so it degrades
-gracefully — but the correct fix is to make the deck arrow-keys-only per
+A deck can violate the last row and have click-to-advance. The overlay's click
+guard then suppresses only the click that ends a text-selection drag, so it
+degrades gracefully. The correct fix is to make the deck arrow-keys-only, per
 `deck-create`'s *Navigation & Event Standards*.
 
-## Using the overlay (tell the user)
+## Use the overlay (tell the user)
 
-1. Open the deck in Chrome and click **✎ Review** (bottom-left).
-2. **Select text** on a slide → a popover lets you add an optional note →
+1. Open the deck in Chrome. Click **✎ Review** (bottom-left).
+2. **Select text** on a slide. A popover lets you add an optional note. Click
    **Add**. The highlight appears and **autosaves to `localStorage`**
    immediately.
 3. Click **Connect folder** once and pick the deck's folder. From then on
-   **Save** writes a real `‹deck›.annotations.json` next to the deck, and the
-   tool reads the deck's own source to fill in
-   **source line / column / context** for each highlight. (If the browser blocks
-   folder access on `file://`, **Save** downloads the JSON instead — move it
-   next to the deck.)
-4. The connected folder is **remembered across reloads** (the directory handle
-   is stored in IndexedDB, keyed per deck). After a reload the tool reconnects
-   silently if the browser still grants access; otherwise the button reads
-   **Reconnect folder** and a single click re-grants permission without
-   re-picking the folder. (Browsers require a user gesture to re-grant, so the
-   one click can't be avoided; clearing site data forgets the folder.)
-5. Navigation while reviewing is the deck's normal **← / →** (the overlay's own
-   keystrokes never leak to the deck).
-
-## Acting on the feedback (the review loop)
+   **Save** writes a real `‹deck›.annotations.json` next to the deck. The tool
+   also reads the deck's own source to fill in
+   **source line / column / context** for each highlight. If the browser blocks
+   folder access on `file://`, **Save** downloads the JSON instead. Move it next
+   to the deck.
+4. The tool **remembers the connected folder across reloads**. It stores the
+   directory handle in IndexedDB, keyed per deck. After a reload the tool
+   reconnects silently if the browser still grants access. If not, the button
+   reads **Reconnect folder**, and a single click re-grants permission without a
+   new folder pick. Browsers require a user gesture to re-grant, so you can't
+   avoid the one click. If you clear site data, the tool forgets the folder.
+5. During a review you navigate with the deck's normal **← / →**. The overlay's
+   own keystrokes never leak to the deck.
+
+## Act on the feedback (the review loop)
 
 When the user says "work the annotations":
 
@@ -121,12 +122,13 @@ When the user says "work the annotations":
 2. For each `status: "open"` annotation, locate the text in the deck source:
    - Prefer `source.line` / `source.column` when present.
    - Otherwise search the source for `quote` (disambiguate with `prefix` /
-     `suffix`, scoped to `slideId`). The quote is the underlying DOM text, so it
-     matches the source even across inline tags / entities.
-3. Make the edit, honoring the user's `note`.
+     `suffix`, scoped to `slideId`). The quote is the underlying DOM text, so
+     it matches the source even across inline tags / entities.
+3. Make the edit. Honor the user's `note`.
 4. Optionally set the annotation's `status` to `"done"` in the JSON so the panel
    shows it resolved.
-5. Re-render / re-screenshot to verify, then report what changed per annotation.
+5. Re-render or re-screenshot to verify. Then report what changed for each
+   annotation.
 
 ### Sidecar JSON schema
 
@@ -150,17 +152,17 @@ When the user says "work the annotations":
 }
 ```
 
-## Removing the overlay (for final delivery)
+## Remove the overlay (for final delivery)
 
 To hand off a clean presentation, delete the injected
 `<script src="slide-annotator.js" …>` line and the `slide-annotator.js` file.
-Leaving the `window.deckGoto = go;` line in the deck is harmless.
+The `window.deckGoto = go;` line can stay in the deck. It is harmless.
 
 ## Constraints
 
-- Keep `slide-annotator.js` **dependency-free and host-agnostic** — it must work
-  on any static HTML page, not just `deck-create` output.
+- Keep `slide-annotator.js` **dependency-free and host-agnostic**. It must work
+  on any static HTML page. `deck-create` output is not the only target.
 - Edit the tool **here** (`assets/slide-annotator.js`) as the source of truth,
   then re-install onto decks. Don't fork per-deck copies with divergent
   behavior.
-- Never auto-send or upload annotations anywhere — the sidecar JSON stays local.
+- Never auto-send or upload annotations anywhere. The sidecar JSON stays local.

package/templates/.claude/skills/deck-review/assets/slide-annotator.js

@@ -7,20 +7,21 @@
  *             data-slide-selector=".slide"
  *             data-label-selector=".slide-num"></script>
  *
- * Click the “✎ Review” button (bottom-left), select text on a slide, optionally
- * add a note, and Add. Annotations autosave to localStorage immediately. Click
- * “Connect folder” once to (a) write a real sidecar JSON next to the page and
- * (b) resolve each highlight to its SOURCE line/column + context lines by
- * reading the page’s own source file. No build step, no server, no deps.
+ * Click the “✎ Review” button (bottom-left). Select text on a slide. Add an
+ * optional note. Then click Add. Annotations autosave to localStorage
+ * immediately. Click “Connect folder” once. The tool then writes a real
+ * sidecar JSON next to the page. It also reads the page’s own source file, so
+ * it resolves each highlight to its SOURCE line/column + context lines. The
+ * tool needs no build step, no server, and no dependencies.
  *
- * The connected folder is remembered across reloads (the directory handle is
- * stored in IndexedDB). On reload it reconnects silently if the browser still
- * grants permission; otherwise the button reads “Reconnect folder” and one
- * click re-grants access without re-picking the folder.
+ * The tool remembers the connected folder across reloads. It stores the
+ * directory handle in IndexedDB. On reload it reconnects silently if the
+ * browser still grants permission. If not, the button reads “Reconnect
+ * folder”. One click then re-grants access without a new folder pick.
  *
- * Optional host hook: if the page defines `window.deckGoto(index)` the panel’s
- * “Go” buttons will navigate to the right slide. Without it, the tool still
- * works (it falls back to scrollIntoView).
+ * Optional host hook. If the page defines `window.deckGoto(index)`, the
+ * panel’s “Go” buttons navigate to the right slide. Without it, the tool
+ * still works (it falls back to scrollIntoView).
  *
  * SIDECAR JSON SCHEMA (what an agent reads to act on the feedback):
  * {
@@ -120,7 +121,8 @@
 ::highlight(sa-all){background:rgba(255,221,0,.45);text-decoration:underline;text-decoration-color:#caا}\
 ::highlight(sa-active){background:rgba(255,0,110,.35)}\
 @media print{.sa-ui{display:none!important}}";
-  // (one stray glyph above is harmless inside a CSS comment-free value; replaced below)
+  // The stray glyph above is harmless in a comment-free CSS value.
+  // The next line replaces it.
   css = css.replace("#caا", "#b38f00");
   var styleEl = document.createElement("style");
   styleEl.textContent = css;
@@ -160,13 +162,14 @@
   ui.note = ui.pop.querySelector("textarea");
   var onlyThisSlide = false;
 
-  // Keep the tool's own keystrokes from leaking to the host page (e.g. a deck's
-  // Space / arrow-key slide navigation) while typing a note or using a panel
-  // button. We stop propagation in the BUBBLE phase, so: (a) our capture-phase
-  // Esc handler has already run, and (b) the default action — typing the
-  // character, moving the caret — still happens. Scoped to the tool's own UI,
-  // so arrow/Space navigation still works when focus is on the page itself.
-  // Independent of any host: we never touch the host's handlers, just our own.
+  // Keep the tool's own keystrokes away from the host page. One example is a
+  // deck's Space and arrow-key slide navigation. This applies while the user
+  // types a note or uses a panel button. We stop propagation in the BUBBLE
+  // phase. So our capture-phase Esc handler already ran. The default action
+  // also still happens. The character appears and the caret moves. We scope
+  // this to the tool's own UI. Arrow and Space navigation still works when
+  // focus is on the page itself. This works with any host. We never touch
+  // the host's handlers, only our own.
   [ui.fab, ui.banner, ui.panel, ui.pop].forEach(function (node) {
     ["keydown", "keyup", "keypress"].forEach(function (type) {
       node.addEventListener(type, function (e) { e.stopPropagation(); });
@@ -210,10 +213,11 @@
     else if (review) { toggle(false); e.stopPropagation(); }
   }, true);
 
-  // In review mode, swallow ONLY the click that ends a text-selection drag, so a
-  // host with click-to-advance can't navigate out from under the highlight. Plain
-  // clicks (with no active selection) pass through untouched — footer dots, links
-  // and buttons keep working. Non-invasive and host-agnostic.
+  // In review mode, swallow ONLY the click that ends a text-selection drag.
+  // A host with click-to-advance then cannot navigate out from under the
+  // highlight. Plain clicks (with no active selection) pass through
+  // untouched. Footer dots, links and buttons keep working. The tool does
+  // not intrude, and it works with any host.
   function clickSuppressor(e) {
     if (e.target.closest(".sa-ui")) return;
     var sel = window.getSelection();
@@ -252,9 +256,10 @@
     var off = offsets(slide, range);
     var text = slide.textContent;
     var slides = allSlides();
-    // Anchor on the underlying DOM text (text.slice), NOT Selection.toString():
-    // the latter applies text-transform (e.g. uppercase headings) and would no
-    // longer match the source or the slide's textContent.
+    // Anchor on the underlying DOM text (text.slice). Do NOT use
+    // Selection.toString(). It applies text-transform (e.g. uppercase
+    // headings). The result would no longer match the source or the slide's
+    // textContent.
     var storedQuote = text.slice(off.start, off.end) || quote;
 
     pending = {
@@ -394,7 +399,7 @@
     if (!list.length) {
       ui.list.innerHTML = '<div class="sa-empty">' +
         (onlyThisSlide ? "No annotations on this slide." :
-        "No annotations yet.<br><br>Select text on a slide to highlight it. Highlights autosave locally; click <b>Connect folder</b> to write the sidecar JSON and capture source line numbers.") +
+        "No annotations yet.<br><br>Select text on a slide to highlight it. Highlights autosave locally. Click <b>Connect folder</b> to write the sidecar JSON and capture source line numbers.") +
         '</div>';
       return;
     }
@@ -417,7 +422,7 @@
   function currentSlideIndex() {
     var slides = allSlides();
     for (var i = 0; i < slides.length; i++) if (slides[i].classList.contains("active")) return i;
-    // else the slide most centered in viewport
+    // else the slide most centered in the viewport
     var best = 0, bestD = Infinity, cx = window.innerWidth / 2, cy = window.innerHeight / 2;
     slides.forEach(function (s, i) {
       var r = s.getBoundingClientRect();
@@ -442,12 +447,13 @@
     if (ui.count) ui.count.textContent = state.annotations.length;
   }
 
-  /* Persist the connected directory handle across reloads. FileSystemHandles are
-   * structured-cloneable, so they live in IndexedDB (localStorage is strings
-   * only). Re-granting read/write permission after a reload needs a user
-   * gesture, so a remembered folder reconnects with one click via the same
-   * "Connect folder" button rather than the full directory picker. Keyed by
-   * cfg.target so distinct decks in a folder don't clobber each other. */
+  /* Persist the connected directory handle across reloads. FileSystemHandles
+   * are structured-cloneable, so they live in IndexedDB (localStorage holds
+   * strings only). A re-grant of read/write permission after a reload needs
+   * a user gesture. So a remembered folder reconnects with one click through
+   * the same "Connect folder" button. It does not open the full directory
+   * picker. The key is cfg.target, so distinct decks in a folder do not
+   * clobber each other. */
   var IDB_NAME = "slide-annotator", IDB_STORE = "handles";
   function idbOpen() {
     return new Promise(function (resolve, reject) {
@@ -484,16 +490,17 @@
       : rememberedHandle ? "Reconnect folder" : "Connect folder";
   }
 
-  // Adopt a (freshly picked or re-granted) handle: link source, load any
-  // sidecar, and remember it for next time. Shared by connect and restore.
+  // Adopt a freshly picked or re-granted handle. Link the source, load any
+  // sidecar, and remember the handle for next time. Both connect and restore
+  // call this.
   async function adoptFolder(handle) {
     dirHandle = handle;
-    // read page source → enables source line/column resolution
+    // read the page source → the tool can then resolve source line/column
     try {
       var fh = await dirHandle.getFileHandle(cfg.target);
       sourceText = await (await fh.getFile()).text();
       state.annotations.forEach(function (a) { a.source = locateInSource(a); });
-    } catch (e) { sourceText = null; setStatus("Connected, but '" + cfg.target + "' not found in folder — line numbers unavailable."); }
+    } catch (e) { sourceText = null; setStatus("Connected, but the folder has no '" + cfg.target + "'. Line numbers are unavailable."); }
     // load an existing sidecar if present
     try {
       var sh = await dirHandle.getFileHandle(SIDECAR);
@@ -503,12 +510,13 @@
     rememberedHandle = null;
     updateConnectLabel();
     persistLocal(); renderPanel(); renderHighlights();
-    setStatus("Connected. Saving to " + SIDECAR + (sourceText ? " · source linked" : ""));
+    setStatus("Connected. Saves to " + SIDECAR + (sourceText ? " · source linked" : ""));
   }
 
   async function connectFolder() {
-    // Prefer a folder remembered from a prior session: re-granting permission is
-    // a single click (this click IS the required user gesture), no picker.
+    // Prefer a folder remembered from a prior session. A permission re-grant
+    // takes a single click (this click IS the required user gesture). The
+    // picker does not open.
     if (rememberedHandle) {
       try {
         var perm = await rememberedHandle.requestPermission({ mode: "readwrite" });
@@ -524,10 +532,11 @@
     }
   }
 
-  // On load, try to restore a previously connected folder. queryPermission needs
-  // no gesture; if it's still "granted" we reconnect silently. If it's "prompt",
-  // we keep the handle so the next "Connect folder" click reconnects with one
-  // grant dialog (no picker). Handles cleared/denied storage are ignored.
+  // On load, try to restore a previously connected folder. queryPermission
+  // needs no gesture. If it is still "granted", we reconnect silently. If it
+  // is "prompt", we keep the handle. The next "Connect folder" click then
+  // reconnects with one grant dialog (no picker). We ignore a handle from
+  // cleared or denied storage.
   function restoreFolder() {
     idbGet(cfg.target).then(function (handle) {
       if (!handle || typeof handle.queryPermission !== "function") return;
@@ -535,7 +544,7 @@
         if (perm === "granted") { adoptFolder(handle); }
         else {
           rememberedHandle = handle; updateConnectLabel();
-          if (review) setStatus("Folder '" + cfg.target + "' remembered — click Reconnect folder.");
+          if (review) setStatus("Folder '" + cfg.target + "' remembered. Click Reconnect folder.");
         }
       }).catch(function () {});
     });
@@ -553,7 +562,7 @@
       } catch (e) { setStatus("Disk write failed (" + e.name + "). Downloaded instead."); }
     }
     download(SIDECAR, json);
-    setStatus("Downloaded " + SIDECAR + " — move it next to the deck.");
+    setStatus("Downloaded " + SIDECAR + ". Move it next to the deck.");
   }
 
   async function loadDisk() {
@@ -669,7 +678,7 @@
     // Supply page source to resolve source line/column without the folder picker.
     setSource: function (text) { sourceText = text; state.annotations.forEach(function (a) { a.source = locateInSource(a); }); persistLocal(); renderPanel(); },
     get state() { return state; },
-    // for automation/testing:
+    // for automation and tests:
     _capture: captureSelection,
     _confirm: function (note) { if (pending) { ui.note.value = note || ""; confirmPending(); } }
   };