portable-agent-layer 0.34.0 → 0.35.0

package/assets/skills/presentation/SKILL.md

@@ -103,6 +103,8 @@ Exit codes: `0` = clean, `1` = errors found (or warnings under `--strict`), `2`
 
 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.
 
+**Print / PDF view with trainer notes.** Open the built HTML in your browser and press Cmd/Ctrl-P (no special URL param needed). The print stream interleaves trainer notes between slides — `[Slide 1][Notes 1][Slide 2][Notes 2]…` — so flipping pages reads in delivery order. Long notes flow across multiple pages. Slides without a `Note:` block produce no extra page. Each notes page carries a header identifying the source slide. Limitation: a single fenced code block inside notes cannot break across pages — the doctor warns at 30 lines (`notes-code-too-long`); split the block or shorten the example.
+
 ## Deck folder layout
 
 ```

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

@@ -9,4 +9,30 @@ The default. Title at top, body below.
   - 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.
+Note:
+- [Reveal.js print docs](https://revealjs.com/pdf-export/)
+- Why this slide demonstrates print-with-notes
+  - Long enough to cross a page break in the trainer print-out
+  - Mixes link, bullet hierarchy, blockquote, inline code
+  - Lets you verify the multi-page flow without authoring a fixture deck
+- Default layout — when to leave it off
+  - You want title + body, no special shape
+  - You want the layout-agnostic spacing rules to kick in
+  - You want the doctor to skip layout-shape checks
+- Bullet hygiene reminder (per SKILL.md)
+  - 2–15 words at top level, 2–10 at sub
+  - No prose paragraphs — the `prose-paragraph-in-body` rule will warn
+  - Em-dash continuation in bullets is also flagged
+- Quote example
+  > Slides are a delivery surface, not a document. Prose belongs in notes.
+- Anticipated questions
+  - "Why a 30-line cap on notes code blocks?" — single `<pre>` blocks don't break across printed pages; longer blocks clip
+  - "Can I disable the trainer-notes printout?" — yes, remove the notes injection block from the `.then()` in skeleton.html in your local override
+  - "Does the speaker view (S key) still work?" — yes, the injection only affects print, not the speaker view path
+- Forward references
+  - more on layout-specific rules in the `code` and `table` slides
+  - more on print-view polish in `base.css` under "Trainer notes in print"
+- Closing beats
+  - The print-with-notes feature exists so a trainer can hand a delegate a printed deck and a printed prep packet at once
+  - Ordering is `[Slide 1][Notes 1][Slide 2][Notes 2]…` so flipping pages reads in delivery order
+  - Slides without a `Note:` block produce zero extra pages — title cards stay clean

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

@@ -436,3 +436,209 @@ html.print-pdf .reveal .slides .pdf-page {
     margin: 16px auto !important;
   }
 }
+
+/* ── Trainer notes in print (Cmd+P on the regular URL)
+ * skeleton.html injects a `.print-notes-page` div after each slide section that
+ * has speaker notes. On screen they are invisible; Cmd+P produces the ordering
+ * [Slide N][Notes N][Slide N+1][Notes N+1]…. Long notes flow across multiple
+ * pages. Slides with no Note: block produce no extra page.
+ *
+ * Key mechanics:
+ *   • `page-break-after: always` on sections forces each slide to end at a page
+ *     boundary even if its content is shorter than the page height.
+ *   • `page-break-before/after: always` on .print-notes-page ensures the notes
+ *     block starts on a fresh page and the next slide starts on a fresh page.
+ *   • `break-inside: auto` lets long notes flow across pages naturally. */
+@media print {
+  html:not(.print-pdf) .reveal .slides > section {
+    page-break-after: always !important;
+    break-after: always !important;
+  }
+
+  html:not(.print-pdf) .reveal .slides > .print-notes-page {
+    display: block !important;
+    page-break-before: always !important;
+    break-before: always !important;
+    page-break-after: always !important;
+    break-after: always !important;
+    page-break-inside: auto;
+    break-inside: auto;
+    overflow: visible !important;
+    position: static !important;
+    min-height: 0 !important;
+    padding: 36px 56px 56px 56px;
+    box-sizing: border-box;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+      "Helvetica Neue", Arial, sans-serif;
+    font-size: 13pt;
+    line-height: 1.5;
+    color: #111;
+    background: #fff;
+  }
+
+  html:not(.print-pdf) .reveal .slides > .print-notes-page ul,
+  html:not(.print-pdf) .reveal .slides > .print-notes-page ol {
+    margin: 0.4em 0 0.8em 0;
+    padding-left: 1.4em;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page li {
+    margin: 0.15em 0;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page a {
+    color: var(--brand-primary, #0040c2);
+    text-decoration: underline;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page code {
+    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+    font-size: 0.92em;
+    background: #f4f4f4;
+    padding: 1px 4px;
+    border-radius: 3px;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page pre {
+    font-size: 0.92em;
+    line-height: 1.4;
+    background: #f4f4f4;
+    padding: 8px 12px;
+    border-radius: 4px;
+    white-space: pre-wrap;
+    overflow: visible;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page blockquote {
+    margin: 0.6em 0 0.6em 1em;
+    padding-left: 0.8em;
+    border-left: 2px solid #a0a0a0;
+    color: #444;
+    font-style: italic;
+  }
+
+  /* Slide-context header: "Notes — slide N  <slide title>" */
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-header {
+    display: flex;
+    align-items: baseline;
+    gap: 0.8em;
+    margin: 0 0 24px 0;
+    padding: 0 0 10px 0;
+    border-bottom: 1.5pt solid var(--brand-primary, #0040c2);
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-label {
+    font-size: 11pt;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: var(--brand-primary, #0040c2);
+    white-space: nowrap;
+  }
+  html:not(.print-pdf) .reveal .slides > .print-notes-page .print-notes-title {
+    font-size: 13pt;
+    font-weight: 500;
+    color: #222;
+  }
+}
+
+/* ── Per-slide print chrome (logo + slide number)
+ * skeleton.html injects `.print-logo` and `.print-slide-number` into every
+ * section. On screen: invisible. In Cmd+P print: positioned at the same
+ * bottom corners as the screen-mode chrome, once per slide page.
+ *
+ * The screen-mode equivalents (.slides::after logo and .slides > .slide-number)
+ * are suppressed in print because they are positioned relative to .slides — a
+ * container that spans all pages in Cmd+P mode, putting them at the very end
+ * of the document rather than on each individual slide. */
+@media print {
+  /* Suppress the screen-mode global chrome */
+  html:not(.print-pdf) .reveal .slides::after,
+  html:not(.print-pdf) .reveal .slides > .slide-number {
+    display: none !important;
+  }
+
+  /* Sections must be position:relative so absolute children anchor to the
+   * slide page, not to the full-document .slides container. */
+  html:not(.print-pdf) .reveal .slides > section {
+    position: relative !important;
+    /* Ensure background images (logos) print on all browsers. */
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+
+  html:not(.print-pdf) .reveal .slides > section .print-logo {
+    display: block !important;
+    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;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+
+  html:not(.print-pdf) .reveal .slides > section .print-slide-number {
+    display: block !important;
+    position: absolute;
+    bottom: 1.5rem;
+    left: 1.5rem;
+    font-family: var(--font-body, sans-serif);
+    font-size: 9pt;
+    font-weight: 400;
+    line-height: 28px;
+    color: #71717A;
+    letter-spacing: 0.05em;
+    pointer-events: none;
+  }
+}
+
+/* ── Layout-specific print overrides
+ * Reveal's vendored print CSS forces several properties with !important on
+ * heading and paragraph elements, which clobbers layout-specific design intent:
+ *   • h1-h6: font-size (28–20pt), color (#000), text-align (left),
+ *             letter-spacing (normal), line-height (normal)
+ *   • p, li, td: font-size (20pt), color (#000)
+ *
+ * We beat these by pairing higher-specificity selectors with !important.
+ * Reveal's rules are scoped to `html:not(.print-pdf) .reveal h1` — specificity
+ * (0,2,1). Our layout-scoped rules use `html:not(.print-pdf) .reveal
+ * section[data-layout="…"] h1` — specificity (0,3,2), which wins. */
+@media print {
+  /* big-stat — restore the dominant number that Reveal shrinks to 28pt */
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] h1 {
+    font-size: 96pt !important;
+    color: var(--brand-primary, #0E1335) !important;
+    text-align: center !important;
+    letter-spacing: -0.025em !important;
+    line-height: 0.9 !important;
+    font-weight: 800 !important;
+    -webkit-print-color-adjust: exact !important;
+    print-color-adjust: exact !important;
+  }
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] h2,
+  html:not(.print-pdf) .reveal section[data-layout="big-stat"] p {
+    color: #71717A !important;
+    text-align: center !important;
+    font-weight: 400 !important;
+  }
+
+  /* quote / pull-quote — Reveal forces p { font-size: 20pt !important }, but
+   * blockquote text lives in p elements. `inherit` re-derives the size from the
+   * blockquote element (var(--text-xl) / var(--text-2xl)), restoring design intent. */
+  html:not(.print-pdf) .reveal section[data-layout="quote"] blockquote p,
+  html:not(.print-pdf) .reveal section[data-layout="pull-quote"] blockquote p {
+    font-size: inherit !important;
+    color: inherit !important;
+  }
+}
+
+/* Screen: injected notes pages are invisible. The `@media print` block above
+ * restores display:block. Using !important because Reveal may globally set
+ * visibility rules on .slides children. */
+@media screen {
+  .reveal .slides > .print-notes-page,
+  .reveal .slides > section .print-logo,
+  .reveal .slides > section .print-slide-number {
+    display: none !important;
+  }
+}

package/assets/skills/presentation/theme-base/skeleton.html

@@ -47,6 +47,55 @@ Reveal.initialize({
   const sn = document.querySelector('.reveal > .slide-number');
   const slides = document.querySelector('.reveal .slides');
   if (sn && slides) slides.appendChild(sn);
+
+  // Inject print-only chrome (logo + slide number) into every section, and a
+  // `.print-notes-page` after each section that has notes. All injected elements
+  // are display:none on screen; Cmd+P produces [Slide N][Notes N]… ordering.
+  const sections = document.querySelectorAll('.reveal .slides > section');
+  const totalSlides = sections.length;
+  let slideNum = 0;
+  for (const section of sections) {
+    slideNum++;
+
+    const logoEl = document.createElement('div');
+    logoEl.className = 'print-logo';
+    section.appendChild(logoEl);
+
+    const numEl = document.createElement('div');
+    numEl.className = 'print-slide-number';
+    numEl.textContent = `${slideNum} / ${totalSlides}`;
+    section.appendChild(numEl);
+
+    const notesEl = section.querySelector('aside.notes');
+    if (!notesEl?.innerHTML.trim()) continue;
+
+    const heading = section.querySelector('h1, h2, h3');
+    const title = heading ? heading.textContent.trim() : '';
+
+    const page = document.createElement('div');
+    page.className = 'print-notes-page';
+
+    const hdr = document.createElement('header');
+    hdr.className = 'print-notes-header';
+    const label = document.createElement('span');
+    label.className = 'print-notes-label';
+    label.textContent = `Notes — slide ${slideNum}`;
+    hdr.appendChild(label);
+    if (title) {
+      const titleSpan = document.createElement('span');
+      titleSpan.className = 'print-notes-title';
+      titleSpan.textContent = title;
+      hdr.appendChild(titleSpan);
+    }
+    page.appendChild(hdr);
+
+    const body = document.createElement('div');
+    body.className = 'print-notes-content';
+    body.innerHTML = notesEl.innerHTML;
+    page.appendChild(body);
+
+    section.insertAdjacentElement('afterend', page);
+  }
 });
 </script>
 </body>

package/assets/skills/presentation/tools/lib/lint-rules.ts

@@ -632,6 +632,31 @@ export const RULES: Rule[] = [
     },
   },
 
+  {
+    // Notes get printed as separate pages with `showNotes: 'separate-page'`.
+    // Browsers split long *list* content across pages cleanly, but a single
+    // fenced code block inside notes is one indivisible element — if it runs
+    // longer than one printed page it gets clipped. Warn at 30 lines so the
+    // author can split or shorten before the trainer discovers it on paper.
+    name: "notes-code-too-long",
+    scope: "slide",
+    check: (ctx) => {
+      const notes = extractNotes(ctx.body);
+      if (!notes.trim()) return [];
+      const findings: Finding[] = [];
+      for (const n of codeBlockLineCounts(notes)) {
+        if (n > 30) {
+          findings.push({
+            rule: "notes-code-too-long",
+            severity: "W",
+            msg: `notes code block has ${n} lines — won't break across printed pages cleanly (limit 30)`,
+          });
+        }
+      }
+      return findings;
+    },
+  },
+
   // ── Deck-scope rules (Tier 3) ───────────────────────────────────────────
 
   {

package/assets/templates/AGENTS.md.template

@@ -55,6 +55,7 @@ Start your response with the following header in this mode:
 
 - **Mandatory output format** — Every response MUST use exactly one of the output formats above (ALGORITHM, NATIVE, or MINIMAL). No freeform output.
 - **Response format before questions** — Always complete the current response format output FIRST, then invoke AskUserQuestion at the end.
+- **Named project → resume first** — Whenever the user references a project by name in ANY mode, run `bun ~/.pal/tools/project.ts resume <slug>` before any file search or task execution. The project record has paths, context, and handoff notes that make manual searching unnecessary.
 
 ---
 
@@ -73,7 +74,7 @@ Load context on-demand by reading the file at the path listed. Only load what th
 | Opinion tracking | `~/.pal/docs/OPINION_TRACKING.md` |
 | Steering rules | `~/.pal/docs/STEERING_RULES.md` |
 | Algorithm (complex work phases) | `~/.pal/docs/ALGORITHM.md` |
-| Project lifecycle (when/how to register and manage user projects) | `~/.pal/skills/projects/SKILL.md` |
+| Project lookup AND lifecycle (find paths, resume state, register, manage) | `~/.pal/skills/projects/SKILL.md` |
 
 ### User Context (TELOS)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {