portable-agent-layer 0.28.1 → 0.29.0

package/assets/skills/presentation/README.md

@@ -0,0 +1,21 @@
+# presentation
+
+PAL skill for building branded HTML presentations from markdown using Reveal.js. Multi-template (one user can register multiple brands), single self-contained HTML output, brand-neutral engine.
+
+See `SKILL.md` for the full workflow. TL;DR:
+
+```bash
+# one-time per brand
+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
+```
+
+Layouts: title, section, content, two-column, image-text, quote, closing, agenda, table, comparison, code.
+
+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.
+
+PPTX import (v2): not yet supported.

package/assets/skills/presentation/SKILL.md

@@ -0,0 +1,172 @@
+---
+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>`
+---
+
+## Overview
+
+Renders a deck folder (markdown + config) to a single self-contained HTML presentation using Reveal.js, themed by one of the user's registered brand templates. Decks stay in plain markdown for git-friendliness; templates own brand identity (color, logo, fonts, footer); the skill itself is brand-neutral.
+
+**Three-layer separation:**
+
+1. **Skill** (this folder) — brand-neutral engine: Reveal.js vendored offline, base CSS, 11 layout components, build pipeline.
+2. **Templates** — user-owned brand assets at `~/.pal-data/presentation-templates/<name>/` (override-able). Registered in `~/.pal-data/presentation-templates/registry.json`. Multi-template — one user can have several brands.
+3. **Decks** — one folder per presentation, anywhere in user's filesystem. Contains `slides.config.yml`, a `slides/` folder of one-markdown-file-per-slide, `assets/`.
+
+## Workflow
+
+### Step 0 (one-time per brand): Set up a template
+
+Interactive:
+```bash
+bun ~/.pal/skills/presentation/tools/setup-template.ts
+```
+
+Walks through 9 fields: name, storage path, logo file, primary color, accent color, footer text, logo placement, fonts, aspect ratio. Optional: generate a showcase deck demonstrating every layout.
+
+Non-interactive (Claude can drive it):
+```bash
+bun ~/.pal/skills/presentation/tools/setup-template.ts \
+  --name <slug> \
+  --logo <abs-path-to-logo.svg> \
+  --primary "#0E1335" \
+  [--accent "#FFB84D"] \
+  [--footer "Konvert7 · 2026"] \
+  [--logo-placement "footer"] \
+  [--fonts "system"] \
+  [--aspect "16:9"] \
+  [--showcase] \
+  [--yes]
+```
+
+Defaults if omitted: accent = derived complementary of primary; logo-placement = footer; fonts = system; aspect = 16:9.
+
+### Step 1: Scaffold a deck
+
+```bash
+bun ~/.pal/skills/presentation/tools/new-deck.ts <deck-dir> --template <name> [--title "Deck title"]
+```
+
+If `--template` is omitted and only one template is registered, that one is used. If multiple are registered, the command lists them and exits. Adds `--showcase` to scaffold a demo deck with every layout exercised.
+
+### Step 2: Author content
+
+Each slide is its own markdown file under `<deck-dir>/slides/`. Files are concatenated at build time in filename order (`001.md`, `002.md`, `003-foo.md`, …) — use leading zeros so sort order is stable. **Do not put `---` separators inside slide files** — the separator is added between files at build time.
+
+Authoring this way means: a malformed edit only takes down its own slide, slides can be reordered by renaming, and parallel writes don't conflict.
+
+Per-slide conventions (inside each file):
+- Speaker notes: lines starting with `Note:`.
+- Layout directive: `<!-- .slide: data-layout="..." -->` at the top.
+- See "Layouts" below for the available layout names.
+
+Backwards compatible: if `slides/` doesn't exist, the build falls back to a single `<deck-dir>/content.md` with `---` separators between slides.
+
+### Step 3: Build
+
+```bash
+bun ~/.pal/skills/presentation/tools/build.ts <deck-dir>
+```
+
+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.
+
+### Step 4: Present
+
+```bash
+bun ~/.pal/skills/presentation/tools/present.ts <deck-dir>
+```
+
+Builds (if missing or stale) and opens in the default browser. `F` = fullscreen, `S` = speaker notes window, `?` = keyboard shortcuts.
+
+## Deck folder layout
+
+```
+<deck-dir>/
+├── slides.config.yml       # template name, deck title, language, aspect override
+├── slides/                 # one markdown file per slide; concatenated at build time
+│   ├── 001.md
+│   ├── 002.md
+│   └── …
+├── overrides.css           # optional — per-deck CSS overrides
+├── assets/                 # images / videos referenced from slides/*.md
+└── dist/                   # build output (gitignored automatically)
+    └── index.html
+```
+
+(Legacy: a single `content.md` at the deck root still works — see Step 2.)
+
+## Content conventions
+
+```markdown
+<!-- .slide: data-layout="title" -->
+# Deck title
+## Subtitle line
+
+Note: Speaker note for the title slide.
+
+---
+
+<!-- .slide: data-layout="content" -->
+## Today's three points
+- First
+- Second
+- Third
+
+---
+
+<!-- .slide: data-layout="two-column" -->
+## Title
+
+<div class="col-left">
+
+Left content here, can include **markdown**.
+
+</div>
+
+<div class="col-right">
+
+Right content.
+
+</div>
+
+---
+
+<!-- .slide: data-layout="closing" -->
+# Thank you
+## Questions?
+```
+
+## Layouts (v1)
+
+| Layout | When | Notes |
+|---|---|---|
+| `title` | Cover slide | Big title, optional subtitle, brand logo prominent |
+| `section` | Section divider | Full-bleed accent background, large white title |
+| `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 |
+| `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 |
+| `code` | Code-focused | Triple-backtick fenced blocks with language tag |
+
+## Other commands
+
+```bash
+bun ~/.pal/skills/presentation/tools/list-templates.ts
+```
+
+Prints all registered templates with their primary color and storage path.
+
+## When to use this skill
+
+- Building a workshop deck, internal presentation, conference talk, sales pitch, lecture
+- A user mentioning a deck / slides / talk / lecture / "prezentáció" / equivalent in their language
+- The user already has a template registered and wants to make a new deck
+
+Do NOT use when:
+- A static one-pager / handout PDF is needed → use `consulting-report` or `create-pdf`
+- The user wants editable PowerPoint specifically (v1 doesn't export pptx; deferred to v2)

package/assets/skills/presentation/demo/slides/001-title.md

@@ -0,0 +1,5 @@
+<!-- .slide: data-layout="title" -->
+# Layout showcase
+## Every layout in this skill, one slide each
+
+Note: This deck is the smoke-test for the presentation skill. Every layout the skill ships should render correctly here.

package/assets/skills/presentation/demo/slides/002-agenda.md

@@ -0,0 +1,13 @@
+<!-- .slide: data-layout="agenda" -->
+## Agenda
+
+1. Title — cover slides
+2. Section — full-bleed dividers
+3. Content — the default
+4. Two-column — side-by-side
+5. Image + text — visuals plus narrative
+6. Quote — pull quotes
+7. Table — tabular data
+8. Comparison — option boxes
+9. Code — fenced code blocks
+10. Closing — thank-you slide

package/assets/skills/presentation/demo/slides/003-section-text-heavy.md

@@ -0,0 +1,3 @@
+<!-- .slide: data-layout="section" -->
+# Text-heavy layouts
+## Title, section, content, two-column, quote

package/assets/skills/presentation/demo/slides/004-content.md

@@ -0,0 +1,12 @@
+<!-- .slide: data-layout="content" -->
+## Content layout
+
+The default. Title at top, body below.
+
+- Bullets work as you'd expect
+- Sub-bullets too
+  - Like this
+  - And this
+- **Bold**, *italic*, `inline code`, [links](https://example.com)
+
+Note: If you don't add a `data-layout` directive, this is what you get.

package/assets/skills/presentation/demo/slides/005-two-column.md

@@ -0,0 +1,22 @@
+<!-- .slide: data-layout="two-column" -->
+## Two-column layout
+
+<div class="col-left">
+
+**Left side**
+
+- Use for comparisons
+- Or before/after
+- Or feature/benefit
+
+</div>
+
+<div class="col-right">
+
+**Right side**
+
+- Mirrors the left
+- Same width
+- Vertical divider between
+
+</div>

package/assets/skills/presentation/demo/slides/006-quote.md

@@ -0,0 +1,4 @@
+<!-- .slide: data-layout="quote" -->
+> Make everything as simple as possible, but not simpler.
+>
+> — Albert Einstein

package/assets/skills/presentation/demo/slides/007-section-structured.md

@@ -0,0 +1,3 @@
+<!-- .slide: data-layout="section" -->
+# Structured layouts
+## Table, comparison, image+text, code

package/assets/skills/presentation/demo/slides/008-table.md

@@ -0,0 +1,11 @@
+<!-- .slide: data-layout="table" -->
+## Table layout
+
+| Phase     | Duration | Output           | Owner    |
+|-----------|----------|------------------|----------|
+| Discovery | 2 weeks  | Findings deck    | Lead PM  |
+| Design    | 4 weeks  | Component specs  | Designer |
+| Build     | 6 weeks  | Working software | Eng team |
+| Launch    | 1 week   | Release notes    | Lead PM  |
+
+Note: Markdown tables — header row gets the brand-primary background, even rows get a subtle surface tint.

package/assets/skills/presentation/demo/slides/009-comparison.md

@@ -0,0 +1,25 @@
+<!-- .slide: data-layout="comparison" -->
+## Comparison layout
+
+<div class="compare">
+<div class="option">
+
+**Option A — Build in-house**
+
+- Full control over the roadmap
+- Higher up-front investment
+- 6+ months to v1
+- Owned IP, no vendor lock-in
+
+</div>
+<div class="option">
+
+**Option B — Buy & integrate**
+
+- 4–6 weeks to deployment
+- Per-seat licensing cost
+- Vendor roadmap dependency
+- Faster time-to-value
+
+</div>
+</div>

package/assets/skills/presentation/demo/slides/010-image-text.md

@@ -0,0 +1,20 @@
+<!-- .slide: data-layout="image-text" -->
+## Image + text layout
+
+<div class="image">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300" preserveAspectRatio="xMidYMid meet">
+<rect width="400" height="300" fill="#E5E7EB"/>
+<text x="200" y="160" font-family="sans-serif" font-size="22" fill="#6B7280" text-anchor="middle">your image here</text>
+</svg>
+</div>
+<div class="text">
+
+Drop an image into your deck's `assets/` folder, then reference it from markdown:
+
+```
+![alt](assets/diagram.png)
+```
+
+The image is left-aligned, the text gets the right column. Both vertically centered.
+
+</div>

package/assets/skills/presentation/demo/slides/011-code.md

@@ -0,0 +1,19 @@
+<!-- .slide: data-layout="code" -->
+## Code layout
+
+```python
+def fibonacci(n: int) -> int:
+    """Iterative — O(n) time, O(1) space."""
+    if n < 2:
+        return n
+    a, b = 0, 1
+    for _ in range(n - 1):
+        a, b = b, a + b
+    return b
+
+
+print([fibonacci(i) for i in range(10)])
+# [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
+```
+
+Note: Syntax highlighting via the bundled highlight.js — supports 30+ languages out of the box.

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

@@ -0,0 +1,5 @@
+<!-- .slide: data-layout="closing" -->
+# That's the lot
+## All 11 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.

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

@@ -0,0 +1,15 @@
+# Deck folder
+
+Edit `content.md` — slides separated by `---` on its own line.
+
+Build: `bun ~/.pal/skills/presentation/tools/build.ts .`
+Present: `bun ~/.pal/skills/presentation/tools/present.ts .`
+
+Layout per slide:
+```markdown
+<!-- .slide: data-layout="content" -->
+## Slide title
+- 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.

package/assets/skills/presentation/template/slides/001-title.md

@@ -0,0 +1,5 @@
+<!-- .slide: data-layout="title" -->
+# New deck
+## Subtitle here
+
+Note: Speaker note — only visible in speaker view.

package/assets/skills/presentation/template/slides/002-content.md

@@ -0,0 +1,6 @@
+<!-- .slide: data-layout="content" -->
+## What's inside
+
+- Point one
+- Point two
+- Point three

package/assets/skills/presentation/template/slides/003-closing.md

@@ -0,0 +1,3 @@
+<!-- .slide: data-layout="closing" -->
+# Thank you
+## Questions?

package/assets/skills/presentation/theme-base/base.css

@@ -0,0 +1,167 @@
+/* presentation skill — theme-base/base.css
+ * Brand-neutral base. Templates override the --brand-* custom properties.
+ * Do not put brand colours here — only neutral defaults. */
+
+:root {
+  --brand-primary: #0E1335;
+  --brand-accent: #2563EB;
+  --brand-bg: #FFFFFF;
+  --brand-fg: #111827;
+  --brand-muted: #6B7280;
+  --brand-surface: #F9FAFB;
+  --brand-divider: #E5E7EB;
+
+  --brand-logo: none;
+
+  --font-display: "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --font-body:    "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --font-mono:    "JetBrains Mono", "Menlo", "Consolas", monospace;
+
+  --space-1: 0.5rem;
+  --space-2: 1rem;
+  --space-3: 1.5rem;
+  --space-4: 2.5rem;
+  --space-5: 4rem;
+}
+
+.reveal {
+  font-family: var(--font-body);
+  font-size: 48px;
+  font-weight: 400;
+  color: var(--brand-fg);
+}
+.reveal-viewport { background: var(--brand-bg); }
+
+/* Default content padding inside every slide. Distinct from Reveal's `margin` config:
+ *   `margin` (Reveal) = letterbox between canvas and viewport
+ *   this padding   = inset between section content and canvas edge
+ * Bottom reserve protects the chrome (logo + slide-number) anchored at canvas-bottom.
+ * Special layouts (title/section/quote/closing) override below in layouts.css. */
+.reveal .slides > section {
+  padding: 2.5rem 5rem 4.5rem;
+  box-sizing: border-box;
+}
+
+
+.reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6 {
+  font-family: var(--font-display);
+  color: var(--brand-fg);
+  letter-spacing: -0.015em;
+  line-height: 1.15;
+  margin: 0 0 var(--space-3) 0;
+  text-transform: none;
+}
+.reveal h1 { font-size: 2.6em; font-weight: 700; }
+.reveal h2 { font-size: 2.0em; font-weight: 600; }
+.reveal h3 { font-size: 1.5em; font-weight: 600; }
+.reveal h4 { font-size: 1.2em; font-weight: 600; }
+
+.reveal p { line-height: 1.5; margin: 0 0 var(--space-2) 0; }
+
+.reveal ul, .reveal ol {
+  margin: 0 0 var(--space-2) 1.4em;
+  line-height: 1.5;
+}
+.reveal li { margin-bottom: var(--space-1); }
+.reveal li > ul, .reveal li > ol { margin-top: var(--space-1); margin-bottom: 0; }
+
+.reveal a {
+  color: var(--brand-accent);
+  text-decoration: none;
+  border-bottom: 1px solid currentColor;
+}
+
+.reveal blockquote {
+  border-left: 4px solid var(--brand-accent);
+  margin: 0;
+  padding: var(--space-2) var(--space-3);
+  background: var(--brand-surface);
+  font-style: italic;
+}
+
+.reveal pre {
+  background: #1E1E1E;
+  border-radius: 4px;
+  font-size: 0.7em;
+  line-height: 1.5;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+}
+.reveal pre code {
+  padding: var(--space-2);
+  display: block;
+  font-family: var(--font-mono);
+}
+.reveal :not(pre) > code {
+  background: var(--brand-surface);
+  padding: 0.1em 0.4em;
+  border-radius: 3px;
+  font-family: var(--font-mono);
+  font-size: 0.85em;
+  color: var(--brand-primary);
+}
+
+.reveal table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: var(--space-2) 0;
+  font-size: 0.8em;
+}
+.reveal th {
+  background: var(--brand-primary);
+  color: #fff;
+  text-align: left;
+  padding: var(--space-1) var(--space-2);
+  font-weight: 600;
+}
+.reveal td {
+  padding: var(--space-1) var(--space-2);
+  border-bottom: 1px solid var(--brand-divider);
+}
+.reveal tr:nth-child(even) td { background: var(--brand-surface); }
+
+/* Footer logo — pseudo on .slides (the canvas) so it inherits Reveal's scale+translate
+ * transforms and stays at canvas-bottom-right regardless of the configured `margin`. */
+.reveal .slides::after {
+  content: '';
+  position: absolute;
+  bottom: 1.5rem;
+  right: 1.5rem;
+  width: 90px;
+  height: 28px;
+  background: var(--brand-logo) no-repeat right bottom / contain;
+  opacity: 0.55;
+  pointer-events: none;
+  z-index: 10;
+}
+
+/* Slide number — JS hook in skeleton.html re-parents Reveal's .slide-number into .slides,
+ * so it shares the same canvas coordinate system as the logo. */
+.reveal .slides > .slide-number {
+  position: absolute;
+  bottom: 1.5rem;
+  left: 1.5rem;
+  right: auto;
+  top: auto;
+  background: transparent;
+  color: var(--brand-muted);
+  font-family: var(--font-body);
+  font-size: 0.55em;
+  font-weight: 400;
+  line-height: 28px;
+  letter-spacing: 0.05em;
+  padding: 0;
+  pointer-events: none;
+  z-index: 10;
+}
+
+/* Hide both chrome elements on cover, divider, and closing layouts.
+ * !important is required because Reveal sets style="display: block" inline on .slide-number
+ * via JS — only !important beats inline styles. */
+.reveal .slides:has(> section.present[data-layout="title"])::after,
+.reveal .slides:has(> section.present[data-layout="title"]) > .slide-number,
+.reveal .slides:has(> section.present[data-layout="section"])::after,
+.reveal .slides:has(> section.present[data-layout="section"]) > .slide-number,
+.reveal .slides:has(> section.present[data-layout="closing"])::after,
+.reveal .slides:has(> section.present[data-layout="closing"]) > .slide-number {
+  display: none !important;
+}