portable-agent-layer 0.41.1 → 0.43.0

package/.husky/install.mjs

@@ -0,0 +1,8 @@
+import { existsSync } from 'node:fs'
+
+if (process.env.CI === 'true' || process.env.NODE_ENV === 'production' || !existsSync('.git')) {
+  process.exit(0)
+}
+
+const husky = (await import('husky')).default
+console.log(husky())

package/README.md

@@ -84,6 +84,7 @@ pal cli status        # check your setup
 | `pal cli doctor` | Check prerequisites and system health |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli usage` | Summarize token usage and estimated cost |
+| `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 
 ### Target flags
 
@@ -159,7 +160,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `council` | Multi-perspective parallel debate on decisions |
 | `create-pdf` | Render structured content into a PDF |
 | `create-skill` | Scaffold a new skill from a description |
-| `extract-entities` | Extract people and companies from content |
+| `entities` | Detect, save, and query people & companies in the personal knowledge graph |
 | `extract-wisdom` | Extract structured insights from content |
 | `first-principles` | Break down problems to fundamentals |
 | `fyzz-chat-api` | Query Fyzz Chat conversations via API |

package/assets/skills/analyze-youtube/SKILL.md

@@ -23,7 +23,7 @@ Follow the user's request. Common tasks:
 
 - **Summarize** the video content
 - **Answer a specific question** about what's shown or discussed
-- **Extract entities** (defer to /extract-entities if installed)
+- **Extract entities** (defer to /entities if installed)
 - **Extract wisdom** (defer to /extract-wisdom if installed)
 - **Compare** with other content
 

package/assets/skills/consulting-report/template/components/code-block.tsx

@@ -0,0 +1,21 @@
+import type { CodeSample } from "@/lib/types";
+
+interface CodeBlockProps {
+  sample: CodeSample;
+}
+
+export async function CodeBlock({ sample }: CodeBlockProps) {
+  return (
+    <div className="my-4 break-inside-avoid">
+      <div className="font-sans text-[0.65rem] font-bold uppercase tracking-widest text-primary mb-1">
+        {sample.language}
+      </div>
+      <pre className="rounded-lg overflow-x-auto text-[0.8rem] leading-relaxed px-5 py-4 bg-[#f6f8fa]">
+        <code>{sample.code}</code>
+      </pre>
+      {sample.caption && (
+        <p className="text-[0.78rem] text-muted italic mt-1">{sample.caption}</p>
+      )}
+    </div>
+  );
+}

package/assets/skills/consulting-report/template/components/cover-page.tsx

@@ -1,46 +1,107 @@
+interface MetadataItem {
+  label: string;
+  value: string;
+}
+
 interface CoverPageProps {
-  clientName: string;
   reportTitle: string;
   reportDate: string;
-  classification: string;
+  clientName: string;
   consultancyName: string;
   preTitle?: string;
+  /** Path to consultancy logo image. Falls back to consultancyName text wordmark. */
+  consultancyLogoSrc?: string;
+  /** Path to client logo image. Falls back to clientName text wordmark. */
+  clientLogoSrc?: string;
+  /** Optional metadata rows rendered in the bottom strip (e.g. classification, version). */
+  metadata?: MetadataItem[];
+}
+
+function LogoSlot({
+  src,
+  name,
+  align = "left",
+}: {
+  src?: string;
+  name: string;
+  align?: "left" | "right";
+}) {
+  if (src) {
+    return (
+      // biome-ignore lint/performance/noImgElement: Template reports are static exports; next/image is not needed for print logos.
+      <img
+        src={src}
+        alt={name}
+        className="h-10 w-auto object-contain"
+        style={{ maxWidth: 180 }}
+      />
+    );
+  }
+  return (
+    <span
+      className={`font-sans text-sm font-bold uppercase tracking-widest text-foreground ${
+        align === "right" ? "text-right" : ""
+      }`}
+    >
+      {name}
+    </span>
+  );
 }
 
 export function CoverPage({
-  clientName,
   reportTitle,
-  reportDate,
-  classification,
+  clientName,
   consultancyName,
-  preTitle = "Strategic Assessment",
+  preTitle,
+  consultancyLogoSrc,
+  clientLogoSrc,
+  metadata,
 }: CoverPageProps) {
   return (
-    <div
-      className={[
-        "min-h-screen flex flex-col justify-center p-16",
-        "break-after-page",
-        "bg-gradient-to-b from-background to-background-secondary",
-      ].join(" ")}
-    >
-      <div className="font-sans text-sm font-semibold text-destructive uppercase tracking-[0.15em] mb-16">
-        {classification}
+    <div className="min-h-screen flex flex-col break-after-page bg-background">
+      {/* Logo strip */}
+      <div className="flex items-center justify-between px-16 py-8 border-b-2 border-primary">
+        <LogoSlot src={consultancyLogoSrc} name={consultancyName} align="left" />
+        <LogoSlot src={clientLogoSrc} name={clientName} align="right" />
       </div>
 
-      <div className="text-sm tracking-[0.25em] text-primary uppercase mb-4 font-semibold font-sans">
-        {preTitle}
+      {/* Main content — vertically centered */}
+      <div className="flex-1 flex flex-col justify-center px-16 py-20">
+        {preTitle && (
+          <p className="font-sans text-xs font-bold uppercase tracking-widest text-primary mb-5">
+            {preTitle}
+          </p>
+        )}
+        <h1 className="font-heading text-5xl font-semibold text-foreground leading-tight mb-6 tracking-tight max-w-2xl">
+          {reportTitle}
+        </h1>
+        <p className="font-heading text-xl text-muted font-normal">
+          Prepared for {clientName}
+        </p>
       </div>
-      <h1 className="font-heading text-5xl font-semibold text-foreground leading-tight mb-4 tracking-tight">
-        {reportTitle}
-      </h1>
-      <p className="font-heading text-2xl text-muted mb-16 font-normal">
-        Prepared for {clientName}
-      </p>
 
-      <div className="mt-auto pt-6 border-t border-border">
-        <p className="font-sans text-base text-muted">{reportDate}</p>
-        <p className="text-muted-dark text-sm mt-2 font-sans">{consultancyName}</p>
-      </div>
+      {/* Metadata strip */}
+      {metadata && metadata.length > 0 && (
+        <div className="border-t border-border px-16 py-8">
+          <dl
+            className="grid gap-x-12 gap-y-4"
+            style={{
+              gridTemplateColumns: `repeat(${Math.min(metadata.length, 4)}, auto) 1fr`,
+            }}
+          >
+            {metadata.map((item) => (
+              <div key={item.label}>
+                <dt className="font-sans text-[0.62rem] font-bold uppercase tracking-widest text-muted mb-1">
+                  {item.label}
+                </dt>
+                <dd className="font-sans text-sm font-medium text-foreground">
+                  {item.value}
+                </dd>
+              </div>
+            ))}
+          </dl>
+        </div>
+      )}
     </div>
   );
 }

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

@@ -0,0 +1,62 @@
+import type { Decision } from "@/lib/types";
+
+interface DecisionTableProps {
+  decisions: Decision[];
+  intro?: string;
+}
+
+function StatusBadge({ status }: { status: Decision["status"] }) {
+  if (status === "adopt-default") {
+    return (
+      <span className="inline-block px-2 py-0.5 rounded font-sans text-[0.65rem] font-bold uppercase tracking-widest bg-success/10 text-success border border-success/30">
+        Adopt default
+      </span>
+    );
+  }
+  return (
+    <span className="inline-block px-2 py-0.5 rounded font-sans text-[0.65rem] font-bold uppercase tracking-widest bg-warning/10 text-warning border border-warning/30">
+      Confirm at sync
+    </span>
+  );
+}
+
+export function DecisionTable({ decisions, intro }: DecisionTableProps) {
+  const thClass =
+    "font-sans text-[0.68rem] font-bold uppercase tracking-widest text-primary px-3 py-2 border-b-2 border-primary text-left";
+  const tdClass = "px-3 py-2.5 border-b border-border-subtle align-top";
+
+  return (
+    <div className="my-4">
+      {intro && <p className="text-[0.9375rem] mb-4">{intro}</p>}
+      <table className="w-full border-collapse font-body text-[0.85rem]">
+        <thead>
+          <tr>
+            <th className={`${thClass} w-[4%]`}>#</th>
+            <th className={`${thClass} w-[28%]`}>Decision</th>
+            <th className={`${thClass} w-[44%]`}>Recommended default</th>
+            <th className={`${thClass} w-[24%]`}>Status</th>
+          </tr>
+        </thead>
+        <tbody>
+          {decisions.map((d, i) => (
+            <tr key={d.id} className="break-inside-avoid">
+              <td className={`${tdClass} text-muted font-sans text-[0.78rem]`}>
+                {i + 1}
+              </td>
+              <td className={tdClass}>
+                <div className="font-sans font-semibold text-foreground">{d.title}</div>
+                {d.description && (
+                  <div className="text-muted text-[0.82rem] mt-0.5">{d.description}</div>
+                )}
+              </td>
+              <td className={`${tdClass} text-muted`}>{d.recommendedDefault}</td>
+              <td className={tdClass}>
+                <StatusBadge status={d.status} />
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/assets/skills/consulting-report/template/components/process-stage.tsx

@@ -0,0 +1,28 @@
+import type { ProcessStage } from "@/lib/types";
+
+interface ProcessStageProps {
+  stage: ProcessStage;
+}
+
+export function ProcessStageBlock({ stage }: ProcessStageProps) {
+  return (
+    <div className="mb-6 break-inside-avoid">
+      <div className="font-sans font-semibold text-primary text-xs uppercase tracking-widest mb-3">
+        {stage.name}
+      </div>
+      <ol className="list-decimal list-outside ml-5 space-y-2">
+        {stage.items.map((item) => (
+          <li
+            key={`${item.text}:${item.note ?? ""}`}
+            className="text-[0.9375rem] text-foreground pl-1"
+          >
+            {item.text}
+            {item.note && (
+              <span className="ml-1 text-muted text-[0.82rem] italic">({item.note})</span>
+            )}
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}

package/assets/skills/consulting-report/template/components/tier-matrix.tsx

@@ -0,0 +1,102 @@
+import type { CSSProperties } from "react";
+import type { TierMatrixCellValue, TierMatrixRow } from "@/lib/types";
+
+interface TierMatrixProps {
+  columns: string[];
+  rows: TierMatrixRow[];
+  caption?: string;
+  /** Alignment for data cells. Defaults to "center" for symbol matrices; use "left" for text-heavy tables. */
+  alignCells?: "left" | "center";
+  /**
+   * Column sizing mode:
+   * - "auto" (default): browser distributes space by content — no explicit widths applied.
+   * - "capped": columnWidths[i] applied as max-width — content drives size up to the cap.
+   * - "manual": columnWidths[i] applied as explicit width.
+   * columnWidths is parallel to ALL columns: [0] = layer column, [1..n] = data columns.
+   */
+  sizing?: "auto" | "capped" | "manual";
+  columnWidths?: string[];
+}
+
+function CellContent({ value }: { value: TierMatrixCellValue }) {
+  if (value === "required") {
+    return <span className="text-success font-bold text-base">✓</span>;
+  }
+  if (value === "recommended") {
+    return (
+      <span className="font-sans text-[0.7rem] font-semibold uppercase tracking-widest text-warning">
+        rec.
+      </span>
+    );
+  }
+  if (value === false) {
+    return <span className="text-muted">—</span>;
+  }
+  return <span>{value}</span>;
+}
+
+export function TierMatrix({
+  columns,
+  rows,
+  caption,
+  alignCells = "center",
+  sizing = "auto",
+  columnWidths,
+}: TierMatrixProps) {
+  const thClass =
+    "font-sans text-[0.68rem] font-bold uppercase tracking-widest text-primary px-3 py-2 border-b-2 border-primary";
+  const tdClass = "px-3 py-2 border-b border-border-subtle align-middle";
+  const colHeaderAlign = alignCells === "left" ? "text-left" : "text-center";
+  const cellAlign = alignCells === "left" ? "text-left" : "text-center";
+
+  function colStyle(index: number): CSSProperties | undefined {
+    const val = columnWidths?.[index];
+    if (!val) return undefined;
+    if (sizing === "manual") return { width: val };
+    if (sizing === "capped") return { maxWidth: val };
+    return undefined;
+  }
+
+  return (
+    <div className="my-4">
+      <table className="w-full border-collapse font-body text-[0.85rem] break-inside-avoid">
+        <thead>
+          <tr>
+            <th className={`${thClass} text-left`} style={colStyle(0)}>
+              Layer
+            </th>
+            {columns.map((col, i) => (
+              <th
+                key={col}
+                className={`${thClass} ${colHeaderAlign}`}
+                style={colStyle(i + 1)}
+              >
+                {col}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={`${row.layer}:${row.cells.join("|")}`}>
+              <td
+                className={`${tdClass} text-left font-sans font-medium text-foreground`}
+              >
+                {row.layer}
+              </td>
+              {row.cells.map((cell, i) => (
+                <td
+                  key={`${columns[i] ?? "cell"}:${String(cell)}`}
+                  className={`${tdClass} ${cellAlign}`}
+                >
+                  <CellContent value={cell} />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      {caption && <p className="text-[0.78rem] text-muted italic mt-1">{caption}</p>}
+    </div>
+  );
+}

package/assets/skills/consulting-report/template/lib/types.ts

@@ -4,7 +4,7 @@
 // project (the report instance that supplies the actual data). Projects import
 // the types they need; they do NOT edit this file.
 //
-// Two families of types:
+// Three families of types:
 //
 //   1. Strategic-assessment shapes — Finding, Recommendation, TimelinePhase,
 //      and the ReportData interface composed of them. These power the default
@@ -14,6 +14,10 @@
 //      power rubric-style deliverables (an opportunity scoring playbook is one
 //      example). Each is optional; projects use whichever apply.
 //
+//   3. Process-guide shapes — TierMatrixRow, ProcessStage, CodeSample, Decision.
+//      Power process documentation deliverables (tiered requirements matrices,
+//      stage-by-stage process flows, technical appendices, sign-off tables).
+//
 // Adding a new section type? Add its interface here so all reports share the
 // same vocabulary.
 
@@ -188,3 +192,47 @@ export interface TuningLogEntry {
   rationale: string;
   approver: string;
 }
+
+// --- Process-guide shapes ---
+
+/** Generic N-column checklist matrix (e.g. requirements by tier/level). */
+export type TierMatrixCellValue = "required" | "recommended" | false | string;
+export interface TierMatrixRow {
+  /** Row label (e.g. "Formatter", "Secret scan"). */
+  layer: string;
+  /** One value per column, parallel to the `columns` prop on TierMatrix. */
+  cells: TierMatrixCellValue[];
+}
+
+/** One item inside a ProcessStage. */
+export interface ProcessStageItem {
+  text: string;
+  /** Optional inline cross-reference, e.g. "see §4.6". Renders muted. */
+  note?: string;
+}
+
+/** A named process stage with ordered action items. */
+export interface ProcessStage {
+  id: string;
+  name: string;
+  items: ProcessStageItem[];
+}
+
+/** A code sample for a technical appendix. */
+export interface CodeSample {
+  id: string;
+  title: string;
+  /** Language identifier shown as a badge, e.g. "yaml", "typescript", "markdown". */
+  language: string;
+  caption?: string;
+  code: string;
+}
+
+/** A single row in a sign-off or open-decisions table. */
+export interface Decision {
+  id: string;
+  title: string;
+  description?: string;
+  recommendedDefault: string;
+  status: "adopt-default" | "confirm-at-sync";
+}

package/assets/skills/consulting-report/tools/generate-pdf.ts

@@ -12,11 +12,12 @@
 //   node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts <report-dir> [--pdf <out>] [--html <out>] [--skip-build]
 
 import { spawnSync } from "node:child_process";
-import { createReadStream, constants as fsConstants } from "node:fs";
-import { access, stat } from "node:fs/promises";
+import { createReadStream, constants as fsConstants, realpathSync } from "node:fs";
+import { access, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Server } from "node:http";
 import { extname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
+import { PDFDocument } from "pdf-lib";
 import { chromium } from "playwright";
 
 interface ReportMeta {
@@ -24,6 +25,10 @@ interface ReportMeta {
   reportTitle: string;
   classification: string;
   consultancyName: string;
+  /** Public path to consultancy logo (e.g. "/logos/konvert7.svg"). Used in the PDF footer. */
+  consultancyLogoSrc?: string;
+  /** Public path to client logo (e.g. "/logos/transcend.svg"). Used in the PDF header. */
+  clientLogoSrc?: string;
 }
 
 const COLOR = {
@@ -56,6 +61,25 @@ function slugify(s: string): string {
     .replace(/^-|-$/g, "");
 }
 
+/** Reads a logo file from the static export and returns a base64 data URI, or null if not found. */
+async function logoDataUri(
+  outDir: string,
+  publicPath: string | undefined
+): Promise<string | null> {
+  if (!publicPath) return null;
+  const filePath = join(outDir, publicPath);
+  if (!(await exists(filePath))) return null;
+  const buf = await readFile(filePath);
+  const ext = extname(filePath).toLowerCase();
+  let mime = "image/jpeg";
+  if (ext === ".svg") {
+    mime = "image/svg+xml";
+  } else if (ext === ".png") {
+    mime = "image/png";
+  }
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
 async function loadMeta(reportDir: string): Promise<ReportMeta> {
   const dataPath = join(reportDir, "lib", "report-data.ts");
   if (!(await exists(dataPath))) {
@@ -150,29 +174,79 @@ async function renderPdf(
       );
     });
 
+    // Load logos as base64 data URIs — Playwright's header/footer templates
+    // run in an isolated context and cannot load external or local-path URLs.
+    const [clientUri, consultancyUri] = await Promise.all([
+      logoDataUri(outDir, meta.clientLogoSrc),
+      logoDataUri(outDir, meta.consultancyLogoSrc),
+    ]);
+
+    const clientSlot = clientUri
+      ? `<img src="${clientUri}" style="height:18px; width:auto; object-fit:contain; display:block;">`
+      : `<span style="font-weight:600; color:${COLOR.navy}; letter-spacing:0.05em;">${escapeHtml(meta.clientName.toUpperCase())}</span>`;
+
+    const consultancySlot = consultancyUri
+      ? `<img src="${consultancyUri}" style="height:14px; width:auto; object-fit:contain; display:block;">`
+      : `<span style="color:${COLOR.navy};">${escapeHtml(meta.consultancyName)}</span>`;
+
     const header = `
 <div style="width:100%; font-family:Inter,'Helvetica Neue',Arial,sans-serif; font-size:7.5pt; padding:0 0.7in; display:flex; justify-content:space-between; align-items:center;">
-  <span style="font-weight:600; color:${COLOR.navy}; letter-spacing:0.05em;">${escapeHtml(meta.clientName.toUpperCase())}</span>
+  ${clientSlot}
   <span style="color:#94a3b8;">${escapeHtml(meta.reportTitle)}</span>
 </div>`;
 
+    // Footer: consultancy logo left, page number right — no classification (cover carries it)
     const footer = `
 <div style="width:100%; font-family:Inter,'Helvetica Neue',Arial,sans-serif; font-size:7.5pt; padding:0 0.7in; display:flex; justify-content:space-between; align-items:center;">
-  <span style="color:${COLOR.red}; font-weight:600; letter-spacing:0.05em;">${escapeHtml(meta.classification)}</span>
-  <span style="color:${COLOR.navy};">${escapeHtml(meta.consultancyName)}</span>
+  ${consultancySlot}
   <span style="color:${COLOR.navy};"><span class="pageNumber"></span></span>
 </div>`;
 
-    await page.pdf({
-      path: pdfPath,
-      format: "A4",
-      printBackground: true,
-      displayHeaderFooter: true,
-      headerTemplate: header,
-      footerTemplate: footer,
-      margin: { top: "0.7in", right: "0.7in", bottom: "0.7in", left: "0.7in" },
-      preferCSSPageSize: false,
-    });
+    const margin = { top: "0.7in", right: "0.7in", bottom: "0.7in", left: "0.7in" };
+
+    // Render cover (page 1) and body (pages 2+) separately so the cover has
+    // no header/footer and full-bleed margins, then merge with pdf-lib.
+    const tmpCover = `${pdfPath}.cover.tmp.pdf`;
+    const tmpBody = `${pdfPath}.body.tmp.pdf`;
+
+    await Promise.all([
+      page.pdf({
+        path: tmpCover,
+        format: "A4",
+        pageRanges: "1",
+        printBackground: true,
+        displayHeaderFooter: false,
+        margin: { top: "0", right: "0", bottom: "0", left: "0" },
+        preferCSSPageSize: false,
+      }),
+      page.pdf({
+        path: tmpBody,
+        format: "A4",
+        pageRanges: "2-",
+        printBackground: true,
+        displayHeaderFooter: true,
+        headerTemplate: header,
+        footerTemplate: footer,
+        margin,
+        preferCSSPageSize: false,
+      }),
+    ]);
+
+    // Merge: use body PDF as the base so its named destinations and link
+    // annotations stay intact. Insert the cover page at position 0.
+    const [coverBytes, bodyBytes] = await Promise.all([
+      readFile(tmpCover),
+      readFile(tmpBody),
+    ]);
+    const [coverDoc, bodyDoc] = await Promise.all([
+      PDFDocument.load(coverBytes),
+      PDFDocument.load(bodyBytes),
+    ]);
+    const [coverPage] = await bodyDoc.copyPages(coverDoc, [0]);
+    bodyDoc.insertPage(0, coverPage);
+    await writeFile(pdfPath, await bodyDoc.save());
+
+    await Promise.all([unlink(tmpCover), unlink(tmpBody)]);
   } finally {
     await browser.close();
     server.close();
@@ -236,9 +310,18 @@ async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
 }
 
 // Node ≥ 22.6 doesn't expose import.meta.main; gate on argv[1] instead.
+// Use realpathSync on both sides so symlinked skill paths (e.g. ~/.pal/skills →
+// PAL repo) match the resolved import.meta.url.
+function realResolve(p: string): string {
+  try {
+    return realpathSync(resolve(p));
+  } catch {
+    return resolve(p);
+  }
+}
 const isMain =
   process.argv[1] &&
-  resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+  realResolve(process.argv[1]) === realResolve(new URL(import.meta.url).pathname);
 if (isMain) {
   await run();
 }