portable-agent-layer 0.38.0 → 0.39.0

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

@@ -6,7 +6,46 @@ argument-hint: scaffold <target-dir> | dev <report-dir> | <report-dir> (render P
 
 ## Overview
 
-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.
+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`, font via `next/font/google` (Inter), Tailwind v4 for styling. `bun run dev` gives a live preview while authoring; the PDF is rendered by Playwright against a static export.
+
+## Authoring contract — what belongs where
+
+The split is deliberate. Don't edit the template for one report; don't put report data in the template.
+
+| File | Lives in | Edited by |
+|------|----------|-----------|
+| `lib/types.ts` | Template | Skill maintainer only (when adding new section types) |
+| `lib/report-data.ts` | Project | **You.** Replace the scaffolded placeholder with your data. |
+| `app/page.tsx` | Project | **You.** Compose your layout from the components in `@/components`. |
+| `components/*.tsx` | Template | Skill maintainer only (when adding new primitives) |
+| `app/globals.css` | Project (copied from template) | Brand colors and project-specific overrides only. |
+
+**Tunable parameters** (e.g., the "TUNABLE" marker on configuration rows) take their label from the data:
+
+```ts
+// In your project's report-data.ts:
+{ name: "Decision band thresholds", currentValue: "16–20 strong …",
+  tunable: true, tunableLabel: "Owner edit" }
+```
+
+The component renders whatever `tunableLabel` you provide; the template never hardcodes a person's name.
+
+**Custom band labels** (Scorecard / BandBadge): the `band` field is a free-form string. Pass `bandStyles` to `<Scorecard>` to map your band labels to colors:
+
+```tsx
+<Scorecard
+  scorecard={...}
+  bandStyles={{
+    Greenlit: { color: "...", background: "...", borderColor: "..." },
+    Investigate: { ... },
+    Hold: { ... },
+  }}
+/>
+```
+
+**Configurable columns** (ConfigurationTable, TuningLog): pass a `columns` prop to override the default schema. See each component's source for the column type.
+
+**Rubric levels** (RubricTable): supports any number of levels — the colors sample the default palette evenly. Pass `palette` to override.
 
 ## Workflow
 

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

@@ -24,9 +24,8 @@
   --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;
+  --font-body: var(--font-inter), system-ui, sans-serif;
 }
 
 @source "./**/*.{ts,tsx}";
@@ -41,320 +40,42 @@ body {
   -moz-osx-font-smoothing: grayscale;
 }
 
-/* McKinsey-style report layout */
+/* Restore default list markers (Tailwind's preflight strips them).
+   Scoped to @layer base so Tailwind utilities (e.g., `list-none`, `m-0`)
+   on individual components still win. */
+@layer base {
+  ol, ul {
+    padding-left: 1.6rem;
+    margin: 0.75rem 0;
+  }
+  ol { list-style: decimal outside; }
+  ul { list-style: disc outside; }
+  li { margin: 0.25rem 0; }
+  li::marker {
+    color: var(--color-muted);
+    font-weight: 600;
+  }
+}
+
+/* Page-level wrapper used by every report's app/page.tsx. */
 .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 */
+/* Compatibility hooks for raw <table className="comparison-table"> markup
+   used directly in pages (not via the <ComparisonTable> component). Projects
+   that author tables inline use these. */
 .comparison-table {
   width: 100%;
   border-collapse: collapse;
   margin: 1.5rem 0;
   font-family: var(--font-body);
   font-size: 0.9375rem;
-  page-break-inside: avoid;
+  /* No page-break-inside:avoid here — long tables must be allowed to break.
+     Short tables stay together naturally (browsers prefer not to break short
+     content). */
 }
 .comparison-table th {
   font-family: var(--font-sans);
@@ -381,53 +102,9 @@ body {
   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 */
+/* Print rules — Playwright honors these when generating PDF. Atomic blocks
+   carry their own break-inside-avoid via Tailwind utilities on the component;
+   only page-level rules and cover-after live here. */
 @media print {
   body {
     font-size: 11pt;
@@ -436,23 +113,35 @@ body {
     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);
   }
+  /* No orphaned headings — if there isn't room for at least one line of
+     content after a heading, push the heading to the next page. */
+  h1, h2, h3, h4, h5, h6 {
+    break-after: avoid;
+    page-break-after: avoid;
+  }
+  /* Label-as-heading: a paragraph that contains only a <strong> child is
+     semantically a sub-heading (e.g., "Scoring guidance:"). Same orphan
+     treatment as real headings. */
+  p:has(> strong:only-child) {
+    break-after: avoid;
+    page-break-after: avoid;
+  }
+  /* Don't break paragraphs across pages.
+     Chromium's PDF engine doesn't reliably honor `orphans`/`widows`, so we
+     use the stronger `break-inside: avoid`. Most paragraphs are short
+     enough to stay whole; very long ones (>1 page) will break anyway
+     because the browser has no choice. */
+  p {
+    break-inside: avoid;
+    page-break-inside: avoid;
+  }
 }
 
-/* Page setup for PDF */
+/* Page setup for PDF (A4, narrow margins). */
 @page {
   size: A4;
   margin: 18mm 16mm;

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

@@ -1,5 +1,5 @@
 import type { Metadata } from "next";
-import { Inter, Source_Serif_4 } from "next/font/google";
+import { Inter } from "next/font/google";
 import "./globals.css";
 
 const inter = Inter({
@@ -8,12 +8,6 @@ const inter = 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.",
@@ -23,7 +17,7 @@ export default function RootLayout({
   children,
 }: Readonly<{ children: React.ReactNode }>) {
   return (
-    <html lang="en" className={`${inter.variable} ${sourceSerif.variable}`}>
+    <html lang="en" className={inter.variable}>
       <body className="bg-background font-body text-foreground antialiased">
         {children}
       </body>

package/assets/skills/consulting-report/template/components/band-badge.tsx

@@ -0,0 +1,72 @@
+// Generic band badge. The set of band labels is not pinned by the template —
+// projects pass any string. A default style map covers the strategic-bet
+// "Strong/Promising/Park/Decline" vocabulary out of the box; projects can
+// supply their own via `bandStyles`.
+
+import type { CSSProperties } from "react";
+
+export type BandStyle = {
+  color: string;
+  background: string;
+  borderColor: string;
+};
+
+const defaultBandStyles: Record<string, BandStyle> = {
+  Strong: {
+    color: "var(--color-success)",
+    background: "rgba(22,163,74,0.12)",
+    borderColor: "rgba(22,163,74,0.4)",
+  },
+  Promising: {
+    color: "var(--color-primary)",
+    background: "rgba(29,78,216,0.10)",
+    borderColor: "rgba(29,78,216,0.35)",
+  },
+  Park: {
+    color: "var(--color-muted)",
+    background: "rgba(100,116,139,0.12)",
+    borderColor: "rgba(100,116,139,0.35)",
+  },
+  Decline: {
+    color: "var(--color-destructive)",
+    background: "rgba(220,38,38,0.10)",
+    borderColor: "rgba(220,38,38,0.35)",
+  },
+};
+
+interface BandBadgeProps {
+  band: string;
+  /**
+   * Override or extend the default band styles. Keys are band labels; values
+   * are the visual treatment. Falls back to a neutral style when a band
+   * label is not found in either the override map or the defaults.
+   */
+  bandStyles?: Record<string, BandStyle>;
+}
+
+const fallbackStyle: BandStyle = {
+  color: "var(--color-muted)",
+  background: "rgba(100,116,139,0.10)",
+  borderColor: "rgba(100,116,139,0.30)",
+};
+
+function resolveStyle(band: string, override?: Record<string, BandStyle>): BandStyle {
+  return override?.[band] ?? defaultBandStyles[band] ?? fallbackStyle;
+}
+
+export function BandBadge({ band, bandStyles }: BandBadgeProps) {
+  const s = resolveStyle(band, bandStyles);
+  const style: CSSProperties = {
+    color: s.color,
+    background: s.background,
+    borderColor: s.borderColor,
+  };
+  return (
+    <span
+      className="inline-flex items-center px-2.5 py-0.5 rounded-full font-sans text-[0.7rem] font-bold uppercase tracking-widest border whitespace-nowrap"
+      style={style}
+    >
+      {band}
+    </span>
+  );
+}

package/assets/skills/consulting-report/template/components/callout.tsx

@@ -5,9 +5,11 @@ interface CalloutProps {
 
 export function Callout({ label = "Key Takeaway", children }: CalloutProps) {
   return (
-    <div className="callout">
-      <div className="callout-label">{label}</div>
-      <div className="callout-content">{children}</div>
+    <div className="bg-callout border-l-4 border-primary px-6 py-5 my-6 rounded-r-lg break-inside-avoid">
+      <div className="font-sans font-semibold text-primary text-xs uppercase tracking-widest mb-2">
+        {label}
+      </div>
+      <div className="text-foreground">{children}</div>
     </div>
   );
 }

package/assets/skills/consulting-report/template/components/comparison-table.tsx

@@ -17,21 +17,27 @@ export function ComparisonTable({
   rows,
   metricLabel = "Metric",
 }: ComparisonTableProps) {
+  const thClass =
+    "font-sans text-[0.7rem] font-semibold uppercase tracking-widest text-primary px-4 py-3 border-b-2 border-primary text-left";
+  const tdClass =
+    "px-4 py-3 border-b border-border-subtle align-top last:[&:last-child]:border-b-0";
   return (
-    <table className="comparison-table">
+    <table className="w-full border-collapse my-6 font-body text-[0.9375rem]">
       <thead>
         <tr>
-          <th>{metricLabel}</th>
-          <th>{leftLabel}</th>
-          <th>{rightLabel}</th>
+          <th className={thClass}>{metricLabel}</th>
+          <th className={thClass}>{leftLabel}</th>
+          <th className={thClass}>{rightLabel}</th>
         </tr>
       </thead>
       <tbody>
         {rows.map((row) => (
           <tr key={row.metric}>
-            <td className="metric">{row.metric}</td>
-            <td>{row.left}</td>
-            <td>{row.right}</td>
+            <td className={`${tdClass} font-sans font-semibold text-foreground`}>
+              {row.metric}
+            </td>
+            <td className={tdClass}>{row.left}</td>
+            <td className={tdClass}>{row.right}</td>
           </tr>
         ))}
       </tbody>