portable-agent-layer 0.42.0 → 0.43.1

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();
 }

package/assets/skills/telos/SKILL.md

@@ -4,7 +4,7 @@ description: Personal context management. Use when discussing goals, beliefs, ch
 argument-hint: [area to view or update]
 ---
 
-Manage the user's TELOS files — the persistent personal context that drives PAL.
+Manage the user's TELOS files — from Greek τέλος (télos), meaning end/purpose/goal. The persistent personal context that orients PAL around who the user is and what they're working toward.
 
 ## TELOS Files
 

package/assets/templates/PAL/ALGORITHM.md

@@ -38,7 +38,7 @@ Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 **0.5. ISA context** — before reverse engineering, orient against the ISA:
 
 ```bash
-# If cwd matches a registered project — read its open ISCs:
+# If cwd matches a registered project — read its open ISCs (Ideal State Criteria):
 bun ~/.pal/tools/project.ts list-isc <project-name>
 
 # If this is ad-hoc work with no registered project — scaffold a task ISA:

package/assets/templates/PAL/README.md

@@ -85,7 +85,7 @@ Persistent storage across sessions:
 CLI utilities: `tool:opinion` (manage opinions), `tool:reflect` (relationship reflection), `tool:analyze` (learning analysis), `pal cli usage` (token usage tracking), `pal cli export` / `pal cli import` (state portability).
 
 ### TELOS (`telos/`)
-Personal context system — mission, goals, projects, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.
+From Greek τέλος (télos) — end, purpose, goal. The persistent personal context that orients PAL around who the user is and what they're working toward: mission, goals, beliefs, challenges, strategies, ideas, learnings, mental models, narratives. Managed via the telos skill.
 
 ### Security (`SecurityValidator.ts`)
 Hook-based security: validates Bash commands and file operations against dangerous patterns. Fail-open design — blocks known-dangerous operations without breaking legitimate work.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -41,7 +41,7 @@ AI agents come and go. Your accumulated knowledge, preferences, and workflows sh
 **What portability means in practice:**
 - No agent-specific assumptions in core logic
 - Agent-specific code isolated in `src/targets/`
-- Skills, memory, and TELOS are agent-agnostic
+- Skills, memory, and TELOS (Greek: τέλος — end/purpose/goal; the user's persistent life context) are agent-agnostic
 - A single `pal cli install --<agent>` registers everything
 
 ### 2. Cross-Platform by Default

package/assets/templates/rules.codex.rules

@@ -0,0 +1,64 @@
+# BEGIN PAL MANAGED CODEX RULES
+# Managed by PAL. Install replaces this block; uninstall removes only this block.
+prefix_rule(
+    pattern = ["bun", "~/.pal/tools/project.ts"],
+    decision = "allow",
+    justification = "PAL project state commands are part of the installed PAL workflow",
+    match = [
+        "bun ~/.pal/tools/project.ts resume portable-agent-layer",
+        "bun ~/.pal/tools/project.ts list-isc portable-agent-layer",
+        "bun ~/.pal/tools/project.ts add-next portable-agent-layer note",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/other.ts",
+    ],
+)
+
+prefix_rule(
+    pattern = ["bun", "~/.pal/tools/algorithm-reflect.ts"],
+    decision = "allow",
+    justification = "PAL Algorithm reflection logging is part of the installed PAL workflow",
+    match = [
+        "bun ~/.pal/tools/algorithm-reflect.ts --task work --criteria 1 --passed 1 --failed 0 --sentiment 8",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/project.ts list",
+    ],
+)
+
+prefix_rule(
+    pattern = [
+        "bun",
+        [
+            "~/.pal/tools/analyze.ts",
+            "~/.pal/tools/handoff-note.ts",
+            "~/.pal/tools/relationship-note.ts",
+            "~/.pal/tools/synthesize.ts",
+            "~/.pal/tools/thread.ts",
+            "~/.pal/tools/wisdom-frame.ts",
+        ],
+    ],
+    decision = "allow",
+    justification = "PAL installed agent tools are safe to run without repeated approval",
+    match = [
+        "bun ~/.pal/tools/thread.ts --list",
+        "bun ~/.pal/tools/wisdom-frame.ts --help",
+    ],
+    not_match = [
+        "bun ~/.pal/tools/project.ts list",
+        "bun ./local-script.ts",
+    ],
+)
+
+prefix_rule(
+    pattern = ["node", "--experimental-strip-types", "~/.pal/skills/consulting-report/tools/generate-pdf.ts"],
+    decision = "allow",
+    justification = "PAL consulting-report PDF generation requires Node for Playwright compatibility",
+    match = [
+        "node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
+    ],
+    not_match = [
+        "node ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
+    ],
+)
+# END PAL MANAGED CODEX RULES

package/assets/templates/settings.claude.json

@@ -20,7 +20,8 @@
       "Bash(stat //*)",
       "Bash(readlink //*)",
       "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
-      "Bash(bun ~/.pal/tools/*.ts *)"
+      "Bash(bun ~/.pal/tools/*.ts *)",
+      "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.42.0",
+  "version": "0.43.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -82,6 +82,7 @@
     "@konvert7/klint": "0.4.0",
     "adm-zip": "^0.5.17",
     "marked": "18.0.4",
+    "pdf-lib": "1.17.1",
     "playwright": "^1.60.0"
   }
 }

package/src/hooks/lib/agent.ts

@@ -42,7 +42,7 @@ export const isOpencode = () => getActiveAgent() === "opencode";
  * Format a "block this action" response for the current agent.
  * Claude Code:       { decision: "block", reason }
  * Cursor preToolUse: { permission: "deny", user_message }
- * Codex PreToolUse:  { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" } }
+ * Codex PreToolUse:  { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }
  */
 export function blockResponse(reason: string, hookEventName?: string): string {
   if (isCursor()) {
@@ -50,7 +50,11 @@ export function blockResponse(reason: string, hookEventName?: string): string {
   }
   if (isCodex() && hookEventName === "PreToolUse") {
     return JSON.stringify({
-      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny" },
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: reason,
+      },
     });
   }
   return JSON.stringify({ decision: "block", reason });

package/src/hooks/lib/claude-md.ts

@@ -13,6 +13,7 @@ import {
   lstatSync,
   readdirSync,
   readFileSync,
+  readlinkSync,
   statSync,
   symlinkSync,
   unlinkSync,
@@ -54,8 +55,11 @@ function latestMtime(...filePaths: string[]): number {
 function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
     const stat = lstatSync(linkPath);
-    if (!stat.isSymbolicLink()) unlinkSync(linkPath);
-    else return; // already a symlink, leave it
+    if (stat.isSymbolicLink()) {
+      const currentTarget = resolve(dirname(linkPath), readlinkSync(linkPath));
+      if (currentTarget === targetPath) return;
+    }
+    unlinkSync(linkPath);
   } catch {
     // doesn't exist — create it
   }

package/src/hooks/lib/paths.ts

@@ -81,6 +81,7 @@ export const assets = {
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
+  codexRulesTemplate: () => pkg("assets", "templates", "rules.codex.rules"),
   agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/codex/install.ts

@@ -19,8 +19,10 @@ import {
   countSkills,
   generateSkillIndex,
   loadCodexHooksTemplate,
+  loadCodexRulesTemplate,
   log,
   mergeCodexHooks,
+  mergeCodexRules,
   readJson,
   scaffoldPalSettings,
   writeJson,
@@ -56,6 +58,7 @@ function enableCodexHooks(configPath: string): void {
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CODEX_DIR = platform.codexDir();
 const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 
 // --- Ensure ~/.codex/ exists ---
 mkdirSync(CODEX_DIR, { recursive: true });
@@ -73,6 +76,17 @@ const merged = mergeCodexHooks(existing, template);
 writeJson(HOOKS_FILE, merged);
 log.success("Merged PAL hooks into ~/.codex/hooks.json");
 
+// --- Merge allowlist rules ---
+mkdirSync(resolve(CODEX_DIR, "rules"), { recursive: true });
+if (existsSync(RULES_FILE)) {
+  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
+  log.info("Backed up rules/default.rules");
+}
+const rulesTemplate = loadCodexRulesTemplate(assets.codexRulesTemplate());
+const existingRules = existsSync(RULES_FILE) ? readFileSync(RULES_FILE, "utf-8") : "";
+writeFileSync(RULES_FILE, mergeCodexRules(existingRules, rulesTemplate), "utf-8");
+log.success("Merged PAL allowlist rules into ~/.codex/rules/default.rules");
+
 // --- Symlink skills to ~/.codex/skills/ ---
 const codexSkillsDir = resolve(CODEX_DIR, "skills");
 copySkills(codexSkillsDir);

package/src/targets/codex/uninstall.ts

@@ -13,6 +13,7 @@ import {
   readJson,
   removeSkills,
   unmergeCodexHooks,
+  unmergeCodexRules,
   writeJson,
 } from "../lib";
 
@@ -38,6 +39,7 @@ function disableCodexHooks(configPath: string): void {
 const PKG_ROOT = palPkg().replaceAll("\\", "/");
 const CODEX_DIR = platform.codexDir();
 const HOOKS_FILE = resolve(CODEX_DIR, "hooks.json");
+const RULES_FILE = resolve(CODEX_DIR, "rules", "default.rules");
 
 // --- Remove PAL hooks from hooks.json ---
 if (existsSync(HOOKS_FILE)) {
@@ -54,6 +56,18 @@ if (existsSync(HOOKS_FILE)) {
   log.info("No hooks.json found, nothing to do");
 }
 
+// --- Remove PAL allowlist rules from default.rules ---
+if (existsSync(RULES_FILE)) {
+  copyFileSync(RULES_FILE, `${RULES_FILE}.bak.${Date.now()}`);
+  log.info("Backed up rules/default.rules");
+
+  const cleanedRules = unmergeCodexRules(readFileSync(RULES_FILE, "utf-8"));
+  writeFileSync(RULES_FILE, cleanedRules, "utf-8");
+  log.success("Removed PAL allowlist rules from ~/.codex/rules/default.rules");
+} else {
+  log.info("No default.rules found, nothing to do");
+}
+
 // --- Remove PAL skill symlinks ---
 const codexSkillsDir = resolve(CODEX_DIR, "skills");
 const removed = removeSkills(codexSkillsDir);

package/src/targets/lib.ts

@@ -333,6 +333,36 @@ export function unmergeCodexHooks(
   return result;
 }
 
+// --- Codex rules (Starlark .rules file) ---
+
+const CODEX_RULES_BEGIN = "# BEGIN PAL MANAGED CODEX RULES";
+const CODEX_RULES_END = "# END PAL MANAGED CODEX RULES";
+
+export function loadCodexRulesTemplate(templatePath: string): string {
+  return readFileSync(templatePath, "utf-8").trim();
+}
+
+function stripPalCodexRules(content: string): string {
+  const escapedBegin = CODEX_RULES_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const escapedEnd = CODEX_RULES_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const block = new RegExp(String.raw`\n?${escapedBegin}[\s\S]*?${escapedEnd}\n?`, "g");
+  return content
+    .replace(block, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function mergeCodexRules(existing: string, template: string): string {
+  const preserved = stripPalCodexRules(existing);
+  const prefix = preserved ? `${preserved}\n\n` : "";
+  return `${prefix}${template.trim()}\n`;
+}
+
+export function unmergeCodexRules(existing: string): string {
+  const cleaned = stripPalCodexRules(existing);
+  return cleaned ? `${cleaned}\n` : "";
+}
+
 // --- TELOS scaffolding ---
 
 /** Copy template files into telos/ without overwriting existing ones */