npm - @forwardimpact/outpost - Versions diffs - 3.12.0 → 3.13.0 - Mend

@forwardimpact/outpost 3.12.0 → 3.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (129) hide show

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

@@ -1,13 +1,16 @@
 ---
 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,
+Write tier: `0-Draft`
+Frontmatter: none
+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,12 +20,12 @@ 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
 - User's description of the presentation
-- `Knowledge/` — optional context about company, product, team, projects
+- `3-Team/` — optional context about company, product, team, projects
 ## Outputs
@@ -32,9 +35,9 @@ Run when the user asks to create a presentation, slide deck, or pitch deck.
 ## Workflow
-1. Check `Knowledge/` for relevant context about the company, product, team,
+1. Check `3-Team/` 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)
@@ -54,26 +57,79 @@ The conversion script accepts optional arguments:
 Defaults: input = `/tmp/outpost-presentation.html`, output =
 `~/Desktop/presentation.pdf`
+## Source Annotations — REQUIRED
+Decks are condensed views of source documents (knowledge-base notes, drafts
+under `0-Draft/`, project docs). As a deck is iterated on, improvements get
+**back-ported** to those sources. So every deck must record what maps where.
+Embed the mapping as HTML comments (invisible in the browser and in the PDF).
+A deck with untraceable content is incomplete.
+### Comment syntax
+    <!-- src: <relative-path>#<heading> -->
+    <!-- src-note: <free text> -->
+- `src:` maps the **next element** (and everything inside it) to a source file
+  or section. A nested `src:` overrides its parent for that subtree.
+- The path is **relative to the deck file itself**. The heading is the exact
+  markdown heading text without the leading `#`-marks, as in an Obsidian
+  `[[file#heading]]` link. Omit `#<heading>` to map to the whole file.
+- `src: #<heading>` (path omitted) inherits the path from the nearest
+  **enclosing** `src:`. Use this for repeated sections within one annotated
+  slide, so the doc path is stated once per slide.
+- `src-note:` records exceptions and nuances in prose: content synthesized
+  from multiple sources, deliberately omitted source fields, or deviations
+  from the field conventions.
+### Placement rules
+1. **Legend first.** Put one legend comment right after `<body>`. It explains
+   the syntax and the deck's field conventions (see below). Never nest a
+   literal `<!--` inside it — write the syntax without comment delimiters.
+2. **One `src:` per slide**, mapping it to its primary source document, placed
+   immediately before the `<section class="slide">`.
+3. **One `src:` per repeated content block** (a goal, a priority, a feature
+   card…), mapping it to the source section heading, placed immediately
+   before the block's opening tag.
+4. **Field conventions instead of per-paragraph comments.** When a block's
+   inner elements map 1:1 to labelled source fields (e.g. `.card.why p` ↔
+   `**Why it matters:**`), declare that mapping **once in the legend**.
+   Annotate individual elements only when they deviate — then use `src-note:`.
+5. **Synthesized content** (title pages, summary slides that condense several
+   sources) gets a `src-note:` saying what it draws on.
+### Authoring for back-portability
+- Keep deck headings **verbatim from the source headings** where possible.
+  The anchor then doubles as an integrity check.
+- Keep stable IDs from the sources (A1, B2, goal numbers) visible in the deck
+  content, so items self-identify even if comments are stripped.
+- When back-porting: treat the deck text as the edited version of the mapped
+  source field. Apply the change to the source file at the given heading.
+  Carry the substance back, not the deck's condensed formatting. Find all
+  annotations with `rg '<!-- src' <deck>.html`.
 ## 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 +139,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 +153,22 @@ 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
+- Always embed source annotations (`src:` / `src-note:` comments + legend)
+  that map deck sections to their source documents — see Source Annotations
+- 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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,34 +1,37 @@
 ---
 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.
+Write tier: `0-Draft`
+Frontmatter: none
-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.
+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 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).
+  edited `*.html` in `0-Draft/`).
+- 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 +43,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 +52,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 +76,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 +86,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 +125,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 +155,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.