portable-agent-layer 0.32.0 → 0.34.0

package/README.md

@@ -82,6 +82,7 @@ pal cli status        # check your setup
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |
 | `pal cli doctor` | Check prerequisites and system health |
+| `pal cli usage` | Summarize token usage and estimated cost |
 
 ### Target flags
 

package/assets/skills/presentation/SKILL.md

@@ -59,9 +59,10 @@ Authoring this way means: a malformed edit only takes down its own slide, slides
 Per-slide conventions (inside each file):
 - Speaker notes: lines starting with `Note:`.
 - Layout directive: `<!-- .slide: data-layout="..." -->` at the top.
+- Image references: `![alt](../assets/foo.png)` — the natural relative path from `slides/*.md` to the deck's `assets/` folder. The build rewrites this to `assets/foo.png` in the concatenated `<deck-name>.md` (which sits at the deck root, so the path stays valid for direct preview), and inlines the image bytes as a `data:` URI in the HTML so the output is truly self-contained (emailable, USB-stickable). Remote refs (`https://…`) and `data:` URIs pass through untouched.
 - 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.
+Backwards compatible: if `slides/` doesn't exist, the build falls back to a single `<deck-dir>/content.md` with `---` separators between slides. Image refs there should use `assets/foo.png` (root-relative), since `content.md` already lives at the deck root.
 
 ### Step 3: Build
 
@@ -69,12 +70,14 @@ Backwards compatible: if `slides/` doesn't exist, the build falls back to a sing
 bun ~/.pal/skills/presentation/tools/build.ts <deck-dir> [--out <dir>] [--force]
 ```
 
-Output goes to `<out>/<deck-name>/`, where `<deck-name>` = the basename of `<deck-dir>`:
+Output files (where `<deck-name>` = 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.
+Default location: `--out` defaults to the **deck-dir itself**, and the files land flat at `<deck-dir>/<deck-name>.{html,md}` — next to your slides, regardless of where you ran the build from. The scaffolder's `.gitignore` already covers them.
+
+Override: pass `--out <dir>` to redirect elsewhere. When `--out` is *not* the deck-dir, a `<deck-name>/` subdir is created under it so multiple decks can coexist in one collection folder.
 
 `--force` overwrites an existing build. Without it, the build refuses to clobber `<deck-name>.{md,html}`.
 
@@ -90,7 +93,8 @@ Catches authoring failures before you ever open the browser:
 - 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.
+- **Visual-line budget**: any bullet-bearing slide (`content`, `agenda`, `comparison`, `two-column`) with > 10 flattened list lines (top-level + sub-bullets combined). 10 fits cleanly; 11+ overflows even when each line is short.
+- Image referenced via `![](../assets/...)` (slide-relative) or `![](assets/...)` (root-relative, for legacy `content.md` decks) 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.
@@ -112,10 +116,105 @@ Open `<out>/<deck-name>/<deck-name>.html` in your browser. Iterate by editing a
 └── 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.
+Build output lands flat inside the deck-dir by default (`<deck-dir>/<deck-name>.{html,md}`), or under `<out>/<deck-name>/` when `--out` is explicit. Both shapes are covered by the scaffolder's `.gitignore`.
 
 (Legacy: a single `content.md` at the deck root still works — see Step 2.)
 
+## Content principles
+
+The doctor enforces *structural* discipline (slide budgets, layout-content match, missing assets). These rules are about *content* — what goes on the slide and in the notes. They apply to every deck regardless of type. For type-specific rules, see the "see also" links at the bottom of this section.
+
+### Core rules
+
+- **A slide carries what the *learner* takes away — never what happens in the room.** "We will discuss CI/CD agents" is not a slide; "CodeRabbit and CodeAnt cost ~$15/dev/mo at this scale" is.
+- **Less is more on bullets.** The doctor caps `content` at 7 bullets; the content rule is stricter — 3–5 is usually right. One bullet is not a slide; either expand or fold into the previous one.
+- **Two ideas → two slides.** If a slide carries two takeaways, split.
+- **No sentences on slides or in notes.** Exceptions: quotes, code comments, single callout sentences. Everything else is bullets, including notes.
+- **A title-only slide is valid only as a `section` divider.** Single-word slides and single-bullet slides are not valid — split or expand.
+- **Vocabulary consistency.** Pick one word per concept ("agent" vs "assistant", "tool" vs "capability") and use it everywhere. Drift confuses the audience.
+- **Layout choice = content choice, not decoration.** `big-stat` says "this number *is* the point." `comparison` says "you have to choose between these." `quote` says "someone earned the right to say this." Wrong layout muddies the message.
+- **Define jargon before using it.** First use of a non-obvious term gets a parenthesized gloss or its own glossary slide. After that, no.
+
+### Bullet & sub-bullet structure
+
+- **Top-level bullet = one fact or one claim.** 6–12 words. If you need more, split or use a sub-bullet.
+- **Sub-bullets = elaboration of the parent.** A list, an example, a clarification. 2–8 words each. Don't start a new claim at a sub-bullet — that's a top-level bullet.
+- **Never use em-dash continuations to extend a bullet.** `- Foo — bar — baz` is prose pretending to be a bullet. Convert to:
+  ```markdown
+  - Foo
+    - bar
+    - baz
+  ```
+  Em-dash is reserved for: title qualifiers ("Block 4 — Landscape"), and anticipated Q&A in notes (`"Question?" — short answer`).
+- **Stable parallel structure inside a bullet group.** If bullet 1 starts with a verb, bullets 2–N start with verbs. If bullet 1 is `Name: description`, the rest match.
+- **Concrete over abstract.** Show paths, file names, numbers, command snippets in backticks. "the project file" is weaker than `./CLAUDE.md`.
+
+### Notes structure
+
+Notes are the speaker's working surface during delivery. They must be scannable, not readable. Strict format:
+
+1. **Source links first**, one per line, before any explanation. Multiple links are fine if the slide cites multiple sources. The speaker should never scroll to find a link they're about to open in the browser.
+2. **Named beats as top-level bullets.** A "beat" is a named chunk of context — `Eval setup`, `Headline numbers`, `Why X wins`, `Common output`, `Anticipated questions`. The beat name lets the speaker jump.
+3. **Sub-bullets under each beat.** Same 2–8 word budget. Lists, edge cases, examples. No prose.
+4. **Quotes nest under a `- Quote` beat** as a markdown blockquote (`>`). Quotes are the only place full sentences are allowed in notes.
+5. **Anticipated Q&A near the end.** Format: `- "Question?" — short answer`. The em-dash here separates the quote from the answer; this is the legal use.
+6. **Forward references are terse.** "more in Day 2 when you build your own", "see Block 2 for X". Not "we'll discuss this later" prose.
+
+### Voice
+
+- **Declarative, not hedging.** "Anthropic's holdout" beats "Anthropic has chosen a different approach." If you mean it, say it; if you don't, cut it.
+- **Opinionated where the room expects opinion.** Workshops are taught, not narrated. State which option you'd pick and why.
+- **Concrete identifiers visible.** File paths, version numbers, URLs, exact tool names. The audience should be able to type what's on the slide and have it work.
+
+### Examples
+
+**Bad slide — describes the room, not the takeaway:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Code Review Agents
+
+- We will look at three vendors
+- Pricing comparison
+- Live demo of CodeRabbit
+```
+
+**Good slide — what the learner walks away with:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Code review agents — when each wins
+
+- CodeRabbit: best for large PRs, weakest at C# specifics
+- CodeAnt: tightest C# rules, no PR summary
+- Custom (Claude Code in CI): controllable, you pay per token
+```
+
+**Bad notes — prose, no source link:**
+
+```markdown
+Note: We should talk about EchoLeak here. It was a vulnerability in Microsoft 365 Copilot discovered in 2025 that allowed prompt injection through email content. The attack worked by sending a crafted email that the Copilot assistant would later read and execute instructions from. This is a good example of why we need to think about prompt injection in agentic systems.
+```
+
+**Good notes — link first, bullets, anticipated questions:**
+
+```markdown
+Note:
+- [EchoLeak (CVE-2025-32711) — Microsoft writeup](https://msrc.microsoft.com/...)
+- Zero-click prompt injection in M365 Copilot via crafted email
+- Attack surface: any agent that reads attacker-controlled content
+- Mitigations
+  - Tool allowlists, not denylists
+  - Human-in-loop on data exfil tools
+- "Could this happen with Claude Code?" — yes, via any tool that reads external text (web fetch, MCP server, log file)
+```
+
+### See also (type-specific rules)
+
+- **Workshops, training, hands-on sessions:** [`WORKSHOP.md`](WORKSHOP.md)
+
+(Future: `PITCH.md`, `LECTURE.md`, `INTERNAL_REVIEW.md` — coming soon.)
+
 ## Content conventions
 
 ```markdown
@@ -188,6 +287,26 @@ Composable on any `<img>` or wrapper element:
 | `image-duotone` | Brand-tinted monochrome via filter chain |
 | `image-overlay` | Adds a brand-gradient scrim from transparent → primary at 75% bottom |
 
+## Text-alignment utilities
+
+Composable on any block element. Use these instead of inline `style="text-align: …"` — Reveal's print stylesheet forces `text-align: left !important` on every `div`/`p`/`ol`/`ul`, which silently kills inline alignment styles in print (the on-screen view looks fine, the printed PDF lands left-aligned).
+
+| Class | Effect |
+|---|---|
+| `text-center` | Center inline content (typical use: wrapping a centered `<img>` or caption) |
+| `text-right` | Right-align inline content |
+| `text-left` | Left-align inline content (rarely needed; default) |
+
+Example — centering an image on a `content` slide:
+
+```markdown
+<div class="text-center">
+
+![Waldo](../assets/waldo.png)
+
+</div>
+```
+
 ## 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, …)`.

package/assets/skills/presentation/WORKSHOP.md

@@ -0,0 +1,128 @@
+# Workshop-specific content rules
+
+Read [`SKILL.md`](SKILL.md) first — the general content principles apply unchanged. This file only adds the rules that are specific to workshops, training sessions, and hands-on formats.
+
+A workshop is not a talk. The deck is scaffolding for the room's work, not the work itself. If the slides could be read alone and convey the value, it isn't a workshop — it's a recorded lecture.
+
+## Rules
+
+- **Block arc: opener → core → demo/exercise → synthesis.** Every block follows this shape.
+  - **Opener** — one slide that earns the block: a stat, a story, a failure case. "Why should you care for the next 45 minutes?"
+  - **Core** — the actual material. The teaching slides.
+  - **Demo or exercise** — the participants do something or watch something done. Live, not recorded.
+  - **Synthesis** — one slide that closes the loop: "what you now know" or "what you can do tomorrow."
+  - Skip a beat and the block falls flat. Especially the opener.
+- **Topic shape inside a block — preferred, not required: what → proof → mechanics → advanced → exercise.** A useful default ordering for depth topics. Skip any beat that doesn't fit the topic. Reorder if a different sequence teaches better. Variability is expected; this is the shape to fall back to when nothing better suggests itself.
+  - **What** — what it is + landscape framing (who built it, who supports it, who doesn't), if it matters.
+  - **Proof** — only if you have a *genuinely* interesting stat, eval, or incident. See the big-stat rule below.
+  - **Mechanics** — how it actually works: scopes, locations, semantics, limits.
+  - **Advanced** — patterns, extensions, teaser hooks for later blocks/days.
+  - **Exercise** — bullets are *principles* (learner takeaway), notes carry facilitation.
+- **Big-stat is for genuinely interesting numbers, not a checkbox.** Use the `big-stat` layout when you have a stat that *changes the room's mind* — a real eval result, a striking incident metric, a non-obvious cost number. Don't manufacture one. A topic without a strong stat skips the proof slide; a generic stat dilutes every later one. Format when used: h1 = the number with `<em class="unit">`, h2 = the comparison-with-context (named alternatives, named source).
+- **~50% slides / ~50% hands-on.** If deck-time exceeds half the block's runtime, cut slides — not exercise time.
+- **Recall check at every block boundary.** A question slide between blocks: "Before we move on — what would you do if X?" One question, no answer, deliberate silence. Forces consolidation.
+- **Question slides as discussion prompts.** Bold question, no answer, no bullets. Use sparingly (2–3 per day max) — overuse breaks the room's trust that you have answers.
+- **Energy curve matters.**
+  - Hardest cognitive lift in the morning, before lunch.
+  - Live coding right after lunch is malpractice (post-meal energy crash).
+  - Demos and discussion in the afternoon.
+  - End each day on synthesis or a payoff demo, never on dense content.
+- **Buffer / reserve slides per block.** Every block has 1–2 slides marked optional (in the deck, not separate) used only if pace allows. Lets you stretch comfortably without scrambling. Marker convention: filename suffix `-reserve` (e.g., `045-reserve-extra-eval-example.md`) and a `<!-- reserve -->` comment at the top of the slide so the doctor can flag if any are still flagged at build time.
+- **Exercise slides follow a strict template.**
+  - **Title prefix `Exercise — `** so the room sees the mode change.
+  - **Bullets = principles, not procedure.** What the learner *takes away* by doing the exercise. Procedure ("5 minutes solo, then we compare two") goes in notes.
+  - **Standard note beats, in order:** `Facilitation`, `Common output`, `Common mistakes`, `Anticipated questions`. Use these names verbatim — the speaker scans by them.
+  - **Keep principles transferable.** A bullet that only makes sense in the context of this specific repo isn't a principle; demote it to a note example.
+
+## Examples
+
+**Bad opener — describes the agenda instead of earning the block:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Security block
+
+- Prompt injection
+- Tool aliasing
+- Credential exposure
+- Hook-based guardrails
+```
+
+**Good opener — a real incident earns the next 90 minutes:**
+
+```markdown
+<!-- .slide: data-layout="big-stat" -->
+# 9 seconds
+## Replit production database, deleted by an agent
+
+Note:
+- [Replit prod-DB deletion — postmortem](https://...)
+- Agent had unscoped DB credentials in its environment
+- "Drop the dev tables" → matched against prod by mistake
+- This is the failure mode the next 90 minutes prevent
+- "Could Claude Code do this?" — yes, if you give it `.env` with prod creds
+```
+
+**Bad recall slide — gives the answer:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Recap
+
+- Tier 1 = enterprise sanctioned
+- Tier 2 = paid + settings off
+- Tier 3 = prohibited
+```
+
+**Good recall slide — forces the room to retrieve:**
+
+```markdown
+<!-- .slide: data-layout="quote" -->
+> Your colleague asks if she can paste a 20-line C# snippet
+> from our payment service into ChatGPT Plus. What do you say?
+
+Note:
+- Let the room answer first, ~30 seconds of silence is fine
+- Correct: depends on classification — if Confidential, no; if Internal, sanitize and yes (settings off)
+- Don't give the answer until at least one person tries
+```
+
+**Bad exercise slide — procedure on the slide, no transferable principle:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Write a CLAUDE.md
+
+- Open your favorite repo
+- Spend 5 minutes writing CLAUDE.md
+- We'll pick 2 to share
+- Discuss what worked
+```
+
+**Good exercise slide — principles on the slide, procedure in notes:**
+
+```markdown
+<!-- .slide: data-layout="content" -->
+## Exercise — write your CLAUDE.md
+
+- Capture conventions, not procedures (procedures belong in skills)
+- One fact per line, no prose paragraphs
+- Glossary entries earn their place — only project-specific terms
+- Order matters — most-violated rules first, model reads top-down
+- Commit it; use `.local.md` only for personal overrides
+
+Note:
+- Facilitation
+  - 5 min solo on a repo they know
+  - 2 volunteers show on screen
+  - group critiques against the failure modes from prior slides
+- Common output
+  - "Use Polly for retries, not custom code"
+  - "Tests live in `tests/Unit/`, not `src/__tests__/`"
+- Common mistakes
+  - writing instructions that should be skills
+  - copying a generic style guide instead of capturing real violations
+- Anticipated questions
+  - "Should this be in AGENTS.md or CLAUDE.md?" — symlink and stop choosing
+  - "What if there's already one?" — diff against it; usually adds 30%
+```

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

@@ -244,6 +244,14 @@
 .reveal tr:nth-child(even) td { background: var(--brand-surface); }
 .reveal tr:last-child td { border-bottom: 0; }
 
+/* ── Text alignment utilities — composable on any block element.
+ * `!important` is needed because Reveal's print stylesheet forces
+ * `text-align: left !important` on every div/p/ol/ul, which would otherwise
+ * override author intent (inline styles or any non-`!important` rule). */
+.reveal .text-center { text-align: center !important; }
+.reveal .text-right  { text-align: right !important; }
+.reveal .text-left   { text-align: left !important; }
+
 /* ── Image utilities (composable on any <img> or wrapper) */
 .reveal .image-rounded img,
 .reveal img.image-rounded { border-radius: var(--radius-md); }
@@ -323,3 +331,108 @@
   color: var(--brand-accent);
   height: 2px;
 }
+
+/* ── Print
+ * Reveal's vendored print stylesheet (`@media print { html:not(.print-pdf) … }`)
+ * forces every heading to `color:#000!important` and `p/li/td` to `#000`. That
+ * inverts the white-on-brand text we use on `section` and `closing` dividers
+ * (whose gradient background is on the section element itself, so it still
+ * renders blue) — producing black-on-blue when the user hits Cmd+P without
+ * `?print-pdf`. Restore brand text colors here, and force color-adjust:exact
+ * so the gradient prints reliably. */
+@media print {
+  .reveal section[data-layout="section"],
+  .reveal section[data-layout="closing"] {
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+  .reveal section[data-layout="section"] h1,
+  .reveal section[data-layout="section"] h4,
+  .reveal section[data-layout="closing"] h1 {
+    color: #fff !important;
+  }
+  .reveal section[data-layout="section"] h2,
+  .reveal section[data-layout="section"] h3 {
+    color: rgba(255, 255, 255, 0.7) !important;
+  }
+  .reveal section[data-layout="section"] p,
+  .reveal section[data-layout="section"] li,
+  .reveal section[data-layout="closing"] h2,
+  .reveal section[data-layout="closing"] p,
+  .reveal section[data-layout="closing"] li {
+    color: rgba(255, 255, 255, 0.85) !important;
+  }
+  .reveal section[data-layout="title"] h1 {
+    color: var(--brand-primary) !important;
+  }
+
+  /* ── Cmd+P scope (browser print on the regular URL, NOT ?print-pdf)
+   * Reveal forces every section to `display:block; position:static; padding:60px 20px;
+   * transform:none`, which strips the flex centering from title/section/closing/quote/
+   * big-stat/pull-quote and leaves their content top-aligned. Restore centering, then
+   * frame every printed page with a hairline so it reads like a printed sheet. */
+
+  /* Hairline frame — inset so it lives inside the printable area and survives
+   * the printer's unprintable-margin clipping. */
+  html:not(.print-pdf) .reveal .slides section {
+    box-shadow: inset 0 0 0 1px var(--neutral-300) !important;
+  }
+
+  /* Make every section fill the printable page. Two effects, no layout
+   * coercion:
+   *   1. The inset frame above wraps the full page edge instead of
+   *      shrink-wrapping content.
+   *   2. The flex-centered layouts below have a tall container to center
+   *      within (without a tall container, `justify-content: center` has
+   *      nothing to center against). */
+  html:not(.print-pdf) .reveal .slides section {
+    min-height: 100vh !important;
+    box-sizing: border-box !important;
+  }
+
+  /* Apply `--table-scale` to td/th in print. Reveal's print stylesheet forces
+   * `font-size: 20pt !important` on all td, which would otherwise override
+   * the screen rule. Scale font AND padding together — scaling font alone
+   * leaves the row height dominated by static cell padding, dampening the
+   * shrink effect. */
+  html:not(.print-pdf) .reveal section[data-layout="table"] td,
+  html:not(.print-pdf) .reveal section[data-layout="table"] th {
+    font-size: calc(20pt * var(--table-scale, 1)) !important;
+    padding: calc(0.5rem * var(--table-scale, 1)) calc(1rem * var(--table-scale, 1)) !important;
+  }
+
+  /* Reveal's print stylesheet forces every section to `display: block`,
+   * stripping the on-screen flex centering from the layouts that use it.
+   * Restore `display: flex` for those layouts ONLY — `flex-direction`,
+   * `justify-content`, and `align-items` come from layouts.css unchanged.
+   * Layouts not listed here stay as `display: block` and sit at the top of
+   * the page; that preserves the natural flow of layouts that depend on it
+   * (image-text and two-column rely on inline-block siblings, content/agenda/
+   * comparison/metric-grid/code/table all flow as block stacks). */
+  html:not(.print-pdf) .reveal .slides section[data-layout="title"],
+  html:not(.print-pdf) .reveal .slides section[data-layout="section"],
+  html:not(.print-pdf) .reveal .slides section[data-layout="closing"],
+  html:not(.print-pdf) .reveal .slides section[data-layout="quote"],
+  html:not(.print-pdf) .reveal .slides section[data-layout="big-stat"],
+  html:not(.print-pdf) .reveal .slides section[data-layout="pull-quote"] {
+    display: flex !important;
+  }
+}
+
+/* ── Print-view polish (`?print-pdf` URL — Reveal stacks each slide as a `.pdf-page`)
+ * Reveal sizes `.pdf-page` to slide dims and stacks them flush-left with no
+ * separation. Center each one and draw a hairline frame so the print preview
+ * reads like a sheaf of printed pages, not a left-aligned wall of slides.
+ *
+ * Why box-shadow inset and not `border`: Reveal forces `@page { margin: 0 }`,
+ * so an outside border would land at the edge of paper and be clipped by the
+ * printer's unprintable margin. An inset shadow draws the line *inside* the
+ * page box and survives the print. */
+html.print-pdf .reveal .slides .pdf-page {
+  box-shadow: inset 0 0 0 1px var(--neutral-300);
+}
+@media screen {
+  html.print-pdf .reveal .slides .pdf-page {
+    margin: 16px auto !important;
+  }
+}

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

@@ -213,9 +213,13 @@
   letter-spacing: var(--tracking-wide);
 }
 
-/* ── 9. table ── styling already in base; just ensure breathing room */
+/* ── 9. table ── styling already in base; just ensure breathing room.
+ * `--table-scale` is set per-slide by build.ts (`injectTableScale`) when row
+ * count exceeds 6 — multiplies the cell font-size to keep dense tables on a
+ * single page. Defaults to 1 (no change) when the var is unset. */
 .reveal section[data-layout="table"] table {
   margin-top: var(--space-3);
+  font-size: calc(var(--text-sm) * var(--table-scale, 1));
 }
 
 /* ── 10. comparison ── 2-3 option boxes with numbered badge + top stripe */
@@ -265,7 +269,12 @@
   max-height: 65vh;
   margin: var(--space-2) 0;
 }
-.reveal section[data-layout="code"] pre code { font-size: 0.9em; }
+/* Code font size scales down for long blocks. The build script sets
+   --code-scale on each code-layout section based on line count: 1.0 for ≤15
+   lines, 0.6 for ≥25 lines, linear in between. Defaults to 1.0 if unset. */
+.reveal section[data-layout="code"] pre code {
+  font-size: calc(0.9em * var(--code-scale, 1));
+}
 
 /* ── 12. big-stat ── One giant number + a muted caption beneath. Use sparingly.
  * Author surface:

package/assets/skills/presentation/tools/build.ts

@@ -8,7 +8,8 @@
 //   <out>/<deck-name>/<deck-name>.md     concatenated slides (written first)
 //   <out>/<deck-name>/<deck-name>.html   self-contained presentation
 //
-// --out defaults to process.cwd(). The deck-name subdir is always created
+// --out defaults to the deck-dir itself (output lands at <deck-dir>/<deck-name>/,
+// which the scaffolder gitignores). The deck-name subdir is always created
 // inside --out, even when --out is explicitly provided. Existing files in
 // the subdir are preserved unless --force is passed.
 
@@ -19,6 +20,71 @@ import { dataUri, escapeForTextarea, readText } from "./lib/inline";
 import { THEME_BASE, VENDOR_REVEAL } from "./lib/paths";
 import { getTemplate } from "./lib/registry";
 
+// Walk markdown line-by-line, skipping fenced code blocks, applying `transform`
+// to each non-fenced line. Used by both the concat-step path rewrite and the
+// HTML-step image inliner so neither touches example image syntax inside ``` blocks.
+async function mapMarkdownOutsideFences(
+  md: string,
+  transform: (line: string) => string | Promise<string>
+): Promise<string> {
+  const out: string[] = [];
+  let inFence = false;
+  for (const line of md.split("\n")) {
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      out.push(line);
+      continue;
+    }
+    out.push(inFence ? line : await transform(line));
+  }
+  return out.join("\n");
+}
+
+// Rewrite `../assets/X` (the natural relative path from a `slides/*.md` file)
+// to `assets/X` so the concatenated markdown — which lives at the deck root —
+// resolves images correctly when previewed directly. Bare `X.png` references
+// (no path) are left to the doctor to flag; we don't guess where they live.
+function rewriteImageRefsForConcat(md: string): Promise<string> {
+  return mapMarkdownOutsideFences(md, (line) =>
+    line.replace(/(!\[[^\]]*\]\()([^)]+)(\))/g, (whole, open, ref, close) => {
+      const trimmed = ref.trim();
+      if (/^(https?:|data:)/i.test(trimmed)) return whole;
+      if (trimmed.startsWith("../assets/")) {
+        return `${open}${trimmed.slice(3)}${close}`;
+      }
+      return whole;
+    })
+  );
+}
+
+// Inline every local image reference in the concatenated markdown as a data: URI
+// so the resulting HTML is truly self-contained (emailable, USB-stickable).
+// Resolves refs against `deckDir` (the concat-md's location). Missing files are
+// left untouched — the doctor flags them; build doesn't crash on author errors.
+async function inlineImagesInMarkdown(md: string, deckDir: string): Promise<string> {
+  return mapMarkdownOutsideFences(md, async (line) => {
+    const matches = [...line.matchAll(/(!\[[^\]]*\]\()([^)]+)(\))/g)];
+    if (matches.length === 0) return line;
+    let result = line;
+    for (const m of matches) {
+      const [whole, open, ref, close] = m;
+      const trimmed = ref.trim();
+      if (/^(https?:|data:)/i.test(trimmed)) continue;
+      const abs = resolve(deckDir, trimmed);
+      try {
+        await access(abs, fsConst.F_OK);
+      } catch {
+        continue;
+      }
+      // dataUri returns `url("data:...")` for CSS use; strip the `url("…")` wrapper for <img>.
+      const wrapped = await dataUri(abs);
+      const inner = wrapped.replace(/^url\("/, "").replace(/"\)$/, "");
+      result = result.replace(whole, `${open}${inner}${close}`);
+    }
+    return result;
+  });
+}
+
 const ASPECTS: Record<string, [number, number]> = {
   "16:9": [1920, 1080],
   "16:10": [1920, 1200],
@@ -65,6 +131,62 @@ function deckSlug(deckDir: string): string {
   return slug || "deck";
 }
 
+// Build-time injection: code-layout slides with > 15 lines of code get a
+// `style="--code-scale: X"` attribute baked into the slide directive. CSS in
+// layouts.css multiplies the base code font by this variable. Linear from 1.0
+// at 15 lines to 0.6 at 25 lines; clamped at 0.6 beyond. Build-time keeps the
+// attribute on the rendered <section>, so navigation/Highlight re-runs cannot
+// strip it.
+function injectCodeScale(slideMarkdown: string): string {
+  const layoutRe = /<!--\s*\.slide:\s*data-layout="code"([^>]*)-->/i;
+  const layoutMatch = layoutRe.exec(slideMarkdown);
+  if (!layoutMatch) return slideMarkdown;
+
+  const codeRe = /```[^\n]*\n([\s\S]*?)\n```/;
+  const codeMatch = codeRe.exec(slideMarkdown);
+  if (!codeMatch) return slideMarkdown;
+
+  const lines = codeMatch[1].split("\n").length;
+  if (lines <= 15) return slideMarkdown;
+
+  const scale = Math.max(0.6, 1 - (lines - 15) * 0.04).toFixed(2);
+  // Don't double-inject if a previous build already set it.
+  const extras = layoutMatch[1].replace(/\s+style="--code-scale:\s*[^"]+"/i, "").trim();
+  const attrs = extras
+    ? `${extras} style="--code-scale: ${scale}"`
+    : `style="--code-scale: ${scale}"`;
+  const newDirective = `<!-- .slide: data-layout="code" ${attrs} -->`;
+  return slideMarkdown.replace(layoutMatch[0], newDirective);
+}
+
+// Build-time injection: table-layout slides with > 4 rows get a
+// `style="--table-scale: X"` attribute baked into the slide directive. CSS
+// multiplies cell font-size AND cell padding by this var so both shrink
+// together (font-only shrinking is dampened by static padding). Linear from
+// 1.0 at 4 rows to 0.6 at ≥10 rows. Mirrors `injectCodeScale`.
+function injectTableScale(slideMarkdown: string): string {
+  const layoutRe = /<!--\s*\.slide:\s*data-layout="table"([^>]*)-->/i;
+  const layoutMatch = layoutRe.exec(slideMarkdown);
+  if (!layoutMatch) return slideMarkdown;
+
+  // Count markdown table rows (lines starting with `|`) excluding the
+  // separator (`| --- | --- |`) which doesn't render as a row.
+  const sepRe = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/;
+  let rows = 0;
+  for (const line of slideMarkdown.split("\n")) {
+    if (/^\s*\|/.test(line) && !sepRe.test(line)) rows++;
+  }
+  if (rows <= 4) return slideMarkdown;
+
+  const scale = Math.max(0.6, 1 - (rows - 4) * 0.067).toFixed(2);
+  const extras = layoutMatch[1].replace(/\s+style="--table-scale:\s*[^"]+"/i, "").trim();
+  const attrs = extras
+    ? `${extras} style="--table-scale: ${scale}"`
+    : `style="--table-scale: ${scale}"`;
+  const newDirective = `<!-- .slide: data-layout="table" ${attrs} -->`;
+  return slideMarkdown.replace(layoutMatch[0], newDirective);
+}
+
 async function buildConcat(deckDir: string): Promise<string> {
   const slidesDir = join(deckDir, "slides");
   if (await exists(slidesDir)) {
@@ -73,7 +195,8 @@ async function buildConcat(deckDir: string): Promise<string> {
       throw new Error(`slides/ is empty at ${slidesDir}`);
     }
     const parts = await Promise.all(files.map((f) => readText(join(slidesDir, f))));
-    return `${parts.map((p) => p.trim()).join("\n\n---\n\n")}\n`;
+    const joined = `${parts.map((p) => injectTableScale(injectCodeScale(p.trim()))).join("\n\n---\n\n")}\n`;
+    return rewriteImageRefsForConcat(joined);
   }
   const legacy = join(deckDir, "content.md");
   if (await exists(legacy)) {
@@ -90,7 +213,7 @@ async function main() {
   }
   const deckDir = resolve(argv[0]);
 
-  let outRoot = process.cwd();
+  let outRoot = deckDir;
   let force = false;
   for (let i = 1; i < argv.length; i++) {
     if (argv[i] === "--out") outRoot = resolve(argv[++i]);
@@ -110,7 +233,10 @@ async function main() {
   }
 
   const slug = deckSlug(deckDir);
-  const outDir = join(outRoot, slug);
+  // When --out is the deck-dir itself (the default), write directly into it —
+  // no extra <slug>/ subdir. Otherwise create the subdir so multiple decks
+  // can coexist under one shared --out.
+  const outDir = resolve(outRoot) === deckDir ? deckDir : join(outRoot, slug);
   const concatPath = join(outDir, `${slug}.md`);
   const htmlPath = join(outDir, `${slug}.html`);
 
@@ -145,7 +271,7 @@ async function main() {
   const skeleton = await readText(join(THEME_BASE, "skeleton.html"));
   const revealCss = await readText(join(VENDOR_REVEAL, "reveal.css"));
   const highlightCss = await readText(
-    join(VENDOR_REVEAL, "plugin", "highlight", "monokai.css")
+    join(VENDOR_REVEAL, "plugin", "highlight", "github-dark.css")
   );
   const revealJs = await readText(join(VENDOR_REVEAL, "reveal.js"));
   const markdownJs = await readText(
@@ -156,7 +282,11 @@ async function main() {
   );
   const notesJs = await readText(join(VENDOR_REVEAL, "plugin", "notes", "notes.js"));
 
-  const contentMd = await readFile(concatPath, "utf8");
+  // Read the concat back from disk, then inline image refs as data: URIs so
+  // the HTML is self-contained. The on-disk concat keeps plain `assets/X` paths
+  // for direct markdown preview; only the HTML embeds full image bytes.
+  const contentMdRaw = await readFile(concatPath, "utf8");
+  const contentMd = await inlineImagesInMarkdown(contentMdRaw, deckDir);
 
   let deckOverridesCss = "";
   const overridesPath = join(deckDir, "overrides.css");