portable-agent-layer 0.29.1 → 0.30.1

package/assets/skills/consulting-report/tools/generate-pdf.ts

@@ -251,7 +251,7 @@ async function renderSections(
     const tag = depth === 1 ? "h1" : depth === 2 ? "h2" : "h3";
     out.push(`<${tag} id="${s.id}">${escapeHtml(s.title)}</${tag}>`);
     out.push(htmlBody as string);
-    if (s.subsections && s.subsections.length) {
+    if (s.subsections?.length) {
       out.push(await renderSections(s.subsections, contentDir, depth + 1));
     }
   }
@@ -273,10 +273,9 @@ function renderToc(sections: Section[]): string {
 }
 
 function renderCover(r: ConsultingReport, brand: Brand): string {
-  const logo =
-    brand.logoPath && brand.logoPath.length
-      ? `<img class="logo" src="file://${brand.logoPath}" alt="${escapeHtml(brand.businessName)}">`
-      : "";
+  const logo = brand.logoPath?.length
+    ? `<img class="logo" src="file://${brand.logoPath}" alt="${escapeHtml(brand.businessName)}">`
+    : "";
   const brandLabel = brand.brandLabel || `${brand.businessName} Assessment`;
   return `
 <div class="cover">

package/assets/skills/create-skill/SKILL.md

@@ -1,32 +1,69 @@
 ---
 name: create-skill
-description: Scaffold a new PAL skill from a description. Use when creating a new skill, adding a capability, or building a custom command.
-argument-hint: <skill description>
+description: Scaffold a new PAL skill from a description. Use when creating a new skill, adding a capability, or building a custom command. Enforces general, assistant-facing, personally-clean skill writing.
+argument-hint: <skill name> <skill description>
 ---
 
-When the user invokes /create-skill <name> <description>:
+## What makes a good PAL skill
 
-1. Create a new markdown file in the skills/ directory
-2. Use this template:
+Before writing any skill, internalize these three rules. A skill that violates them gets re-written, not committed.
+
+1. **Pointed at the assistant, not the user.** A skill is *instructions you (the assistant) follow*. Write in second person addressing yourself ("read X", "extract Y", "output Z"). Prescriptive verbs, deterministic flow. It is **not** a user tutorial, marketing blurb, or README. The user reads `README.md`; you read `SKILL.md`.
+
+2. **Zero personal information.** No usernames, real names, employer names, project codenames, dataset names, hostnames, absolute home paths (`C:\Users\someone\…`), email addresses, or anecdotes about the author's own work. A skill must be reusable by any user. If the rule is "don't expand `~` on Windows cmd," that is the rule — don't add "because $username's primary shell is cmd." Personal context belongs in the user's private memory, never in the skill body.
+
+3. **General, not user-specific.** A skill describes a *workflow class* (e.g. "build a deck," "summarize a PDF," "lint a python file"), not a single user's habits. Use placeholders (`<deck-dir>`, `<input.pdf>`), not hardcoded paths. If the workflow only makes sense for one person, it is a memory entry or a personal hook, not a skill.
+
+## Skill anatomy
 
 ```markdown
 ---
-name: <name>
-description: <one-line description>
+name: <slug>                           # the slash-command name; lowercase-kebab
+description: <one sentence trigger>    # WHEN to invoke (used by the dispatcher), not WHAT it does
+argument-hint: <args>                  # optional; how the user passes input
 ---
 
-When the user invokes /<name> <args>:
+## Overview / Workflow
+
+Numbered steps the assistant follows on invocation. Each step is concrete:
+read this file, run this command, ask this question, output this format.
+
+## Output format
 
-1. <step>
-2. <step>
-3. <step>
+Exactly what the assistant returns to the user. Specify structure if the
+caller will parse it; specify tone if the caller is a human.
 
-Output format:
-- <format specification>
+## When to use / Do NOT use
+
+Two short lists. The "do not" list disambiguates this skill from neighbours
+that would otherwise also match the user's request.
 ```
 
-3. Validate the skill has:
-   - Clear trigger (when to invoke)
-   - Specific steps (not vague)
-   - Defined output format
-   - Reasonable scope (one skill, one job)
+## Workflow when the user invokes `/create-skill <name> <description>`
+
+1. Sanity-check the name and description against the three rules above. If the description leaks personal info ("a skill for me to clean my Notion db"), rewrite it to the general form ("clean a Notion database via the API") before scaffolding.
+2. Create `assets/skills/<name>/SKILL.md` in the repo (the canonical source). The installed copy at `~/.pal/skills/<name>/SKILL.md` may be a junction to this path — verify the user's setup before assuming.
+3. Populate the SKILL.md from the anatomy above. Required fields: `name`, `description`, body sections (Workflow, Output format, When to use). Add `argument-hint` if the skill takes arguments.
+4. If the skill needs runtime tooling (TypeScript, scripts, vendored assets), scaffold a `tools/` subdir alongside SKILL.md. Otherwise leave the skill markdown-only.
+5. Validate before declaring done:
+   - **Trigger clarity** — could a model decide *not* to invoke this skill from the description alone? If yes, tighten the description.
+   - **Step concreteness** — every step has a verb and an object; no "as needed" or "appropriately."
+   - **Output specification** — caller knows what they get back.
+   - **Scope discipline** — one skill, one job. If the skill needs section headers like "for case A do X, for case B do Y," it is two skills.
+   - **Personal-info scan** — grep the new SKILL.md for usernames, real names, absolute home paths, employer or project codenames; remove any hits.
+   - **Generality test** — could a stranger with the same workflow need use this unchanged? If no, factor the user-specific bits into memory.
+
+## Anti-patterns to refuse
+
+- A SKILL.md whose description starts with "I want…" or "My …" — that's a journal entry, not a skill.
+- Hardcoded paths under `C:\Users\<name>\…` or `/Users/<name>/…` — use `~` (and document the cmd.exe `%USERPROFILE%` alternative if Windows is in scope).
+- Brand- or company-specific defaults baked into the skill body. Default brand colors, footer strings, etc. belong in *templates* (user data) or *config*, never in the skill.
+- A description longer than ~30 words, or one that explains the implementation rather than the trigger.
+- Skills that duplicate an existing skill's trigger surface. Read the existing skills index before scaffolding.
+
+## Output format
+
+After scaffolding, return:
+- The path of the created `SKILL.md`.
+- A 2-3 sentence summary of the trigger and workflow.
+- Any anti-pattern violations you caught and corrected during scaffolding (so the user learns the rule).

package/assets/skills/presentation/README.md

@@ -10,12 +10,18 @@ bun ~/.pal/skills/presentation/tools/setup-template.ts
 
 # per deck
 bun ~/.pal/skills/presentation/tools/new-deck.ts ~/decks/my-talk --template my-brand
-$EDITOR ~/decks/my-talk/content.md
-bun ~/.pal/skills/presentation/tools/present.ts ~/decks/my-talk
+$EDITOR ~/decks/my-talk/slides/
+bun ~/.pal/skills/presentation/tools/build.ts ~/decks/my-talk
+# → ./my-talk/my-talk.html (and ./my-talk/my-talk.md — concatenated source)
+# open the .html in your browser; refresh after each rebuild
 ```
 
-Layouts: title, section, content, two-column, image-text, quote, closing, agenda, table, comparison, code.
+Output: `<cwd>/<deck-name>/<deck-name>.html` (self-contained) plus `<deck-name>.md` (concatenated source). Override the parent dir with `--out <dir>`; pass `--force` to overwrite an existing build.
 
-PDF export (v1.1): use the browser's print-to-PDF (`Cmd+P` in the open deck) — Reveal supports `?print-pdf` query mode for clean page breaks. Standalone PDF tooling (decktape) deferred until requested.
+Layouts (14): title, section, content, two-column, image-text, quote, closing, agenda, table, comparison, code, big-stat, metric-grid, pull-quote.
 
-PPTX import (v2): not yet supported.
+Image utilities: `image-rounded`, `image-shadow`, `image-bleed`, `image-duotone`, `image-overlay`.
+
+PDF export: use the browser's print-to-PDF (`Cmd+P` in the open deck) — Reveal supports `?print-pdf` query mode for clean page breaks. Standalone PDF tooling (decktape) deferred until requested.
+
+PPTX import: not yet supported.

package/assets/skills/presentation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: presentation
-description: Build branded HTML presentations from markdown using Reveal.js. Multi-template registry per user (each template = brand color, logo, fonts, footer, aspect). Per-deck workflow: scaffold → edit one markdown file per slide in slides/ → build → present. Output: single self-contained HTML. Use when creating slide decks, talks, workshop slides, lectures, or pitch decks.
-argument-hint: <deck-dir> to build, OR `setup-template` to add a brand template, OR `new <deck-dir> --template <name>` to scaffold a deck, OR `list-templates`, OR `present <deck-dir>`
+description: Build branded HTML presentations from markdown using Reveal.js. Multi-template registry per user (each template = brand color, logo, fonts, footer, aspect). Per-deck workflow: scaffold → edit one markdown file per slide in slides/ → build → present. Output: a `<deck-name>/` subdir with a self-contained HTML and a concatenated markdown sibling. 14 layouts including data-display patterns (big-stat, metric-grid). Use when creating slide decks, talks, workshop slides, lectures, or pitch decks.
+argument-hint: <deck-dir> to build, OR `setup-template` to add a brand template, OR `new <deck-dir> --template <name>` to scaffold a deck, OR `list-templates`
 ---
 
 ## Overview
@@ -66,18 +66,38 @@ Backwards compatible: if `slides/` doesn't exist, the build falls back to a sing
 ### Step 3: Build
 
 ```bash
-bun ~/.pal/skills/presentation/tools/build.ts <deck-dir>
+bun ~/.pal/skills/presentation/tools/build.ts <deck-dir> [--out <dir>] [--force]
 ```
 
-Produces `<deck-dir>/dist/index.html` — a single self-contained HTML file (CSS, JS, fonts, logo all inlined). Email it, USB-stick it, host it anywhere.
+Output goes to `<out>/<deck-name>/`, where `<deck-name>` = the basename of `<deck-dir>`:
+
+- `<deck-name>.md` — the concatenated source (all `slides/*.md` joined with `---` separators), written to disk **first** so you can inspect, diff, or feed it into other tooling.
+- `<deck-name>.html` — the self-contained presentation (CSS, JS, fonts, logo all inlined). Email it, USB-stick it, host it anywhere.
+
+Defaults: `--out` defaults to the current working directory. The `<deck-name>/` subdir is always created — even when `--out` is explicit — so multiple decks can coexist in one folder.
+
+`--force` overwrites an existing build. Without it, the build refuses to clobber `<deck-name>.{md,html}`.
 
-### Step 4: Present
+### Step 3.5 (optional but recommended): Lint with the doctor
 
 ```bash
-bun ~/.pal/skills/presentation/tools/present.ts <deck-dir>
+bun ~/.pal/skills/presentation/tools/doctor.ts <deck-dir> [--strict]
 ```
 
-Builds (if missing or stale) and opens in the default browser. `F` = fullscreen, `S` = speaker notes window, `?` = keyboard shortcuts.
+Catches authoring failures before you ever open the browser:
+
+- Slide missing `data-layout` directive (silently defaults to `content`).
+- Title or subtitle exceeding the visual budget (h1 > 60 chars, h2 > 100).
+- Layout-content mismatch — `comparison` without a `<div class="compare">`, `metric-grid` without `<div class="metrics">`, `two-column` missing column wrappers, etc.
+- Overflow heuristics — `agenda` > 10 items, `content` > 7 bullets, `code` block > 25 lines, `table` > 10 rows, `metric-grid` ≠ 3 metrics.
+- Image referenced via `![](assets/...)` but the file is missing.
+- Layout requirements — `big-stat` without an h1, `quote` / `pull-quote` without a `> blockquote`.
+
+Exit codes: `0` = clean, `1` = errors found (or warnings under `--strict`), `2` = usage error. Run before each build in your iteration loop, or wire it into a pre-commit hook.
+
+### Step 4: Open
+
+Open `<out>/<deck-name>/<deck-name>.html` in your browser. Iterate by editing a slide, re-running the build, and refreshing the tab. Reveal shortcuts: `F` = fullscreen, `S` = speaker notes window, `?` = keyboard shortcuts, `Esc` = overview.
 
 ## Deck folder layout
 
@@ -89,11 +109,11 @@ Builds (if missing or stale) and opens in the default browser. `F` = fullscreen,
 │   ├── 002.md
 │   └── …
 ├── overrides.css           # optional — per-deck CSS overrides
-├── assets/                 # images / videos referenced from slides/*.md
-└── dist/                   # build output (gitignored automatically)
-    └── index.html
+└── assets/                 # images / videos referenced from slides/*.md
 ```
 
+Build output is **never** written inside `<deck-dir>` — it lands in `<out>/<deck-name>/` (default `<cwd>/<deck-name>/`). The scaffolder's `.gitignore` covers the case of running build from inside the deck-dir.
+
 (Legacy: a single `content.md` at the deck root still works — see Step 2.)
 
 ## Content conventions
@@ -137,21 +157,77 @@ Right content.
 ## Questions?
 ```
 
-## Layouts (v1)
+## Layouts (v2 — 14 total)
 
 | Layout | When | Notes |
 |---|---|---|
-| `title` | Cover slide | Big title, optional subtitle, brand logo prominent |
-| `section` | Section divider | Full-bleed accent background, large white title |
+| `title` | Cover slide | Big title, accent rule, brand logo prominent |
+| `section` | Section divider | Full-bleed brand-primary gradient + accent rule |
 | `content` | Default | Title + bullets / paragraphs |
 | `two-column` | Side-by-side content | Use `<div class="col-left">` / `<div class="col-right">` |
 | `image-text` | Image + text combo | Use `<div class="image">` / `<div class="text">` |
-| `quote` | Big italic blockquote | Use markdown `>` syntax |
-| `closing` | Thank-you / Q&A | Mirrors title styling on accent BG |
+| `quote` | Big italic blockquote | Use markdown `>` syntax; oversized accent glyph |
+| `closing` | Thank-you / Q&A | Mirrors title styling on gradient brand BG |
 | `agenda` | Numbered list | Numbered ol, large type, generous whitespace |
-| `table` | Tabular data | Markdown tables, styled with zebra rows + accent header |
-| `comparison` | 2–3 option boxes side-by-side | Use `<div class="compare">` with `<div class="option">` children |
+| `table` | Tabular data | Markdown tables with zebra rows + accent header |
+| `comparison` | 2–3 option boxes side-by-side | Use `<div class="compare">` + `<div class="option">` children |
 | `code` | Code-focused | Triple-backtick fenced blocks with language tag |
+| `big-stat` | One number does the work | `# 87%` + `## caption`. Wrap unit in `<em class="unit">%</em>` |
+| `metric-grid` | 3-up KPI cards | `<div class="metrics">` with `<div class="metric">` children (`.label`, `.value`, `.delta.up\|.down`) |
+| `pull-quote` | Oversized in-line quote | Display-font italic, accent rule on left, em-dashed attribution on a paragraph after |
+
+## Image utility classes
+
+Composable on any `<img>` or wrapper element:
+
+| Class | Effect |
+|---|---|
+| `image-rounded` | `--radius-md` corners |
+| `image-shadow` | `--shadow-lg` drop |
+| `image-bleed` | Fill container, `object-fit: cover` |
+| `image-duotone` | Brand-tinted monochrome via filter chain |
+| `image-overlay` | Adds a brand-gradient scrim from transparent → primary at 75% bottom |
+
+## Design tokens
+
+The skill ships a token system in `theme-base/base.css`. Templates only declare two anchors (`--brand-primary`, `--brand-accent`); the rest derives via `color-mix(in oklch, …)`.
+
+| Token group | Values |
+|---|---|
+| Color scales | `--brand-primary-{50..900}`, `--brand-accent-{50..900}`, `--neutral-{50..950}` |
+| Semantic | `--brand-bg`, `--brand-fg`, `--brand-muted`, `--brand-surface`, `--brand-divider` |
+| Type | `--text-{xs..6xl}`, `--text-display`, `--leading-*`, `--tracking-*` |
+| Spacing | `--space-{0,px,0.5,1..7}` |
+| Radius | `--radius-{sm,md,lg,xl,full}` |
+| Shadow | `--shadow-{sm,md,lg,xl}` |
+| Motion | `--duration-{fast,base,slow}`, `--ease-{out,in-out}` |
+
+Templates that need to override a derived token (dark theme, brand-tinted surface) can do so in `template.css`.
+
+## After authoring slides — always surface the run commands
+
+When you (the assistant) author or edit slides for the user, **end your response with the exact `build` command** the user can run themselves. The user's iteration loop is small manual edits in `slides/*.md` plus a browser refresh; they need the command in the conversation, not buried in docs.
+
+Print this block as the closing of any turn that touches slides:
+
+```bash
+# lint — catches overflow, missing assets, layout-content mismatches
+# bash / PowerShell / Git Bash:
+bun ~/.pal/skills/presentation/tools/doctor.ts <deck-dir>
+# Windows cmd.exe:
+bun %USERPROFILE%\.pal\skills\presentation\tools\doctor.ts <deck-dir>
+
+# build — writes <cwd>/<deck-name>/<deck-name>.{html,md}
+# bash / PowerShell / Git Bash:
+bun ~/.pal/skills/presentation/tools/build.ts <deck-dir>
+# Windows cmd.exe (no ~ expansion):
+bun %USERPROFILE%\.pal\skills\presentation\tools\build.ts <deck-dir>
+
+# add --out <dir> to override the output parent, --force to overwrite an existing build
+# add --strict to doctor to promote warnings to errors
+```
+
+Substitute `<deck-dir>` with the actual deck path. Do this even when you also ran the build yourself — the user wants the command on hand for their own re-runs. **On Windows, check the user's shell before printing**: `cmd.exe` does not expand `~`, so if the user runs commands from a `C:\…>` prompt, print the `%USERPROFILE%` form. PowerShell, Git Bash, WSL, and Mac/Linux all expand `~` correctly.
 
 ## Other commands
 

package/assets/skills/presentation/demo/slides/011a-big-stat.md

@@ -0,0 +1,6 @@
+<!-- .slide: data-layout="big-stat" -->
+# 87<em class="unit">%</em>
+
+## of customers stayed with us year-over-year — up from 71% in 2024
+
+Note: big-stat is for moments where one number does the work of a whole slide. Use sparingly — once or twice per deck. The unit (%, $, k) goes in `<em class="unit">` so it scales smaller than the figure itself.

package/assets/skills/presentation/demo/slides/011b-metric-grid.md

@@ -0,0 +1,22 @@
+<!-- .slide: data-layout="metric-grid" -->
+## Q1 metrics at a glance
+
+<div class="metrics">
+<div class="metric">
+<p class="label">MRR</p>
+<p class="value">$48k</p>
+<p class="delta up">+12% QoQ</p>
+</div>
+<div class="metric">
+<p class="label">Active accounts</p>
+<p class="value">1,284</p>
+<p class="delta up">+204</p>
+</div>
+<div class="metric">
+<p class="label">Churn</p>
+<p class="value">2.1%</p>
+<p class="delta down">−0.4 pp</p>
+</div>
+</div>
+
+Note: metric-grid is a 3-up KPI strip. Each `.metric` block has a `.label`, `.value`, and optional `.delta` with `.up` / `.down` modifiers.

package/assets/skills/presentation/demo/slides/011c-pull-quote.md

@@ -0,0 +1,6 @@
+<!-- .slide: data-layout="pull-quote" -->
+> The best way to predict the future is to build it — but only if you can also explain why anyone should care.
+
+— A composite of every product strategy memo we've ever written
+
+Note: pull-quote sits between section divider and quote. Bigger than a regular blockquote, italicized in the display font, anchored by an accent rule on the left and an em-dashed attribution underneath.

package/assets/skills/presentation/demo/slides/012-closing.md

@@ -1,5 +1,5 @@
 <!-- .slide: data-layout="closing" -->
 # That's the lot
-## All 11 layouts, one place
+## All 14 layouts, one place
 
-Note: If you saw all 11 distinct slide styles, the build pipeline is working. Edit theme-base/layouts.css to tune any of them brand-wide; edit your template's template.css to override colors per brand; edit overrides.css in a deck folder for one-off tweaks.
+Note: If you saw all 14 distinct slide styles, the build pipeline is working. Edit theme-base/layouts.css to tune any of them brand-wide; edit your template's template.css to override colors per brand; edit overrides.css in a deck folder for one-off tweaks.

package/assets/skills/presentation/template/README.md

@@ -1,9 +1,10 @@
 # Deck folder
 
-Edit `content.md` — slides separated by `---` on its own line.
+One markdown file per slide under `slides/`. Files are concatenated at build time in filename order (use leading zeros: `001.md`, `002.md`, …). **Don't put `---` separators inside slide files** — the separator is added between files at build time.
 
 Build: `bun ~/.pal/skills/presentation/tools/build.ts .`
-Present: `bun ~/.pal/skills/presentation/tools/present.ts .`
+
+Output lands at `<cwd>/<deck-name>/<deck-name>.html` — open it in your browser and refresh after each rebuild.
 
 Layout per slide:
 ```markdown
@@ -12,4 +13,4 @@ Layout per slide:
 - bullet
 ```
 
-Available layouts: title, section, content, two-column, image-text, quote, closing, agenda, table, comparison, code. See the skill's SKILL.md for details on each.
+Available layouts: title, section, content, two-column, image-text, quote, closing, agenda, table, comparison, code, big-stat, metric-grid, pull-quote. See the skill's SKILL.md for details on each.