portable-agent-layer 0.26.1 → 0.27.1

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

@@ -1,12 +1,14 @@
 ---
 name: create-pdf
-description: Convert markdown files into a styled PDF report using md-to-pdf. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf.
+description: Convert markdown files into a styled PDF. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf.
 argument-hint: <file paths, glob pattern, or directory containing .md files>
 ---
 
 ## Overview
 
-Combine one or more markdown files into a single styled PDF using `bunx --bun md-to-pdf`. This skill handles concatenation, page breaks, styling, and conversion. It does NOT generate content — use the `research` skill or other content-generation workflows first, then pipe the resulting markdown files into this skill.
+Combine one or more markdown files into a single styled PDF. Pipeline: Markdown → HTML → PDF via a headless browser.
+
+This skill handles concatenation, page breaks, styling, and conversion. It does NOT generate content — use the `research` skill or other content-generation workflows first, then pipe the resulting markdown files into this skill.
 
 ## Input
 
@@ -26,9 +28,11 @@ Determine the list of markdown files and their order:
 - If glob/directory: list and sort alphabetically (files prefixed with `00_` come first naturally)
 - Confirm the file list and order with the user if more than 5 files
 
-### Step 2: Combine with Page Breaks
+### Step 2: Combine (only if multiple files)
+
+For a single input file, skip this step and pass it directly to the tool in Step 3.
 
-Concatenate all files with page break dividers between them:
+For multiple files, concatenate with page break dividers between them into a single temp markdown:
 
 ```bash
 cat \
@@ -37,83 +41,70 @@ cat \
   second_file.md \
   <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
   third_file.md \
-  ... \
-  > /tmp/combined_raw.md
+  > /tmp/combined.md
 ```
 
 For many files, generate the cat command dynamically rather than typing each one.
 
-### Step 3: Add PDF Frontmatter
+### Step 3: Render to PDF
 
-Prepend YAML frontmatter with styling, then append the combined content:
+Invoke the skill tool. Flags:
+- `--pdf <path>` — explicit output PDF path (default: `<input_basename>.pdf` next to the input)
+- `--html <path>` — explicit intermediate HTML path (default: `<input_basename>.html` next to the input; kept for inspection/re-printing)
 
-```bash
-cat > <output_name>.md << 'FRONTMATTER'
----
-pdf_options:
-  format: A4
-  margin: 25mm
-  printBackground: true
-stylesheet: https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown.css
-body_class: markdown-body
-css: |-
-  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; font-size: 11px; line-height: 1.6; color: #1a1a1a; }
-  h1 { font-size: 22px; border-bottom: 2px solid #333; padding-bottom: 8px; }
-  h2 { font-size: 17px; }
-  h3 { font-size: 14px; }
-  table { border-collapse: collapse; width: 100%; margin: 12px 0; }
-  th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; font-size: 10px; }
-  th { background: #f0f0f0; }
-  blockquote { border-left: 3px solid #666; padding-left: 12px; color: #444; }
-  hr { border: none; border-top: 1px solid #ccc; margin: 20px 0; }
-  a { color: #0366d6; text-decoration: none; }
----
+Single-file example:
 
-FRONTMATTER
-cat /tmp/combined_raw.md >> <output_name>.md
+```bash
+bun ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts /path/to/report.md --pdf /path/to/report.pdf
 ```
 
-The user may request custom styling (font size, margins, colors). Override the defaults above accordingly.
-
-### Step 4: Generate PDF
+Multi-file example (after Step 2):
 
 ```bash
-bunx --bun md-to-pdf <output_name>.md
+bun ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts /tmp/combined.md --pdf /path/to/report.pdf --html /path/to/report.html
 ```
 
-### Step 5: Verify and Report
+The tool writes the self-contained HTML (inline CSS, UTF-8) and the PDF, and prints both paths + sizes on stdout.
+
+### Step 4: Verify and Report
 
 ```bash
-ls -lh <output_name>.pdf
+ls -lh <output>.pdf
 ```
 
 Report the file path and size to the user.
 
+## Styling
+
+Default styling (A4, 25mm margins, GitHub-ish look, table-friendly, page-break-aware headings) is baked into the tool. To customize, edit `tools/md-to-html-pdf.ts` — the `css` string and the `page.pdf({...})` options live side-by-side so fonts, colors, margins, or header/footer templates can be tuned in one place.
+
+For header/footer templates (page numbers, client name, CONFIDENTIAL markings, etc.), extend `page.pdf` with `displayHeaderFooter`, `headerTemplate`, and `footerTemplate` — do NOT combine with CSS `@page` margin-box rules, which duplicate.
+
 ## Translation Variant
 
 If the user asks to translate markdown files and then create a PDF:
 
-1. Spawn **parallel subagents** to translate files — batch 2-4 files per agent, all agents in a **single message**
+1. Spawn **parallel subagents** to translate files — batch 2-4 files per agent, all agents in a **single message** (skip parallelism when there is only one file; a single coherent translator is faster and more consistent)
 2. Each agent reads the source file, translates all text content to the target language, and writes to `<original_name>_<lang>.md`
 3. Rules for translation agents:
    - Keep all markdown formatting, links, and structure identical
    - Keep source/link titles in their original language; translate surrounding text
    - Translate naturally, not word-for-word; use proper domain terminology
-4. After all agents complete, run Steps 2-5 above on the translated files
+4. After all agents complete, run Steps 2-4 above on the translated files
 5. Output filename gets a `_<lang>` suffix (e.g., `report_hu.pdf`)
 
 **Batch sizing for translation agents:**
 
 | Files | Agents | Files per agent |
 |-------|--------|-----------------|
-| 1-4   | 1-2    | 2 each          |
+| 1     | 0      | done inline     |
+| 2-4   | 1-2    | 2 each          |
 | 5-10  | 3-4    | 2-3 each        |
 | 11+   | 5      | 3-4 each        |
 
 ## Important
 
-- Use `bunx --bun md-to-pdf` (NOT npx) for PDF conversion
 - This skill only converts — it does not research or generate content
 - Individual markdown files are preserved alongside the PDF for future editing
-- If `md-to-pdf` is not installed, `bunx` will auto-install it on first run
+- The intermediate HTML is also preserved — open it in a browser to inspect or Print-to-PDF manually
 - Always verify the PDF exists before reporting success

package/assets/skills/create-pdf/tools/md-to-html-pdf.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+// create-pdf skill tool: Markdown -> HTML (marked, GFM) -> PDF (Playwright).
+// Self-contained HTML: all CSS inlined, no CDN at render time.
+//
+// Usage:
+//   bun ~/.pal/skills/create-pdf/tools/md-to-html-pdf.ts <input.md> [--html <out.html>] [--pdf <out.pdf>]
+
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, resolve } from "node:path";
+import { marked } from "marked";
+import { chromium } from "playwright";
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error("usage: md-to-html-pdf.ts <input.md> [--html <out>] [--pdf <out>]");
+  process.exit(1);
+}
+
+const input = resolve(args[0]);
+let htmlOut = "";
+let pdfOut = "";
+for (let i = 1; i < args.length; i++) {
+  if (args[i] === "--html") htmlOut = resolve(args[++i]);
+  else if (args[i] === "--pdf") pdfOut = resolve(args[++i]);
+}
+const stem = basename(input, extname(input));
+const dir = dirname(input);
+if (!htmlOut) htmlOut = resolve(dir, `${stem}.html`);
+if (!pdfOut) pdfOut = resolve(dir, `${stem}.pdf`);
+
+const md = await readFile(input, "utf8");
+marked.setOptions({ gfm: true, breaks: false });
+const body = await marked.parse(md);
+
+const css = `
+html { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  font-size: 11px; line-height: 1.6; color: #1a1a1a; margin: 0;
+}
+h1 { font-size: 22px; border-bottom: 2px solid #333; padding-bottom: 8px; margin-top: 0; }
+h2 { font-size: 17px; margin-top: 1.6em; }
+h3 { font-size: 14px; }
+h1, h2, h3, h4 { page-break-after: avoid; }
+p, li { orphans: 3; widows: 3; }
+hr { border: none; border-top: 1px solid #ccc; margin: 20px 0; }
+a { color: #0366d6; text-decoration: none; }
+blockquote { border-left: 3px solid #666; padding-left: 12px; color: #444; margin: 12px 0; }
+code { background: #f4f4f4; padding: 1px 4px; border-radius: 3px; font-size: 10px; }
+pre { background: #f4f4f4; padding: 10px; border-radius: 4px; overflow-x: auto; }
+pre code { background: transparent; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 12px 0; page-break-inside: avoid; }
+th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; font-size: 10px; vertical-align: top; }
+th { background: #f0f0f0; }
+tr { page-break-inside: avoid; }
+ul, ol { padding-left: 1.4em; }
+`;
+
+const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>${stem}</title>
+<style>${css}</style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+
+await writeFile(htmlOut, html, "utf8");
+
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage();
+  await page.goto(`file://${htmlOut}`, { waitUntil: "networkidle" });
+  await page.pdf({
+    path: pdfOut,
+    format: "A4",
+    margin: { top: "25mm", right: "25mm", bottom: "25mm", left: "25mm" },
+    printBackground: true,
+    preferCSSPageSize: false,
+  });
+} finally {
+  await browser.close();
+}
+
+const [htmlStat, pdfStat] = await Promise.all([stat(htmlOut), stat(pdfOut)]);
+console.log(`HTML: ${htmlOut} (${(htmlStat.size / 1024).toFixed(1)} KB)`);
+console.log(`PDF:  ${pdfOut} (${(pdfStat.size / 1024).toFixed(1)} KB)`);

package/assets/skills/think/SKILL.md

@@ -10,10 +10,10 @@ Route $ARGUMENTS to the right thinking mode based on intent. Detect the mode fro
 
 | Intent signals | Mode | How to invoke |
 |---------------|------|---------------|
-| decompose, root cause, fundamental, challenge assumptions, first principles | **First Principles** | Use the Skill tool to invoke `first-principles` with $ARGUMENTS |
-| debate, weigh options, multiple viewpoints, perspectives, deliberate | **Council** | Use the Skill tool to invoke `council` with $ARGUMENTS |
-| brainstorm, creative, divergent, ideas, what if, possibilities | **Creative** | Follow the Creative steps below with $ARGUMENTS |
-| think through, analyze, explore deeply, examine from angles | **Deep Analysis** | Follow the Deep Analysis steps below with $ARGUMENTS |
+| decompose, root cause, fundamental, challenge assumptions, first principles, why is X happening | **First Principles** | Use the Skill tool to invoke `first-principles` with $ARGUMENTS |
+| debate, weigh options, multiple viewpoints, perspectives, deliberate, should I, which is better | **Council** | Use the Skill tool to invoke `council` with $ARGUMENTS |
+| brainstorm, creative, divergent, ideas, what if, possibilities, how could we, make it better | **Creative** | Follow the Creative steps below with $ARGUMENTS |
+| think through, analyze, explore deeply, examine from angles, tradeoffs, what are the implications | **Deep Analysis** | Follow the Deep Analysis steps below with $ARGUMENTS |
 
 If intent is ambiguous, default to **Deep Analysis**.
 
@@ -39,9 +39,72 @@ Divergent ideation — quantity and variety over polish.
 
 Multi-angle exploration for complex topics.
 
-1. **Frame the question** precisely
+1. **Frame the question** precisely — what is actually being asked?
 2. **Technical** — mechanics, constraints, and trade-offs
-3. **Practical** — what does this look like in practice? What's the effort?
+3. **Practical** — what does this look like in practice? What's the effort and friction?
 4. **Strategic** — how does this fit the bigger picture? What does it enable or block?
-5. **Tensions** — where do the angles disagree?
+5. **Tensions** — where do the angles disagree? What can't be optimized simultaneously?
 6. **Synthesis** — what the analysis reveals that wasn't obvious at the surface
+
+---
+
+## Examples
+
+**Example 1 → First Principles**
+```
+User: "why is our test suite so slow?"
+→ Intent: root cause, decompose
+→ Invoke first-principles: "Why is the test suite slow?"
+→ Break down: what makes tests slow? → I/O, parallelism, fixtures, network calls
+→ Challenge each assumption: are all these tests necessary? Is the slowness uniform?
+```
+
+**Example 2 → Council**
+```
+User: "should we use a monorepo or separate repos?"
+→ Intent: debate, weigh options
+→ Invoke council with the question
+→ Multiple perspectives argue in parallel, then synthesize
+```
+
+**Example 3 → Creative**
+```
+User: "how could we make onboarding more engaging?"
+→ Intent: brainstorm, possibilities
+→ Restate: "How do we make first-run onboarding feel less like a form?"
+→ Obvious: wizard steps, progress bar, skip option
+→ Wild: game mechanic for first task, video from the AI, co-pilot mode for first session
+→ Diamond pick: co-pilot mode — high novelty, directly addresses the friction
+```
+
+**Example 4 → Deep Analysis**
+```
+User: "what are the tradeoffs of server-side rendering?"
+→ Intent: explore tradeoffs, implications
+→ Technical: hydration cost, TTFB vs TTI, caching strategies
+→ Practical: team expertise, deployment complexity, SEO requirements
+→ Strategic: enables progressive enhancement, constrains client-side interactivity
+→ Tensions: performance vs interactivity, simplicity vs capability
+→ Synthesis: SSR is a distribution of complexity, not a removal of it
+```
+
+---
+
+## Anti-patterns
+
+- **Don't ask which mode to use.** Detect from context and commit. The routing table is the decision — use it.
+- **Don't use Deep Analysis as the default for everything.** "Should I do X or Y?" is Council. "Why is X broken?" is First Principles. Reserve Deep Analysis for genuine multi-angle exploration.
+- **Don't produce shallow Creative output.** Wild ideas must genuinely challenge constraints — listing 5 obvious variations is not creative thinking.
+- **Don't skip the Tensions section in Deep Analysis.** If you can't find a tension, you haven't analyzed deeply enough.
+- **Don't combine modes in one response.** Pick one and commit. Mixing modes produces unfocused output.
+- **Don't over-explain the routing.** One line is enough: "This is a root-cause question — First Principles." Then do the work.
+
+---
+
+## Rules
+
+- **Mode detection is mandatory** — classify before starting, state it in one line
+- **First Principles and Council are delegated** — always invoke those skills rather than reimplementing them
+- **Creative and Deep Analysis run inline** — follow the steps above directly
+- **Tensions are non-negotiable in Deep Analysis** — name at least one real conflict between the angles
+- **Wild ideas in Creative must be genuinely unconventional** — if a PM would have thought of it in 30 seconds, it's not wild enough

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -76,6 +76,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "adm-zip": "^0.5.16"
+    "adm-zip": "^0.5.16",
+    "marked": "^15.0.0",
+    "playwright": "^1.49.0"
   }
 }

package/src/cli/index.ts

@@ -338,6 +338,24 @@ function checkCopilotInstructionsPresent(): boolean {
   return existsSync(resolve(platform.copilotDir(), "copilot-instructions.md"));
 }
 
+function playwrightBrowsersPath(): string {
+  if (process.env.PLAYWRIGHT_BROWSERS_PATH) return process.env.PLAYWRIGHT_BROWSERS_PATH;
+  const home = homedir();
+  if (process.platform === "darwin") return resolve(home, "Library/Caches/ms-playwright");
+  if (process.platform === "win32") return resolve(home, "AppData/Local/ms-playwright");
+  return resolve(home, ".cache/ms-playwright");
+}
+
+function checkPlaywrightChromium(): boolean {
+  const base = playwrightBrowsersPath();
+  if (!existsSync(base)) return false;
+  try {
+    return readdirSync(base).some((f) => f.startsWith("chromium-"));
+  } catch {
+    return false;
+  }
+}
+
 function checkHookHealth(home: string): HookHealth {
   const logPath = resolve(home, "memory", "state", "debug.log");
 
@@ -509,6 +527,13 @@ function doctor(silent = false): DoctorResult {
       ? ok("Dependencies installed")
       : fail("Dependencies missing — run 'pal cli install'");
 
+    // Playwright Chromium (required by create-pdf + consulting-report skills)
+    checkPlaywrightChromium()
+      ? ok("Playwright Chromium installed")
+      : fail(
+          "Playwright Chromium — not found (run 'pal cli install' or 'bunx playwright install chromium')"
+        );
+
     // Hook registration (per installed agent)
     if (claude.available) {
       checkClaudeHooksRegistered()
@@ -607,6 +632,24 @@ async function install(targets: Targets) {
     log.warn("bun install failed — continuing anyway, but hooks may not work");
   }
 
+  // Fetch the Chromium build Playwright uses for PDF rendering (create-pdf skill).
+  // Idempotent — skipped if already cached. Skipped entirely under PAL_SKIP_BROWSER_INSTALL=1
+  // (used by tests to avoid a ~150MB download on every run).
+  // Uses `bun x` (not `bunx`) for Windows compatibility — bunx resolves unreliably under cmd.exe.
+  if (process.env.PAL_SKIP_BROWSER_INSTALL !== "1") {
+    log.info("Installing Playwright Chromium...");
+    const pw = spawnSync("bun", ["x", "playwright", "install", "chromium"], {
+      cwd: pkg,
+      stdio: "inherit",
+      shell: true,
+    });
+    if (pw.status !== 0) {
+      log.warn(
+        `playwright install chromium failed (exit ${pw.status}) — create-pdf and consulting-report skills won't work. Retry manually: bun x playwright install chromium`
+      );
+    }
+  }
+
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");