portable-agent-layer 0.30.1 → 0.32.0

package/assets/skills/consulting-report/SKILL.md

@@ -1,115 +1,115 @@
 ---
 name: consulting-report
-description: Produce branded consulting-report PDFs from a structured report directory (cover page, linked TOC, headers/footers with page numbers, typography system, callout boxes, findings + recommendations). Use when generating an assessment report, strategic review, or consulting deliverable PDF.
-argument-hint: <report-dir> OR `scaffold <target-dir>` to start a new report
+description: Build a beautifully-typeset consulting-report PDF from a typed data file and a React layout. Use when generating an assessment, strategic review, operational readiness check, or any McKinsey-style consulting deliverable as a PDF.
+argument-hint: scaffold <target-dir> | dev <report-dir> | <report-dir> (render PDF)
 ---
 
 ## Overview
 
-Renders a structured consulting-report directory to a branded PDF: cover page, linked table of contents, page-numbered headers/footers, typography system (Georgia body + Inter headings), colored callout boxes for findings and recommendations, tables with zebra striping.
-
-Each report lives in its own directory with data (TypeScript) + narrative (Markdown) + diagrams (images). The skill provides a scaffolder to spin up new reports from a template and a generator to render them.
-
-**Default brand:** Konvert7. Override per report via the `brand` block in `report-data.ts`.
-
-## Report Directory Layout
-
-```
-<report-dir>/
-├── content/
-│   ├── report-data.ts          # report structure (schema: ConsultingReport)
-│   ├── executive-summary.md    # narrative sections
-│   └── …
-├── diagrams/                   # source images (PNG/JPG)
-├── diagrams-compressed/        # generated — ignore
-└── <client>-<title>-<date>.{pdf,html}  # output
-```
+Every report is a self-contained Next.js app: typed report data in `lib/report-data.ts`, layout composed from React components in `app/page.tsx`, fonts via `next/font/google` (Source Serif 4 + Inter), Tailwind v4 for styling. `bun run dev` gives a live preview while authoring; the PDF is rendered by Playwright against a static export.
 
 ## Workflow
 
-### Step 1: Scaffold a new report (skip if the report directory already exists)
+### 1. Scaffold a new report
 
 ```bash
 bun ~/.pal/skills/consulting-report/tools/scaffold.ts <target-dir> \
-  --client "Client Name" \
-  --title "Report Title"
+  [--client "Client Name"] [--title "Report Title"] [--no-install]
 ```
 
-Creates the directory, stamps today's date + client + title into `report-data.ts`, and writes a starter `executive-summary.md`. If the target directory already exists, the command errors — move or remove first.
+Creates `<target-dir>` from the template and runs `bun install` inside. If `--client` / `--title` are passed, they're stamped into `lib/report-data.ts`. The scaffolder refuses to overwrite an existing directory.
+
+### 2. Fill in the content
 
-### Step 2: Fill in content
+Two files do the work:
 
-Edit:
+- **`lib/report-data.ts`** — typed metadata: client, title, date, classification, consultancy name, executive summary, situation assessment, findings, risk analysis, strategic opportunity, recommendations, target state, roadmap, call to action. The `ReportData` interface guides what's required.
+- **`app/page.tsx`** — the layout. Composes `<CoverPage/>`, `<Section/>`, `<Exhibit/>`, `<FindingCard/>`, `<RecommendationCard/>`, `<Callout/>`, `<Timeline/>`, etc. against the data. Edit freely — section titles, intros, ordering, custom JSX, anything.
 
-- `<dir>/content/report-data.ts` — cover metadata, sections list, optional findings / recommendations / conclusion / appendix. Each `section.content` is either an inline markdown string OR a `.md` filename relative to `content/`.
-- `<dir>/content/*.md` — the narrative sections referenced from `report-data.ts`.
-- `<dir>/diagrams/` — drop PNG/JPG images. Reference them from markdown with relative paths, e.g. `![alt](../diagrams-compressed/architecture.jpg)`.
+Static images go in `public/`; reference them from JSX as `<img src="/your-image.png">`.
 
-### Step 3: Render
+### 3. Live preview while authoring
 
 ```bash
-node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts <report-dir>
+bun ~/.pal/skills/consulting-report/tools/dev.ts <report-dir>
 ```
 
-Output: `<dir>/<client-slug>-<title-slug>-<date>.pdf` and matching `.html`. Override with `--pdf <path>` / `--html <path>`.
-
-The generator:
-- Loads `content/report-data.ts` dynamically
-- Compresses `diagrams/*` to JPEG 70% / 1200px via `sips` (macOS); silently skips if `sips` is absent
-- Renders cover, auto-generated linked TOC, sections, findings, recommendations, conclusion, appendix
-- Prints via Playwright with page-numbered header/footer templates
+Wraps `bun run dev` in the report directory. Open the URL printed by Next, edit `app/page.tsx` or `lib/report-data.ts`, browser hot-reloads.
 
-### Step 4: Verify
+### 4. Render the PDF
 
 ```bash
-ls -lh <dir>/*.pdf
+node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts <report-dir>
 ```
 
-Open the PDF. Check: cover centered and branded; TOC links jump; findings render in red/amber boxes by severity; recommendations in blue boxes with priority badges; every page has the CONFIDENTIAL footer and page number.
-
-## Report Schema
-
-```ts
-interface ConsultingReport {
-  clientName: string;
-  reportTitle: string;
-  reportDate: string;
-  classification: string;          // e.g., "CONFIDENTIAL"
-  version: string;
-  brand?: { businessName: string; brandLabel?: string; logoPath?: string; };
-  sections: Section[];
-  findings?: Finding[];            // renders as red/amber/blue boxes by severity
-  recommendations?: Recommendation[];  // blue boxes with priority badges
-  conclusion?: Conclusion;
-  supportingEvidence?: Record<string, string[]>;  // appendix
-}
-
-interface Section { id: string; title: string; content: string; subsections?: Section[]; }
-interface Finding { id: string; title: string; severity: "critical"|"high"|"medium"|"low"; evidence: string; impact?: string; }
-interface Recommendation { id: string; title: string; priority: "immediate"|"short-term"|"long-term"; detail: string; owner?: string; }
-interface Conclusion { assessorNote?: string; contextNote?: string; closingRemarks?: string; }
+Runs `next build` (which produces a static export at `out/`), then Playwright loads it via a tiny in-process HTTP server and prints the PDF with page-numbered header/footer. Output:
+
+```
+<report-dir>/<client-slug>-<title-slug>-<date>.pdf
 ```
 
-## Styling
+Override with `--pdf <path>`. Pass `--skip-build` to re-render the PDF from the existing `out/` without re-building.
 
-The typography system (Georgia body 10.5pt / Inter headings), color palette (navy #1B2A4A, blue #2E5090, red #DC2626, amber #D97706, green #059669), callout boxes, badges, table styling, cover layout, and header/footer templates are baked into `tools/generate-pdf.ts`. To customize: edit the `css()` function and the `renderPdf()` header/footer strings in one place.
+Run with **Node**, not Bun — Playwright's `chromium.launch()` hangs under Bun on Windows.
 
-Do NOT combine CSS `@page` margin-box rules with the Playwright `displayHeaderFooter` templates — they duplicate.
+## Directory Layout
 
-## Demo
+```
+<report-dir>/
+├── app/
+│   ├── layout.tsx        # font wiring (Inter + Source Serif 4)
+│   ├── page.tsx          # the report's layout — edit freely
+│   └── globals.css       # design tokens via @theme + custom CSS
+├── components/           # report primitives — edit if you need new shapes
+│   ├── cover-page.tsx
+│   ├── table-of-contents.tsx
+│   ├── section.tsx
+│   ├── exhibit.tsx
+│   ├── stat-grid.tsx
+│   ├── comparison-table.tsx
+│   ├── finding-card.tsx
+│   ├── recommendation-card.tsx
+│   ├── severity-badge.tsx
+│   ├── callout.tsx
+│   ├── quote-block.tsx
+│   └── timeline.tsx
+├── lib/
+│   ├── report-data.ts    # all your content
+│   └── utils.ts
+├── public/               # static images, optional
+├── package.json          # exact-pinned: next, react, tailwindcss, etc.
+├── tsconfig.json
+├── next.config.js
+└── postcss.config.mjs
+```
 
-A runnable demo lives at `~/.pal/skills/consulting-report/demo/`:
+## Component Cheatsheet
+
+- `<CoverPage clientName reportTitle reportDate classification consultancyName preTitle />` — full-bleed cover
+- `<TableOfContents items={[{id, title}, …]} title?>` — linked TOC, anchors to section IDs
+- `<Section id title>` — top-level section with bottom-rule heading; `id` enables TOC links
+- `<Exhibit number title source?>` — bordered card for figures, tables, side data
+- `<StatGrid stats={[{value, label, caption?}, …]} />` — large-number grid for executive summary
+- `<ComparisonTable leftLabel rightLabel rows={[{metric, left, right}, …]} metricLabel?>` — current vs. target side-by-side
+- `<FindingCard finding={f} index={i} />` — driven by `Finding` type, includes severity badge
+- `<RecommendationCard recommendation={r} index={i} />` — driven by `Recommendation` type, includes priority badge
+- `<Callout label?>` — left-rule emphasis block (default label "Key Takeaway")
+- `<QuoteBlock quote attribution role? />` — pull-quote with serif quote mark
+- `<Timeline phases={r.roadmap} />` — vertical timeline with dotted line
+- `<SeverityBadge severity />` — pill badge: critical / high / medium / low
+
+## Demo
 
 ```bash
 node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ~/.pal/skills/consulting-report/demo
 ```
 
-Inspect the produced PDF to see the full layout (cover, TOC, sections, findings, recommendations, conclusion, appendix) before writing your own report.
+Renders the bundled Acme Industries example end-to-end. Inspect the resulting PDF to see the full layout before authoring your own.
 
 ## Important
 
-- Reports live wherever you want; the skill only needs the `<report-dir>` path
-- The scaffolder refuses to overwrite an existing directory
-- Images go in `diagrams/`; reference them from markdown via `diagrams-compressed/<name>.jpg` so the compressed output is used
-- Heading anchor IDs come from `section.id` — keep them unique and slug-safe
-- Every report re-renders deterministically from source; the PDF and HTML are disposable artifacts
+- Run on Node ≥ 22.6 (Playwright + `--experimental-strip-types`)
+- Bundled fonts come from Google Fonts via `next/font/google` — no licensing surface, no CDN at runtime, glyphs embedded at build time
+- Reports are disposable artifacts of `lib/report-data.ts` + `app/page.tsx`; commit the source, not the PDF
+- The scaffolder runs `bun install` inside the target by default — pass `--no-install` to skip
+- Header/footer templates render with `displayHeaderFooter: true` in Playwright; don't combine with CSS `@page` margin-box rules

package/assets/skills/consulting-report/demo/app/globals.css

@@ -0,0 +1,459 @@
+@import "tailwindcss";
+
+@theme {
+  --color-background: #ffffff;
+  --color-background-secondary: #f8fafc;
+  --color-background-tertiary: #f1f5f9;
+  --color-background-elevated: #e2e8f0;
+
+  --color-foreground: #0f172a;
+  --color-muted: #475569;
+  --color-muted-dark: #94a3b8;
+
+  --color-border: #e2e8f0;
+  --color-border-subtle: #f1f5f9;
+  --color-border-emphasis: #cbd5e1;
+
+  --color-primary: #1d4ed8;
+  --color-accent: #7c3aed;
+  --color-success: #16a34a;
+  --color-warning: #d97706;
+  --color-destructive: #dc2626;
+
+  --color-section: #f8fafc;
+  --color-callout: #eff6ff;
+
+  --font-sans: var(--font-inter), system-ui, sans-serif;
+  --font-serif: var(--font-source-serif), Georgia, serif;
+  --font-heading: var(--font-inter), system-ui, sans-serif;
+  --font-body: var(--font-source-serif), Georgia, serif;
+}
+
+@source "./**/*.{ts,tsx}";
+@source "../components/**/*.{ts,tsx}";
+
+body {
+  font-family: var(--font-body);
+  background: var(--color-background);
+  color: var(--color-foreground);
+  line-height: 1.7;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* McKinsey-style report layout */
+.report-container {
+  max-width: 850px;
+  margin: 0 auto;
+  padding: 2rem;
+}
+
+.report-section {
+  margin-bottom: 3rem;
+  page-break-inside: avoid;
+}
+
+.report-section h2 {
+  font-family: var(--font-heading);
+  font-size: 1.75rem;
+  font-weight: 600;
+  color: var(--color-foreground);
+  margin-bottom: 1.5rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 2px solid var(--color-primary);
+}
+
+.report-section h3 {
+  font-family: var(--font-heading);
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--color-foreground);
+  margin-bottom: 1rem;
+}
+
+/* Exhibit */
+.exhibit {
+  background: var(--color-background-secondary);
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  margin: 1.5rem 0;
+}
+.exhibit-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--color-border-subtle);
+}
+.exhibit-number {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  color: var(--color-primary);
+  font-size: 0.875rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+}
+.exhibit-title {
+  font-family: var(--font-heading);
+  font-weight: 600;
+  color: var(--color-foreground);
+}
+
+/* Callout */
+.callout {
+  background: var(--color-callout);
+  border-left: 4px solid var(--color-primary);
+  padding: 1.25rem 1.5rem;
+  margin: 1.5rem 0;
+  border-radius: 0 0.5rem 0.5rem 0;
+}
+.callout-label {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  color: var(--color-primary);
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  margin-bottom: 0.5rem;
+}
+.callout-content {
+  font-size: 1.125rem;
+  font-weight: 500;
+  color: var(--color-foreground);
+}
+
+/* Quote block */
+.quote-block {
+  position: relative;
+  padding: 1.5rem 2rem;
+  margin: 1.5rem 0;
+  background: var(--color-background-secondary);
+  border-radius: 0.5rem;
+  border: 1px solid var(--color-border-subtle);
+}
+.quote-block::before {
+  content: "\201C";
+  position: absolute;
+  top: 0.5rem;
+  left: 0.75rem;
+  font-size: 3rem;
+  color: var(--color-primary);
+  opacity: 0.5;
+  font-family: Georgia, serif;
+  line-height: 1;
+}
+.quote-text {
+  font-style: italic;
+  color: var(--color-foreground);
+  font-size: 1.0625rem;
+  line-height: 1.7;
+}
+.quote-attribution {
+  margin-top: 0.75rem;
+  font-size: 0.875rem;
+  color: var(--color-muted);
+}
+
+/* Severity badges */
+.severity-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.25rem 0.75rem;
+  border-radius: 9999px;
+  font-family: var(--font-sans);
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+.severity-critical {
+  background: rgba(220, 38, 38, 0.1);
+  color: var(--color-destructive);
+  border: 1px solid rgba(220, 38, 38, 0.3);
+}
+.severity-high {
+  background: rgba(234, 88, 12, 0.1);
+  color: #ea580c;
+  border: 1px solid rgba(234, 88, 12, 0.3);
+}
+.severity-medium {
+  background: rgba(217, 119, 6, 0.1);
+  color: var(--color-warning);
+  border: 1px solid rgba(217, 119, 6, 0.3);
+}
+.severity-low {
+  background: rgba(22, 163, 74, 0.1);
+  color: var(--color-success);
+  border: 1px solid rgba(22, 163, 74, 0.3);
+}
+
+/* Finding card */
+.finding-card {
+  background: var(--color-background-secondary);
+  border: 1px solid var(--color-border);
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  margin-bottom: 1rem;
+}
+.finding-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  margin-bottom: 0.75rem;
+}
+.finding-title {
+  font-family: var(--font-heading);
+  font-weight: 600;
+  color: var(--color-foreground);
+  font-size: 1.0625rem;
+}
+.finding-evidence {
+  font-size: 0.9375rem;
+  color: var(--color-muted);
+  margin-top: 0.5rem;
+}
+
+/* Timeline */
+.timeline {
+  position: relative;
+  padding-left: 2rem;
+}
+.timeline::before {
+  content: "";
+  position: absolute;
+  left: 0.5rem;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: linear-gradient(180deg, var(--color-primary) 0%, var(--color-accent) 100%);
+}
+.timeline-item {
+  position: relative;
+  padding-bottom: 1.5rem;
+}
+.timeline-item::before {
+  content: "";
+  position: absolute;
+  /* Center dot on the vertical line: line is at left:0.5rem (8px) +1px,
+     timeline-item starts at padding 2rem (32px). Dot half-width 6px → place
+     left at -1.8125rem so dot center lands at 9px from .timeline left. */
+  left: -1.8125rem;
+  top: 0.4rem;
+  width: 0.75rem;
+  height: 0.75rem;
+  border-radius: 50%;
+  background: var(--color-primary);
+}
+.timeline-phase {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  color: var(--color-primary);
+  font-size: 0.875rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+}
+.timeline-title {
+  font-family: var(--font-heading);
+  font-weight: 600;
+  color: var(--color-foreground);
+  margin-top: 0.25rem;
+}
+.timeline-description {
+  color: var(--color-muted);
+  font-size: 0.9375rem;
+  margin-top: 0.25rem;
+}
+
+/* Table of Contents */
+.toc {
+  page-break-after: always;
+  margin-bottom: 3rem;
+}
+.toc h2 {
+  font-family: var(--font-heading);
+  font-size: 1.75rem;
+  font-weight: 600;
+  color: var(--color-foreground);
+  margin-bottom: 1.5rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 2px solid var(--color-primary);
+}
+.toc ol {
+  list-style: none;
+  padding-left: 0;
+  margin: 0;
+}
+.toc li {
+  margin: 0.75rem 0;
+  border-bottom: 1px dotted var(--color-border-emphasis);
+  padding-bottom: 0.5rem;
+}
+.toc a {
+  display: flex;
+  gap: 1rem;
+  align-items: baseline;
+  color: var(--color-foreground);
+  text-decoration: none;
+}
+.toc-number {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  font-size: 0.875rem;
+  color: var(--color-primary);
+  width: 2rem;
+  flex-shrink: 0;
+}
+.toc-title {
+  font-family: var(--font-heading);
+  font-weight: 500;
+  font-size: 1rem;
+}
+
+/* Stat grid */
+.stat-grid {
+  display: grid;
+  gap: 1.5rem;
+  margin: 1.5rem 0;
+  padding: 1.5rem;
+  background: var(--color-background-secondary);
+  border-radius: 0.5rem;
+  border: 1px solid var(--color-border);
+  page-break-inside: avoid;
+}
+.stat {
+  text-align: left;
+}
+.stat-value {
+  font-family: var(--font-sans);
+  font-size: 2.5rem;
+  font-weight: 700;
+  color: var(--color-primary);
+  letter-spacing: -0.02em;
+  line-height: 1;
+}
+.stat-label {
+  margin-top: 0.5rem;
+  font-family: var(--font-sans);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--color-foreground);
+}
+.stat-caption {
+  margin-top: 0.25rem;
+  font-family: var(--font-body);
+  font-size: 0.8125rem;
+  color: var(--color-muted);
+}
+
+/* Comparison table */
+.comparison-table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 1.5rem 0;
+  font-family: var(--font-body);
+  font-size: 0.9375rem;
+  page-break-inside: avoid;
+}
+.comparison-table th {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--color-primary);
+  padding: 0.75rem 1rem;
+  border-bottom: 2px solid var(--color-primary);
+  text-align: left;
+}
+.comparison-table td {
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--color-border-subtle);
+  vertical-align: top;
+}
+.comparison-table .metric {
+  font-family: var(--font-sans);
+  font-weight: 600;
+  color: var(--color-foreground);
+}
+.comparison-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+/* Cover page */
+.cover-page {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  padding: 4rem;
+  page-break-after: always;
+  background: linear-gradient(180deg, var(--color-background) 0%, var(--color-background-secondary) 100%);
+}
+.cover-classification {
+  font-family: var(--font-sans);
+  font-size: 0.875rem;
+  font-weight: 600;
+  color: var(--color-destructive);
+  text-transform: uppercase;
+  letter-spacing: 0.15em;
+  margin-bottom: 4rem;
+}
+.cover-title {
+  font-family: var(--font-heading);
+  font-size: 3rem;
+  font-weight: 600;
+  color: var(--color-foreground);
+  line-height: 1.2;
+  margin-bottom: 1rem;
+  letter-spacing: -0.02em;
+}
+.cover-subtitle {
+  font-family: var(--font-heading);
+  font-size: 1.5rem;
+  color: var(--color-muted);
+  margin-bottom: 4rem;
+  font-weight: 400;
+}
+.cover-meta {
+  margin-top: auto;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--color-border);
+}
+.cover-date {
+  font-family: var(--font-sans);
+  font-size: 1rem;
+  color: var(--color-muted);
+}
+
+/* Print styles — what Playwright sees */
+@media print {
+  body {
+    font-size: 11pt;
+  }
+  .report-container {
+    max-width: none;
+    padding: 0;
+  }
+  .report-section,
+  .callout,
+  .exhibit,
+  .finding-card,
+  .quote-block {
+    break-inside: avoid;
+  }
+  .cover-page {
+    page-break-after: always;
+  }
+  a {
+    text-decoration: none;
+    color: var(--color-foreground);
+  }
+}
+
+/* Page setup for PDF */
+@page {
+  size: A4;
+  margin: 18mm 16mm;
+}

package/assets/skills/consulting-report/demo/app/layout.tsx

@@ -0,0 +1,32 @@
+import type { Metadata } from "next";
+import { Inter, Source_Serif_4 } from "next/font/google";
+import "./globals.css";
+
+const inter = Inter({
+  subsets: ["latin"],
+  variable: "--font-inter",
+  display: "swap",
+});
+
+const sourceSerif = Source_Serif_4({
+  subsets: ["latin"],
+  variable: "--font-source-serif",
+  display: "swap",
+});
+
+export const metadata: Metadata = {
+  title: "Consulting Report",
+  description: "Strategic assessment and recommendations.",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="en" className={`${inter.variable} ${sourceSerif.variable}`}>
+      <body className="bg-background font-body text-foreground antialiased">
+        {children}
+      </body>
+    </html>
+  );
+}